Output and visualization API

Output defines snapshot capture and persistence. Visualization provides topology-aware field views and optional Makie rendering for those snapshots.

Output

AtmosTransport.Output Module

Output

Topology-aware diagnostic output for AtmosTransport runtime products.

This module owns the public NetCDF output contract. Runtime code should capture model state with capture_snapshot and write files with write_snapshot_netcdf instead of defining ad-hoc NetCDF layouts in runner code.

The writer is intentionally topology-dispatched:

• LatLonMesh writes regular CF lon/lat coordinates.

• ReducedGaussianMesh writes native cell-indexed diagnostics plus a legacy lon/lat raster view for current debug plots.

• CubedSphereMesh writes panel-native diagnostics with GEOS-style lons, lats, corner_lons, corner_lats, cell_area, and cubed_sphere metadata so Panoply and downstream tools have enough geometry context to render C-grid snapshots.

New topologies should add methods for the small internal schema/diagnostic functions in this folder; they should not special-case the runner.

source

AtmosTransport.Output.SnapshotFrame Type

SnapshotFrame

CPU-resident snapshot of one model state at one output time.

air_mass and each entry in tracers keep the topology-native storage shape:

• LL: (lon, lat, lev)

• RG: (cell, lev)

• CS: NTuple{6, Array{T, 3}} with panel interiors (Xdim, Ydim, lev)

Tracer arrays store the model's conservative χ × carrier-air-mass quantity, not mixing ratio or physical kg species. Derived VMR and column diagnostics are computed by write_snapshot_netcdf. tracer_total_mass stores a compensated Float64 sum of that conservative quantity for every tracer. It is kept separately so Float32 visualization payloads cannot degrade global signed mass diagnostics through cancellation or output conversion.

Snapshot storage must be CPU-resident. Use capture_snapshot for model state on any backend; it strips cubed-sphere halos and copies device arrays to the host before constructing the frame.

source

AtmosTransport.Output.SnapshotWriteOptions Type

SnapshotWriteOptions(; float_type=Float32, deflate_level=0, shuffle=true)

Options controlling NetCDF snapshot output.

• float_type is the on-disk type for heavy diagnostic variables.

• deflate_level is the NetCDF compression level for heavy payload variables: 0 disables compression, 1 is fast/light, and 9 is maximum compression.

• shuffle enables the NetCDF shuffle filter when compression is active.

source

AtmosTransport.Output.capture_snapshot Method

capture_snapshot(model; time_hours=0, halo_width=0) -> SnapshotFrame

Capture full air-mass and conservative tracer-storage fields from a TransportModel.

The result is CPU-resident and topology-native. For cubed-sphere states, halo_width strips panel halos before writing. GPU-backed arrays are copied to host memory by Array(...).

source

AtmosTransport.Output.column_mass_per_area Method

column_mass_per_area(field, mesh)

Vertically integrate per-cell mass and divide by horizontal cell area.

source

AtmosTransport.Output.column_mean_mixing_ratio Method

column_mean_mixing_ratio(air_mass, tracer_storage)

Compute the air-mass-weighted vertical mean mixing ratio for one snapshot field.

The returned shape is topology-native horizontal storage:

• LL: (lon, lat)

• RG: (cell,)

• CS: NTuple{6, Matrix{Float64}}

source

AtmosTransport.Output.layer_mass_per_area Method

layer_mass_per_area(field, mesh)

Convert per-cell layer mass [kg cell⁻¹] to mass per horizontal area [kg m⁻²] without changing topology-native storage.

source

AtmosTransport.Output.runtime_output_spec Method

runtime_output_spec(output_cfg, FT; default_path="", default_cap_hours=8760, fallback_hours=[])

Parse the run-time output contract from TOML-compatible [output] settings.

Preferred keys are path, cadence_hours or hours, and split = "single" | "daily". Legacy snapshot_file, snapshot_hours, and snapshot_interval_hours remain accepted.

source

AtmosTransport.Output.write_snapshot_binary Method

write_snapshot_binary(path, frames, grid; mass_basis=:dry, options=SnapshotWriteOptions())

Write CS snapshots to a self-describing binary file. Skips NetCDF library overhead entirely; pair with scripts/postprocess/binary_to_netcdf.jl for the offline conversion. Throws if grid.horizontal is not a CubedSphereMesh.

source

AtmosTransport.Output.write_snapshot_netcdf Method

write_snapshot_netcdf(path, frames, grid; mass_basis=:dry, options=SnapshotWriteOptions(),
                      fields=output_field_spec())

Write topology-aware runtime snapshots to NetCDF.

The output contains full per-level VMR fields, stored air mass, layer mass-per-area diagnostics, column air mass per area, and tracer column means. Reduced-Gaussian files also carry a legacy lon/lat raster view for quick plots. Cubed-sphere files carry panel lon/lat coordinates and a cubed_sphere grid-mapping variable modeled after GEOS-Chem diagnostics.

source

Visualization

AtmosTransport.Visualization Module

Visualization

Topology-aware snapshot visualization support.

This module owns the lightweight data layer only: snapshot discovery, field views, unit scaling, and topology-aware rasterization for quick maps. Makie plotting lives in AtmosTransportMakieExt so the model/runtime does not pay a plotting load cost unless a Makie backend is explicitly loaded.

source

AtmosTransport.Visualization.CubedSphereSnapshotTopology Type

CubedSphereSnapshotTopology(Nc, nlevel, panel_convention)

Cubed-sphere snapshot geometry. Values are stored as (Xdim, Ydim, nf) for a single horizontal field, with nf == 6.

source

AtmosTransport.Visualization.HorizontalField Type

HorizontalField

A topology-native horizontal field view from one snapshot time.

For LL/RG snapshots values is a (lon, lat) matrix. For CS snapshots it is a (Xdim, Ydim, nf) array until rasterized or plotted natively.

source

AtmosTransport.Visualization.LatLonSnapshotTopology Type

LatLonSnapshotTopology(lons, lats; grid_type=:latlon)

Regular lon-lat snapshot geometry. Values are stored as (lon, lat).

source

AtmosTransport.Visualization.PlotSpec Type

PlotSpec(variable; transform=:column_mean, level=nothing, title=nothing, unit=:native)

One panel specification for multi-panel plots and movies.

source

AtmosTransport.Visualization.RasterField Type

RasterField

Regular lon-lat representation used by fast debug maps and movies.

source

AtmosTransport.Visualization.ReducedGaussianSnapshotTopology Type

ReducedGaussianSnapshotTopology(lons, lats, nrings, regridding)

Reduced-Gaussian snapshot geometry after the current writer's ring-aware nearest-neighbor projection onto a regular lon-lat diagnostic grid.

source

AtmosTransport.Visualization.SnapshotDataset Type

SnapshotDataset

Metadata for an AtmosTransport NetCDF snapshot file.

The object intentionally does not hold an open NetCDF handle. Field reads open the file briefly and close it immediately, which is robust for scripts, animations, and long debugging sessions.

source

AtmosTransport.Visualization.SnapshotRegridCache Type

SnapshotRegridCache()

Cache expensive topology-to-raster geometry, especially CS→LL conservative regridders, across frames in snapshot grids and movies.

source

AtmosTransport.Visualization.as_raster Method

as_raster(field; resolution=(360, 181), cache=SnapshotRegridCache())

Return a regular lon-lat RasterField for fast plotting.

LL and current RG diagnostic snapshots are already raster-like. CS fields are conservatively regridded to lon-lat and reuse cache across frames.

source

AtmosTransport.Visualization.catrine_map_curtains Method

catrine_map_curtains(at_path, gc_dir; kwargs...) -> NamedTuple

Create the CATRINE AtmosTransport/GEOS-Chem column-map and pressure-curtain comparison product. Output is controlled by the out_dir keyword. This specialized visualization requires a Makie backend.

source

AtmosTransport.Visualization.catrine_map_curtains_3way Method

catrine_map_curtains_3way(at_geos_path, at_era5_path, gc_dir; kwargs...) -> NamedTuple

Compare GEOS-Chem with AtmosTransport runs driven by GEOS-IT and ERA5 in one CATRINE column-map and pressure-curtain product. Output is controlled by the out_dir keyword. This specialized visualization requires a Makie backend.

source

AtmosTransport.Visualization.fieldview Method

fieldview(snapshot, variable; transform=:column_mean, time=1, level=nothing, unit=:native)

Load one topology-native horizontal field from a snapshot file.

time may be a one-based frame index or a snapshot hour. For CS snapshots, transform may be :column_mean, :column_sum, :level_slice, or :surface_slice. LL/RG snapshots currently carry column means only.

source

AtmosTransport.Visualization.mapplot! Method

mapplot!(axis, field; kwargs...)

Render a topology-aware field into an existing Makie axis and return the plot object. A Makie backend must be loaded.

source

AtmosTransport.Visualization.mapplot Method

mapplot(field; kwargs...) -> Figure

Render one topology-aware HorizontalField as a lon-lat map. Load a Makie backend such as CairoMakie before calling this function. Cubed-sphere fields are conservatively rasterized and may reuse a SnapshotRegridCache.

source

AtmosTransport.Visualization.movie Method

movie(snapshot, variable, output_path; kwargs...) -> String

Render one snapshot variable to an animation and return output_path. A Makie backend must be loaded.

source

AtmosTransport.Visualization.movie_grid Method

movie_grid(snapshot, specs, output_path; kwargs...) -> String

Render several PlotSpec panels to one animation and return output_path. A Makie backend must be loaded.

source

AtmosTransport.Visualization.open_snapshot Method

open_snapshot(path) -> SnapshotDataset

Read snapshot metadata and infer its topology.

Supported formats are the current AtmosTransport LL/RG column-mean snapshots and CS panel snapshots written by run_driven_simulation.

source

AtmosTransport.Visualization.robust_colorrange Method

robust_colorrange(fields; trim=(0.01, 0.99))

Compute a robust color range from one or more fields by ignoring non-finite values and clipping to quantiles.

source

AtmosTransport.Visualization.snapshot_grid Method

snapshot_grid(snapshot, variable; kwargs...) -> Figure

Render one snapshot variable at several output times in a shared figure. A Makie backend must be loaded.

source