Main modules

A tour of the tracmass package, in the spirit of the Fortran documentation’s Main modules chapter. The API reference has the full signatures and docstrings.

src/tracmass/
  __init__.py            top-level API, free_device_memory()
  driver.py              run(): settings-driven one-call entry point
  config.py              Dynaconf settings (tracmass.toml), subset helpers
  runsetup.py            settings resolution for the integrators, run metadata
  particle.py            ParticleState, reason codes, ParticleRecorder
  seed.py                seeding helpers
  output.py              load(), output file names
  monitoring.py          RunMonitor (print / log / rich)
  verbose.py             set_verbose(), timed() debug logging
  integrate/
    full_grid.py         steady_state, time_dependent, the compiled window loop
    streaming.py         time_dependent_patched, time_dependent_streaming
  advection_scheme/
    full_grid.py         piecewise, analytical (kernels on the whole grid)
    stencil.py           piecewise_local (patches), piecewise_stencil (stencils)
  gcm/
    flux_grid.py         GridFields, LazyFluxFields, FluxFields, new_grid,
                         new_flux, update_flux, extract_stencil, edge_mask
    theoretical.py       synthetic double gyre
    fabboni.py           Fabboni analytical case
    glorys.py, ecco2.py, scrippsgog.py   reanalysis adapters
  seagrid/
    glorys.py, ecco2.py, scrippsgog.py   download / cache / open raw data
    coast.py             landmask, distance_to_land
  trajs/
    coords.py            xy_to_lonlat, lonlat_to_xy for any grid

tracmass.driver

run() activates a settings environment, builds the grid and the flux buffer, seeds and calls the integrator. INTEGRATORS maps the names allowed in the integrator setting to functions. Counterpart of TRACMASS.F90. See Main program.

tracmass.config

Loads the settings files into tracmass.settings (also available as tracmass.config.settings). Helpers: move_vertically(), n_particle_batches(), gcm_name(), gcm_subset() and apply_gcm_subset(module). Counterpart of init_namelist in mod_init.F90.

tracmass.runsetup

Everything that turns “argument not given” into a value from the settings: manage_run_io (the decorator that builds and closes the monitor and recorder), resolve_no_wflux, resolve_n_windows, resolve_rampup, resolve_seed_freq, resolve_timax, and run_metadata, which writes the tracmass.run metadata into each output file.

tracmass.particle

ParticleState is a NamedTuple of arrays, one entry per particle (a struct of arrays, where Fortran has an array of trajectory structs):

Field	Description
x, y, z	Position in grid-cell units
ia, ja, ka	1-based cell indices
tt	Elapsed time, s
ts	Normalised time, tt / timestep
t0	Release time, s
subvol	Transport carried by the particle
niter	Sub-cycle counter
active	Still being integrated
reason	Why it stopped (0 while active or paused)

The module also defines the REASON_* codes (see Stopping trajectories), ParticleRecorder for streaming output to Parquet, and write_trajectories_parquet for writing one state. Counterpart of mod_vars.F90 (trajectory variables) and mod_write.F90.

tracmass.seed

ijk, mask, from_df, from_df_xyz, latlon_box, latlon_point, latlon_list and from_settings. Counterpart of mod_seed.F90. See Seeding.

tracmass.integrate

The window loop (_run_window, a lax.while_loop around the kernel), the sub-step cap and snapping (_substep_cap, _snap_to_substep), particle batching (_integrate_batched), resuming paused particles (_resume_paused), and the four public integrators. Counterpart of mod_loop.F90. See Integrators.

tracmass.advection_scheme

Kernel factories. piecewise(grid) and analytical(grid, tseas) close over a whole-grid GridFields. piecewise_local(imt, jmt, km, iperio) takes the patch geometry as an argument, and piecewise_stencil(grid) works on per-particle stencils. Counterpart of mod_pos_tstep.F90 and mod_pos_tanalytical.F90. See Advection schemes.

tracmass.gcm

The grid and flux containers and their constructors (flux_grid.py), and the adapters. Counterpart of mod_getfile.F90, mod_swap.F90 and the projects’ setup_grid.F90 and read_field.F90. See Grid and flux data and GCM adapters.

tracmass.seagrid

Raw data access for each reanalysis: open_dataset(dtm), grid_definition(), retrieve(dtm), plus landmask(k) and distance_to_land(k).

tracmass.output

load() finds and reads trajectory files, and the helpers that name them (output_stem, output_folder, output_filename). See Output.

tracmass.monitoring and tracmass.verbose

RunMonitor prints per-window progress (counterpart of mod_print.F90). set_verbose() turns on time-stamped debug logging of every stage. See Monitoring.

tracmass.trajs

Coordinate conversion for any grid with lon/lat arrays. See Coordinates.