# 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

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

```python
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](stopping.md#leaving-the-domain).

## 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

```python
from tracmass import config

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