Internal API#

This page shows already-implemented Uxarray internal API functions. You can also check the UXarray Milestones and UXarray RoadMap for a high level understanding of UXarray’s future function development milestones and roadmap. Please let us know if you have any feedback!

UxDataset#

The uxarray.UxDataset class inherits from xarray.Dataset. Below is a list of features explicitly added to work on Unstructured Grids.

Class#

UxDataset(*args[, uxgrid, source_datasets])

A xarray.Dataset-like, multi-dimensional, in memory, array database.

Attributes#

UxDataset._source_datasets

UxDataset._uxgrid

Methods#

UxDataset.__getitem__(key)

Override to make sure the result is an instance of uxarray.UxDataArray or uxarray.UxDataset.

UxDataset.__setitem__(key, value)

Add an array to this dataset.

UxDataset._calculate_binary_op(*args, **kwargs)

Override to make the result a complete instance of uxarray.UxDataset.

UxDataset._construct_dataarray(name)

Override to make the result an instance of uxarray.UxDataArray.

UxDataset._construct_direct(*args, **kwargs)

Override to make the result an uxarray.UxDataset class.

UxDataset._copy(**kwargs)

Override to make the result a complete instance of uxarray.UxDataset.

UxDataset._replace(*args, **kwargs)

Override to make the result a complete instance of uxarray.UxDataset.

UxDataArray#

The uxarray.UxDataArray class inherits from xarray.DataArray. Below is a list of features explicitly added to work on Unstructured Grids.

Class#

UxDataArray(*args[, uxgrid])

N-dimensional xarray.DataArray-like array.

Attributes#

UxDataArray._uxgrid

Methods#

UxDataArray._construct_direct(*args, **kwargs)

Override to make the result a uxarray.UxDataArray class.

UxDataArray._copy(**kwargs)

Override to make the result a complete instance of uxarray.UxDataArray.

UxDataArray._replace(*args, **kwargs)

Override to make the result a complete instance of uxarray.UxDataArray.

UxDataArray._face_centered()

Returns whether the data stored is Face Centered (i.e. contains the "n_face" dimension).

UxDataArray._node_centered()

Returns whether the data stored is Node Centered (i.e. contains the "n_node" dimension).

UxDataArray._slice_from_grid(sliced_grid)

Slices a UxDataArray from a sliced Grid, using cached indices to correctly slice the data variable.

Grid#

Class#

Grid(grid_ds[, source_grid_spec, ...])

Represents a two-dimensional unstructured grid encoded following the UGRID conventions and provides grid-specific functionality.

Operators#

Grid.__eq__(other)

Two grids are equal if they have matching grid topology variables, coordinates, and dims all of which are equal.

Grid.__ne__(other)

Two grids are not equal if they have differing grid topology variables, coordinates, or dims.

Helpers#

Connectivity#

grid.connectivity._face_nodes_to_sparse_matrix(...)

Converts a given dense matrix connectivity to a sparse matrix format where the locations of non fill-value entries are stored using COO (coordinate list) standard.

grid.connectivity._replace_fill_values(...)

Replaces all instances of the the current fill value (original_fill) in (grid_var) with (new_fill) and converts to the dtype defined by (new_dtype)

grid.connectivity._build_edge_node_connectivity(...)

Constructs the UGRID connectivity variable (edge_node_connectivity) and stores it within the internal (Grid._ds) and through the attribute (Grid.edge_node_connectivity).

grid.connectivity._build_node_faces_connectivity(...)

Builds the Grid.node_faces_connectivity: integer DataArray of size (n_node, n_max_faces_per_node) (optional) A DataArray of indices indicating faces that are neighboring each node.

grid.connectivity._build_edge_face_connectivity(...)

Helper for (edge_face_connectivity) construction.

grid.connectivity._populate_edge_node_connectivity(grid)

Constructs the UGRID connectivity variable (edge_node_connectivity) and stores it within the internal (Grid._ds) and through the attribute (Grid.edge_node_connectivity).

grid.connectivity._populate_edge_face_connectivity(grid)

Constructs the UGRID connectivity variable (edge_node_connectivity) and stores it within the internal (Grid._ds) and through the attribute (Grid.edge_node_connectivity).

grid.connectivity._populate_n_nodes_per_face(grid)

Constructs the connectivity variable (n_nodes_per_face) and stores it within the internal (Grid._ds) and through the attribute (Grid.n_nodes_per_face).

Geometry#

Coordinates#

grid.coordinates._get_lonlat_from_xyz(x, y, z)

grid.coordinates._get_xyz_from_lonlat(...)

grid.coordinates._populate_cartesian_xyz_coord(grid)

A helper function that populates the xyz attribute in UXarray.Grid._ds.

grid.coordinates._populate_lonlat_coord(grid)

Helper function that populates the longitude and latitude and store it into the node_lon and node_lat.

grid.coordinates._populate_face_centroids(grid)

Finds the centroids of faces using cartesian averaging based off the vertices.

grid.coordinates._construct_face_centroids(...)

Constructs the xyz centroid coordinate for each face using Cartesian Averaging.

grid.coordinates._set_desired_longitude_range(ds)

Sets the longitude range to [-180, 180] for all longitude variables.

grid.coordinates._populate_edge_centroids(grid)

Finds the centroids using cartesian averaging of the edges based off the vertices.

grid.coordinates._construct_edge_centroids(...)

Constructs the xyz centroid coordinate for each edge using Cartesian Averaging.

Arcs#

grid.arcs._angle_of_2_vectors(u, v)

Calculate the angle between two 3D vectors u and v in radians.

grid.arcs._decide_pole_latitude(lat1, lat2)

Determine the pole latitude based on the latitudes of two points on a Great Circle Arc (GCA).

Utils#

grid.utils._newton_raphson_solver_for_gca_constLat(...)

Solve for the intersection point between a great circle arc and a constant latitude.

grid.utils._inv_jacobian(x0, x1, y0, y1, z0, ...)

Calculate the inverse Jacobian matrix for a given set of parameters.

Validation#

grid.validation._check_connectivity(self)

Check if all nodes are referenced by at least one element.

grid.validation._check_duplicate_nodes(self)

Check if there are duplicate nodes in the mesh.

grid.validation._check_area(self)

Check if each face area is greater than our constant ERROR_TOLERANCE.

Accurate Computing Utils#

utils.computing._err_fmac(a, b, c)

Error-free transformation for the FMA operation.

utils.computing._fast_two_mult(a, b)

Error-free transformation of the product of two floating-point numbers such that a * b = x + y exactly.

utils.computing._fast_two_sum(a, b)

Compute a fast error-free transformation of the sum of two floating- point numbers.

utils.computing._two_sum(a, b)

Error-free transformation of the sum of two floating-point numbers such that a + b = x + y exactly

utils.computing._two_prod_fma(a, b)

Error-free transformation of the product of two floating-point numbers using FMA, such that a * b = x + y exactly.

utils.computing._comp_prod_fma(vec)

Compute the compensated product using Fused Multiply-Add (FMA).

utils.computing._sum_of_squares_re(vec)

Compute the sum of squares of a vector using a compensated algorithm.

utils.computing._vec_sum(p)

Compute the sum of a vector using a compensated summation algorithm.

utils.computing._norm_faithful(x)

Compute the faithful norm of a vector.

utils.computing._norm_l(x)

Compute the L2 norm (Euclidean norm) of a vector using a compensated algorithm.

utils.computing._norm_g(x)

Compute the compensated Euclidean norm of a vector.

utils.computing._two_square(Aa)

Compute the square of a number with a compensation for the round-off error.

utils.computing._acc_sqrt(T, t)

Compute the accurate square root of a number with a compensation for round-off error.

utils.computing._split(a)

Split a floating-point number into two parts: The rounded floating point presentation and its error.

Remapping#

remap.nearest_neighbor._nearest_neighbor(...)

Nearest Neighbor Remapping between two grids, mapping data that resides on the corner nodes, edge centers, or face centers on the source grid to the corner nodes, edge centers, or face centers of the destination grid.

remap.nearest_neighbor._nearest_neighbor_uxda(...)

Nearest Neighbor Remapping implementation for UxDataArray.

remap.nearest_neighbor._nearest_neighbor_uxds(...)

Nearest Neighbor Remapping implementation for UxDataset.

remap.inverse_distance_weighted._inverse_distance_weighted_remap(...)

Inverse Distance Weighted Remapping between two grids.

remap.inverse_distance_weighted._inverse_distance_weighted_remap_uxda(...)

Inverse Distance Weighted Remapping implementation for UxDataArray.

remap.inverse_distance_weighted._inverse_distance_weighted_remap_uxds(...)

Inverse Distance Weighted implementation for UxDataset.

Grid Parsing and Encoding#

UGRID#

io._ugrid._read_ugrid(xr_ds)

UGRID file reader.

io._ugrid._encode_ugrid(ds)

Encodes UGRID file .

io._ugrid._is_ugrid(ds)

Check mesh topology and dimension.

io._ugrid._validate_minimum_ugrid(grid_ds)

Checks whether a given grid_ds meets the requirements for a minimum unstructured grid encoded in the UGRID conventions, containing a set of (x, y) latlon coordinates and face node connectivity.

MPAS#

io._mpas._read_mpas(ext_ds[, use_dual])

Function to read in a MPAS Grid dataset and encode either the Primal or Dual Mesh in the UGRID conventions.

io._mpas._primal_to_ugrid(in_ds, out_ds)

Encodes the MPAS Primal-Mesh in the UGRID conventions.

io._mpas._dual_to_ugrid(in_ds, out_ds)

Encodes the MPAS Dual-Mesh in the UGRID conventions.

io._mpas._replace_padding(verticesOnCell, ...)

Replaces the padded values in verticesOnCell defined by nEdgesOnCell with a fill-value.

io._mpas._replace_zeros(grid_var)

Replaces all instances of a zero (invalid/missing MPAS value) with a fill value.

Exodus#

io._exodus._read_exodus(ext_ds)

Exodus file reader.

io._exodus._encode_exodus(ds[, outfile])

Encodes an Exodus file.

io._exodus._get_element_type(num_nodes)

Helper function to get exodus element type from number of nodes.

SCRIP#

io._scrip._to_ugrid(in_ds, out_ds)

If input dataset (in_ds) file is an unstructured SCRIP file, function will reassign SCRIP variables to UGRID conventions in output file (out_ds).

io._scrip._read_scrip(ext_ds)

Function to reassign lat/lon variables to node variables.

io._scrip._encode_scrip(...)

Function to reassign UGRID formatted variables to SCRIP formatted variables.

Shapefile#

io._shapefile._read_shpfile(filepath)

Read shape file.

Vertices#

io._vertices._read_face_vertices(...)

Create a grid with faces constructed from vertices specified by the given argument.

Utils#

io.utils._parse_grid_type(dataset)

Checks input and contents to determine grid type.

Core Utils#

core.utils._map_dims_to_ugrid(ds, ...)

Given a dataset containing variables residing on an unstructured grid, remaps the original dimension name to match the UGRID conventions (i.e. "nCell": "n_face").

Visualization#

plot.grid_plot._plot_coords_as_points(...[, ...])

Helper function for plotting coordinates (node, edge, face) as Points with Holoviews.

plot.dataarray_plot._plot_data_as_points(...)

Helper function for plotting data variables as Points, either on the Nodes, Face Centers, or Edge Centers.

plot.dataarray_plot._polygon_raster(uxda[, ...])

Implementation of Polygon Rasterization.

plot.dataarray_plot._point_raster(uxda[, ...])

Implementation of Point Rasterization.

Slicing#

grid.slice._slice_node_indices(grid, indices)

Slices (indexes) an unstructured grid given a list/array of node indices, returning a new Grid composed of elements that contain the nodes specified in the indices.

Subsetting#

subset.grid_accessor.GridSubsetAccessor(uxgrid)

Accessor for performing unstructured grid subsetting, accessed through Grid.subset

subset.dataarray_accessor.DataArraySubsetAccessor(uxda)

Accessor for performing unstructured grid subsetting with a data variable, accessed through UxDataArray.subset

Neighbor#

grid.neighbors._populate_edge_node_distances(grid)

Populates edge_node_distances

grid.neighbors._construct_edge_node_distances(...)

Helper for computing the arc-distance between nodes compose each edge.

grid.neighbors._populate_edge_face_distances(grid)

Populates edge_face_distances

grid.neighbors._construct_edge_face_distances(...)

Helper for computing the arc-distance between faces that saddle a given edge.

Gradients#

core.gradient._calculate_edge_face_difference(...)

Helper function for computing the aboslute difference between the data values on each face that saddle each edge.

core.gradient._calculate_edge_node_difference(...)

Helper function for computing the aboslute difference between the data values on each node that saddle each edge.

core.gradient._calculate_grad_on_edge_from_faces(...)

Helper function for computing the horizontal gradient of a field on each cell using values at adjacent cells.