Architecture Overview
=====================

This project implements a Monte Carlo simulation framework for the classical Heisenberg (and optional Ising) spin models on periodic supercells. The code is organized around a small set of core data structures and a clear simulation pipeline, with MPI used to distribute temperature points and (optionally) perform replica exchange.

High-level flow
---------------

1. **Initialization and input parsing**
   - The entry point `src/MMC.cpp` reads command-line options, a TOML input file, and a POSCAR-like structure file.
   - Input is split by responsibility:
     - `input.toml` defines Monte Carlo parameters, model/hamiltonian options, lattice size, neighbor definitions, and initialization settings.
     - `POSCAR` provides the lattice vectors and atomic positions for the base cell.

2. **Data distribution (MPI)**
   - The root process parses input and then broadcasts the `Supercell` and `MonteCarlo` configuration to all ranks.

3. **Supercell construction**
   - The lattice is enlarged according to `n_x, n_y, n_z`.
   - Spins are initialized using either explicit directions or rotations derived from `Initialization` angles.
   - Neighbor lists are built for each site by matching element types and distances with tolerance.

4. **Simulation loop**
   - The framework selects one of two methods:
     - **Classical Monte Carlo**: each rank handles a subset of temperature points.
     - **Parallel Tempering**: ranks perform replica exchange at fixed intervals.
   - Each Monte Carlo step updates a randomly chosen spin using the Metropolis criterion.

5. **Output**
   - Thermodynamic observables (energy, heat capacity, magnetization, susceptibility) are collected and written to an output file.
   - Spin configurations can be exported to XSF for visualization.

Core data structures
--------------------

- **BaseSite** (`src/MC_structure.h`)
  - Stores per-species parameters read from input: element names, exchange parameters, anisotropy, magnetic field, and neighbor definitions.

- **Site** (`src/MC_structure.h`)
  - Represents a single spin site in the supercell.
  - Holds pointers back to BaseSite parameters and a list of neighbor site pointers.

- **Lattice** (`src/MC_structure.h`)
  - Lattice vectors, scaling, supercell size, Hamiltonian type, model type, and optional external field.

- **MonteCarlo** (`src/MC_structure.h`)
  - Temperature schedule, number of steps, flips per step, and method selection.

- **Supercell** (`src/MC_structure.h`)
  - Owns the 4D container of `Site` objects.
  - Stores function pointers for the active Hamiltonian and update rule.

Hamiltonian and updates
-----------------------

- Hamiltonians are defined in `src/Hamiltonian.cpp` and selected at runtime based on input.
- The update rule is selected by model type:
  - Heisenberg: random 3D spin proposals.
  - Ising: spin flips.

Parallelization model
---------------------

- **Classical Monte Carlo**: temperatures are partitioned across ranks; each rank relaxes and samples at its assigned temperatures, then results are gathered on rank 0.
- **Parallel Tempering**: replica exchange steps occur at a configurable interval using Metropolis acceptance, with temperatures swapped between neighboring ranks.

Configuration boundaries
------------------------

- `input.toml` defines physics and simulation parameters.
- `POSCAR` defines the base lattice and atom positions.
- The code uses a tolerance-based distance check to match neighbor shells.

Key entry points and files
--------------------------

- Entry point: `src/MMC.cpp`
- Input parsing: `src/configure_in.cpp`, `src/structure_in.cpp`
- Supercell construction: `src/initialization.cpp`
- Hamiltonians: `src/Hamiltonian.cpp`
- Monte Carlo methods: `src/methods/classical.cpp`, `src/methods/parallel_tempering.cpp`
- Output: `src/result_out.cpp`, `src/spin_out.cpp`

Design notes for agents
-----------------------

- Runtime behavior is driven entirely by the parsed `Supercell` and `MonteCarlo` structures.
- The selected Hamiltonian and update strategy are injected via function pointers in `Supercell`.
- Neighbor topology is derived once during initialization and reused throughout the simulation.
- MPI is used only for distributing temperature points and replica exchange, not for domain decomposition.