gh-37512: FiniteRankFreeModule.isomorphism_with_fixed_basis: Make it an actual isomorphism
    
<!-- ^ Please provide a concise and informative title. -->
<!-- ^ Don't put issue numbers in the title, do this in the PR
description below. -->
<!-- ^ For example, instead of "Fixes #12345" use "Introduce new method
to calculate 1 + 2". -->
<!-- v Describe your changes below in detail. -->
<!-- v Why is this change required? What problem does it solve? -->
<!-- v If this PR resolves an open issue, please link to it here. For
example, "Fixes #12345". -->

For this we define a new class `SetIsomorphism`, which knows its
inverse.

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->

- [x] The title is concise and informative.
- [x] The description explains in detail what this PR is about.
- [ ] I have linked a relevant issue or discussion.
- [ ] I have created tests covering the changes.
- [ ] I have updated the documentation accordingly.

### ⌛ Dependencies

<!-- List all open PRs that this PR logically depends on. For example,
-->
<!-- - #12345: short description why this is a dependency -->
<!-- - #34567: ... -->
    
URL: #37512
Reported by: Matthias Köppe
Reviewer(s): Eric Gourgoulhon, Travis Scrimshaw

Author: Release Manager

src/sage/categories/map.pyx

@@ -1272,7 +1272,7 @@ cdef class Map(Element):
 
     def section(self):
         """
-        Return a section of self.
+        Return a section of ``self``.
 
         .. NOTE::
 
@@ -1439,6 +1439,7 @@ cdef class Section(Map):
         """
         return self._inverse
 
+
 cdef class FormalCompositeMap(Map):
     """
     Formal composite maps.

src/sage/categories/morphism.pxd

@@ -8,3 +8,6 @@ cdef class Morphism(Map):
 cdef class SetMorphism(Morphism):
     cdef object _function
     cpdef bint _eq_c_impl(left, Element right) noexcept
+
+cdef class SetIsomorphism(SetMorphism):
+    cdef object _inverse

src/sage/categories/morphism.pyx

@@ -570,7 +570,7 @@ cdef class SetMorphism(Morphism):
 
         - ``parent`` -- a Homset
         - ``function`` -- a Python function that takes elements
-          of the domain as input and returns elements of the domain.
+          of the domain as input and returns elements of the codomain.
 
         EXAMPLES::
 
@@ -736,3 +736,159 @@ cdef class SetMorphism(Morphism):
             return not (isinstance(right, Element) and self._eq_c_impl(right))
         else:
             return False
+
+
+cdef class SetIsomorphism(SetMorphism):
+    r"""
+    An isomorphism of sets.
+
+    INPUT:
+
+    - ``parent`` -- a Homset
+    - ``function`` -- a Python function that takes elements
+      of the domain as input and returns elements of the codomain.
+
+    EXAMPLES::
+
+        sage: f = sage.categories.morphism.SetIsomorphism(Hom(ZZ, ZZ, Sets()),
+        ....:                                             operator.__neg__); f
+        Generic endomorphism of Integer Ring
+        sage: f._set_inverse(f)
+        sage: ~f is f
+        True
+    """
+    def _set_inverse(self, inverse):
+        r"""
+        Set the inverse morphism of ``self`` to be ``inverse``.
+
+        INPUT:
+
+        - ``inverse`` -- a :class:`SetIsomorphism`
+
+        EXAMPLES::
+
+            sage: f = sage.categories.morphism.SetIsomorphism(Hom(ZZ, ZZ, Sets()),
+            ....:                                             operator.__neg__)
+            sage: f._set_inverse(f)
+            sage: ~f is f
+            True
+        """
+        self._inverse = inverse
+
+    def __invert__(self):
+        r"""
+        Return the inverse morphism of ``self``.
+
+        If :meth:`_set_inverse` has not been called yet, an error is raised.
+
+        EXAMPLES::
+
+            sage: f = sage.categories.morphism.SetIsomorphism(Hom(ZZ, ZZ, Sets()),
+            ....:                                             operator.__neg__)
+            sage: ~f
+            Traceback (most recent call last):
+            ...
+            RuntimeError: inverse morphism has not been set
+            sage: f._set_inverse(f)
+            sage: ~f
+            Generic endomorphism of Integer Ring
+        """
+        if not self._inverse:
+            raise RuntimeError('inverse morphism has not been set')
+        return self._inverse
+
+    cdef dict _extra_slots(self) noexcept:
+        """
+        Extend the dictionary with extra slots for this class.
+
+        INPUT:
+
+        - ``_slots`` -- a dictionary
+
+        EXAMPLES::
+
+            sage: f = sage.categories.morphism.SetIsomorphism(Hom(ZZ, ZZ, Sets()),
+            ....:                                             operator.__neg__)
+            sage: f._set_inverse(f)
+            sage: f._extra_slots_test()
+            {'_codomain': Integer Ring,
+             '_domain': Integer Ring,
+             '_function': <built-in function neg>,
+             '_inverse': Generic endomorphism of Integer Ring,
+             '_is_coercion': False,
+             '_repr_type_str': None}
+        """
+        slots = SetMorphism._extra_slots(self)
+        slots['_inverse'] = self._inverse
+        return slots
+
+    cdef _update_slots(self, dict _slots) noexcept:
+        """
+        Update the slots of ``self`` from the data in the dictionary.
+
+        INPUT:
+
+        - ``_slots`` -- a dictionary
+
+        EXAMPLES::
+
+            sage: f = sage.categories.morphism.SetIsomorphism(Hom(ZZ, ZZ, Sets()),
+            ....:                                             operator.__neg__)
+            sage: f._update_slots_test({'_function': operator.__neg__,
+            ....:                       '_inverse': f,
+            ....:                       '_domain': QQ,
+            ....:                       '_codomain': QQ,
+            ....:                       '_repr_type_str': 'bla'})
+            sage: f(3)
+            -3
+            sage: f._repr_type()
+            'bla'
+            sage: f.domain()
+            Rational Field
+            sage: f.codomain()
+            Rational Field
+            sage: f.inverse() == f
+            True
+        """
+        self._inverse = _slots['_inverse']
+        SetMorphism._update_slots(self, _slots)
+
+    def section(self):
+        """
+        Return a section of this morphism.
+
+        EXAMPLES::
+
+            sage: f = sage.categories.morphism.SetIsomorphism(Hom(ZZ, ZZ, Sets()),
+            ....:                                             operator.__neg__)
+            sage: f._set_inverse(f)
+            sage: f.section() is f
+            True
+        """
+        return self.__invert__()
+
+    def is_surjective(self):
+        r"""
+        Return whether this morphism is surjective.
+
+        EXAMPLES::
+
+            sage: f = sage.categories.morphism.SetIsomorphism(Hom(ZZ, ZZ, Sets()),
+            ....:                                             operator.__neg__)
+            sage: f.is_surjective()
+            True
+        """
+        return True
+
+    def is_injective(self):
+        r"""
+        Return whether this morphism is injective.
+
+        EXAMPLES::
+
+            sage: f = sage.categories.morphism.SetIsomorphism(Hom(ZZ, ZZ, Sets()),
+            ....:                                             operator.__neg__)
+            sage: f.is_injective()
+            True
+        """
+        return True