tracmass.seed#

tracmass.seed.ijk(i1, i2, j1, j2, k1, k2, grid=None, use_subset_coordinates=False, **sub_kw)[source]#

Seed particles in every cell of an i/j/k index box.

Parameters:

  • i1 (int) – 1-based TRACMASS cell index ranges (inclusive). By default i and j are absolute, full-grid indices – the frame of saved trajectories – whatever subset the grid was loaded with.

  • i2 (int) – 1-based TRACMASS cell index ranges (inclusive). By default i and j are absolute, full-grid indices – the frame of saved trajectories – whatever subset the grid was loaded with.

  • j1 (int) – 1-based TRACMASS cell index ranges (inclusive). By default i and j are absolute, full-grid indices – the frame of saved trajectories – whatever subset the grid was loaded with.

  • j2 (int) – 1-based TRACMASS cell index ranges (inclusive). By default i and j are absolute, full-grid indices – the frame of saved trajectories – whatever subset the grid was loaded with.

  • k1 (int) – 1-based TRACMASS cell index ranges (inclusive). By default i and j are absolute, full-grid indices – the frame of saved trajectories – whatever subset the grid was loaded with.

  • k2 (int) – 1-based TRACMASS cell index ranges (inclusive). By default i and j are absolute, full-grid indices – the frame of saved trajectories – whatever subset the grid was loaded with.

  • grid (GridFields or None, optional) – The run grid. Its i_offset / j_offset convert absolute indices to the subset-relative ones particles use while integrating, cells outside the grid are dropped, and land cells (kmt == 0) are skipped. Without a grid the indices are used as given (no offset, no masking).

  • use_subset_coordinates (bool, optional) – If True, i/j are already subset-relative (cell 1 is the subset’s first cell) and no offset is applied. Default False. From settings: use_subset_coordinates in [env.seed].

  • **sub_kw – Sub-cell options (sub_dist, i_sub_num, …).

Returns:

ParticleState – Particles in subset-relative indices.

Raises:

ValueError – If grid is given and no cell of the box lies inside it.

Return type:

ParticleState

Examples

>>> # glorys subset i1 = 2600, j1 = 500: absolute cells 2611..2621
>>> state = seed.ijk(2611, 2621, 511, 521, 1, 1, grid=grid)
>>> # the same cells in subset coordinates
>>> state = seed.ijk(11, 21, 11, 21, 1, 1, grid=grid,
...                  use_subset_coordinates=True)
tracmass.seed.from_settings(grid=None, cfg=None)[source]#

Seed particles as described by the [env.seed] settings table.

Parameters:

  • grid (GridFields or None, optional) – Passed on to the seeding function (ijk uses it to skip land).

  • cfg (mapping or None, optional) – The seed table. Default: seed from the active tracmass.config.settings environment.

Returns:

ParticleState

Raises:

ValueError – If there is no seed table, or its approach is not a key of SETTINGS_APPROACHES.

Return type:

ParticleState

Notes

The table names an approach and gives its arguments in a box sub-table; every other key (sub_dist, i_sub_num, …) is passed on as a sub-cell seeding option:

[omi.seed]
approach = "ijk"
sub_dist = "rect_xyz"
i_sub_num = 40
j_sub_num = 40
k_sub_num = 1
box = { i1 = 10, i2 = 20, j1 = 10, j2 = 20, k1 = 1, k2 = 1 }

i/j/k in box are 1-based TRACMASS cell indices, with i/j absolute (full-grid) unless the table sets use_subset_coordinates = true (see ijk()). With approach = "latlon_box" the box is geographic instead (see latlon_box()):

box = { lat1 = -64, lat2 = -62, lon1 = -70, lon2 = -68, k1 = 1, k2 = 1 }

and approach = "latlon_point" takes lat, lon, dlat (and optionally dlon, k1, k2). approach = "latlon_list" seeds one particle per point, from a table file (seed_file = "points.csv" with lat/lon columns) or inline lat = [...] / lon = [...] lists (see latlon_list()).

Examples

>>> tracmass.settings.setenv("omi")
>>> state = seed.from_settings(grid)
tracmass.seed.latlon_box(lat1, lat2, lon1, lon2, kpos=1, grid=None, *, k1=None, k2=None, gcm=None, **sub_kw)[source]#

Seed every ocean cell whose centre lies in a lat/lon box.

Parameters:

  • lat1 (float) – Latitude range in degrees (inclusive).

  • lat2 (float) – Latitude range in degrees (inclusive).

  • lon1 (float) – Longitude range in degrees (inclusive), eastward from lon1 to lon2: any longitude convention works, and lon1 > lon2 gives a box across the dateline (e.g. 170 → -170).

  • lon2 (float) – Longitude range in degrees (inclusive), eastward from lon1 to lon2: any longitude convention works, and lon1 > lon2 gives a box across the dateline (e.g. 170 → -170).

  • kpos (int, optional) – 1-based level to seed when k1 is not given. Default 1.

  • grid (GridFields) – The run grid (required): selects the window of the GCM’s lon/lat (for a subset) and its kmt masks out land.

  • k1 (int or None, optional) – 1-based level range (inclusive), as in ijk(); k2 defaults to k1. Levels below the local bottom (k > kmt) are skipped.

  • k2 (int or None, optional) – 1-based level range (inclusive), as in ijk(); k2 defaults to k1. Levels below the local bottom (k > kmt) are skipped.

  • gcm (str or None, optional) – Adapter providing lonlat_grid. Default: [env.gcm] name.

  • **sub_kw – Sub-cell options (sub_dist, i_sub_num, …), see ijk().

Returns:

ParticleState

Raises:

ValueError – If grid is missing, the GCM has no geographic grid, or the box contains no ocean cell of the grid.

Return type:

ParticleState

Examples

>>> state = seed.latlon_box(-64, -62, -70, -68, grid=grid, k1=1,
...                         i_sub_num=10, j_sub_num=10)

From settings:

[omi.seed]
approach = "latlon_box"
i_sub_num = 10
box = { lat1 = -64, lat2 = -62, lon1 = -70, lon2 = -68, k1 = 1, k2 = 1 }
tracmass.seed.latlon_point(lat, lon, dlat, dlon=None, kpos=1, grid=None, **kw)[source]#

Seed the ocean cells within dlat / dlon degrees of a point.

A latlon_box() of lat ± dlat by lon ± dlon (dlon defaults to dlat); other keywords (k1, k2, gcm, sub-cell options) are passed on.

Parameters:
Return type:

ParticleState

tracmass.seed.latlon_list(df=None, grid=None, *, seed_file=None, lat=None, lon=None, lat_col='lat', lon_col='lon', k_col='k', kpos=1, gcm=None, **_ignored)[source]#

Seed one particle at each lat/lon position of a table.

Each row becomes a particle at the exact fractional grid position of its point (not snapped to the cell centre), found with tracmass.trajs.coords.lonlat_to_xy() on the adapter’s lonlat_grid(grid). A point on land (or outside the grid) is moved to the centre of the nearest ocean cell.

Parameters:

  • df (pd.DataFrame or str or None) – Table with lat_col / lon_col columns (and optionally k_col, the 1-based level of each point). A str is read as a file, like seed_file.

  • grid (GridFields) – The run grid (required): selects the GCM’s lon/lat window (for a subset) and its kmt masks out land.

  • seed_file (str or None, optional) – Path to a .csv or .parquet file to read df from.

  • lat (list of float or None, optional) – Positions given directly instead of df / seed_file.

  • lon (list of float or None, optional) – Positions given directly instead of df / seed_file.

  • lat_col (str, optional) – Column names. Defaults "lat", "lon", "k".

  • lon_col (str, optional) – Column names. Defaults "lat", "lon", "k".

  • k_col (str, optional) – Column names. Defaults "lat", "lon", "k".

  • kpos (int, optional) – 1-based level for every particle when there is no k_col column. Default 1.

  • gcm (str or None, optional) – Adapter providing lonlat_grid. Default: [env.gcm] name.

  • **_ignored – Sub-cell options from a settings table are accepted and ignored: each point is seeded exactly once.

Returns:

ParticleState – Particles in subset-relative coordinates, in row order (rows whose level lies below the local bottom, k > kmt, are dropped).

Raises:

ValueError – If grid or the positions are missing, a column is absent, or no point lies in an ocean cell deep enough for its level.

Return type:

ParticleState

Examples

>>> df = pd.DataFrame({"lat": [-63.0, -62.5], "lon": [-69.0, -68.2]})
>>> state = seed.latlon_list(df, grid=grid)

From settings:

[omi.seed]
approach = "latlon_list"
seed_file = "stations.csv"  # columns lat, lon (and optionally k)

or with the positions inline:

[omi.seed]
approach = "latlon_list"
lat = [-63.0, -62.5]
lon = [-69.0, -68.2]
tracmass.seed.SETTINGS_APPROACHES = {'ijk': <function ijk>, 'latlon_box': <function latlon_box>, 'latlon_list': <function latlon_list>, 'latlon_point': <function latlon_point>}#

Seeding approaches usable from a [env.seed] settings table, by name. Each takes the table’s box entries and sub-cell keys as keyword arguments plus grid=.

tracmass.seed.mask(mask, kpos=1, **sub_kw)[source]#

Seed particles at every True cell of a raw (j, i)-ordered mask.

mask must be in the grid’s native row-major orientation — the same orientation grid fields come in straight from xarray/NetCDF (e.g. seagrid.ecco2.grid_definition().kmt.values or seagrid.glorys’s raw kmt): latitude (j) first, longitude (i) second. This is the opposite of GridFields.kmt’s (imt, jmt) convention — do not pass grid.kmt here directly; use ijk() for that.

Parameters:

  • mask (np.ndarray) – Boolean array, shape (jmt, imt) for a 2-D mask or (jmt, imt, kmt) for a 3-D one. True marks a cell to seed.

  • kpos (int, optional) – 1-based vertical level for seeded particles when mask is 2-D. Ignored (and superseded by the mask’s own k-axis) when mask is 3-D. Default 1.

  • **sub_kw – Forwarded to _expand_sub() (e.g. sub_dist, i_sub_num).

Returns:

ParticleState – One particle per True cell, placed at the cell centre, at level kpos (2-D mask) or the cell’s own k (3-D mask).

Warns:

UserWarning – If mask.shape[0] > mask.shape[1] (more j than i). Ocean grids are normally near-global in longitude but span at most the poles in latitude, so jmt > imt usually means mask was passed already transposed to (imt, jmt) instead of the expected raw (jmt, imt).

Return type:

ParticleState

Examples

>>> kmt = seagrid.ecco2.grid_definition().kmt.values  # (jmt, imt)
>>> state = seed.mask(kmt > 0, kpos=1)