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).
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 trajectory/ folder as files named traj-TIME.csv with the columns:

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

The tracking computation can use tensorflow (default) or a CUDA-based cupy/numba backend (tracking.library). Output writing can use numpy (default) or cudf (output.library), which also supports parquet 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`	Method for seeding particles (accumulation or all).	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`	Height of the seeding layer in the method full.	20.0	—

tracking

Name	Description	Default value	Units
`tracking.method`	Method for tracking particles (3d or simple).	3d	—
`tracking.library`	Library used for tracking (cuda, tensorflow, etc.).	tensorflow	—

removal

Name	Description	Default value	Units
`removal.method`	Method for removing particles (ablation, etc.).		—

output

Name	Description	Default value	Units
`output.library`	Library used for outputting particles (numpy, pyvista, etc.).	numpy	—
`output.add_topography`	Add topography when writing particles.	True	—
`output.format`	Type of output format for particles (csv, parquet).	csv	—
`output.add_fields`	List of fields to write in the output file (englt, velbar, weight).	['weight', 'englt', 'velmag']	—

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

Module particles