Implement compositional_inverse for symbolic functions

Author: user202729

src/sage/modules/free_module_element.pyx

@@ -4271,6 +4271,45 @@ cdef class FreeModuleElement(Vector):   # abstract base class
             return vector(ring, coeffs)
         return vector(coeffs)
 
+    def compositional_inverse(self, allow_inverse_multivalued=True, **kwargs):
+        """
+        Find the compositional inverse of this symbolic function.
+
+        INPUT: see :meth:`sage.symbolic.expression.Expression.compositional_inverse`
+
+        .. SEEALSO::
+
+            :meth:`sage.symbolic.expression.Expression.compositional_inverse`
+
+        EXAMPLES::
+
+            sage: f(x, y, z) = (y, z, x)
+            sage: f.compositional_inverse()
+
+        TESTS::
+
+            sage: f.change_ring(SR)
+            sage: f.change_ring(SR).compositional_inverse()
+        """
+        from sage.rings.abc import CallableSymbolicExpressionRing
+        if not isinstance(self.base_ring(), CallableSymbolicExpressionRing):
+            raise ValueError("base ring must be a symbolic expression ring")
+        from sage.symbolic.ring import SR
+        tmp_vars = [SR.symbol() for _ in range(self.parent().dimension())]
+        input_vars = self.base_ring().args()
+        from sage.symbolic.relation import solve
+        l = solve([a == b for a, b in zip(self.change_ring(SR), tmp_vars)], input_vars, solution_dict=True, **kwargs)
+        if not l:
+            raise ValueError("cannot find an inverse")
+        if len(l) > 1 and not allow_inverse_multivalued:
+            raise ValueError("inverse is multivalued, pass allow_inverse_multivalued=True to bypass")
+        d = l[0]
+        subs_dict = dict(zip(tmp_vars, input_vars))
+        for x in input_vars:
+            if set(d[x].variables()) & set(input_vars):
+                raise ValueError("cannot find an inverse")
+        return self.parent()([d[x].subs(subs_dict) for x in input_vars])
+
 
 # ############################################
 # Generic dense element

src/sage/symbolic/expression.pyx

@@ -13512,6 +13512,59 @@ cdef class Expression(Expression_abc):
                         S = S.subs(di)
                 return S
 
+    def compositional_inverse(self, allow_inverse_multivalued=True, **kwargs):
+        """
+        Find the compositional inverse of this symbolic function.
+
+        INPUT:
+
+        - ``allow_inverse_multivalued`` -- (default: ``True``); see example below
+        - ``**kwargs`` -- additional keyword arguments passed to :func:`sage.symbolic.relation.solve`.
+
+        .. SEEALSO::
+
+            :meth:`sage.modules.free_module_element.FreeModuleElement.compositional_inverse`.
+
+        EXAMPLES::
+
+            sage: f(x) = x+1
+            sage: f.compositional_inverse()
+            sage: var("y")
+            sage: f(x) = x+y
+            sage: f.compositional_inverse()
+            sage: f(x) = x^2
+            sage: f.compositional_inverse()
+
+        When ``allow_inverse_multivalued=False``, there is some additional checking::
+
+            sage: f(x) = x^2
+            sage: f.compositional_inverse(allow_inverse_multivalued=False)
+
+        Nonetheless, the checking is not always foolproof (``x |--> log(x) + 2*pi*I`` is another possibility)::
+
+            sage: f(x) = exp(x)
+            sage: f.compositional_inverse(allow_inverse_multivalued=False)
+
+        Sometimes passing ``kwargs`` is useful, for example ``algorithm`` can be used
+        when the default solver fails::
+
+            sage: f(x) = (2/3)^x
+            sage: f.compositional_inverse()
+            sage: f.compositional_inverse(algorithm="giac")  # needs sage.libs.giac
+
+        TESTS::
+
+            sage: f(x) = x+exp(x)
+            sage: f.compositional_inverse()
+            sage: f(x) = 0
+            sage: f.compositional_inverse()
+            sage: f(x, y) = (x, x)
+            sage: f.compositional_inverse()
+            sage: (x+1).compositional_inverse()
+        """
+        from sage.modules.free_module_element import vector
+        return vector([self]).compositional_inverse(allow_inverse_multivalued=allow_inverse_multivalued, **kwargs)[0]
+
 
 cpdef _repr_Expression(x):
     r"""