Trac #17965: Uniformize the API to compute the inverse of an element

Some classes in Sage implement the inverse of an element through the
inverse method:
{{{
mistral-/opt/sage/src/sage>grep "def inverse(" **/*.py
algebras/finite_dimensional_algebras/finite_dimensional_algebra_element.
py:    def inverse(self):
algebras/iwahori_hecke_algebra.py:            def inverse(self):
categories/coxeter_groups.py:        def inverse(self):
combinat/affine_permutation.py:    def inverse(self):
combinat/permutation.py:    def inverse(self):
combinat/tableau_tuple.py:    def inverse(self,k):
crypto/classical_cipher.py:    def inverse(self):
crypto/classical_cipher.py:    def inverse(self):
crypto/classical_cipher.py:    def inverse(self):
crypto/classical_cipher.py:    def inverse(self):
dynamics/interval_exchanges/iet.py:    def inverse(self):
groups/abelian_gps/element_base.py:    def inverse(self):
groups/abelian_gps/values.py:    def inverse(self):
groups/affine_gps/group_element.py:    def inverse(self):
modules/matrix_morphism.py:    def inverse(self):
rings/number_field/class_group.py:    def inverse(self):
rings/universal_cyclotomic_field/universal_cyclotomic_field.py:
def inverse(self):
schemes/elliptic_curves/formal_group.py:    def inverse(self, prec=20):
schemes/elliptic_curves/weierstrass_transform.py:    def inverse(self):
}}}

Some other through the `__invert__` method:
{{{
mistral-/opt/sage/src/sage>grep "def __invert__(" **/*.py
categories/algebras_with_basis.py:        def __invert__(self):
categories/magmas.py:                def __invert__(self):
categories/modules_with_basis.py:    def __invert__(self):
categories/modules_with_basis.py:    def __invert__(self):
combinat/combinatorial_algebra.py:    def __invert__(self):
combinat/sf/dual.py:        def __invert__(self):
combinat/species/generating_series.py:    def __invert__(self):
groups/indexed_free_group.py:        def __invert__(self):
groups/indexed_free_group.py:        def __invert__(self):
groups/matrix_gps/group_element.py:    def __invert__(self):
groups/raag.py:        def __invert__(self):
libs/coxeter3/coxeter_group.py:        def __invert__(self):
logic/boolformula.py:    def __invert__(self):
misc/sage_input.py:    def __invert__(self):
modular/dirichlet.py:    def __invert__(self):
modular/local_comp/smoothchar.py:    def __invert__(self):
modules/matrix_morphism.py:    def __invert__(self):
rings/continued_fraction.py:    def __invert__(self):
rings/finite_rings/element_ext_pari.py:    def __invert__(self):
rings/function_field/function_field_ideal.py:    def __invert__(self):
rings/infinity.py:    def __invert__(self):
rings/multi_power_series_ring_element.py:    def __invert__(self):
rings/number_field/morphism.py:    def __invert__(self):
rings/number_field/number_field_ideal.py:    def __invert__(self):
rings/number_field/number_field_ideal_rel.py:    def __invert__(self):
rings/pari_ring.py:    def __invert__(self):
rings/polynomial/polynomial_quotient_ring_element.py:    def
__invert__(self):
rings/qqbar.py:    def __invert__(self):
rings/quotient_ring_element.py:    def __invert__(self):
rings/universal_cyclotomic_field/universal_cyclotomic_field.py:
def __invert__(self):
sandpiles/sandpile.py:    def __invert__(self):
schemes/elliptic_curves/heegner.py:    def __invert__(self):
schemes/elliptic_curves/height.py:    def __invert__(self):
schemes/elliptic_curves/weierstrass_morphism.py:    def
__invert__(self):
schemes/elliptic_curves/weierstrass_morphism.py:    def
__invert__(self):
schemes/hyperelliptic_curves/monsky_washnitzer.py:    def
__invert__(self):
structure/factorization.py:    def __invert__(self):
}}}

Usually they provide a crosslink so that `__invert__` and
`inverse` are equivalent, but this is done on a case by case bases,
so of course such links are missing here and there:
{{{
sage: ~AA(sqrt(~2))
1.414213562373095?
sage: AA(sqrt(~2)).inverse()
...
AttributeError: 'AlgebraicReal' object has no attribute 'inverse'
}}}

{{{
sage: R.<u,v,w> = QQ[]
sage: f = EllipticCurve_from_cubic(u^3 + v^3 + w^3, [1,-1,0],
morphism=True)
sage: f.inverse()
Scheme morphism:
...
sage: ~f
...
TypeError: bad operand type for unary ~:
'WeierstrassTransformationWithInverse_class'
}}}

Shall we change the code to systematically implement `__invert__` as
per Python's convention, and then implement the cross link `inverse`
-> `__invert__` once for all high up in the class hierarchy,
typically in `Magmas.ElementMethods`?

Caveat: this won't cover all cases since we have invertible elements
that don't belong to a magma; e.g. a isomorphisms between two
different parents; so it will still be necessary to handle a couple
special cases by hand.

See also comment about `__inverse__` in
sage.categories.coxeter_groups.py around line 699.

Note: the default implementation ~f = 1/f provided by Element should
probably be implemented in `Monoids.ElementMethods`; see also #17692.

Note: the qqbar classes also implement an `invert` method, but that's
for a slightly different use case. So we may, or not, want to make
this uniform too. `invert` does not fit Sage's usual verb/noun
convention since it's a verb while it is not inplace.

URL: https://trac.sagemath.org/17965
Reported by: nthiery
Ticket author(s): Frédéric Chapoton
Reviewer(s): Travis Scrimshaw

Author: Release Manager

src/sage/algebras/hecke_algebras/ariki_koike_algebra.py

@@ -1125,7 +1125,7 @@ def inverse_T(self, i):
             return self._from_dict({m: ~self._q, self.one_basis(): c})
 
         class Element(CombinatorialFreeModule.Element):
-            def inverse(self):
+            def __invert__(self):
                 r"""
                 Return the inverse if ``self`` is a basis element.
 
@@ -1134,7 +1134,7 @@ def inverse(self):
                     sage: LT = algebras.ArikiKoike(3, 4).LT()
                     sage: t = LT.T(1) * LT.T(2) * LT.T(3); t
                     T[1,2,3]
-                    sage: t.inverse()
+                    sage: t.inverse()   # indirect doctest
                     (q^-3-3*q^-2+3*q^-1-1) + (q^-3-2*q^-2+q^-1)*T[3]
                      + (q^-3-2*q^-2+q^-1)*T[2] + (q^-3-q^-2)*T[3,2]
                      + (q^-3-2*q^-2+q^-1)*T[1] + (q^-3-q^-2)*T[1,3]
@@ -1148,8 +1148,6 @@ def inverse(self):
                 H = self.parent()
                 return ~self[l,w] * H.prod(H.inverse_T(i) for i in reversed(w.reduced_word()))
 
-            __invert__ = inverse
-
     class T(_Basis):
         r"""
         The basis of the Ariki-Koike algebra given by monomials of the

src/sage/algebras/iwahori_hecke_algebra.py

@@ -1732,7 +1732,7 @@ class Element(CombinatorialFreeModule.Element):
                 sage: T1.parent()
                 Iwahori-Hecke algebra of type A2 in 1,-1 over Integer Ring in the T-basis
             """
-            def inverse(self):
+            def __invert__(self):
                 r"""
                 Return the inverse if ``self`` is a basis element.
 
@@ -1746,7 +1746,7 @@ def inverse(self):
                     sage: R.<q> = LaurentPolynomialRing(QQ)
                     sage: H = IwahoriHeckeAlgebra("A2", q).T()
                     sage: [T1,T2] = H.algebra_generators()
-                    sage: x = (T1*T2).inverse(); x
+                    sage: x = (T1*T2).inverse(); x   # indirect doctest
                     (q^-2)*T[2,1] + (q^-2-q^-1)*T[1] + (q^-2-q^-1)*T[2] + (q^-2-2*q^-1+1)
                     sage: x*T1*T2
                     1
@@ -1771,8 +1771,6 @@ def inverse(self):
 
                 return H.prod(H.inverse_generator(i) for i in reversed(w.reduced_word()))
 
-            __invert__ = inverse
-
     standard = T
 
     class _KLHeckeBasis(_Basis):

src/sage/algebras/yokonuma_hecke_algebra.py

@@ -454,7 +454,7 @@ def inverse_g(self, i):
         return self.g(i) + (~self._q + self._q) * self.e(i)
 
     class Element(CombinatorialFreeModule.Element):
-        def inverse(self):
+        def __invert__(self):
             r"""
             Return the inverse if ``self`` is a basis element.
 
@@ -463,7 +463,7 @@ def inverse(self):
                 sage: Y = algebras.YokonumaHecke(3, 3)
                 sage: t = prod(Y.t()); t
                 t1*t2*t3
-                sage: ~t
+                sage: t.inverse()   # indirect doctest
                 t1^2*t2^2*t3^2
                 sage: [3*~(t*g) for g in Y.g()]
                 [(q^-1+q)*t2*t3^2 + (q^-1+q)*t1*t3^2
@@ -494,5 +494,3 @@ def inverse(self):
             c = ~self.coefficients()[0]
             telt = H.monomial( (tuple((H._d - e) % H._d for e in t), H._Pn.one()) )
             return c * telt * H.prod(H.inverse_g(i) for i in reversed(w.reduced_word()))
-
-        __invert__ = inverse

src/sage/categories/complex_reflection_or_generalized_coxeter_groups.py

@@ -1142,15 +1142,15 @@ def _mul_(self, other):
             """
             return self.apply_simple_reflections(other.reduced_word())
 
-        def inverse(self):
+        def __invert__(self):
             """
             Return the inverse of ``self``.
 
             EXAMPLES::
 
                 sage: W = WeylGroup(['B',7])
                 sage: w = W.an_element()
-                sage: u = w.inverse()
+                sage: u = w.inverse()  # indirect doctest
                 sage: u == ~w
                 True
                 sage: u * w == w * u
@@ -1166,8 +1166,6 @@ def inverse(self):
             """
             return self.parent().one().apply_simple_reflections(self.reduced_word_reverse_iterator())
 
-        __invert__ = inverse
-
         def apply_conjugation_by_simple_reflection(self, i):
             r"""
             Conjugate ``self`` by the ``i``-th simple reflection.

src/sage/categories/groups.py

@@ -640,27 +640,6 @@ def order(self):
                 from sage.misc.misc_c import prod
                 return prod(c.cardinality() for c in self.cartesian_factors())
 
-        class ElementMethods:
-            def multiplicative_order(self):
-                r"""
-                Return the multiplicative order of this element.
-
-                EXAMPLES::
-
-                    sage: G1 = SymmetricGroup(3)
-                    sage: G2 = SL(2,3)
-                    sage: G = cartesian_product([G1,G2])
-                    sage: G((G1.gen(0), G2.gen(1))).multiplicative_order()
-                    12
-                """
-                from sage.rings.infinity import Infinity
-                orders = [x.multiplicative_order() for x in self.cartesian_factors()]
-                if any(o is Infinity for o in orders):
-                    return Infinity
-                else:
-                    from sage.arith.functions import LCM_list
-                    return LCM_list(orders)
-
     class Topological(TopologicalSpacesCategory):
         """
         Category of topological groups.

src/sage/categories/magmas.py

@@ -671,9 +671,7 @@ def __invert__(self):
                         ZeroDivisionError: rational division by zero
 
                         sage: ~C([2,2,2,2])
-                        Traceback (most recent call last):
-                        ...
-                        TypeError: no conversion of this rational to integer
+                        (1/2, 1/2, 0.500000000000000, 3)
                     """
                     # variant without coercion:
                     # return self.parent()._cartesian_product_of_elements(

src/sage/categories/monoids.py

@@ -252,18 +252,18 @@ def _div_(left, right):
                 sage: c1._div_(c2)
                 (x0*x1^-1, x1*x0^-1)
 
-            With this implementation, division will fail as soon
-            as ``right`` is not invertible, even if ``right``
+            With this default implementation, division will fail as
+            soon as ``right`` is not invertible, even if ``right``
             actually divides ``left``::
 
-                sage: x = cartesian_product([2, 1])
+                sage: x = cartesian_product([2, 0])
                 sage: y = cartesian_product([1, 1])
                 sage: x / y
-                (2, 1)
-                sage: x / x
+                (2, 0)
+                sage: y / x
                 Traceback (most recent call last):
                 ...
-                TypeError: no conversion of this rational to integer
+                ZeroDivisionError: rational division by zero
 
             TESTS::
 
@@ -354,6 +354,37 @@ def powers(self, n):
                 l.append(x)
             return l
 
+        def __invert__(self):
+            r"""
+            Return the multiplicative inverse of ``self``.
+
+            There is no default implementation, to avoid conflict
+            with the default implementation of ``_div_``.
+
+            EXAMPLES::
+
+                sage: A = Matrix([[1, 0], [1, 1]])
+                sage: ~A
+                [ 1 0]
+                [-1 1]
+            """
+            raise NotImplementedError("please implement __invert__")
+
+        def inverse(self):
+            """
+            Return the multiplicative inverse of ``self``.
+
+            This is an alias for inversion, which can also be invoked
+            by ``~x`` for an element ``x``.
+
+            EXAMPLES::
+
+                sage: AA(sqrt(~2)).inverse()
+                1.414213562373095?
+            """
+            # Nota Bene: Element classes should implement ``__invert__`` only.
+            return self.__invert__()
+
     class Commutative(CategoryWithAxiom):
         r"""
         Category of commutative (abelian) monoids.
@@ -639,3 +670,40 @@ def lift(i, gen):
                                                       lambda g: (i, g))
                                                for i, M in enumerate(F)])
                 return Family(gens_prod, lift, name="gen")
+
+        class ElementMethods:
+            def multiplicative_order(self):
+                r"""
+                Return the multiplicative order of this element.
+
+                EXAMPLES::
+
+                    sage: G1 = SymmetricGroup(3)
+                    sage: G2 = SL(2,3)
+                    sage: G = cartesian_product([G1,G2])
+                    sage: G((G1.gen(0), G2.gen(1))).multiplicative_order()
+                    12
+                """
+                from sage.rings.infinity import Infinity
+                orders = [x.multiplicative_order() for x in self.cartesian_factors()]
+                if any(o is Infinity for o in orders):
+                    return Infinity
+                else:
+                    from sage.arith.functions import LCM_list
+                    return LCM_list(orders)
+
+            def __invert__(self):
+                """
+                Return the inverse.
+
+                EXAMPLES::
+
+                    sage: a1 = Permutation((4,2,1,3))
+                    sage: a2 = SL(2,3)([2,1,1,1])
+                    sage: h = cartesian_product([a1,a2])
+                    sage: ~h
+                    ([2, 4, 1, 3], [1 2]
+                    [2 2])
+                """
+                build = self.parent()._cartesian_product_of_elements
+                return build([x.__invert__() for x in self.cartesian_factors()])

src/sage/combinat/affine_permutation.py

@@ -161,21 +161,19 @@ def __mul__(self, q):
         return self.__rmul__(q)
 
     @cached_method
-    def inverse(self):
+    def __invert__(self):
         r"""
         Return the inverse affine permutation.
 
         EXAMPLES::
 
             sage: p = AffinePermutationGroup(['A',7,1])([3, -1, 0, 6, 5, 4, 10, 9])
-            sage: p.inverse()
+            sage: p.inverse()  # indirect doctest
             Type A affine permutation with window [0, -1, 1, 6, 5, 4, 10, 11]
         """
-        inv = [self.position(i) for i in range(1,len(self)+1)]
+        inv = [self.position(i) for i in range(1, len(self) + 1)]
         return type(self)(self.parent(), inv, check=False)
 
-    __invert__=inverse
-
     def apply_simple_reflection(self, i, side='right'):
         r"""
         Apply a simple reflection.
@@ -855,8 +853,8 @@ def to_lehmer_code(self, typ='decreasing', side='right'):
                 a=self(i)
                 for j in range(i-self.k, i):
                     b=self(j)
-                    #A small rotation is necessary for the reduced word from
-                    #the lehmer code to match the element.
+                    # A small rotation is necessary for the reduced word from
+                    # the Lehmer code to match the element.
                     if a < b:
                         code[i-1]+=((b-a)//(self.k+1)+1)
         elif typ[0] == 'i' and side[0] == 'l':
@@ -2330,6 +2328,7 @@ def from_lehmer_code(self, C, typ='decreasing', side='right'):
 
     Element = AffinePermutationTypeA
 
+
 class AffinePermutationGroupTypeC(AffinePermutationGroupGeneric):
     #------------------------
     #Type-specific methods.

src/sage/combinat/colored_permutations.py

@@ -109,15 +109,15 @@ def _mul_(self, other):
         p = self._perm._left_to_right_multiply_on_right(other._perm)
         return self.__class__(self.parent(), colors, p)
 
-    def inverse(self):
+    def __invert__(self):
         """
         Return the inverse of ``self``.
 
         EXAMPLES::
 
             sage: C = ColoredPermutations(4, 3)
             sage: s1,s2,t = C.gens()
-            sage: ~t
+            sage: ~t  # indirect doctest
             [[0, 0, 3], [1, 2, 3]]
             sage: all(x * ~x == C.one() for x in C.gens())
             True
@@ -127,8 +127,6 @@ def inverse(self):
                               tuple(-self._colors[i - 1] for i in ip),  # -1 for indexing
                               ip)
 
-    __invert__ = inverse
-
     def __eq__(self, other):
         """
         Check equality.
@@ -1030,7 +1028,7 @@ def _mul_(self, other):
         p = self._perm._left_to_right_multiply_on_right(other._perm)
         return self.__class__(self.parent(), colors, p)
 
-    def inverse(self):
+    def __invert__(self):
         """
         Return the inverse of ``self``.
 
@@ -1039,7 +1037,7 @@ def inverse(self):
             sage: S = SignedPermutations(4)
             sage: s1,s2,s3,s4 = S.gens()
             sage: x = s4*s1*s2*s3*s4
-            sage: ~x
+            sage: ~x   # indirect doctest
             [2, 3, -4, -1]
             sage: x * ~x == S.one()
             True
@@ -1049,8 +1047,6 @@ def inverse(self):
                               tuple(self._colors[i - 1] for i in ip),  # -1 for indexing
                               ip)
 
-    __invert__ = inverse
-
     def __iter__(self):
         """
         Iterate over ``self``.

src/sage/combinat/root_system/fundamental_group.py

@@ -249,15 +249,15 @@ def _repr_(self):
         """
         return self.parent()._prefix + "[" + repr(self.value()) + "]"
 
-    def inverse(self):
+    def __invert__(self):
         r"""
         Return the inverse element of ``self``.
 
         EXAMPLES::
 
             sage: from sage.combinat.root_system.fundamental_group import FundamentalGroupOfExtendedAffineWeylGroup
             sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['A',3,1])
-            sage: F(1).inverse()
+            sage: F(1).inverse()   # indirect doctest
             pi[3]
             sage: F = FundamentalGroupOfExtendedAffineWeylGroup(['E',6,1], prefix="f")
             sage: F(1).inverse()
@@ -266,8 +266,6 @@ def inverse(self):
         par = self.parent()
         return self.__class__(par, par.dual_node(self.value()))
 
-    __invert__ = inverse
-
     def _richcmp_(self, x, op):
         r"""
         Compare ``self`` with `x`.

src/sage/geometry/hyperbolic_space/hyperbolic_isometry.py

@@ -324,21 +324,19 @@ def matrix(self):
         """
         return self._matrix
 
-    def inverse(self):
+    def __invert__(self):
         r"""
         Return the inverse of the isometry ``self``.
 
         EXAMPLES::
 
             sage: UHP = HyperbolicPlane().UHP()
             sage: A = UHP.get_isometry(matrix(2,[4,1,3,2]))
-            sage: B = A.inverse()
+            sage: B = A.inverse()   # indirect doctest
             sage: A*B == UHP.get_isometry(identity_matrix(2))
             True
         """
-        return self.__class__(self.domain(), self.matrix().inverse())
-
-    __invert__ = inverse
+        return self.__class__(self.domain(), self.matrix().__invert__())
 
     def is_identity(self):
         """