# tmisawa/sai-qmc architecture

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

- Interactive diagram: https://gitdiagram.com/tmisawa/sai-qmc
- Repository: https://github.com/tmisawa/sai-qmc

## Overview

SAI-QMC is a command-line finite-temperature determinant quantum Monte Carlo simulator for the half-filled repulsive Hubbard model. The user supplies lattice and run parameters; the executable sets up replicas, warms and measures Monte Carlo chains, then reports scalar observables and optional longitudinal/transverse spin structure factors with statistical errors. The graph separates model setup, simulation numerics, measurement, and execution/output. Relationships inside the replica runner are supported by its excerpt; some wiring in the partially excerpted main program is shown as unverified rather than inferred as a confirmed call.

Main entry points: [`src/main.c`](https://github.com/tmisawa/sai-qmc/blob/main/src/main.c) (Run coordinator), [`src/replica_run.c`](https://github.com/tmisawa/sai-qmc/blob/main/src/replica_run.c) (Replica runner), [`src/structure_factor.c`](https://github.com/tmisawa/sai-qmc/blob/main/src/structure_factor.c) (Spin structure factors), [`src/field.c`](https://github.com/tmisawa/sai-qmc/blob/main/src/field.c) (Auxiliary field)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Run and model setup"]
  node_input["Input parser<br/>[io.c]"]
  node_lattice["Lattice<br/>[lattice.c]"]
  node_model["Hubbard model<br/>[model.c]"]
end

subgraph group_numerics["DQMC numerics"]
  node_rng["Random generator<br/>[rng.c]"]
  node_field["Auxiliary field<br/>[field.c]"]
  node_dqmc["DQMC engine<br/>[dqmc.c]"]
  node_green["Green functions<br/>[green.c]"]
  node_linalg["Linear algebra<br/>[linalg.c]"]
end

subgraph group_observables["Measurement and observables"]
  node_measure["Scalar measurements<br/>[measure.c]"]
  node_spin["Spin structure factors<br/>[structure_factor.c]"]
end

subgraph group_execution["Replica execution and output"]
  node_cli["Run coordinator<br/>[main.c]"]
  node_runner["Replica runner<br/>[replica_run.c]"]
  node_replica["Replica results<br/>[replica.c]"]
  node_parallel["MPI coordination<br/>[replica_mpi.c]"]
  node_scalarout["Scalar output<br/>[scalar_output.c]"]
  node_profile["Run profiler<br/>[profiler.c]"]
end

node_user(("Researcher"))
node_results["Observable files"]

node_user -->|"starts run"| node_cli
node_cli -.->|"reads settings"| node_input
node_cli -.->|"dispatches replicas"| node_runner
node_runner -->|"initializes"| node_model
node_runner -->|"initializes"| node_field
node_runner -->|"initializes and sweeps"| node_dqmc
node_runner -->|"measures spin"| node_spin
node_runner -->|"accumulates samples"| node_replica
node_field -.->|"uses"| node_rng
node_dqmc -.->|"updates"| node_green
node_green -->|"uses"| node_linalg
node_runner -.->|"samples observables"| node_measure
node_cli -.->|"coordinates MPI"| node_parallel
node_cli -.->|"writes scalar data"| node_scalarout
node_cli -.->|"writes spin data"| node_spin
node_cli -.->|"records timings"| node_profile
node_scalarout -.->|"writes"| node_results
node_spin -.->|"writes"| node_results

click node_cli "https://github.com/tmisawa/sai-qmc/blob/main/src/main.c"
click node_input "https://github.com/tmisawa/sai-qmc/blob/main/src/io.c"
click node_lattice "https://github.com/tmisawa/sai-qmc/blob/main/src/lattice.c"
click node_model "https://github.com/tmisawa/sai-qmc/blob/main/src/model.c"
click node_rng "https://github.com/tmisawa/sai-qmc/blob/main/src/rng.c"
click node_field "https://github.com/tmisawa/sai-qmc/blob/main/src/field.c"
click node_dqmc "https://github.com/tmisawa/sai-qmc/blob/main/src/dqmc.c"
click node_green "https://github.com/tmisawa/sai-qmc/blob/main/src/green.c"
click node_linalg "https://github.com/tmisawa/sai-qmc/blob/main/src/linalg.c"
click node_runner "https://github.com/tmisawa/sai-qmc/blob/main/src/replica_run.c"
click node_replica "https://github.com/tmisawa/sai-qmc/blob/main/src/replica.c"
click node_parallel "https://github.com/tmisawa/sai-qmc/blob/main/src/replica_mpi.c"
click node_measure "https://github.com/tmisawa/sai-qmc/blob/main/src/measure.c"
click node_spin "https://github.com/tmisawa/sai-qmc/blob/main/src/structure_factor.c"
click node_scalarout "https://github.com/tmisawa/sai-qmc/blob/main/src/scalar_output.c"
click node_profile "https://github.com/tmisawa/sai-qmc/blob/main/src/profiler.c"

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_input,node_lattice,node_model toneBlue
class node_rng,node_field,node_dqmc,node_green,node_linalg toneAmber
class node_measure,node_spin toneMint
class node_cli,node_runner,node_replica,node_parallel,node_scalarout,node_profile toneRose
class node_user,node_results toneIndigo
```

## Components

### Run and model setup

- [Input parser](https://github.com/tmisawa/sai-qmc/blob/main/src/io.c): `src/io.c`
- [Lattice](https://github.com/tmisawa/sai-qmc/blob/main/src/lattice.c): `src/lattice.c`
- [Hubbard model](https://github.com/tmisawa/sai-qmc/blob/main/src/model.c): `src/model.c`

### DQMC numerics

- [Random generator](https://github.com/tmisawa/sai-qmc/blob/main/src/rng.c): `src/rng.c`
- [Auxiliary field](https://github.com/tmisawa/sai-qmc/blob/main/src/field.c): `src/field.c`
- [DQMC engine](https://github.com/tmisawa/sai-qmc/blob/main/src/dqmc.c): `src/dqmc.c`
- [Green functions](https://github.com/tmisawa/sai-qmc/blob/main/src/green.c): `src/green.c`
- [Linear algebra](https://github.com/tmisawa/sai-qmc/blob/main/src/linalg.c): `src/linalg.c`

### Measurement and observables

- [Scalar measurements](https://github.com/tmisawa/sai-qmc/blob/main/src/measure.c): `src/measure.c`
- [Spin structure factors](https://github.com/tmisawa/sai-qmc/blob/main/src/structure_factor.c): `src/structure_factor.c`

### Replica execution and output

- [Run coordinator](https://github.com/tmisawa/sai-qmc/blob/main/src/main.c): `src/main.c`
- [Replica runner](https://github.com/tmisawa/sai-qmc/blob/main/src/replica_run.c): `src/replica_run.c`
- [Replica results](https://github.com/tmisawa/sai-qmc/blob/main/src/replica.c): `src/replica.c`
- [MPI coordination](https://github.com/tmisawa/sai-qmc/blob/main/src/replica_mpi.c): `src/replica_mpi.c`
- [Scalar output](https://github.com/tmisawa/sai-qmc/blob/main/src/scalar_output.c): `src/scalar_output.c`
- [Run profiler](https://github.com/tmisawa/sai-qmc/blob/main/src/profiler.c): `src/profiler.c`

### Other components

- **Researcher**
- **Observable files**

## Connections

- Researcher → Run coordinator: starts run (evidence: `README.md`)
- Run coordinator → Input parser: reads settings
- Run coordinator → Replica runner: dispatches replicas
- Replica runner → Hubbard model: initializes (evidence: `src/replica_run.c`)
- Replica runner → Auxiliary field: initializes (evidence: `src/replica_run.c`)
- Replica runner → DQMC engine: initializes and sweeps (evidence: `src/replica_run.c`)
- Replica runner → Spin structure factors: measures spin (evidence: `src/replica_run.c`)
- Replica runner → Replica results: accumulates samples (evidence: `src/replica_run.c`)
- Auxiliary field → Random generator: uses
- DQMC engine → Green functions: updates
- Green functions → Linear algebra: uses (evidence: `src/green.c`)
- Replica runner → Scalar measurements: samples observables
- Run coordinator → MPI coordination: coordinates MPI
- Run coordinator → Scalar output: writes scalar data
- Run coordinator → Spin structure factors: writes spin data
- Run coordinator → Run profiler: records timings
- Scalar output → Observable files: writes
- Spin structure factors → Observable files: writes
