LCS-Parcels

Lagrangian coherent structure (LCS) diagnostics on top of Parcels: deformation gradient grad F, Cauchy-Green tensor (grad F)^T grad F, its eigen-analysis, and the finite-time Lyapunov exponent (FTLE), following Haller (2015), doi:10.1146/annurev-fluid-010313-141322.

This package contains no Parcels code. It emits a particle set to release and ingests the advected positions to diagnose. You run Parcels (or anything else) in between.

Install

Python 3.12 or newer:

$ pip install lcs_parcels

For unreleased main:

$ pip install git+https://github.com/geomar-od-lagrange/lcs_parcels.git

To work on the package code instead, or to run the examples, use pixi:

$ pixi install
$ pixi run test                       # run the test suite, including the Parcels-free example
$ pixi run -e examples get-data       # download the CMEMS subset the Cabo Verde examples read (once)
$ pixi run -e examples test-examples  # execute every example against the current API

Quickstart

import numpy as np
from lcs_parcels import NeighborSeedGrid

# 1. Lay out a seed grid and emit a particle set.
seed = NeighborSeedGrid.from_axes(
    lon=np.linspace(-25.0, -20.0, 6),
    lat=np.linspace(15.0, 20.0, 5),
)
lon_0, lat_0 = seed.to_parcels_pset()

# 2. Advect (lon_0, lat_0) from t0 to t1 with Parcels, which is not part of
#    this package, and collect the final positions.

# 3. Ingest the advected positions into a flow map and diagnose it.
flowmap = seed.pset_to_flowmap(
    lon=lon_advected, lat=lat_advected, t0=t0, t1=t1
)
ftle = flowmap.ftle()  # xr.DataArray of the FTLE (1/s) on the (i, j) grid

# 4. Or go straight to the hyperbolic LCS curves, FTLE field included.
lcs = flowmap.hyperbolic_lcs()

Lon/lat pairs are keyword-only throughout, so a transposed call raises TypeError. Every returned array carries long_name and units, so ftle.plot(x="lon_grid", y="lat_grid") labels itself.

print(flowmap) gives a one-line summary and flowmap.ds gives the dataset itself:

>>> print(flowmap)
<NeighborFlowMap 6x5 grid, lon -25.00..-20.00, lat 15.00..20.00, t0 2020-01-01T00:00:00, T +7.0 days>

Examples

Examples live under examples/. Each is a jupytext triplet (.py/.md/.ipynb) sharing one source, and the rendered .ipynb is the one to read. They are listed in increasing scope:

• get_data downloads the CMEMS subset the Cabo Verde notebooks read. Run once, before them. Needs CMEMS credentials.
• example_grid_pset exercises the package API on its own, without Parcels.
• cabo_verde_ftle shows the Parcels v4 wiring and the FTLE from CMEMS currents.
• cabo_verde_lcs builds repelling and attracting LCS as strain tensor lines.
• cabo_verde_lcs_evolution evolves an extracted LCS as a material curve.

The Parcels examples need the examples pixi environment (pixi install -e examples) and a CMEMS currents file you save yourself. See examples/README.md for the reading order and the data.

Scope

Rectilinear grids with a monotonic lon_grid axis, away from the poles. The limits, and the accuracy of a separation, are in docs/api.md and docs/numerics.md.

License

MIT