Documentation

PATMO is a one-dimensional planetary atmosphere model for coupled chemistry, transport, and radiative effects. In the current repository, the central idea is not “run one fixed solver with one fixed network,” but instead:

1. prepare a case with a reaction network, settings, profiles, fluxes, and a Fortran driver
2. use Python to generate case-specific Fortran modules into build/
3. compile the generated code with the fixed runtime modules and DLSODES solver
4. run the resulting executable and inspect the output files written by the driver

In other words, the repository is best understood as a two-stage system: Python performs the preprocessing and code generation, and Fortran performs the time integration.

Manual Case Run

If a case already has the required plain-text files in place, the shortest current workflow is:

python3 patmo -test=modern_sulfur_cycle
cd build
make
./test

The first command generates the build directory for the selected case. Compilation happens only after that, inside build/.

Spreadsheet-Assisted Workflow

The repository also contains helper scripts such as compile.sh and the case-specific scripts in tests/modern_sulfur_cycle/ and tests/archean/. In the current code, those scripts can:

• convert reaction_network.xlsx into reaction_network.ntw
• convert settings.xlsx into options.opt
• convert profile.xlsx into profile.dat
• interpolate solar_flux.xlsx into solar_flux.txt
• validate patmo_dumpDensityToFile calls in test.f90
• append default volcano options when a volcano_events.dat file is present
• invoke python3 patmo -test=<case> and enter build/

chmod +x ./compile.sh
./compile.sh
make
./test

The helper script does not replace compilation; it prepares the case and build directory, then leaves you in build/ so you can run make and then ./test.

A runnable PATMO case lives under tests/<case>/. The current code does not treat the case directory as passive data only. It treats it as the main scientific setup for the run, including the input files and the driver program that decides what to load, what to set, and what to dump.

Network File Format

The explicit network file is a structured comma-separated text format. The current parser in src_py/patmo_network.py recognizes:

• #@var:T=Tgas style variable aliases
• @format: lines that define how each reaction row is parsed
• @ghost: lines for additional ghost species
• reaction rows containing indexed reactants, products, and one rate expression

#@var:T=Tgas
@format:idx,R,R,R,P,P,P,rate
1,COS,OH,,CO2,SH,,1.1E-13*exp(-1200/T)
2,COS,O,,CO,SO,,2.1E-11*exp(-2200/T)

If options.network is left empty and options.species is provided, the Python side can also construct a reduced network directly from the KIDA database.

The current option parser lives in src_py/patmo_options.py. It supports integers, floats, booleans, comma-separated lists, and key:value dictionaries. Boolean flags are read from T and F.

Core Setup

Process Switches And Boundary Terms

The current main orchestration logic is in the repository root file patmo. That script performs the following build sequence for -test=<case>:

Generated And Copied Build Files

After compilation, the runtime behavior is centered on the generated patmo module and the case-specific test.f90 driver.

Photochemistry Path

The current photolysis workflow is split across Python preprocessing and Fortran runtime:

• src_py/patmo_photochemistry.py finds SWRI cross-sections and interpolates them onto the active log-energy metric
• the interpolated cross-section tables needed by the runtime are written into build/xsecs/
• build/xsecs/photoMetric.dat and build/xsecs/*.dat are written for the runtime side
• patmo_photo loads those files at initialization time
• patmo_photoRates integrates cross-sections against the current optical depth field and flux scaling

Process Terms In The Current ODE

The generated ODE system contains the reaction network terms and then layers additional process terms on top. In the current source, those include:

• molecular and eddy diffusion between neighboring cells
• constant-species constraints
• gravity settling for configured species
• dry deposition in the bottom layer
• lower-boundary emissions
• wet deposition
• optional water removal
• optional aerosol formation
• optional hydrogen escape
• optional volcanic gas and ash forcing

The public routines currently exposed by src_f90/patmo.f90 are the routines a case driver usually calls. The table below focuses on the ones that appear most often in the bundled cases.

Important current-state note: the main source file now defines patmo_run(dt, convergence). The hello, benchmark, and entropy examples still call an older one-argument form, so they should be read as legacy examples rather than as the most current driver template.

Output behavior is split between fixed PATMO dump routines and whatever the case-specific driver writes. The most common current output files are:

The repository currently contains five bundled case folders. They are not all at the same maturity level.

What The Current Code Already Does

• reads volcano_events.dat at initialization time when useVolcano = T
• supports GAS and ASH event rows
• maps event altitude ranges from km to the existing model grid
• adds volcanic gas source terms inside the ODE right-hand side
• adds gray ash opacity to the optical-depth field
• updates ash by source input, decay, and simple settling after each step

Current Event File Shape

# kind species t_start_s t_end_s zmin_km zmax_km source_rate
GAS SO2 0.0 5.1840e6 12.0 25.0 2.50e3
GAS H2S 0.0 5.1840e6 10.0 22.0 3.00e2
ASH ASH 0.0 1.2960e7 14.0 30.0 2.00e-8

This format reflects the current source code and the example file shipped in tests/modern_sulfur_cycle/volcano_events.dat. It should not yet be treated as a frozen interface.

• build/ is a generated workspace. It is not the source of truth; the source of truth is the case directory plus the Python and Fortran templates.
• The repository mixes current workflows with older examples. This page prioritizes the currently consistent path rather than flattening those differences away.
• When photochemistry is enabled, wavelength-based configuration is the more current path in this repository.
• The external wiki can still be useful, but this page is meant to describe the code snapshot currently present in this repo.