Source code for pyrockfall._rock
"""
Rock definition for pyrockfall
==============================
This module defines the :class:`Rock` class, representing a rock type or group
to be thrown in rockfall simulations. Each :class:`Rock` encapsulates material
properties as probability distributions (or deterministic constants) to support
uncertainty quantification during sampling.
Main Features
-------------
* Material properties as distributions:
- ``mass`` and ``density`` can be deterministic or random (SciPy frozen RVs
or custom distributions).
* Consistent sampling API:
- :meth:`Rock.ppf` for inverse-CDF sampling from quantiles.
- :meth:`Rock.rvs` for random variate draws.
Notes
-----
Use :func:`stats.asDistribution` to convert numeric inputs into deterministic
distributions and to accept frozen SciPy distributions seamlessly.
"""
from typing import List, Optional, Tuple
import numpy as np
from . import stats
[docs]
class Rock:
"""Represents a rock type or group in a rockfall simulation.
Each instance stores the probabilistic description of material properties,
currently **mass** and **density**. Properties may be deterministic
(e.g., :class:`Deterministic`) or random (e.g., SciPy ``rv_frozen`` or
custom :class:`TruncatedRandomVariable`).
Args:
name (str, optional): Name of the rock group. If not provided,
names are auto-generated as ``"Group <i>"``.
Attributes:
name (str): Name of the rock group.
mass: stats.Distribution object for mass.
density: stats.Distribution object for density.
"""
_instance_count = 0
def __init__(self, name: str = '',
mass: stats.DistributionLike = 0.0,
density: stats.DistributionLike = 0.0,
color: Optional[Tuple[int, int, int]] = None) -> None:
"""Initialize a new :class:`Rock`."""
Rock._instance_count += 1
self._name = name or f'Group {Rock._instance_count}'
# Defaults are deterministic zeros; users should override as needed.
self._mass: stats.Distribution = stats.asDistribution(mass)
self._density: stats.Distribution = stats.asDistribution(density)
self._color: Optional[Tuple[int, int, int]] = color
# ---------------------- Properties ----------------------
@property
def name(self) -> str:
"""str: Name of the rock group."""
return self._name
@property
def mass(self) -> stats.Distribution:
"""stats.Distribution for mass (deterministic or random)."""
return self._mass
@mass.setter
def mass(self, value: stats.DistributionLike) -> None:
"""Set mass as a value or distribution.
Args:
value: Numeric value (wrapped via :func:`stats.asDistribution`) or a
distribution .
"""
self._mass = stats.asDistribution(value)
@property
def density(self) -> stats.Distribution:
"""stats.Distribution for density (deterministic or random)."""
return self._density
@density.setter
def density(self, value: stats.DistributionLike) -> None:
"""Set density as a value or distribution.
Args:
value: Numeric value (wrapped via :func:`stats.asDistribution`) or a
distribution.
"""
self._density = 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:
"""int: Number of random variables (currently 2: mass and density)."""
return 2
# ---------------------- Sampling API ----------------------
[docs]
def ppf(self, q: np.ndarray) -> List[np.ndarray]:
"""Evaluate the percent-point function (inverse CDF).
Args:
q (np.ndarray): Quantiles for each random variable, shape ``(2, N)``.
- ``q[0, :]``: quantiles for mass
- ``q[1, :]``: quantiles for density
Returns:
list[np.ndarray]: ``[mass_samples, density_samples]``, each of shape ``(N,)``.
"""
q = np.asarray(q)
if q.ndim != 2 or q.shape[0] != 2:
raise ValueError(f"`q` must have shape (2, N). Got {q.shape}.")
mass_samples = self._mass.ppf(q[0])
density_samples = self._density.ppf(q[1])
return [np.asarray(mass_samples), np.asarray(density_samples)]
[docs]
def rvs(self, num_samples: int) -> List[np.ndarray]:
"""Draw random samples for mass and density.
Args:
num_samples (int): Number of samples ``N``.
Returns:
list[np.ndarray]: ``[mass_samples, density_samples]``, each of shape ``(N,)``.
"""
N = int(num_samples)
mass_samples = self._mass.rvs(N)
density_samples = self._density.rvs(N)
return [np.asarray(mass_samples), np.asarray(density_samples)]