Metadata-Version: 2.4
Name: isingenerator
Version: 3.1.2
Summary: High-performance 2D Ising model Monte Carlo simulation with topological analysis
Author-email: Erick Ríos <erickjesusriosgonzalez@gmail.com>
License: MIT
Project-URL: Homepage, https://isingenerator.readthedocs.io/en/latest/
Project-URL: Documentation, https://isingenerator.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/erick-rios/ISINGenerator
Keywords: ising model,monte carlo,statistical mechanics,phase transition,computational physics,forman-ricci curvature,HPC,OpenMP,topological variables,high performance computing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: C++
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: matplotlib>=3.7
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-benchmark; extra == "dev"

<p align="center">
  <a href="https://github.com/erick-rios/ISINGenerator">
    <img src="https://img.shields.io/badge/GitHub-Repository-black?style=for-the-badge">
  </a>
  <a href="https://pypi.org/project/isingenerator/">
    <img src="https://img.shields.io/badge/PyPI-Package-blue?style=for-the-badge">
  </a>
</p>

<p align="center">
  <img src="https://github.com/erick-rios/ISINGenerator/raw/main/images/logo.png" width="300">
</p>

<h1 align="center">
ISINGenerator
</h1>

<p align="center">
High-performance 2D Ising model Monte Carlo simulation with topological and geometrical analysis
</p>

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

## Features

<p align="center">
  <img src="https://github.com/erick-rios/ISINGenerator/raw/main/images/initial_state.png" width="45%">
  <img src="https://github.com/erick-rios/ISINGenerator/raw/main/images/nearest_neighbors.png" width="46.5%">
</p>

<p align="center">
Spin configuration (left) and nearest neighbors curvature (right) representation.
</p>
- 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

```bash
pip install isingenerator
```


## Quick start

```python
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 |D| \rangle$ |
| `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/

