Regional subsets#

A global 1/12° reanalysis snapshot is tens of gigabytes. Most experiments only need a region, a few levels, or both. Fortran TRACMASS cuts out a subdomain with l_subdom and imindom…jmaxdom. TRACMASS-JAX does the same with the subset of the [env.gcm] table. The subset is applied in the adapter, before any data is read, so a subset makes every window cheaper to read in proportion to its size.

Setting a subset#

[omi.gcm]
name = "glorys"
subset = { i1 = 2600, i2 = 3700, j1 = 500, j2 = 1600, k1 = 1, k2 = 2 }

tracmass.settings.setenv("omi")
grid, lazy = tracmass.new_flux("glorys", dtm_start="2010-06-01", dtm_end="2010-07-01")
grid.imt, grid.jmt, grid.km, grid.i_offset, grid.j_offset
# (1100, 1100, 2, 2600, 500)

Key

Meaning

i1, i2

0-based Python slice limits on the model’s x axis (i2 excluded)

j1, j2

0-based slice limits on the y axis

k1, k2

1-based levels, both included (k1 = 1 is the first level)

istep, jstep, kstep

optional strides

  • A key that is left out, or set to "@none", means no limit on that edge.

  • Only the keys present are written, so a partial table combines with limits set directly in gcm.<adapter>.settings["subset"].

  • For glorys the x/y limits index TRACMASS cells, that is, the grid after the NEMO halo columns have been removed.

  • new_flux applies the subset when it resolves the adapter, before the first fluxes() call. To push it in by hand, use tracmass.config.apply_gcm_subset(module).

  • The synthetic adapters (theoretical, fabboni) have no source data to cut, and ignore the subset.

Tip

For a run without vertical motion, k1 = k2 = <level> together with move_vertically = false reads a single level. That is 50 times less data per window for GLORYS.

Periodicity and edges#

An x-subset is no longer periodic, so glorys and ecco2 set iperio = 0 for it. On every non-periodic axis the outermost ring of cells counts as outside the domain. A particle that enters it stops with out_of_bounds_h. Leave at least one cell of margin between the seeding box and the subset edges. See Stopping trajectories.

Relative and absolute coordinates#

Inside a run, particles use subset-relative indices, with cell 1 being the subset’s first cell. Seeding boxes and saved trajectories use absolute indices, so files from different subsets share the full-grid frame:

  • seed.ijk(..., grid=grid) subtracts grid.i_offset / grid.j_offset from the box you pass. Pass use_subset_coordinates=True (or set it in the seed table) to give the box relative to the subset.

  • The recorder adds the offsets back to x, ia and y, ja, and stores i_offset / j_offset in the file metadata.

  • gcm.glorys.lonlat_to_xy and xy_to_lonlat always use full-grid indices.

With istep / jstep the offset is still added, but positions stay in strided-cell units, and a warning says so.

Helpers#

from tracmass import config

config.gcm_name()        # "glorys"
config.gcm_subset()      # {"i1": 2600, "i2": 3700, "istep": None, ...}