"""
Analysis module for pyrockfall
==============================
This module defines the :class:`Analysis` class — an orchestration layer that
coordinates sampling, physics kernels, and interaction with the slope/geometry
backend in a **vectorised** manner for both 2D and 3D simulations.
Design Philosophy
-----------------
- Classes (e.g., :class:`Seeder`, :class:`Rock`, :class:`Material`, :class:`SlopeModel`)
are used for **configuration**.
- Before simulation, all classes are **sampled** into **NumPy arrays** (and a
sampled slope batch), after which the :class:`Analysis` methods operate as
**pure, argument-in / value-out kernels** to preserve vectorisation and
enable easy testing/parallelism.
- Intersection queries are delegated to the sampled slope object (e.g.,
``SlopeBatch``), which provides **batched**, **broadcastable** kernels.
Contents
--------
- :class:`Analysis`: Public API comprising validation, sampling, frame transforms,
impact and sliding mechanics, free-fall integration, metrics, and high-level
preprocessing/processing/postprocessing orchestration.
Notes
-----
This file contains **signatures and docstrings only** (no implementations) to
clarify the public API and expected array shapes. Implementations should be
vectorised and side-effect free (no mutation of ``self``), except where a method
explicitly writes into an external container (e.g., ``Trajectories``).
"""
from __future__ import annotations
from enum import Enum, auto
from dataclasses import dataclass
from scipy.stats.qmc import LatinHypercube
import numpy as np
from typing import Tuple, List, Dict, Optional
from ._rock import Rock
from ._seeder import Seeder, SeederRocksThrown
from ._slope import Slope
from ._vegetation import Vegetation
from ._trajectories import Trajectories
from ._impacts import Impacts
from ._utils import (
decompose,
sampleNormals,
getSubSamples,
setSubSamples,
scatterSubSamples,
)
[docs]
class Sampling(Enum):
"""
Enumeration of stochastic sampling methods.
Attributes:
LatinHypercube: Use Latin Hypercube Sampling.
MonteCarlo: Use simple Monte Carlo sampling.
"""
LatinHypercube = auto()
MonteCarlo = auto()
FLOOR_ELEMENT_ID = -2 # sentinel: block reached the slope's lowest elevation with no real segment hit
[docs]
class AnalysisRocksThrown(Enum):
"""
Enumeration of rock-throwing strategies in simulation.
Attributes:
DistributedFromNumberOfRocks: Rocks distributed globally among all seeders.
IndividuallyPerSeeder: Each seeder throws its specified number of rocks.
"""
DistributedFromNumberOfRocks = auto()
IndividuallyPerSeeder = auto()
[docs]
@dataclass
class SampleMaps:
rockSamples: Dict[Rock, List[int]]
seederSamples: Dict[Seeder, List[int]]
numSamples: int
[docs]
class Analysis:
"""
Refactored Analysis class that avoids adding new instance attributes at runtime.
- All configuration stays on `self`.
- Every method receives exactly the arrays/values it needs and returns outputs explicitly.
- The main loop threads the necessary arrays between steps.
"""
def __init__(self, copy: Optional["Analysis"] = None):
"""
Args:
copy (Analysis, optional): If given, copies this instance's
configuration (seeders, slope, vegetation, physics parameters,
etc.) into the new instance. This is meant for users who want
to take an existing (possibly already-run) Analysis, tweak a
setting, and re-run it from scratch -- it copies the setup
only, never simulation results: `trajectories` and `impacts`
are always created fresh and empty, regardless of whether
`copy` already holds a finished simulation.
"""
# --- Configuration / fixed attributes only ---
self.seeders: List[Seeder] = []
self._slope: Optional[Slope] = None
self._vegetation: Optional[Vegetation] = None
self.rockThrowMode = AnalysisRocksThrown.IndividuallyPerSeeder
self.numberOfRocks = 0
self.useSpecificSeed = False
self.specificSeed = 12345234
self.samplingMethod = Sampling.LatinHypercube
self.normalVelocityThreshold = 0.1
self.stoppedVelocity = 1e-5
self.scaleByVelocity = False
self.K = 9.144 # velocity scale
self.scaleByMass = False
self.C = 1000.0 # mass scale
self.considerRotationalVelocity = False
self.A = 6.096
self.B = 76.2
self.gravity = -9.80665
self.timeStep = 1e-2
self.tolerance = 1e-7
self.maxIter = 1000
self._ndim = 0
self._maps: Optional[SampleMaps] = None
if copy is not None:
for attr, value in copy.__dict__.items():
if attr in {
"seeders","_slope","_vegetation","rockThrowMode","numberOfRocks","useSpecificSeed","specificSeed",
"samplingMethod","normalVelocityThreshold","stoppedVelocity","scaleByVelocity","K",
"scaleByMass","C","considerRotationalVelocity","A","B","gravity","tolerance","maxIter","_ndim",
"timeStep"
}:
setattr(self, attr, value)
# Always fresh, even when copying another Analysis: `copy` carries over
# settings for a rerun, not a previous run's results.
self.trajectories = Trajectories()
self.impacts = Impacts()
@property
def slope(self) -> Slope:
if self._slope is None:
raise RuntimeError("Slope not set yet")
return self._slope
@slope.setter
def slope(self, value: Slope) -> None:
self._slope = value
@property
def hasVegetation(self) -> bool:
return self._vegetation is not None
@property
def vegetation(self) -> Vegetation:
if self._vegetation is None:
raise RuntimeError("Slope has no vegetation")
return self._vegetation
@vegetation.setter
def vegetation(self, value: Vegetation) -> None:
self._vegetation = value
@property
def maps(self) -> SampleMaps:
if self._maps is None:
raise RuntimeError("Sample maps not set yet")
return self._maps
@maps.setter
def maps(self, value: SampleMaps) -> None:
self._maps = value
# ----------------- Validation & setup helpers -----------------
def _checkBeforeRun(self) -> None:
if len(self.seeders) == 0:
raise ValueError('No seeders defined')
for s in self.seeders:
if not isinstance(s, Seeder):
raise ValueError('All seeders must be of type Seeder')
self._ndim = self.seeders[0].points.shape[0]
if self.slope is None:
raise ValueError('No slope defined')
if not isinstance(self.slope, Slope):
raise ValueError('Slope must be of type Slope')
if self.slope.nodes.shape[1] != self._ndim:
raise ValueError('Slope dimensionality must match seeder dimensionality')
if self.rockThrowMode == AnalysisRocksThrown.DistributedFromNumberOfRocks and self.numberOfRocks == 0:
raise ValueError('Number of rocks thrown must be greater than 0')
if self.scaleByVelocity and self.K <= 0.0:
raise ValueError('Scaling parameter for velocity must be greater than 0')
if self.scaleByMass and self.C <= 0.0:
raise ValueError('Scaling parameter for mass must be greater than 0')
def _distribute_rocks(self) -> None:
if self.rockThrowMode == AnalysisRocksThrown.DistributedFromNumberOfRocks:
for s in self.seeders:
s.numberOfRocks = self.numberOfRocks // len(self.seeders)
s.rockThrowMode = SeederRocksThrown.Overall
def _prepare_sample_maps(self) -> None:
rocktypes = list({r for s in self.seeders for r in s.rocks})
samples_per_rock: Dict[Rock, List[int]] = {r: [] for r in rocktypes}
samples_per_seeder: Dict[Seeder, List[int]] = {s: [] for s in self.seeders}
num_samples = 0
for s in self.seeders:
num_samples_init = num_samples
if s.rockThrowMode == SeederRocksThrown.Overall:
num_rocks_per_type = s.numberOfRocks // len(s.rocks)
for r in s.rocks:
samples_per_rock[r].extend(range(num_samples, num_samples + num_rocks_per_type))
num_samples += num_rocks_per_type
elif s.rockThrowMode == SeederRocksThrown.PerRockType:
for r in s.rocks:
samples_per_rock[r].extend(range(num_samples, num_samples + s.numberOfRocks))
num_samples += s.numberOfRocks
samples_per_seeder[s].extend(range(num_samples_init, num_samples))
self.maps = SampleMaps(samples_per_rock, samples_per_seeder, num_samples)
def _draw_percentiles(self, num_vars: int, num_samples: int) -> np.ndarray:
if self.samplingMethod == Sampling.LatinHypercube:
lhc = LatinHypercube(num_vars, rng=self.specificSeed) if self.useSpecificSeed else LatinHypercube(num_vars)
percentiles = lhc.random(num_samples)
else: # MonteCarlo
if self.useSpecificSeed:
np.random.seed(self.specificSeed)
percentiles = np.random.rand(num_samples, num_vars)
return percentiles.T # (num_vars, num_samples)
def _calcSlopeNormals(self, profiles: np.ndarray) -> np.ndarray:
"""
Compute per-element unit normals using self.slope.elements.
Args:
profiles: array of node coordinates. Accepts:
- (D, N) -> single geometry
- (D, N, S>=1) -> multiple samples; uses sample 0
Returns:
normals: (D, M) unit normals, where:
D is 2 (segments) or 3 (triangles), M is number of elements.
"""
D = profiles.shape[0]
elements = self.slope.elements # (M, 2) for 2D, (M, 3) for 3D
M = elements.shape[0]
if self._ndim == 2:
# 2D segments → perpendicular vector
if D != 2:
raise ValueError("2-node elements require D=2 nodes.")
i, j = elements[:, 0], elements[:, 1]
edge = profiles[:, j] - profiles[:, i] # (2, M)
n = np.stack((-edge[1], edge[0]), axis=0) # rotate 90° CCW
norm = np.linalg.norm(n, axis=0)
norm = np.where(norm == 0.0, 1.0, norm) # avoid div-by-zero
return n / norm
elif self._ndim == 3:
# 3D triangles → cross product of two edges
if D != 3:
raise ValueError("3-node elements require D=3 nodes.")
i, j, k = elements[:, 0], elements[:, 1], elements[:, 2]
p1, p2, p3 = profiles[:, i], profiles[:, j], profiles[:, k] # (3, M) each
e1 = p2 - p1
e2 = p3 - p1
n = np.cross(e1.T, e2.T).T # (3, M)
norm = np.linalg.norm(n, axis=0)
norm = np.where(norm == 0.0, 1.0, norm)
return n / norm
else:
raise ValueError("Elements must have 2 (2D) or 3 (3D) nodes.")
# ----------------- Generation phase -----------------
def _generate_samples(self) -> Tuple[
np.ndarray, np.ndarray, np.ndarray, # position, velocity, angular_velocity
np.ndarray, np.ndarray, # rock_params, material_params
np.ndarray, np.ndarray, # time, acceleration
np.ndarray, np.ndarray, # profiles, slope_normals
Optional[np.ndarray], Optional[np.ndarray], # drag_params, canopy
]:
self._distribute_rocks()
self._prepare_sample_maps()
rocktypes = list(self.maps.rockSamples.keys())
num_vars = sum(s.numRandomVariables for s in self.seeders) \
+ sum(r.numRandomVariables for r in rocktypes) \
+ sum(m.numRandomVariables for m in self.slope.materialTable) \
+ self.slope.numRandomVariables
if self._vegetation is not None:
num_vars += sum(d.numRandomVariables for d in self.vegetation.dragTable) \
+ self.vegetation.numRandomVariables
percentiles = self._draw_percentiles(num_vars, self.maps.numSamples)
# Initial kinematics
position = np.zeros((self._ndim, self.maps.numSamples))
velocity = np.zeros((self._ndim, self.maps.numSamples))
angular_velocity = np.zeros((1 if self._ndim == 2 else self._ndim, self.maps.numSamples))
count_vars = 0
count_samples = 0
for s in self.seeders:
nv = s.numRandomVariables
ns = len(self.maps.seederSamples[s])
q = percentiles[count_vars:count_vars+nv, count_samples:count_samples+ns]
pos, tra_vel, ang_vel = s.ppf(q)
position[:, self.maps.seederSamples[s]] = pos
velocity[:, self.maps.seederSamples[s]] = tra_vel
angular_velocity[:, self.maps.seederSamples[s]] = -np.radians(ang_vel)
count_vars += nv
count_samples += ns
# Rock properties
max_n_params_r = max([r.numRandomVariables for r in rocktypes]) if rocktypes else 0
rock_params = np.zeros((max_n_params_r, self.maps.numSamples))
count_samples = 0
for r in rocktypes:
nv = r.numRandomVariables
ns = len(self.maps.rockSamples[r])
q = percentiles[count_vars:count_vars+nv, count_samples:count_samples+ns]
rock_params[:nv, self.maps.rockSamples[r]] = r.ppf(q)
count_vars += nv
count_samples += ns
# Material properties (per-material, per-block)
materials = self.slope.materialTable
num_materials = len(materials)
max_n_params_m = max([m.numRandomVariables for m in materials]) if materials else 0
material_params = np.zeros((max_n_params_m, num_materials, self.maps.numSamples))
for m_id, m in enumerate(materials):
nv = m.numRandomVariables
material_params[:nv, m_id, :] = m.ppf(percentiles[count_vars:count_vars+nv])
count_vars += nv
# Time/acc/geometry
time = np.zeros(self.maps.numSamples)
acceleration = np.zeros((self._ndim, self.maps.numSamples))
acceleration[-1, :] = self.gravity
# Slope samples
nv = self.slope.numRandomVariables
profiles = self.slope.ppf(percentiles[count_vars:count_vars+nv]).transpose(1, 0, 2)
slope_normals = self._calcSlopeNormals(profiles)
count_vars += nv
drag_params = np.empty((1, 0, position.shape[1]))
canopy = np.empty((position.shape[1], 0, 1))
if self._vegetation is not None:
drags = self.vegetation.dragTable
num_drags = len(drags)
max_n_params_d = max([d.numRandomVariables for d in drags]) if drags else 0
drag_params = np.zeros((max_n_params_d, num_drags, self.maps.numSamples))
for d_id, d in enumerate(drags):
nv = d.numRandomVariables
drag_params[:nv, d_id, :] = d.ppf(percentiles[count_vars:count_vars+nv])
count_vars += nv
nv = self.vegetation.numRandomVariables
canopy = self.vegetation.ppf(percentiles[count_vars:count_vars+nv]).transpose(1, 0, 2)
count_vars += nv
return (
position, velocity, angular_velocity,
rock_params, material_params,
time, acceleration,
profiles, slope_normals,
drag_params, canopy,
)
def _sampleRoughness(self, numSamplesPerMaterial: int):
delta = np.empty((len(self.slope.materialTable), numSamplesPerMaterial), dtype=float)
for i, material in enumerate(self.slope.materialTable):
delta[i] = material.roughness.rvs(numSamplesPerMaterial)
return delta
# ----------------- Physics kernels (argument-pure) -----------------
def _addRoughness(
self,
normal,
element_id,
roughness_samples,
cum_impacts,
) -> np.ndarray:
# Impacted material id for each sample
mat_id = self.slope.materialIDs[element_id]
# batch ocurrences by element_id to efficiently sample roughness perturbations per impact
order = np.argsort(mat_id, kind="stable")
mat_sorted = mat_id[order]
is_new = np.r_[True, mat_sorted[1:] != mat_sorted[:-1]]
group_start = np.flatnonzero(is_new)
group_size = np.diff(np.r_[group_start, len(mat_sorted)])
local_sorted = np.arange(len(mat_sorted)) - np.repeat(group_start, group_size)
local_idx = np.empty_like(local_sorted)
local_idx[order] = local_sorted
# base normal angle for each impacted sample
theta0 = np.arctan2(normal[1], normal[0]) # (S,)
# sample angular perturbation
imp_id = cum_impacts[mat_id] + local_idx
imp_id %= roughness_samples.shape[1] # wrap around if run out of samples for a material
delta = roughness_samples[mat_id, imp_id]
np.add.at(cum_impacts, mat_id, 1)
theta = theta0 + np.radians(delta)
# rebuild perturbed unit normals
return np.stack((np.cos(theta), np.sin(theta)), axis=0) # (2, S)
def _impactMaterial(
self,
element_id: np.ndarray, # (S,) -1 means no touch
material_params: np.ndarray, # (A, B, S)
) -> np.ndarray:
"""
Returns per-sample material parameters with shape (A, S),
where A = #params per material, S = #samples.
Non-touching samples (element_id == -1) are set to NaN.
"""
out = np.full((material_params.shape[0], element_id.shape[0]), np.nan, dtype=material_params.dtype)
hit = element_id >= 0
if not np.any(hit):
return out
# material id for each *hit* sample
mat_ids = np.asarray(self.slope.materialIDs, dtype=int)[element_id[hit]] # (H,)
s_idx = np.nonzero(hit)[0] # (H,)
# Gather: for each hit sample s, take column (material=mat_ids[s], sample=s)
# Resulting shape: (A, H)
out[:, s_idx] = material_params[:, mat_ids, s_idx]
return out
def _impactDrag(
self,
segment_id: np.ndarray,
drag_params: np.ndarray,
) -> np.ndarray:
"""Return per-sample vegetation drag parameters with shape (A, S)."""
out = np.full((drag_params.shape[0], segment_id.shape[0]), np.nan, dtype=drag_params.dtype)
hit = segment_id >= 0
if not np.any(hit):
return out
drag_ids = np.asarray(self.vegetation.dragIdentities, dtype=int)[segment_id[hit]]
s_idx = np.nonzero(hit)[0]
# if drag_params.shape[-1] == 1:
# sample_idx = np.zeros_like(s_idx)
# elif drag_params.shape[-1] == segment_id.shape[0]:
# sample_idx = s_idx
# else:
# raise ValueError("`drag_params` last axis must be 1 or match `segment_id`.")
out[:, s_idx] = drag_params[:, drag_ids, s_idx]
return out
def _isImpacting(
self,
normal_velocity: np.ndarray,
) -> np.ndarray:
"""Return (is_impacting, is_velocity_lt_threshold)."""
return normal_velocity < 0.0
def _impacts(
self,
vn: np.ndarray, # (S,) normal velocity scalar
vt: np.ndarray, # (D, S) tangential velocity vector
w: np.ndarray, # (A, S) angular velocity vector (A=1 if D=2 else D)
mass: np.ndarray, # (S,) mass per sample
density: np.ndarray, # (S,) density per sample
rn: np.ndarray, # (S,) normal restitution per sample
rt: np.ndarray, # (S,) tangential restitution per sample
normal: np.ndarray, # (D, S) unit facet normal per sample
) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
"""Return (normal_velocity, tangential_velocity, angular_velocity) after impact."""
if self.considerRotationalVelocity:
r = np.cbrt(3 * mass / (4 * np.pi * density))
I = 2/5 * mass * r**2
den = I + mass * r**2
if self._ndim == 2:
normal = np.array([normal[0], normal[1], np.zeros_like(normal[0])]) # (3,S)
vt = np.array([vt[0], vt[1], np.zeros_like(vt[0])]) # (3,S)
w = np.array([np.zeros_like(w[0]), np.zeros_like(w[0]), w[0]]) # (3,S)
wn, wt = decompose(w, normal)
v_slip = vt + r * np.cross(normal.T, wt.T).T # (D,N)
v_slip_norm = np.linalg.norm(v_slip, axis=0)
vt_norm = np.linalg.norm(vt, axis=0) # (S,)
# Friction
frict = (1 - rt) / ((v_slip_norm / self.A)**2 + 1.2)
frict += rt
# Normal scaling
scl = np.full_like(vn, 0.0)
mask = rn != 0.0
scl[mask] = rt[mask] / ((vn[mask] / (self.B * rn[mask]))**2 + 1.0)
num = r**2 * (I * np.sum(wt**2, axis=0) + mass * np.sum(vt**2, axis=0)) * frict * scl
vt_post_norm = np.sqrt(num / den)
# direction preserved from slip
den_t = np.where(vt_norm > 0.0, vt_norm, 1.0) # avoid div-by-zero
num_t = np.where(vt_norm > 0.0, vt_post_norm, 0.0) # zero if no slip
vt_post = vt * num_t / den_t
wt_post = (1/r) * np.cross(normal.T, vt_post.T).T
w_post = wn + wt_post
if self._ndim == 2:
w_post = w_post[2][np.newaxis, :]
vt_post = vt_post[:2, :]
else:
vt_post = vt * rt
w_post = w
scln = np.full_like(vn, 1.0)
if self.scaleByVelocity:
scln *= 1 + (vn / self.K) ** 2
if self.scaleByMass:
scln *= 1 + (mass / self.C) ** 2
vn_post = -rn / scln * vn
return vn_post, vt_post, w_post
def _isSliding(
self,
vt: np.ndarray, # (3, S) tangential velocity vector on the facet
normal: np.ndarray, # (3, S) unit facet normal per sample
phi: np.ndarray, # (S,) friction angle [rad] per sample
) -> np.ndarray:
"""
Decide stick–slip state on the current facet using a per-step Coulomb test.
Returns:
is_sliding: (S,) bool -> true if in contact and sliding this step
Assumes:
- `normal` columns are unit vectors.
- Tangential driving is due to self.gravity projected onto the tangent plane.
- Static friction coefficient mu_s = tan(phi).
"""
# Gravity vector in world coords
g = np.zeros(self._ndim, dtype=float) # (D,)
g[self._ndim - 1] = self.gravity # (D,)
# Tangential speed norm
vt_norm = np.linalg.norm(vt, axis=0) # (S,)
is_stopped = vt_norm < self.stoppedVelocity # (S,) bool
# Tangential component of gravity: a_t = g - (g·n) n
gn = np.sum(g[:, None] * normal, axis=0) # (S,)
a_t = g[:, None] - normal * gn # (D,S)
at_norm = np.linalg.norm(a_t, axis=0) # (S,)
# Normal load per unit mass (>=0): N/m = max(0, -(g·n))
N_over_m = np.maximum(0.0, -gn) # (S,)
# Static friction threshold
mu_s = np.tan(np.radians(phi)) # (1,S)
# Start sliding if required tangential > mu_s * N
start_sliding = at_norm > mu_s * N_over_m # (1,S) bool
# Stick–slip decision (elementwise)
is_sliding = ~is_stopped | (is_stopped & start_sliding) # (1,S)
return is_sliding # return as (S,)
def _slide(
self,
pos, # (D,S) positions at contact
vt, # (D,S) tangential velocities; assumed dot(vt, n)==0
n, # (D,S) unit normals of contacted facets
phi, # friction angle in degrees (float or (S,))
profiles,
elem_id,
):
"""
One RK2 (midpoint) step confined to the tangent plane. Works for D=2 or 3.
Returns:
pos_new (D,S), vt_new (D,S), is_falling (S,), is_sticking (S,)
"""
dt = np.full(vt.shape[1], self.timeStep, dtype=float) # (S,)
# Gravity vector in world coords (last axis is vertical). Shape (D,)
g = np.zeros(self._ndim, dtype=float)
g[self._ndim - 1] = self.gravity
# Calculate friction coefficient
mu = np.tan(np.radians(phi)) # (S,)
# Ensure vt is strictly tangential (cheap safety)
vt = vt - n * np.sum(vt * n, axis=0, keepdims=True) # (D,S)
# Tangential component of gravity: g_t = g - (g·n) n
gn = np.sum(g[:, None] * n, axis=0) # (S,)
gt = g[:, None] - n * gn # (D,S)
gt_norm = np.linalg.norm(gt, axis=0) # (S,)
# Normal load per unit mass (>=0): N/m = max(0, -(g·n))
N_over_m = np.maximum(0.0, -gn) # (S,)
# Direction for friction:
vt_norm = np.linalg.norm(vt, axis=0) # (S,)
moving = vt_norm > self.stoppedVelocity
dir_t = np.zeros_like(vt) # (D,S)
if np.any(moving):
dir_t[:, moving] = vt[:, moving] / vt_norm[moving]
# If nearly at rest, use downhill direction (gt) so friction opposes motion correctly if it slips at all
near_rest = ~moving
use_downhill = near_rest & (gt_norm > 0)
if np.any(use_downhill):
h = gt[:, use_downhill]
hnorm = np.linalg.norm(h, axis=0)
dir_t[:, use_downhill] = h / hnorm
# Tangential acceleration with kinetic friction magnitude μ*N/m opposing dir_t
a0 = gt - dir_t * (mu * N_over_m)[None, :] # (D,S)
# ---- Projected midpoint (RK2) in the tangent plane ----
v_half = vt + 0.5 * a0 * dt[None, :]
# Re-project to tangent (numerical cleanliness)
v_half = v_half - n * np.sum(v_half * n, axis=0, keepdims=True)
# Friction direction at half step
v_half_norm = np.linalg.norm(v_half, axis=0)
half_moving = v_half_norm > self.stoppedVelocity
dir_half = np.zeros_like(v_half)
if np.any(half_moving):
dir_half[:, half_moving] = v_half[:, half_moving] / v_half_norm[half_moving]
use_downhill2 = (~half_moving) & (gt_norm > 0)
if np.any(use_downhill2):
h2 = gt[:, use_downhill2]
h2n = np.linalg.norm(h2, axis=0)
dir_half[:, use_downhill2] = h2 / h2n
a_half = gt - dir_half * (mu * N_over_m)[None, :] # (D,S)
vt_new = vt + a_half * dt[None, :]
vt_new = vt_new - n * np.sum(vt_new * n, axis=0, keepdims=True) # enforce tangency
pos_new = pos + v_half * dt[None, :]
pos_new = pos_new - n * np.sum((pos_new - pos) * n, axis=0, keepdims=True)
# ---- Guaranteed-to-stop clamp (exact stop inside the step when applicable) ----
# Predict stop time using initial parallel deceleration along dir_t.
# a_parallel0 < 0 ensures deceleration along motion; t_stop = v0 / |a_parallel0|.
dir_norm = np.linalg.norm(dir_t, axis=0)
has_dir = dir_norm > 0
a_parallel0 = np.sum(a0 * dir_t, axis=0) # (S,)
t_stop = np.full(vt.shape[1], np.inf, dtype=float)
stop_cand = has_dir & (a_parallel0 < -1e-14)
if np.any(stop_cand):
t_stop[stop_cand] = vt_norm[stop_cand] / (-a_parallel0[stop_cand])
stop_in_step = stop_cand & (t_stop <= dt)
if np.any(stop_in_step):
ts = t_stop[stop_in_step]
p0 = pos[:, stop_in_step]
v0 = vt[:, stop_in_step]
a0s = a0[:, stop_in_step]
# Exact position up to stop time with constant a0 (good approximation over small dt)
pos_new[:, stop_in_step] = p0 + v0 * ts + 0.5 * a0s * (ts**2)
vt_new[:, stop_in_step] = 0.0
dt[stop_in_step] = ts
# Sticking mask: anything not detached and effectively at rest *after
# this step* (stopped mid-step, or ended it near zero speed). Do not
# gate this on the pre-step speed: a block starting the step at rest
# must still be allowed to accelerate away from rest this step.
vt_new_norm = np.linalg.norm(vt_new, axis=0)
is_sticking = (stop_in_step | (vt_new_norm <= self.stoppedVelocity))
# Treat blocks sliding off to other elements
disp = pos_new - pos
new_element_id, alpha = self.slope.exitTime(
pos,
disp,
elem_id,
samples=profiles,
tol=self.tolerance
)
gone_to_new = (alpha < 1.0) & (alpha > 0.0)
new_element_id[~gone_to_new] = elem_id[~gone_to_new]
if np.any(gone_to_new):
alpha = alpha[gone_to_new]
pos_new[:, gone_to_new] = pos[:, gone_to_new] + disp[:, gone_to_new] * alpha
vt_new[:, gone_to_new] = vt_new[:, gone_to_new] + (vt_new[:, gone_to_new] - vt[:, gone_to_new]) * alpha
dt[gone_to_new] *= alpha
# Zero-out tiny residual tangential velocity for sticking samples
if np.any(is_sticking):
vt_new[:, is_sticking] = 0.0
return pos_new, vt_new, a0, dt, new_element_id
def _isFalling(
self,
vn: np.ndarray,
normals: np.ndarray
) -> np.ndarray:
is_falling = (vn > self.normalVelocityThreshold) | (normals[-1] <= 0.0)
return is_falling
def _fall(
self,
position: np.ndarray,
velocity: np.ndarray,
profiles: np.ndarray,
element_id: np.ndarray,
segment_id: np.ndarray,
canopy: Optional[np.ndarray] = None,
drag_params: Optional[np.ndarray] = None,
) -> Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
"""Update ballistic blocks. Returns (position, velocity, dt)."""
g = np.zeros_like(velocity)
g[-1, :] = self.gravity
elapsed_time = np.full(position.shape[1], np.nan, dtype=float)
no_vegetation = segment_id < 0
in_vegetation = segment_id >= 0
if np.any(no_vegetation):
pos, vel, acc, pro, elm, can, seg = getSubSamples(
no_vegetation,
position,
velocity,
g,
profiles,
element_id,
canopy,
segment_id
)
elm2, dt_elm = self.slope.intersectParabola(
pos,
vel,
acc,
elm,
samples=pro,
tol=self.tolerance,
)
good_elm = np.isfinite(dt_elm) & (np.abs(dt_elm) > 0.0)
if self.hasVegetation:
seg2, dt_seg = self.vegetation.intersectParabola(
pos,
vel,
acc,
seg,
samples=can,
tol=self.tolerance,
)
good_seg = np.isfinite(dt_seg) & (np.abs(dt_seg) > 0.0)
hit_elm = good_elm & (~good_seg | (dt_elm <= dt_seg))
hit_seg = good_seg & (~good_elm | (dt_seg < dt_elm))
dt = np.full_like(dt_elm, np.inf)
dt[hit_elm] = dt_elm[hit_elm]
dt[hit_seg] = dt_seg[hit_seg]
good = hit_elm | hit_seg
seg_out = seg.copy()
seg_out[hit_seg] = seg2[hit_seg]
else:
good = np.isfinite(dt_elm) & (np.abs(dt_elm) > 0.0)
hit_elm = good_elm
dt = dt_elm
seg_out = seg
elm_out = elm.copy()
elm_out[hit_elm] = elm2[hit_elm]
no_hit = ~good
if np.any(no_hit):
dt_floor = self.slope.intersectFloor(
pos[:, no_hit], vel[:, no_hit], acc[:, no_hit],
self.slope.floor, t_min=0.0, tol=self.tolerance,
)
floor_hit = np.isfinite(dt_floor) & (np.abs(dt_floor) > 0.0)
if np.any(floor_hit):
idx_floor = np.flatnonzero(no_hit)[floor_hit]
dt[idx_floor] = dt_floor[floor_hit]
elm_out[idx_floor] = FLOOR_ELEMENT_ID
good[idx_floor] = True
if np.any(good):
pos[:, good] += vel[:, good] * dt[good] + 0.5 * acc[:, good] * dt[good]**2
vel[:, good] += acc[:, good] * dt[good]
elapsed_time[no_vegetation] = dt
setSubSamples(
no_vegetation,
(pos, vel, elm_out, seg_out),
position,
velocity,
element_id,
segment_id,
)
if np.any(in_vegetation):
pos, vel, acc, pro, elm, can, seg, drag = getSubSamples(
in_vegetation,
position,
velocity,
g,
profiles,
element_id,
canopy,
segment_id,
drag_params,
)
elm2, dt_elm = self.slope.intersectDamped(
pos,
vel,
acc,
drag,
elm,
samples=pro,
tol=self.tolerance,
)
seg2, dt_seg = self.vegetation.intersectDamped(
pos,
vel,
acc,
drag,
seg,
samples=can,
tol=self.tolerance,
t_min=self.tolerance
)
good_elm = np.isfinite(dt_elm) & (np.abs(dt_elm) > 0.0)
good_seg = np.isfinite(dt_seg) & (np.abs(dt_seg) > 0.0)
hit_elm = good_elm & (~good_seg | (dt_elm <= dt_seg))
hit_seg = good_seg & (~good_elm | (dt_seg < dt_elm))
dt = np.full_like(dt_elm, np.inf)
dt[hit_elm] = dt_elm[hit_elm]
dt[hit_seg] = dt_seg[hit_seg]
good = hit_elm | hit_seg
if np.any(good):
d = drag[good] # or damping[good]
t = dt[good]
e = np.exp(-d * t)
a_d = acc[:, good] / d[None, :]
v0_minus_ad = vel[:, good] - a_d
pos[:, good] += a_d * t[None, :] + v0_minus_ad / d[None, :] * (1.0 - e)[None, :]
vel[:, good] = a_d + v0_minus_ad * e[None, :]
elapsed_time[in_vegetation] = dt
elm_out = elm.copy()
seg_out = seg.copy()
elm_out[hit_elm] = elm2[hit_elm]
seg_out[hit_seg] = seg2[hit_seg]
setSubSamples(
in_vegetation,
(pos, vel, elm_out, seg_out),
position,
velocity,
element_id,
segment_id,
)
return position, velocity, elapsed_time, element_id, segment_id
# ----------------- Orchestration -----------------
def _saveTrajectories(
self,
time: np.ndarray,
position: np.ndarray,
velocity: np.ndarray,
angular_velocity: np.ndarray,
acceleration: np.ndarray,
) -> None:
self.trajectories.addData(time, position, velocity, angular_velocity, acceleration)
[docs]
def preprocess(self):
self._checkBeforeRun()
return self._generate_samples()
[docs]
def process(self, *state_tuple):
(
position, velocity, angular_velocity,
rock_params, material_params,
time, acceleration,
profiles, slope_normals,
drag_params, canopy,
) = state_tuple
down_vec = np.zeros_like(position)
down_vec[-1] = -1.0
element_id, time_hit = self.slope.intersectParabola(
position, down_vec, np.zeros_like(position),
np.full(position.shape[1], -1, dtype=int), samples=profiles,
t_min=-np.inf, tol=self.tolerance)
# Check for block inside slope
is_on_el = element_id >= 0
if np.any(is_on_el):
pos_on_el, vel_on_el, id_on_el = getSubSamples(is_on_el,
position, velocity,
element_id
)
normal_on_el = sampleNormals(pos_on_el, id_on_el, slope_normals)
is_inside = (normal_on_el[-1] < 0) & (time_hit[is_on_el] > self.tolerance)
if np.any(is_inside):
dlt_h = -time_hit[is_on_el][is_inside]
dlt_v = np.sqrt(2*self.gravity*dlt_h)
pos_on_el[-1, is_inside] += dlt_h
vel_on_el[-1, is_inside] += dlt_v
position[:, is_on_el] = pos_on_el
velocity[:, is_on_el] = vel_on_el
# Elements under blocks
element_id[np.abs(time_hit) > self.tolerance] = -1
# Segments above blocks
segment_id = np.full(position.shape[1], -1, dtype=int)
if self._vegetation is not None:
segment_id, _ = self.vegetation.verticalProjection(
position,
segment_id,
direction=1,
samples=canopy,
)
# Sample roughness
roughness_samples = self._sampleRoughness(numSamplesPerMaterial=position.shape[1]*100//len(self.slope.materialTable)) # oversample to avoid running out of roughness samples for highly impacted materials
cum_impacts = np.zeros(len(self.slope.materialTable), dtype=int)
it = -1
while True:
it += 1
# save
self._saveTrajectories(time, position, velocity, angular_velocity, acceleration)
# mapping to segments
drag_samples = self._impactDrag(segment_id, drag_params)[0]
# mapping to elements
is_on_el = element_id >= 0
is_falling = (~is_on_el) & (element_id != FLOOR_ELEMENT_ID)
is_sliding = np.full_like(is_on_el, False, dtype=bool)
if np.any(is_on_el):
# get samples on elements
pos_on_el, vel_on_el, acc_on_el, w_on_el, rp_on_el, t_on_el, id_on_el = getSubSamples(is_on_el,
position, velocity, acceleration, angular_velocity,
rock_params, time, element_id,
)
# materials at impact locations
mp_on_el = self._impactMaterial(id_on_el, material_params)
# get normal and tangential velocities
normal_on_el = sampleNormals(pos_on_el, id_on_el, slope_normals)
normal_on_el = self._addRoughness(normal_on_el, id_on_el, roughness_samples, cum_impacts)
vn_on_el, vt_on_el = decompose(vel_on_el, normal_on_el)
an_on_el, at_on_el = decompose(acc_on_el, normal_on_el)
is_low = np.abs(vn_on_el) < self.normalVelocityThreshold # check if velocity before impact is less then threshold
vn_on_el[is_low] = 0.0 # force parallel when vn is nearly zero
# check if impacting
is_imp = self._isImpacting(vn_on_el)
if np.any(is_imp):
# get impacting samples
t_imp, pos_imp, id_imp, vn_imp, vt_imp, w_imp, m_imp, d_imp, rn_imp, rt_imp, normal_imp = getSubSamples(is_imp,
t_on_el, pos_on_el, id_on_el,
vn_on_el, vt_on_el, w_on_el,
rp_on_el[0], rp_on_el[1], mp_on_el[0], mp_on_el[1],
normal_on_el
)
# impact update
vn_post, vt_post, w_post = self._impacts(
vn_imp, vt_imp, w_imp,
m_imp, d_imp,
rn_imp, rt_imp,
normal_imp
)
# is_imp/vn_imp/etc. are variable-size, order-losing subsets of impacting blocks;
# their count and identities change each iteration. Scatter them onto the full,
# fixed-size block set, filling non-impacting blocks with NaNs.
# This gives Impacts one fixed-shape row per block, like Trajectories,
# while preserving block identity.
(full_is_imp,) = scatterSubSamples(is_on_el, False, is_imp)
t_full, pos_full, normal_full, vn_imp_full, vt_imp_full, w_imp_full, \
vn_post_full, vt_post_full, w_post_full, rn_full, rt_full = scatterSubSamples(
full_is_imp, np.nan,
t_imp, pos_imp, normal_imp,
vn_imp, vt_imp, w_imp,
vn_post, vt_post, w_post,
rn_imp, rt_imp,
)
(id_full,) = scatterSubSamples(full_is_imp, -1, id_imp)
self.impacts.addData(
t_full, pos_full, normal_full, id_full,
vn_imp_full, vt_imp_full, w_imp_full,
vn_post_full, vt_post_full, w_post_full,
rn_full, rt_full,
)
setSubSamples(is_imp, (vn_post, vt_post, w_post), vn_on_el, vt_on_el, w_on_el)
# check if sliding
is_low |= np.abs(vn_on_el) < self.normalVelocityThreshold # check if post impact velocity is nearly zero
is_sliding_on_el = np.full_like(is_low, False, dtype=bool)
if np.any(is_low):
vt_low, normal_low, phi_low = getSubSamples(is_low, vt_on_el, normal_on_el, mp_on_el[2])
setSubSamples(is_low, (self._isSliding(vt_low, normal_low, phi_low),), is_sliding_on_el)
# slide update (apply only to sliding blocks by slicing inputs)
if np.any(is_sliding_on_el):
pos_s, vt_s, t_s, normal_s, phi_s, pro_s, id_s = getSubSamples(is_sliding_on_el,
pos_on_el, vt_on_el, t_on_el,
normal_on_el, mp_on_el[2],
profiles, id_on_el
)
pos_s, vt_s, at_s, dt_s, id_s = self._slide(pos_s, vt_s, normal_s, phi_s, pro_s, id_s)
t_s += dt_s
setSubSamples(is_sliding_on_el,
(pos_s, vt_s, at_s, .0, .0, t_s, id_s),
pos_on_el, vt_on_el, at_on_el, vn_on_el, an_on_el, t_on_el, id_on_el
)
# rotate back to Cartesian
vel_on_el = vt_on_el + normal_on_el * vn_on_el[None, :]
acc_on_el = at_on_el + normal_on_el * an_on_el[None, :]
# check if falling
is_falling_on_el = (~is_low & (vn_on_el > 0.0)) | (normal_on_el[-1] <= 0.0)
is_falling_on_el &= ~is_sliding_on_el
setSubSamples(is_on_el,
(is_sliding_on_el, is_falling_on_el, pos_on_el, vel_on_el, acc_on_el, w_on_el, t_on_el, id_on_el),
is_sliding, is_falling, position, velocity, acceleration, angular_velocity, time, element_id
)
# fall update
if np.any(is_falling):
pos_fall, vel_fall, pro_fall, elem_fall, seg_fall, can_fall, drag_fall = getSubSamples(
is_falling,
position,
velocity,
profiles,
element_id,
segment_id,
canopy,
drag_samples,
)
pos_fall, vel_fall, dt, elem_fall, seg_fall = self._fall(
pos_fall,
vel_fall,
pro_fall,
elem_fall,
seg_fall,
canopy=can_fall,
drag_params=drag_fall,
)
good = np.isfinite(dt) & (np.abs(dt) > 0.0)
idx = np.flatnonzero(is_falling)
idx_keep = idx[good]
idx_drop = idx[~good]
is_falling[idx_drop] = False # stop falling if numerical issue or end of slope
position[...,idx_keep] = pos_fall[...,good]
velocity[...,idx_keep] = vel_fall[...,good]
acceleration[...,idx_keep] = 0.0
acceleration[-1, idx_keep] = self.gravity
time[...,idx_keep] += dt[...,good]
element_id[...,idx_keep] = elem_fall[...,good]
segment_id[...,idx_keep] = seg_fall[...,good]
# termination
if not (np.any(is_falling) or np.any(is_sliding)):
break
if self.maxIter > 0 and it >= self.maxIter:
break
return (
position, velocity, angular_velocity,
rock_params, material_params,
time, acceleration,
profiles, slope_normals,
)
[docs]
def postprocess(self, rock_params: np.ndarray) -> None:
self.trajectories.simulationDone()
self.impacts.simulationDone()
mass = rock_params[0, :]
density = rock_params[1, :]
r = np.cbrt(3 * mass / (4 * np.pi * density))
inertia = 2/5 * mass * r**2
self.trajectories.mass = mass
self.trajectories.inertia = inertia
self.trajectories.floor = self.slope.floor
[docs]
def run(self) -> None:
state_tuple = self.preprocess()
state_tuple = self.process(*state_tuple)
self.postprocess(state_tuple[3])