pylag.data_reader module

Abstract base class for PyLag DataReaders.

class pylag.data_reader.DataReader

Bases: object

Abstract base class for PyLag data readers

PyLag DataReaders provide a common interface through which it is possible to access input data that is used to drive the particle tracking model. The desired input data is returned in a common format, irrespective of its origin. By subclassing PyLag DataReader, it becomes possible to extend the model to accept input data in many different formats. Examples of input data include fluid velocity vectors and eddy diffusivities. These may come from an analytical model, or be defined on a discrete numerical grid, as used by a particular hydrodynamic of ocean general circulation model; all of these can be supported by subclassing DataReader and implementing code that extracts and returns the required information.

For efficiency reasons, DataReader has been implemented in Cython and only part of its API is exposed in Python. In order to make it possible to use DataReader objects in Python, a set of Python wrappers have been added to the DataReader base class. These are documented here.

find_host_using_global_search_wrapper(self, ParticleSmartPtr particle)

Python wrapper for finding and setting the host element using a global search

Parameters

particle (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its current position.

Returns

Flag signifying whether the host element was found successfully.

Return type

int

find_host_using_local_search_wrapper(self, ParticleSmartPtr particle)

Python wrapper for finding and setting the host element using a local search

Parameters

particle (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its current position.

Returns

Flag signifying whether the host element was found successfully.

Return type

int

find_host_wrapper(self, ParticleSmartPtr particle_old, ParticleSmartPtr particle_new)

Python wrapper for finding and setting the particle’s host element

Parameters
Returns

Flag signifying whether the new host element was found successfully.

Return type

int

get_boundary_intersection_wrapper(self, ParticleSmartPtr particle_old, ParticleSmartPtr particle_new)

Python wrapper for finding the point no the boundary the particle intersected

This can be used when imposing horizontal boundary conditions.

Parameters
Returns

  • start_point (NumPy array) – Start coordinates of the side the particle crossed.

  • end_point (NumPy array) – End coordinates of the side the particle crossed.

  • intersection (NumPy array) – Coordinates of the intersection point.

get_environmental_variable_wrapper(self, str var_name, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Python wrapper for getting environmental variables

Parameters
Returns

The value of the environmental variable at the particle’s current position

Return type

float

get_grid_names(self)

Return a list of grid names on which data are defined

Returns

A list of grid names

Return type

list

get_horizontal_eddy_diffusivity_derivative_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle, Ah_prime)

Python wrapper for getting the horizontal eddy diffusivity at the particle’s position

Parameters
Return type

None

get_horizontal_eddy_diffusivity_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Python wrapper for getting the horizontal eddy diffusivity at the particle’s position

Parameters
Returns

The horizontal eddy diffusivity

Return type

float

get_horizontal_velocity_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle, vel)

Python wrapper for getting the horizontal velocity at the particle’s position

This function will return a two component vector giving the fluid velocity at the given time and the particle’s current location. The velocity is passed back through the supplied argument vel.

Parameters
Return type

None

get_surface_stokes_drift_velocity_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Return surface Stoke’s drift velocity

This function will return a two component vector giving the surface Stoke’s drift velocity at the given time and the particle’s location.

Parameters
Returns

stokes_drift – The surface Stoke’s drift velocity.

Return type

1D NumPy array of length two.

get_ten_meter_wind_velocity_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Return the 10 m wind velocity

This function will return a two component vector giving the 10 m wind velocity at the given time and the particle’s current location.

Parameters
Returns

wind_velocity – The horizontal wind velocity.

Return type

1D NumPy array of length two.

get_velocity_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle, vel)

Python wrapper for getting the velocity at the particle’s position

This function will return a three component vector giving the fluid velocity at the given time and the particle’s current location. The velocity is passed back through the supplied argument vel.

Parameters
Return type

None

get_vertical_eddy_diffusivity_derivative_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Python wrapper for getting the vertical eddy diffusivity derivative at the particle’s position

Parameters
Returns

The vertical eddy diffusivity

Return type

float

get_vertical_eddy_diffusivity_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Python wrapper for getting the vertical eddy diffusivity at the particle’s position

Parameters
Returns

The vertical eddy diffusivity

Return type

float

get_xmin(self) → DTYPE_FLOAT_t

Python wrapper for getting the minimum x value across the grid

Primarily introduced to increase the number of significant figures used when computing changes in particle positions on small domains.

Returns

The minimum x value

Return type

float

get_ymin(self) → DTYPE_FLOAT_t

Python wrapper for getting the minimum y value across the grid

Primarily introduced to increase the number of significant figures used when computing changes in particle positions on small domains.

Returns

The minimum y value

Return type

float

get_zmax_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Python wrapper for getting the maximum z value at the particle’s position

Typically, the maximum z-value will correspond to the free surface height at the given time and the particle’s current position.

Parameters
Returns

The maximum z value

Return type

float

get_zmin_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Python wrapper for getting the minimum z value at the particle’s position

Typically, the minimum z-value will correspond to the bathymetry at the given time and the particle’s current position.

Parameters
Returns

The minimum z value

Return type

float

is_wet_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Python wrapper for getting the wet/dry status of the particle

Parameters
Returns

Flag identifying whether the current cell is wet or dry

Return type

int

read_data(self, DTYPE_FLOAT_t time)

Read in time dependent variable data from file

time is used to test if new data should be read in from file.

Parameters

time (float) – The current time.

set_default_location_wrapper(self, ParticleSmartPtr particle)

Python wrapper for setting the default location of a particle

Can be used to set a particle’s position to a default location within an element (for example, should it not be possible to strictly apply the horizontal boundary condition).

Parameters

particle (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its current position.

Return type

None

set_local_coordinates_wrapper(self, ParticleSmartPtr particle)

Python wrapper for setting particle local coordinates

Used to set particle local horizontal coordinates (e.g. within its host element).

Parameters

particle (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its current position.

Return type

None

set_vertical_grid_vars_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Python wrapper for setting particle vertical grid variables

Vertical grid variables include local vertical coordinates and indices identifying the current vertical level within which the particle resides.

Parameters

particle (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its current position.

Returns

Flag signifying whether or not the operation was a success.

Return type

int

setup_data_access(self, start_datetime, end_datetime)

Setup access to time dependant variables

Setup access to input data using the supplied datatime arguments.

Parameters