How javi786/abiotic-s-cycling-model works
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: impl_modules.hpp Module internals · run_multi_config.py Batch scripts · impl_simulation.hpp Simulation loop · output Run output
Components 23
C++ core
Compiled simulation runtime, configuration loading, reservoir state, and process modules.
- Entry point · Program startup and simulation launch.
Functional_SCycle_Code/src/main.cpp - Config load · Loads configuration into simulation parameters.
Functional_SCycle_Code/src/config.cpp - Simulation loop · Shared simulation execution boundary.
Functional_SCycle_Code/src/impl_simulation.hpp - Reservoir state · Reservoir masses and updates across Earth systems.
Functional_SCycle_Code/src/impl_reservoirs.hpp - Module registry · Enables or disables process modules for a run.
Functional_SCycle_Code/src/modules/modules.hpp - Module internals · Shared implementation layer for process modules.
Functional_SCycle_Code/src/impl_modules.hpp - Erosion · Surface-to-reservoir flux process.
Functional_SCycle_Code/src/modules/Erosion.hpp - Subduction · Deep Earth recycling flux process.
Functional_SCycle_Code/src/modules/Subduction.hpp - Volcanism · Mantle-to-surface degassing flux process.
Functional_SCycle_Code/src/modules/Volcanism.hpp - Precipitation · Ocean-atmosphere removal process.
Functional_SCycle_Code/src/modules/Precipitation.hpp - Hydrothermal · Seafloor circulation exchange process.
Functional_SCycle_Code/src/modules/HydrothermalCirculation.hpp - Comet delivery · External sulfur input boundary.
Functional_SCycle_Code/src/modules/CometDelivery.hpp - Rainout · Atmospheric removal and deposition process.
Functional_SCycle_Code/src/modules/Rainout.hpp - Convection · Circulation-driven transport process.
Functional_SCycle_Code/src/modules/Convection.hpp
Python orchestration
Experiment generation, batch execution, and analysis/plotting scripts.
- Batch scripts · Top-level batch execution and scenario runners.
Functional_SCycle_Code/run_multi_config.py - Config gen · Creates families of YAML scenario files.
Functional_SCycle_Code/generate_configs.py - Init conditions · Builds initial reservoir conditions for runs.
Functional_SCycle_Code/generate_initial_conditions.py - Seedings · Creates seeding scenario batches.
Functional_SCycle_Code/seedings.py - Analysis · Figures, summaries, and report generation pipeline.
Functional_SCycle_Code/processing/generate_report.py - Analysis tools · 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 · Main scenario contract for the compiled model.
Functional_SCycle_Code/new_config.yaml - Run output · Numerical output and graph artifacts from simulation runs.
Functional_SCycle_Code/output - Data archive · Precomputed parameter-sweep and seeding experiment batches.
Functional_SCycle_Code/Data
Connections 25
- 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.