Repository: scipy/scipy

Issue:
DOC: scipy.interpolate.RegularGridInterpolator and interpn works for rectilinear grids, not just regular grids.
### Issue with current documentation:

The documentation for scipy.interpolate.RegularGridInterpolator describes the class as for "Interpolation on a regular grid in arbitrary dimensions" and there is this statement, "The data must be defined on a regular grid; the grid spacing however may be uneven." Isn't such a grid a rectilinear grid, and not explicitly *not* a regular grid? See [Regular Grid](https://en.wikipedia.org/wiki/Regular_grid).

The really odd thing about all of this is that the code on which this class is based, *regulargrid* by Johannes Buchner, seems to make the same mistake. In the README for the [regulargrid repo](https://github.com/JohannesBuchner/regulargrid), it even links the wikipedia article I've just referenced here at the top. Then it goes on to describe a Cartesian Grid as one with equal spacing between points (correct, but that spacing has to also be equal across each dimension) and a Regular Grid as having unequal spacing between points (incorrect). Beneath this definition of "Cartesian grid", there's an example of a grid which is Regular but not Cartesian. 

Just to make sure that the "Regular grid" was actually rectilinear, I checked regulargrid/test/test_regulargrid.py.  On line 13, the breaks are distributed randomly in each of two spatial dimensions, making it in fact rectilinear and not regular.

I can also confirm that the same mistake is made in scipy.interpolate.interpn - I've used this code on rectilinear grids and it seems to work fine, despite the method saying that a "regular grid" is required many times in the documentation.

I think correcting this is important - I tried for hours to find a rectilinear grid interpolator so that I could use it instead of interpn... it turns out I need not have bothered!

### Suggested fix:

The documentation for scipy.interpolate.RegularGridInterpolator and scipy.interpolate.interpn should be updated to specify that the interpolation happens on a rectilinear grid rather than a regular grid.


Discussion:
Hi @mountaindust, thank you for reporting. Isn't this a duplicate of the discussion we had in #14926?
Just to add to what Pamphile said, https://github.com/scipy/scipy/pull/16073 went in yesteday, so the word _rectilinear _ is now live in the dev version of the documentation (to become 1.9.0 when it is released):  

http://scipy.github.io/devdocs/reference/generated/scipy.interpolate.RegularGridInterpolator.html#scipy.interpolate.RegularGridInterpolator

If you have a better wording or additions to the docstring, pull requests are most welcome!
My searches for existing issues somehow failed to turn up #14926 or #16073, so it's good to see this discussion! I think my main issue with the documentation @ev-br linked to is that the beginning of that paragraph at the top still says "The data must be defined on a regular grid". Yes, it goes on to say "the grid spacing however may be uneven", but since that is a contradiction with the definition of regular grid, I think it just confuses the issue, and a user may not even read that far because... why would you be expecting a contradiction to follow?

You have to go all the way down to the notes before you get a definitive answer about what this class does "In other words, this class assumes that the data is defined on a *rectilinear* grid."

Why not something like:
> Interpolation on a regular or rectilinear grid in arbitrary dimensions.
> 
> The data must be defined on a rectilinear grid; that is, a rectangular grid with even or uneven spacing. Linear, nearest-neighbor,...

Similar for the interpn case, something similarly straightforward:
> Multidimensional interpolation on regular or rectilinear grids.
>
> Strictly speaking, not all regular grids are supported - this function works on rectilinear grids, that is, a rectangular grid with even or uneven spacing.
For the record, and in my personal opinion, it starts pushing towards the overly rigoristic territory.  A user cannot expect that all Bravais lattices (and its N-D generalizations) are magically supported. However, personal opinions aside, would you be interested in sending a PR e.g. your wording @mountaindust ?

Resolving patch:
diff --git a/scipy/interpolate/_interpolate.py b/scipy/interpolate/_interpolate.py
--- a/scipy/interpolate/_interpolate.py
+++ b/scipy/interpolate/_interpolate.py
@@ -2350,12 +2350,12 @@ def integrate(self, ranges, extrapolate=None):
 
 class RegularGridInterpolator:
     """
-    Interpolation on a regular grid in arbitrary dimensions.
+    Interpolation on a regular or rectilinear grid in arbitrary dimensions.
 
-    The data must be defined on a regular grid; the grid spacing however may be
-    uneven. Linear, nearest-neighbor, spline interpolations are supported.
-    After setting up the interpolator object, the interpolation method may be
-    chosen at each evaluation.
+    The data must be defined on a rectilinear grid; that is, a rectangular
+    grid with even or uneven spacing. Linear, nearest-neighbor, spline
+    interpolations are supported. After setting up the interpolator object,
+    the interpolation method may be chosen at each evaluation.
 
     Parameters
     ----------
@@ -2746,10 +2746,11 @@ def _find_indices(self, xi):
 def interpn(points, values, xi, method="linear", bounds_error=True,
             fill_value=np.nan):
     """
-    Multidimensional interpolation on regular grids.
+    Multidimensional interpolation on regular or rectilinear grids.
 
-    Strictly speaking, not all regular grids are supported, and this function
-    works on *rectilinear* grids.
+    Strictly speaking, not all regular grids are supported - this function
+    works on *rectilinear* grids, that is, a rectangular grid with even or
+    uneven spacing.
 
     Parameters
     ----------
@@ -2817,7 +2818,8 @@ def interpn(points, values, xi, method="linear", bounds_error=True,
                            in N dimensions
 
     RegularGridInterpolator : Linear and nearest-neighbor Interpolation on a
-                              regular grid in arbitrary dimensions
+                              regular or rectilinear grid in arbitrary
+                              dimensions
 
     RectBivariateSpline : Bivariate spline approximation over a rectangular mesh
 


Test patch: