API reference#

This page provides an auto-generated summary of UXarray’s API. For more details and examples, refer to the relevant chapters in the main part of the documentation.

Top Level Functions#

open_grid(grid_filename_or_obj[, latlon, ...])

Constructs and returns a Grid from a grid file.

open_dataset(grid_filename_or_obj, ...[, ...])

Wraps xarray.open_dataset() to support reading in a grid and data file together.

open_mfdataset(grid_filename_or_obj, paths)

Wraps xarray.open_dataset() to support reading in a grid and multiple data files together.

Grid#

Constructor#

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

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

I/O & Conversion#

Grid.from_dataset(dataset[, use_dual])

Constructs a Grid object from an xarray.Dataset.

Grid.from_file(filename[, backend])

Constructs a Grid object from a using the read_file method with a specified backend.

Grid.from_topology(node_lon, node_lat, ...)

Constructs a Grid object from user-defined topology variables provided in the UGRID conventions.

Grid.from_structured([ds, lon, lat, tol])

Converts a structured xarray.Dataset or longitude and latitude coordinates into an unstructured uxarray.Grid.

Grid.from_points(points[, method, ...])

Create a grid from unstructured points.

Grid.to_xarray([grid_format])

Returns an xarray.Dataset with the variables stored under the Grid encoded in a specific grid format.

Grid.to_geodataframe([periodic_elements, ...])

Constructs a GeoDataFrame consisting of polygons representing the faces of the current Grid

Grid.to_polycollection([periodic_elements, ...])

Constructs a matplotlib.collections.PolyCollection` consisting of polygons representing the faces of the current Grid

Grid.to_linecollection([periodic_elements, ...])

Constructs a matplotlib.collections.LineCollection` consisting of lines representing the edges of the current Grid

Indexing#

Grid.isel(**dim_kwargs)

Indexes an unstructured grid along a given dimension (n_node, n_edge, or n_face) and returns a new grid.

Dimensions#

Grid.dims

Names of all unstructured grid dimensions.

Grid.sizes

Names and values of all unstructured grid dimensions.

Grid.n_node

Total number of nodes.

Grid.n_edge

Total number of edges.

Grid.n_face

Total number of faces.

Grid.n_max_face_nodes

The maximum number of nodes that can make up a single face.

Grid.n_max_face_edges

The maximum number of edges that surround a single face.

Grid.n_max_face_faces

The maximum number of faces that surround a single face.

Grid.n_max_edge_edges

The maximum number of edges that surround a single edge.

Grid.n_max_node_faces

The maximum number of faces that surround a single node.

Grid.n_max_node_edges

The maximum number of edges that surround a single node.

Grid.n_nodes_per_face

The number of nodes that make up each face.

Spherical Coordinates#

Grid.node_lon

Longitude of each node in degrees.

Grid.node_lat

Latitude of each node in degrees.

Grid.edge_lon

Longitude of the center of each edge in degrees.

Grid.edge_lat

Latitude of the center of each edge in degrees.

Grid.face_lon

Longitude of the center of each face in degrees.

Grid.face_lat

Latitude of the center of each face in degrees.

Cartesian Coordinates#

Grid.node_x

Cartesian x location of each node in meters.

Grid.node_y

Cartesian y location of each node in meters.

Grid.node_z

Cartesian z location of each node in meters.

Grid.edge_x

Cartesian x location of the center of each edge in meters.

Grid.edge_y

Cartesian y location of the center of each edge in meters.

Grid.edge_z

Cartesian z location of the center of each edge in meters.

Grid.face_x

Cartesian x location of the center of each face in meters.

Grid.face_y

Cartesian y location of the center of each face in meters.

Grid.face_z

Cartesian z location of the center of each face in meters.

Connectivity#

Grid.connectivity

Names of all connectivity variables.

Grid.face_node_connectivity

Indices of the nodes that make up each face.

Grid.face_edge_connectivity

Indices of the edges that surround each face.

Grid.face_face_connectivity

Indices of the faces that surround each face.

Grid.edge_node_connectivity

Indices of the two nodes that make up each edge.

Grid.edge_edge_connectivity

Indices of the edges that surround each edge.

Grid.edge_face_connectivity

Indices of the faces that saddle each edge.

Grid.node_node_connectivity

Indices of the nodes that surround each node.

Grid.node_edge_connectivity

Indices of the edges that surround each node.

Grid.node_face_connectivity

Indices of the faces that surround each node.

Descriptors#

Grid.descriptors

Names of all descriptor variables.

Grid.face_areas

The area of each face.

Grid.bounds

Latitude Longitude Bounds for each Face in degrees.

Grid.edge_node_distances

Distances between the two nodes that surround each edge in degrees.

Grid.edge_face_distances

Distances between the centers of the faces that saddle each edge in degrees.

Grid.antimeridian_face_indices

Index of each face that crosses the antimeridian.

Grid.boundary_node_indices

Indices of nodes that border regions not covered by any geometry (holes) in a partial grid.

Grid.boundary_edge_indices

Indices of edges that border regions not covered by any geometry (holes) in a partial grid.

Grid.boundary_face_indices

Indices of faces that border regions not covered by any geometry (holes) in a partial grid.

Grid.partial_sphere_coverage

Boolean indicated whether the Grid partial covers the unit sphere (i.e. contains holes).

Grid.global_sphere_coverage

Boolean indicated whether the Grid completely covers the unit sphere (i.e. contains no holes).

Grid.triangular

Boolean indicated whether the Grid is strictly composed of triangular faces.

Attributes#

Grid.attrs

Dictionary of parsed attributes from the source grid.

Methods#

Grid.copy()

Returns a deep copy of this grid.

Grid.chunk([n_node, n_edge, n_face])

Converts all arrays to dask arrays with given chunks across grid dimensions in-place.

Grid.validate([check_duplicates])

Validates the current Grid, checking for Duplicate Nodes, Present Connectivity, and Non-Zero Face Areas.

Grid.compute_face_areas([quadrature_rule, ...])

Face areas calculation function for grid class, calculates area of all faces in the grid.

Grid.calculate_total_face_area([...])

Function to calculate the total surface area of all the faces in a mesh.

Grid.normalize_cartesian_coordinates()

Normalizes Cartesian coordinates.

Grid.construct_face_centers([method])

Constructs face centers, this method provides users direct control of the method for constructing the face centers, the default method is "cartesian average", but a more accurate method is "welzl" that is based on the recursive Welzl algorithm.

Inheritance of Xarray Functionality#

The primary data structures in UXarray, uxarray.UxDataArray and uxarray.UxDataset inherit from xarray.DataArray and xarray.Dataset respectively. This means that they contain the same methods and attributes that are present in Xarray, with new additions and some overloaded as discussed in the next sections. For a detailed list of Xarray specific behavior and functionality, please refer to Xarray’s documentation.

UxDataArray#

Constructor#

UxDataArray(*args[, uxgrid])

Grid informed xarray.DataArray with an attached Grid accessor and grid-specific functionality.

Grid Accessor#

UxDataArray.uxgrid

Linked Grid representing to the unstructured grid the data resides on.

I/O & Conversion#

UxDataArray.to_geodataframe([...])

Constructs a GeoDataFrame consisting of polygons representing the faces of the current Grid with a face-centered data variable mapped to them.

UxDataArray.to_polycollection([...])

Constructs a matplotlib.collections.PolyCollection` consisting of polygons representing the faces of the current UxDataArray with a face-centered data variable mapped to them.

UxDataArray.to_dataset([dim, name, ...])

Convert a UxDataArray to a UxDataset.

UxDataset#

Constructor#

UxDataset(*args[, uxgrid, source_datasets])

Grid informed xarray.Dataset with an attached Grid accessor and grid-specific functionality.

Grid Accessor#

UxDataset.uxgrid

Linked Grid representing to the unstructured grid the data resides on.

I/O & Conversion#

UxDataset.from_structured(ds[, tol])

Converts a structured xarray.Dataset into an unstructured uxarray.UxDataset

Plotting#

UXarray’s plotting API is written using hvPlot.

Grid#

Grid.plot()

Plotting accessor for Grid.

Grid.plot.mesh([periodic_elements, backend])

Plots the edges of a Grid.

Grid.plot.edges([periodic_elements, ...])

Plots the edges of a Grid.

Grid.plot.node_coords([backend])

Generate a point plot for the grid corner nodes.

Grid.plot.nodes([backend])

Generate a point plot for the grid corner nodes.

Grid.plot.face_coords([backend])

Wrapper for Grid.plot.points(element='face centers')

Grid.plot.face_centers([backend])

Wrapper for Grid.plot.points(element='face centers')

Grid.plot.edge_coords([backend])

Wrapper for Grid.plot.points(element='edge centers')

Grid.plot.edge_centers([backend])

Wrapper for Grid.plot.points(element='edge centers')

UxDataArray#

UxDataArray.plot()

Plotting Accessor for UxDataArray.

UxDataArray.plot.polygons([...])

Generated a shaded polygon plot.

UxDataArray.plot.points([backend])

Generate a point plot based on the specified grid element type (nodes, faces, or edges) shaded with the data mapped to those elements.

UxDataset#

UxDataset.plot()

Plotting accessor for UxDataset.

Subsetting#

Grid#

Grid.subset()

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

Grid.subset.nearest_neighbor(center_coord, k)

Subsets an unstructured grid by returning the k closest neighbors from a center coordinate.

Grid.subset.bounding_box(lon_bounds, lat_bounds)

Subsets an unstructured grid between two latitude and longitude points which form a bounding box.

Grid.subset.bounding_circle(center_coord, r)

Subsets an unstructured grid by returning all elements within some radius (in degrees) from a center coord.

UxDataArray#

UxDataArray.subset()

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

UxDataArray.subset.nearest_neighbor(...[, ...])

Subsets an unstructured grid by returning the k closest neighbors from a center coordinate.

UxDataArray.subset.bounding_box(lon_bounds, ...)

Subsets an unstructured grid between two latitude and longitude points which form a bounding box.

UxDataArray.subset.bounding_circle(...[, ...])

Subsets an unstructured grid by returning all elements within some radius (in degrees) from a center coord.

Cross Sections#

Grid#

Grid.cross_section()

Accessor for cross-section operations on a Grid

Grid.cross_section.constant_latitude(lat[, ...])

Extracts a cross-section of the grid at a specified constant latitude.

UxDataArray#

UxDataArray.cross_section()

Accessor for cross-section operations on a UxDataArray

UxDataArray.cross_section.constant_latitude(lat)

Extracts a cross-section of the data array at a specified constant latitude.

Remapping#

UxDataArray#

UxDataArray.remap()

Remapping accessor for UxDataArray

UxDataArray.remap.nearest_neighbor(...[, ...])

Nearest Neighbor Remapping between a source UxDataArray and destination Grid

UxDataArray.remap.inverse_distance_weighted(...)

Inverse Distance Weighted Remapping between a source UxDataArray and destination Grid

UxDataset#

UxDataset.remap()

Remapping accessor for UxDataset

UxDataset.remap.nearest_neighbor(...[, ...])

Nearest Neighbor Remapping between a source UxDataset and destination Grid

UxDataset.remap.inverse_distance_weighted(...)

Inverse Distance Weighted Remapping between a source UxDataset and destination Grid

Mathematical Operators#

UxDataArray.integrate([quadrature_rule, order])

Computes the integral of a data variable.

UxDataArray.gradient([normalize, use_magnitude])

Computes the horizontal gradient of a data variable.

UxDataArray.difference([destination])

Computes the absolute difference of a data variable.

Dual Mesh Construction#

Grid.get_dual()

Compute the dual for a grid, which constructs a new grid centered around the nodes, where the nodes of the primal become the face centers of the dual, and the face centers of the primal become the nodes of the dual.

UxDataArray.get_dual()

Compute the dual mesh for a data array, returns a new data array object.

UxDataset.get_dual()

Compute the dual mesh for a dataset, returns a new dataset object.

Aggregations#

Topological#

Topological aggregations apply an aggregation (i.e. averaging) on a per-element basis. For example, instead of computing the average across all values, we can compute the average of all the nodes that surround each face and store the result on each face.

UxDataArray.topological_mean(destination, ...)

Performs a topological mean aggregation.

UxDataArray.topological_min([destination])

Performs a topological min aggregation.

UxDataArray.topological_max([destination])

Performs a topological max aggregation.

UxDataArray.topological_median([destination])

Performs a topological median aggregation.

UxDataArray.topological_std([destination])

Performs a topological std aggregation.

UxDataArray.topological_var([destination])

Performs a topological var aggregation.

UxDataArray.topological_sum([destination])

Performs a topological sum aggregation.

UxDataArray.topological_prod([destination])

Performs a topological prod aggregation.

UxDataArray.topological_all([destination])

Performs a topological all aggregation.

UxDataArray.topological_any([destination])

Performs a topological any aggregation.

Intersections#

grid.intersections.gca_gca_intersection(...)

Calculate the intersection point(s) of two Great Circle Arcs (GCAs) in a Cartesian coordinate system.

grid.intersections.gca_const_lat_intersection(...)

Calculate the intersection point(s) of a Great Circle Arc (GCA) and a constant latitude line in a Cartesian coordinate system.

Spherical Geometry#

Intersections#

grid.intersections.gca_gca_intersection(...)

Calculate the intersection point(s) of two Great Circle Arcs (GCAs) in a Cartesian coordinate system.

grid.intersections.gca_const_lat_intersection(...)

Calculate the intersection point(s) of a Great Circle Arc (GCA) and a constant latitude line in a Cartesian coordinate system.

Arcs#

grid.arcs.in_between(p, q, r)

Determines whether the number q is between p and r.

grid.arcs.point_within_gca(pt, gca_cart[, ...])

Check if a point lies on a given Great Circle Arc (GCA).

grid.arcs.extreme_gca_latitude(gca_cart, ...)

Calculate the maximum or minimum latitude of a great circle arc defined by two 3D points.

Accurate Computing#

utils.computing.cross_fma(v1, v2)

Calculate the cross product of two 3D vectors utilizing the fused multiply-add operation.

utils.computing.dot_fma(v1, v2)

Calculate the dot product of two vectors using the FMA (fused multiply- add) operation.