Create draft for finite Drinfeld module doctest

src/sage/modules/finite_drinfeld_module.py

@@ -1,16 +1,26 @@
 r"""
-<Short one-line summary that ends with no period>
+This module provides classes for finite Drinfeld modules
+(`FiniteDrinfeldModule`) and their module action on the algebraic
+closure of `\Fq` (`FiniteDrinfeldModuleAction`).
 
-<Paragraph description>
-
-EXAMPLES::
+AUTHORS:
 
-<Lots and lots of examples>
+- Antoine Leudière (2022-04): initial version
 
-AUTHORS:
+Let `\tau` be the `\Fq`-linear Frobenius endomorphism of `\Fqbar`
+defined by `x \mapsto x^q`. Let `L\{\tau\}` be the ring of Ore
+polynomials in `\tau` with coefficients in L. Fix an element `\omega` in
+`L` (global parameter). A finite Drinfeld module is an `\Fq`-algebra
+morphism `\phi: \Fq[X] \to L\{\tau\]` such that:
+    - the constant coefficient of `\phi(X)` is `\omega`,
+    - there exists at least one `a \in \Fq[X]` such that `\phi(a)` has a
+      non zero `\tau`-degree.
 
-- Antoine Leudière (2022-04-26): initial version
+As an `\Fq[X]`-algebra morphism, a finite Drinfeld module is only
+determined by the image of `X`.
 
+Crucially, the Drinfeld module `\phi` gives rise to the `\Fq[X]`-module
+law on `\Fqbar` defined by `(a, x) = \phi(a)(x)`.
 """
 
 #*****************************************************************************
@@ -25,14 +35,106 @@
 
 from sage.categories.action import Action
 from sage.categories.homset import Hom
+from sage.misc.latex import latex
 from sage.rings.morphism import RingHomomorphism_im_gens
 from sage.rings.polynomial.ore_polynomial_element import OrePolynomial
 from sage.rings.polynomial.ore_polynomial_ring import OrePolynomialRing
 from sage.rings.polynomial.polynomial_ring import PolynomialRing_dense_finite_field
-from sage.misc.latex import latex
 
 
 class FiniteDrinfeldModule(RingHomomorphism_im_gens):
+    r"""
+    Class for finite Drinfeld modules.
+
+    INPUT:
+
+    - ``polring`` -- the base polynomial ring
+    - ``gen`` -- the image of `X`
+
+    EXAMPLES:
+        
+    .. RUBRIC:: Basics
+
+    First, create base objects::
+
+        sage: Fq = GF(7^2)
+        sage: FqX.<X> = Fq[]
+        sage: L = Fq.extension(3)
+        sage: frobenius = L.frobenius_endomorphism(2)
+        sage: Ltau.<t> = OrePolynomialRing(L, frobenius)
+
+    Then we instanciate the Drinfeld module::
+
+        sage: phi_X = 1 + t^2
+        sage: phi = FiniteDrinfeldModule(FqX, phi_X)
+        sage: phi
+        Finite Drinfeld module from Univariate Polynomial Ring in X over Finite Field in z2 of size 7^2 over Finite Field in z6 of size 7^6 generated by t^2 + 1.
+
+    There are getters for the base objects::
+
+        sage: phi.polring()
+        Univariate Polynomial Ring in X over Finite Field in z2 of size 7^2
+        sage: phi.ore_polring()
+        Ore Polynomial Ring in t over Finite Field in z6 of size 7^6 twisted by z6 |--> z6^(7^2)
+        sage: phi.gen()
+        t^2 + 1
+
+    And the class inherits `RingHomomorphism_im_gens`, so that one can
+    use::
+
+        sage: phi.domain()
+        Univariate Polynomial Ring in X over Finite Field in z2 of size 7^2
+        sage: phi.codomain()
+        Ore Polynomial Ring in t over Finite Field in z6 of size 7^6 twisted by z6 |--> z6^(7^2)
+        sage: phi.im_gens()
+        [t^2 + 1]
+
+    The rank of the Drinfeld module is retrieved with::
+
+        sage: phi.rank()
+        2
+
+    .. RUBRIC:: The module law induced by a Drinfeld module
+
+    The most important feature of Drinfeld modules is that they induce
+    an `\Fq[X]`-module law on the algebraic closure `\Fqbar` of `\Fq`.
+    We implement this action for any finite field extension `M` of `L`.
+    The `_get_action_` method returns an `Action` object::
+
+        sage: M = L.extension(2)
+        sage: action = phi._get_action_(M)
+        sage: action
+        Action on Finite Field in z12 of size 7^12 induced by the Finite Drinfeld module from Univariate Polynomial Ring in X over Finite Field in z2 of size 7^2 over Finite Field in z6 of size 7^6
+        generated by t^2 + 1.
+        sage: x = M.gen()
+        sage: g = X^3 + X + 5
+        sage: action(g, x)
+        ...
+        6*z12^11 + 5*z12^9 + 5*z12^8 + 2*z12^7 + 6*z12^6 + z12^5 + 6*z12^4 + 2*z12^3 + 3*z12^2 + 5*z12 + 4
+
+    Furthermore, it can be useful to embed a Drinfeld module into a
+    larger Ore polynomial ring::
+
+        sage: M = L.extension(2)
+        sage: psi = phi.change_ring(M); psi
+        Finite Drinfeld module from Univariate Polynomial Ring in X over Finite Field in z2 of size 7^2 over Finite Field in z12 of size 7^12 generated by t^2 + 1.
+
+        .. NOTE::
+
+        The general definition of a Drinfeld module is out of the scope
+        of this implementation.
+
+    ::
+
+        You can see all available methods of `RingHomomorphism_im_gens`
+        with `dir(sage.rings.morphism.RingHomomorphism_im_gens)`. Same
+        for `Action`.
+
+    .. SEEALSO::
+        :mod:`sage.categories.action.Action`
+        :mod:`sage.rings.polynomial.ore_polynomial_element`
+        :mod:`sage.rings.polynomial.ore_polynomial_ring`
+    """
 
     def __init__(self, polring, gen):
         # VERIFICATIONS
@@ -107,7 +209,7 @@ def _latex_(self):
 
     def _repr_(self):
         return f'Finite Drinfeld module from {self.polring()} over ' \
-                f'{self.ore_polring().base_ring()} defined by {self.gen()}.'
+                f'{self.ore_polring().base_ring()} generated by {self.gen()}.'
 
     ###########
     # Getters #