diff --git a/README.md b/README.md index dd71baf7f..4cb08f78a 100644 --- a/README.md +++ b/README.md @@ -62,7 +62,23 @@ recognizing unstructured grid model outputs. We picked the name "UXarray" * Perform aggregations within different topology elements using connectivity information * Mathematical Operators * Support for Integral, Difference, and Gradient calculations - +* Dual Mesh Construction + * Support for constructing a dual mesh from any grid or dataset +* Great Circle Arc (GCA) Functionality + * Function to find the intersection points of two GCA's + * Function to determine if a point is within a GCA +* Face Area Calculation + * Calculate the face area of any face (or all faces) within the grid +* Non-conservative Zonal Mean (coming soon, in development) + * The ability to calculate a non-conservative zonal mean +* Point in Face (coming soon, in development) + * Determines if a point is inside a face +* Faces Containing Point (coming soon, in development) + * For a given point, returns the face or faces containing it +* Spherical Bounding Box + * A spherical bounding box for each face +* Cross-Sections + * Extract cross-sections of a grid based on constant longitude or latitude ## Intended Features diff --git a/docs/api.rst b/docs/api.rst index f9146e69f..b32b192e9 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -414,44 +414,15 @@ on each face. -Intersections -~~~~~~~~~~~~~ - -.. autosummary:: - :toctree: generated/ - - grid.intersections.gca_gca_intersection - grid.intersections.gca_const_lat_intersection - - Spherical Geometry ------------------ -Intersections -~~~~~~~~~~~~~ .. autosummary:: :toctree: generated/ + grid.geometry.pole_point_inside_polygon grid.intersections.gca_gca_intersection grid.intersections.gca_const_lat_intersection - -Arcs -~~~~ - -.. autosummary:: - :toctree: generated/ - - grid.arcs.in_between grid.arcs.point_within_gca grid.arcs.extreme_gca_latitude - - -Accurate Computing ------------------- - -.. autosummary:: - :toctree: generated/ - - utils.computing.cross_fma - utils.computing.dot_fma diff --git a/docs/getting-started/overview.rst b/docs/getting-started/overview.rst index 3b3aee3c1..4285b2d6d 100644 --- a/docs/getting-started/overview.rst +++ b/docs/getting-started/overview.rst @@ -33,9 +33,6 @@ UGRID conventions, which can contain a mix of triangles, quadrilaterals, or other geometric faces. - - - Core Data Structures ==================== @@ -54,15 +51,24 @@ an Unstructured Grid aware implementation of many Xarray functions and use cases a ``Grid`` property (``UxDataArray.uxgrid``) just like ``UxDataset``. Core Functionality -==================== -In addition to providing a way to load in and interface with Unstructured Grids, we -also aim to provide computational and analysis operators that directly operate on -Unstructured Grids. +================== -The list of currently implemented operators can be found in the -`User API `_ -documentation. +UXarray supplies amply ability to manipulate and worth with unstructured grids and datasets. +UXarray has many different operators and functionality, and more detailed overviews can be found +by clicking each functionality listed below. This is not a complete list of functionality inside +UXarray, but highlights some key functions and operators. -Get involved in the `Prioritization of Uxarray analysis -operators `_ to be released in -the future! +* `Cross Sections `_ +* `Dual Mesh Construction `_ +* `Face Area Calculation `_ +* Faces Containing Point (coming soon) +* `GCA Intersections `_ +* `GCA Point Within/On `_ +* `Gradient, Difference, Integrate `_ +* Non-conservative Zonal Mean (coming soon) +* Point In Face (coming soon) +* `Remapping/Regridding Operators `_ +* `Spherical Bounding Box `_ +* `Subsetting `_ +* `Topological Aggregations `_ +* `Visualization Tools `_ diff --git a/uxarray/grid/intersections.py b/uxarray/grid/intersections.py index 528304d35..80528d6a0 100644 --- a/uxarray/grid/intersections.py +++ b/uxarray/grid/intersections.py @@ -134,7 +134,7 @@ def constant_lat_intersections_face_bounds(lat, face_bounds_lat): constant latitude. This function checks whether the specified latitude, `lat`, in degrees lies within - the latitude bounds of grid faces, defined by `face_min_lat_rad` and `face_max_lat_rad`, + the latitude bounds of grid faces, defined by `face_bounds_lat_min` and `face_bounds_lat_max`, which are given in radians. The function returns the indices of the faces where the latitude is within these bounds. @@ -142,7 +142,8 @@ def constant_lat_intersections_face_bounds(lat, face_bounds_lat): ---------- lat : float The latitude in degrees for which to find intersecting faces. - TODO: + face_bounds_lat : numpy.ndarray + The latitude bounds for the face, in radians Returns ------- @@ -164,7 +165,7 @@ def constant_lon_intersections_face_bounds(lon, face_bounds_lon): constant longitude. This function checks whether the specified longitude, `lon`, in degrees lies within - the longitude bounds of grid faces, defined by `face_min_lon_rad` and `face_max_lon_rad`, + the longitude bounds of grid faces, defined by `face_bounds_lon_min` and `face_bounds_lon_max`, which are given in radians. The function returns the indices of the faces where the longitude is within these bounds. @@ -172,7 +173,8 @@ def constant_lon_intersections_face_bounds(lon, face_bounds_lon): ---------- lon : float The longitude in degrees for which to find intersecting faces. - TODO: + face_bounds_lon : numpy.ndarray + The latitude bounds for the face, in radians Returns ------- @@ -201,6 +203,23 @@ def constant_lon_intersections_face_bounds(lon, face_bounds_lon): def _gca_gca_intersection_cartesian(gca_a_xyz, gca_b_xyz): + """Testing function for 'gca_gca_intersection' which converts xyz to the proper coordinates to use for + `gca_gca_intersection`. This function is not optimized and shouldn't be used for anything but testing. + + Parameters + ---------- + gca_a_xyz : numpy.ndarray + The first arc check for intersection, shape [2, 3] + gca_b_xyz : numpy.ndarray + The second arc to check for intersection, shape [2, 3] + + Returns + ------- + numpy.ndarray + Returns the result of `gca_gca_intersection`, which is an array of points where the two arcs intersect. Returns + an empty if the arcs do not intersect anywhere + + """ gca_a_xyz = np.asarray(gca_a_xyz) gca_b_xyz = np.asarray(gca_b_xyz) @@ -229,6 +248,25 @@ def _gca_gca_intersection_cartesian(gca_a_xyz, gca_b_xyz): @njit(cache=True) def gca_gca_intersection(gca_a_xyz, gca_a_lonlat, gca_b_xyz, gca_b_lonlat): + """Returns the intersections points of two arcs. If the arcs do not intersect, returns an empty array. + + Parameters + ---------- + gca_a_xyz : numpy.ndarray + The first arc check for intersection in cartesian coordinates, shape [2, 3] + gca_a_lonlat : numpy.ndarray + The first arc check for intersection in spherical coordinates, shape [2, 2] + gca_b_xyz : numpy.ndarray + The second arc to check for intersection in cartesian coordinates, shape [2, 3] + gca_b_lonlat : numpy.ndarray + The second arc check for intersection in spherical coordinates, shape [2, 2] + + Returns + ------- + numpy.ndarray + Returns an array of points where the two arcs intersect. Returns an empty if the arcs do not intersect anywhere + + """ if gca_a_xyz.shape[1] != 3 or gca_b_xyz.shape[1] != 3: raise ValueError("The two GCAs must be in the cartesian [x, y, z] format")