Rename helper function to not mention bicubic (#75)

* rename helper function to not mention bicubic

* add a deprecated function version

* fix formatting

* adjust the deprecated function to work properly

* add NEWS entry about the deprecation

* Update ext/TrixiBottomTopographyMakieExt.jl

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update NEWS.md

Co-authored-by: Joshua Lampert <[email protected]>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Joshua Lampert <[email protected]>

Author: 3 people

NEWS.md

@@ -18,4 +18,6 @@ for human readability.
 
 #### Deprecated
 
+- Helper function `evaluate_bicubicspline_interpolant` renamed to be `evaluate_two_dimensional_interpolant` [#75]
+
 #### Removed

docs/src/function.md

@@ -116,11 +116,11 @@ y_int_pts = Vector(LinRange(spline_struct.y[1], spline_struct.y[end], n))
 
 To fill a matrix `z_int_pts`, which contains the corresponding `z` values
 for `x_int_pts` and `y_int_pts`, we use the helper function
-`evaluate_bicubicspline_interpolant`.
+`evaluate_two_dimensional_interpolant`.
 
 ```@example 2d
 # Get interpolated matrix
-z_int_pts = evaluate_bicubicspline_interpolant(spline_func, x_int_pts, y_int_pts)
+z_int_pts = evaluate_two_dimensional_interpolant(spline_func, x_int_pts, y_int_pts)
 ```
 
 Plotting the interpolated values gives the representation directly below the
@@ -142,7 +142,7 @@ with the interpolation knots as follows
 # Get the original interpolation knots
 x_knots = spline_struct.x
 y_knots = spline_struct.y
-z_knots = evaluate_bicubicspline_interpolant(spline_func, x_knots, y_knots)
+z_knots = evaluate_two_dimensional_interpolant(spline_func, x_knots, y_knots)
 
 plot_topography_with_interpolation_knots(x_int_pts, y_int_pts, z_int_pts,
                                          x_knots, y_knots, z_knots;

examples/rhine_data_bicubic-free.jl

@@ -24,12 +24,12 @@ if isdefined(Main, :Makie)
     y_int_pts = Vector(LinRange(spline_struct.y[1], spline_struct.y[end], n))
 
     # Get interpolated matrix
-    z_int_pts = evaluate_bicubicspline_interpolant(spline_func, x_int_pts, y_int_pts)
+    z_int_pts = evaluate_two_dimensional_interpolant(spline_func, x_int_pts, y_int_pts)
 
     # Get the original interpolation knots
     x_knots = spline_struct.x
     y_knots = spline_struct.y
-    z_knots = evaluate_bicubicspline_interpolant(spline_func, x_knots, y_knots)
+    z_knots = evaluate_two_dimensional_interpolant(spline_func, x_knots, y_knots)
 
     plot_topography_with_interpolation_knots(x_int_pts, y_int_pts, z_int_pts,
                                              x_knots, y_knots, z_knots;

examples/rhine_data_bicubic-nak.jl

@@ -24,7 +24,7 @@ if isdefined(Main, :Makie)
     y_int_pts = Vector(LinRange(spline_struct.y[1], spline_struct.y[end], n))
 
     # Get interpolated matrix
-    z_int_pts = evaluate_bicubicspline_interpolant(spline_func, x_int_pts, y_int_pts)
+    z_int_pts = evaluate_two_dimensional_interpolant(spline_func, x_int_pts, y_int_pts)
 
     plot_topography(x_int_pts, y_int_pts, z_int_pts;
                     xlabel = "ETRS89\n East",

examples/rhine_data_bilinear.jl

@@ -23,7 +23,7 @@ if isdefined(Main, :Makie)
     y_int_pts = Vector(LinRange(spline_struct.y[1], spline_struct.y[end], n))
 
     # Get interpolated matrix
-    z_int_pts = evaluate_bicubicspline_interpolant(spline_func, x_int_pts, y_int_pts)
+    z_int_pts = evaluate_two_dimensional_interpolant(spline_func, x_int_pts, y_int_pts)
 
     plot_topography(x_int_pts, y_int_pts, z_int_pts;
                     xlabel = "E", ylabel = "N", zlabel = "H")

ext/TrixiBottomTopographyMakieExt.jl

@@ -8,17 +8,26 @@ using Makie: Makie
 using TrixiBottomTopography
 
 # Import functions such that they can be extended with new methods
-import TrixiBottomTopography: evaluate_bicubicspline_interpolant, plot_topography,
+import TrixiBottomTopography: evaluate_two_dimensional_interpolant, plot_topography,
                               plot_topography_with_interpolation_knots
 
+# To keep functionality we allow for the old function name `evaluate_bicubicspline_interpolant` to be used.
+# From a front end perspective nothing changes; however, if one starts Julia with `--depwarn=yes`
+# a warning would be thrown when one uses the deprecated function name.
+function TrixiBottomTopography.evaluate_bicubicspline_interpolant(spline, x, y)
+    Base.depwarn("evaluate_bicubicspline_interpolant is deprecated. Use evaluate_two_dimensional_interpolant instead.",
+                 :evaluate_bicubicspline_interpolant)
+    return evaluate_two_dimensional_interpolant(spline, x, y)
+end
+
 """
-    evaluate_bicubicspline_interpolant(spline, x, y)
+    evaluate_two_dimensional_interpolant(spline, x, y)
 
 Helper function to sample the bicubic spline function `spline`
 at the interpolation nodes `x` (with size `n`) and `y` (with size `m`)
 and return the values in an array `z` of size `m` by `n`.
 """
-function evaluate_bicubicspline_interpolant(spline, x, y)
+function evaluate_two_dimensional_interpolant(spline, x, y)
 
     # Get dimensions for solution matrix
     n = length(x)

src/TrixiBottomTopography.jl

@@ -37,9 +37,10 @@ export convert_dgm_1d, convert_dgm_2d
 # Note, Empty routines for visualization are included and exported. They are extended
 # in `ext/TrixiBottomTopographyMakieExt.jl` where their implementations are found.
 function evaluate_bicubicspline_interpolant end
+function evaluate_two_dimensional_interpolant end
 function plot_topography end
 function plot_topography_with_interpolation_knots end
-export evaluate_bicubicspline_interpolant, plot_topography,
-       plot_topography_with_interpolation_knots
+export evaluate_bicubicspline_interpolant, evaluate_two_dimensional_interpolant,
+       plot_topography, plot_topography_with_interpolation_knots
 
 end