trace#

Particle tracing utilities.

Implements pathline tracing for capture zone visualization.

Functions#

traceline(ml, xstart, ystart, zstart, hstepmax[, ...])

Function to trace one pathline.

timtraceline(ml, xstart, ystart, zstart, hstepmax[, ...])

Deprecated alias for traceline().

tracelines(ml, xstart, ystart, zstart, hstepmax[, ...])

Function to trace multiple pathlines.

timtracelines(ml, xstart, ystart, zstart, hstepmax[, ...])

Deprecated alias for tracelines().

Module Contents#

traceline(ml, xstart, ystart, zstart, hstepmax, vstepfrac=0.2, tmax=1000000000000.0, nstepmax=100, win=None, silent=False)[source]#

Function to trace one pathline.

Parameters:

  • ml (Model object) – model to which the element is added

  • xstart (scalar) – x-coordinate of starting location

  • ystart (scalar) – y-coordinate of starting location

  • zstart (scalar) – z-coordinate of starting location

  • hstepmax (scalar) – maximum horizontal step size [L]

  • vstepfrac (scalar) – maximum vertical step as fraction of layer thickness

  • tmax (scalar) – maximum travel time

  • nstepmax (int) – maximum number of steps

  • win (list) – list with [xmin, xmax, ymin, ymax]

  • silent (string) – if ‘.’, prints dot upon completion of each traceline

Returns:

Result dictionary with keys:

  • trace: np.array of (x, y, z, t) along the path

  • message: termination message

  • complete: whether tracing stopped at a terminal condition

  • total_travel_time: final time in the trace

  • layers: model layer index for each trace segment / step

Return type:

dict

timtraceline(ml, xstart, ystart, zstart, hstepmax, vstepfrac=0.2, tmax=1000000000000.0, nstepmax=100, win=None, silent=False, returnlayers=False, *, metadata=False)[source]#

Deprecated alias for traceline().

Deprecated since version Use: traceline() instead. This function will be removed in a future version. It returns only the trace array, or (trace, layers) when returnlayers is True (not the full dict).

tracelines(ml, xstart, ystart, zstart, hstepmax, vstepfrac=0.2, tmax=1000000000000.0, nstepmax=100, silent='.', win=None)[source]#

Function to trace multiple pathlines.

Parameters:

  • ml (Model object) – model to which the element is added

  • xstart (array) – x-coordinates of starting locations

  • ystart (array) – y-coordinates of starting locations

  • zstart (array) – z-coordinates of starting locations

  • hstepmax (scalar) – maximum horizontal step size [L]

  • vstepfrac (scalar) – maximum vertical step as fraction of layer thickness

  • tmax (scalar) – maximum travel time

  • nstepmax (int) – maximum number of steps

  • silent (string) – if ‘.’, prints dot upon completion of each traceline

  • win (list) – list with [xmin, xmax, ymin, ymax]

Returns:

One result dict per starting point, in the same form as traceline() (each dict always includes a layers entry).

Return type:

list of dict

timtracelines(ml, xstart, ystart, zstart, hstepmax, vstepfrac=0.2, tmax=1000000000000.0, nstepmax=100, silent='.', win=None, *, metadata=False, returnlayers=False)[source]#

Deprecated alias for tracelines().

Deprecated since version Use: tracelines() instead. This function will be removed in a future version. It returns a list of trace arrays, or a list of (trace, layers) pairs when returnlayers is True (not result dicts).