HD / Section 6.4 / Theorem 2 replication package
===============================================

The supplied respondents(1).csv and categories(1).csv contain 239 respondents,
seven dimensions, 33 nonempty traits, and 202 distinct complete trait profiles.
The group size is 30, taken from the HD description in manuscript Section 6.4.
The interval quotas alone do not identify a unique group size. Raw file bytes
are preserved under the names input/respondents.csv and input/categories.csv.

CASE 1
case1_original_quotas/respondents.csv adds selection_probability to the original
columns. Quotas remain unchanged. Probabilities depend only on the complete
(a,b,c,d,e,f,g) profile and minimize the respondent-weighted squared distance
from the uniform probability 30/239, subject to all quota intervals, sum 30,
and probability bounds [0,1]. This is the same objective used for CCA.
The unique solution assigns zero probability to 51 respondents (37 profiles),
no one probability one, and positive probabilities between 0.0053948240 and
0.5357170111. This is a constructed target vector, not a recovered priority vector.

SLSQP identifies the active set; exact rational linear algebra reconstructs the
primal solution. A dual feasibility LP and rational reconstruction provide a
certificate satisfying stationarity, dual signs, and complementarity. Feasibility
and optimality are independently checked using fractions, including redundant
active trait constraints and all original interval quotas.

profile_targets.csv contains the exact numerator and denominator for each profile.
These fractions are authoritative. The selection_probability decimal column is
a 17-digit numerical representation for convenient downstream use.

CASE 2
case2_uniform/categories.csv replaces each lower/upper quota with the floor/ceiling
of 30/239 times that trait's respondent count, using exact rational arithmetic.
All 33 quota rows change. The companion respondents.csv adds the common probability
30/239. quota_audit.csv compares the original and changed quotas and expected counts.

EXPERIMENT AND OUTCOMES
10,000 fresh paths per case from Theorem 2's floating-variable sampling construction;
seeds 20261012 and 20261013. The C++ rounding source is identical to the CCA sampler;
the degree D is computed from the instance, and equals seven here.
No support compression or exhaustive support enumeration is performed.
The exact-arithmetic law preserves individual marginals and total group size;
the equally weighted collection of saved samples generally does not implement
the exact target frequencies. Floating-point residuals are reported separately.

For each trait: quota miss = max(lower-count, count-upper, 0), in seats.
For each group: average quota violation = mean miss over all 33 traits;
maximum quota miss = maximum miss over those traits. All traits are nonempty.
Means over groups are Monte Carlo estimates. Approximate 95% Monte Carlo intervals
use the sample standard deviation of the group averages divided by sqrt(draws),
not a standard error treating within-group traits as independent observations.

Archived results (10,000 groups per case):
  Case 1 mean quota violation: 0.2695393939393939; largest observed miss: 4.
  Case 2 mean quota violation: 0.2153272727272727; largest observed miss: 4.
  Theorem 2's worst-case bound for both cases: D-1 = 6.
  Four-seat misses occur in 3 and 10 groups, respectively.
  Maximum miss one or two: 96.92% and 97.57% of groups, respectively.
The full histogram, per-group metrics, and all 33 trait results are included.
The older manuscript's statement of maximum miss three is not the maximum in
these newly specified runs. Use the supplied results snippet when describing them.

FILE GUIDE
  input/                         Exact supplied input bytes
  case1_original_quotas/          Original quotas, calibrated targets, and results
  case2_uniform/                  Uniform targets, adjusted quotas, and results
  */panel_members.csv            Every draw's 30 nationbuilder_id values
  */panels.csv                   Same panels with zero-based source row indices
  */panel_metrics.csv            Each group's average and maximum miss, total
                                  shortfall/excess, all 33 counts and quota misses
  */trait_results.csv            Each trait's mean miss and largest observed miss
  */marginal_diagnostics.csv      Target probability, count, frequency, and error
  */sampler_input.txt            Exact numerical input sent to C++
  */sampler_diagnostics.json      Observed numerical residuals and elapsed time
  */summary.json                 Case-specific numerical summary
  case1_original_quotas/profile_targets.csv       Exact rational target vector
  case1_original_quotas/calibration_certificate.json  Exact dual certificate
  quota_audit.csv                Original/new quotas and exact expected counts
  results.json                   Combined results and input characteristics
  results_summary.csv            Concise machine-readable results table
  input_validation.json          Data and calibration characteristics
  run_manifest.json              Input hashes, seeds, versions, ordering, and RNG
  verification.json              Independent verification result
  HD-results-report.pdf/.tex     Full results description and all-trait appendix
  paper-results-snippet.tex       Suggested HD paragraph for Section 6.4
  run_experiment.py              Input construction, calibration, runs, summaries
  theorem2_sampler.cpp           Sampling construction, C++17 standard library
  verify_results.py              Independent Python standard-library verifier
  build_report.py                Generates report TeX and paper snippet
  requirements.txt              NumPy/SciPy versions
  SHA256SUMS                    Hashes of the archived files

REPRODUCTION
Requirements: Python 3.11+, NumPy/SciPy from requirements.txt, and a C++17 compiler
available as c++ (or set CXX). The archived environment used Python 3.12.14,
NumPy 2.3.5, SciPy 1.17.0, and GCC 13.3.0 on x86_64 Linux.

From the extracted HD-replication directory:

  python3 -m pip install -r requirements.txt
  OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 python3 run_experiment.py --draws 10000 --seed 20261012
  python3 verify_results.py
  python3 build_report.py
  pdflatex -interaction=nonstopmode -halt-on-error HD-results-report.tex
  pdflatex -interaction=nonstopmode -halt-on-error HD-results-report.tex

The experiment command loads the archived rational targets. To reconstruct them
and their optimality certificate from the raw inputs, add --recalibrate:

  OPENBLAS_NUM_THREADS=1 OMP_NUM_THREADS=1 python3 run_experiment.py --draws 10000 --seed 20261012 --recalibrate

The --draws and --seed options allow other Monte Carlo experiments. Running the
script overwrites generated results in the two case folders. Preserve a copy of
the delivered archive if you want to retain this run. Rebuild the report after
changes; the figures in this README describe the delivered 10,000-draw run.
The independent verifier alone requires only Python's standard library. LaTeX
is needed only for rebuilding the PDF; no external plotting libraries are used.

NUMERICAL RULES AND SCOPE
Columns use original respondent order; active trait rows use original category
order. The first linear dependency is selected by incremental column elimination,
with largest-magnitude residual pivot and first-row tie breaking. Normalize the
null direction to maximum absolute entry one. Endpoint choice uses mt19937_64
and its top 53 bits. Directions use double precision; states, endpoint distances,
and sums use long double. Snap tolerance is 1e-15. Final single-coordinate cleanup
is allowed only within 1e-9 of the integral value forced by group size. Actual
maximum residuals are recorded; every final group and trait count is independently
checked against integer quotas.

Seeds alone do not guarantee bitwise identical paths across compiler/architecture
floating-point implementations. The archived panel files are the exact empirical
record. Other calibration objectives or null-direction rules may change the
statistics. No LEXIMIN comparison is included. The two cases use different quotas
and target vectors, so their mean-miss difference is not an algorithm comparison.
