uxarray.Grid

class uxarray.Grid(grid_ds, source_grid_spec=None, source_dims_dict=None, is_subset=False, inverse_indices=None)

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

Can be used standalone to work with unstructured grids, or can be paired with either a ux.UxDataArray or ux.UxDataset and accessed through the .uxgrid attribute.

For constructing a grid from non-UGRID datasets or other types of supported data, see our ux.open_grid method or specific class methods (Grid.from_dataset, Grid.from_face_verticies, etc.)

Note on Sphere Radius:

All internal calculations use a unit sphere (radius=1.0). The physical sphere radius from the source grid is preserved in the sphere_radius property for scaling results.

Parameters:

• grid_ds (xr.Dataset) – xarray.Dataset encoded in the UGRID conventions

• source_grid_spec (str, default="UGRID") – Original unstructured grid format (i.e. UGRID, MPAS, etc.)

• source_dims_dict (dict, default={}) – Mapping of dimensions from the source dataset to their UGRID equivalent (i.e. {nCell : n_face})

• is_subset (bool, default=False) – Flag to mark if the grid is a subset or not

• inverse_indices (xr.Dataset, default=None) – A dataset of indices that correspond to the original grid, if the grid being constructed is a subset

Examples

>>> import uxarray as ux
>>> grid_path = "/path/to/grid.nc"
>>> data_path = "/path/to/data.nc"

1. Open a grid file with uxarray.open_grid():

>>> uxgrid = ux.open_grid(grid_path)

2. Open an unstructured grid dataset file with uxarray.open_dataset(), then access the Grid.:

>>> uxds = ux.open_dataset(grid_path, data_path)
>>> uxds.uxgrid

__init__(grid_ds, source_grid_spec=None, source_dims_dict=None, is_subset=False, inverse_indices=None)

Methods

__init__(grid_ds[, source_grid_spec, ...])
calculate_total_face_area([quadrature_rule, ...])	Function to calculate the total surface area of all the faces in a mesh.
chunk([n_node, n_edge, n_face])	Converts all arrays to dask arrays with given chunks across grid dimensions in-place.
compute_face_areas([quadrature_rule, order, ...])	Face areas calculation function for grid class, calculates area of all faces in the 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.
copy()	Returns a deep copy of this grid.
from_dataset(dataset[, use_dual])	Constructs a Grid object from a dataset.
from_face_vertices(face_vertices[, latlon])	Constructs a Grid object from user-defined face vertices.
from_file(filename[, backend])	Constructs a Grid object from a using the read_file method with a specified backend.
from_healpix(zoom[, pixels_only, nest])	Constructs a Grid object representing a given HEALPix zoom level.
from_points(points[, method, boundary_points])	Create a grid from unstructured points.
from_structured([ds, lon, lat, tol])	Converts a structured xarray.Dataset or longitude and latitude coordinates into an unstructured uxarray.Grid.
from_topology(node_lon, node_lat, ...[, ...])	Constructs a Grid object from user-defined topology variables provided in the UGRID conventions.
get_ball_tree([coordinates, ...])	Get the BallTree data structure of this Grid that allows for nearest neighbor queries (k nearest or within some radius) on either the (node_x, node_y, node_z) and (node_lon, node_lat), edge (edge_x, edge_y, edge_z) and (edge_lon, edge_lat), or center (face_x, face_y, face_z) and (face_lon, ` face_lat`) nodes.
get_dual([check_duplicate_nodes])	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.
get_edges_at_constant_latitude(lat[, ...])	Identifies the indices of edges that intersect with a line of constant latitude.
get_edges_at_constant_longitude(lon[, ...])	Identifies the indices of edges that intersect with a line of constant longitude.
get_faces_at_constant_latitude(lat)	Identifies the indices of faces that intersect with a line of constant latitude.
get_faces_at_constant_longitude(lon)	Identifies the indices of faces that intersect with a line of constant longitude.
get_faces_between_latitudes(lats)	Identifies the indices of faces that are strictly between two lines of constant latitude.
get_faces_between_longitudes(lons)	Identifies the indices of faces that are strictly between two lines of constant longitude.
get_faces_containing_point(points[, ...])	Identify which grid faces contain the given point(s).
get_kd_tree([coordinates, ...])	Get the KDTree data structure of this Grid that allows for nearest neighbor queries (k nearest or within some radius) on either the (node_x, node_y, node_z) and (node_lon, node_lat), edge (edge_x, edge_y, edge_z) and (edge_lon, edge_lat), or center (face_x, face_y, face_z) and (face_lon, face_lat) nodes.
get_spatial_hash([reconstruct])	Get the SpatialHash data structure of this Grid that allows for fast face search queries.
isel([inverse_indices])	Indexes an unstructured grid along a given dimension (n_node, n_edge, or n_face) and returns a new grid.
normalize_cartesian_coordinates()	Normalizes Cartesian coordinates.
to_geodataframe([periodic_elements, ...])	Constructs a GeoDataFrame consisting of polygons representing the faces of the current Grid
to_linecollection([periodic_elements, ...])	Constructs a matplotlib.collections.LineCollection` consisting of lines representing the edges of the current unstructured grid.
to_polycollection([periodic_elements, ...])	Constructs a matplotlib.collections.PolyCollection` consisting of polygons representing the faces of the current Grid
to_xarray([grid_format])	Returns an xarray.Dataset with the variables stored under the Grid encoded in a specific grid format.
validate([check_duplicates])	Validates the current Grid, checking for Duplicate Nodes, Present Connectivity, and Non-Zero Face Areas.

Attributes

antimeridian_face_indices	Indices of faces that touch or cross the antimeridian.
attrs	Dictionary of parsed attributes from the source grid.
boundary_edge_indices	Indices of edges that border regions not covered by any geometry (holes) in a partial grid.
boundary_face_indices	Indices of faces that border regions not covered by any geometry (holes) in a partial grid.
boundary_node_indices	Indices of nodes that border regions not covered by any geometry (holes) in a partial grid.
bounds	Spherical bounds of each face in degrees
connectivity	Names of all connectivity variables.
coordinates	Names of all coordinate variables.
descriptors	Names of all descriptor variables.
dims	Names of all unstructured grid dimensions.
edge_edge_connectivity	Connectivity variable representing the indices of edges that share at least one node.
edge_face_connectivity	Connectivity variable representing the indices of faces that saddle each edge.
edge_face_distances	Arc distance between the faces that saddle each edge (in radians).
edge_lat	Latitude coordinate of the center of each edge (in degrees).
edge_lon	Longitude coordinate of the center of each edge (in degrees).
edge_node_connectivity	Connectivity variable representing the indices of nodes (mesh vertices) that define each edge.
edge_node_distances	Arc distance between the two nodes that make up each edge (in radians).
edge_x	Cartesian x coordinate of the center of each edge (in meters).
edge_y	Cartesian y coordinate of the center of each edge (in meters).
edge_z	Cartesian z coordinate of the center of each edge (in meters).
face_areas	Area of each face.
face_bounds_lat	Latitude bounds for each face in degrees.
face_bounds_lon	Longitude bounds for each face in degrees.
face_edge_connectivity	Connectivity variable representing the indices of edges that define each face.
face_face_connectivity	Connectivity variable representing the indices of faces that share edges.
face_jacobian	Declare face_jacobian as a property.
face_lat	Latitude coordinate of the center of each face (in degrees).
face_lon	Longitude coordinate of the center of each face (in degrees).
face_node_connectivity	Connectivity variable representing the indices of nodes (mesh vertices) that define each face.
face_x	Cartesian x coordinate of the center of each face (in meters).
face_y	Cartesian y coordinate of the center of each face (in meters).
face_z	Cartesian z coordinate of the center of each face (in meters).
global_sphere_coverage	Boolean indicated whether the Grid completely covers the unit sphere (i.e. contains no holes).
inverse_indices	Indices for a subset that map each face in the subset back to the original grid
is_subset	Returns True if the Grid is a subset, 'False' otherwise.
max_face_radius	Maximum Euclidean distance from each face center to its nodes.
n_edge	Total number of edges.
n_face	Total number of faces.
n_max_edge_edges	Maximum number of edges surrounding a single edge.
n_max_face_edges	Maximum number of edges defining a single face.
n_max_face_faces	Maximum number of neighboring faces surrounding a single face.
n_max_face_nodes	Maximum number of nodes defining a single face.
n_max_node_edges	Maximum number of edges surrounding a single node.
n_max_node_faces	Maximum number of faces surrounding a single node.
n_node	Total number of nodes.
n_nodes_per_face	An array containing the maximum number of nodes for each face.
node_edge_connectivity	Connectivity variable representing the indices of edges that contain each node.
node_face_connectivity	Connectivity variable representing the indices of faces that share a given node.
node_lat	Latitude coordinate of each node (in degrees).
node_lon	Longitude coordinate of each node (in degrees).
node_node_connectivity	Connectivity variable representing the indices of nodes (mesh vertices) that surround each node.
node_x	Cartesian x coordinate of each node (in meters).
node_y	Cartesian y coordinate of each node (in meters).
node_z	Cartesian z coordinate of each node (in meters).
parsed_attrs	Dictionary of parsed attributes from the source grid.
partial_sphere_coverage	Boolean indicated whether the Grid partial covers the unit sphere (i.e. contains holes).
sizes	Names and values of all unstructured grid dimensions.
sphere_radius	Physical sphere radius from the source grid (e.g., Earth's radius for MPAS ocean grids).
triangular	Boolean indicated whether the Grid is strictly composed of triangular faces.