pastax.metric

Along-trajectory metrics for evaluating Lagrangian simulation quality.

Every metric here is a broadcasting function of two trajectories, f(y, y_ref), whose last two axes are (time, 2) and whose leading axes broadcast under standard NumPy/JAX rules. A metric therefore works transparently on a single trajectory (T, 2), an ensemble (S, T, 2), or any batched/broadcast pair — no ensemble flag required.

Because they satisfy the same broadcasting contract as the kernels in pastax.score, these metrics double as energy-score kernels, e.g. energy_score(forecast, obs, kernel=liu_index, reduce="last").

separation_distance¶

pastax.metric.separation_distance(y, y_ref)

Point-wise great-circle distance between y and y_ref.

Parameters

• y (Float[jaxlib._jax.Array, '*batch time 2']) – Predicted trajectory/-ies, shape (..., T, 2).

• y_ref (Float[jaxlib._jax.Array, '*#batch time 2']) – Reference trajectory, shape (..., T, 2); broadcasts against y.

Returns

Distance at each time step in metres, shape (..., T).

Return type

Float[jaxlib._jax.Array, ‘*batch time’]

normalized_separation_distance¶

pastax.metric.normalized_separation_distance(y, y_ref, min_length=0)

Instantaneous separation normalised by cumulative reference arc length.

$$\mathrm{NSD}_t = \frac{\mathrm{sep\_dist}_t}{\mathrm{trav\_dist}_t}$$

(1)

where $\mathrm{sep\_dist}_t$ is the separation distance at time $t$ and $\mathrm{trav\_dist}_t$ is the reference trajectory travel distance at time $t$.

Parameters

• y (Float[jaxlib._jax.Array, '*batch time 2']) – Predicted trajectory/-ies, shape (..., T, 2).

• y_ref (Float[jaxlib._jax.Array, '*#batch time 2']) – Reference trajectory, shape (..., T, 2); broadcasts against y.

• min_length (float) – Minimum length added to the denominator to avoid division by zero, or to soften the metric for very short trajectories.

Returns

Dimensionless normalised separation, shape (..., T).

Return type

Float[jaxlib._jax.Array, ‘*batch time’]

liu_index¶

pastax.metric.liu_index(y, y_ref, min_length=0)

Liu & Weisberg (2011) normalised cumulative Lagrangian separation.

$$\mathrm{Liu}_t = \frac{\operatorname{cumsum}(\mathrm{sep\_dist})_t} {\operatorname{cumsum}(\mathrm{trav\_dist})_t}$$

(2)

where $\mathrm{sep\_dist}_t$ is the separation distance at time $t$ and $\mathrm{trav\_dist}_t$ is the reference trajectory travel distance at time $t$. The denominator is thus a double cumulative sum of the per-step distances.

Reference: Liu & Weisberg (2011), J. Geophys. Res.

Parameters

• y (Float[jaxlib._jax.Array, '*batch time 2']) – Predicted trajectory/-ies, shape (..., T, 2).

• y_ref (Float[jaxlib._jax.Array, '*#batch time 2']) – Reference trajectory, shape (..., T, 2); broadcasts against y.

• min_length (float) – Minimum length added to the denominator to avoid division by zero, or to soften the metric for very short trajectories.

Returns

Dimensionless Liu Index, shape (..., T).

Return type

Float[jaxlib._jax.Array, ‘*batch time’]