1D Ising Model Monte Carlo Simulation in C++

This portfolio project implements a reproducible Metropolis Monte Carlo study of the one-dimensional nearest-neighbour Ising model. The simulation is written in modern C++17; Python is used only to verify machine-readable results and render deterministic SVG figures.

Scientific question

How accurately can finite, independently seeded Monte Carlo chains reproduce exact thermodynamic observables of the infinite 1D Ising model, and what do acceptance, magnetization, uncertainty, and finite-size diagnostics reveal about the sampling process?

The original coursework was rebuilt to separate archived provenance from an active implementation that has periodic boundaries, a persistent deterministic random-number engine, explicit burn-in and measurement phases, multiple independent chains, validation, tests, and reproducible outputs.

Model and assumptions

For spins (s_i \in {-1,+1}), the Hamiltonian is

[ H = -J \sum_{i=0}^{N-1} s_i s_{(i+1) \bmod N} - h \sum_i s_i. ]

The active model is strictly one-dimensional, with natural units (J=k_B=1), zero external field (h=0), nearest-neighbour coupling, and periodic boundary conditions. Every bond is counted once. A proposed flip at site (i) has

[ \Delta E = 2s_i(s_{i-1}+s_{i+1}). ]

The Metropolis rule accepts every (\Delta E \le 0) proposal and otherwise accepts with probability (\exp(-\beta\Delta E)). One sweep is exactly (N) randomly selected flip attempts; production updates use the local energy change and do not recompute the full Hamiltonian per proposal.

Equilibration, measurement, and observables

Each beta point runs independent chains. A chain is randomly initialized, equilibrated for the configured burn-in sweeps, then sampled only during a distinct measurement phase at the configured interval. With (e=E/N) and (m=M/N), the reported estimators are

[ C/N = \beta^2N(\langle e^2\rangle-\langle e\rangle^2), \qquad \chi/N = \beta N(\langle m^2\rangle-\langle m\rangle^2). ]

The susceptibility uses signed magnetization, while (\langle |m|\rangle) is reported separately. Every Monte Carlo observable is calculated per chain and its standard error is estimated across the independent chain estimates. This is a simple between-chain uncertainty measure, not a full integrated-autocorrelation-time analysis; consecutive retained samples can remain autocorrelated.

Exact 1D comparison

For the infinite zero-field 1D model,

[ u(\beta)=-\tanh(\beta), \qquad c(\beta)=\frac{\beta^2}{\cosh^2(\beta)}. ]

The CSV includes both exact curves and absolute Monte Carlo errors. The infinite 1D zero-field model has no finite-temperature phase transition, and its signed magnetization is zero in the symmetry-preserving equilibrium ensemble. Non-zero finite-run (\langle|m|\rangle) values are finite-size and sampling diagnostics, not evidence of spontaneous symmetry breaking. At low temperature, finite chains can mix slowly between positive and negative magnetized configurations.

Reproducibility

One persistent std::mt19937_64 engine is used per chain. The documented master seed is 20250807; independent chain seeds are derived deterministically with SplitMix64 from the master seed, beta index, and chain index. Identical inputs produce byte-identical CSV files. Metadata records the build environment, every simulation parameter, derivation method, generation command and time, source commit available at configuration, and the SHA-256 of the result CSV.

Build and run

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
ctest --test-dir build --output-on-failure

Canonical portfolio run (40 beta values from 0.05 through 2.00):

./build/ising_simulation --config config/portfolio_run.json --output results/ising_1d_results.csv --metadata-output results/run_metadata.json
python scripts/summarize_results.py
python scripts/plot_results.py

Quick smoke run without modifying committed results:

./build/ising_simulation --config config/smoke_run.json --output /tmp/ising-smoke.csv --metadata-output /tmp/ising-smoke-metadata.json

Verification and deterministic plot consistency:

python scripts/verify_results.py
python scripts/plot_results.py --check

CI executes the Release build, all CTest tests, a temporary smoke simulation, result verification, and the SVG consistency check without regenerating canonical files. GitHub Actions is configured for both push and pull_request events so the same offline validation runs before review.

Key numerical results

The committed run uses (N=128), 1,000 burn-in sweeps, 5,000 measurement sweeps, a 10-sweep measurement interval, four chains, and 500 retained measurements per chain.

• Low beta (β = 0.05): ⟨e⟩ = -0.052672 (exact -0.049958); C/N = 0.002480 (exact 0.002494); ⟨|m|⟩ = 0.075133; acceptance = 0.949992.

• Middle beta (β = 1.05): ⟨e⟩ = -0.782875 (exact -0.781806); C/N = 0.432614 (exact 0.428629); ⟨|m|⟩ = 0.207156; acceptance = 0.219093.

• High beta (β = 2.00): ⟨e⟩ = -0.965625 (exact -0.964028); C/N = 0.263246 (exact 0.282603); ⟨|m|⟩ = 0.515766; acceptance = 0.034297.

• Maximum absolute errors: energy 0.003996; heat capacity 0.049931.

Figures

Energy

Heat capacity

Magnetization diagnostics

Susceptibility

Acceptance rate

Interpretation and limitations

Energy should follow the exact infinite-chain result closely, while the fluctuation-based heat capacity is noisier. Falling acceptance and growing (\langle|m|\rangle) at high beta diagnose slow low-temperature dynamics in a finite lattice; they do not establish a critical temperature. Finite (N), finite burn-in, finite measurement length, discrete beta spacing, autocorrelation, and only four chains limit precision. No autocorrelation-time, blocking, or finite-size-scaling analysis is attempted. This project is educational and descriptive.

Repository structure

include/ising/   reusable C++ interfaces
src/             spin system, simulation, statistics, and CLI
tests/           deterministic unit and integration tests
config/          canonical and smoke profiles
scripts/         result verification, summary derivation, and SVG plotting
results/         canonical CSV, metadata, and summary
assets/          deterministic text SVG figures
archive/         untouched original coursework and provenance notes

Original coursework archive and license

The files formerly at repository root are preserved under archive/original_coursework, with hashes for the original binary/document artifacts. They are not part of the active build. The MIT license covers the rebuilt active project; no retroactive license claim is made over uncertain or third-party archived material.