# Supplementary materials

This archive accompanies **The Nim-Sum of a Random Integer Partition**.
It contains the exact counts through total size `N = 20000`, the data behind every numerical table and figure, the exact counting code, and independent verification routines.

## Directory map

```text
nim_random_partition_supplement/
├── README.md
├── DATA_DICTIONARY.md
├── CITATION.txt
├── MANIFEST.tsv
├── SHA256SUMS.txt
├── requirements.txt
├── data/
│   ├── counts/
│   ├── tables/
│   └── figures/
├── code/
│   ├── exact_counts/
│   ├── analysis/
│   ├── independent_checks/
│   └── release/
└── figures/
```

## Exact counts

The main count table is

```text
data/counts/nim_losing_counts_N0_N20000.tsv
```

It has one row for every total size `N = 0,...,20000`. The column `losing_count_a_N` is zero for odd `N`. For even `N`, the OEIS index is `k = N/2`.

The compact two-column sequence file is

```text
data/counts/oeis_A048833_k0_k10000.txt
```

Its first column is the OEIS index `k`, not the total size. Thus the last row `k = 10000` corresponds to total size `N = 20000`.

The preceding public OEIS b-file is retained as a comparison snapshot:

```text
data/counts/oeis_A048833_public_k0_k750.txt
```

The release verification report is

```text
data/counts/exact_count_verification.txt
```

The exact reconstruction used 17 prime moduli. Their product had 527 bits, while `p(20000)` had 507 bits. Every reconstructed count was also checked modulo the independent prime `2147483171`. The packaged values through `k = 750` agree with the preceding public OEIS b-file.

The historical list of 17 primes from the original run was not retained. The file

```text
code/exact_counts/moduli_example_17.txt
```

contains a fresh valid set of 17 distinct primes below `2^31` whose product also has 527 bits. It is supplied for rerunning the calculation, not as a claim about the exact prime list used in the original run. A full run with this example prime set was executed on a sixteen-core AMD Ryzen 9 9950X and reproduced all 10001 packaged values.

## Table data

Each numerical table in the paper has a separate TSV file.

| Paper table | File | Generated by |
|---|---|---|
| Table 1 | `data/tables/table_01_first_order_milestones.tsv` | `build_count_data.py` |
| Table 2 | `data/tables/table_02_error_decomposition.tsv` | `compute_error_decomposition.py` |
| Table 3 | `data/tables/table_03_two_level_error_budget.tsv` | `compute_hierarchy_data.py` |
| Table 4 | `data/tables/table_04_second_order_fixed_size.tsv` | `compute_second_order_data.py` |
| Table 5 | `data/tables/table_05_major_arc_validation.tsv` | `compute_major_arc_validation.py` |

The TSV files retain more digits than the printed tables.

## Figure data and figure files

Figures 1 and 2 are generated directly from their limiting formulas. Figures 3--6 use the following data files.

| Paper figure | Data file |
|---|---|
| Figures 3--4 | `data/figures/fig_03_04_hierarchy_and_error_sources_N2000_N20000.tsv` |
| Figure 5 | `data/figures/fig_05_fixed_size_correction_N2000_N20000.tsv` |
| Figure 6 | `data/figures/fig_06_exact_density_N100_N20000.tsv` |

The PDF files carry the numbered names used by the manuscript source;
the PNG copies carry descriptive names.

| Paper figure | PDF | PNG |
|---|---|---|
| The dyadic sawtooth | `fig1.pdf` | `dyadic_sawtooth.png` |
| The Poisson transition | `fig2.pdf` | `poisson_transition.png` |
| The dyadic hierarchy | `fig3.pdf` | `dyadic_hierarchy.png` |
| The sources of the two-level error | `fig4.pdf` | `two_level_error_sources.png` |
| The fixed-size correction | `fig5.pdf` | `fixed_size_correction.png` |
| Exact density and first-order prediction | `fig6.pdf` | `exact_density.png` |

Each figure is provided as vector PDF and high-resolution PNG in `figures/`.

## Reproduce the figures from the included data

Install the Python packages in `requirements.txt`, then run

```bash
python3 code/analysis/make_all_figures.py
```

This command reads the included TSV files and writes all six PDF and PNG figures to `figures/`.

## Rebuild the numerical data and figures

The following wrapper runs the data scripts in dependency order and then regenerates all figures:

```bash
code/analysis/rebuild_all_analysis.sh
```

The equivalent explicit sequence is

```bash
python3 code/analysis/build_count_data.py
python3 code/analysis/compute_hierarchy_data.py
python3 code/analysis/compute_second_order_data.py
python3 code/analysis/compute_error_decomposition.py
python3 code/analysis/compute_major_arc_validation.py
python3 code/analysis/make_all_figures.py
```

The major-arc calculation is the most expensive Python check. Figure generation itself only reads the completed TSV files.

## Quick exact-count check

A short run through total size `N = 1500` reproduces the `751` packaged values and exercises the C++ recurrence, 17-prime CRT reconstruction, independent check prime, and packaged-data comparison:

```bash
OMP_NUM_THREADS=4 \
code/exact_counts/run_exact_counts.sh 1500 work/quick_check
```

The generated files are written to `work/quick_check/output/`. On an AVX2 machine this run normally finishes in a few seconds. The exact quick run and the independent knapsack check can also be launched together with

```bash
code/independent_checks/run_quick_checks.sh
```

## Full exact-count run

The complete run is

```bash
OMP_NUM_THREADS=16 \
code/exact_counts/run_exact_counts.sh 20000 work/full_run
```

The program requires a C++ compiler with AVX2 and OpenMP support. On a sixteen-core AMD Ryzen 9 9950X with sixteen threads, the 17 reconstruction primes took about 110 seconds in total, and the complete driver including the independent check-prime pass finished in about two minutes.

The exact-count driver performs the following steps:

1. compiles `nimxor_walsh_avx2.cpp`;
2. computes the residue table for each of the 17 reconstruction primes;
3. reconstructs the integer counts by CRT;
4. computes the residues modulo the independent check prime;
5. verifies all generated values modulo that prime; and
6. compares the generated range with the packaged exact data.

## Independent direct-knapsack check

The main exact algorithm uses signed partition recurrences and Walsh characters. A separate check at `N = 1500` uses a direct distinct-part XOR knapsack, reconstructs the distinct-core counts by CRT, and then applies the odd-core convolution:

```bash
python3 code/independent_checks/knapsack_check_N1500.py
```

This check is algorithmically separate from the main exact-count recurrence and reproduces the packaged value of `a_1500`. Its packaged output is recorded in `data/counts/knapsack_check_N1500.txt`.

The release-level count and knapsack checks can be run with

```bash
code/independent_checks/run_all_checks.sh
```

A combined quick run that also rebuilds the exact counts through `N = 1500` is

```bash
OMP_NUM_THREADS=4 code/independent_checks/run_quick_checks.sh
```

The recorded direct-knapsack output is in `data/counts/knapsack_check_N1500.txt`.

## Software

The analysis scripts require Python 3, NumPy, and Matplotlib. The exact count program requires `g++` or a compatible C++ compiler with `-O3 -march=native -mavx2 -fopenmp`. The direct knapsack helper uses standard C++17.
