DiskForge

DiskForge generates non-overlapping configurations of hard disks in a two-dimensional periodic box. It prepares an initial configuration, increases the disk radius along a discrete compression schedule, and resolves overlaps with deterministic, seed-controlled relocation. The command-line executable is named diskforge.

The project supports reproducible computational experiments with dense particle configurations. It provides multiple CPU engines, independent final validation, machine-readable output, provenance manifests, and benchmark tools. The compression procedure is an algorithmic construction method, not a physical dynamics integrator or an equilibrium sampler.

Features

• Periodic two-dimensional hard-disk geometry.
• Reproducible mt19937_64 random streams with an explicit 64-bit seed.
• Lattice Monte Carlo and random sequential adsorption initialization.
• Four CPU engines: scan-legacy, scan-fast, scan-omp, and event.
• Deterministic event-calendar scheduling in the default event engine.
• OpenMP overlap discovery in scan-omp.
• Independent long-double, O(N²) validation of completed configurations.
• JSON results and schema-v2 reproducibility manifests.
• Unit, CLI, differential, sanitizer, and benchmark test suites.

Requirements

• A C++20 compiler; GCC is the tested default.
• GNU Make.
• OpenMP.
• Python 3 for the benchmark and CLI test scripts.

The release profile uses -march=native, so release binaries are intended for the machine on which they are built.

Build

make release

Additional build and verification targets:

make debug
make asan
make test
make asan-test

Build artifacts are written as diskforge, diskforge_debug, and diskforge_asan. Use make clean to remove them and the intermediate build/ directory.

Quick start

Run the default event engine with 4,096 particles and seed 42:

./diskforge run

Generate a smaller configuration and save its coordinates:

./diskforge run \
  --particles 1024 \
  --seed 12345 \
  --pf-in 0.35 \
  --pf-end 0.50 \
  --output configuration.txt

The coordinate file contains one x y pair per particle. Unless --skip-oracle is supplied, every completed run is checked by two independent O(N²) final oracles in addition to unconditional structural validation.

Algorithm

The simulation begins by placing disks with either lattice-based Monte Carlo preparation or random sequential adsorption. It then builds a periodic linked cell list so that each disk only needs to inspect nearby cells.

Compression proceeds through a deterministic sequence of increasing radii. At each step, the engine identifies disks that overlap under the minimum-image periodic distance. Those disks and their affected neighbors are relocated with seeded random proposals until the configuration is overlap-free, or until a safety cap is reached.

The default event engine avoids scanning the complete system at every radius. For each nearby pair, it schedules the first compression step at which that pair could overlap. Moving a disk invalidates its old events and schedules new local ones. The actual relocation order remains deterministic, so a fixed executable, parameter set, environment, and seed reproduce the same result.

Finally, the program validates coordinates, cell membership, and local geometry. Unless explicitly disabled, an independent quadratic-time oracle also checks the final configuration without relying on the linked-cell structure.

Engines

Engine	Purpose
event	Default exact discrete-radius event scheduler.
scan-fast	Optimized serial linked-cell overlap scan.
scan-omp	scan-fast discovery with OpenMP parallelism.
scan-legacy	Source-shaped serial reference implementation.
all	Runs all four engines from the same initialized state.

For example:

./diskforge run --engine event --particles 4096 --seed 42
./diskforge run --engine scan-omp --threads 6 --particles 4096 --seed 42
./diskforge run --engine all --particles 256 --seed 42

The optimized engines preserve the same seeded trajectory and final state as the reference engine under the project's stated numerical contract.

Output and reproducibility

Normal output contains parseable INIT, RESULT, and COUNTERS records. Add --json to emit one JSON object per engine:

./diskforge run \
  --engine event \
  --particles 4096 \
  --seed 42 \
  --json \
  --no-output

For a reproducibility sidecar, provide a manifest path:

./diskforge run \
  --seed 42 \
  --output configuration.txt \
  --manifest run.json

The manifest records the resolved parameters, invocation and executable metadata, initialization state, selected environment values, checksums, oracle results, work counters, and artifact paths. Coordinate and manifest files are staged and validated before being atomically replaced.

Use --skip-oracle only when the quadratic validation cost is unsuitable, such as in large timing sweeps. Structural checks still run, but JSON then reports the oracle and validity fields as null.

Important controls

--engine NAME
--seed UINT64
--particles N
--init lattice-mc|rsa
--pf-in X
--pf-end X
--radius-end X
--mc-sweeps N
--mc-step-scale X
--rsa-attempts N
--compression-a X
--epsilon-floor X
--max-trials N
--max-steps N
--threads N
--oracle-threads N
--output PATH
--manifest PATH
--skip-oracle
--json

Run ./diskforge --help for the complete command-line reference.

The default lattice-mc initializer is robust but may retain correlations with its seed lattice when too few sweeps are used. The rsa initializer can exhaust its attempt cap at high packing fractions. Exhausted hard caps represent failed or censored realizations and should remain visible in scientific and performance reporting.

Benchmarking

A short benchmark sanity check is available with:

make benchmark-smoke

The primary paired benchmark uses 30 seeds, three repeats, and all four engines:

make benchmark

The benchmark randomizes adjacent baseline/candidate order, checks exact paired states, preserves failures and timeouts, and reports seed-clustered bootstrap confidence intervals.

To compare the current binary with another compatible build:

PARITY_BASELINE=/path/to/diskforge make parity

Project layout

diskforge.cpp        simulation engine implementation
src/                    application and reusable simulation components
tests/                  C++ unit tests and Python CLI tests
scripts/                benchmark, parity, and sensitivity tools
results/                machine-readable experiment results
Makefile                build, test, and benchmark targets

License

DiskForge is available under the MIT License.