"""
Seeder for Rockfall Simulations
===============================
This module defines the :class:`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:`SeederRocksThrown`: Enum specifying seeding strategies.
- :class:`Seeder`: Main class for defining point seeders.
- :class:`LineSeeder`: Main class for defining line seeders.
- :class:`AreaSeeder`: Main class for defining area seeders.
"""
from __future__ import annotations
from enum import Enum, auto
from typing import List, Sequence, Tuple, Union
import numpy as np
from ._rock import Rock
from . import stats
[docs]
class SeederRocksThrown(Enum):
"""Enum specifying how rocks are distributed across types when seeding."""
Overall = auto()
"""Rocks distributed across all types collectively."""
PerRockType = auto()
"""Rocks assigned per rock type."""
[docs]
class Seeder:
"""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.
Args:
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.
Attributes:
rocks (list[Rock]): Rock types/groups associated with the seeder.
rockThrowMode (SeederRocksThrown): Strategy for distributing rocks.
numberOfRocks (int): Number of rocks to throw.
translationalVelocity (list): Distributions for translational velocity
components (length ``D``).
angularVelocity (list): Distributions for angular velocity components:
length 1 in 2D (scalar ωz), length 3 in 3D (ωx, ωy, ωz).
"""
_instance_count = 0
# --------------------------------------------------------------------- #
# Constructor and core geometry
# --------------------------------------------------------------------- #
def __init__(self, points: np.ndarray, rocks: List[Rock], name: str = "") -> None:
Seeder._instance_count += 1
self._name: str = name or f"Seeder {Seeder._instance_count}"
self.rockThrowMode: SeederRocksThrown = SeederRocksThrown.Overall
self.numberOfRocks: int = 0
self.rocks: List[Rock] = rocks
P = np.asarray(points, dtype=float)
if P.ndim == 1:
P = P.reshape(-1, 1)
if P.ndim != 2:
raise ValueError("points must be shape (D,) or (D, N).")
D, N = P.shape
if D not in (2, 3):
raise ValueError(f"D must be 2 or 3; got D={D}.")
if N < 1:
raise ValueError("points must contain at least one point.")
self._D: int = D
self._points: np.ndarray = P # shape (D, N)
# Default velocity distributions (dimension-aware).
# Use asDistribution for scalars; asDistVector for explicit vectors.
self._translationalVelocity: stats.DistributionVector = stats.DistributionVector(0.0, length=D)
self._angularVelocity: stats.DistributionVector = stats.DistributionVector(0.0, length=1 if D == 2 else 3)
# --------------------------------------------------------------------- #
# Properties
# --------------------------------------------------------------------- #
@property
def name(self) -> str:
"""str: Name of the seeder."""
return self._name
@property
def D(self) -> int:
"""int: Dimension of the seeder (2 or 3)."""
return self._D
@property
def points(self) -> np.ndarray:
"""ndarray: Seeder coordinates of shape ``(D, N)``."""
return self._points
@property
def isPointSeeder(self) -> bool:
"""bool: True if seeder is a point seeder."""
return True
@property
def isLineSeeder(self) -> bool:
"""bool: True if seeder is a line seeder."""
return False
@property
def isAreaSeeder(self) -> bool:
"""bool: True if seeder is an area seeder."""
return False
@property
def numRVsPosition(self) -> int:
"""int: Number of random variables for position sampling."""
return 0 if self.points.shape[1] == 1 else 1
@property
def numRandomVariables(self) -> int:
"""int: Number of random variables.
Count:
* ``D`` translational components
* 1 angular in 2D, or 3 angular in 3D
* + number of position RVs
"""
base = self.D + (1 if self.D == 2 else 3)
return base + self.numRVsPosition
# --------------------- Velocity distributions --------------------- #
@property
def translationalVelocity(
self,
) -> stats.DistributionVector:
"""list: Distributions for ``D`` translational velocity components."""
return self._translationalVelocity
@translationalVelocity.setter
def translationalVelocity(self, value: stats.DistributionVectorLike) -> None:
"""Set translational velocity distributions.
Accepts either:
* a **vector** (list/tuple/1D ndarray) converted via :func:`asDistVector`
(length must equal ``D``), or
* a **scalar/distribution** to be **broadcast** to all ``D`` components
using :func:`asDistribution`.
Raises:
ValueError: If a vector is provided but its length ≠ ``D``.
"""
self._translationalVelocity = stats.asDistributionVector(value, length=self.D)
@property
def angularVelocity(self) -> stats.DistributionVector:
"""list: Distributions for angular velocity (1 in 2D, 3 in 3D)."""
return self._angularVelocity
@angularVelocity.setter
def angularVelocity(self, value: stats.DistributionVectorLike) -> None:
"""Set angular velocity distributions.
Accepts either:
* a **vector** (list/tuple/1D ndarray) converted via :func:`asDistVector`
(length must be 1 in 2D or 3 in 3D), or
* a **scalar/distribution** to be **broadcast** to the angular length
using :func:`asDistribution`.
Raises:
ValueError: If a vector is provided but its length is invalid for the dimension.
"""
required = 1 if self.D == 2 else 3
self._angularVelocity = stats.asDistributionVector(value, length=required)
# --------------------------------------------------------------------- #
# Sampling helpers
# --------------------------------------------------------------------- #
def _sample_positions(self, u: np.ndarray) -> np.ndarray:
"""Sample positions to be one of the provided points.
Args:
u (np.ndarray): Samples in ``[0,1]``, shape ``(1, M)``.
Returns:
np.ndarray: Sampled positions of shape ``(D, M)``.
"""
# Check shape of u
if u.ndim == 1:
u = u.reshape(1, -1)
if u.ndim != 2 or u.shape[0] > 1:
raise ValueError("Position sampling quantiles u must have shape (1, M).")
# Check for deterministic case
if u.shape[0] == 0:
return np.repeat(self.points[:, 0:1], repeats=u.shape[1], axis=1)
# Sanity check: all quantiles must be in [0, 1]
if ((u < 0) | (u > 1)).any():
raise ValueError("Position sampling quantiles must be in [0, 1].")
D = self.points.shape[0]
num_pts = self.points.shape[1]
# Compute indices of points corresponding to each u
# Intervals: (0, 1/num_pts], (1/num_pts, 2/num_pts], ..., ((n-1)/n, 1]
# so index = ceil(u * num_pts) - 1
idx = np.ceil(u * num_pts).astype(int) - 1
# Clip just in case u == 0.0; this maps it to the first interval.
# (If you want to treat u == 0 as invalid, you can check and raise instead.)
idx = np.clip(idx, 0, num_pts - 1)
# Get samples' position
samples = self.points[:, idx.ravel()] # shape (D, M)
return samples
def _ppf_stack(self, dists: Sequence, qs: np.ndarray) -> np.ndarray:
"""Evaluate percent-point function for a list of distributions.
Args:
dists (Sequence): List of distributions.
qs (np.ndarray): Quantiles, shape ``(len(dists), M)``.
Returns:
np.ndarray: Samples, shape ``(len(dists), M)``.
"""
return np.vstack([dists[i].ppf(qs[i]) for i in range(len(dists))])
def _rvs_stack(self, dists: Sequence, n: int) -> np.ndarray:
"""Draw random samples from a list of distributions.
Args:
dists (Sequence): List of distributions.
n (int): Number of samples.
Returns:
np.ndarray: Samples, shape ``(len(dists), n)``.
"""
return np.vstack([d.rvs(n) for d in dists])
# --------------------------------------------------------------------- #
# Public API
# --------------------------------------------------------------------- #
[docs]
def ppf(self, q: np.ndarray) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
"""Generate deterministic samples from quantiles.
Args:
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:
tuple:
- **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.
Raises:
ValueError: If the shape of ``q`` is inconsistent with the seeder definition.
"""
q = np.asarray(q, dtype=float)
if q.ndim != 2 or q.shape[0] != self.numRandomVariables:
raise ValueError(
f"q must have shape (numRandomVariables, M) with numRandomVariables={self.numRandomVariables}, "
f"got {q.shape}."
)
M = q.shape[1]
D = self.D
A = 1 if D == 2 else 3
q_trans = q[0:D, :]
q_ang = q[D:D + A, :]
q_pos = q[D + A:, :]
translational_velocity = self._ppf_stack(self._translationalVelocity, q_trans) # (D, M)
angular_velocity = self._ppf_stack(self._angularVelocity, q_ang) # (A, M)
positions = self._sample_positions(q_pos) # (D, M)
return positions, translational_velocity, angular_velocity
[docs]
def rvs(self, num_samples: int) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
"""Generate random samples of positions and velocities.
Args:
num_samples (int): Number of samples.
Returns:
tuple:
- **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.
"""
N = int(num_samples)
D = self.D
A = 1 if D == 2 else 3
translational_velocity = self._rvs_stack(self._translationalVelocity, N) # (D, N)
angular_velocity = self._rvs_stack(self._angularVelocity, N) # (A, N)
positions = self._sample_positions(np.random.rand(self.numRVsPosition, N)) # (D, N)
return positions, translational_velocity, angular_velocity
# --------------------------------------------------------------------- #
# Plot helper
# --------------------------------------------------------------------- #
[docs]
def plot(self, ax=None, **kwargs):
"""Visualize the seeder geometry.
Args:
ax (matplotlib.axes.Axes, optional): Axes to plot on.
If ``None``, a new figure/axes is created.
**kwargs: Forwarded to matplotlib ``plot``/``scatter``.
Returns:
matplotlib.axes.Axes: The axes with the Seeder drawn.
"""
import matplotlib.pyplot as plt
if self.D == 2:
if ax is None:
_, ax = plt.subplots()
P = self._points
if self.isPointSeeder:
ax.scatter(P[0, 0], P[1, 0], **kwargs)
else:
ax.plot(P[0, :], P[1, :], **kwargs)
return ax
# 3D plotting
from mpl_toolkits.mplot3d import Axes3D # type: ignore
if ax is None:
fig = plt.figure()
ax = fig.add_subplot(111, projection="3d")
P = self._points
if self.isPointSeeder:
ax.scatter(P[0, 0], P[1, 0], P[2, 0], **kwargs)
else:
ax.plot(P[0, :], P[1, :], P[2, :], **kwargs)
return ax
[docs]
class LineSeeder(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.
Args:
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.
Attributes:
rocks (list[Rock]): Rock types/groups associated with the seeder.
rockThrowMode (SeederRocksThrown): Strategy for distributing rocks.
numberOfRocks (int): Number of rocks to throw.
translationalVelocity (list): Distributions for translational velocity
components (length ``D``).
angularVelocity (list): Distributions for angular velocity components:
length 1 in 2D (scalar ωz), length 3 in 3D (ωx, ωy, ωz).
"""
@property
def isPointSeeder(self) -> bool:
"""bool: True if seeder is a point seeder."""
return False
@property
def isLineSeeder(self) -> bool:
"""bool: True if seeder is a line seeder."""
return True
@property
def isAreaSeeder(self) -> bool:
"""bool: True if seeder is an area seeder."""
return False
@property
def numRVsPosition(self) -> int:
"""int: Number of random variables for position sampling."""
return 1
def _sample_positions(self, u: np.ndarray) -> np.ndarray:
"""Sample positions uniformly along a polyline by arc length.
Args:
u (np.ndarray): Samples in ``[0,1]``, shape ``(M,)``.
Returns:
np.ndarray: Sampled positions of shape ``(D, M)``.
"""
if u.shape[0] != 1:
raise ValueError("Position sampling quantiles u with shape (1, M) must be provided for LineSeeder.")
P = self._points # (D, N)
if P.shape[1] == 1:
return np.repeat(P, repeats=u.size, axis=1)
seg = P[:, 1:] - P[:, :-1] # (D, N-1)
lengths = np.linalg.norm(seg, axis=0) # (N-1,)
if not np.all(lengths > 0):
raise ValueError("Degenerate segments (zero length) detected.")
cum = np.cumsum(lengths)
total = cum[-1]
ends = cum / total
starts = np.zeros_like(ends)
starts[1:] = ends[:-1]
# Segment index for each u
idx = np.searchsorted(ends, u.ravel(), side="right")
idx = np.clip(idx, 0, len(lengths) - 1)
# Local interpolation parameter
seg_start = starts[idx]
seg_end = ends[idx]
w = (u - seg_start) / (seg_end - seg_start)
Ps = P[:, idx] # (D, M)
Ss = seg[:, idx] # (D, M)
return Ps + Ss * w
[docs]
class AreaSeeder(Seeder):
@property
def isPointSeeder(self) -> bool:
"""bool: True if seeder is a point seeder."""
return False
@property
def isLineSeeder(self) -> bool:
"""bool: True if seeder is a line seeder."""
return False
@property
def isAreaSeeder(self) -> bool:
"""bool: True if seeder is an area seeder."""
return True
@property
def numRVsPosition(self) -> int:
"""int: Number of random variables for position sampling."""
return self.points.shape[1]
def _sample_positions(self, u: np.ndarray) -> np.ndarray:
"""Sample positions uniformly with a linear combination.
Args:
u (np.ndarray): Samples in ``[0,1]``, shape ``(N, M)``.
Returns:
np.ndarray: Sampled positions of shape ``(D, M)``.
"""
if u.ndim != 2 or u.shape[0] != self.points.shape[1]:
raise ValueError("Position sampling quantiles u with shape (N, M) must be provided for AreaSeeder.")
if self._points.shape[1] < 2:
raise ValueError("AreaSeeder requires at least 2 points.")
# Normalize u to sum to 1
u_sum = np.sum(u, axis=0, keepdims=True) # (1, M)
u_norm = u / u_sum # (N, M)
# Compute positions as linear combinations
positions = self._points @ u_norm # (D, M)
return positions