trac_6188_review.patch on Ticket #6188 – Attachment – Sage

sage/rings/number_field/number_field.py

# HG changeset patch
# User John Cremona <john.cremona@gmail.com>
# Date 1244151511 -3600
# Node ID e9c8a156d9d3c9c316186deed452cd80b18ccbf7
# Parent  0b6b4751a6eafc40481b322ad6110092b79d56e5
[mq]: docrev

diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/number_field.py

-                      a
     def specified_complex_embedding(self):
         r"""
         Returns the embedding of this field into the complex numbers has
+        Returns the embedding of this field into the complex numbers which has
         been specified.
         Fields created with the ``QuadraticField`` or
 …
         """
         Return generators for the unit group modulo torsion.
+        INPUT:
+        - ``proof`` (bool, default True) flag passed to ``pari``.
+        .. note::
+            For more functionality see the unit_group() function.
         ALGORITHM: Uses PARI's bnfunit command.
-        INPUTS: proof - default: True
-        NOTE: For more functionality see the unit_group() function.
         EXAMPLES::
             sage: x = QQ['x'].0
 …
         ALGORITHM: Uses PARI's bnfunit command.
+        INPUTS: proof -- default: True
+        NOTE: the group is cached.
+        INPUT:
+        - ``proof`` (bool, default True) flag passed to ``pari``.
+        .. note::
+           The group is cached.
         EXAMPLES::
 …
         If prec is 53 (the default), then the complex double field is used;
         otherwise the arbitrary precision (but slow) complex field is used.
         EXAMPLES::
             sage: C = CyclotomicField(4)
 …
         return self.gen()
 class NumberField_quadratic(NumberField_absolute):
     """
+    r"""
     Create a quadratic extension of the rational field.
     The command QuadraticField(a) creates the field Q(sqrt(a)).
+    The command ``QuadraticField(a)`` creates the field `\QQ(\sqrt{a})`.
     EXAMPLES::
 …
         field is negative, then the following warning from the PARI manual
         applies:
+            IMPORTANT WARNING: For `D<0`, this function may give
+            incorrect results when the class group has a low exponent
+            (has many cyclic factors), because implementing Shank's
+            method in full generality slows it down immensely.
+        .. warning::
+            For `D<0`, this function may give incorrect results when
+            the class group has a low exponent (has many cyclic
+            factors), because implementing Shank's method in full
+            generality slows it down immensely.
         EXAMPLES::
 …
         It is an open problem to *prove* that there are infinity many
         positive square-free `d` such that
         `\QQ(\sqrt{d})` has class number `1`:n
+        `\QQ(\sqrt{d})` has class number `1`:
         ::
 …
 def refine_embedding(e, prec=None):
     """
     Given an embedding e: K->RR or CC, returns an equivalent embedding
     with higher precision.
+    r"""
+    Given an embedding from a number field to either `\RR` or
+    `\CC`, returns an equivalent embedding with higher precision.
     INPUT:
     -  ``e`` - an embedding of a number field into either
        RR or CC (with some precision)

sage/rings/number_field/number_field_ideal.py

diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/number_field_ideal.py

-                      a
             is in the ideal.
         AUTHOR: John Cremona  2008-10-31
+            Uses linear algebra.  The change-of-basis matrix is
+            cached.  Provides simpler implementations for
+            _contains_(), is_integral() and smallest_integer().
+        ALGORITHM:
+        Uses linear algebra.  The change-of-basis matrix is cached.
+        Provides simpler implementations for ``_contains_()``,
+        ``is_integral()`` and ``smallest_integer()``.
         EXAMPLES::
 …
             return self.__pari_hnf
     def basis(self):
         """
+        r"""
         Return an immutable sequence of elements of this ideal (note:
         their parent is the number field) that form a basis for this
         ideal viewed as a ZZ-module.
+        ideal viewed as a `\ZZ` -module.
         OUTPUT:
             basis -- an immutable sequence.
 …
         return self.__basis
     def free_module(self):
         """
         Return the free ZZ-module contained in the vector space
+        r"""
+        Return the free `\ZZ`-module contained in the vector space
         associated to the ambient number field, that corresponds
         to this ideal.
 …
             [ 5  1  1  0  1  0]
             [ 5  6  2  1  1  1]
         However, the actual ZZ-module is not at all random::
+        However, the actual `\ZZ`-module is not at all random::
             sage: A.basis_matrix().change_ring(ZZ).echelon_form()
             [ 1  0  0  5  1  1]
 …
         return self.__elements_from_hnf(hnf)
     def integral_split(self):
         """
         Return a tuple (I, d), where I is an integral ideal, and d is the
         smallest positive integer such that this ideal is equal to I/d.
+        r"""
+        Return a tuple `(I, d)`, where `I` is an integral ideal, and `d` is the
+        smallest positive integer such that this ideal is equal to `I/d`.
         EXAMPLES::
 …
     def valuation(self, p):
         r"""
+        Return the valuation of this fractional ideal at the prime
+        Return the valuation of self at ``p``.
+        INPUT:
+        - ``p`` -- a prime ideal `\mathfrak{p}` of this number field.
+        OUTPUT:
+        (integer) The valuation of this fractional ideal at the prime
         `\mathfrak{p}`.  If `\mathfrak{p}` is not prime, raise a
         ValueError.
-        INPUT:
-            p -- a prime ideal of this number field.
-        OUTPUT:
-            integer
         EXAMPLES::
             sage: K.<a> = NumberField(x^5 + 2); K
 …
         return ZZ(nf.idealval(self.pari_hnf(), p._pari_prime))
     def decomposition_group(self):
+        """
+        Return the decomposition group of self, as a subset of the automorphism
+        group of the number field of self. Raises an error if the field isn't
+        Galois. See the decomposition_group method of the GaloisGroup_v2 class
+        for further examples and doctests.
+        r"""
+        Return the decomposition group of self, as a subset of the
+        automorphism group of the number field of self. Raises an
+        error if the field isn't Galois. See the decomposition_group
+        method of the ``GaloisGroup_v2`` class for further examples
+        and doctests.
         EXAMPLE::
 …
         return self.number_field().galois_group().decomposition_group(self)
     def ramification_group(self, v):
+        """
+        Return the vth ramification group of self, i.e. the set of elements s
+        of the Galois group of the number field of self (which we assume is Galois)
+        such that s acts trivially modulo self^(v+1). See the
+        ramification_group method of the GaloisGroup class for further examples
+        and doctests.
+        r"""
+        Return the `v`'th ramification group of self, i.e. the set of
+        elements `s` of the Galois group of the number field of self
+        (which we assume is Galois) such that `s` acts trivially
+        modulo the `(v+1)`'st power of self. See the
+        ramification_group method of the ``GaloisGroup`` class for
+        further examples and doctests.
         EXAMPLE::
 …
         return self.number_field().galois_group().ramification_group(self, v)
     def inertia_group(self):
         """
+        r"""
         Return the inertia group of self, i.e. the set of elements s of the
         Galois group of the number field of self (which we assume is Galois)
         such that s acts trivially modulo self. This is the same as the 0th
         ramification group of self. See the inertia_group method of the
         GaloisGroup_v2 class for further examples and doctests.
+        ``GaloisGroup_v2`` class for further examples and doctests.
         EXAMPLE::
 …
         return self.ramification_group(0)
     def artin_symbol(self):
+        """
+        Return the Artin symbol ( K / Q, self), where K is the number field of self.
+        This is the unique element s of the decomposition group of self such that
+        s(x) = x^p mod self where p is the residue characteristic of self.
+        (Here self should be prime and unramified.)
+        r"""
+        Return the Artin symbol `( K / \QQ, P)`, where `K` is the
+        number field of `P` =self.  This is the unique element `s` of
+        the decomposition group of `P` such that `s(x) = x^p \pmod{P}`
+        where `p` is the residue characteristic of `P`.  (Here `P`
+        (self) should be prime and unramified.)
         See the artin_symbol method of the GaloisGroup_v2 class for further
         documentation and examples.
+        See the ``artin_symbol`` method of the ``GaloisGroup_v2``
+        class for further documentation and examples.
         EXAMPLE::
 …
         return self.number_field().galois_group().artin_symbol(self)
 def basis_to_module(B, K):
     """
     Given a basis B of elements for a ZZ-submodule of a number field K, return
     the corresponding ZZ-submodule.
+    r"""
+    Given a basis `B` of elements for a `\ZZ`-submodule of a number
+    field `K`, return the corresponding `\ZZ`-submodule.
     EXAMPLES::
 …
           `I`, i.e. a list of elements in the ring of integers `R` representing
           the elements of `(R/I)^*`.
         METHOD: Use pari's ``idealstar`` to find the group structure and
+        ALGORITHM: Use pari's ``idealstar`` to find the group structure and
         generators of the multiplicative group modulo the ideal.
         EXAMPLES::
 …
     def denominator(self):
         r"""
         Return the denominator ideal of this fractional ideal. Each fractional
         ideal has a unique expression as `N/D` where N, D are coprime integral
         ideals; the denominator is D.
+        Return the denominator ideal of this fractional ideal. Each
+        fractional ideal has a unique expression as `N/D` where `N`,
+        `D` are coprime integral ideals; the denominator is `D`.
         EXAMPLES::
 …
         return self._denom_ideal
     def numerator(self):
         """
+        r"""
         Return the numerator ideal of this fractional ideal.
         Each fractional ideal has a unique expression as N/D where N,
         D are coprime integral ideals.  The numerator is N.
+        Each fractional ideal has a unique expression as `N/D` where `N`,
+        `D` are coprime integral ideals.  The numerator is `N`.
         EXAMPLES::
 …
         Returns True if this ideal is coprime to the other, else False.
         INPUT:
+           other -- another ideal of the same field, or generators of an ideal.
+        - ``other`` -- another ideal of the same field, or generators
+          of an ideal.
         OUTPUT:
+           True if self and other are coprime, else False.
+        True if self and other are coprime, else False.
+        NOTE:
+        .. note::
            This function works for fractional ideals as well as
            integral ideals.
 …
         return k(l)
     def small_residue(self, f):
         """
         Given an element f of the ambient number field, returns an
         element g such that f - g belongs to the ideal self (which
         must be integral), and g is small.
+        r"""
+        Given an element `f` of the ambient number field, returns an
+        element `g` such that `f - g` belongs to the ideal self (which
+        must be integral), and `g` is small.
         .. note::
 …
         INPUT:
+        - flag -- when flag=2, it also computes the generators of the
+          group `(O_K/I)^*`, which takes more time. By default flag=1
+          (no generators are computed). In both cases the special pari
+          structure ``bid`` is computed as well.  If flag=0
+          (deprecated) it computes only the group structure of
+          `(O_K/I)^*` (with generators) and not the special ``bid``
+          structure.  OUTPUT: The finite abelian group `(O_K/I)^*`.
+        - ``flag`` (int default 1) -- when ``flag`` =2, it also
+          computes the generators of the group `(O_K/I)^*`, which
+          takes more time. By default ``flag`` =1 (no generators are
+          computed). In both cases the special pari structure ``bid``
+          is computed as well.  If ``flag`` =0 (deprecated) it computes
+          only the group structure of `(O_K/I)^*` (with generators)
+          and not the special ``bid`` structure.
+        OUTPUT:
+        The finite abelian group `(O_K/I)^*`.
         .. note::
 …
         INPUT:
         - ``x`` - a non-zero element of the number field of self,
                   which must have valuation equal to 0 at all prime
                   ideals in the support of the ideal self.
+          which must have valuation equal to 0 at all prime ideals in
+          the support of the ideal self.
         OUTPUT:
         - ``l`` - a list of integers `(x_i)` such that `0 \leq x_i < d_i` and
           `x = \prod_i g_i^{x_i}` in `(R/I)^*`, where I = self, R = ring of
+          `x = \prod_i g_i^{x_i}` in `(R/I)^*`, where `I` = self, `R` = ring of
           integers of the field, and `g_i` are the generators of `(R/I)^*`, of
           orders `d_i` respectively, as given in the ``bid`` structure of
           the ideal self.
 …
         return [ZZ(l) for l in k.pari_nf().ideallog(x._pari_(), self._pari_bid_(2))]
     def element_1_mod(self, other):
         """
         Returns an element r in this ideal such that 1-r is in other
+        r"""
+        Returns an element `r` in this ideal such that `1-r` is in other
         An error is raised if either ideal is not integral of if they
         are not coprime.
         INPUT:
+            other -- another ideal of the same field, or generators of an ideal.
+        - ``other`` -- another ideal of the same field, or generators
+          of an ideal.
         OUTPUT:
+            r -- an element of the ideal self such that 1-r is in the ideal other
+        An element `r` of the ideal self such that `1-r` is in the ideal other
         AUTHOR: Maite Aranes
 …
                                   for p,e in self.factor()]])
     def prime_to_idealM_part(self, M):
         """
         Version for integral ideals of the prime_to_m_part function over ZZ.
         Returns the largest divisor of self that is coprime to the ideal M.
+        r"""
+        Version for integral ideals of the ``prime_to_m_part`` function over `\ZZ`.
+        Returns the largest divisor of self that is coprime to the ideal ``M``.
         INPUT:
+            M -- an integral ideal of the same field, or generators of an ideal
+        - ``M`` -- an integral ideal of the same field, or generators of an ideal
         OUTPUT:
+            An ideal which is the largest divisor of self that is coprime to M.
+        An ideal which is the largest divisor of self that is coprime to `M`.
         AUTHOR: Maite Aranes
 …
         return "Lifting map to %s from quotient of integers by %s"%(self.__OK, self.__I)
 def quotient_char_p(I, p):
     """
     Given an integral ideal I that contains a prime number p, compute
     a vector space V = (OK mod p) / (I mod p), along with a
     homomorphism OK --> V and a section V --> OK.
+    r"""
+    Given an integral ideal `I` that contains a prime number `p`, compute
+    a vector space `V = (O_K \mod p) / (I \mod p)`, along with a
+    homomorphism `O_K \to V` and a section `V \to O_K`.
     EXAMPLES::

sage/rings/number_field/number_field_ideal_rel.py

diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/number_field_ideal_rel.py

-                      a
 """
+r"""
 Relative Number Field Ideals
 AUTHORS:
 …
         sage: i = K.ideal(38); i
         Fractional ideal (38)
+    WARNING: Ideals in relative number fields are broken::
+    .. warning::
+       Ideals in relative number fields are broken::
         sage: K.<a0, a1> = NumberField([x^2 + 1, x^2 + 2]); K
         Number Field in a0 with defining polynomial x^2 + 1 over its base field
 …
             return self.__pari_rhnf
     def absolute_ideal(self):
         """
         If this is an ideal in the extension L/K, return the ideal with
         the same generators in the absolute field L/Q.
+        r"""
+        If this is an ideal in the extension `L/K`, return the ideal with
+        the same generators in the absolute field `L/\QQ`.
         EXAMPLES::
 …
             sage: L.<c> = K.extension(x^2 - b)
             sage: F = L.absolute_field('a')
         Let's check an inert ideal first::
+        An example of an inert ideal::
             sage: P = F.factor(13)[0][0]; P
             Fractional ideal (13)
 …
             sage: J.absolute_ideal()
             Fractional ideal (13)
         Now how about a non-trivial ideal in L, but one that is actually
         principal in the subfield K::
+        Now a non-trivial ideal in `L` that is principal in the
+        subfield `K`::
             sage: J = L.ideal(b); J
             Fractional ideal (b)
 …
             sage: J.absolute_ideal().norm()
         Now an ideal not generated by an element of K::
+        Now an ideal not generated by an element of `K`::
             sage: J = L.ideal(c); J
             Fractional ideal (c)
 …
         raise NotImplementedError, "For a fractional ideal in a relative number field you must use relative_norm or absolute_norm as appropriate"
     def ideal_below(self):
         """
         Compute the ideal of K below this ideal of L.
+        r"""
+        Compute the ideal of `K` below this ideal of `L`.
         EXAMPLES::
 …
         raise NotImplementedError
     def integral_split(self):
         """
         Return a tuple (I, d), where I is an integral ideal, and d is the
         smallest positive integer such that this ideal is equal to I/d.
+        r"""
+        Return a tuple `(I, d)`, where `I` is an integral ideal, and `d` is the
+        smallest positive integer such that this ideal is equal to `I/d`.
         EXAMPLES::
 …
         raise ValueError, "the fractional ideal (= %s) is not prime"%self
     def ramification_index(self):
         """
         For ideals in relative number fields ramification_index is
         deliberately not implemented in order to avoid ambiguity.  Either
         relative_ramification_index or absolute_ramification_index should
         be used instead.
+        r"""
+        For ideals in relative number fields, ``ramification_index``
+        is deliberately not implemented in order to avoid ambiguity.
+        Either ``relative_ramification_index`` or
+        ``absolute_ramification_index`` should be used instead.
         """
         raise NotImplementedError, "For an ideal in a relative number field you must use relative_ramification_index or absolute_ramification_index as appropriate"
     def residue_class_degree(self):
+        """
+        r"""
+        Return the resifue class degree of this prime.
         EXAMPLES::
             sage: PQ.<X> = QQ[]
 …
         return xmrange_iter(abs_residues.iter_list, lambda c: from_abs(abs_residues.typ(c)))
     def element_1_mod(self, other):
         """
         Returns an element r in this ideal such that 1-r is in other.
+        r"""
+        Returns an element `r` in this ideal such that `1-r` is in other.
         An error is raised if either ideal is not integral of if they
         are not coprime.
         INPUT:
         - other -- another ideal of the same field, or generators of an ideal.
+        - ``other`` -- another ideal of the same field, or generators of an ideal.
+        OUTPUT: an element of the ideal self such that 1-r is in the ideal
+        other.
+        OUTPUT:
+        an element `r` of the ideal self such that `1-r` is in the
+        ideal other.
         EXAMPLES::
 …
     def valuation(self, p):
         r"""
+        Return the valuation of this fractional ideal at the prime
+        `\mathfrak{p}`.  If `\mathfrak{p}` is not prime, raise a ValueError.
+        Return the valuation of this fractional ideal at ``p``.
         INPUT:
         - p -- a prime ideal of this relative number field.
+        - ``p`` -- a prime ideal `\mathfrak{p}` of this relative number field.
+        OUTPUT: integer
+        OUTPUT:
+        (integer) The valuation of this fractional ideal at the prime
+        `\mathfrak{p}`.  If `\mathfrak{p}` is not prime, raise a
+        ValueError.
         EXAMPLES::

sage/rings/number_field/number_field_rel.py

diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/number_field_rel.py

-                      a
 r"""
 Relative Number Fields
 AUTHORS::
+AUTHORS:
 - William Stein (2004, 2005): initial version
 - Steven Sivek (2006-05-12): added support for relative extensions
 …
 # from sage.rings.number_field.number_field import is_CyclotomicField
 def is_RelativeNumberField(x):
     """
     Return True if x is a relative number field.
+    r"""
+    Return True if `x` is a relative number field.
     EXAMPLES::
 …
 class NumberField_relative(NumberField_generic):
     """
+    INPUT:
+    - ``base`` -- the base field
+    - ``polynomial`` -- must be defined in the ring `K[x]`, where `K` is
+      the base field.
+    - ``name`` -- variable name
+    - ``latex_name`` -- latex variable name
+    - ``names`` -- alternative to name
+    - ``check`` -- whether to check irreducibility of polynomial.
     EXAMPLES::
         sage: K.<a> = NumberField(x^3 - 2)
 …
         r"""
         INPUT:
         - base -- the base field
         - polynomial -- must be defined in the ring ``K['x']``, where K is
+        - ``base`` -- the base field
+        - ``polynomial`` -- must be defined in the ring `K[x]`, where `K` is
           the base field.
         - name -- variable name
         - latex_name -- latex variable name
         - names -- alternative to name
         - check -- whether to check irreducibility of polynomial.
+        - ``name`` -- variable name
+        - ``latex_name`` -- latex variable name
+        - ``names`` -- alternative to name
+        - ``check`` -- whether to check irreducibility of polynomial.
         EXAMPLES::
 …
             Number Field in a1 with defining polynomial x^2 + 1
         TESTS:
+        Let's ensure that irreducibility testing is working::
+        Test that irreducibility testing is working::
             sage: x = ZZ['x'].0
             sage: K.<a, b> = NumberField([x^2 + 2, x^2 + 3])
 …
         INPUT:
+        - names -- number of names should be at most the number of generators
+          of self, i.e., the number of steps in the tower of relative fields.
+        - ``names`` -- number of names should be at most the number of
+          generators of self, i.e., the number of steps in the tower
+          of relative fields.
         Also, ``K.structure()`` returns from_K and to_K, where
         from_K is an isomorphism from K to self and to_K is an
         isomorphism from self to K.
+        Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where
+        from_K is an isomorphism from `K` to self and ``to_K`` is an
+        isomorphism from self to `K`.
         EXAMPLES::
 …
         return L
     def is_absolute(self):
+        """
+        r"""
+        Returns False, since this is not an absolute field.
         EXAMPLES::
             sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
 …
     def gen(self, n=0):
         """
         Return the n'th generator of this relative number field.
+        Return the `n`'th generator of this relative number field.
         EXAMPLES::
 …
         return self.__gens[n]
     def galois_closure(self, names=None):
         """
+        r"""
         Return the absolute number field `K` that is the Galois closure of this
         relative number field.
 …
         return self.absolute_polynomial().degree()
     def relative_degree(self):
+        """
+        r"""
+        Returns the relative degree of this relative number field.
         EXAMPLES::
 …
     def _latex_(self):
         r"""
         Return a \LaTeX representation of the extension.
+        Return a `\LaTeX` representation of the extension.
         EXAMPLES::
 …
         INPUT:
         - x -- an element of some number field
+        - ``x`` -- an element of some number field
         EXAMPLES::
 …
         raise TypeError, "Cannot coerce element into this number field"
     def _coerce_non_number_field_element_in(self, x):
         """
         Coerce a non-number field element x into this number field.
+        r"""
+        Coerce the non-number field element `x` into this number field.
         INPUT:
         - x -- a non number field element x, e.g., a list, integer, rational,
           or polynomial.
+        - ``x`` -- a non number field element, e.g., a list,
+          integer, rational, or polynomial.
         EXAMPLES::
 …
             TypeError: <class 'sage.rings.polynomial.polynomial_element_generic.Polynomial_generic_dense_field'>
         One can also coerce an element of the polynomial quotient ring
         that's isomorphic to the number field::
+        that is isomorphic to the number field::
             sage: K.<a> = NumberField(x^3 + 17)
             sage: b = K.polynomial_quotient_ring().random_element()
 …
         There are situations for which one might imagine canonical
         coercion could make sense (at least after fixing choices), but
         which aren't yet implemented::
+        which are not yet implemented::
             sage: K.<a> = QuadraticField(2)
             sage: K.coerce(sqrt(2))
 …
             sage: type(K.coerce_map_from(QQ))
             <type 'sage.structure.coerce_maps.DefaultConvertMap_unique'>
+        Make sure we still get our optimized morphisms for special fields:
+        Make sure we still get our optimized morphisms for special fields::
             sage: K.<a> = NumberField(polygen(QQ)^2-2)
             sage: type(K.coerce_map_from(QQ))
             <type 'sage.rings.number_field.number_field_element_quadratic.Q_to_quadratic_field_element'>
 …
     def _coerce_map_from_(self, R):
         """
         Canonical implicit coercion of x into self.
+        Canonical implicit coercion of ``R`` into self.
         Elements of this field canonically coerce in, as does anything
         that coerces into the base field of this field.
 …
     def _rnfeltreltoabs(self, element, check=False):
         r"""
         Return PARI's rnfeletreltoabs, but without requiring rnfinit().
+        Return PARI's ``rnfeletreltoabs()``, but without requiring ``rnfinit()``.
         TESTS::
 …
         return sage.rings.number_field.number_field_ideal_rel.NumberFieldFractionalIdeal_rel
     def _pari_base_bnf(self, certify=False, units=True):
         """
+        r"""
         Return the PARI bnf (big number field) representation of the
         absolute base field in terms of the pari variable y, suitable
         for extension by the pari variable x.
+        absolute base field in terms of the pari variable ``y``, suitable
+        for extension by the pari variable ``x``.
         All caching is done by the absolute base field.
         INPUT:
         - proof -- bool (default: True) if True, certify correctness of
           calculations (not assuming GRH).
+        - ``certify`` (bool, default True) -- if True, certify
+          correctness of calculations (not assuming GRH).
         EXAMPLES::
 …
     @cached_method
     def _pari_base_nf(self):
         """
+        r"""
         Return the PARI number field representation of the absolute
         base field, in terms of the pari variable y, suitable for
         extension by the pari variable x.
+        base field, in terms of the pari variable ``y``, suitable for
+        extension by the pari variable ``x``.
         In future, all caching will be done by the absolute base
         field, but for now we work around a PARI bug that makes
 …
     def is_galois(self):
         r"""
         For a relative number field, is_galois() is deliberately not
+        For a relative number field, ``is_galois()`` is deliberately not
         implemented, since it is not clear whether this would mean "Galois over
+        QQ" or "Galois over the given base field". Use either
+        is_galois_absolute() or is_galois_relative() respectively.
+        `\QQ`" or "Galois over the given base field". Use either ``is_galois_absolute()`` or ``is_galois_relative()`` respectively.
         EXAMPLES::
 …
     def is_galois_relative(self):
         r"""
+        Return True if for this relative extension L/K, L is a Galois extension of K.
+        Return True if for this relative extension `L/K`, `L` is a
+        Galois extension of `K`.
         EXAMPLE::
 …
     def is_galois_absolute(self):
         r"""
         Return True if for this relative extension L/K, L is a Galois extension of `\QQ`.
+        Return True if for this relative extension `L/K`, `L` is a Galois extension of `\QQ`.
         EXAMPLE::
 …
     def absolute_vector_space(self):
         """
+        Return vector space over `\QQ` of self and isomorphisms from
+        the vector space to self and in the other direction.
         EXAMPLES::
             sage: K.<a,b> = NumberField([x^3 + 3, x^3 + 2]); K
 …
         return ans
     def vector_space(self):
         """
         For a relative number field `L`, ``L.vector_space()`` is deliberately
         not implemented, so that a user cannot confuse
         ``L.relative_vector_space()`` with ``L.absolute_vector_space()``.
+        r"""
+        For a relative number field, ``vector_space()`` is
+        deliberately not implemented, so that a user cannot confuse
+        ``relative_vector_space()`` with ``absolute_vector_space()``.
         """
         raise NotImplementedError, "For a relative number field L you must use either L.relative_vector_space() or L.absolute_vector_space() as appropriate"
     def absolute_base_field(self):
         """
+        r"""
         Return the base field of this relative extension, but viewed
         as an absolute field over QQ.
+        as an absolute field over `\QQ`.
         EXAMPLES::
 …
     def pari_absolute_base_polynomial(self):
         r"""
         Return the PARI polynomial defining the absolute base field, in y.
+        Return the PARI polynomial defining the absolute base field, in ``y``.
         EXAMPLES::
 …
         return [from_abs(x) for x in abs.roots_of_unity()]
     def absolute_generator(self):
         """
         Return the chosen generator over QQ for this relative number field.
+        r"""
+        Return the chosen generator over `\QQ` for this relative number field.
         EXAMPLES::
 …
     def absolute_field(self, names):
         r"""
         Return an absolute number field K that is isomorphic to this
         field along with a field-theoretic bijection from self to K
         and from K to self.
+        Return an absolute number field `K` that is isomorphic to this
+        field along with a field-theoretic bijection from self to `K`
+        and from `K` to self.
         INPUT:
         - names -- string; name of generator of the absolute field
+        - ``names`` -- string; name of generator of the absolute field
         OUTPUT: an absolute number field
+        Also, ``K.structure()`` returns from_K and to_K, where from_K is an
+        isomorphism from K to self and to_K is an isomorphism from self to K.
+        Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where
+        ``from_K`` is an isomorphism from `K` to self and ``to_K`` is
+        an isomorphism from self to `K`.
         EXAMPLES::
 …
         """
         Return the defining polynomial of this relative number field.
         This is exactly the same as ``self.relative_polynomal()``.
+        This is exactly the same as ``relative_polynomal()``.
         EXAMPLES::
 …
     def polynomial(self):
         """
         For a relative number field ``L``, ``L.polynomial()`` is deliberately
         not implemented.  Either ``L.relative_polynomial()`` or
         ``L.absolute_polynomial()`` must be used.
+        For a relative number field, ``polynomial()`` is deliberately
+        not implemented.  Either ``relative_polynomial()`` or
+        ``absolute_polynomial()`` must be used.
         """
         raise NotImplementedError, "For a relative number field L you must use either L.relative_polynomial() or L.absolute_polynomial() as appropriate"
 …
         return self.base_field()
     def embeddings(self, K):
         """
+        r"""
         Compute all field embeddings of the relative number field self
         into the field K (which need not even be a number field, e.g.,
         it could be the complex numbers). This will return an
         identical result when given K as input again.
+        into the field `K` (which need not even be a number field,
+        e.g., it could be the complex numbers). This will return an
+        identical result when given `K` as input again.
         If possible, the most natural embedding of K into self
+        If possible, the most natural embedding of self into `K`
         is put first in the list.
         INPUT:
         - K -- a number field
+        - ``K`` -- a field
         EXAMPLES::
 …
     def absolute_discriminant(self, v=None):
         r"""
         Return the absolute discriminant of this relative number field
         or if v is specified, the determinant of the trace pairing
         on the elements of the list v.
+        or if ``v`` is specified, the determinant of the trace pairing
+        on the elements of the list ``v``.
         INPUT:
         - v (optional) -- list of element of this relative number field.
+        - ``v`` (optional) -- list of element of this relative number field.
         OUTPUT: Integer if v is omitted, and Rational otherwise.
+        OUTPUT: Integer if ``v`` is omitted, and Rational otherwise.
         EXAMPLES::
 …
         INPUT:
         - proof -- (default: False)
+        - ``proof`` -- (default: False)
         EXAMPLES::
 …
         INPUT:
         - gens -- list of elements of self; if no generators are given, just
+        - ``gens`` -- list of elements of self; if no generators are given, just
           returns the cardinality of this number field (oo) for consistency.
         - check_is_integral -- bool (default: True), whether to check that each
+        - ``check_is_integral`` -- bool (default: True), whether to check that each
           generator is integral.
         - check_rank -- bool (default: True), whether to check that the ring
+        - ``check_rank`` -- bool (default: True), whether to check that the ring
           generated by gens is of full rank.
         - allow_subfield -- bool (default: False), if True and the generators
+        - ``allow_subfield`` -- bool (default: False), if True and the generators
           do not generate an order, i.e., they generate a subring of smaller
           rank, instead of raising an error, return an order in a smaller
           number field.
 …
             sage: R = P.order([a,b,c]); R
             Relative Order in Number Field in sqrt2 with defining polynomial x^2 - 2 over its base field
         The base ring of an order in a relative extension is still ZZ.::
+        The base ring of an order in a relative extension is still `\ZZ`.:
             sage: R.base_ring()
             Integer Ring
 …
         INPUT:
         - proof -- default: True
+        - ``proof`` -- default: True
         EXAMPLES::
 …
         Given an element in self or an embedding of a subfield into self,
         return a relative number field `K` isomorphic to self that is relative
         over the absolute field `\QQ(\alpha)` or the domain of `\alpha`, along
         with isomorphisms from `K` to self and from self to K.
+        with isomorphisms from `K` to self and from self to `K`.
         INPUT:
         - alpha -- an element of self, or an embedding of a subfield into self
         - names -- name of generator for output field K.
+        - ``alpha`` -- an element of self, or an embedding of a subfield into self
+        - ``names`` -- name of generator for output field `K`.
         OUTPUT: K -- a relative number field
+        OUTPUT: `K` -- a relative number field
         Also, ``K.structure()`` returns from_K and to_K, where
         from_K is an isomorphism from K to self and to_K is an isomorphism
         from self to K.
+        Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where
+        ``from_K`` is an isomorphism from `K` to self and ``to_K`` is
+        an isomorphism from self to `K`.
         EXAMPLES::
 …
             sage: L.base_field()
             Number Field in w with defining polynomial x^2 + 3
         Now suppose we have K below L below M::
+        Now suppose we have `K` below `L` below `M`::
             sage: M = NumberField(x^8 + 2, 'a'); M
             Number Field in a with defining polynomial x^8 + 2
 …
             sage: M_over_L_over_K.base_field() is L_over_K
             True
         Let's test relativizing a degree 6 field over its degree 2 and degree 3
+        Test relativizing a degree 6 field over its degree 2 and degree 3
         subfields, using both an explicit element::
             sage: K.<a> = NumberField(x^6 + 2); K

sage/rings/number_field/order.py

diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/order.py

-                      a
 - William Stein and Robert Bradshaw (2007-09): initial version
 EXAMPLES:
 We define an absolute order::
     sage: K.<a> = NumberField(x^2 + 1); O = K.order(2*a)
 …
 def is_NumberFieldOrder(R):
     """
     Return True if R an order in a number field or R is the ring ZZ of integers.
+    r"""
+    Return True if R is either an order in a number field or is the ring `\ZZ` of integers.
     EXAMPLES::
 …
     return isinstance(R, Order) or R == ZZ
 def EquationOrder(f, names):
     """
+    r"""
     Return the equation order generated by a root of the irreducible
     polynomial f or list of polynomials f (to construct a relative
+    polynomial f or list of polynomials `f` (to construct a relative
     equation order).
     IMPORTANT: Note that the generators of the returned order need
     *not* be a root of f, since the generators of an order are -- in
     SAGE -- module generators.
+    *not* be roots of `f`, since the generators of an order are -- in
+    Sage -- module generators.
     EXAMPLES::
 …
     def __mul__(self, right):
         """
         Create an ideal in this order using the notation Ok*gens
+        Create an ideal in this order using the notation ``Ok*gens``
         EXAMPLES::
 …
     def __rmul__(self, left):
         """
         Create an ideal in this order using the notation gens*Ok.
+        Create an ideal in this order using the notation ``gens*Ok``.
         EXAMPLES::
 …
             return self.number_field().maximal_order()
     def gen(self, i):
         """
         Return i-th module generator of this order.
+        r"""
+        Return `i`'th module generator of this order.
         EXAMPLES::
 …
         """
         Return a list of the module generators of this order.
+        NOTE: For a (much smaller) list of ring generators use
+        ``self.ring_generators()``.
+        .. note::
+           For a (much smaller) list of ring generators use
+           ``ring_generators()``.
         EXAMPLES::
 …
         return self.absolute_degree()
     def basis(self):  # this must be defined in derived class
         """
         Return a basis over ZZ of this order.
+        r"""
+        Return a basis over `\ZZ` of this order.
         EXAMPLES::
 …
         r"""
         Returns the coordinate vector of `x` with respect to this order.
         INPUT::
+        INPUT:
         - `x` -- an element of the number field of this order.
+        - ``x`` -- an element of the number field of this order.
         OUTPUT:
 …
         AUTHOR: John Cremona  2008-11-15
+        ALGORITHM:
         Uses linear algebra.  The change-of-basis matrix is
         cached.  Provides simpler implementations for
         _contains_(), is_integral() and smallest_integer().
+        ``_contains_()``, ``is_integral()`` and ``smallest_integer()``.
         EXAMPLES::
 …
         return to_V(K(x))*M
     def free_module(self):
         """
         Return the free ZZ-module contained in the vector space
+        r"""
+        Return the free `\ZZ`-module contained in the vector space
         associated to the ambient number field, that corresponds
         to this ideal.
 …
             [  0   0   1]
         An example in a relative extension.  Notice that the module is
         a ZZ-module in the absolute_field associated to the relative
+        a `\ZZ`-module in the absolute_field associated to the relative
         field::
             sage: K.<a,b> = NumberField([x^2 + 1, x^2 + 2])
 …
         INPUT:
         - prime -- a prime ideal of the maximal order in this number field.
         - name -- the name of the variable in the residue field
         - check -- whether or not to check the primality of prime.
+        - ``prime`` -- a prime ideal of the maximal order in this number field.
+        - ``name`` -- the name of the variable in the residue field
+        - ``check`` -- whether or not to check the primality of prime.
         OUTPUT:
 …
         `\ZZ`-module, or the degree of the ambient number field that contains
         this order.
         This is a synonym for ``self.degree()``.
+        This is a synonym for ``degree()``.
         EXAMPLES::
 …
         return self.degree()
     def class_number(self, proof=None):
+        """
+        r"""
+        Return the class number of this order.
         EXAMPLES::
             sage: ZZ[2^(1/3)].class_number()
 …
         r"""
         Compare the order self to other.
+        NOTE: This is a well defined way to compare any two objects, but it is
+        not the partial inclusion ordering!.  Thus self < other being True does
+        not necessarily mean that self is contained in other.  Use
+        ``self.is_suborder(other)`` to determine inclusion.
+        .. note::
+           This is a well defined way to compare any two objects, but
+           it is not the partial inclusion ordering!.  Thus self <
+           other being True does not necessarily mean that self is
+           contained in other.  Use ``self.is_suborder(other)`` to
+           determine inclusion.
         EXAMPLES::
 …
         return cmp(self._module_rep, other._module_rep)
     def absolute_degree(self):
         """
         Returns the absolute degree of this order, ie the degree of this order over ZZ.
+        r"""
+        Returns the absolute degree of this order, ie the degree of this order over `\ZZ`.
         EXAMPLES::
 …
                 raise ValueError, "the module must have full rank."
     def __call__(self, x):
         """
         Coerce x into this order.
+        r"""
+        Coerce ``x`` into this order.
         EXAMPLES::
 …
         INPUT:
         - magma -- a magma interpreter
+        - ``magma`` -- a magma interpreter
         OUTPUT:
 …
         INPUT:
         - other -- another absolute order with the same ambient number field.
+        - ``other`` -- another absolute order with the same ambient number field.
         OUTPUT:
 …
         return "%sOrder in %r" % ("Maximal " if self._is_maximal else "", self._K)
     def basis(self):
         """
         Return the basis over ZZ for this order.
+        r"""
+        Return the basis over `\ZZ` for this order.
         EXAMPLES::
 …
         INPUT:
         - names -- string (default: 'z'); name of generator of absolute extension.
+        - ``names`` -- string (default: 'z'); name of generator of absolute extension.
+        NOTE: There *is* a default variable name, since this absolute
+        order is frequently used for internal algorithms.
+        .. note::
+           There *is* a default variable name, since this absolute
+           order is frequently used for internal algorithms.
         EXAMPLES::
 …
             sage: S.basis()
             [1, 5/12*z^3 + 1/6*z, 1/2*z^2, 1/2*z^3]
+        We compute a relative order in alpha0, alpha1, then make the number field
+        that contains the absolute order be called gamma.::
+        We compute a relative order in alpha0, alpha1, then make the
+        number field that contains the absolute order be called
+        gamma.::
             sage: R = EquationOrder( [x^2 + 2, x^2 - 3], 'alpha'); R
             Relative Order in Number Field in alpha0 with defining polynomial x^2 + 2 over its base field
 …
         Return module basis for this relative order.  This is a list
         of elements that generate this order over the base order.
+        WARNING: For now this basis is actually just a basis over ZZ.
+        .. warning::
+           For now this basis is actually just a basis over `\ZZ`.
         EXAMPLES::
 …
         INPUT:
         - other -- another order with the same ambient absolute number field.
+        - ``other`` -- another order with the same ambient absolute number field.
         OUTPUT:
 …
 def each_is_integral(v):
     """
     Return True if each element of the list v of elements of a number
+    Return True if each element of the list ``v`` of elements of a number
     field is integral.
     EXAMPLES::
 …
     """
     INPUT:
     - gens -- list of integral elements of an absolute order.
     - check_is_integral -- bool (default: True), whether to check that each
+    - ``gens`` -- list of integral elements of an absolute order.
+    - ``check_is_integral`` -- bool (default: True), whether to check that each
       generator is integral.
     - check_rank -- bool (default: True), whether to check that the ring
+    - ``check_rank`` -- bool (default: True), whether to check that the ring
       generated by gens is of full rank.
     - is_maximal -- bool (or None); set if maximality of the generated order is
+    - ``is_maximal`` -- bool (or None); set if maximality of the generated order is
       known
     - allow_subfield -- bool (default: False), if True and the generators do
+    - ``allow_subfield`` -- bool (default: False), if True and the generators do
       not generate an order, i.e., they generate a subring of smaller rank,
       instead of raising an error, return an order in a smaller number field.
 …
     """
     INPUT:
     - gens -- list of elements of an absolute number field that generates an
+    - ``gens`` -- list of elements of an absolute number field that generates an
       order in that number field as a ZZ *module*.
     - check_integral -- check that each gen is integral
     - check_rank -- check that the gens span a module of the correct rank
     - check_is_ring -- check that the module is closed under multiplication
+    - ``check_integral`` -- check that each gen is integral
+    - ``check_rank`` -- check that the gens span a module of the correct rank
+    - ``check_is_ring`` -- check that the module is closed under multiplication
       (this is very expensive)
     - is_maximal -- bool (or None); set if maximality of the generated order is known
+    - ``is_maximal`` -- bool (or None); set if maximality of the generated order is known
     OUTPUT:
 …
         sage: R.basis()
         [1/2, i]
     We turn off all check flags and make a really messed up order.::
+    We turn off all check flags and make a really messed up order::
         sage: R = absolute_order_from_module_generators([1/2, i],  check_is_ring=False, check_integral=False, check_rank=False); R
         Order in Number Field in i with defining polynomial x^2 + 1
 …
     """
     INPUT:
     - gens -- list of integral elements of an absolute order.
     - check_is_integral -- bool (default: True), whether to check that each
+    - ``gens`` -- list of integral elements of an absolute order.
+    - ``check_is_integral`` -- bool (default: True), whether to check that each
       generator is integral.
     - check_rank -- bool (default: True), whether to check that the ring
+    - ``check_rank`` -- bool (default: True), whether to check that the ring
       generated by gens is of full rank.
     - is_maximal -- bool (or None); set if maximality of the generated order is
+    - ``is_maximal`` -- bool (or None); set if maximality of the generated order is
       known
     EXAMPLES:
 …
         Relative Order in Number Field in i with defining polynomial x^2 + 1 over its base field
     Basis for the relative order, which is obtained by computing the algebra generated
     by i and a.::
+    by i and a::
         sage: S.basis()
         [1, 7*i - 2*a, -a*i + 8, 25*i - 7*a]

sage/rings/number_field/unit_group.py

diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/unit_group.py

-                      a
 """
+r"""
 Unit Groups of Number Fields
 EXAMPLES::
 …
         INPUT:
         - number_field - a number field
         - proof - boolean (default True): proof flag
+        - ``number_field`` - a number field
+        - ``proof`` - boolean (default True): proof flag
         The proof flag is passed to pari via the pari_bnf() function
+        The proof flag is passed to pari via the ``pari_bnf()`` function
         which computes the unit group.  See the documentation for the
         number_field module.
 …
         INPUT:
         - u -- Any object from which an element of the unit group's number
           field K may be constructed; an error is raised if an element of K
+        - ``u`` -- Any object from which an element of the unit group's number
+          field `K` may be constructed; an error is raised if an element of `K`
           cannot be constructed from u, or if the element constructed is not a
           unit.
 …
     def _coerce_impl(self, x):
         """
         Canonical coercion of x into this unit group.
+        Canonical coercion of ``x`` into this unit group.
         EXAMPLES:
 …
     def gen(self, i=0):
         """
         Return the i-th generator for this unit group.
+        Return the `i`'th generator for this unit group.
+        NOTE: i=0 gives the torsion generator, i.e. a primitive root of unity.
+        .. note::
+           `i=0` gives the torsion generator, i.e. a primitive root of unity.
         EXAMPLES::
 …
     def log(self, u):
         """
         Return the exponents of the unit u with respect to group generators.
+        r"""
+        Return the exponents of the unit ``u`` with respect to group generators.
         INPUT:
         - u -- Any object from which an element of the unit group's number
           field K may be constructed; an error is raised if an element of K
+        - ``u`` -- Any object from which an element of the unit group's number
+          field `K` may be constructed; an error is raised if an element of `K`
           cannot be constructed from u, or if the element constructed is not a
           unit.
         OUTPUT: a list of integers giving the exponents of u with
+        OUTPUT: a list of integers giving the exponents of ``u`` with
         respect to the unit group's basis.
         EXAMPLES::
 …
         return self(u).list()
     def exp(self, exponents):
         """
+        r"""
         Return unit with given exponents with respect to group generators.
         INPUT:
         - u -- Any object from which an element of the unit group's number
           field K may be constructed; an error is raised if an element of K
           cannot be constructed from u, or if the element constructed is not a
           unit.
+        - ``u`` -- Any object from which an element of the unit
+          group's number field `K` may be constructed; an error is
+          raised if an element of `K` cannot be constructed from u, or
+          if the element constructed is not a unit.
         OUTPUT: a list of integers giving the exponents of u with
+        OUTPUT: a list of integers giving the exponents of ``u`` with
         respect to the unit group's basis.
         EXAMPLES::

Context Navigation

Ticket #6188: trac_6188_review.patch

sage/rings/number_field/number_field.py

sage/rings/number_field/number_field_ideal.py

sage/rings/number_field/number_field_ideal_rel.py

sage/rings/number_field/number_field_rel.py

sage/rings/number_field/order.py

sage/rings/number_field/unit_group.py

Download in other formats: