Improve handling of degenerate jacobians in non-rectilinear grids.

anntzer · anntzer · commit e4ef1cd2cc31 · 2022-12-13T22:37:52.000+01:00
grid_helper_curvelinear and floating_axes have code to specifically
handle the case where the transform from rectlinear to non-rectilinear
axes has null derivatives in one of the directions, inferring the angle
of the jacobian from the derivative in the other direction.  (This angle
defines the rotation applied to axis labels, ticks, and tick labels.)

This approach, however, is insufficient if the derivatives in both
directions are zero.  A classical example is e.g. the ``exp(-1/x**2)``
transform, for which all derivatives are zero.  To handle this case more
robustly (and also to better encapsulate the angle calculation, which is
currently repeated at a few places), instead, one can increase the step
size of the numerical differentiation until the gradient becomes
nonzero.  This amounts to moving along the corresponding gridline until
one actually leaves the position of the tick, and thus is indeed a
justifiable approach to compute the tick rotation.

Full example:

    import matplotlib.pyplot as plt
    import mpl_toolkits.axisartist.floating_axes as floating_axes
    import numpy as np

    # def tr(x, y): return x - y, x + y
    # def inv_tr(u, v): return (u + v) / 2, (v - u) / 2

    @np.errstate(divide="ignore")  # at x=0, exp(-1/x**2)=0; div-by-zero can be ignored.
    def tr(x, y):
        return np.exp(-x**-2) - np.exp(-y**-2), np.exp(-x**-2) + np.exp(-y**-2)
    def inv_tr(u, v):
        return (-np.log((u+v)/2))**(1/2), (-np.log((v-u)/2))**(1/2)

    ax1 = plt.figure().add_subplot(
        axes_class=floating_axes.FloatingAxes,
        grid_helper=floating_axes.GridHelperCurveLinear(
            (tr, inv_tr), extremes=(0, 10, 0, 10)))

    plt.show()

np.broadcast_shapes requires numpy 1.20, which is allowed per NEP29.
diff --git a/doc/api/next_api_changes/development/24714-AL.rst b/doc/api/next_api_changes/development/24714-AL.rst
@@ -0,0 +1,2 @@
+numpy>=1.20 is now required
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/doc/devel/dependencies.rst b/doc/devel/dependencies.rst
@@ -21,7 +21,7 @@ reference.
 * `dateutil <https://pypi.org/project/python-dateutil/>`_ (>= 2.7)
 * `fontTools <https://fonttools.readthedocs.io/en/latest/>`_ (>= 4.22.0)
 * `kiwisolver <https://github.com/nucleic/kiwi>`_ (>= 1.0.1)
-* `NumPy <https://numpy.org>`_ (>= 1.19)
+* `NumPy <https://numpy.org>`_ (>= 1.20)
 * `packaging <https://pypi.org/project/packaging/>`_ (>= 20.0)
 * `Pillow <https://pillow.readthedocs.io/en/latest/>`_ (>= 6.2)
 * `pyparsing <https://pypi.org/project/pyparsing/>`_ (>= 2.3.1)
@@ -203,7 +203,7 @@ Setup dependencies
 - `setuptools_scm <https://pypi.org/project/setuptools-scm/>`_ (>= 7).  Used to
   update the reported ``mpl.__version__`` based on the current git commit.
   Also a runtime dependency for editable installs.
-- `NumPy <https://numpy.org>`_ (>= 1.19).  Also a runtime dependency.
+- `NumPy <https://numpy.org>`_ (>= 1.20).  Also a runtime dependency.
 
 
 .. _compile-dependencies:
diff --git a/environment.yml b/environment.yml
@@ -14,7 +14,7 @@ dependencies:
   - fonttools>=4.22.0
   - importlib-resources>=3.2.0
   - kiwisolver>=1.0.1
-  - numpy>=1.19
+  - numpy>=1.20
   - pillow>=6.2
   - pygobject
   - pyparsing
diff --git a/lib/matplotlib/__init__.py b/lib/matplotlib/__init__.py
@@ -217,7 +217,7 @@ def _check_versions():
             ("cycler", "0.10"),
             ("dateutil", "2.7"),
             ("kiwisolver", "1.0.1"),
-            ("numpy", "1.19"),
+            ("numpy", "1.20"),
             ("pyparsing", "2.3.1"),
     ]:
         module = importlib.import_module(modname)
diff --git a/lib/mpl_toolkits/axisartist/floating_axes.py b/lib/mpl_toolkits/axisartist/floating_axes.py
@@ -68,25 +68,19 @@ def trf_xy(x, y):
 
         if self.nth_coord == 0:
             mask = (ymin <= yy0) & (yy0 <= ymax)
-            (xx1, yy1), (dxx1, dyy1), (dxx2, dyy2) = \
-                grid_helper_curvelinear._value_and_jacobian(
+            (xx1, yy1), angle_normal, angle_tangent = \
+                grid_helper_curvelinear._value_and_jac_angle(
                     trf_xy, self.value, yy0[mask], (xmin, xmax), (ymin, ymax))
             labels = self._grid_info["lat_labels"]
 
         elif self.nth_coord == 1:
             mask = (xmin <= xx0) & (xx0 <= xmax)
-            (xx1, yy1), (dxx2, dyy2), (dxx1, dyy1) = \
-                grid_helper_curvelinear._value_and_jacobian(
+            (xx1, yy1), angle_tangent, angle_normal = \
+                grid_helper_curvelinear._value_and_jac_angle(
                     trf_xy, xx0[mask], self.value, (xmin, xmax), (ymin, ymax))
             labels = self._grid_info["lon_labels"]
 
         labels = [l for l, m in zip(labels, mask) if m]
-
-        angle_normal = np.arctan2(dyy1, dxx1)
-        angle_tangent = np.arctan2(dyy2, dxx2)
-        mm = (dyy1 == 0) & (dxx1 == 0)  # points with degenerate normal
-        angle_normal[mm] = angle_tangent[mm] + np.pi / 2
-
         tick_to_axes = self.get_tick_transform(axes) - axes.transAxes
         in_01 = functools.partial(
             mpl.transforms._interval_contains_close, (0, 1))
diff --git a/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py b/lib/mpl_toolkits/axisartist/grid_helper_curvelinear.py
@@ -15,29 +15,58 @@
 from .grid_finder import GridFinder
 
 
-def _value_and_jacobian(func, xs, ys, xlims, ylims):
+def _value_and_jac_angle(func, xs, ys, xlims, ylims):
     """
-    Compute *func* and its derivatives along x and y at positions *xs*, *ys*,
-    while ensuring that finite difference calculations don't try to evaluate
-    values outside of *xlims*, *ylims*.
+    Parameters
+    ----------
+    func : callable
+        A function that transforms the coordinates of a point (x, y) to a new
+        coordinate system (u, v), and which can also take x and y as arrays of
+        shape *shape* and returns (u, v) as a ``(2, shape)`` array.
+    xs, ys : array-likes
+        Points where *func* and its derivatives will be evaluated.
+    xlims, ylims : pairs of floats
+        (min, max) beyond which *func* should not be evaluated.
+
+    Returns
+    -------
+    val
+        Value of *func* at each point of ``(xs, ys)``.
+    thetas_dx
+        Angles (in radians) defined by the (u, v) components of the numerically
+        differentiated ``df/dx`` vector, at each point of ``(xs, ys)``.  If
+        needed, the differentiation step size is increased until at least one
+        component of ``df/dx`` is nonzero, under the constraint of not going
+        out of the *xlims*, *ylims* bounds.
+    thetas_dy
+        Like *thetas_dx*, but for ``df/dy``.
     """
-    eps = np.finfo(float).eps ** (1/2)  # see e.g. scipy.optimize.approx_fprime
+    shape = np.broadcast_shapes(np.shape(xs), np.shape(ys))
     val = func(xs, ys)
-    # Take the finite difference step in the direction where the bound is the
-    # furthest; the step size is min of epsilon and distance to that bound.
-    xlo, xhi = sorted(xlims)
-    dxlo = xs - xlo
-    dxhi = xhi - xs
-    xeps = (np.take([-1, 1], dxhi >= dxlo)
-            * np.minimum(eps, np.maximum(dxlo, dxhi)))
-    val_dx = func(xs + xeps, ys)
-    ylo, yhi = sorted(ylims)
-    dylo = ys - ylo
-    dyhi = yhi - ys
-    yeps = (np.take([-1, 1], dyhi >= dylo)
-            * np.minimum(eps, np.maximum(dylo, dyhi)))
-    val_dy = func(xs, ys + yeps)
-    return (val, (val_dx - val) / xeps, (val_dy - val) / yeps)
+    thetas = []
+    for dfunc, zs, lims in [
+            (lambda eps: func(xs + eps, ys), xs, xlims),
+            (lambda eps: func(xs, ys + eps), ys, ylims),
+    ]:
+        # Take the finite difference step towards the furthest bound; the step
+        # size is min of epsilon and distance to that bound.
+        lo, hi = sorted(lims)
+        dlo = zs - lo
+        dhi = hi - zs
+        sign = np.take([-1, 1], dhi >= dlo)
+        eps_max = np.maximum(dlo, dhi)
+        thetas_dz = np.empty(shape)
+        missing = np.full(shape, True)
+        eps = np.finfo(float).eps ** (1/2)  # cf. scipy.optimize.approx_fprime
+        while missing.any() and (eps < eps_max).any():
+            eps = sign * np.minimum(eps, eps_max)
+            df_x, df_y = (dfunc(eps) - val) / eps
+            good = missing & ((df_x != 0) | (df_y != 0))
+            thetas_dz[good] = np.arctan2(df_y, df_x)[good]
+            missing &= ~good
+            eps *= 2
+        thetas.append(thetas_dz)
+    return (val, *thetas)
 
 
 class FixedAxisArtistHelper(AxisArtistHelper.Fixed):
@@ -157,12 +186,11 @@ def trf_xy(x, y):
         elif self.nth_coord == 1:
             xx0 = (xmin + xmax) / 2
             yy0 = self.value
-        xy1, dxy1_dx, dxy1_dy = _value_and_jacobian(
+        xy1, angle_dx, angle_dy = _value_and_jac_angle(
             trf_xy, xx0, yy0, (xmin, xmax), (ymin, ymax))
         p = axes.transAxes.inverted().transform(xy1)
         if 0 <= p[0] <= 1 and 0 <= p[1] <= 1:
-            d = [dxy1_dy, dxy1_dx][self.nth_coord]
-            return xy1, np.rad2deg(np.arctan2(*d[::-1]))
+            return xy1, np.rad2deg([angle_dy, angle_dx][self.nth_coord])
         else:
             return None, None
 
@@ -187,23 +215,17 @@ def trf_xy(x, y):
         # find angles
         if self.nth_coord == 0:
             mask = (e0 <= yy0) & (yy0 <= e1)
-            (xx1, yy1), (dxx1, dyy1), (dxx2, dyy2) = _value_and_jacobian(
+            (xx1, yy1), angle_normal, angle_tangent = _value_and_jac_angle(
                 trf_xy, self.value, yy0[mask], (-np.inf, np.inf), (e0, e1))
             labels = self._grid_info["lat_labels"]
 
         elif self.nth_coord == 1:
             mask = (e0 <= xx0) & (xx0 <= e1)
-            (xx1, yy1), (dxx2, dyy2), (dxx1, dyy1) = _value_and_jacobian(
+            (xx1, yy1), angle_tangent, angle_normal = _value_and_jac_angle(
                 trf_xy, xx0[mask], self.value, (-np.inf, np.inf), (e0, e1))
             labels = self._grid_info["lon_labels"]
 
         labels = [l for l, m in zip(labels, mask) if m]
-
-        angle_normal = np.arctan2(dyy1, dxx1)
-        angle_tangent = np.arctan2(dyy2, dxx2)
-        mm = (dyy1 == 0) & (dxx1 == 0)  # points with degenerate normal
-        angle_normal[mm] = angle_tangent[mm] + np.pi / 2
-
         tick_to_axes = self.get_tick_transform(axes) - axes.transAxes
         in_01 = functools.partial(
             mpl.transforms._interval_contains_close, (0, 1))
diff --git a/lib/mpl_toolkits/axisartist/tests/test_floating_axes.py b/lib/mpl_toolkits/axisartist/tests/test_floating_axes.py
@@ -1,5 +1,7 @@
 import numpy as np
 
+import pytest
+
 import matplotlib.pyplot as plt
 import matplotlib.projections as mprojections
 import matplotlib.transforms as mtransforms
@@ -112,3 +114,29 @@ def test_axis_direction():
     ax.axis['y'] = ax.new_floating_axis(nth_coord=1, value=0,
                                         axis_direction='left')
     assert ax.axis['y']._axis_direction == 'left'
+
+
+def test_transform_with_zero_derivatives():
+    # The transform is really a 45° rotation
+    #     tr(x, y) = x-y, x+y; inv_tr(u, v) = (u+v)/2, (u-v)/2
+    # with an additional x->exp(-x**-2) on each coordinate.
+    # Therefore all ticks should be at +/-45°, even the one at zero where the
+    # transform derivatives are zero.
+
+    # at x=0, exp(-x**-2)=0; div-by-zero can be ignored.
+    @np.errstate(divide="ignore")
+    def tr(x, y):
+        return np.exp(-x**-2) - np.exp(-y**-2), np.exp(-x**-2) + np.exp(-y**-2)
+
+    def inv_tr(u, v):
+        return (-np.log((u+v)/2))**(1/2), (-np.log((v-u)/2))**(1/2)
+
+    fig = plt.figure()
+    ax = fig.add_subplot(
+        axes_class=FloatingAxes, grid_helper=GridHelperCurveLinear(
+            (tr, inv_tr), extremes=(0, 10, 0, 10)))
+    fig.canvas.draw()
+
+    for k in ax.axis:
+        for l, a in ax.axis[k].major_ticks.locs_angles:
+            assert a % 90 == pytest.approx(45, abs=1e-3)
diff --git a/requirements/testing/minver.txt b/requirements/testing/minver.txt
@@ -4,7 +4,7 @@ contourpy==1.0.1
 cycler==0.10
 kiwisolver==1.0.1
 importlib-resources==3.2.0
-numpy==1.19.0
+numpy==1.20.0
 packaging==20.0
 pillow==6.2.1
 pyparsing==2.3.1
diff --git a/setup.py b/setup.py
@@ -322,7 +322,7 @@ def make_release_tree(self, base_dir, files):
         "cycler>=0.10",
         "fonttools>=4.22.0",
         "kiwisolver>=1.0.1",
-        "numpy>=1.19",
+        "numpy>=1.20",
         "packaging>=20.0",
         "pillow>=6.2.0",
         "pyparsing>=2.3.1",

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+numpy>=1.20 is now required`
	`2`	`+~~~~~~~~~~~~~~~~~~~~~~~~~~~`