slim4.particles2d

Particles2D

Classes

class slim4.particles2d.ParticleArrays2d

This class holds the particle data for 2D particles. It is designed to be used with the Tracker2d class, and to be able to store a large number of particles efficiently on the GPU. It also provides methods to add, remove and sort particles, as well as to compute the concentration field on the mesh. The particles are stored in a structure of arrays format, with the position of the particles in local coordinates (xi, eta) within each triangle, and the triangle indices and boundary types of the particles. The class also allows to store additional scalar attributes for the particles, which can be used to compute the concentration field or to export the particles. The class also keeps track of the random seed used for the random number generator, which is used for the random walk of the particles.

Properties

random_seed: int — random seed
mesh: slim2d.Mesh — mesh
size: int — size

Constructor

__init__(mesh, attr_names=[], initial_capacity=0, random_seed=0)

Create a new slim4::particles2d::ParticleArrays2d with the given capacity

Parameters

mesh: slim2d.Mesh — The 2D mesh
attr_names: List[str] — additional scalar attributes
initial_capacity: int — capacity
random_seed: int — random_seed (if 0 time will be used)

Methods

add_particles(position, attrs={})

Add particles to the slim4::particles2d::ParticleArrays2d

Parameters

position: NDArray[np.float64] — The 2D position of the particles (2, n_particles)

attrs: Dict[str,NDArray[np.float64]] — additional scalar attributes

Returns

n_added: int — the number of particles added

sort(): Sort the particles by triangle, and putting the deleted particles at the end (for better performance)

remove_inactive()

Remove inactive particles (settled, leaving, etc.) from the slim4::particles2d::ParticleArrays2d. This also sorts the particles.

Returns

removed: ParticleArrays2d — the removed particles

remove_all(): Remove all particles (settled, leaving, etc.) from the slim4::particles2d::ParticleArrays2d. This also sorts the particles.

get_position()

Get the 2D position of the particles

Returns

xy: NDArray[np.float64] — The 2D position of the particles (2, n_particles)

get_concentration(attr_name, by_area)

Get the 2D position of the particles

Parameters

attr_name: str — The name of the attribute to sum (if ‘count’ the number of particles is used)

by_area: bool — = true Compute the concentration by squared meters

Returns

concentration: slim.ScalarArrayDevice — P0 array with the concentration of particles on each element (n_triangles)

get_concentration_3D(attr_name, mesh3D, z_0, eta)

Get the 3D position of the particles. The user has to provide the particle relative vertical position (between 0 at the surface and 1 at the bottom) in the parray with the name z

Parameters

attr_name: str — The name of the attribute to sum (if ‘count’ the number of particles is used)
mesh3D: slim3d.Mesh — The 3D mesh on which the concentration is computed
z_0: slim.ScalarArrayDevice — The z coordinates of the nodes in the 3D mesh
eta: slim.ScalarArrayDevice — The sea surface elevation at the time of the computation

Returns

concentration: slim.ScalarArrayDeviceMPI — P0 array with the concentration of particles on each prism (n_prims)

z: slim.ScalarArrayDeviceMPI — P1 array with the updated z coordinates of the mesh (1,6,n_prisms)

get_triangle()

Get the triangle indices of the particles

Returns

tri: NDArray[np.int32] — The triangle indices of the particles (n_particles)

get_bndtype()

Get the bndtype flag

Returns

bndtype: NDArray[np.int32] — The bndtype flag of the particles (n_particles)

get_deletion_time()

Get the deletion time of the deleted particles

Returns

deletion_time: NDArray[np.float64] — The deletion time of the deleted particles (n_particles)

get_attr(name)

Get the attribute of the particles

Parameters

name: str — The name of the attribute

Returns

attr: NDArray[np.float64] — The attribute of the particles (n_particles)

set_attr(name, value)

Set the attribute of the particles to a new value

Parameters

name: str — The name of the attribute

value: NDArray[np.float64] — The value of the attribute

get_attribute_names()

Get the names of the attributes of the particles

Returns

names: List[str] — The names of the attributes of the particles

eval_data2d(mesh, data, t)

Evaluate the data at time t for 2D field

Parameters

mesh: slim2d.Mesh — the 2d mesh
data: slim.Data — The data to evaluate
t: float — The time to evaluate the data at

Returns

evaluated_data: NDArray[np.float64] — The evaluated data

static create_xdmf(fname)

Create a new xdmf export for the particles

Parameters

fname: str — The name of the xdmf file to create (without extension)

append_to_xdmf(fname, t, fields=[])

Append the particles to an existing xdmf export

Parameters

fname: str — The name of the xdmf file to append to (without extension)
t: float — The time to export
fields: List[str] — The fields to export (if empty, all fields will be exported). Defaults fields are ‘tri’, ‘bndtype’ and ‘deletion_time’

class slim4.particles2d.Tracker2d

doc

Constructor

__init__(mesh, eta, uv, bath, kh, kh_formula='direct')

Create new 2D tracker

Parameters

mesh: slim2d.Mesh — 2D mesh
eta: slim.Data — elevation
uv: slim.Data — velocity field (u, v)
bath: slim.Data — Bathymetry (positive down)
kh: slim.Data — horizontal diffusivity
kh_formula: slim2d.HorizontalDiffusivityFormula | str — horizontal diffusivity formula

Methods

set_boundary(tag, type)

Set open boundaries for the tracker

Parameters

tag: str — The boundary tag

type: particles.ParticleBoundaryType | str — The type of boundary

move(p_array, t, dt)

Move particles

Parameters

p_array: ParticleArrays2d — particle arrays
t: float — time
dt: float — time diff between

Returns

end_t: float — the new time after moving the particles

add_particles(p_array, px, t, attrs={})

doc

Parameters

p_array: ParticleArrays2d — p_array
px: NDArray[np.float64] — px
t: float — time
attrs: Dict[str,NDArray[np.float64]] — additional scalar attributes

Returns

n_added: int — the number of particles added

class slim4.particles2d.Sediments2d

doc

Constructor

__init__(mesh, eta, uv, bath, kh, kh_formula='direct')

Create new 2D tracker

Parameters

mesh: slim2d.Mesh — 2D mesh
eta: slim.Data — elevation
uv: slim.Data — velocity field (u, v)
bath: slim.Data — Bathymetry (positive down)
kh: slim.Data — horizontal diffusivity
kh_formula: slim2d.HorizontalDiffusivityFormula | str — horizontal diffusivity formula

Methods

set_boundary(tag, type)

Set open boundaries for the tracker

Parameters

tag: str — The boundary tag

type: particles.ParticleBoundaryType | str — The type of boundary

move(p_array, t, dt)

Move particles

Parameters

p_array: ParticleArrays2d — particle arrays
t: float — time
dt: float — time diff between

Returns

end_t: float — the new time after moving the particles

add_particles(p_array, px, t, attrs={})

doc

Parameters

p_array: ParticleArrays2d — p_array
px: NDArray[np.float64] — px
t: float — time
attrs: Dict[str,NDArray[np.float64]] — additional scalar attributes

Returns

n_added: int — the number of particles added

resuspend_sediments(parray, t, dt, mesh, z, uv2d_data, eta_data, ks, D50, porosity, rho_sediments, volumic_mass_sediment_layer, rho_water, nu, h_min)

doc

Parameters

parray: ParticleArrays2d — parray
t: float — time
dt: float — time step
mesh: slim2d.Mesh — mesh
z: slim.Data — z
uv2d_data: slim.Data — uv2d_data
eta_data: slim.Data — eta_data
ks: float — form roughness height
D50: float — median grain size
porosity: float — sediment porosity
rho_sediments: float — sediment density
volumic_mass_sediment_layer: float — volumic mass of the sediment layer
rho_water: float — water density
nu: float — kinematic viscosity
h_min: float — minimum water depth for resuspension

class slim4.particles2d.Plastic

2D Lagrangian tracker for macro plastic transport in a 2D hydrodynamic framework. Each particle represent a certain mass of plastic taht may decrease with time. Typical workflow: 1. create() — instantiate with hydrodynamic fields 2. add_particles() — inject particles with per-grain attributes 3. move() update_mass() remove_inactive() — advance each time step 4. get_suspension_concentration() — post-process

Constructor

__init__(mesh, eta, uv, bath, wind, wind_factor, mass_loss, kh, kh_formula='direct')

Create new 2D tracker

Parameters

mesh: slim2d.Mesh — 2D mesh
eta: slim.Data — elevation
uv: slim.Data — velocity field (u, v)
bath: slim.Data — Bathymetry (positive down)
wind: slim.Data — Wind velocity (u_wind,v_wind)
wind_factor: float — scaling factor for the wind (-)
mass_loss: float — Plastic mass loss (1/s)
kh: slim.Data — horizontal diffusivity
kh_formula: slim2d.HorizontalDiffusivityFormula | str — horizontal diffusivity formula

Methods

set_boundary(tag, type)

Set open boundaries for the tracker

Parameters

tag: str — The boundary tag

type: particles.ParticleBoundaryType | str — The type of boundary

move(p_array, t, dt)

Move particles

Parameters

p_array: ParticleArrays2d — particle arrays
t: float — time
dt: float — time diff between

Returns

end_t: float — the new time after moving the particles

add_particles(p_array, px, attrs)

doc

Parameters

p_array: ParticleArrays2d — p_array
px: NDArray[np.float64] — px
attrs: Dict[str,NDArray[np.float64]] — ex: {‘mass’: the particle mass (kg) additional scalar attributes}

Returns

n_added: int — the number of particles added

update_mass(parray, dt)

doc

Parameters

parray: ParticleArrays2d — parray of the particles in suspension

dt: float — time step

class slim4.particles2d.ResidenceTimeArray

doc

Properties

nnz: int — numner of non-zero entries
n_rows: int — number of mesh elements in the region of interest
n_cols: int — number of time bins

Constructor

__init__(n_rows, n_cols, initial_capacity=0)

Create a new slim4::particles2d::ResidenceTimeArray:: with the given capacity

Parameters

n_rows: int — number of mesh elements in the region of interest
n_cols: int — number of time bins
initial_capacity: int — initial capacity of the array

Methods

get_entries()

Get the entries of the connectivity array

Returns

pfrom: NDArray[np.int32] — pfrom
pto: NDArray[np.int32] — pto
weight: NDArray[np.float64] — weight

update(pfrom, pto, pweight)

Adds the entries to the connectivity array

Parameters

pfrom: slim.IdxArrayDevice — pfrom
pto: slim.IdxArrayDevice — pto
pweight: slim.ScalarArrayDevice — weight

class slim4.particles2d.Particle2dRT

doc

Constructor

__init__(mesh, eta, uv, bath, kh, kh_formula='direct')

Create new 2D tracker

Parameters

mesh: slim2d.Mesh — 2D mesh
eta: slim.Data — elevation
uv: slim.Data — velocity field (u, v)
bath: slim.Data — Bathymetry (positive down)
kh: slim.Data — horizontal diffusivity
kh_formula: slim2d.HorizontalDiffusivityFormula | str — horizontal diffusivity formula

Methods

set_boundary(tag, type)

Set open boundaries for the tracker

Parameters

tag: str — The boundary tag

type: particles.ParticleBoundaryType | str — The type of boundary

move(p_array, t, dt)

Move particles

Parameters

p_array: ParticleArrays2d — particle arrays
t: float — time
dt: float — time diff between

Returns

end_t: float — the new time after moving the particles

add_particles(p_array, px, t, attrs={})

doc

Parameters

p_array: ParticleArrays2d — p_array
px: NDArray[np.float64] — px
t: float — time
attrs: Dict[str,NDArray[np.float64]] — additional scalar attributes

Returns

n_added: int — the number of particles added

update_clock(p_array, dt)

doc

Parameters

p_array: ParticleArrays2d — p_array

dt: float — timestep

update_state_and_residence_time(p_array, elem_map, RT_array, t, time_bin_size)

doc

Parameters

p_array: ParticleArrays2d — particles array
elem_map: slim.Data — element map to determine which particles are in the region of interest
RT_array: ResidenceTimeArray — residence time array to update residence times of exiting particles
t: float — time
time_bin_size: float — duration of time bins for residence time array discretization

update_exposition_time(deleted, ET_array, time_bin_size)

doc

Parameters

deleted: ParticleArrays2d — deleted particles array
ET_array: ResidenceTimeArray — residence time array to update exposition times of deleted particles
time_bin_size: float — duration of time bins for exposition time array discretization