# leofio/perfectsimulation architecture

> Architecture diagram of the GitHub repository leofio/perfectsimulation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/leofio/perfectsimulation
- Repository: https://github.com/leofio/perfectsimulation

## Overview

This is a perfect-simulation library for sampling exact stationary configurations of lattice-based statistical-mechanics models. A user constructs a lattice and model, then runs monotone CFTP, bounding-chain CFTP, or read-only CFTP to obtain samples. The model layer supplies state transitions and counter-based randomness; model implementations cover Ising, hard-core, and random-cluster systems, with a documented random-cluster-to-Potts coloring capability. The README is empty, so capabilities are inferred from source and the project tree; unsampled subsystem wiring is omitted.

Main entry points: [`src/models/baseModel.py`](https://github.com/leofio/perfectsimulation/blob/main/src/models/baseModel.py) (Model abstractions), [`src/lattice.py`](https://github.com/leofio/perfectsimulation/blob/main/src/lattice.py) (Lattice builders), [`src/perfectSim/cftp.py`](https://github.com/leofio/perfectsimulation/blob/main/src/perfectSim/cftp.py) (Monotone CFTP), [`src/models/randomCluster.py`](https://github.com/leofio/perfectsimulation/blob/main/src/models/randomCluster.py) (Random-cluster model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_geometry["Lattice geometry"]
  node_lattice["Lattice builders<br/>[lattice.py]"]
end

subgraph group_models["Model dynamics"]
  node_base["Model abstractions<br/>[baseModel.py]"]
  node_ising["Ising models<br/>[ising.py]"]
  node_hardcore["Hard-core models<br/>[hardCore.py]"]
  node_randomcluster["Random-cluster model<br/>[randomCluster.py]"]
  node_potts["Potts coloring<br/>[potts.py]"]
end

subgraph group_sampling["Perfect sampling"]
  node_monotone["Monotone CFTP<br/>[cftp.py]"]
  node_bounding["Bounding CFTP<br/>[bounding_cftp.py]"]
  node_rocftp["Read-only CFTP<br/>[rocftp.py]"]
end

node_user(("Researcher"))
node_samples["Exact samples"]

node_user -->|"constructs"| node_lattice
node_user -->|"configures"| node_ising
node_user -->|"configures"| node_hardcore
node_user -->|"configures"| node_randomcluster
node_user -->|"runs"| node_monotone
node_user -->|"runs"| node_bounding
node_user -->|"runs"| node_rocftp
node_lattice -->|"provides geometry"| node_ising
node_lattice -->|"provides geometry"| node_hardcore
node_lattice -->|"provides geometry"| node_randomcluster
node_base -->|"defines interface"| node_ising
node_base -->|"defines interface"| node_hardcore
node_base -->|"defines interface"| node_randomcluster
node_monotone -->|"requests randomness, applies updates"| node_base
node_bounding -->|"requests randomness, applies updates"| node_base
node_rocftp -->|"requests randomness, applies updates"| node_base
node_monotone -->|"returns samples"| node_samples
node_bounding -->|"returns samples"| node_samples
node_rocftp -->|"returns samples"| node_samples
node_monotone -.->|"provides RC states"| node_potts
node_randomcluster -->|"provides edges"| node_potts
node_potts -->|"colors clusters"| node_samples

click node_lattice "https://github.com/leofio/perfectsimulation/blob/main/src/lattice.py"
click node_base "https://github.com/leofio/perfectsimulation/blob/main/src/models/baseModel.py"
click node_ising "https://github.com/leofio/perfectsimulation/blob/main/src/models/ising.py"
click node_hardcore "https://github.com/leofio/perfectsimulation/blob/main/src/models/hardCore.py"
click node_randomcluster "https://github.com/leofio/perfectsimulation/blob/main/src/models/randomCluster.py"
click node_potts "https://github.com/leofio/perfectsimulation/blob/main/src/models/potts.py"
click node_monotone "https://github.com/leofio/perfectsimulation/blob/main/src/perfectSim/cftp.py"
click node_bounding "https://github.com/leofio/perfectsimulation/blob/main/src/perfectSim/bounding_cftp.py"
click node_rocftp "https://github.com/leofio/perfectsimulation/blob/main/src/perfectSim/rocftp.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lattice toneBlue
class node_base,node_ising,node_hardcore,node_randomcluster,node_potts toneAmber
class node_monotone,node_bounding,node_rocftp toneMint
class node_user,node_samples toneIndigo
```

## Components

### Lattice geometry

- [Lattice builders](https://github.com/leofio/perfectsimulation/blob/main/src/lattice.py): `src/lattice.py`

### Model dynamics

- [Model abstractions](https://github.com/leofio/perfectsimulation/blob/main/src/models/baseModel.py): `src/models/baseModel.py`
- [Ising models](https://github.com/leofio/perfectsimulation/blob/main/src/models/ising.py): `src/models/ising.py`
- [Hard-core models](https://github.com/leofio/perfectsimulation/blob/main/src/models/hardCore.py): `src/models/hardCore.py`
- [Random-cluster model](https://github.com/leofio/perfectsimulation/blob/main/src/models/randomCluster.py): `src/models/randomCluster.py`
- [Potts coloring](https://github.com/leofio/perfectsimulation/blob/main/src/models/potts.py): `src/models/potts.py`

### Perfect sampling

- [Monotone CFTP](https://github.com/leofio/perfectsimulation/blob/main/src/perfectSim/cftp.py): `src/perfectSim/cftp.py`
- [Bounding CFTP](https://github.com/leofio/perfectsimulation/blob/main/src/perfectSim/bounding_cftp.py): `src/perfectSim/bounding_cftp.py`
- [Read-only CFTP](https://github.com/leofio/perfectsimulation/blob/main/src/perfectSim/rocftp.py): `src/perfectSim/rocftp.py`

### Other components

- **Researcher**
- **Exact samples**

## Connections

- Researcher → Lattice builders: constructs
- Researcher → Ising models: configures
- Researcher → Hard-core models: configures
- Researcher → Random-cluster model: configures
- Researcher → Monotone CFTP: runs
- Researcher → Bounding CFTP: runs
- Researcher → Read-only CFTP: runs
- Lattice builders → Ising models: provides geometry
- Lattice builders → Hard-core models: provides geometry
- Lattice builders → Random-cluster model: provides geometry
- Model abstractions → Ising models: defines interface
- Model abstractions → Hard-core models: defines interface
- Model abstractions → Random-cluster model: defines interface
- Monotone CFTP → Model abstractions: requests randomness, applies updates
- Bounding CFTP → Model abstractions: requests randomness, applies updates
- Read-only CFTP → Model abstractions: requests randomness, applies updates
- Monotone CFTP → Exact samples: returns samples
- Bounding CFTP → Exact samples: returns samples
- Read-only CFTP → Exact samples: returns samples
- Monotone CFTP → Potts coloring: provides RC states
- Random-cluster model → Potts coloring: provides edges
- Potts coloring → Exact samples: colors clusters