# pkua007/rampack architecture

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

- Interactive diagram: https://gitdiagram.com/pkua007/rampack
- Repository: https://github.com/pkua007/rampack

## Overview

RAMPACK is a command-line Monte Carlo particle-system simulator with configuration preview, shape inspection, trajectory operations, and in-run or post-run analysis. The principal workflow is CLI mode selection, PYON parameter loading, packing construction, Monte Carlo evolution, observable collection, and trajectory/snapshot output. The README documents hard/soft interactions, particle moves, triclinic isobaric relaxation, wall handling, and analysis capabilities; source excerpts confirm dispatch, preview behavior, and selected observable implementations. Casino and trajectory internals were not sampled, so their finer wiring is represented only at the documented subsystem level.

Main entry points: [`src/core/Simulation.cpp`](https://github.com/pkua007/rampack/blob/main/src/core/Simulation.cpp) (Simulation engine), [`src/Main.cpp`](https://github.com/pkua007/rampack/blob/main/src/Main.cpp) (Mode dispatcher), [`src/frontend/IO.cpp`](https://github.com/pkua007/rampack/blob/main/src/frontend/IO.cpp) (Parameter loading), [`src/frontend/modes/PreviewMode.cpp`](https://github.com/pkua007/rampack/blob/main/src/frontend/modes/PreviewMode.cpp) (Initial preview)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Command modes"]
  node_main["Mode dispatcher<br/>[Main.cpp]"]
  node_casino["Monte Carlo mode<br/>[CasinoMode.cpp]"]
  node_preview["Initial preview<br/>[PreviewMode.cpp]"]
  node_shape_preview["Shape preview"]
  node_trajectory_mode["Trajectory mode<br/>[TrajectoryMode.cpp]"]
end

subgraph group_model["System model"]
  node_params["Parameter loading<br/>[IO.cpp]"]
  node_pyon["PYON parser<br/>[Parser.cpp]"]
  node_shape_traits["Shape traits<br/>[ShapeTraits.h]"]
  node_packing["Particle packing<br/>[Packing.cpp]"]
  node_lattice["Lattice initialization<br/>[Lattice.cpp]"]
  node_geometry["Shape geometry<br/>[ShapeGeometry.cpp]"]
  node_interactions["Interaction models<br/>[Interaction.cpp]"]
end

subgraph group_sampling["Simulation and analysis"]
  node_simulation["Simulation engine<br/>[Simulation.cpp]"]
  node_moves["Move samplers<br/>[MoveSampler.h]"]
  node_box_scaling["Box relaxation<br/>[VolumeScaler.h]"]
  node_observables["Observable collection"]
  node_analysis["Analysis measures"]
end

subgraph group_files["Trajectory and output"]
  node_recorders["Trajectory recorders"]
  node_players["Trajectory players<br/>[SimulationPlayer.h]"]
  node_snapshot_io["Snapshot formats<br/>[RamsnapWriter.cpp]"]
  node_trajectory_io["Trajectory formats<br/>[RamtrjIO.cpp]"]
end

node_user(("CLI user"))
node_file_output["Output files"]

node_user -->|"selects mode"| node_main
node_main -->|"dispatches"| node_casino
node_main -->|"dispatches"| node_preview
node_main -->|"dispatches"| node_shape_preview
node_main -->|"dispatches"| node_trajectory_mode
node_preview -->|"loads parameters"| node_params
node_shape_preview -->|"loads input"| node_params
node_shape_preview -->|"matches shape"| node_shape_traits
node_params -->|"parses input"| node_pyon
node_params -->|"builds traits"| node_shape_traits
node_preview -->|"creates packing"| node_packing
node_lattice -->|"populates"| node_packing
node_shape_traits -->|"provides geometry"| node_geometry
node_casino -->|"loads configuration"| node_params
node_casino -->|"runs sampling"| node_simulation
node_simulation -->|"uses moves"| node_moves
node_simulation -->|"evaluates energy"| node_interactions
node_simulation -->|"scales box"| node_box_scaling
node_simulation -->|"collects measurements"| node_observables
node_observables -->|"updates measures"| node_analysis
node_simulation -->|"records snapshots"| node_recorders
node_preview -->|"writes preview"| node_snapshot_io
node_shape_preview -->|"writes shape preview"| node_file_output
node_snapshot_io -->|"writes snapshot"| node_file_output
node_recorders -->|"encodes frames"| node_trajectory_io
node_trajectory_io -->|"writes trajectory"| node_file_output
node_trajectory_mode -->|"operates on trajectory"| node_players
node_players -->|"reads frames"| node_trajectory_io
node_players -->|"exports results"| node_file_output

click node_main "https://github.com/pkua007/rampack/blob/main/src/Main.cpp"
click node_casino "https://github.com/pkua007/rampack/blob/main/src/frontend/modes/CasinoMode.cpp"
click node_preview "https://github.com/pkua007/rampack/blob/main/src/frontend/modes/PreviewMode.cpp"
click node_shape_preview "https://github.com/pkua007/rampack/blob/main/src/frontend/modes/ShapePreviewMode.cpp"
click node_trajectory_mode "https://github.com/pkua007/rampack/blob/main/src/frontend/modes/TrajectoryMode.cpp"
click node_params "https://github.com/pkua007/rampack/blob/main/src/frontend/IO.cpp"
click node_pyon "https://github.com/pkua007/rampack/blob/main/src/pyon/Parser.cpp"
click node_shape_traits "https://github.com/pkua007/rampack/blob/main/src/core/ShapeTraits.h"
click node_packing "https://github.com/pkua007/rampack/blob/main/src/core/Packing.cpp"
click node_lattice "https://github.com/pkua007/rampack/blob/main/src/core/lattice/Lattice.cpp"
click node_geometry "https://github.com/pkua007/rampack/blob/main/src/core/ShapeGeometry.cpp"
click node_interactions "https://github.com/pkua007/rampack/blob/main/src/core/Interaction.cpp"
click node_simulation "https://github.com/pkua007/rampack/blob/main/src/core/Simulation.cpp"
click node_moves "https://github.com/pkua007/rampack/blob/main/src/core/MoveSampler.h"
click node_box_scaling "https://github.com/pkua007/rampack/blob/main/src/core/VolumeScaler.h"
click node_observables "https://github.com/pkua007/rampack/blob/main/src/core/ObservablesCollector.cpp"
click node_analysis "https://github.com/pkua007/rampack/tree/main/src/core/observables"
click node_recorders "https://github.com/pkua007/rampack/blob/main/src/core/SimulationRecorder.h"
click node_players "https://github.com/pkua007/rampack/blob/main/src/core/SimulationPlayer.h"
click node_snapshot_io "https://github.com/pkua007/rampack/blob/main/src/core/io/RamsnapWriter.cpp"
click node_trajectory_io "https://github.com/pkua007/rampack/blob/main/src/core/io/RamtrjIO.cpp"

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_main,node_casino,node_preview,node_shape_preview,node_trajectory_mode,node_user toneBlue
class node_params,node_pyon,node_shape_traits,node_packing,node_lattice,node_geometry,node_interactions toneAmber
class node_simulation,node_moves,node_box_scaling,node_observables,node_analysis toneMint
class node_recorders,node_players,node_snapshot_io,node_trajectory_io toneRose
class node_file_output toneIndigo
```

## Components

### Command modes

- [Mode dispatcher](https://github.com/pkua007/rampack/blob/main/src/Main.cpp): `src/Main.cpp`
- [Monte Carlo mode](https://github.com/pkua007/rampack/blob/main/src/frontend/modes/CasinoMode.cpp): `src/frontend/modes/CasinoMode.cpp`
- [Initial preview](https://github.com/pkua007/rampack/blob/main/src/frontend/modes/PreviewMode.cpp): `src/frontend/modes/PreviewMode.cpp`
- [Shape preview](https://github.com/pkua007/rampack/blob/main/src/frontend/modes/ShapePreviewMode.cpp): `src/frontend/modes/ShapePreviewMode.cpp`
- [Trajectory mode](https://github.com/pkua007/rampack/blob/main/src/frontend/modes/TrajectoryMode.cpp): `src/frontend/modes/TrajectoryMode.cpp`

### System model

- [Parameter loading](https://github.com/pkua007/rampack/blob/main/src/frontend/IO.cpp): `src/frontend/IO.cpp`
- [PYON parser](https://github.com/pkua007/rampack/blob/main/src/pyon/Parser.cpp): `src/pyon/Parser.cpp`
- [Shape traits](https://github.com/pkua007/rampack/blob/main/src/core/ShapeTraits.h): `src/core/ShapeTraits.h`
- [Particle packing](https://github.com/pkua007/rampack/blob/main/src/core/Packing.cpp): `src/core/Packing.cpp`
- [Lattice initialization](https://github.com/pkua007/rampack/blob/main/src/core/lattice/Lattice.cpp): `src/core/lattice/Lattice.cpp`
- [Shape geometry](https://github.com/pkua007/rampack/blob/main/src/core/ShapeGeometry.cpp): `src/core/ShapeGeometry.cpp`
- [Interaction models](https://github.com/pkua007/rampack/blob/main/src/core/Interaction.cpp): `src/core/Interaction.cpp`

### Simulation and analysis

- [Simulation engine](https://github.com/pkua007/rampack/blob/main/src/core/Simulation.cpp): `src/core/Simulation.cpp`
- [Move samplers](https://github.com/pkua007/rampack/blob/main/src/core/MoveSampler.h): `src/core/MoveSampler.h`
- [Box relaxation](https://github.com/pkua007/rampack/blob/main/src/core/VolumeScaler.h): `src/core/VolumeScaler.h`
- [Observable collection](https://github.com/pkua007/rampack/blob/main/src/core/ObservablesCollector.cpp): `src/core/ObservablesCollector.cpp`
- [Analysis measures](https://github.com/pkua007/rampack/tree/main/src/core/observables): `src/core/observables`

### Trajectory and output

- [Trajectory recorders](https://github.com/pkua007/rampack/blob/main/src/core/SimulationRecorder.h): `src/core/SimulationRecorder.h`
- [Trajectory players](https://github.com/pkua007/rampack/blob/main/src/core/SimulationPlayer.h): `src/core/SimulationPlayer.h`
- [Snapshot formats](https://github.com/pkua007/rampack/blob/main/src/core/io/RamsnapWriter.cpp): `src/core/io/RamsnapWriter.cpp`
- [Trajectory formats](https://github.com/pkua007/rampack/blob/main/src/core/io/RamtrjIO.cpp): `src/core/io/RamtrjIO.cpp`

### Other components

- **CLI user**
- **Output files**

## Connections

- CLI user → Mode dispatcher: selects mode
- Mode dispatcher → Monte Carlo mode: dispatches
- Mode dispatcher → Initial preview: dispatches
- Mode dispatcher → Shape preview: dispatches
- Mode dispatcher → Trajectory mode: dispatches
- Initial preview → Parameter loading: loads parameters
- Shape preview → Parameter loading: loads input
- Shape preview → Shape traits: matches shape
- Parameter loading → PYON parser: parses input
- Parameter loading → Shape traits: builds traits
- Initial preview → Particle packing: creates packing
- Lattice initialization → Particle packing: populates
- Shape traits → Shape geometry: provides geometry
- Monte Carlo mode → Parameter loading: loads configuration
- Monte Carlo mode → Simulation engine: runs sampling
- Simulation engine → Move samplers: uses moves
- Simulation engine → Interaction models: evaluates energy
- Simulation engine → Box relaxation: scales box
- Simulation engine → Observable collection: collects measurements
- Observable collection → Analysis measures: updates measures
- Simulation engine → Trajectory recorders: records snapshots
- Initial preview → Snapshot formats: writes preview
- Shape preview → Output files: writes shape preview
- Snapshot formats → Output files: writes snapshot
- Trajectory recorders → Trajectory formats: encodes frames
- Trajectory formats → Output files: writes trajectory
- Trajectory mode → Trajectory players: operates on trajectory
- Trajectory players → Trajectory formats: reads frames
- Trajectory players → Output files: exports results