Curated public API

This page is the small top-level surface exposed by using AtmosTransport. Everything else remains reachable through its owning submodule, for example AtmosTransport.Preprocessing.process_day or AtmosTransport.Adjoints.cs_surface_emission_footprint.

Run a configured simulation

Symbol	Use
`run_driven_simulation(cfg)`	Canonical high-level run entry point for a TOML-derived config dictionary.
`validate_config(cfg)`	Pre-flight common config mistakes before model allocation.
`expand_data_path(path)`	Resolve `~/...` and environment-variable paths such as `$ATMOSTRANSPORT_DATA_ROOT/...`.
`expand_binary_paths(input_cfg)`	Resolve `[input]` `binary_paths` or `folder + start_date + end_date`.

julia

using TOML, AtmosTransport

# First run examples/generate_synthetic_quickstart.jl from the terminal.
cfg = TOML.parsefile("config/examples/minimal_template.toml")
ok, errors = validate_config(cfg)
ok || error(join(errors, "\n"))
model = run_driven_simulation(cfg)

Inspect transport binaries

Symbol	Use
`inspect_binary(path)`	Print header/capability information and return capability flags.
`binary_capabilities(reader)`	Summarize operator payload support for an open reader.
`has_surface(reader_or_settings)`	Query PBL surface payloads in a binary reader, or configured surface-field support in preprocessing settings.
`has_vdiff_fields(reader_or_settings)`	Query GCHP vertical-diffusion payloads in a reader, or configured support in preprocessing settings.
`TransportBinaryReader`, `TransportBinaryHeader`	Read current version-4 binaries on any supported topology.
`TransportBinaryDriver`	Runtime met driver shared by lat-lon, reduced-Gaussian, and cubed-sphere binaries.
`load_transport_window(driver, i)`	Load a runtime forcing window.
`write_transport_binary(...)`	Write synthetic or preprocessed LL/RG transport binaries.
`total_windows`, `window_dt`, `steps_per_window`, `steps_per_window_schedule`	Inspect driver timing.
`grid_type`, `horizontal_topology`	Inspect binary topology metadata.
`supports_diffusion`, `supports_convection`	Check whether a driver can support requested physics.

All three topologies share this reader, driver, and runtime-window API. Cubed-sphere preprocessing uses panel-aware streaming writer helpers; those helpers are advanced construction APIs rather than a second reader hierarchy.

Work with grids and state

Symbol	Use
`CPU`, `GPU`	Architecture tags for grids and drivers.
`earth_parameters`	Default planetary constants.
`AtmosGrid`	Combine horizontal mesh, vertical coordinate, and architecture.
`LatLonMesh`, `ReducedGaussianMesh`, `CubedSphereMesh`	Horizontal mesh constructors.
`HybridSigmaPressure`	Hybrid sigma-pressure vertical coordinate.
`nx`, `ny`, `ncells`, `nfaces`, `nlevels`, `nrings`, `cell_index`	Grid dimensions and indexing.
`cell_area`, `cell_faces`, `floattype`	Grid geometry and scalar type helpers.
`radius`, `gravity`, `reference_pressure`	Planet constants stored on a grid.
`pressure_at_interface`, `pressure_at_level`, `level_thickness`	Vertical coordinate helpers.
`CellState`, `CubedSphereState`	Store air mass and conservative `mixing ratio × carrier-air-mass` tracer fields.
`DryBasis`, `MoistBasis`	Make the air-mass basis explicit in state containers.
`allocate_face_fluxes`, `allocate_tracers`	Allocate state-compatible transport storage.
`get_tracer`, `mixing_ratio`, `total_mass`, `total_air_mass`	Common state diagnostics.
`tracer_names`, `ntracers`	Inspect tracer layout.

Configure physics and custom loops

Symbol	Use
`AdvectionWorkspace`, `DiffusionWorkspace`	Independent scratch storage for low-level advection and diffusion calls. Model constructors allocate them automatically.
`UpwindScheme`, `SlopesScheme`, `PPMScheme`, `LinRoodPPMScheme`	Common advection schemes.
`NoDiffusion`, `ImplicitVerticalDiffusion`	Diffusion operator choices.
`NoSurfaceFlux`, `SurfaceFluxOperator`, `SurfaceFluxSource`	Surface-flux operator stack.
`PerTracerFluxMap`, `flux_for`	Map emissions to named tracers.
`NoConvection`, `CMFMCConvection`, `TM5Convection`	Convection operator choices.
`NoChemistry`, `ExponentialDecay`, `CompositeChemistry`	Chemistry operator choices.
`ConstantField`, `ProfileKzField`	Simple time-varying fields used by physics operators.
`apply!`	Generic low-level operator application hook.
`TransportModel`	Low-level bundle of state, fluxes, grid, and operators.
`Simulation`, `DrivenSimulation`	Low-level harnesses for custom in-memory and window-driven loops.
`step!`, `run!`, `run_window!`	Low-level loop hooks for custom experiments.
`with_chemistry`, `with_diffusion`, `with_emissions`	Functional model-update helpers.
`build_runtime_physics_recipe`, `validate_runtime_physics_recipe`	Build and check physics recipes from config.
`build_initial_mixing_ratio`, `pack_initial_tracer_mass`	Initial-condition helpers.
`TransportTracerSpec`	Runtime tracer specification record.

Manual `DrivenSimulation` Assembly

Use this pattern when you want the runtime loop but need to own the model construction. It is the advanced path behind run_driven_simulation, without the wrapper's multi-file output, GPU adaptation, and progress plumbing.

julia

using TOML, AtmosTransport
using AtmosTransport.MetDrivers: air_mass_basis, driver_grid

# Requires the binary generated by examples/generate_synthetic_quickstart.jl.
cfg = TOML.parsefile("config/examples/minimal_template.toml")
paths = expand_binary_paths(cfg["input"])
FT = Float64

driver = TransportBinaryDriver(first(paths); FT = FT, arch = CPU())
recipe = build_runtime_physics_recipe(cfg, driver, FT)
validate_runtime_physics_recipe(recipe, driver)

grid = driver_grid(driver)
window1 = load_transport_window(driver, 1)
Basis = air_mass_basis(driver) === :dry ? DryBasis : MoistBasis
air = copy(window1.air_mass)

vmr = build_initial_mixing_ratio(
    air, grid, Dict("kind" => "uniform", "background" => 400e-6);
    surface_pressure = window1.surface_pressure,
)
co2 = pack_initial_tracer_mass(grid, air, vmr; mass_basis = Basis())

state = CellState(Basis, air; CO2 = co2)
fluxes = allocate_face_fluxes(grid.horizontal, nlevels(grid);
                              FT = FT, basis = Basis)
model = TransportModel(state, fluxes, grid, recipe.advection;
                       diffusion = recipe.diffusion,
                       convection = recipe.convection)

sim = DrivenSimulation(model, driver;
                       stop_window = min(total_windows(driver), 24),
                       chemistry = recipe.chemistry)
run_window!(sim)

The constructor validates grid and mass-basis compatibility before stepping. DrivenSimulation.step! then refreshes forcing from the driver and delegates the actual operator ordering to TransportModel.step!.

Output, regridding, and visualization

Symbol	Use
`capture_snapshot`, `write_snapshot_netcdf`	Capture and write diagnostic frames.
`SnapshotFrame`	CPU-resident tracer and air-mass snapshot, with independent signed Float64 tracer totals.
`SnapshotWriteOptions`	Select spatial output precision, compression and shuffle settings for the snapshot writer.
`build_regridder`, `apply_regridder!`	Build and apply offline conservative regridders.
`open_snapshot`	Open a written snapshot NetCDF.
`fieldview`	Extract a plottable field view from a snapshot.
`mapplot`, `movie`	Plot or animate snapshot fields when a Makie backend is loaded.

Advanced names

Internal tape records, checkpoint schedules, payload-section loaders, kernel variants, and preprocessing drivers are intentionally not exported at the top level. Advanced workflows can use explicit qualification through the owning module:

julia

AtmosTransport.MetDrivers.load_qv_pair_window!(...)
AtmosTransport.Preprocessing.process_day(...)
AtmosTransport.Adjoints.cs_surface_emission_footprint(...)

Top-level docstrings

AtmosTransport.AtmosTransport Module

julia

AtmosTransport

Offline atmospheric transport on lat-lon, reduced-Gaussian, and cubed-sphere grids.

Quick start

julia

using TOML
using AtmosTransport

# First run examples/generate_synthetic_quickstart.jl from the terminal.
cfg = TOML.parsefile("config/examples/minimal_template.toml")
ok, errors = validate_config(cfg)
ok || error(join(errors, "
"))
run_driven_simulation(cfg)

From the shell, use the same library entry point through the canonical runner:

bash

julia --project=. examples/generate_synthetic_quickstart.jl
julia --project=. scripts/run_transport.jl config/examples/minimal_template.toml

Common entry points

run_driven_simulation: load a run config, dispatch on the first transport binary's topology, run the simulation, and write snapshots.
validate_config: catch common run-config mistakes before opening binary readers or allocating model state.
inspect_binary: inspect a preprocessed transport binary header and capability flags.
open_snapshot, mapplot, movie: inspect and plot written NetCDF snapshots.
write_transport_binary: build a transport binary from in-memory test or preprocessing windows.

See the rendered getting-started docs under docs/src/getting_started/, the architecture tour in docs/src/concepts/architecture.md, and the curated API map in docs/src/api/public_api.md.

source

AtmosTransport.expand_data_path Method

julia

expand_data_path(p::AbstractString) -> String

Resolve a TOML/CLI path string by substituting $ATMOSTRANSPORT_DATA_ROOT (or ${ATMOSTRANSPORT_DATA_ROOT}) and any environment variable that is set in ENV, then running expanduser for any leading ~. Returns a plain String.

source

Curated public API ​

Run a configured simulation ​

Inspect transport binaries ​

Work with grids and state ​

Configure physics and custom loops ​

Manual DrivenSimulation Assembly ​

Output, regridding, and visualization ​

Advanced names ​

Top-level docstrings ​

Curated public API

Run a configured simulation

Inspect transport binaries

Work with grids and state

Configure physics and custom loops

Manual `DrivenSimulation` Assembly

Output, regridding, and visualization

Advanced names

Top-level docstrings