pylag.unstructured module

Tools for navigating unstructured triangular grids

Note

unstructured is implemented in Cython. Only a small portion of the API is exposed in Python with accompanying documentation.

class pylag.unstructured.Grid

Bases: object

Base class for grid objects

Objects of type Grid can perform grid searches, compute local coordinates to assist with interpolation and help identify grid boundary crossings. Derived classes must implement functionality that is specific to a given grid type (e.g. an unstructured grid in cartesian coordinates vs an unstructured grid in geographic coordinates.

find_host_using_global_search_wrapper(self, ParticleSmartPtr particle)

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_using_particle_tracing_wrapper(self, ParticleSmartPtr particle_old, ParticleSmartPtr particle_new)

Python wrapper for finding and setting the host element using particle tracing

Parameters:

particle_old (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its last known position.
particle_new (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its new position.

Returns:

Flag signifying whether the 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

Parameters:

particle_old (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its last known position.
particle_new (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its new position.

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_element_area_wrapper(self, ParticleSmartPtr particle)

Wrapper for returning the area of the particle’s host element

Parameters:: particle (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its current position.
Returns:: The element area.
Return type:: float

get_grad_phi_wrapper(self, host)

Python wrapper for computing gradients in phi

Parameters:: host (int) – The host element.
Returns:: dphi_dx, dphi_dy – Phi gradients in x and y.
Return type:: NDArray

get_phi(self, DTYPE_FLOAT_t x1, DTYPE_FLOAT_t x2, DTYPE_INT_t host) → vector[DTYPE_FLOAT_t]

interpolate_in_space_wrapper(self, var_arr, ParticleSmartPtr particle)

Python wrapper for interpolate in space

Parameters:

var_arr (numpy array) – Variable array of points defined at element nodes.
particle (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its current position.

interpolate_in_time_and_space_2D_wrapper(self, var_last_arr, var_next_arr, time_fraction, ParticleSmartPtr particle)

Python wrapper for interpolate in time and space 2D

Parameters:

var_last_arr (numpy array) – Variable array of points defined at element nodes at the last time index.
var_next_arr (numpy array) – Variable array of points defined at element nodes at the next time index.
particle (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its current position.

interpolate_in_time_and_space_wrapper(self, var_last_arr, var_next_arr, k, time_fraction, ParticleSmartPtr particle)

Python wrapper for interpolate in time and space

Parameters:

var_last_arr (numpy array) – Variable array of points defined at element nodes at the last time point.
var_last_arr – Variable array of points defined at element nodes at the next time point.
k (int) – k layer index.
time_fraction (float) – Fraction position between the first and last time points.
particle (pylag.particle_cpp_wrapper.ParticleSmartPtr) – The particle at its current position.

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

shepard_interpolation_wrapper(self, DTYPE_FLOAT_t x, DTYPE_FLOAT_t y, vector[DTYPE_FLOAT_t] xpts, vector[DTYPE_FLOAT_t] ypts, vector[DTYPE_FLOAT_t] vals, vector[DTYPE_INT_t] valid_points)

Python wrapper for shepard interpolation

Parameters:

x (float) – x-position
float (y -) – y-position
xpts (numpy array) – x-coordinates of values.
ypts (numpy array) – y-coordinates of values.
vals (numpy array) – Values at x/y coordinates.
valid_points (numpy array) – Array of 1/0 flags which signify which values to use (1) and which to ignore (0).

class pylag.unstructured.UnstructuredCartesianGrid(config, name, n_nodes, n_elems, nv, nbe, x, y, xc, yc, land_sea_mask_c, land_sea_mask, areas=None)

Bases: Grid

Unstructured grid

Objects of type UnstructuredCartesianGrid can perform grid searches, compute local coordinates to assist with interpolation and help identify grid boundary crossings for unstructured cartesian (x,y) grids.

Parameters:

config (configparser.ConfigParser) – PyLag configuration object.
name (str) – The grid name. Useful if data are defined on multiple unstructured grids and a means is required to distinguish one from the other.
n_nodes (int) – The number of nodes
n_elems (int) – The number of elements
nv (memoryview) – Memory view of nodes surrounding elements. With shape [3, n_elems]
nbe (memoryview) – Memory view of elements surrounding elements. With shape [3, n_elems]
x (1D memory view) – x-coordinates of grid nodes
y (1D memory view) – y-coordinates of grid nodes
xc (1D memory view) – x-coordinates of element centres
yc (1D memory view) – y-coordinates of element centres
land_sea_mask_c (1D memory view) – Land-sea element mask
land_sea_mask (1D memory view) – Land-sea element mask nodes

get_phi(self, DTYPE_FLOAT_t x1, DTYPE_FLOAT_t x2, DTYPE_INT_t host) → vector[DTYPE_FLOAT_t]

Get barycentric coordinates.

Compute and return barycentric coordinates for the point (x,y) within the 2D triangle defined by x/y coordinates stored in the vectors x_tri and y_tri.

Barycentric coordinates are calculated using the formula:

phi_i(x,y) = A_i(x,y)/A

where A is the area of the element and A_i is the area of the sub triangle that is formed using the particle’s position coordinates within the element and the two element vertices that lie opposite the i vertex. Signed areas are calculated using the vector cross product:

2A(abc) = (x1 - x0)(y2 - y0) - (y1 - y0)(x2 - x0)

A_i terms are computed by substituting in x and y for x_i and y_i for i=0:2.

In PyLag, nodes are clockwise ordered, meaning the signed area given by the above formula is negative. However the negative sign and the factor of two cancel when the ratio is formed. For this reason, they are both ignored.

Parameters:

x1 (float) – x-position in cartesian coordinates.
x2 (float) – y-position in cartesian coordinates.
host (int) – Host element.

Returns:

phi – Barycentric coordinates.

Return type:

C array, float

class pylag.unstructured.UnstructuredGeographicGrid(config, name, n_nodes, n_elems, nv, nbe, x, y, xc, yc, land_sea_mask_c, land_sea_mask, areas=None)

Bases: Grid

Unstructured geographic grid

Objects of type UnstructuredGeographicGrid can perform grid searches, compute local coordinates to assist with interpolation and help identify grid boundary crossings for unstructured geographic (lat/lon) grids.

Parameters:

config (configparser.ConfigParser) – PyLag configuration object.
name (str) – The grid name. Useful if data are defined on multiple unstructured grids and a means is required to distinguish one from the other.
n_nodes (int) – The number of nodes
n_elems (int) – The number of elements
nv (memoryview) – Memory view of nodes surrounding elements. With shape [3, n_elems]
nbe (memoryview) – Memory view of elements surrounding elements. With shape [3, n_elems]
x (1D memory view) – x-coordinates of grid nodes in radians.
y (1D memory view) – y-coordinates of grid nodes in radians.
xc (1D memory view) – x-coordinates of element centres in radians.
yc (1D memory view) – y-coordinates of element centres in radians.
land_sea_mask_c (1D memory view) – Land sea element mask
land_sea_mask (1D memory view) – Land sea element mask at nodes

get_phi(self, DTYPE_FLOAT_t x1, DTYPE_FLOAT_t x2, DTYPE_INT_t host) → vector[DTYPE_FLOAT_t]

Get normalised tetrahedral coordinates

Parameters:

x1 (float) – Longitude in radians
x2 (float) – Latitude in radians
host (int) – Host element

Returns:

phi – Three vector giving a point’s normalised tetrahedral coordinates within a spherical triangle.

Return type:

vector[FLOAT]

pylag.unstructured.get_unstructured_grid(config, *args, **kwargs)

Factory method for unstructured grid types

The factory method is used to distinguish between geographic and cartesian unstructured grid types. Required arguments are documented in the respective class docs.

Parameters:: config (ConfigParser) – Object of type ConfigParser.