Module `particles`

This IGM module implements a particle tracking routine, which computes the trajectories of virtual particles advected by the ice flow. The routine operates in real-time during the forward model run, and a large number of particles can be processed efficiently thanks to the parallel implementation with TensorFlow. The routine includes particle seeding (by default in the accumulation area at regular intervals, though this can be customized) and tracking (advection by the velocity field in 3D).

State variables

Reads: U, V, W, thk

Writes: particle

Tracking methods

Two tracking implementations are available, selected via tracking.method:

simple: Horizontal and vertical directions are treated differently:
In the horizontal plane, particles are advected using the horizontal velocity field (interpolated bi-linearly at the particle positions).
In the vertical direction, particles are tracked along the ice column, scaled between 0 (at the bed) and 1 (at the surface). Particles are initialized at relative height 1 (on the surface). The evolution of the particle's position within the ice column over time is computed from the surface mass balance: the particle deepens when SMB is positive and re-emerges when SMB is negative.
3d: Uses the vertical velocity W computed by the vertical_velocity sub-module of iceflow, which integrates the divergence of the horizontal velocity to enable full 3D particle tracking. To activate it, set iceflow.vertical_velocity.enabled: true in the iceflow configuration.

The default tracking.method is 3d.

Seeding

Seeding occurs in the accumulation area at intervals of seeding.frequency years, with spatial density controlled by seeding.density (0.2 = one seed every 5 grid cells). To use a custom seeding strategy (e.g. near rock walls or nunataks), redefine the seeding_particles() function in a particles.py file in the working directory — igm_run will override the built-in implementation with yours.

Output

Particle positions are saved at the interval set by processes.time.save. Trajectories are written to a trajectories/ folder as files named traj-TIME.csv with the columns:

ID,  state.xpos,  state.ypos,  state.zpos, state.rhpos,  state.tpos, state.englt

Particle-to-grid mapping

Particle-borne quantities (e.g. weight, added through output.add_fields) can be scattered back onto the 2D grid. The scatter is a nearest-cell binning: each particle's value is accumulated in the grid cell that contains it (no bilinear spreading to neighbouring cells).

Interpolation and writing backends

The velocity interpolation at the particle positions is done by default in pure TensorFlow (tracking.library: tensorflow), which runs on CPU and GPU and needs no extra dependency. Two optional accelerated kernels are available for very large particle populations on NVIDIA GPUs; both require additional software that is not installed with IGM:

Parameter	Option	Description
`tracking.library`	`tensorflow` (default)	Pure TensorFlow interpolation, runs on CPU or GPU
	`cuda`	Optional: compiled TensorFlow custom op (`interpolate_2d.so`), NVIDIA GPU; must be compiled from the sources in `igm/processes/particles/interpolate_2d/`
	`cupy`	Optional: Numba CUDA kernel, requires `cupy` and `numba`
`output.library`	`numpy` (default)	Writes CSV files (`output.format` is ignored)
	`cudf`	RAPIDS GPU dataframes, writes `csv`, `feather` or `parquet` (`output.format`)

Parameters

Default configuration file (particles.yaml):

particles:
  seeding:
    method: accumulation
    frequency: 50.0
    density: 0.2
    tlast_init: -1.0e+5000
    height: 20.0
  tracking:
    method: 3d
    library: tensorflow
  removal:
    method: ""
  output:
    library: numpy
    add_topography: True
    format: csv
    add_fields:
      - weight
      - englt
      - velmag


  # tracking_method: 3d
  # frequency_seeding: 50
  # density_seeding: 0.2
  # tlast_seeding_init: -1.0e+5000
  # write_trajectories: True
  # add_topography: True
  # computation_library: tensorflow
  # writing_library: numpy
  # output_format: csv
  # fields:
  #   - weight
  #   - englt
  #   - velmag
  # seeding_method: accumulation

Structure of the parameters:

particles
├── seeding
│   └── ...
├── tracking
│   └── ...
├── removal
│   └── ...
└── output
    └── ...

Description of the parameters:

seeding

Name	Description	Default value	Units
`seeding.method`	Seeding method: `accumulation` (seed at the surface of the accumulation area, where thk > 1 m and smb > 0, every `frequency` years) or `all` (seed the whole ice volume in layers spaced by `height` at the first time step, then at the surface wherever the cumulated accumulation exceeds `height`).	accumulation	—
`seeding.frequency`	Frequency of seeding.	50.0	y
`seeding.density`	Density of seeding (1 means we seed all pixels, 0.2 means we seed each 5 grid cell, etc.)	0.2	—
`seeding.tlast_init`	Initialize the date of last seeding. If default value, the seeding will start the first year of the simulation. Changing this value allows to defer it	-inf	y
`seeding.height`	Method `all` only: vertical spacing of the seeded layers, and cumulated accumulation (m ice eq.) that triggers a new surface seeding.	20.0	m

tracking

Name	Description	Default value	Units
`tracking.method`	Method for tracking particles (3d or simple).	3d	—
`tracking.library`	Library used to interpolate velocities at particle positions: `tensorflow` (default, portable, CPU or GPU), `cuda` (compiled TensorFlow custom op, NVIDIA GPU), or `cupy` (Numba CUDA kernel, requires `cupy` and `numba`).	tensorflow	—

removal

Name	Description	Default value	Units
`removal.method`	Particle removal: empty string (none) or `ablation` (remove particles that have returned to the ice surface, i.e. relative height r = 1).		—

output

Name	Description	Default value	Units
`output.library`	Library used to write particle files: `numpy` (default, CSV only) or `cudf` (RAPIDS, GPU; supports the formats set by `format`).	numpy	—
`output.add_topography`	Add topography when writing particles.	True	—
`output.format`	Output file format with `library: cudf`: `csv`, `feather`, or `parquet` (ignored with `numpy`, which always writes CSV).	csv	—
`output.add_fields`	Extra particle fields to track and write: `weight`, `englt` (englacial time, yr), `velmag` (3D speed, m yr^{-1}).	['weight', 'englt', 'velmag']	—

Contributors: Guillaume Jouvet, Claire-Mathile Stücki, Brandon Finley.

Module particles