Plotting

mcising includes plotting functions for all key observables, lattice visualization, and a bulk export tool. Every plot function accepts either a SimulationResults object or an HDF5 file path.

Optional dependency

Since 0.26.0 matplotlib is the optional plot extra — install with pip install 'mcising[plot]'. The core simulation API works without it; accessing any plotting function without matplotlib raises an ImportError naming the extra. (pandas, used only by SimulationResults.to_dataframe, is the dataframe extra.)

Thermodynamic quantities

Each function plots one quantity vs temperature with real error bars: blocking (Flyvbjerg–Petersen) standard errors for the means, delete-one-block jackknife errors for specific heat and susceptibility (see Statistics). Points whose series is too short to quote an uncertainty render without a bar rather than with a fake zero-height one.

from mcising import (
    Simulation, SimulationConfig, LatticeConfig, save_hdf5,
    plot_energy, plot_magnetization, plot_specific_heat, plot_susceptibility,
)

config = SimulationConfig(
    lattice=LatticeConfig(size=16),
    temperatures=(3.0, 2.5, 2.269, 2.0, 1.5),
    n_sweeps=1000,
    measurement_interval=20,   # 50 samples (and stored configurations) per T
    compute_correlation=True,  # needed by plot_correlation below
)
results = Simulation(config).run()
save_hdf5(results, "results.h5")

# Plot from memory or from file — both work
plot_energy(results).savefig("energy.png")
plot_magnetization("results.h5").savefig("magnetization.png")
plot_specific_heat("results.h5").savefig("specific_heat.png")
plot_susceptibility("results.h5").savefig("susceptibility.png")

Comparing different coupling configurations

Pass a list of file paths to overlay results with auto-generated legends:

for j2 in (0.0, 0.3, 0.5):
    run = Simulation(
        SimulationConfig(
            lattice=LatticeConfig(size=16, j1=1.0, j2=j2),
            temperatures=(3.0, 2.5, 2.0),
            n_sweeps=500,
        )
    ).run()
    save_hdf5(run, f"j2_{j2}.h5")

plot_energy(["j2_0.0.h5", "j2_0.3.h5", "j2_0.5.h5"]).savefig("compare.png")

Each curve is labeled with the coupling parameters extracted from the HDF5 metadata.

Spin configurations

Single temperature — all configs or one

from mcising import plot_lattice

# Show ALL configurations at T=2.269 side by side
plot_lattice("results.h5", temperature=2.269)

# Show just configuration #3
plot_lattice("results.h5", temperature=2.269, n=3)

If you request an invalid index, you get a descriptive error:

ValueError: Config index 999 out of range. Temperature T=2.269
has 50 configurations (n=0..49).

Bulk export to zip

Export every lattice configuration as a PNG in a zip file:

from mcising import export_lattices

# Tree mode: folders per temperature
export_lattices("results.h5", "lattices.zip")
# → square_16x16_J1=1.0_metropolis/T=2.2690/config_001.png

# Flat mode: all PNGs in one folder
export_lattices("results.h5", "lattices.zip", flat=True)
# → square_16x16_J1=1.0_metropolis_T=2.2690_config_001.png

# Export only specific temperatures
export_lattices("results.h5", "lattices.zip", temperatures=[2.269, 1.5])

Filenames encode lattice type, size, couplings, algorithm, temperature, and sample number.

Diagnostic plots

Energy time series

Check if thermalization was sufficient — the trace should be stationary (no drift):

from mcising import plot_energy_timeseries

plot_energy_timeseries("results.h5", temperature=2.269)

Magnetization histogram

See the distribution of magnetization at a given temperature. Bimodal below Tc, Gaussian above:

from mcising import plot_magnetization_histogram

plot_magnetization_histogram("results.h5", temperature=2.269)

Correlation function

Requires compute_correlation=True in the simulation config; the plotted C(r) is the run's last evaluation (see correlation_interval in the configuration guide):

from mcising import plot_correlation

plot_correlation("results.h5", temperature=2.269)

Summary table

No plotting needed — just print a Rich table:

results.summary()

                    Simulation Results
┏━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━┓
┃      T ┃   <E>/N ┃ <|M|>/N ┃   Cv/N ┃   chi/N ┃ samples ┃
┡━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━┩
│ 1.5000 │ -1.9484 │  0.9859 │ 0.1992 │  0.0246 │      50 │
│ 2.2690 │ -1.4531 │  0.6712 │ 1.8420 │ 12.5430 │      50 │
│ 3.5000 │ -0.6630 │  0.0605 │ 0.2657 │  1.5562 │      50 │
└────────┴─────────┴─────────┴────────┴─────────┴─────────┘

See the API Reference for full function signatures.