# javi786/abiotic-s-cycling-model architecture

> Architecture diagram of the GitHub repository javi786/abiotic-s-cycling-model, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/javi786/abiotic-s-cycling-model
- Repository: https://github.com/javi786/abiotic-s-cycling-model

## Overview

1. This repository is a config-driven geochemical simulation system for sulfur cycling through Earth reservoirs over deep time. The architecture is split into a compiled C++ simulation core, Python-based experiment generation, and Python postprocessing/plotting.

2. The core runtime lives under `src/`. `main.cpp` and `main.hpp` provide the executable entry point, while `config.*` handles loading YAML configuration into runtime parameters. The model operates on reservoirs such as mantle, crust, oceans, and atmosphere, with masses exchanged as fluxes over time.

3. Geochemical behavior is encapsulated as independent modules under `src/modules/`. Each module represents one process boundary, such as erosion, subduction, volcanism, precipitation, hydrothermal circulation, comet delivery, rainout, and convection. The architecture is modular: processes can be enabled or disabled by changing the module list in `modules.hpp`, which directly affects which fluxes participate in a run.

4. `impl_modules.hpp`, `impl_reservoirs.hpp`, and `impl_simulation.hpp` appear to provide the shared implementation layer for module behavior, reservoir state updates, and the simulation loop. This is the main internal boundary between model physics and the executable harness.

5. `new_config.yaml` is the primary model input. It defines numeric parameters and process settings in mass and flux units, and acts as the contract between the YAML configuration layer and the C++ runtime. The README indicates the simulation is launched with this config file and can be swapped for alternate scenarios.

6. The build/runtime boundary is centered around `make` and the produced `evolve` binary. The workflow is: compile the C++ model, then execute the binary against a YAML config. This means the simulation itself is not interpreted; the run-time is a compiled executable with external configuration.

7. Python utilities under `pytools/` and root scripts like `run_multi_config.py`, `generate_configs.py`, `generate_initial_conditions.py`, and `seedings.py` automate experiment creation. These scripts generate many YAML configurations, set up initial conditions, and run batches of simulations, so they form the repository’s parameter-sweep and ensemble layer.

8. The `processing/` directory is the analysis and visualization boundary. Scripts such as `generate_graph.py`, `generate_heatmap.py`, `generate_phaseplot.py`, `generate_distributions.py`, `generate_single_plot.py`, and `generate_report.py` consume output files and transform them into figures or summary reports. `Report.py` and `tools.py` support this analysis pipeline.

9. Simulation outputs are written to `output/` as paired `.txt` and `.dot` files alongside copied configuration files. The text files hold the numerical matrices/results, while the dot files capture graph-like structure for the run. This output format is then reused by the plotting scripts and by the archived experiment datasets.

10. The `Data/` tree is a large repository of precomputed experiment batches, organized by research question rather than by code layer. Examples include subduction-rate sweeps, GOE-related erosion studies, OWS surviving-fraction studies, and seeding experiments, each containing many config/output pairs. This makes the repo both a simulator and a results archive for parameter dependence studies.

11. The repo also includes helper documentation folders like `readme_parameters` and `readme_seedings`, which suggest the model is meant to be operated by varying reservoir/process parameters and then comparing output ensembles. The overall architecture is therefore: YAML configuration in, compiled process network simulation in the middle, batch orchestration around it, and text/graph outputs feeding the analysis pipeline.

Main entry points: [`Functional_SCycle_Code/src/impl_modules.hpp`](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/impl_modules.hpp) (Module internals), [`Functional_SCycle_Code/run_multi_config.py`](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/run_multi_config.py) (Batch scripts), [`Functional_SCycle_Code/src/impl_simulation.hpp`](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/impl_simulation.hpp) (Simulation loop), [`Functional_SCycle_Code/output`](https://github.com/javi786/abiotic-s-cycling-model/tree/master/Functional_SCycle_Code/output) (Run output)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["C++ core"]
  node_main["Entry point<br/>C++ executable<br/>[main.cpp]"]
  node_config["Config load<br/>YAML runtime config<br/>[config.cpp]"]
  node_simloop["Simulation loop<br/>run loop"]
  node_reservoirs[("Reservoir state<br/>state model")]
  node_modules["Module registry<br/>process wiring<br/>[modules.hpp]"]
  node_implmods["Module internals<br/>module base impl<br/>[impl_modules.hpp]"]
  node_erosion["Erosion<br/>process module<br/>[Erosion.hpp]"]
  node_subduction["Subduction<br/>process module<br/>[Subduction.hpp]"]
  node_volcanism["Volcanism<br/>process module<br/>[Volcanism.hpp]"]
  node_precip["Precipitation<br/>process module<br/>[Precipitation.hpp]"]
  node_hydro["Hydrothermal<br/>process module"]
  node_comet["Comet delivery<br/>process module<br/>[CometDelivery.hpp]"]
  node_rainout["Rainout<br/>process module<br/>[Rainout.hpp]"]
  node_convection["Convection<br/>process module<br/>[Convection.hpp]"]
end

subgraph group_python["Python orchestration"]
  node_scripts["Batch scripts<br/>Python orchestration"]
  node_genconfigs["Config gen<br/>Python generator"]
  node_initconds["Init conditions<br/>Python generator"]
  node_seedings["Seedings<br/>Python generator<br/>[seedings.py]"]
  node_processing["Analysis<br/>Python postprocess<br/>[generate_report.py]"]
  node_tools["Analysis tools<br/>helpers<br/>[tools.py]"]
end

subgraph group_data["Data and outputs"]
  node_newconfig["Primary config<br/>YAML input<br/>[new_config.yaml]"]
  node_output[("Run output<br/>results")]
  node_datasets[("Data archive<br/>experiment archive")]
end

node_main -->|"loads"| node_config
node_config -->|"feeds"| node_simloop
node_simloop -->|"updates"| node_reservoirs
node_modules -->|"assembles"| node_simloop
node_implmods -->|"implements"| node_modules
node_implmods -->|"supports"| node_simloop
node_erosion -->|"uses"| node_implmods
node_subduction -->|"uses"| node_implmods
node_volcanism -->|"uses"| node_implmods
node_precip -->|"uses"| node_implmods
node_hydro -->|"uses"| node_implmods
node_comet -->|"uses"| node_implmods
node_rainout -->|"uses"| node_implmods
node_convection -->|"uses"| node_implmods
node_scripts -->|"drives"| node_genconfigs
node_scripts -->|"drives"| node_initconds
node_scripts -->|"drives"| node_seedings
node_genconfigs -->|"writes"| node_newconfig
node_initconds -->|"derives"| node_newconfig
node_scripts -->|"runs"| node_output
node_processing -->|"consumes"| node_output
node_processing -->|"uses"| node_tools
node_datasets -->|"stores"| node_output
node_datasets -->|"contains"| node_newconfig
node_output -->|"feeds"| node_processing

click node_main "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/main.cpp"
click node_config "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/config.cpp"
click node_simloop "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/impl_simulation.hpp"
click node_reservoirs "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/impl_reservoirs.hpp"
click node_modules "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/modules.hpp"
click node_implmods "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/impl_modules.hpp"
click node_erosion "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Erosion.hpp"
click node_subduction "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Subduction.hpp"
click node_volcanism "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Volcanism.hpp"
click node_precip "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Precipitation.hpp"
click node_hydro "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/HydrothermalCirculation.hpp"
click node_comet "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/CometDelivery.hpp"
click node_rainout "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Rainout.hpp"
click node_convection "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Convection.hpp"
click node_scripts "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/run_multi_config.py"
click node_genconfigs "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/generate_configs.py"
click node_initconds "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/generate_initial_conditions.py"
click node_seedings "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/seedings.py"
click node_processing "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/processing/generate_report.py"
click node_tools "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/processing/tools.py"
click node_newconfig "https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/new_config.yaml"
click node_output "https://github.com/javi786/abiotic-s-cycling-model/tree/master/Functional_SCycle_Code/output"
click node_datasets "https://github.com/javi786/abiotic-s-cycling-model/tree/master/Functional_SCycle_Code/Data"

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_config,node_simloop,node_reservoirs,node_modules,node_implmods,node_erosion,node_subduction,node_volcanism,node_precip,node_hydro,node_comet,node_rainout,node_convection toneBlue
class node_scripts,node_genconfigs,node_initconds,node_seedings,node_processing,node_tools toneAmber
class node_newconfig,node_output,node_datasets toneMint
```

## Components

### C++ core

Compiled simulation runtime, configuration loading, reservoir state, and process modules.

- [Entry point](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/main.cpp): C++ executable · Program startup and simulation launch. · `Functional_SCycle_Code/src/main.cpp`
- [Config load](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/config.cpp): YAML runtime config · Loads configuration into simulation parameters. · `Functional_SCycle_Code/src/config.cpp`
- [Simulation loop](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/impl_simulation.hpp): run loop · Shared simulation execution boundary. · `Functional_SCycle_Code/src/impl_simulation.hpp`
- [Reservoir state](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/impl_reservoirs.hpp): state model · Reservoir masses and updates across Earth systems. · `Functional_SCycle_Code/src/impl_reservoirs.hpp`
- [Module registry](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/modules.hpp): process wiring · Enables or disables process modules for a run. · `Functional_SCycle_Code/src/modules/modules.hpp`
- [Module internals](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/impl_modules.hpp): module base impl · Shared implementation layer for process modules. · `Functional_SCycle_Code/src/impl_modules.hpp`
- [Erosion](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Erosion.hpp): process module · Surface-to-reservoir flux process. · `Functional_SCycle_Code/src/modules/Erosion.hpp`
- [Subduction](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Subduction.hpp): process module · Deep Earth recycling flux process. · `Functional_SCycle_Code/src/modules/Subduction.hpp`
- [Volcanism](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Volcanism.hpp): process module · Mantle-to-surface degassing flux process. · `Functional_SCycle_Code/src/modules/Volcanism.hpp`
- [Precipitation](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Precipitation.hpp): process module · Ocean-atmosphere removal process. · `Functional_SCycle_Code/src/modules/Precipitation.hpp`
- [Hydrothermal](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/HydrothermalCirculation.hpp): process module · Seafloor circulation exchange process. · `Functional_SCycle_Code/src/modules/HydrothermalCirculation.hpp`
- [Comet delivery](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/CometDelivery.hpp): process module · External sulfur input boundary. · `Functional_SCycle_Code/src/modules/CometDelivery.hpp`
- [Rainout](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Rainout.hpp): process module · Atmospheric removal and deposition process. · `Functional_SCycle_Code/src/modules/Rainout.hpp`
- [Convection](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/src/modules/Convection.hpp): process module · Circulation-driven transport process. · `Functional_SCycle_Code/src/modules/Convection.hpp`

### Python orchestration

Experiment generation, batch execution, and analysis/plotting scripts.

- [Batch scripts](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/run_multi_config.py): Python orchestration · Top-level batch execution and scenario runners. · `Functional_SCycle_Code/run_multi_config.py`
- [Config gen](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/generate_configs.py): Python generator · Creates families of YAML scenario files. · `Functional_SCycle_Code/generate_configs.py`
- [Init conditions](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/generate_initial_conditions.py): Python generator · Builds initial reservoir conditions for runs. · `Functional_SCycle_Code/generate_initial_conditions.py`
- [Seedings](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/seedings.py): Python generator · Creates seeding scenario batches. · `Functional_SCycle_Code/seedings.py`
- [Analysis](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/processing/generate_report.py): Python postprocess · Figures, summaries, and report generation pipeline. · `Functional_SCycle_Code/processing/generate_report.py`
- [Analysis tools](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/processing/tools.py): helpers · Shared plotting and report helpers. · `Functional_SCycle_Code/processing/tools.py`

### Data and outputs

Primary scenario inputs, generated outputs, and archived experiment batches.

- [Primary config](https://github.com/javi786/abiotic-s-cycling-model/blob/master/Functional_SCycle_Code/new_config.yaml): YAML input · Main scenario contract for the compiled model. · `Functional_SCycle_Code/new_config.yaml`
- [Run output](https://github.com/javi786/abiotic-s-cycling-model/tree/master/Functional_SCycle_Code/output): results · Numerical output and graph artifacts from simulation runs. · `Functional_SCycle_Code/output`
- [Data archive](https://github.com/javi786/abiotic-s-cycling-model/tree/master/Functional_SCycle_Code/Data): experiment archive · Precomputed parameter-sweep and seeding experiment batches. · `Functional_SCycle_Code/Data`

## Connections

- Entry point → Config load: loads · Executable reads YAML parameters into runtime state.
- Config load → Simulation loop: feeds · Parsed parameters drive the simulation loop.
- Simulation loop → Reservoir state: updates · Time stepping mutates reservoir masses.
- Module registry → Simulation loop: assembles · Registry determines which processes participate in a run.
- Module internals → Module registry: implements · Shared module behavior is bound into the registry.
- Module internals → Simulation loop: supports · Module implementation layer integrates with the run loop.
- Erosion → Module internals: uses · Process module uses common implementation support.
- Subduction → Module internals: uses · Process module uses common implementation support.
- Volcanism → Module internals: uses · Process module uses common implementation support.
- Precipitation → Module internals: uses · Process module uses common implementation support.
- Hydrothermal → Module internals: uses · Process module uses common implementation support.
- Comet delivery → Module internals: uses · Process module uses common implementation support.
- Rainout → Module internals: uses · Process module uses common implementation support.
- Convection → Module internals: uses · Process module uses common implementation support.
- Batch scripts → Config gen: drives · Batch runner consumes generated scenarios.
- Batch scripts → Init conditions: drives · Batch runner may generate starting states.
- Batch scripts → Seedings: drives · Batch runner orchestrates ensemble creation.
- Config gen → Primary config: writes · Scenario generators expand from the primary model contract.
- Init conditions → Primary config: derives · Initial conditions are built around the main YAML schema.
- Batch scripts → Run output: runs · Batch workflow executes simulations and collects outputs.
- Analysis → Run output: consumes · Analysis pipeline reads simulation results.
- Analysis → Analysis tools: uses · Plots and reports share helper utilities.
- Data archive → Run output: stores · Archived experiments contain output files in the same format.
- Data archive → Primary config: contains · Archived experiments include many scenario configs.
- Run output → Analysis: feeds · Generated outputs are the input to downstream analysis.