Python API¶

Library allows to compute Lagrangian analysis with Python.

Physical quantity units¶

class lagrangian.LatitudeUnit¶

Bases: object

__call__(unit)¶

Checks if the unit can define this type of axis.

Parameters: unit (str) – Unit to check

Returns: if the unit can define this type of axis

Return type: bool

class lagrangian.LongitudeUnit¶

Bases: object

__call__(unit)¶

Checks if the unit can define this type of axis.

Parameters: unit (str) – Unit to check

Returns: if the unit can define this type of axis

Return type: bool

class lagrangian.AxisType¶

Type of axis

kUnknown¶: Unknown axis type

kLatitude¶: Latitude axis

kLongitude¶: Longitude axis

kTime¶: Temporal axis

kX¶: X axis

kY¶: Y axis

Spatial and temporal axes¶

class lagrangian.Axis(points, axis_type, unit=None)¶

Bases: object

A coordinate axis is a Variable that specifies one of the coordinates of a Variable’s values.

Mathematically it is a vector function F from index space to Sn:

F(i, j, k,...) -> (S1, S2, ...Sn)

where i, j, k are integers, and S is the set of reals (R).

The components of F are just its coordinate axes:

F = (A1, A2, ...An)
 A1(i, j, k, ...) -> S1
 A2(i, j, k, ...) -> S1
 An(i, j, k, ...) -> Sn

Parameters:	points (numpy.ndarray) – axis values axis_type (lagrangian.AxisType) – axis type unit (str) – Unit of the axis

increment¶: Get increment value if is_regular

start¶: Get starting value if is_regular

type¶: Get type of axis

get_coordinate_value(index)¶

Get the ith coordinate value.

Parameters:	index (int) – which coordinate. Between 0 and get_num_elements()-1 inclusive
Returns:	coordinate value
Return type:	float

get_min_value()¶

Get the minimum coordinate value

Returns:	minimum coordinate value
Return type:	float

get_max_value()¶

Get the maximum coordinate value

Returns:	maximum coordinate value
Return type:	float

get_num_elements()¶

Get the number of values for this axis

Returns:	Get the number of values for this axis
Return type:	int

find_index(coordinate)¶

Given a coordinate position, find what element contains it. This mean that:

edge[i] <= pos < edge[i+1] (if values are ascending)
edge[i] > pos >= edge[i+1] (if values are descending)

Parameters:	coordinate (float) – position in this coordinate system
Returns:	the index of the axis if the point is contained in the axis or -1 if it is located outside of the axis
Return type:	int

find_index_bounded(coordinate)¶

Given a coordinate position, find what element contains it or is closest to it.

Parameters:	coordinate (float) – position in this coordinate system
Returns:	index of the grid point containing it or -1 if outside grid area
Return type:	int

normalize(coordinate, circle)¶

Standardization of longitude

Parameters:

coordinate (float) – position in this coordinate system
circle (float) – value of the trigonometric circle in this coordinate system

Returns:

longitude between:

[self.get_min_value(), self.get_max_value() + circle]

Return type:

float

convert(unit)¶

Converts the axis data from unit self.units to unit. Can be called only if the property self.units is not None

Parameters:	unit (str) – the new unit

find_indexes(coordinate)¶

Given a coordinate position, find grids elements around it. This mean that:

points[i0] <= coordinate < points[i1]

Parameters:	coordinate (float) – position in this coordinate system
Returns:	i0 and i1 if the coordinate is inside the axis otherwise None
Return type:	tuple

__eq__(rhs):: Returns self == rhs.

__ne__(rhs):: Returns self != rhs.

Dates and time¶

class lagrangian.DateTime(value)¶

Bases: object

A datetime object is a single object containing all the information from a date object and a time object. Like a date object, datetime assumes the current Gregorian calendar extended in both directions; like a time object, datetime assumes there are exactly 3600*24 seconds in every day.

Parameters:	value (datetime.datetime, str) – Value used to build the new instance

__call__()¶

Get the Python representation of the instance

Returns:	Python object that represents the instance
Return type:	datetime.datetime

Velocity fields¶

class lagrangian.Field(*args)¶

Bases: object

Abstract class defining a field where it is possible to calculate a speed

unit_type¶: Unit type used by this field.

get_unit()¶

Unit used by this field.

Returns:	unit
Return type:	str

class lagrangian.PythonField(unit_type=cpp_lagrangian.kMetric)¶

Bases: lagrangian.Field

Python base class for implementing the class a field where it is possible to calculate a speed.

To implement this class, you must implement the method compute respecting the following signature:

def compute (double t, double x, double y):
    return (u, v, defined)

where u and v are the velocities computed, and defined a boolean indicating whether the calculated velocities are valid or not.

Parameters:	unit_type (lagrangian.UnitType) – Unit field

class lagrangian.Vonkarman(a=1, w=35.06, r0=0.35, tc=1, alpha=2, y0=0.3, l=2, u0=14)¶

Bases: lagrangian.Field

Vonkarman field

compute(t, x, y)¶

Compute the field to the spatiotemporal position wanted

Parameters:	t (float) – Time expressed as a number of seconds elapsed since 1970. x (float) – Longitude expressed as degree y (float) – Latitude expressed as degree
Returns:	u & v interpolated
Return type:	tuple

Numerical grids¶

class lagrangian.CellProperties¶

Bases: object

Cell properties of the grid used for the interpolation.

contains(x, y)¶

Test if the coordinate is in the cell.

Parameters:	x (float) – Longitude y (float) – Latitude
Returns:	True if the coordinate is in the cell.
Return type:	bool

update(x0, x1, y0, y1, ix0, ix1, iy0, iy1)¶

Update the cell properties

Parameters:

x0 (float) – First longitude of the cell in degrees
x1 (float) – Last longitude of the cell in degress
y0 (float) – First latitude of the cell in degrees
y1 (float) – Last latitude of the cell in degrees
ix0 (int) – Index of the first longitude in the grid
ix1 (int) – Index of the last longitude in the grid
iy0 (int) – Index of the first latitude in the grid
iy1 (int) – Index of the last latitude in the grid

iy1¶

Get the index of the last latitude in the grid

Returns:	The index of the last latitude
Type:	int

x0¶

Get the first longitude of the cell

Returns:	The first longitude
Type:	float

x1¶

Get the last longitude of the cell

Returns:	The last longitude
Type:	float

y0¶

Get the first latitude of the cell

Returns:	The first latitude
Type:	float

y1¶

Get the last latitude of the cell

Returns:	The last latitude
Type:	float

class lagrangian.MapProperties(nx, ny, x_min, y_min, step)¶

Bases: object

Properties of a regular grid

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

get_x_value(idx)¶

Get the longitude value

Parameters:	idx (int) – Index of the longitude in the grid
Returns:	The longitude
Type:	float

get_y_value(idx)¶

Get the latitude value

Parameters:	idx (int) – Index of the latitude in the grid
Returns:	The latitude
Type:	float

nx¶

Get the number of longitudes in the grid

Returns:	The number of longitudes
Return type:	int

ny¶

Get the number of latitudes in the grid

Returns:	The number of latitudes
Return type:	int

step¶

Get the step between two consecutive longitudes and latitudes

Returns:	The step
Return type:	float

x_min¶

Get the minimal longitude

Returns:	The minimal longitude
Return type:	float

y_min¶

Get the minimal latitude

Returns:	The minimal latitude
Return type:	float

get_x_axis()¶

Get X axis values

Returns:	X axis values
Return type:	numpy.ndarray

get_y_axis()¶

Get Y axis values

Returns:	Y axis values
Return type:	numpy.ndarray

Runge Kutta¶

class lagrangian.RungeKutta(size_of_interval, field)¶

Bases: object

Fourth-order Runge-Kutta method

Parameters:	size_of_interval (float) – Number of time interval field (lagrangian.Field) – Field reader

compute(t, x, y, cell=None)¶

Move a point in a field

Parameters:	t (float) – Time in number of seconds elapsed since 1970 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 which contains the longitude and latitude after moving or None if the read field is undefined for the requested position
Return type:	tuple

Stencils¶

class lagrangian.Position¶

Bases: object

Define the position of N points Mₖ = (xₖ, yₖ):

        Mₖ₊₁
        |
Mₖ₊ᵢ ⎯⎯ M₀ ⎯⎯  Mₖ
        |
        Mₖ₊ₙ

get_xi(idx)¶

Get the longitude of the point idx

Parameters:	idx (int) – position
Returns:	The longitude in degrees
Return type:	float

get_yi(idx)¶

Get the latitude of the point idx

Parameters:	idx (int) – position
Returns:	The latitude in degrees
Return type:	float

time¶

Get the time at the end of the integration

Returns:	The time expressed in number of seconds elapsed since 1970
Return type:	float

completed¶

Test if the integration is over

Returns:	True if the integration is over
Return type:	bool

set_completed()¶: Indicate that the integration is complete.

missing()¶: Set the instance to represent a missing position.

is_missing()¶

Test if the integration is defined.

Returns:	True if the integration is defined
Return type:	bool

max_distance()¶

Compute the distance max

Returns:	The max distance
Return type:	float

compute(rk, it, cell)¶

To move a particle with a velocity field.

Parameters:	rk (lagrangian.RungeKutta) – Runge-Kutta handler it (lagrangian.Iterator) – Iterator cell (lagrangian.CellProperties) – Cell properties of the grid used for the interpolation.
Returns:	True if the particle could be moved otherwise false
Return type:	bool

strain_tensor()¶: TODO

class lagrangian.Triplet(x, y, delta)¶

Bases: lagrangian.Position

Define the position of 3 points

Parameters:	x (float) – Longitude of the initial point y (float) – Latitude of the initial point delta (float) – Initial initial separation in degrees of neighboring particles

class lagrangian.Quintuplet(x, y, delta)¶

Bases: lagrangian.Position

Define the position of 5 points

Parameters:	x (float) – Longitude of the initial point y (float) – Latitude of the initial point delta (float) – Initial initial separation in degrees of neighboring particles

class lagrangian.Stencil¶

Type of stencils known

kTriplet¶: Define a stencil with 3 points

kQuintuplet¶: Define a stencil with 5 points

Integration¶

class lagrangian.Iterator(begin, end, inc)¶

Bases: object

Definition of an iterator over a time period

Parameters:	begin (float) – Begin of the period expressed in number of seconds elapsed since 1970 end (float) – End of the period expressed in number of seconds elapsed since 1970 inc (float) – Time increment in seconds

__iter__()¶

Iterate over the defined period

Returns:	The number of seconds elapsed since 1970
Return type:	float

class lagrangian.AbstractIntegration(*args)¶

Handles the time integration

lagrangian.Integration.get_iterator()¶

Return an iterator that describes the integration period

Returns:	The iterator
Return type:	`lagrangian::Iterator`

lagrangian.Integration.fetch(t)¶

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

Parameters:	t (float) – t Time step in seconds

lagrangian.Integration.compute(it, x0, x1)¶

Calculate the new position of the particle

Parameters:	it (`lagrangian.Iterator`) – Iterator x0 (float) – Longitude in degrees y0 (float) – Latitude in degrees
Returns:	A tuple that contains the new position (x1, y1) of the particle or None if the read field is undefined for the requested position
Return type:	tuple

class lagrangian.Integration(start_time, end_time, delta_t, field)¶

Bases: lagrangian.AbstractIntegration

Handles the time integration

Parameters:	start_time (`lagrangian.DateTime`) – Start time of the integration (number of seconds elapsed 1970) end_time (`lagrangian.DateTime`) – End date of the integration (number of seconds elapsed 1970) delta_t (`datetime.timedelta`) – Time interval, in seconds field (`lagrangian.Field`) – Field to use for computing the velocity of a point.

class lagrangian.Path(start_time, end_time, delta_t, field)¶

Bases: lagrangian.AbstractIntegration

Handles the movement of a particle using the Runge-Kutta method.

Parameters:	start_time (`lagrangian.DateTime`) – Start time of the integration (number of seconds elapsed 1970) end_time (`lagrangian.DateTime`) – End date of the integration (number of seconds elapsed 1970) delta_t (`datetime.timedelta`) – Time interval, in seconds field (`lagrangian.Field`) – Field to use for computing the velocity of a point.

Lyapunov Exponents¶

class lagrangian.Mode¶

Mode of integration

kFSLE¶: Finite Size Lyapunov Exponent

kFTLE¶: Finite Time Lyapunov Exponent

class lagrangian.FiniteLyapunovExponents¶

Bases: object

Storing Lyapunov coefficients calculated.

Velocity readers¶

class lagrangian.Netcdf¶

Bases: object

Grid NetCDF CF reader.

The grid must contain at least one variable and two vectors defining the axes of the longitudes and latitudes of the variable. For example :

dimensions:
  y = 915 ;
  x = 1080 ;
variables:
   double y(y) ;
       y:long_name = "Latitudes" ;
       y:units = "degrees_north" ;
   double x(x) ;
       x:long_name = "Longitudes" ;
       x:units = "degrees_east" ;
   float u(x, y) ;
       u:_FillValue = 999f ;
       u:long_name = "U" ;
       u:units = "cm/s" ;
       u:date = "2012-01-01 00:00:00.000000 UTC" ;
    float v(y, x) ;
       v:_FillValue = 999f ;
       v:long_name = "U" ;
       v:units = "cm/s" ;
       V:date = "2012-01-01 00:00:00.000000 UTC" ;

Note

The variable to be read must set an attribute named “date” that define the date of data contained in the variable.

interpolate(longitude, latitude, fill_value=0, cell=lagrangian.CellProperties.NONE)¶

Computes the velocity of the grid point requested

Parameters:	longitude (float) – Longitude in degrees. latitude (float) – Latitude in degrees fill_value (float) – Value to be taken into account for fill values cell (lagrangian.CellProperties) – Cell properties of the grid used for the interpolation.

load(name, unit)¶

Load data into memory

Parameters:	name (str) – Name of the grid who contains data unit (str) – Unit of data loaded into memory.

open(filename)¶

Opens a file in read-only.

Parameters:	filename (str) – Path to the grid

class lagrangian.PythonReader¶: Python base class for implementing a velocity reader fields.

class lagrangian.ReaderType¶

Type of fields reader known

kNetCDF¶: The velocity field is read from NetCDF grids.

class lagrangian.Factory¶

Reader Factory

static new_reader(reader_type)¶

Parameters:	reader_type (ReaderType) – Name of the grid who contains data
Returns:	An instance of a reader
Return type:	lagrangian.AbstractReader

class lagrangian.TimeSerie(configuration_file, unit_type=lagrangian.kMetric, reader_type=lagrangian.kNetCDF)¶

Bases: lagrangian.Field

Time series of velocity field

Parameters:

configuration_file (str) –
The configuration file contains the list of files to take into account to interpolate speeds, the expected syntax is :
```
U = <path to the NetCDF file>
U = ...
V = <path to the NetCDF file>
V = ...
U_NAME = <name of the NetCDF variable>
V_NAME = <name of the NetCDF variable>
FILL_VALUE = <value>
```
Keys representing the following data:
- U defines the netCDF files containing the eastward velocities.
- V defines the netCDF files containing the northward velocities.
- U_NAME defines the NetCDF variable containing the eastward velocities.
- V_NAME defines the NetCDF variable containing the northward velocities.
- FILL_VALUE value to be taken into account when the reader encounters an undefined value. This value must be 0 if you do not wish to generate undefined values when integrating or nan if the calculation must generate undefined values.
The path to the NetCDF file must contain an absolute path, for example:
```
U = /home/lagrangian/file.nc
```
The path may also contain environment variables using the shell syntax, for example:
```
U = ${DATA}/file.nc
```
unit_type (lagrangian.UnitType) – Unit fields.
reader_type (lagrangian.ReaderType) – The reader used to read grids containing speeds.

start_time()¶

Returns the date of the first grid constituting the time series.

Returns:	the date of the first date
Type:	datetime.datetime

end_time()¶

Returns the date of the last grid constituting the time series.

Returns:	the date of the last date
Type:	datetime.datetime

compute(t, x, y, cell=None)¶

Interpolates the velocity to the wanted spatio temporal position.

Parameters:	t (float) – Time expressed as a number of seconds elapsed since 1970. x (float) – Longitude expressed as degree y (float) – Latitude expressed as degree cell (lagrangian.CellProperties) – Cell properties of the grid used for the interpolation
Returns:	A tuple that contains the interpolated velocity (u, v) of the to the wanted spatio temporal position or None if the field is undefined for the asked position
Return type:	tuple

fetch(t0, t1)¶

Loads the grids used to interpolate the velocities in the interval [t0, t1]

Parameters:	t0 (float) – First date of the interval expressed as a number of seconds elapsed since 1970. t1 (float) – Last date of the interval expressed as a number of seconds elapsed since 1970.

Map of Lyapunov Exponents¶

class lagrangian.MapOfFiniteLyapunovExponents(map_properties, fle, stencil=langrangian.kTriplet, netcdf_reader=None)¶

Bases: object

Handles a map of Finite Size or Time Lyapunov Exponents

Parameters:

map_properties (lagrangian.MapProperties) – Properties of the regular grid to create
fle (lagrangian.FiniteLyapunovExponents) – FLE handler
stencil (lagrangian.Stencil) – Type of stencil used for the calculation of finite difference.
netcdf_reader (lagrangian.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.

compute()¶: Compute the map

Note

You can set the environment variable OMP_NUM_THREADS to enable parallelization of code with the number of threads defined.

get_map_of_lambda1(fill_value)¶

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

get_map_of_lambda2(fill_value)¶

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

get_map_of_theta1(fill_value)¶

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

get_map_of_theta2(fill_value)¶

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

Utility functions¶

lagrangian.debug(msg)¶

Display a debugging message

Parameters:	msg (str) – Message to display

lagrangian.set_verbose(value)¶

Enable or disable verbose mode

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

lagrangian.version()¶

Return the version number

Returns:	Version number
Return type:	str

Table of Contents

Previous topic

Next topic

This Page

Python API¶

Physical quantity units¶

Spatial and temporal axes¶

Dates and time¶

Velocity fields¶

Numerical grids¶

Runge Kutta¶

Stencils¶

Integration¶

Lyapunov Exponents¶

Velocity readers¶

Map of Lyapunov Exponents¶

Utility functions¶

Parameters:	unit (str) – Unit to check
Returns:	if the unit can define this type of axis
Return type:	bool