_trajectories module

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.

class pyrockfall._trajectories.Trajectories[source]

Bases: object

Records and processes the time history of block positions, velocities, accelerations, and energy during rockfall simulations.

Provides utilities for data analysis, exporting, and visualization.

addData(time, positions, velocities, angular_velocities, accelerations)[source]

Adds a new time step of simulation data to the internal history.

Parameters:
  • 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).

simulationDone()[source]

Finalizes the data collection by converting all internal lists to NumPy arrays.

property timeHistory: ndarray

Returns: np.ndarray: Time history of the simulation.

property positionHistory: ndarray

Returns: np.ndarray: Position history of the simulation.

property velocityHistory: ndarray

Returns: np.ndarray: Velocity history of the simulation.

property angularVelocityHistory: ndarray

Returns: np.ndarray: Angular velocity history of the simulation.

property accelerationHistory: ndarray

Returns: np.ndarray: Acceleration history of the simulation.

property numberOfBlocks: int

Returns: int: Number of blocks simulated.

property endpoints

Returns: np.ndarray: Final positions of all blocks.

property startTime

Returns: np.ndarray: Start time for each block.

property stopTime

Returns: np.ndarray: Stop time for each block.

position(time)[source]

Returns the position of the blocks at the specified time(s).

Parameters:

time (float or np.ndarray) – Time(s) at which to compute the position.

Returns:

Interpolated positions (dim x time x blocks).

Return type:

np.ndarray

velocity(time, angVel=False)[source]

Returns the velocity of the blocks at the specified time(s).

Parameters:
  • time (float or np.ndarray) – Time(s) at which to compute the velocity.

  • angVel (bool) – If True, also return angular velocity.

Returns:

Velocities or (velocities, angular velocities).

Return type:

np.ndarray or tuple

acceleration(time)[source]

Returns the acceleration of the blocks at the specified time(s).

Parameters:

time (float or np.ndarray) – Time(s) at which to compute the acceleration.

Returns:

Acceleration values (dim x time x blocks).

Return type:

np.ndarray

collector(points, normals)[source]

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:

First crossing times (collectors x blocks), NaN if no crossing.

Return type:

np.ndarray

plot(ax=None, **kwargs)[source]

Plots the 2D projection of the trajectory of all blocks.

Parameters:
  • ax (matplotlib.axes.Axes, optional) – Axis to plot on.

  • **kwargs – Additional arguments passed to ax.plot.

Returns:

The axis with plotted trajectories.

Return type:

matplotlib.axes.Axes

reasonStopped()[source]
Returns:

Reason each block stopped (default: “Stopped”).

Return type:

list of str

writeTXT(basename, time_step, compress=True)[source]

Exports simulation results to plain-text files in PyRockfall-compatible format.

Parameters:
  • basename (str or list) – Base file name or directory.

  • time_step (float) – Temporal resolution of output.

  • compress (bool) – Whether to use gzip compression.

Returns:

Paths to output files.

Return type:

list of str

readTXT(basename)[source]

Imports trajectories from TXT or TXT.GZ files.

Parameters:

basename (str or list) – File path or prefix.

Returns:

Files successfully read.

Return type:

list of str

writeNPZ(basename, time_step=None)[source]

Saves the trajectory data to a compressed .npz file.

Parameters:
  • basename (str) – Output path (without .npz).

  • time_step (float, optional) – Resample time step.

Returns:

Path to the saved file.

Return type:

str

readNPZ(filename)[source]

Loads trajectory data from a .npz file.

Parameters:

filename (str) – Path to the NPZ file.