sagemathgh-38703: Implementation of Ore modules
    
This PR implements modules over Ore polynomial rings.

More precisely, if $A[X;\theta,\partial]$ is a Ore polynomial ring, we
propose an implementation of finite free modules $M$ over $A$ equipped
with a map $f : M \to M$ such that $f(ax) = \theta(a) f(x) + \partial(a)
x$ for all $a \in R$ and $x \in M$.
Such a map is called *pseudolinear* and it endows `M` with a structure
of module over $A[X;\theta,\partial]$ (the map $f$ corresponding to the
multiplication by $X$).

This PR includes:
- an implementation of the category of Ore modules
- an implementation of Ore modules, their submodules and their quotients
(with an option to give chosen names to elements in a distinguished
basis)
- a constructor to create quotients of the form $A[X;\theta,\partial] /
A[X;\theta,\partial]P$
- an implementation of morphisms between Ore modules, including methods
for computing kernels, cokernels, images and coimages

This is the second step (after PR sagemath#38650) towards the implemetation of
Anderson motives.

### 📝 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 and checked the documentation
preview.

### ⌛ Dependencies

sagemath#38650: pseudomorphisms
    
URL: sagemath#38703
Reported by: Xavier Caruso
Reviewer(s): Rubén Muñoz--Bertrand

Author: Release Manager

src/doc/en/reference/categories/index.rst

@@ -162,6 +162,7 @@ Individual Categories
    sage/categories/monoids
    sage/categories/number_fields
    sage/categories/objects
+   sage/categories/ore_modules
    sage/categories/partially_ordered_monoids
    sage/categories/permutation_groups
    sage/categories/pointed_sets

src/doc/en/reference/index.rst

@@ -51,6 +51,7 @@ Linear Algebra
 * :doc:`Matrices and Spaces of Matrices <matrices/index>`
 * :doc:`Vectors and Modules <modules/index>`
 * :doc:`Tensors on Free Modules of Finite Rank <tensor_free_modules/index>`
+* :doc:`Modules over Ore rings <oremodules/index>`
 
 Calculus and Analysis
 ---------------------

src/doc/en/reference/oremodules/conf.py

@@ -0,0 +1 @@
+../conf_sub.py

src/doc/en/reference/oremodules/index.rst

@@ -0,0 +1,56 @@
+Modules over Ore rings
+======================
+
+Let `R` be a commutative ring, `\theta : K \to K` by a ring
+endomorphism and `\partial : K \to K` be a `\theta`-derivation,
+that is an additive map satisfying the following axiom
+
+.. MATH::
+
+    \partial(x y) = \theta(x) \partial(y) + \partial(x) y
+
+The Ore polynomial ring associated to these data is 
+`\mathcal S = R[X; \theta, \partial]`; its elements are the
+usual polynomials over `R` but the multiplication is twisted
+according to the rule
+
+.. MATH::
+
+    \partial(x y) = \theta(x) \partial(y) + \partial(x) y
+
+We refer to :mod:`sage.rings.polynomial.ore_polynomial_ring.OrePolynomial`
+for more details.
+
+A Ore module over `(R, \theta, \partial)` is by definition a
+module over `\mathcal S`; it is the same than a `R`-module `M`
+equipped with an additive `f : M \to M` such that
+
+.. MATH::
+
+    f(a x) = \theta(a) f(x) + \partial(a) x
+
+Such a map `f` is called a pseudomorphism
+(see also :meth:`sage.modules.free_module.FreeModule_generic.pseudohom`).
+
+SageMath provides support for creating and manipulating Ore
+modules that are finite free over the base ring `R`.
+This includes, in particular, Frobenius modules and modules
+with connexions.
+
+Modules, submodules and quotients
+---------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/modules/ore_module
+   sage/modules/ore_module_element
+
+Morphisms
+---------
+
+.. toctree::
+   :maxdepth: 1
+
+   sage/modules/ore_module_homspace
+   sage/modules/ore_module_morphism

src/sage/categories/meson.build

@@ -148,6 +148,7 @@ py.install_sources(
   'noetherian_rings.py',
   'number_fields.py',
   'objects.py',
+  'ore_modules.py',
   'partially_ordered_monoids.py',
   'permutation_groups.py',
   'pointed_sets.py',

src/sage/categories/ore_modules.py

@@ -0,0 +1,177 @@
+from sage.misc.lazy_attribute import lazy_attribute
+
+from sage.categories.modules import Modules
+from sage.categories.category_types import Category_over_base_ring
+from sage.categories.homsets import Homsets
+from sage.rings.polynomial.ore_polynomial_ring import OrePolynomialRing
+
+
+class OreModules(Category_over_base_ring):
+    r"""
+    Category of Ore modules.
+    """
+    @staticmethod
+    def __classcall_private__(cls, ring, twist):
+        r"""
+        Normalize the input and call the init function.
+
+        INPUT:
+
+        - ``ring`` -- a commutative ring, the base ring of
+          the Ore modules
+
+        - ``twist`` -- a twisting morphism/derivation or a
+          Ore polynomial ring
+
+        TESTS::
+
+            sage: from sage.categories.ore_modules import OreModules
+            sage: K.<a> = GF(5^3)
+            sage: Frob = K.frobenius_endomorphism()
+            sage: cat = OreModules(K, Frob)
+            sage: cat
+            Category of Ore modules over Finite Field in a of size 5^3 twisted by a |--> a^5
+
+            sage: S = cat.ore_ring('y')
+            sage: cat is OreModules(K, S)
+            True
+        """
+        if isinstance(twist, OrePolynomialRing):
+            ore = twist.change_var('x')
+            if ore.base_ring() is not ring:
+                raise ValueError("base rings do not match")
+        else:
+            ore = OrePolynomialRing(ring, twist, names='x', polcast=False)
+        return cls.__classcall__(cls, ore)
+
+    def __init__(self, ore):
+        r"""
+        Initialize this category.
+
+        TESTS::
+
+            sage: from sage.categories.ore_modules import OreModules
+            sage: K.<a> = GF(5^3)
+            sage: Frob = K.frobenius_endomorphism()
+            sage: cat = OreModules(K, Frob)
+
+            sage: TestSuite(cat).run()
+        """
+        base = ore.base_ring()
+        Category_over_base_ring.__init__(self, base)
+        self._ore = ore
+
+    def __reduce__(self):
+        r"""
+        Return the arguments which were used to create this instance.
+
+        This method is needed for pickling.
+
+        TESTS::
+
+            sage: from sage.categories.ore_modules import OreModules
+            sage: K.<a> = GF(5^3)
+            sage: Frob = K.frobenius_endomorphism()
+            sage: cat = OreModules(K, Frob)
+            sage: cat2 = loads(dumps(cat))  # indirect doctest
+            sage: cat is cat2
+            True
+        """
+        return OreModules, (self.base_ring(), self._ore)
+
+    def super_categories(self):
+        r"""
+        Return the immediate super categories of this category.
+
+        EXAMPLES::
+
+            sage: from sage.categories.ore_modules import OreModules
+            sage: K.<a> = GF(5^3)
+            sage: Frob = K.frobenius_endomorphism()
+            sage: cat = OreModules(K, Frob)
+            sage: cat.super_categories()
+            [Category of vector spaces over Finite Field in a of size 5^3]
+        """
+        return [Modules(self.base())]
+
+    def _repr_object_names(self):
+        r"""
+        Return a string representation naming the objects
+        in this category.
+
+        EXAMPLES::
+
+            sage: from sage.categories.ore_modules import OreModules
+            sage: K.<a> = GF(5^3)
+            sage: Frob = K.frobenius_endomorphism()
+            sage: cat = OreModules(K, Frob)
+            sage: cat._repr_object_names()
+            'Ore modules over Finite Field in a of size 5^3 twisted by a |--> a^5'
+        """
+        return "Ore modules over %s %s" % (self.base_ring(), self._ore._repr_twist())
+
+    def ore_ring(self, var='x'):
+        r"""
+        Return the underlying Ore polynomial ring.
+
+        INPUT:
+
+        - ``var`` (default; ``x``) -- the variable name
+
+        EXAMPLES::
+
+            sage: from sage.categories.ore_modules import OreModules
+            sage: K.<a> = GF(5^3)
+            sage: Frob = K.frobenius_endomorphism()
+            sage: cat = OreModules(K, Frob)
+            sage: cat.ore_ring()
+            Ore Polynomial Ring in x over Finite Field in a of size 5^3 twisted by a |--> a^5
+
+            sage: cat.ore_ring('y')
+            Ore Polynomial Ring in y over Finite Field in a of size 5^3 twisted by a |--> a^5
+        """
+        return self._ore.change_var(var)
+
+    def twisting_morphism(self):
+        r"""
+        Return the underlying twisting morphism.
+
+        EXAMPLES::
+
+            sage: from sage.categories.ore_modules import OreModules
+            sage: K.<a> = GF(5^3)
+            sage: Frob = K.frobenius_endomorphism()
+            sage: cat = OreModules(K, Frob)
+            sage: cat.twisting_morphism()
+            Frobenius endomorphism a |--> a^5 on Finite Field in a of size 5^3
+
+        If the twising morphism is the identity, nothing is returned::
+
+            sage: R.<t> = QQ[]
+            sage: d = R.derivation()
+            sage: cat = OreModules(R, d)
+            sage: cat.twisting_morphism()
+        """
+        return self._ore.twisting_morphism()
+
+    def twisting_derivation(self):
+        r"""
+        Return the underlying twisting derivation.
+
+        EXAMPLES::
+
+            sage: from sage.categories.ore_modules import OreModules
+            sage: R.<t> = QQ[]
+            sage: d = R.derivation()
+            sage: cat = OreModules(R, d)
+            sage: cat.twisting_derivation()
+            d/dt
+
+        If the twising derivation is zero, nothing is returned::
+
+            sage: K.<a> = GF(5^3)
+            sage: Frob = K.frobenius_endomorphism()
+            sage: cat = OreModules(K, Frob)
+            sage: cat.twisting_derivation()
+        """
+        return self._ore.twisting_derivation()

src/sage/modules/free_module_pseudomorphism.py

@@ -500,5 +500,70 @@ def __eq__(self, other):
         if isinstance(other, FreeModulePseudoMorphism):
             return self.parent() is other.parent() and self._matrix == other._matrix
 
+    def ore_module(self, names=None):
+        r"""
+        Return the Ore module over which the Ore variable acts
+        through this pseudomorphism.
+
+        INPUT:
+
+        - ``names`` -- a string, a list of strings or ``None``,
+          the names of the vector of the canonical basis of the
+          Ore module; if ``None``, elements are represented as
+          vectors in `K^d` (where `K` is the base ring)
+
+        EXAMPLES::
+
+            sage: Fq.<z> = GF(7^3)
+            sage: Frob = Fq.frobenius_endomorphism()
+            sage: V = Fq^2
+            sage: mat = matrix(2, [1, z, z^2, z^3])
+            sage: f = V.pseudohom(mat, Frob)
+
+            sage: M = f.ore_module()
+            sage: M
+            Ore module of rank 2 over Finite Field in z of size 7^3 twisted by z |--> z^7
+
+        Here `M` is a module over the Ore ring `\mathbb F_q[X; \text{Frob}]`
+        and the variable `X` acts on `M` through `f`::
+
+            sage: S.<X> = M.ore_ring()
+            sage: S
+            Ore Polynomial Ring in X over Finite Field in z of size 7^3 twisted by z |--> z^7
+            sage: v = M((1,0))
+            sage: X*v
+            (1, z)
+
+        The argument ``names`` can be used to give chosen names
+        to the vectors in the canonical basis::
+
+            sage: M = f.ore_module(names=('v', 'w'))
+            sage: M.basis()
+            [v, w]
+
+        or even::
+
+            sage: M = f.ore_module(names='e')
+            sage: M.basis()
+            [e0, e1]
+
+        Note that the bracket construction also works::
+
+            sage: M.<v,w> = f.ore_module()
+            sage: M.basis()
+            [v, w]
+            sage: v + w
+            v + w
+
+        We refer to :mod:`sage.modules.ore_module` for a
+        tutorial on Ore modules in SageMath.
+
+        .. SEEALSO::
+
+            :mod:`sage.modules.ore_module`
+        """
+        from sage.modules.ore_module import OreModule
+        return OreModule(self._matrix, self.parent()._ore, names)
+
     def _test_nonzero_equal(self, tester):
         pass

src/sage/modules/meson.build

@@ -20,6 +20,10 @@ py.install_sources(
   'module_functors.py',
   'multi_filtered_vector_space.py',
   'numpy_util.pxd',
+  'ore_module.py',
+  'ore_module_element.py',
+  'ore_module_homspace.py',
+  'ore_module_morphism.py',
   'quotient_module.py',
   'real_double_vector.py',
   'submodule.py',