ISINGenerator

High-performance 2D Ising model Monte Carlo simulation with topological and geometrical analysis

Written in C++17 with OpenMP parallelism, exposed to Python via pybind11.

Features

Spin configuration (left) and nearest neighbors curvature (right) representation.

- Metropolis algorithm with checkerboard parallelism (OpenMP) - Domain labeling via Union-Find Disjoint Set - **Forman-Ricci curvature** of the +1 spin subgraph - PPM frame generation for animations - LaTex matplotlib visualization

Installation

pip install isingenerator

Quick start

from isingenerator import Simulation, IsingVisualization

sim = Simulation(rows=500, cols=500, J=1.0, B=0.0)

# Temperature sweep
data = sim.run_temperature_range(
    min_temperature=1.0,
    max_temperature=4.0, 
    temperature_step=0.1,
    equilibration_sweeps=50_000,
    measurement_blocks=1_000,
    sweeps_per_block=100,
    threads=8,
    output_csv="results.csv",
)

# Plot
viz = IsingVisualization()
viz.plot_dashboard(data, save="summary.pdf")

# Single temperature
result = sim.run_single_temperature(
    temperature=2.269,
    equilibration_sweeps=100_000,
    measurement_blocks=2_000,
    sweeps_per_block=100,
    threads=8,
)
print(f"M = {result['magnetization']:.4f}")
print(f"FRC mean curvature = {result['forman_ricci_mean_curvature']:.4f}")

# Spin animation
sim.save_frames(
    temperature=2.3, 
    measurement_blocks=500,
    sweeps_per_block=100, 
    folder="frames")
# ffmpeg -framerate 30 -i frames/frame_%06d.ppm -pix_fmt yuv420p spin.mp4

# Forman-Ricci animation
sim.save_frames_forman_ricci(
    temperature=2.3, 
    measurement_blocks=500,
    sweeps_per_block=100, 
    folder="frames_ricci"
)

Observables returned

Key	Description
magnetization	Magnetization per spin: $\langle M \rangle$
energy	Energy per spin: $\langle E \rangle$
total_domains	Total number of connected components
positive_domains / negative_domains	Number of connected components for $s_i = \pm 1$
positive_avg_size / negative_avg_size	Mean component size: $\langle
forman_ricci_mean_curvature	Mean edge curvature: $\langle F(e) \rangle$
forman_ricci_total_curvature	Total curvature: $\sum_{e \in E} F(e)$
forman_ricci_positive_nodes	Cardinality of vertex set: $V$
forman_ricci_edges	Cardinality of edge set: $E$

Physics background

The Hamiltonian of the 2D Ising model is

$$ H = -J \sum_{\langle i,j \rangle} s_i s_j ;- B \sum_i s_i $$

The critical temperature (for $B = 0$ and $J = 1$ ) is given by

$$ T_c = \frac{2J}{\ln\left(1 + \sqrt{2}\right)} \approx 2.269 , \frac{J}{k_B} $$

The Forman–Ricci curvature of an edge $e_{uv}$ in the $+1$ spin subgraph is

$$ F(e_{uv}) = -\deg(u) - \deg(v) $$

where $\deg(\cdot)$ denotes the degree of a vertex in the induced subgraph of positive spins.

Near the critical temperature $T_c$, the mean curvature exhibits a clear signature of the percolation transition.

References:

• Joshua Romero, Mauro Bisson, Massimiliano Fatica, Massimo Bernaschi, High performance implementations of the 2D Ising model on GPUs, Computer Physics Communications, Volume 256, 2020, 107473, ISSN 0010-4655,
• Sedgewick, R., & Wayne, K. (2011). Algorithms. Addison-wesley professional.

Documentation

Full documentation, examples, and API reference are available at:

• GitHub repository:
  https://github.com/erick-rios/ISINGenerator

• PyPI package:
  https://pypi.org/project/isingenerator/