_seeder module

Seeder for Rockfall Simulations

This module defines the Seeder class and related enumerations used to initialise rockfall simulations in 2D and 3D. A Seeder specifies the release locations, initial velocities, and associated rock groups.

Main Features

  • Unified support for 2D and 3D simulations via a points argument.

  • Point seeder: defined by a single point (D,) or a list of points (D,N). If multiple points are provided, positions are sampled to be one of the provided points.

  • Line seeder: defined by a polyline with at least two points (D, N>=2), with positions sampled uniformly along arc length.

  • Area seeder: defined by multiple points (D, N>=2), with positions sampled as linear combinations of the provided points.

  • Dimension-aware velocity distributions: - Translational velocity: D components (vx, vy[, vz]). - Angular velocity: 1 component in 2D (ωz), 3 components in 3D (ωx, ωy, ωz).

Contents

class pyrockfall._seeder.SeederRocksThrown(*values)[source]

Bases: Enum

Enum specifying how rocks are distributed across types when seeding.

Overall = 1

Rocks distributed across all types collectively.

PerRockType = 2

Rocks assigned per rock type.

class pyrockfall._seeder.Seeder(points: ndarray, rocks: List[Rock], name: str = '')[source]

Bases: object

Defines a Seeder (rock thrower) in 2D or 3D rockfall simulations.

A Seeder represents the location(s) where rocks are released, the distributions of their initial velocities, and the associated rock types.

Seeder types:
  • Point seeder: defined by a single point (points.shape == (D,) or (D,N)). When multiple points are provided, positions are sampled to be one of the provided points.

Parameters:
  • points (array-like) – Seeder coordinates of shape (D,) or (D, N). - D=2: 2D seeder. - D=3: 3D seeder. - N=1: point seeder. - N>=2: point seeder with multiple points.

  • rocks (list[Rock]) – Rock instances associated with the seeder.

  • name (str, optional) – Name of the seeder. Auto-generated if not provided.

rocks

Rock types/groups associated with the seeder.

Type:

list[Rock]

rockThrowMode

Strategy for distributing rocks.

Type:

SeederRocksThrown

numberOfRocks

Number of rocks to throw.

Type:

int

translationalVelocity

Distributions for translational velocity components (length D).

Type:

list

angularVelocity

Distributions for angular velocity components: length 1 in 2D (scalar ωz), length 3 in 3D (ωx, ωy, ωz).

Type:

list

rockThrowMode: SeederRocksThrown
numberOfRocks: int
rocks: List[Rock]
property name: str

Name of the seeder.

Type:

str

property D: int

Dimension of the seeder (2 or 3).

Type:

int

property points: ndarray

Seeder coordinates of shape (D, N).

Type:

ndarray

property isPointSeeder: bool

True if seeder is a point seeder.

Type:

bool

property isLineSeeder: bool

True if seeder is a line seeder.

Type:

bool

property isAreaSeeder: bool

True if seeder is an area seeder.

Type:

bool

property numRVsPosition: int

Number of random variables for position sampling.

Type:

int

property numRandomVariables: int

Number of random variables.

Count:
  • D translational components

  • 1 angular in 2D, or 3 angular in 3D

    • number of position RVs

Type:

int

property translationalVelocity: DistributionVector

Distributions for D translational velocity components.

Type:

list

property angularVelocity: DistributionVector

Distributions for angular velocity (1 in 2D, 3 in 3D).

Type:

list

ppf(q: ndarray) → Tuple[ndarray, ndarray, ndarray][source]

Generate deterministic samples from quantiles.

Parameters:

q (np.ndarray) – Percentiles, shape (numRandomVariables, M). - First D rows: translational velocity components. - Next rows: angular velocity (1 row in 2D, 3 rows in 3D). - Last row: position of samples.

Returns:

  • positions (np.ndarray): Seeder positions, shape (D, M).

  • translational_velocity (np.ndarray): Velocities, shape (D, M).

  • angular_velocity (np.ndarray): Angular velocities, shape (1, M) in 2D or (3, M) in 3D.

Return type:

tuple

Raises:

ValueError – If the shape of q is inconsistent with the seeder definition.

rvs(num_samples: int) → Tuple[ndarray, ndarray, ndarray][source]

Generate random samples of positions and velocities.

Parameters:

num_samples (int) – Number of samples.

Returns:

  • positions (np.ndarray): Seeder positions, shape (D, N).

  • translational_velocity (np.ndarray): Velocities, shape (D, N).

  • angular_velocity (np.ndarray): Angular velocities, shape (1, N) in 2D or (3, N) in 3D.

Return type:

tuple

plot(ax=None, **kwargs)[source]

Visualize the seeder geometry.

Parameters:
  • ax (matplotlib.axes.Axes, optional) – Axes to plot on. If None, a new figure/axes is created.

  • **kwargs – Forwarded to matplotlib plot/scatter.

Returns:

The axes with the Seeder drawn.

Return type:

matplotlib.axes.Axes

class pyrockfall._seeder.LineSeeder(points: ndarray, rocks: List[Rock], name: str = '')[source]

Bases: Seeder

Defines a Line Seeder (rock thrower) in 2D or 3D rockfall simulations.

Line Seeder is defined by a polyline with at least 2 points (points.shape == (D, N>=2)). Positions are sampled along the polyline proportional to arc length.

Parameters:
  • points (array-like) – Seeder coordinates of shape (D,) or (D, N). - D=2: 2D seeder. - D=3: 3D seeder. - N=1: single point seeder. - N>=2: line seeder along polyline.

  • rocks (list[Rock]) – Rock instances associated with the seeder.

  • name (str, optional) – Name of the seeder. Auto-generated if not provided.

rocks

Rock types/groups associated with the seeder.

Type:

list[Rock]

rockThrowMode

Strategy for distributing rocks.

Type:

SeederRocksThrown

numberOfRocks

Number of rocks to throw.

Type:

int

translationalVelocity

Distributions for translational velocity components (length D).

Type:

list

angularVelocity

Distributions for angular velocity components: length 1 in 2D (scalar ωz), length 3 in 3D (ωx, ωy, ωz).

Type:

list

property isPointSeeder: bool

True if seeder is a point seeder.

Type:

bool

property isLineSeeder: bool

True if seeder is a line seeder.

Type:

bool

property isAreaSeeder: bool

True if seeder is an area seeder.

Type:

bool

property numRVsPosition: int

Number of random variables for position sampling.

Type:

int

class pyrockfall._seeder.AreaSeeder(points: ndarray, rocks: List[Rock], name: str = '')[source]

Bases: Seeder

property isPointSeeder: bool

True if seeder is a point seeder.

Type:

bool

property isLineSeeder: bool

True if seeder is a line seeder.

Type:

bool

property isAreaSeeder: bool

True if seeder is an area seeder.

Type:

bool

property numRVsPosition: int

Number of random variables for position sampling.

Type:

int