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
- 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
- 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
- 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
- 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.
- 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
- 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.