Source code for pyrockfall._material

"""
Materials for pyrockfall
========================

Defines the :class:`Material` abstraction used in rockfall simulations.

The class encapsulates three stochastic (or deterministic) parameters:

- **normalRestitution** – normal coefficient of restitution (typically in ``[0, 1]``)
- **tangentialRestitution** – tangential coefficient of restitution (typically in ``[0, 1]``)
- **frictionAngle** – friction angle in degrees

Each parameter may be either a deterministic value (wrapped by
:class:`~. _distribution.Deterministic`) or a random variable that exposes
``.ppf(q)`` and ``.rvs(n)`` (e.g., a SciPy ``rv_frozen``).

Notes
-----
- This module does **not** require SciPy at import time; any object with
  ``ppf`` and ``rvs`` methods is accepted (duck typing).
- Returned arrays use the convention ``(3, ...)`` where the first axis
  is ordered as: ``[normal, tangential, friction]``.
"""

from __future__ import annotations

from typing import Optional, Sequence, Tuple, Union

import numpy as np

from . import stats


__all__ = ["Material"]


[docs] class Material: """Material with stochastic properties for slope/rockfall simulation. A :class:`Material` holds three RV-like parameters. Each can be assigned a scalar (wrapped as :class:`Deterministic`) or any object that supports ``ppf`` and ``rvs`` (e.g., SciPy's ``rv_frozen``). Attributes ---------- name : str Name/label of the material. normalRestitution : Deterministic or RV-like Normal restitution coefficient (typ. in ``[0, 1]``). tangentialRestitution : Deterministic or RV-like Tangential restitution coefficient (typ. in ``[0, 1]``). frictionAngle : Deterministic or RV-like Friction angle in degrees. Examples -------- >>> m = Material("Basalt") >>> m.normalRestitution = 0.45 >>> m.tangentialRestitution = 0.6 >>> m.frictionAngle = 35.0 >>> m.numRandomVariables 3 >>> q = [np.array([0.5]), np.array([0.5]), np.array([0.5])] >>> m.ppf(q).shape (3, 1) >>> m.rvs(4).shape (3, 4) """ _instance_count = 0 def __init__( self, name: str = "", normalRestitution: stats.DistributionLike = 0.0, tangentialRestitution: stats.DistributionLike = 0.0, frictionAngle: stats.DistributionLike = 0.0, roughness: stats.DistributionLike = 0.0, color: Optional[Tuple[int, int, int]] = None, ) -> None: """Initialise a :class:`Material`. If no name is provided, a unique default (``"Material <n>"``) is assigned. Args: name: Optional name for the material. color: Optional RGB color (e.g. for visualization/export). Not a stochastic parameter; stored as-is. """ Material._instance_count += 1 self._name: str = name or f"Material {Material._instance_count}" # Default to deterministic zeros self._normalRestitution: stats.Distribution = stats.asDistribution(normalRestitution) self._tangentialRestitution: stats.Distribution = stats.asDistribution(tangentialRestitution) self._frictionAngle: stats.Distribution = stats.asDistribution(frictionAngle) self._roughness: stats.Distribution = stats.asDistribution(roughness) self._color: Optional[Tuple[int, int, int]] = color # ---------------------------- # Properties # ---------------------------- @property def name(self) -> str: """Name of the material.""" return self._name @property def normalRestitution(self) -> stats.Distribution: """Normal restitution coefficient (Deterministic or RV-like).""" return self._normalRestitution @normalRestitution.setter def normalRestitution(self, value: stats.DistributionLike) -> None: """Set the normal restitution coefficient. Accepts a scalar (wrapped as :class:`Deterministic`) or an RV-like object. """ self._normalRestitution = stats.asDistribution(value) @property def tangentialRestitution(self) -> stats.Distribution: """Tangential restitution coefficient (Deterministic or RV-like).""" return self._tangentialRestitution @tangentialRestitution.setter def tangentialRestitution(self, value: stats.DistributionLike) -> None: """Set the tangential restitution coefficient. Accepts a scalar (wrapped as :class:`Deterministic`) or an RV-like object. """ self._tangentialRestitution = stats.asDistribution(value) @property def frictionAngle(self) -> stats.Distribution: """Friction angle in degrees (Deterministic or RV-like).""" return self._frictionAngle @frictionAngle.setter def frictionAngle(self, value: stats.DistributionLike) -> None: """Set the friction angle (degrees). Accepts a scalar (wrapped as :class:`Deterministic`) or an RV-like object. """ self._frictionAngle = stats.asDistribution(value) @property def roughness(self) -> stats.Distribution: return self._roughness @roughness.setter def roughness(self, value: stats.DistributionLike) -> None: self._roughness = stats.asDistribution(value) @property def color(self) -> Optional[Tuple[int, int, int]]: """Optional RGB color for visualization/export.""" return self._color @color.setter def color(self, value: Optional[Tuple[int, int, int]]) -> None: self._color = value @property def numRandomVariables(self) -> int: """Number of stochastic variables (always ``3``).""" return 3 # ---------------------------- # Sampling / quantiles # ----------------------------
[docs] def ppf(self, q: Union[Sequence[np.ndarray], np.ndarray]) -> np.ndarray: """Percent point function (inverse CDF) for each variable. Args: q: Quantiles for each random variable. Provide three arrays (or array‑likes) in the order: ``[normalRestitution, tangentialRestitution, frictionAngle]``. Returns: ndarray: Array of shape ``(3, K)`` (or ``(3, ...)``), where the first axis is ordered as ``[normal, tangential, friction]`` and the remaining dimensions match the broadcast/shape of the provided quantiles. Raises: ValueError: If ``q`` does not contain three quantile arrays. """ if not isinstance(q, (list, tuple, np.ndarray)) or len(q) != 3: raise ValueError("`q` must be a sequence of three quantile arrays.") n, t, f = q # type: ignore[assignment] out = [ self.normalRestitution.ppf(np.asarray(n)), self.tangentialRestitution.ppf(np.asarray(t)), self.frictionAngle.ppf(np.asarray(f)), ] return np.asarray(out)
[docs] def rvs(self, num_samples: int) -> np.ndarray: """Draw random samples for the three stochastic parameters. Args: num_samples: Number of samples to draw per variable (``>= 0``). Returns: ndarray: Array of shape ``(3, num_samples)`` with samples ordered as ``[normal, tangential, friction]`` along the first axis. Notes ----- - If any parameter is deterministic, its samples are just repeated constants. """ if num_samples < 0: raise ValueError("`num_samples` must be non-negative.") samples = [ self.normalRestitution.rvs(num_samples), self.tangentialRestitution.rvs(num_samples), self.frictionAngle.rvs(num_samples), ] return np.asarray(samples)
# ---------------------------- # Representation # ---------------------------- def __repr__(self) -> str: # pragma: no cover - convenience only return ( f"Material(name='{self._name}', " f"normalRestitution={type(self._normalRestitution).__name__}, " f"tangentialRestitution={type(self._tangentialRestitution).__name__}, " f"frictionAngle={type(self._frictionAngle).__name__})" )