Velocity Fields

Velocity Fields#

Classes for handling velocity field data from various sources and formats.

Base Field Class#

class lagrangian.core.Field#

Base class for all velocity field implementations.

__init__(self: lagrangian.core.Field, unit_type: lagrangian.core.UnitType, coordinate_type: lagrangian.core.CoordinatesType = <CoordinatesType.SPHERICAL_EQUATORIAL: 0>) → None#

Default constructor

Parameters:

unit_type (lagrangian.Field) – Unit field
coordinate_type (lagrangian.CoordinateType) – Type of the coordinate system

Raises:

ValueError – if the type of unit or the coordinate system is unknown

Key Methods

compute(): Interpolate velocity at given time and position
fetch(): Load field data for specified time range
unit(): Get velocity units as string

Properties

coordinate_type: Type of coordinate system used
unit_type: Type of units (metric or angular)

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

Interpolates the velocity to the wanted spatio temporal position.

Parameters:

t (datetime.datetime) – Date to evaluate
x (float) – Longitude Longitude expressed as degree
y (float) – Latitude expressed as degree
cell (lagrangian.CellProperties) – Cell properties of the grid used for the interpolation. Default is lagrangian.CellProperties.none()

Returns:

U and V components of the velocities evaluated or None if the velocity is undefined for the requested space-time position

Return type:

tuple, optional

fetch(self: lagrangian.core.Field, first: lagrangian::DateTime, last: lagrangian::DateTime) → None#

Loads the grids used to interpolate the velocities in the interval [first, last]

Parameters:

first (datetime.datetime) – First date of the interval
last (datetime.datetime) – Last date of the interval

unit(self: lagrangian.core.Field) → str#: Returns the unit used by this field :returns: unit used by this field :rtype: str

property coordinate_type#: Coordinate type used by this field.

property unit_type#: Unit type used by this field.

class lagrangian.core.Reader#: Base class for velocity field data readers.

Field Implementations#

class lagrangian.core.field.Python#

Bases: lagrangian.Field

Python-based velocity field implementation allowing custom velocity functions.

__init__(self: lagrangian.core.field.Python, self: object, unit_type: lagrangian.core.UnitType = <UnitType.METRIC: 0>, coordinates_type: lagrangian.core.CoordinatesType = <CoordinatesType.CARTESIAN: 1>) → None#

Constructor

Parameters:

unit_type (lagrangian.UnitType) – Unit type used by this field
coordinates_type (lagrangian.CoordinatesType) – Coordinate type used by this field

class lagrangian.core.field.TimeSerie#

Bases: lagrangian.Field

Time-dependent velocity field loaded from configuration files.

Methods

start_time(): Get start time of available data
end_time(): Get end time of available data

Examples

Loading a time series from NetCDF files:

import lagrangian

# Create field from configuration
field = lagrangian.core.field.TimeSerie(
    configuration_file="velocity_config.ini",
    unit_type=lagrangian.UnitType.METRIC,
    coordinates_type=lagrangian.CoordinatesType.SPHERICAL_EQUATORIAL
)

# Get available time range
start = field.start_time()
end = field.end_time()

__init__(self: lagrangian.core.field.TimeSerie, configuration_file: str, unit_type: lagrangian.core.UnitType = <UnitType.METRIC: 0>, coordinates_type: lagrangian.core.CoordinatesType = <CoordinatesType.SPHERICAL_EQUATORIAL: 0>, reader_type: lagrangian.core.reader.Type = <Type.NETCDF: 0>) → None#

Default constructor

Parameters:

configuration_file (str) – The configuration file contains the list of files to take into account to interpolate velocities.
unit_type (lagrangian.UnitType)
coordniates_type (lagrangian.CoordinatesType) – Type of coordinates
reader_type (lagrangian.reader.Type) – containing velocities.

start_time(self: lagrangian.core.field.TimeSerie) → lagrangian::DateTime#: Returns the date of the first grid constituting the time series.

end_time(self: lagrangian.core.field.TimeSerie) → lagrangian::DateTime#: Returns the date of the last grid constituting the time series.

class lagrangian.core.field.Vonkarman#

Bases: lagrangian.Field

Analytical von Kármán vortex street velocity field.

This provides an analytical representation of a von Kármán vortex street, useful for testing and validation of integration algorithms.

Data Readers#

Classes for reading velocity field data from files.

class lagrangian.core.reader.NetCDF#

Reader for NetCDF velocity field files.

The grid must include at least one data variable and two coordinate vectors that define the longitude and latitude axes of the grid. 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 = "V" ;
       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.

__init__(self: lagrangian.core.reader.NetCDF) → None#: Default constructor

Key Methods

open(): Open a NetCDF file
load(): Load a variable from the file
interpolate(): Interpolate data at given coordinates
date(): Get time information

Examples

Reading velocity data from NetCDF:

import lagrangian

reader = lagrangian.core.reader.NetCDF()
reader.open("velocity_field.nc")
reader.load("u", "m/s")  # Load u-component
reader.load("v", "m/s")  # Load v-component

# Interpolate velocity at specific location
u_vel = reader.interpolate(lon=10.0, lat=45.0)

open(self: lagrangian.core.reader.NetCDF, path: str) → None#

Opens a NetCDF grid in read-only.

Parameters:: path (str) – Path to the NetCDF grid
Raises:: RuntimeError – If the function can not find the definition of longitudes or latitudes in the file.

load(self: lagrangian.core.reader.NetCDF, name: str, unit: str = '') → None#

Load into memory grid data

Parameters:

varname (str) – name of the NetCDF grid who contains grid data
unit (str) – Unit of data loaded into memory. If the parameter is undefined or contains an empty string, the object will not do unit conversion(i.e. the unit of the data loaded into memory is the unit defined in the NetCDF file)

interpolate(self: lagrangian.core.reader.NetCDF, lon: typing.SupportsFloat, lat: typing.SupportsFloat, fill_value: typing.SupportsFloat = 0, cell: lagrangian.core.CellProperties = <lagrangian.core.CellProperties object at 0x7f695defbe70>) → float#

Computes the value of the grid point requested by bilinear interpolation

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) – interpolation.

Returns:

Interpolated value or nan if point is outside the grid or: undefined.

Return type:

float

date(self: lagrangian.core.reader.NetCDF, name: str) → lagrangian::DateTime#

Returns the date of the grid

Parameters:: name (str) – The variable name containing the date
Returns:: The date of the grid
Return type:: datetime.datetime

class lagrangian.core.reader.Type#

Enumeration of available reader types:

NETCDF: NetCDF file reader

Velocity Fields

Contents

Velocity Fields#

Base Field Class#

Field Implementations#

Data Readers#