Integration and Computation

Integration and Computation#

This module provides the core classes for performing Lagrangian trajectory integrations and computing finite-time Lyapunov exponents.

Base Integration#

class lagrangian.core.Integration#

The base class for all integration methods. Handles the time evolution of particles in a velocity field.

__init__(self: lagrangian.core.Integration, start_time: lagrangian::DateTime, end_time: lagrangian::DateTime, delta_t: boost::posix_time::time_duration, field: lagrangian.core.Field) → None#

Default constructor

Parameters:

Key Methods

  • compute(): Executes the integration process to compute particle trajectories.

  • fetch(): Prepares necessary data or performs tasks required before advancing to the next time step.

  • iterator(): Generates an iterator that defines the time steps for the integration period.

Examples

Basic integration setup:

import lagrangian

# Create a field and integration object
field = lagrangian.field.TimeSerie("config.ini")
integration = lagrangian.Integration(
    start_time=datetime(2010, 1, 1),
    end_time=datetime(2010, 1, 10),
    delta_t=timedelta(hours=1),
    field=field
)

# Compute trajectory
result = integration.compute(it=integration.iterator(), x0=10.0, y0=45.0)
compute(self: lagrangian.core.Integration, it: lagrangian.core.Iterator, x0: SupportsFloat, y0: SupportsFloat) → object#

Calculate the new position of the particle

Parameters:

  • it (lagrangian.Iterator) – Iterator

  • x0 (float) – Longitude in degrees

  • y0 (float) – Latitude in degrees

Returns:

the position updated otherwise None if new position is undefined

Return type:

tuple, optional

fetch(self: lagrangian.core.Integration, date: lagrangian::DateTime) → None#

Perform the tasks before a new time step (eg load grids required)

Parameters:

date (datetime.datetime) – Time step to process

iterator(self: lagrangian.core.Integration) → lagrangian.core.Iterator#

Return an iterator that describes the integration period

Returns:

the iterator that describes the integration period

Return type:

lagrangian.Iterator

Path Integration#

class lagrangian.core.Path#

Bases: lagrangian.Integration

Specialized integration for computing particle trajectories (paths) over time.

__init__(self: lagrangian.core.Path, start_time: lagrangian::DateTime, end_time: lagrangian::DateTime, delta_t: boost::posix_time::time_duration, field: lagrangian.core.Field) → None#

Default constructor

Parameters:

Integration Modes#

class lagrangian.core.IntegrationMode#

Enumeration of available integration modes:

  • FSLE: Finite-Size Lyapunov Exponents

  • FTLE: Finite-Time Lyapunov Exponents

Finite Lyapunov Exponents#

class lagrangian.core.FiniteLyapunovExponentsIntegration#

Specialized integration class for computing finite-time Lyapunov exponents.

Finite Size Lyapunov Exponent (FSLE) is a scalar local notion that represents the rate of separation of initially neighbouring particles over a finite-time window \([t_0, t_0 + T]\), where \(T\) is the time two particles need to be advected in order to be separated from a given distance \(d\).

Let \(x(t) = x(t; x_0, t_0)\) be the position of a lagrangian particle at time \(t\), started at \(x_0\) at \(t = t_0\) and advected by the time-dependent fluid flow \(u(x, t)\).

The Forward Finite-Time Lyapunov Exponent at a point \(x_0\) and for the advection time \(T\) is defined as the growth factor of the norm of the perturbation \(dx_0\) started around \(x_0\) and advected by the flow after the finite advection time \(T\).

Maximal stretching occurs when \(dx_0\) is aligned with the eigenvector associated with the maximum eigenvalue \(\delta_{\text{max}}\) of the Cauchy-Green strain tensor \(\Delta\):

\[\Delta = \left[ \nabla \Phi_0^T (x_0) \right]^* \left[ \nabla \Phi_0^T (x_0) \right]\]

where \(\Phi_0^T : x_0 \rightarrow x(t, x_0, t_0)\) is the flow map of the advection equation: it links the location \(x_0\) of a lagrangian particle at \(t = t_0\) to its position \(x(t, x_0, t_0)\) at time \(t\). (* denotes the transposition operator).

FTLE is defined as:

\(\sigma = \frac{1}{2T} \log \left( \lambda_{\text{max}}(\Delta) \right)\)

Finite-Size Lyapunov Exponent is similarly defined: \(T\) is chosen so that neighbouring particles separate from a given distance \(d\).

ComputeExponents function implements the computation of the Lyapunov exponents based on maximal and minimal eigenvalues and orientation of eigenvectors of \(\Delta\) given the elements of \(\nabla \Phi_0^T\) matrix.

For more details see:

  1. G. Haller, Lagrangian coherent structures and the rate of strain in two-dimensional turbulence Phys. Fluids A 13 (2001) 3365-3385 (http://georgehaller.com/reprints/approx.pdf) Remark: In this paper, FTLE is referred to as the Direct Lyapunov Exponent (DLE)

  2. http://mmae.iit.edu/shadden/LCS-tutorial/FTLE-derivation.html

__init__(self: lagrangian.core.FiniteLyapunovExponentsIntegration, start_time: lagrangian::DateTime, end_time: lagrangian::DateTime, delta_t: boost::posix_time::time_duration, mode: lagrangian.core.IntegrationMode, min_sepration: typing.SupportsFloat, delta: typing.SupportsFloat, field: lagrangian.core.Field = None) → None#

Default constructor

Parameters:

  • start_time (datetime.datetime) – Start time of the integration

  • end_time (datetime.datetime) – End date of the integration

  • delta_t (datetime.timedelta) – Time interval

  • mode (lagrangian.IntegrationMode)

  • min_separation (float) – Minimal separation in degrees

  • delta (float) – The gap between two consecutive dots, in degrees, of the grid

  • field (lagrangian.Field) – Field to use for computing the velocity of a point.

Examples

Computing FSLE:

fsle_integration = lagrangian.FiniteLyapunovExponentsIntegration(
    start_time=datetime(2010, 1, 1),
    end_time=datetime(2010, 1, 10),
    delta_t=timedelta(hours=1),
    mode=lagrangian.IntegrationMode.FSLE,
    min_separation=0.1,  # in degrees
    delta=0.01,          # initial separation
    field=field
)
class lagrangian.core.FiniteLyapunovExponents#

Container for finite-time Lyapunov exponent results.

Attributes

  • lambda1: First Lyapunov exponent

  • lambda2: Second Lyapunov exponent

  • theta1: Angle of first eigenvector

  • theta2: Angle of second eigenvector

  • delta_t: Time taken to reach final separation

  • final_separation: Final separation distance

Numerical Integration#

class lagrangian.core.RungeKutta#

Fourth-order Runge-Kutta integrator for solving ordinary differential equations.

__init__(self: lagrangian.core.RungeKutta, arg0: SupportsFloat, arg1: lagrangian.core.Field) → None#

Default constructor

Parameters:

  • size_of_interval (float) – Number of time interval

  • field (lagrangian.Field) – Field reader

Key Methods

  • compute(): Perform the Runge-Kutta integration step

compute(self: lagrangian.core.RungeKutta, t: lagrangian::DateTime, x: typing.SupportsFloat, y: typing.SupportsFloat, cell: lagrangian.core.CellProperties = <lagrangian.core.CellProperties object at 0x7f695df0bab0>) → tuple#

Move a point in a veocity field

Parameters:

  • t (datetime.datetime) – Date

  • x (float) – Longitude in degrees

  • y (float) – Latitude in degrees

  • cell (lagrangian.CellProperties) – Cell properties of the grid used for the interpolation

Returns:

A tuple that contains the longitude/latitude after the shift or None if the velocity field is undefined for the requested position

Return type:

tuple, optional

class lagrangian.core.Iterator#

Iterator for time stepping through integration periods.

Coordinate Systems#

class lagrangian.core.CoordinatesType#

Enumeration of coordinate system types:

  • CARTESIAN: Cartesian coordinates (x, y)

  • SPHERICAL_EQUATORIAL: Spherical coordinates (longitude, latitude)

class lagrangian.core.UnitType#

Enumeration of unit types:

  • METRIC: Metric units (meters)

  • ANGULAR: Angular units (degrees)

Contents