Maps and Analysis

Maps and Analysis#

Classes for computing and analyzing maps of Lagrangian diagnostics.

Map Properties#

class lagrangian.core.MapProperties#

Defines the spatial grid properties for computing Lagrangian maps.

__init__(self: lagrangian.core.MapProperties, nx: SupportsInt, ny: SupportsInt, x_min: SupportsFloat, y_min: SupportsFloat, step: SupportsFloat) → None#

Default constructor

Parameters:

nx (int) – Number of longitudes
ny (int) – Number of latitudes
x_min (float) – Minimal longitude
y_min (float) – Minimal latitude
step (float) – Step between two consecutive longitudes and latitudes

Methods

x_axis(): Get array of x-coordinates
y_axis(): Get array of y-coordinates

Properties

nx, ny: Grid dimensions
x_min, y_min: Grid origin
step: Grid spacing

Examples

Creating a map grid:

import lagrangian

# Define 100x100 grid covering 10°×10° region
map_props = lagrangian.MapProperties(
    nx=100, ny=100,
    x_min=0.0, y_min=40.0,
    step=0.1  # 0.1° spacing
)

# Get coordinate arrays
x_coords = map_props.x_axis()
y_coords = map_props.y_axis()

x_axis(self: lagrangian.core.MapProperties) → numpy.typing.NDArray[numpy.float64]#: Gets the x-axis values

y_axis(self: lagrangian.core.MapProperties) → numpy.typing.NDArray[numpy.float64]#: Gets the y-axis values

property nx#: Number of longitudes in the grid

property ny#: Number of latitudes in the grid

property x_min#: Minimal longitude

property y_min#: Minimal latitude

property step#: Step between two consecutive longitudes and latitudes

Lyapunov Exponent Maps#

class lagrangian.core.MapOfFiniteLyapunovExponents#

Computes maps of finite-time Lyapunov exponents over a spatial grid.

__init__(self: lagrangian.core.MapOfFiniteLyapunovExponents, map_properties: lagrangian.core.MapProperties, fle: lagrangian.core.FiniteLyapunovExponentsIntegration, stencil: lagrangian.core.Stencil = <Stencil.TRIPLET: 0>, reader: lagrangian.core.Reader = None) → None#

Default constructor

Parameters:

map_properties (lagrangian.core.MapProperties) – Properties of the regular grid to create
fle (lagrangian.core.FiniteLyapunovExponents) – FLE handler
stencil (lagrangian.core.Stencil) – Type of stencil used for the calculation of finite difference.
reader (lagrangian.core.reader.NetCDF) – NetCDF used to locate the hidden values (eg continents). These cells identified will not be taken into account during the calculation process, in order to accelerate it. If this parameter is not defined, all cells will be processed in the calculation step.

Key Methods

compute(): Compute FTLE/FSLE for all grid points
map_of_lambda1(): Get map of first Lyapunov exponent
map_of_lambda2(): Get map of second Lyapunov exponent
map_of_theta1(): Get map of first eigenvector angles
map_of_theta2(): Get map of second eigenvector angles
map_of_delta_t(): Get map of integration times
map_of_final_separation(): Get map of final separations

Examples

Computing FSLE maps:

import lagrangian
import numpy as np
from datetime import datetime, timedelta

# Setup field and integration
field = lagrangian.core.field.TimeSerie("config.ini")

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,
    delta=0.01,
    field=field
)

# Define spatial grid
map_props = lagrangian.MapProperties(
    nx=50, ny=50,
    x_min=5.0, y_min=40.0,
    step=0.2
)

# Compute FSLE map
fsle_map = lagrangian.MapOfFiniteLyapunovExponents(
    map_properties=map_props,
    fle=fsle_integration,
    stencil=lagrangian.Stencil.QUINTUPLET
)

# Run computation (parallel)
fsle_map.compute(num_threads=4)

# Extract results
lambda1_map = fsle_map.map_of_lambda1(fill_value=np.nan)
lambda2_map = fsle_map.map_of_lambda2(fill_value=np.nan)
time_map = fsle_map.map_of_delta_t(fill_value=np.nan)

compute(self: lagrangian.core.MapOfFiniteLyapunovExponents, num_threads: SupportsInt = 0) → None#

Compute the map

Parameters:: num_threads (int, optional) – The number of threads to use for the computation. If 0 all CPUs are used. If 1 is given, no parallel computing code is used at all, which is useful for debugging. Defaults to 0.

map_of_lambda1(self: lagrangian.core.MapOfFiniteLyapunovExponents, fill_value: SupportsFloat = nan) → numpy.typing.NDArray[numpy.float64]#

Get the map of the FLE associated to the maximum eigenvalues of Cauchy-Green strain tensor

Parameters:: fill_value (float) – value used for missing cells
Returns:: The map of λ₁ (unit 1/sec)
Return type:: numpy.ndarray

map_of_lambda2(self: lagrangian.core.MapOfFiniteLyapunovExponents, fill_value: SupportsFloat = nan) → numpy.typing.NDArray[numpy.float64]#

Get the map of the FLE associated to the minimum eigenvalues of Cauchy-Green strain tensor

Parameters:: fill_value (float) – value used for missing cells
Returns:: The map of λ₂ (unit 1/sec)
Return type:: numpy.ndarray

map_of_theta1(self: lagrangian.core.MapOfFiniteLyapunovExponents, fill_value: SupportsFloat = nan) → numpy.typing.NDArray[numpy.float64]#

Get the map of the orientation of the eigenvectors associated to the maximum eigenvalues of Cauchy-Green strain tensor

Parameters:: fill_value (float) – value used for missing cells
Returns:: The map of θ₁ (unit degrees)
Return type:: numpy.ndarray

map_of_theta2(self: lagrangian.core.MapOfFiniteLyapunovExponents, fill_value: SupportsFloat = nan) → numpy.typing.NDArray[numpy.float64]#

Get the map of the orientation of the eigenvectors associated to the minimum eigenvalues of Cauchy-Green strain tensor

Parameters:: fill_value (float) – value used for missing cells
Returns:: The map of θ₂ (unit degrees)
Return type:: numpy.ndarray

map_of_delta_t(self: lagrangian.core.MapOfFiniteLyapunovExponents, fill_value: SupportsFloat = nan) → numpy.typing.NDArray[numpy.float64]#

Get the map of the advection time

Parameters:

fill_value (float) – value used for missing cells

Returns:

The map of advection time (unit number of seconds elapsed: since the beginning of the integration)

Return type:

numpy.ndarray

map_of_final_separation(self: lagrangian.core.MapOfFiniteLyapunovExponents, fill_value: SupportsFloat = nan) → numpy.typing.NDArray[numpy.float64]#

Get the map of the effective final separation distance (unit degree)

Parameters:: fill_value (float) – value used for missing cells
Returns:: The map of the effective final separation distance (unit degree)

Utilities and Helpers#

Additional utility classes and functions.

Cell Properties#

class lagrangian.core.CellProperties#

Properties of grid cells for interpolation and computation.

Methods

none(): Create empty cell properties

static none() → lagrangian.core.CellProperties#: Return the representation of a cell unhandled

Time Handling#

class lagrangian.core.DateTime#

Date and time representation for integration.

Methods

to_datetime(): Convert to Python datetime object

to_datetime() → datetime.datetime#

Convert to Python datetime object.

Returns:: Python datetime representation of this DateTime

class lagrangian.core.TimeDuration#

Methods

to_timedelta(): Convert to Python timedelta object

to_timedelta() → datetime.timedelta#

Convert to Python timedelta object.

Returns:: Python timedelta representation of this TimeDuration

Debug and Information#

lagrangian.core.debug(message: str) → None#

Display a debugging message

Parameters:: message (str) – Message to display

Print debug message to console.

lagrangian.core.set_verbose(value: bool) → None#

Enable or disable verbose mode

Parameters:: value (bool) – True to enable verbose mode

Enable or disable verbose output.

Parameters

value: Boolean flag for verbose mode

lagrangian.core.version() → str#

Return the version number

Returns:: Version number
Return type:: str

Get library version string.

Returns

Version string in format “major.minor.patch”

Examples

Checking version and enabling debug output:

import lagrangian

print(f"Lagrangian library version: {lagrangian.version()}")

# Enable verbose output
lagrangian.set_verbose(True)

# Print debug message
lagrangian.debug("Starting computation...")

Maps and Analysis

Contents

Maps and Analysis#

Map Properties#

Lyapunov Exponent Maps#

Utilities and Helpers#

Cell Properties#

Time Handling#

Debug and Information#