Add spatial hashing

[fluidnumerics-joe]

Closes #1126

Overview

This PR adds the SpatialHash class in the neighbors.py module. This class is used to encapsulate the necessary information and methods for conducting unstructured grid searches using spatial hashes. As part of the initialization of the SpatialHash object, an associated unstructured grid is used to construct a uniformly spaced structured grid, called the "hash grid", and relate cell indices in the hash grid to elements in the unstructured grid. This hash table is a critical element of the spatial hash grid search as it is used to create a short-list of elements to search within.

The SpatialHash.query method returns the element id that a point (or element ids that a list of points) reside within alonside the barycentric coordinates. I've included helper methods to compute the barycentric coordinates of a point in relation to a given unstructured grid face (it works for convex faces n>=3 vertices). The barycentric coordinates are used to determine if a point is inside or outside a face; if all the barycentric coordinates are between [0,1], then a point is inside a face.

Currently, only spherical coordinates (in radians or degrees) are supported for this search.

Expected Usage

import uxarray as ux
grid_path = "../../test/meshfiles/fesom/soufflet-netcdf/grid.nc"
uxgrid = ux.open_grid(grid_path)

uxds = ux.open_dataset(grid_path, data_path)

# Construct the `SpatialHash` object
spatial_hash = uxgrid.get_spatial_hash(
    reconstruct="False",
)

# Query the `SpatialHash` for the face id and the barycentric coordinates.
face_ids, bcoords = spatial_hash.query([0.9, 1.8])

PR Checklist

General

• An issue is linked created and linked
• Add appropriate labels
• Filled out Overview and Expected Usage (if applicable) sections

Testing

• Adequate tests are created if there is new functionality
• Tests cover all possible logical paths in your function
• Tests are not too basic (such as simply calling a function and nothing else)

Documentation

• Docstrings have been added to all new functions
• Docstrings have updated with any function changes
• Internal functions have a preceding underscore (_) and have been added to docs/internal_api/index.rst
• User functions have been added to docs/user_api/index.rst

Examples

• Any new notebook examples added to docs/examples/ folder
• Clear the output of all cells before committing
• New notebook files added to docs/examples.rst toctree
• New notebook files added to new entry in docs/gallery.yml with appropriate thumbnail photo in docs/_static/thumbnails/

[review-notebook-app]

Check out this pull request on 

See visual diffs & provide feedback on Jupyter Notebooks.

---

Powered by ReviewNB