# Main modules

A tour of the `tracmass` package, in the spirit of the Fortran
documentation's *Main modules* chapter. The [API reference](../api/index.md)
has the full signatures and docstrings.

```text
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](main_program.md).

## `tracmass.config`

Loads the [settings files](../configuration/settings.md#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](../tutorials/stopping.md)), `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](../tutorials/seeding.md).

## `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](integrators.md).

## `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](schemes.md).

## `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](grid.md) and [GCM adapters](adapters.md).

## `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](../output.md).

## `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](../tools/monitoring.md).

## `tracmass.trajs`

Coordinate conversion for any grid with `lon`/`lat` arrays. See
[Coordinates](../tools/coordinates.md).