"""
Trajectories data structure for pyrockfall
==========================================
Records and processes the time history of block positions, velocities,
accelerations, and energy during rockfall simulations.
Provides tools for analysis, file export/import, and visualization of
simulation results.
"""
import numpy as np
from numbers import Real
import gzip
import os
[docs]
class Trajectories:
"""
Records and processes the time history of block positions, velocities,
accelerations, and energy during rockfall simulations.
Provides utilities for data analysis, exporting, and visualization.
"""
def __init__(self):
"""
Initializes an empty Trajectories instance for storing simulation history.
Sets default values for mass, inertia, floor height, and gravity.
"""
self._time_history = []
self._position_history = []
self._velocity_history = []
self._angular_velocity_history = []
self._acceleration_history = []
self.mass = 0.0
self.inertia = 0.0
self.floor = 0.0
self.gravity = 9.80665
def __del__(self):
"""
Resets all internal history and physical parameters to their default values.
"""
self._time_history = []
self._position_history = []
self._velocity_history = []
self._angular_velocity_history = []
self._acceleration_history = []
self.mass = 0.0
self.inertia = 0.0
self.floor = 0.0
self.gravity = 9.80665
[docs]
def addData(self, time, positions, velocities, angular_velocities, accelerations):
"""
Adds a new time step of simulation data to the internal history.
Args:
time (array-like): Timestamps for each block.
positions (array-like): Block positions (dim x blocks).
velocities (array-like): Block velocities (dim x blocks).
angular_velocities (array-like): Angular velocities for each block.
accelerations (array-like): Block accelerations (dim x blocks).
"""
# Ensure histories are lists before appending
if not isinstance(self._time_history, list):
self._time_history = list(self._time_history)
if not isinstance(self._position_history, list):
self._position_history = list(self._position_history)
if not isinstance(self._velocity_history, list):
self._velocity_history = list(self._velocity_history)
if not isinstance(self._angular_velocity_history, list):
self._angular_velocity_history = list(self._angular_velocity_history)
if not isinstance(self._acceleration_history, list):
self._acceleration_history = list(self._acceleration_history)
self._time_history.append(np.array(time))
self._position_history.append(np.array(positions))
self._velocity_history.append(np.array(velocities))
self._angular_velocity_history.append(np.array(angular_velocities))
self._acceleration_history.append(np.array(accelerations))
[docs]
def simulationDone(self):
"""
Finalizes the data collection by converting all internal lists to NumPy arrays.
"""
self._time_history = np.asarray(self._time_history)
self._position_history = np.asarray(self._position_history)
self._velocity_history = np.asarray(self._velocity_history)
self._angular_velocity_history = np.asarray(self._angular_velocity_history)
self._acceleration_history = np.asarray(self._acceleration_history)
@property
def timeHistory(self) -> np.ndarray:
"""
Returns:
np.ndarray: Time history of the simulation.
"""
return np.asarray(self._time_history)
@property
def positionHistory(self) -> np.ndarray:
"""
Returns:
np.ndarray: Position history of the simulation.
"""
return np.asarray(self._position_history)
@property
def velocityHistory(self) -> np.ndarray:
"""
Returns:
np.ndarray: Velocity history of the simulation.
"""
return np.asarray(self._velocity_history)
@property
def angularVelocityHistory(self) -> np.ndarray:
"""
Returns:
np.ndarray: Angular velocity history of the simulation.
"""
return np.asarray(self._angular_velocity_history)
@property
def accelerationHistory(self) -> np.ndarray:
"""
Returns:
np.ndarray: Acceleration history of the simulation.
"""
return np.asarray(self._acceleration_history)
@property
def numberOfBlocks(self) -> int:
"""
Returns:
int: Number of blocks simulated.
"""
return self.timeHistory.shape[1]
@property
def endpoints(self):
"""
Returns:
np.ndarray: Final positions of all blocks.
"""
return np.array(self.positionHistory[-1, :, :])
@property
def startTime(self):
"""
Returns:
np.ndarray: Start time for each block.
"""
return self.timeHistory[0]
@property
def stopTime(self):
"""
Returns:
np.ndarray: Stop time for each block.
"""
return self.timeHistory[-1]
[docs]
def position(self, time):
"""
Returns the position of the blocks at the specified time(s).
Args:
time (float or np.ndarray): Time(s) at which to compute the position.
Returns:
np.ndarray: Interpolated positions (dim x time x blocks).
"""
time = np.asarray(time)
if time.ndim == 0: # Single float value
time = np.full((1, self.positionHistory.shape[2]), time)
elif time.ndim == 1: # 1D array
time = np.tile(time[:, np.newaxis], (1, self.positionHistory.shape[2]))
num_requested_times, num_samples = time.shape
space_dim = self.positionHistory.shape[1]
pos = np.zeros((space_dim, num_requested_times, num_samples))
for sample in range(num_samples):
sample_time = time[:, sample]
time_history_sample = self.timeHistory[:, sample]
# Find the indices of the time instants just before the desired times
indices = np.searchsorted(time_history_sample, sample_time, side='right')
indices = np.clip(indices, 1, len(time_history_sample) - 1)
# Calculate the time difference between instants
Dt = time_history_sample[indices] - time_history_sample[indices-1]
# Get the positions, velocities, and accelerations at the found indices
pos_sample = np.transpose(self.positionHistory[indices-1, :, sample])
vel_sample = np.transpose(self.velocityHistory[indices, :, sample])
acc_sample = np.transpose(self.accelerationHistory[indices, :, sample])
vel_sample -= acc_sample * Dt
# Calculate the time differences
dt = sample_time - time_history_sample[indices-1]
dt = np.where(dt < Dt, dt, Dt)
# Calculate the new positions
pos[:, :, sample] = pos_sample + vel_sample * dt + 0.5 * acc_sample * dt**2
pos = np.where(np.isnan(time), time, pos)
if num_requested_times == 1:
pos = pos[:, 0, :]
return pos
[docs]
def velocity(self, time, angVel=False):
"""
Returns the velocity of the blocks at the specified time(s).
Args:
time (float or np.ndarray): Time(s) at which to compute the velocity.
angVel (bool): If True, also return angular velocity.
Returns:
np.ndarray or tuple: Velocities or (velocities, angular velocities).
"""
time = np.asarray(time)
if time.ndim == 0: # Single float value
time = np.full((1, self.positionHistory.shape[2]), time)
elif time.ndim == 1: # 1D array
time = np.tile(time[:, np.newaxis], (1, self.positionHistory.shape[2]))
num_requested_times, num_samples = time.shape
space_dim = self.positionHistory.shape[1]
vel = np.zeros((space_dim, num_requested_times, num_samples))
w = np.zeros((space_dim if space_dim == 3 else 1, num_requested_times, num_samples))
for sample in range(num_samples):
sample_time = time[:, sample]
time_history_sample = self.timeHistory[:, sample]
# Find the indices of the time instants just before the desired times
indices = np.searchsorted(time_history_sample, sample_time, side='right')
indices = np.clip(indices, 1, len(time_history_sample) - 1)
# Calculate the time difference between instants
Dt = time_history_sample[indices] - time_history_sample[indices-1]
# Get the positions, velocities, and accelerations at the found indices
vel_sample = np.transpose(self.velocityHistory[indices, :, sample])
acc_sample = np.transpose(self.accelerationHistory[indices, :, sample])
vel_sample -= acc_sample * Dt
# Calculate the time differences
dt = sample_time - time_history_sample[indices-1]
dt = np.where(dt < Dt, dt, Dt)
# Calculate the new velocities
vel[:, :, sample] = vel_sample + acc_sample * dt
w[:, :, sample] = np.transpose(self.angularVelocityHistory[indices, :, sample])
vel = np.where(np.isnan(time), time, vel)
w = np.where(np.isnan(time), time, w)
if num_requested_times == 1:
vel = vel[:, 0, :]
w = w[0, :]
if angVel:
return vel, w
else:
return vel
[docs]
def acceleration(self, time):
"""
Returns the acceleration of the blocks at the specified time(s).
Args:
time (float or np.ndarray): Time(s) at which to compute the acceleration.
Returns:
np.ndarray: Acceleration values (dim x time x blocks).
"""
time = np.asarray(time)
if time.ndim == 0: # Single float value
time = np.full((1, self.positionHistory.shape[2]), time)
elif time.ndim == 1: # 1D array
time = np.tile(time[:, np.newaxis], (1, self.positionHistory.shape[2]))
num_requested_times, num_samples = time.shape
space_dim = self.positionHistory.shape[1]
acc = np.zeros((space_dim, num_requested_times, num_samples))
for sample in range(num_samples):
sample_time = time[:, sample]
time_history_sample = self.timeHistory[:, sample]
# Find the indices of the time instants just before the desired times
indices = np.searchsorted(time_history_sample, sample_time, side='right')
indices = np.clip(indices, 1, len(time_history_sample) - 1)
# Get the positions, velocities, and accelerations at the found indices
acc_sample = np.transpose(self.accelerationHistory[indices, :, sample])
# Calculate the new velocities
acc[:, :, sample] = acc_sample
acc = np.where(np.isnan(time), time, acc)
if num_requested_times == 1:
acc = acc[:, 0, :]
return acc
[docs]
def collector(self, points, normals):
"""
Compute the first intersection time between each block's trajectory and
each collector plane/line (works for 2D and 3D trajectories alike).
Parameters:
points (np.ndarray): Points on each collector (num_dim, num_collectors)
normals (np.ndarray): Normal vectors defining collector orientation (num_dim, num_collectors)
Returns:
np.ndarray: First crossing times (collectors x blocks), NaN if no crossing.
"""
points = np.asarray(points)
normals = np.asarray(normals)
if points.ndim == 1:
points = points[:, None]
normals = normals[:, None]
T, D, P = self.positionHistory.shape
C = points.shape[1]
# Expand dims for broadcasting
# (T, D, P, 1) - (1, D, 1, C) -> (T, D, P, C)
positions = self.positionHistory[:, :, :, None]
points = points[None, :, None, :]
normals = normals[None, :, None, :]
# Compute projection of vector from collector point to particle position onto normal
rel_pos = positions - points # (T, D, P, C)
projections = np.einsum('tdpc,tdpc->tpc', rel_pos, normals) # (T, P, C)
# Detect sign changes over time (crossings)
sign_changes = np.diff(np.sign(projections), axis=0)
t_idx, p_idx, c_idx = np.where(sign_changes != 0)
crossing_times = np.full((C, P), np.nan)
if t_idx.size == 0:
return crossing_times
# Prepare segment data for interpolation from t_idx to t_idx+1
t1 = t_idx + 1
# Dt = t1 - t0
t0 = self.timeHistory[t_idx, p_idx]
t1_val = self.timeHistory[t1, p_idx]
Dt = t1_val - t0
# Get final position p1 (stored), and time t1
vf = self.velocityHistory[t1, :, p_idx].T # (D, N)
a = self.accelerationHistory[t1, :, p_idx].T # (D, N)
v0 = vf - a * Dt # Recovered initial velocity
p0 = self.positionHistory[t_idx, :, p_idx].T # (D, N)
pts_cross = points[0, :, 0, c_idx].T # (D, N)
nrm_cross = normals[0, :, 0, c_idx].T # (D, N)
dp = p0 - pts_cross
A = 0.5 * np.einsum('ij,ij->j', a, nrm_cross)
B = np.einsum('ij,ij->j', v0, nrm_cross)
Cc = np.einsum('ij,ij->j', dp, nrm_cross)
A_is_zero = np.isclose(A, 0.0)
dt = np.full_like(A, np.nan)
# Linear case: A == 0 → dt = -C / B
with np.errstate(divide='ignore', invalid='ignore'):
dt_linear = -Cc[A_is_zero] / B[A_is_zero]
dt[A_is_zero] = np.where(dt_linear > 0, dt_linear, np.nan)
# Quadratic case: A ≠ 0
if np.any(~A_is_zero):
A_q = A[~A_is_zero]
B_q = B[~A_is_zero]
C_q = Cc[~A_is_zero]
discriminant = B_q**2 - 4*A_q*C_q
discriminant[discriminant < 0] = 0.0
sqrt_disc = np.sqrt(discriminant)
with np.errstate(divide='ignore', invalid='ignore'):
dt1 = (-B_q - sqrt_disc) / (2*A_q)
dt2 = (-B_q + sqrt_disc) / (2*A_q)
dt_quad = np.vstack([dt1, dt2])
dt_quad[dt_quad < 0] = np.nan
dt[~A_is_zero] = np.nanmin(dt_quad, axis=0)
valid = ~np.isnan(dt)
t_cross = t0[valid] + dt[valid]
# A block can cross a collector's plane more than once (e.g. it
# bounces back across it later). `t_idx`, and therefore every array
# derived from it above (including c_idx[valid]/p_idx[valid]/t_cross
# here), is already ordered by increasing segment index because
# np.where scans axis 0 (time) outermost. Segments are disjoint,
# non-overlapping time intervals, so this is equivalently an
# ascending-time order. Assigning in reverse means that, for any
# (collector, block) pair hit more than once, the later crossings
# are written first and the earliest crossing is written last -
# and therefore wins, without needing an explicit sort.
# NB: the reversal must be materialised with .copy() - assigning
# through a negative-stride *view* does not reliably preserve the
# write order for duplicate fancy indices.
c_rev = c_idx[valid][::-1].copy()
p_rev = p_idx[valid][::-1].copy()
t_rev = t_cross[::-1].copy()
crossing_times[c_rev, p_rev] = t_rev
return crossing_times
[docs]
def plot(self, ax=None, **kwargs):
"""
Plots the 2D projection of the trajectory of all blocks.
Args:
ax (matplotlib.axes.Axes, optional): Axis to plot on.
**kwargs: Additional arguments passed to `ax.plot`.
Returns:
matplotlib.axes.Axes: The axis with plotted trajectories.
"""
try:
import matplotlib.pyplot as plt
except ImportError as e:
raise ImportError(
"Plotting requires matplotlib. Please install it with `pip install matplotlib`."
) from e
if ax is None:
fig, ax = plt.subplots()
x, y = self.__call__()
ax.plot(x, y, **kwargs)
return ax
[docs]
def reasonStopped(self):
"""
Returns:
list of str: Reason each block stopped (default: "Stopped").
"""
return ["Stopped"] * self.numberOfBlocks
def __call__(self, numPoints=100):
"""
Computes interpolated trajectories between start and stop time.
Args:
numPoints (int): Number of interpolation points.
Returns:
np.ndarray: Interpolated positions.
"""
time = np.linspace(self.startTime, self.stopTime, numPoints)
return self.position(time)
[docs]
def writeTXT(self, basename, time_step, compress=True):
"""
Exports simulation results to plain-text files in PyRockfall-compatible format.
Args:
basename (str or list): Base file name or directory.
time_step (float): Temporal resolution of output.
compress (bool): Whether to use gzip compression.
Returns:
list of str: Paths to output files.
"""
ind = ' '
axes = ('x', 'y', 'z')
ti = self.startTime
tf = self.stopTime
num_time_steps = np.ceil((tf - ti) / time_step).astype(int)
time = np.linspace(self.startTime, self.stopTime, num_time_steps.max())
x = self.position(time)
v, w = self.velocity(time, angVel=True)
reason = self.reasonStopped()
a = self.acceleration(time)
kt = self.mass * np.sum(v**2, axis=0) / 2
kr = self.inertia * w**2 / 2
u = self.mass * self.gravity * (x[1, :, :] - self.floor)
e = kt + kr + u
num_dim, num_time_steps, num_samples = x.shape
axes = axes[:num_dim]
files = []
name_count = -1
prev_name = ''
for s in range(num_samples):
if isinstance(basename, str):
filename = basename
else:
filename = basename[s]
if filename != prev_name:
name_count = -1
prev_name = filename
name_count += 1
ext = 'txt.gz' if compress else 'txt'
if os.path.isdir(filename):
filename = os.path.join(filename, f'{name_count}.{ext}')
else:
filename = f'{filename}{name_count}.{ext}'
f = gzip.open(filename, 'wt') if compress else open(filename, 'w')
files.append(filename)
f.write('PyRockfall Results File:\n')
f.write(ind+'version: 2.1\n')
f.write('\n')
f.write(ind+'path results data:\n')
f.write(ind+'complete: yes\n')
f.write(ind+f'end reason: {reason[s]}\n')
f.write(ind+f'Total events: {self.positionHistory.shape[0]}\n')
if isinstance(self.mass, Real):
f.write(ind+f'rock mass: {self.mass}\n')
else:
f.write(ind+f'rock mass: {self.mass[s]}\n')
if isinstance(self.inertia, Real):
f.write(ind+f'rock inertia: {self.inertia}\n')
else:
f.write(ind+f'rock inertia: {self.inertia[s]}\n')
f.write(ind+f'rock start time: {ti[s]}\n')
for id, axis in enumerate(axes):
f.write(ind+f'rock start Position {axis}: {self.positionHistory[0, id, s]}\n')
f.write(ind+f'rock start rotation: 0.0\n')
for id, axis in enumerate(axes):
f.write(ind+f'rock start velocity {axis}: {self.velocityHistory[0, id, s]}\n')
if len(axes) == 2:
f.write(ind+f'rock start angular velocity: {self.angularVelocityHistory[0, 0, s]}\n')
else:
for id, axis in enumerate(axes):
f.write(ind+f'rock start angular velocity {axis}: {self.angularVelocityHistory[0, id, s]}\n')
f.write(ind+'NOTES: Surface Type: 0-SEGMENT, 1-CORNER, 2-BARRIER, 5-FOREST BOUNDARY, 6/7-BERM, 8/9-INF. BERM\n')
txt_pos = ', '.join([f'position {a}' for a in axes])
txt_vel = ', '.join([f'velocity {a}' for a in axes])
txt_acc = ', '.join([f'acceleration {a}' for a in axes])
f.write(ind+f'time, {txt_pos}, rotation, {txt_vel}, angular velocity, {txt_acc}, angular acceleration, translational energy, rotational energy, potential energy, total energy, bounce height\n')
if ti[s] < tf[s]:
zeros_col = np.zeros((num_time_steps, 1))
data_matrix = np.column_stack([
time[:, s], # time
x[:, :, s].T, # position x/y/z
zeros_col, # rotation
v[:, :, s].T, # velocity x/y/z
w[:, s], # angular velocity
a[:, :, s].T, # acceleration x/y/z
zeros_col, # angular acceleration
kt[:, s], # translational energy
kr[:, s], # rotational energy
u[:, s], # potential energy
e[:, s], # total energy
zeros_col # bounce height
])
# Format all rows with 9 decimal places and join them
lines = [ind + ','.join(f'{val:.9f}' for val in row) + '\n' for row in data_matrix]
f.writelines(lines)
f.close()
return files
[docs]
def readTXT(self, basename):
"""
Imports trajectories from TXT or TXT.GZ files.
Args:
basename (str or list): File path or prefix.
Returns:
list of str: Files successfully read.
"""
ind = ' '
if isinstance(basename, str):
basename = [basename]
files = []
for name in basename:
name_count = -1
while True:
name_count += 1
if os.path.isdir(name):
# If name is a directory, look for files in that directory
filename = os.path.join(name, f'{name_count}')
else:
filename = f'{name}{name_count}'
for ext in ('txt', 'txt.gz'):
if os.path.isfile(filename+f'.{ext}'):
filename = filename+f'.{ext}'
break
else:
# If no file found, break the loop
break
files.append(filename)
if len(files) == 0:
return []
files_to_remove = []
# Read the files
time_history = []
position_history = []
velocity_history = []
angular_velocity_history = []
acceleration_history = []
mass = []
inertia = []
floor = []
for filename in files:
if filename.endswith('.gz'):
with gzip.open(filename, 'rt') as f:
lines = f.readlines()
else:
with open(filename, 'r') as f:
lines = f.readlines()
# Extract data from the file
# Initialize variables
time = []
positions = []
velocities = []
angular_velocities = []
accelerations = []
mass_value = None
inertia_value = None
floor_value = []
has_time_series = False
# Read the file line by line
for line in lines:
# Skip empty lines
if not line.strip():
continue
# Check for specific keywords and extract data accordingly
if line.startswith(ind+'rock mass:'):
mass_value = float(line.split(':')[1].strip())
elif line.startswith(ind+'rock inertia:'):
inertia_value = float(line.split(':')[1].strip())
if has_time_series:
# Read time series data
parts = line.split(',')
ndim = 3 if len(parts) > 15 else 2
time.append(float(parts[0].strip()))
positions.append([float(p.strip()) for p in parts[1:ndim+1]])
v0 = 2 + ndim
w = v0 + ndim
velocities.append([float(v.strip()) for v in parts[v0:w]])
angular_velocities.append(float(parts[w].strip()))
accelerations.append([float(a.strip()) for a in parts[w+1:w+1+ndim]])
if mass_value is None:
mass_value = []
if inertia_value is None:
inertia_value = []
if isinstance(mass_value, list):
id = 13 if ndim == 3 else 10
kt = float(parts[id].strip())
v_2 = np.sum(np.array(velocities[-1])**2)
if v_2 > 0:
mass_value.append(2*kt/v_2)
if isinstance(inertia_value, list):
id = 14 if ndim == 3 else 11
kr = float(parts[id].strip())
w_2 = angular_velocities[-1]**2
if w_2 > 0:
inertia_value.append(2*kr/w_2)
id = 15 if ndim == 3 else 12
U = float(parts[id].strip())
if isinstance(mass_value, list):
h = U / (self.gravity * mass_value[-1])
else:
h = U / (self.gravity * mass_value)
floor_value.append(h - positions[-1][1])
elif line.startswith(ind+'time, position'):
has_time_series = True
# End of file processing
if len(time) == 0:
print(f'Warning: No time series data found in {filename}. Skipping this file.')
files_to_remove.append(filename)
continue
time_history.append(time)
position_history.append(positions)
velocity_history.append(velocities)
angular_velocity_history.append(angular_velocities)
acceleration_history.append(accelerations)
if isinstance(mass_value, list):
mass_value = np.mean(mass_value)
mass.append(mass_value)
if isinstance(inertia_value, list):
inertia_value = np.mean(inertia_value)
inertia.append(inertia_value)
floor.append(np.mean(floor_value))
# Check if any file was read
if len(time_history) == 0:
print('Warning: No valid files found.')
return []
# Store the data in the object
self._time_history = np.transpose(np.asarray(time_history), (1, 0))
self._position_history = np.transpose(np.asarray(position_history), (1, 2, 0))
self._velocity_history = np.transpose(np.asarray(velocity_history), (1, 2, 0))
self._angular_velocity_history = np.transpose(np.asarray(angular_velocity_history), (1, 0))
self._acceleration_history = np.transpose(np.asarray(acceleration_history), (1, 2, 0))
self.mass = np.asarray(mass)
self.inertia = np.asarray(inertia)
self.floor = np.asarray(floor)
# Remove files that were not read
for filename in files_to_remove:
files.remove(filename)
return files
[docs]
def writeNPZ(self, basename, time_step=None):
"""
Saves the trajectory data to a compressed .npz file.
Args:
basename (str): Output path (without .npz).
time_step (float, optional): Resample time step.
Returns:
str: Path to the saved file.
"""
if os.path.isdir(basename):
basename = os.path.join(basename, 'trajectories')
if basename.endswith('.npz'):
basename = basename.split('.npz')[0]
if time_step is not None:
num_time_steps = np.ceil((self.stopTime - self.startTime) / time_step).astype(int)
t = np.linspace(self.startTime, self.stopTime, num_time_steps.max())
x = self.position(t)
v, w = self.velocity(t, angVel=True)
a = self.acceleration(t)
else:
t = self.timeHistory
x = np.transpose(self.positionHistory, (1, 0, 2))
v = np.transpose(self.velocityHistory, (1, 0, 2))
w = np.transpose(self.angularVelocityHistory, (1, 0, 2))
a = np.transpose(self.accelerationHistory, (1, 0, 2))
np.savez_compressed(
basename,
time_history=t,
position_history=x,
velocity_history=v,
angular_velocity_history=w,
acceleration_history=a,
mass=self.mass,
inertia=self.inertia,
floor=self.floor,
gravity=self.gravity
)
return basename + '.npz'
[docs]
def readNPZ(self, filename):
"""
Loads trajectory data from a .npz file.
Args:
filename (str): Path to the NPZ file.
"""
data = np.load(filename)
self._time_history = data['time_history']
self._position_history = np.transpose(data['position_history'], (1, 0, 2))
self._velocity_history = np.transpose(data['velocity_history'], (1, 0, 2))
self._angular_velocity_history = data['angular_velocity_history']
self._acceleration_history = np.transpose(data['acceleration_history'], (1, 0, 2))
self.mass = data['mass']
self.inertia = data['inertia']
self.floor = data['floor']
self.gravity = data['gravity']