Source code for pyrockfall._vegetation
"""
Vegetation class for pyrockfall
==========================
This module defines the :class:`Vegetation` class, which represents the canopy geometry
above a slope. A vegetation is defined by:
- Nodes: coordinates of the geometry (mandatory).
- Elements: connectivity between nodes (optional; if omitted, sequential connectivity is assumed).
- Drag: the drag coefficient that dissipates energy when block moves through vegetation.
The class supports stochastic perturbation of nodes, material assignment,
combination of contiguous slopes, and efficient queries.
"""
import numpy as np
from scipy.stats import norm
from typing import List, Optional, Tuple, Union, Sequence
from numpy.typing import NDArray
from . import stats
from ._geometry import Geometry
from ._utils import uniqueMaterialList
[docs]
class Drag:
_instance_count = 0
def __init__(
self,
name: str = "",
coefficient: stats.DistributionLike = 0.0
) -> None:
Drag._instance_count += 1
self._name: str = name or f"Drag {Drag._instance_count}"
# Default to deterministic zeros
self._coefficient: stats.Distribution = stats.asDistribution(coefficient)
# ----------------------------
# Properties
# ----------------------------
@property
def name(self) -> str:
"""Name of the material."""
return self._name
@property
def coefficient(self) -> stats.Distribution:
return self._coefficient
@coefficient.setter
def coefficient(self, value: stats.DistributionLike) -> None:
self._coefficient = stats.asDistribution(value)
@property
def numRandomVariables(self) -> int:
"""Number of stochastic variables (always ``1``)."""
return 1
# ----------------------------
# Sampling / quantiles
# ----------------------------
[docs]
def ppf(self, q: Union[Sequence[np.ndarray], np.ndarray]) -> np.ndarray:
if not isinstance(q, (list, tuple, np.ndarray)) or len(q) != 1:
raise ValueError("`q` must be a sequence of one quantile array.")
out = [
self.coefficient.ppf(np.asarray(q[0]))
]
return np.asarray(out)
[docs]
def rvs(self, num_samples: int) -> np.ndarray:
if num_samples < 0:
raise ValueError("`num_samples` must be non-negative.")
samples = [
self.coefficient.rvs(num_samples)
]
return np.asarray(samples)
# ----------------------------
# Representation
# ----------------------------
def __repr__(self) -> str: # pragma: no cover - convenience only
return (
f"Drag(coefficient={type(self._coefficient).__name__})"
)
[docs]
class Vegetation:
def __init__(
self,
geometry: Geometry,
drag: Union[Drag, Sequence[Drag]],
identities: Optional[Union[Sequence[int], NDArray[np.integer]]] = None,
):
self._geometry = geometry
if identities is not None:
# user provided table + IDs
if not isinstance(drag, (list, np.ndarray)):
raise TypeError("If `identities` is provided, `materials` must be a list/array of Material (the table).")
self._drag_table = list(drag)
ids = np.asarray(identities, dtype=int)
else:
# materials is either a single material or per-element list
if isinstance(drag, Drag):
self._drag_table = [drag]
ids = np.zeros(len(self._geometry.elements), dtype=int)
elif isinstance(drag, (list, np.ndarray)):
self._drag_table, ids = uniqueMaterialList(list(drag))
else:
raise TypeError("`materials` must be a Material, or a list/array of Material.")
self._geometry.attributes = ids
# Delegate to geometry
def __getattr__(self, name):
return getattr(self._geometry, name)
@property
def drag(self) -> List[Drag]:
return [self._drag_table[mid] for mid in self.dragIdentities]
@property
def dragTable(self) -> List[Drag]:
"""list of Drag: Unique drag used."""
return self._drag_table
@property
def dragIdentities(self) -> np.ndarray:
"""np.ndarray of shape (E,): Drag IDs per element (indices into `dragTable`)."""
attrs = self._geometry.attributes
if attrs is None:
raise ValueError("Drag IDs not stored.")
return attrs