Simulate Runout Paths Using Random Walk and PCM Physics

Simulates the runout paths of mass movements (e.g., debris flows, snow avalanches) from one or more source points using a physically-informed random walk model. Each path incorporates slope-based directionality, lateral dispersion, and energy loss based on the Perla-Cheng-McClung (PCM) velocity model.

Usage

runoutSim(
  dem,
  xy,
  mu = 0.1,
  md = 40,
  int_vel = 1,
  slp_thresh = 30,
  exp_div = 3,
  per_fct = 2,
  walks = 100,
  source_connect = FALSE,
  connect_feature = NULL
)

Arguments

dem: SpatRaster. A digital elevation model (DEM), ideally sink-filled and hydrologically correct.
xy: Numeric vector or matrix. Coordinates of one or more source points (e.g., cbind(x, y)).
mu: Numeric. Basal friction coefficient used in the PCM velocity model (default = 0.1).
md: Numeric. Mass-to-drag ratio used in the PCM model to control deceleration from air drag and terrain resistance.
int_vel: Numeric. Initial velocity for PCM model.
slp_thresh: Numeric. Minimum slope (in degrees) required for particle movement. Particles stop when local slope falls below this value.
exp_div: Numeric. Lateral dispersion exponent controlling spread of paths away from steepest descent. Higher values = less lateral dispersion.
per_fct: Numeric. Persistence factor controlling how strongly particles follow the current downslope direction. Values >1 increase directional inertia.
walks: Integer. Number of random walk particles to simulate per source point (default = 1000).
source_connect: Logical. If TRUE, particles are flagged based on whether they intersect a defined connectivity feature (e.g., stream channel).
connect_feature: SpatRaster. Optional raster of connectivity features created using makeConnFeature(). Required if source_connect = TRUE.

Value

A list of simulated particle paths. Each element contains a matrix or list of stepwise information (e.g., coordinates, step index, velocity, slope, and connectivity).

Details

This function simulates gravity-driven runout from user-defined source cells. Particle paths evolve through a random walk process biased by terrain slope and lateral spread rules. At each step, the PCM velocity model updates particle speed based on slope, friction (mu), and mass-to-drag ratio (md).

Paths terminate when slope falls below slp_thresh, or particles encounter terrain conditions that no longer allow continued downhill movement.

PCM Model

The PCM model (Perla-Cheng-McClung) describes velocity as a balance between gravitational acceleration, frictional resistance, and air drag. Higher md values imply greater momentum and less deceleration from drag.

Applicability

This model can be applied to a variety of gravity-driven mass movements such as debris flows, snow avalanches, and other similar phenomena. The random walk approach, combined with the PCM velocity model, makes it highly versatile for simulating different types of runout based on the underlying physical principles of mass movement.

Connectivity

If source_connect = TRUE, simulated paths are checked for intersection with a connectivity feature raster. This enables downstream analysis of connectivity probability (connToRaster()), or flow velocity surfaces (velocityToRaster()).