_material module

Materials for pyrockfall

Defines the 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 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].

class pyrockfall._material.Material(name: str = '', normalRestitution: stats.DistributionLike = 0.0, tangentialRestitution: stats.DistributionLike = 0.0, frictionAngle: stats.DistributionLike = 0.0, roughness: stats.DistributionLike = 0.0, color: Tuple[int, int, int] | None = None)[source]

Bases: object

Material with stochastic properties for slope/rockfall simulation.

A Material holds three RV-like parameters. Each can be assigned a scalar (wrapped as Deterministic) or any object that supports ppf and rvs (e.g., SciPy’s rv_frozen).

name

Name/label of the material.

Type:

str

normalRestitution

Normal restitution coefficient (typ. in [0, 1]).

Type:

Deterministic or RV-like

tangentialRestitution

Tangential restitution coefficient (typ. in [0, 1]).

Type:

Deterministic or RV-like

frictionAngle

Friction angle in degrees.

Type:

Deterministic or RV-like

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)
property name: str

Name of the material.

property normalRestitution: Distribution

Normal restitution coefficient (Deterministic or RV-like).

property tangentialRestitution: Distribution

Tangential restitution coefficient (Deterministic or RV-like).

property frictionAngle: Distribution

Friction angle in degrees (Deterministic or RV-like).

property roughness: Distribution
property color: Tuple[int, int, int] | None

Optional RGB color for visualization/export.

property numRandomVariables: int

Number of stochastic variables (always 3).

ppf(q: Sequence[ndarray] | ndarray) → ndarray[source]

Percent point function (inverse CDF) for each variable.

Parameters:

q – Quantiles for each random variable. Provide three arrays (or array‑likes) in the order: [normalRestitution, tangentialRestitution, frictionAngle].

Returns:

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.

Return type:

ndarray

Raises:

ValueError – If q does not contain three quantile arrays.

rvs(num_samples: int) → ndarray[source]

Draw random samples for the three stochastic parameters.

Parameters:

num_samples – Number of samples to draw per variable (>= 0).

Returns:

Array of shape (3, num_samples) with samples ordered as [normal, tangential, friction] along the first axis.

Return type:

ndarray

Notes

  • If any parameter is deterministic, its samples are just repeated constants.