uxarray.Grid

class uxarray.Grid(grid_ds, source_grid_spec=None, source_dims_dict={}, 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.)

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={}, 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.
encode_as(grid_type)	Encodes the grid as a new xarray.Dataset per grid format supplied in the grid_type argument.
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()	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([point_xyz, ...])	Identifies the indices of faces that contain a given point.
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 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	Index of each face that crosses 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	Latitude Longitude Bounds for each Face in radians.
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	Indices of the edges that surround each edge.
edge_face_connectivity	Indices of the faces that saddle each edge.
edge_face_distances	Distances between the centers of the faces that saddle each edge in radians.
edge_lat	Latitude of the center of each edge in degrees.
edge_lon	Longitude of the center of each edge in degrees.
edge_node_connectivity	Indices of the two nodes that make up each edge.
edge_node_distances	Distances between the two nodes that surround each edge in radians.
edge_node_x	Cartesian x location for the two nodes that make up every edge.
edge_node_y	Cartesian y location for the two nodes that make up every edge.
edge_node_z	Cartesian z location for the two nodes that make up every edge.
edge_x	Cartesian x location of the center of each edge in meters.
edge_y	Cartesian y location of the center of each edge in meters.
edge_z	Cartesian z location of the center of each edge in meters.
face_areas	The 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	Indices of the edges that surround each face.
face_face_connectivity	Indices of the faces that surround each face.
face_jacobian	Declare face_jacobian as a property.
face_lat	Latitude of the center of each face in degrees.
face_lon	Longitude of the center of each face in degrees.
face_node_connectivity	Indices of the nodes that make up each face.
face_x	Cartesian x location of the center of each face in meters.
face_y	Cartesian y location of the center of each face in meters.
face_z	Cartesian z location 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 face radius of the grid in degrees
n_edge	Total number of edges.
n_face	Total number of faces.
n_max_edge_edges	The maximum number of edges that surround a single edge.
n_max_face_edges	The maximum number of edges that surround a single face.
n_max_face_faces	The maximum number of faces that surround a single face.
n_max_face_nodes	The maximum number of nodes that can make up a single face.
n_max_node_edges	The maximum number of edges that surround a single node.
n_max_node_faces	The maximum number of faces that surround a single node.
n_node	Total number of nodes.
n_nodes_per_face	The number of nodes that make up each face.
node_edge_connectivity	Indices of the edges that surround each node.
node_face_connectivity	Indices of the faces that surround each node.
node_lat	Latitude of each node in degrees.
node_lon	Longitude of each node in degrees.
node_node_connectivity	Indices of the nodes that surround each node.
node_x	Cartesian x location of each node in meters.
node_y	Cartesian y location of each node in meters.
node_z	Cartesian z location 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.
triangular	Boolean indicated whether the Grid is strictly composed of triangular faces.