Point In Face & Get Faces Containing Point

[aaronzedwick]

Adds several new features:

• point_in_face function to determine if a point is in a face.
• get_faces_containing_point which given a point finds the face (or faces) the point resides in.
• max_face_radius which finds the largest face radius and stores it within the grid.
• haversine_distance function which finds the haversine distance between two given points.
• A few fixes to coordinate construction bugs

Closes #905, #1141

Overview

Expected Usage

from uxarray.grid.geometry import point_in_polygon

# Defined polygon
polygon = [ [-10,  10, -10, 10], [10, 10, -10, -10]]

# Point to check
point = [10, 10]

point_in_polygon(polygon, point, inclusive=True)

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

[aaronzedwick]

@ philipc2 do you think this should be an internal function or exposed to the user?

[philipc2]

Please include an ASV benchmark. I'd suggest doing a parameterized benchmark for the 120 and 480 km MPAS grids.

[philipc2]

Please use the optimized functions from #1072 and try to write the function entirely in Numba. This may require us to pass in both the cartesian and spherical versions of point & polygon. Let me know if you have any questions!

[philipc2]

Please add a couple points in the "Overview" of the description of this PR.

[aaronzedwick]

Please add a couple points in the "Overview" of the description of this PR.

Done! It made me realize just how big this PR has gotten!

[rajeeja]

Resolve comments.

[philipc2]

For the notebook:

• Add an introduction below the title consistent with how other notebooks are formatted.
• I don't think we should be showcasing the point_in_face function from the start. We should highlight the Grid functionality. I think we can restructure the notebook to remove the point_in_face part
• Consider adding intermediate markdown blocks between each cell and try to avoid the inline comments, these should be in Markdown

[aaronzedwick]

For the notebook:

• Add an introduction below the title consistent with how other notebooks are formatted.
• I don't think we should be showcasing the point_in_face function from the start. We should highlight the Grid functionality. I think we can restructure the notebook to remove the point_in_face part
• Consider adding intermediate markdown blocks between each cell and try to avoid the inline comments, these should be in Markdown

Removing the point_in_face part doesn't leave much of the notebook left; do you think this function needs a notebook? It is a pretty self-explanatory function to use.

[philipc2]

For the notebook:

• Add an introduction below the title consistent with how other notebooks are formatted.
• I don't think we should be showcasing the point_in_face function from the start. We should highlight the Grid functionality. I think we can restructure the notebook to remove the point_in_face part
• Consider adding intermediate markdown blocks between each cell and try to avoid the inline comments, these should be in Markdown

Removing the point_in_face part doesn't leave much of the notebook left; do you think this function needs a notebook? It is a pretty self-explanatory function to use.

Maybe we can hold off on the notebook for right now, and keep the examples contained within the docstring?

[philipc2]

Using this syntax/style would be good

    Examples
    --------
    >>> import uxarray as ux
    Open a grid from a file path
    >>> uxgrid = ux.open_grid("grid_filename.nc")

    Lazily load grid variables using Dask
    >>> uxgrid = ux.open_grid("grid_filename.nc", chunks=-1)

[aaronzedwick]

Using this syntax/style would be good

    Examples
    --------
    >>> import uxarray as ux
    Open a grid from a file path
    >>> uxgrid = ux.open_grid("grid_filename.nc")

    Lazily load grid variables using Dask
    >>> uxgrid = ux.open_grid("grid_filename.nc", chunks=-1)

Ok! Yeah, I think this works better.

[philipc2]

Excellent work!