Bilinear Remapping

[aaronzedwick]

Closes #678

Overview

Adds bilinear remapping functionality to UXarray.

Expected Usage

import uxarray as ux

source = "/path"
destination = "/path"
source_uxds = ux.open_dataset(destination, destination)
destination = ux.open_dataset(destination, destination)

bilinear_remap = source_uxds.remap.bilinear(destination.uxgrid, remap_to='face centers',
                                                       coord_type='cartesian')

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

[philipc2]

Once this is implemented, @rajeeja this would be a good place to compare our implementation to the one in ESMF.

[philipc2]

Typo in the user guide.

[github-actions]

ASV Benchmarking

Benchmark Comparison Results

Benchmarks that have improved:

Change	Before [aae303f]	After [6fb2230]	Ratio	Benchmark (Parameter)
-	744M	438M	0.59	face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/quad-hexagon/grid.nc'))
-	20.0±0.05ms	15.4±0.06μs	0.00	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/mpas/QU/oQU480.231010.nc'))
-	526M	421M	0.80	mpas_ocean.Integrate.peakmem_integrate('480km')
	failed	7.40±0.06s	n/a	mpas_ocean.RemapDownsample.time_bilinear_remapping

Benchmarks that have stayed the same:

Change	Before [aae303f]	After [6fb2230]	Ratio	Benchmark (Parameter)
	438M	438M	1.00	face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/mpas/QU/oQU480.231010.nc'))
	468M	468M	1.00	face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/scrip/outCSne8/outCSne8.nc'))
	478M	441M	0.92	face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/geoflow-small/grid.nc'))
	9.28±0.05μs	9.15±0.08μs	0.99	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/scrip/outCSne8/outCSne8.nc'))
	43.8±0.4ms	43.1±0.1ms	0.98	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/geoflow-small/grid.nc'))
	3.62±0.09ms	3.65±0.09ms	1.01	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/quad-hexagon/grid.nc'))
	11.7±0.1s	11.6±0.02s	0.99	import.Imports.timeraw_import_uxarray
	762±10μs	772±9μs	1.01	mpas_ocean.CheckNorm.time_check_norm('120km')
	506±4μs	511±5μs	1.01	mpas_ocean.CheckNorm.time_check_norm('480km')
	641±5ms	645±10ms	1.01	mpas_ocean.ConnectivityConstruction.time_face_face_connectivity('120km')
	41.5±0.4ms	42.1±1ms	1.01	mpas_ocean.ConnectivityConstruction.time_face_face_connectivity('480km')
	5.58±0.02μs	5.69±0.02μs	1.02	mpas_ocean.ConnectivityConstruction.time_n_nodes_per_face('120km')
	5.57±0.06μs	5.67±0.07μs	1.02	mpas_ocean.ConnectivityConstruction.time_n_nodes_per_face('480km')
	5.16±0.06ms	5.14±0.01ms	1.00	mpas_ocean.ConstructFaceLatLon.time_cartesian_averaging('120km')
	3.85±0.03ms	3.88±0.03ms	1.01	mpas_ocean.ConstructFaceLatLon.time_cartesian_averaging('480km')
	3.47±0.02s	3.48±0.01s	1.00	mpas_ocean.ConstructFaceLatLon.time_welzl('120km')
	223±1ms	223±1ms	1.00	mpas_ocean.ConstructFaceLatLon.time_welzl('480km')
	833±100ns	698±6ns	~0.84	mpas_ocean.ConstructTreeStructures.time_ball_tree('120km')
	389±100ns	282±10ns	~0.72	mpas_ocean.ConstructTreeStructures.time_ball_tree('480km')
	648±100ns	524±10ns	~0.81	mpas_ocean.ConstructTreeStructures.time_kd_tree('120km')
	397±100ns	287±8ns	~0.72	mpas_ocean.ConstructTreeStructures.time_kd_tree('480km')
	450±6ms	450±1ms	1.00	mpas_ocean.CrossSections.time_const_lat('120km', 1)
	230±4ms	228±2ms	0.99	mpas_ocean.CrossSections.time_const_lat('120km', 2)
	117±0.4ms	118±0.3ms	1.01	mpas_ocean.CrossSections.time_const_lat('120km', 4)
	378±3ms	380±3ms	1.00	mpas_ocean.CrossSections.time_const_lat('480km', 1)
	189±1ms	190±1ms	1.01	mpas_ocean.CrossSections.time_const_lat('480km', 2)
	97.7±1ms	99.5±1ms	1.02	mpas_ocean.CrossSections.time_const_lat('480km', 4)
	124±1ms	124±0.5ms	0.99	mpas_ocean.DualMesh.time_dual_mesh_construction('120km')
	9.25±0.1ms	9.26±0.1ms	1.00	mpas_ocean.DualMesh.time_dual_mesh_construction('480km')
	1.10±0.02s	1.09±0s	0.99	mpas_ocean.GeoDataFrame.time_to_geodataframe('120km', False)
	1.30±0.01ms	1.20±0.03ms	0.92	mpas_ocean.GeoDataFrame.time_to_geodataframe('120km', True)
	87.5±2ms	87.1±0.8ms	1.00	mpas_ocean.GeoDataFrame.time_to_geodataframe('480km', False)
	4.98±0.08ms	4.97±0.05ms	1.00	mpas_ocean.GeoDataFrame.time_to_geodataframe('480km', True)
	425M	425M	1.00	mpas_ocean.Gradient.peakmem_gradient('120km')
	408M	408M	1.00	mpas_ocean.Gradient.peakmem_gradient('480km')
	2.70±0.03ms	2.71±0.02ms	1.00	mpas_ocean.Gradient.time_gradient('120km')
	316±4μs	316±3μs	1.00	mpas_ocean.Gradient.time_gradient('480km')
	238±8μs	234±3μs	0.98	mpas_ocean.HoleEdgeIndices.time_construct_hole_edge_indices('120km')
	120±0.7μs	119±0.9μs	0.99	mpas_ocean.HoleEdgeIndices.time_construct_hole_edge_indices('480km')
	435M	435M	1.00	mpas_ocean.Integrate.peakmem_integrate('120km')
	146±1ms	146±1ms	1.00	mpas_ocean.Integrate.time_integrate('120km')
	10.8±0.5ms	10.6±0.2ms	0.98	mpas_ocean.Integrate.time_integrate('480km')
	341±2ms	351±1ms	1.03	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'exclude')
	342±3ms	347±2ms	1.01	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'include')
	344±2ms	348±4ms	1.01	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'split')
	22.0±0.2ms	22.0±0.1ms	1.00	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'exclude')
	22.3±0.3ms	22.0±0.3ms	0.99	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'include')
	21.9±0.09ms	22.5±0.3ms	1.03	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'split')
	4.51±0.01ms	4.53±0.02ms	1.01	mpas_ocean.PointInPolygon.time_face_search('120km')
	4.68±0.08ms	4.68±0.09ms	1.00	mpas_ocean.PointInPolygon.time_face_search('480km')
	55.1±0.2ms	56.2±0.5ms	1.02	mpas_ocean.RemapDownsample.time_inverse_distance_weighted_remapping
	44.9±0.2ms	45.4±0.6ms	1.01	mpas_ocean.RemapDownsample.time_nearest_neighbor_remapping
	355±1ms	355±0.8ms	1.00	mpas_ocean.RemapUpsample.time_inverse_distance_weighted_remapping
	260±1ms	262±3ms	1.01	mpas_ocean.RemapUpsample.time_nearest_neighbor_remapping
	24.8±0.4ms	24.5±0.5ms	0.99	mpas_ocean.ZonalAverage.time_zonal_average('120km')
	4.69±0.02ms	4.61±0.2ms	0.98	mpas_ocean.ZonalAverage.time_zonal_average('480km')
	406M	406M	1.00	quad_hexagon.QuadHexagon.peakmem_open_dataset
	406M	403M	0.99	quad_hexagon.QuadHexagon.peakmem_open_grid
	7.34±0.02ms	7.49±0.1ms	1.02	quad_hexagon.QuadHexagon.time_open_dataset
	6.46±0.1ms	6.49±0.04ms	1.00	quad_hexagon.QuadHexagon.time_open_grid