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')

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]

Typo in the user guide.

[github-actions]

ASV Benchmarking

Benchmark Comparison Results

Benchmarks that have improved:

Change	Before [aae303f]	After [3d2cb25]	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'))
-	526M	422M	0.80	mpas_ocean.Integrate.peakmem_integrate('480km')
	failed	7.53±0.01s	n/a	mpas_ocean.RemapDownsample.time_bilinear_remapping

Benchmarks that have stayed the same:

Change	Before [aae303f]	After [3d2cb25]	Ratio	Benchmark (Parameter)
	438M	439M	1	face_bounds.FaceBounds.peakmem_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/mpas/QU/oQU480.231010.nc'))
	468M	468M	1	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'))
	20.9±0.2ms	21.4±0.6ms	1.03	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/mpas/QU/oQU480.231010.nc'))
	9.13±0.2μs	8.95±0.1μs	0.98	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/scrip/outCSne8/outCSne8.nc'))
	46.1±1ms	44.4±0.4ms	0.96	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/geoflow-small/grid.nc'))
	3.95±0.1ms	3.94±0.1ms	1	face_bounds.FaceBounds.time_face_bounds(PosixPath('/home/runner/work/uxarray/uxarray/test/meshfiles/ugrid/quad-hexagon/grid.nc'))
	12.1±0.1s	12.1±0.06s	1	import.Imports.timeraw_import_uxarray
	785±7μs	780±8μs	0.99	mpas_ocean.CheckNorm.time_check_norm('120km')
	509±4μs	506±2μs	1	mpas_ocean.CheckNorm.time_check_norm('480km')
	674±5ms	660±20ms	0.98	mpas_ocean.ConnectivityConstruction.time_face_face_connectivity('120km')
	42.4±0.4ms	43.3±0.7ms	1.02	mpas_ocean.ConnectivityConstruction.time_face_face_connectivity('480km')
	5.67±0.03μs	5.67±0.03μs	1	mpas_ocean.ConnectivityConstruction.time_n_nodes_per_face('120km')
	5.65±0.02μs	5.64±0.03μs	1	mpas_ocean.ConnectivityConstruction.time_n_nodes_per_face('480km')
	5.28±0.09ms	5.20±0.04ms	0.99	mpas_ocean.ConstructFaceLatLon.time_cartesian_averaging('120km')
	3.89±0.05ms	3.85±0.03ms	0.99	mpas_ocean.ConstructFaceLatLon.time_cartesian_averaging('480km')
	3.56±0.02s	3.50±0.03s	0.98	mpas_ocean.ConstructFaceLatLon.time_welzl('120km')
	227±2ms	224±1ms	0.99	mpas_ocean.ConstructFaceLatLon.time_welzl('480km')
	755±7ns	707±2ns	0.94	mpas_ocean.ConstructTreeStructures.time_ball_tree('120km')
	291±1ns	279±2ns	0.96	mpas_ocean.ConstructTreeStructures.time_ball_tree('480km')
	557±10ns	546±5ns	0.98	mpas_ocean.ConstructTreeStructures.time_kd_tree('120km')
	295±5ns	284±1ns	0.96	mpas_ocean.ConstructTreeStructures.time_kd_tree('480km')
	462±7ms	463±8ms	1	mpas_ocean.CrossSections.time_const_lat('120km', 1)
	237±3ms	232±2ms	0.98	mpas_ocean.CrossSections.time_const_lat('120km', 2)
	122±1ms	121±2ms	1	mpas_ocean.CrossSections.time_const_lat('120km', 4)
	377±4ms	382±2ms	1.01	mpas_ocean.CrossSections.time_const_lat('480km', 1)
	193±2ms	191±4ms	0.99	mpas_ocean.CrossSections.time_const_lat('480km', 2)
	99.9±0.7ms	98.8±0.7ms	0.99	mpas_ocean.CrossSections.time_const_lat('480km', 4)
	126±1ms	125±1ms	0.99	mpas_ocean.DualMesh.time_dual_mesh_construction('120km')
	10.3±0.3ms	9.64±0.3ms	0.93	mpas_ocean.DualMesh.time_dual_mesh_construction('480km')
	1.12±0.02s	1.10±0.02s	0.98	mpas_ocean.GeoDataFrame.time_to_geodataframe('120km', False)
	88.8±0.2ms	88.4±0.9ms	0.99	mpas_ocean.GeoDataFrame.time_to_geodataframe('480km', False)
	5.40±0.09ms	5.35±0.1ms	0.99	mpas_ocean.GeoDataFrame.time_to_geodataframe('480km', True)
	425M	425M	1	mpas_ocean.Gradient.peakmem_gradient('120km')
	411M	411M	1	mpas_ocean.Gradient.peakmem_gradient('480km')
	2.83±0.07ms	2.81±0.05ms	0.99	mpas_ocean.Gradient.time_gradient('120km')
	331±10μs	330±10μs	1	mpas_ocean.Gradient.time_gradient('480km')
	239±3μs	249±5μs	1.04	mpas_ocean.HoleEdgeIndices.time_construct_hole_edge_indices('120km')
	122±2μs	121±2μs	0.99	mpas_ocean.HoleEdgeIndices.time_construct_hole_edge_indices('480km')
	435M	435M	1	mpas_ocean.Integrate.peakmem_integrate('120km')
	149±1ms	148±3ms	0.99	mpas_ocean.Integrate.time_integrate('120km')
	10.7±0.09ms	10.4±0.3ms	0.98	mpas_ocean.Integrate.time_integrate('480km')
	350±2ms	356±3ms	1.02	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'exclude')
	349±2ms	354±3ms	1.01	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'include')
	351±4ms	356±4ms	1.01	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('120km', 'split')
	22.7±0.1ms	23.2±0.2ms	1.02	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'exclude')
	22.9±0.07ms	23.3±0.3ms	1.02	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'include')
	22.7±0.3ms	23.0±0.09ms	1.01	mpas_ocean.MatplotlibConversion.time_dataarray_to_polycollection('480km', 'split')
	4.69±0.04ms	4.59±0.05ms	0.98	mpas_ocean.PointInPolygon.time_face_search('120km')
	4.69±0.04ms	4.77±0.09ms	1.02	mpas_ocean.PointInPolygon.time_face_search('480km')
	55.8±0.07ms	55.9±0.1ms	1	mpas_ocean.RemapDownsample.time_inverse_distance_weighted_remapping
	45.7±0.2ms	45.5±0.3ms	0.99	mpas_ocean.RemapDownsample.time_nearest_neighbor_remapping
	356±1ms	357±2ms	1	mpas_ocean.RemapUpsample.time_inverse_distance_weighted_remapping
	260±0.7ms	261±0.4ms	1	mpas_ocean.RemapUpsample.time_nearest_neighbor_remapping
	26.0±0.8ms	28.1±1ms	1.08	mpas_ocean.ZonalAverage.time_zonal_average('120km')
	5.09±0.1ms	4.85±0.03ms	0.95	mpas_ocean.ZonalAverage.time_zonal_average('480km')
	405M	405M	1	quad_hexagon.QuadHexagon.peakmem_open_dataset
	405M	405M	1	quad_hexagon.QuadHexagon.peakmem_open_grid
	7.50±0.01ms	7.48±0.05ms	1	quad_hexagon.QuadHexagon.time_open_dataset
	6.58±0.05ms	6.53±0.06ms	0.99	quad_hexagon.QuadHexagon.time_open_grid

Benchmarks that have got worse:

Change	Before [aae303f]	After [3d2cb25]	Ratio	Benchmark (Parameter)
+	1.28±0.01ms	1.43±0.03ms	1.12	mpas_ocean.GeoDataFrame.time_to_geodataframe('120km', True)