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

find_nearest_wet_host_wrapper(self, DTYPE_FLOAT_t time, ParticleSmartPtr particle)

Python wrapper for finding the nearest wet host element

This function is used to find the nearest wet host element to the particle’s current position.

Parameters:
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: