Fix typo in shift inversion docstring, and describe algorithm

lisainstrument/shift_inversion_numpy.py

@@ -79,7 +79,7 @@ class ShiftInverseNumpy:  # pylint: disable=too-few-public-methods
     It will be computed for locations
     $ u_l = u_0 + l \Delta u $ regularly spaced with respect to the
     $u$-coordinate, i.e. the output will be the sequence
-    $ \hat{S}_l = u_l - \hat{S}(u_l) $.
+    $ \hat{S}_l = u_l - v(u_l) $.
 
     Currently, we restrict to the special case where $u_k = v_k$,
     i.e. $v_0 = u_0$ and $\Delta u = \Delta v$.
@@ -169,6 +169,35 @@ class ShiftInverseNumpy:  # pylint: disable=too-few-public-methods
         The output sample locations are not returned, but are implicitly
         equal to the input ones, meaning $ v_l = u_l $.
 
+
+        The algorithm works using fixed point iteration
+        $ \hat{S}_l^{n+1} = f(l,\hat{S}_l^{n}) $,
+        where
+        $ f(l,d) = I[v_k, S_k](v_l - d) $, and $I[v_k, S_k]$ is a
+        function obtained by interpolating the samples $v_k, S_k$,
+        approximating  $I[v_k, S_k](v) \approx S(v) $.
+        On the technical level, the interpolation operator is implemented
+        using shifts directly, with an interface of the form
+        $I[S_k](d_l) \approx S(v_l + d_l)$.
+
+        If the iteration converges, it converges to a solution
+        $ \bar{S}_l = f(l,\bar{S}_l) \approx S(v_l - \bar{S}_l) =  S(u_l - \bar{S}_l)$,
+        where we used the implicit convention that $u_l = v_l$.
+        This equation fulfilled for $\bar{S}_l $ is indeed the one that
+        needs to be fulfilled for the desired quantity $\hat{S}_l$, which
+        can be shown as follows:
+        $u_l = u(v(u_l)) = S(v(u_l)) + v(u_l)$ and hence
+        $\hat{S}_l = u_l - v(u_l) = S(v(u_l)) = S(u_l - \hat{S}_l).
+        This shows that the iteration converges to the correct solution if
+        it converges.
+
+        The initial value is $ \hat{S}_l^0 = S_l $.
+        The iteration is repeated until
+        $ \max_l |\hat{S}_l^{n+1} - \hat{S}_l^{n} | < \epsilon $,
+        where $\epsilon$ is the tolerance specified when constructing
+        the operator.
+
+
         Arguments:
             shift: 1D numpy array with shifts of the coordinate transform [s]