small changes

Author: xcaruso

src/sage/rings/function_field/drinfeld_modules/drinfeld_module.py

@@ -47,15 +47,15 @@ class DrinfeldModule(Parent, UniqueRepresentation):
     polynomials with coefficients in `K`, whose multiplication is given
     by the rule `\tau \lambda = \lambda^q \tau` for any `\lambda \in K`.
 
-    A Drinfeld `\mathbb{F}_q[T]`-module over the `base
-    \mathbb{F}_q[T]`-field `K` is an `\mathbb{F}_q`-algebra morphism
+    A Drinfeld `\mathbb{F}_q[T]`-module over the base
+    `\mathbb{F}_q[T]`-field `K` is an `\mathbb{F}_q`-algebra morphism
     `\phi: \mathbb{F}_q[T] \to K\{\tau\}` such that `\Im(\phi) \not\subset K`
     and `\phi` agrees with `\gamma` on `\mathbb{F}_q`.
 
     For `a` in `\mathbb{F}_q[T]`, `\phi(a)` is denoted `\phi_a`.
 
     The Drinfeld `\mathbb{F}_q[T]`-module `\phi` is uniquely determined
-    by the image `\phi_T` of `T` — this serves as input of the class.
+    by the image `\phi_T` of `T`; this serves as input of the class.
 
     .. NOTE::
 
@@ -84,8 +84,8 @@ class DrinfeldModule(Parent, UniqueRepresentation):
 
         sage: Fq = GF(49)
         sage: A.<T> = Fq[]
-        sage: K.<z> = Frac(A)
-        sage: psi = DrinfeldModule(A, [z, T+1])
+        sage: K = Frac(A)
+        sage: psi = DrinfeldModule(A, [K(T), T+1])
         sage: psi
         Drinfeld module defined by T |--> (T + 1)*t + T
 
@@ -111,8 +111,10 @@ class DrinfeldModule(Parent, UniqueRepresentation):
 
     - ``function_ring`` -- a univariate polynomial ring whose base field
       is a finite field
+
     - ``gen`` -- the generator of the Drinfeld module; as a list of
       coefficients or an Ore polynomial
+
     - ``name`` (default: ``'t'``) -- the name of the Ore polynomial ring
       generator
 
@@ -131,7 +133,7 @@ class DrinfeldModule(Parent, UniqueRepresentation):
     .. NOTE::
 
         Note that the definition of the base field is implicit; it is
-        automatically defined as  the compositum of all the parents of
+        automatically defined as the compositum of all the parents of
         the coefficients.
 
     The above Drinfeld module is finite; it can also be infinite::
@@ -337,7 +339,7 @@ class DrinfeldModule(Parent, UniqueRepresentation):
         sage: identity_morphism.ore_polynomial()
         1
 
-    It is easy to check if a morphism is an isogeny, endomorphism or
+    One checks if a morphism is an isogeny, endomorphism or
     isomorphism::
 
         sage: frobenius_endomorphism.is_isogeny()
@@ -355,17 +357,17 @@ class DrinfeldModule(Parent, UniqueRepresentation):
 
     .. RUBRIC:: The Vélu formula
 
-    Let ``ore_pol`` be a nonzero Ore polynomial. We can decide if there
-    exists a Drinfeld module ``psi`` such that ``ore_pol`` is an isogeny
-    from ``self`` to ``psi``. If so, we find ``psi``::
+    Let ``P`` be a nonzero Ore polynomial. We can decide if ``P``
+    defines an isogeny with a given domain and, if it does, find
+    the codomain::
 
-        sage: ore_pol = (2*z^6 + z^3 + 2*z^2 + z + 2)*t + z^11 + 2*z^10 + 2*z^9 + 2*z^8 + z^7 + 2*z^6 + z^5 + z^3 + z^2 + z
-        sage: psi = phi.velu(ore_pol)
+        sage: P = (2*z^6 + z^3 + 2*z^2 + z + 2)*t + z^11 + 2*z^10 + 2*z^9 + 2*z^8 + z^7 + 2*z^6 + z^5 + z^3 + z^2 + z
+        sage: psi = phi.velu(P)
         sage: psi
         Drinfeld module defined by T |--> (2*z^11 + 2*z^9 + z^6 + 2*z^5 + 2*z^4 + 2*z^2 + 1)*t^2 + (2*z^11 + 2*z^10 + 2*z^9 + z^8 + 2*z^7 + 2*z^6 + z^5 + 2*z^4 + 2*z^2 + 2*z)*t + z
-        sage: ore_pol in Hom(phi, psi)
+        sage: P in Hom(phi, psi)
         True
-        sage: ore_pol * phi(T) == psi(T) * ore_pol
+        sage: P * phi(T) == psi(T) * P
         True
 
     If the input does not define an isogeny, an exception is raised:
@@ -519,14 +521,19 @@ def __classcall_private__(cls, function_ring, gen, name='t', latexname=None):
 
         - ``function_ring`` -- a univariate polynomial ring whose base
           is a finite field
+
         - ``gen`` -- the generator of the Drinfeld module; as a list of
           coefficients or an Ore polynomial
+
         - ``name`` (default: ``'t'``) -- the name of the Ore polynomial
           ring gen
+
         - ``latexname`` (default: ``None``) -- the LaTeX name of the Drinfeld
           module
 
-        OUTPUT: a DrinfeldModule or FiniteDrinfeldModule
+        OUTPUT:
+
+        A DrinfeldModule or FiniteDrinfeldModule.
 
         TESTS::
 
@@ -618,17 +625,20 @@ def __init__(self, gen, category, latexname=None):
         """
         Initialize ``self``.
 
-        Validity of the input is checked in ``__classcall_private__``.
-        The ``__init__`` just saves attributes.
+        Validity of the input is checked in meth:`__classcall_private__`.
+        The meth:`__init__` just saves attributes.
 
         INPUT:
 
         - ``function_ring`` -- a univariate polynomial ring whose base
           is a finite field
+
         - ``gen`` -- the generator of the Drinfeld module; as a list of
           coefficients or an Ore polynomial
+
         - ``name`` (default: ``'t'``) -- the name of the Ore polynomial
           ring gen
+
         - ``latexname`` (default: ``None``) -- the LaTeX name of the Drinfeld
           module
 
@@ -718,11 +728,10 @@ def _Hom_(self, other, category):
         INPUT:
 
         - ``other`` -- the codomain of the homset
+
         - ``category`` -- the category in which we consider the
           morphisms, usually ``self.category()``
 
-        OUTPUT: an homset
-
         EXAMPLES::
 
             sage: Fq = GF(25)
@@ -768,10 +777,8 @@ def _latex_(self):
         r"""
         Return a LaTeX representation of the Drinfeld module.
 
-        If a LaTeX name was given at init. using `latexname`, use the LaTeX
-        name. Otherwise, create a representation.
-
-        OUTPUT: a string
+        If a LaTeX name was given at initialization, we use it.
+        Otherwise, we create a representation.
 
         EXAMPLES::
 
@@ -807,9 +814,7 @@ def _latex_(self):
 
     def _repr_(self):
         r"""
-        Return a string representation of the Drinfeld module.
-
-        OUTPUT: a string
+        Return a string representation of this Drinfeld module.
 
         EXAMPLES::
 
@@ -844,7 +849,7 @@ def action(self):
             sage: action
             Action on Finite Field in z12 of size 5^12 over its base induced by Drinfeld module defined by T |--> z12^5*t^2 + z12^3*t + 2*z12^11 + 2*z12^10 + z12^9 + 3*z12^8 + z12^7 + 2*z12^5 + 2*z12^4 + 3*z12^3 + z12^2 + 2*z12
 
-    The action on elements is computed as follows::
+        The action on elements is computed as follows::
 
             sage: P = T^2 + T + 1
             sage: a = z12 + 1
@@ -905,8 +910,6 @@ def coefficients(self, sparse=True):
 
         - ``sparse`` -- a boolean
 
-        OUTPUT: a list of elements in the base codomain
-
         EXAMPLES::
 
             sage: Fq = GF(25)
@@ -939,8 +942,6 @@ def gen(self):
         r"""
         Return the generator of the Drinfeld module.
 
-        OUTPUT: an Ore polynomial
-
         EXAMPLES::
 
             sage: Fq = GF(25)
@@ -973,8 +974,6 @@ def height(self):
         A rank two Drinfeld module is supersingular if and only if its
         height equals its rank.
 
-        OUTPUT: an integer
-
         EXAMPLES::
 
             sage: Fq = GF(25)
@@ -1015,15 +1014,14 @@ def height(self):
                                  'function field characteristic')
             else:
                 p = self.characteristic()
-                return Integer((self(p).valuation()) // (p.degree()))
+                return Integer(self(p).valuation() // p.degree())
         except NotImplementedError:
             raise NotImplementedError('height not implemented in this case')
 
     def is_finite(self):
         r"""
-        Return ``True`` whether the Drinfeld module is finite.
-
-        OUTPUT: a boolean
+        Return ``True`` if this Drinfeld module is finite,
+        ``False`` otherwise.
 
         EXAMPLES::
 

src/sage/rings/function_field/drinfeld_modules/finite_drinfeld_module.py

@@ -91,7 +91,7 @@ class FiniteDrinfeldModule(DrinfeldModule):
         sage: chi(frob_pol, phi(T))
         0
 
-    This makes it possible to compute the Frobenius trace and norm::
+    as well as its trace and norm::
 
         sage: phi.frobenius_trace()
         6*T + 5*z3^2 + 5*z3 + 6
@@ -100,7 +100,7 @@ class FiniteDrinfeldModule(DrinfeldModule):
         sage: phi.frobenius_norm()
         2*T^2 + (z3^2 + z3 + 4)*T + 2*z3
 
-    And to decide if a Drinfeld module is ordinary or supersingular::
+    We can decide if a Drinfeld module is ordinary or supersingular::
 
         sage: phi.is_ordinary()
         True
@@ -129,10 +129,13 @@ def __init__(self, gen, category, latexname=None):
 
         - ``function_ring`` -- a univariate polynomial ring whose base
           is a finite field
+
         - ``gen`` -- the generator of the Drinfeld module as a list of
           coefficients or an Ore polynomial
+
         - ``name`` (default: `'t'`) -- the name of the Ore polynomial
           ring gen
+
         - ``latexname`` (default: ``None``) -- the LaTeX name of the Drinfeld
           module
 
@@ -148,11 +151,9 @@ def __init__(self, gen, category, latexname=None):
             sage: phi._gen == ore_polring(gen)
             True
         """
-
         # NOTE: There used to be no __init__ here (which was fine). I
         # added one to ensure that FiniteDrinfeldModule would always
         # have _frobenius_norm and _frobenius_trace attributes.
-
         super().__init__(gen, category, latexname)
         self._frobenius_norm = None
         self._frobenius_trace = None
@@ -166,8 +167,6 @@ def frobenius_endomorphism(self):
         *Frobenius endomorphism* is defined as the endomorphism whose
         defining Ore polynomial is `t^q`.
 
-        OUTPUT: a Drinfeld module morphism
-
         EXAMPLES::
 
             sage: Fq = GF(343)
@@ -179,6 +178,9 @@ def frobenius_endomorphism(self):
               From (gen): z6*t^2 + 1
               To (gen):   z6*t^2 + 1
               Defn:       t^2
+
+       TESTS::
+
             sage: from sage.rings.function_field.drinfeld_modules.morphism import DrinfeldModuleMorphism
             sage: isinstance(phi.frobenius_endomorphism(), DrinfeldModuleMorphism)
             True
@@ -214,10 +216,9 @@ def frobenius_charpoly(self, var='X'):
         Note that the *Frobenius trace* is defined as `A(T)` and the
         *Frobenius norm* is defined as `B(T)`.
 
-        INPUT: (default: ``'T'``) the name of the second variable
+        INPUT:
 
-        OUTPUT: an univariate polynomial with coefficients in the
-        function ring
+        - ``var`` (default: ``'X'``) -- the name of the second variable
 
         EXAMPLES::
 
@@ -283,8 +284,6 @@ def frobenius_norm(self):
         Let `n` be the degree of the base field over `\mathbb{F}_q` Then the
         Frobenius norm has degree `n`.
 
-        OUTPUT: an element in the function ring
-
         EXAMPLES::
 
             sage: Fq = GF(343)
@@ -331,26 +330,11 @@ def frobenius_trace(self):
 
         Let `\mathbb{F}_q[T]` be the function ring, write `\chi = T^2 -
         A(X)T + B(X) \in \mathbb{F}_q[T][X]` for the characteristic
-        polynomial of the Frobenius endomorphism. The *Frobenius norm*
-        is defined as the polynomial `B(T) \in \mathbb{F}_q[T]`.
+        polynomial of the Frobenius endomorphism. The *Frobenius trace*
+        is defined as the polynomial `A(T) \in \mathbb{F}_q[T]`.
 
         Let `n` be the degree over `\mathbb{F}_q` of the base codomain.
-        Then the Frobenius trace has degree `\leq \frac{n}{2}`.
-
-        OUTPUT: an element in the function ring
-
-        ALGORITHM:
-
-            Let `A(T)` denote the Frobenius trace and `B(T)` denote the
-            Frobenius norm. We begin by computing `B(T)`, see docstring
-            of method :meth:`frobenius_norm` for details. The
-            characteristic polynomial of the Frobenius yields `t^{2n} -
-            \phi_A t^n + \phi_B = 0`, where `t^n` is the Frobenius
-            endomorphism. As `\phi_B` is now known, we can compute
-            `\phi_A = (t^{2n} + \phi_B) / t^n`. We get `A(T)` by
-            inverting this quantity, using the method
-            :meth:`sage.rings.function_fields.drinfeld_module.drinfeld_module.DrinfeldModule.invert`,
-            see its docstring for details.
+        Then the Frobenius trace has degree at most `\frac{n}{2}`.
 
         EXAMPLES::
 
@@ -372,6 +356,19 @@ def frobenius_trace(self):
 
             sage: A == -phi.frobenius_charpoly()[1]
             True
+
+        ALGORITHM:
+
+            Let `A(T)` denote the Frobenius trace and `B(T)` denote the
+            Frobenius norm. We begin by computing `B(T)`, see docstring
+            of method :meth:`frobenius_norm` for details. The
+            characteristic polynomial of the Frobenius yields `t^{2n} -
+            \phi_A t^n + \phi_B = 0`, where `t^n` is the Frobenius
+            endomorphism. As `\phi_B` is now known, we can compute
+            `\phi_A = (t^{2n} + \phi_B) / t^n`. We get `A(T)` by
+            inverting this quantity, using the method
+            :meth:`sage.rings.function_fields.drinfeld_module.drinfeld_module.DrinfeldModule.invert`,
+            see its docstring for details.
         """
         self._check_rank_two()
         # Notations from Schost-Musleh:
@@ -392,8 +389,6 @@ def invert(self, ore_pol):
         - ``ore_pol`` -- the Ore polynomial whose preimage we want to
           compute
 
-        OUTPUT: a function ring element
-
         EXAMPLES::
 
             sage: Fq = GF(25)
@@ -417,6 +412,7 @@ def invert(self, ore_pol):
             Traceback (most recent call last):
             ...
             ValueError: input must be in the image of the Drinfeld module
+
             sage: phi.invert(t^3 + t^2 + 1)
             Traceback (most recent call last):
             ...
@@ -494,8 +490,6 @@ def is_ordinary(self):
         A rank two Drinfeld module is *ordinary* if and only if it is
         not supersingular; see :meth:`is_supersingular`.
 
-        OUTPUT: a boolean
-
         EXAMPLES::
 
             sage: Fq = GF(343)
@@ -530,8 +524,6 @@ def is_supersingular(self):
         trace. An *ordinary* rank two finite Drinfeld module is a
         Drinfeld module that is not supersingular.
 
-        OUTPUT: a boolean
-
         EXAMPLES::
 
             sage: Fq = GF(343)