Ticket #6188: trac_6188.patch

File trac_6188.patch, 124.9 KB (added by davidloeffler, 13 years ago)

patch against 4.0.1.alpha0

  • doc/en/reference/number_fields.rst

    # HG changeset patch
    # User David Loeffler <D.Loeffler@dpmms.cam.ac.uk>
    # Date 1243963362 -3600
    # Node ID 0b6b4751a6eafc40481b322ad6110092b79d56e5
    # Parent  f77ae09d3d24458409f0431fe7d06d7c250d1f41
    #6188: add missing files in sage/rings/number_field/ to reference manual
    
    diff -r f77ae09d3d24 -r 0b6b4751a6ea doc/en/reference/number_fields.rst
    a b  
    55   :maxdepth: 2
    66
    77   sage/rings/number_field/number_field
     8   sage/rings/number_field/number_field_rel
    89   sage/rings/number_field/number_field_element
     10   sage/rings/number_field/number_field_element_quadratic
     11   sage/rings/number_field/order
    912   sage/rings/number_field/number_field_ideal
     13   sage/rings/number_field/number_field_ideal_rel
    1014   sage/rings/number_field/class_group
    1115   sage/rings/number_field/galois_group
     16   sage/rings/number_field/unit_group
    1217   sage/rings/qqbar
  • sage/rings/number_field/number_field.py

    diff -r f77ae09d3d24 -r 0b6b4751a6ea sage/rings/number_field/number_field.py
    a b  
    212212    Return *the* number field defined by the given irreducible
    213213    polynomial and with variable with the given name. If check is True
    214214    (the default), also verify that the defining polynomial is
    215     irreducible and over Q.
     215    irreducible and over `\QQ`.
    216216   
    217217    INPUT:
    218218   
    219    
    220     -  ``polynomial`` - a polynomial over QQ or a number
     219    -  ``polynomial`` - a polynomial over `\QQ` or a number
    221220       field, or a list of polynomials.
    222    
    223221    -  ``name`` - a string (default: 'a'), the name of the
    224222       generator
    225    
    226223    -  ``check`` - bool (default: True); do type checking
    227224       and irreducibility checking.
    228    
    229225    -  ``embedding`` - image of the generator in an ambient
    230226       field (default: None)
    231227   
    232    
    233228    EXAMPLES::
    234229   
    235230        sage: z = QQ['z'].0
     
    242237        sage: s^2
    243238        2
    244239   
    245     Constructing a relative number field
    246    
    247     ::
     240    Constructing a relative number field::
    248241   
    249242        sage: K.<a> = NumberField(x^2 - 2)
    250243        sage: R.<t> = K[]
     
    267260        sage: m
    268261        Number Field in j with defining polynomial z^3 + i*z + 3 over its base field
    269262   
    270     Number fields are globally unique.
    271    
    272     ::
     263    Number fields are globally unique::
    273264   
    274265        sage: K.<a>= NumberField(x^3-5)     
    275266        sage: a^3
     
    434425    Return the tower of number fields defined by the polynomials or
    435426    number fields in the list v.
    436427   
    437     This is the field constructed first from v[0], then over that field
    438     from v[1], etc. If all is False, then each v[i] must be irreducible
    439     over the previous fields. Otherwise a list of all possible fields
    440     defined by all those polynomials is output.
     428    This is the field `K_0` generated by a root of ``v[0]`` over its base field
     429    `K_1`, which is in turn generated by a root of ``v[1]`` over its base field
     430    `K_2`, etc, until `K_d = \QQ` where `d` is the size of the list `v`.  If
     431    all is False, then each ``v[i]`` must be irreducible over the previous
     432    fields.  Otherwise a list of all possible fields defined by all those
     433    polynomials is output.
    441434   
    442435    If names defines a variable name a, say, then the generators of the
    443436    intermediate number fields are a0, a1, a2, ...
    444437   
    445438    INPUT:
    446439   
    447    
    448440    -  ``v`` - a list of polynomials or number fields
    449    
    450441    -  ``names`` - variable names
    451    
    452     -  ``check`` - bool (default: True) only relevant if
    453        all is False. Then check irreducibility of each input polynomial.
    454    
     442    -  ``check`` - bool (default: True) only relevant if all is False. Then
     443       check irreducibility of each input polynomial.
    455444   
    456445    OUTPUT: a single number field or a list of number fields
    457446   
     
    24882477        other, as well as possibly embeddings into the compositum.  See the
    24892478        documentation for both_maps below.
    24902479
    2491         If preserve_embedding is \code{True} and if self and other \em{both}
    2492         have embeddings into the same ambient field, only compositums
    2493         respecting both embeddings are returned.  If one (or both) of self or
    2494         other does not have an embedding, or they do not have embeddings into
    2495         the same ambient field, or preserve_embedding is not \code{True} all
    2496         possible composite number fields are returned.
     2480        If preserve_embedding is ``True`` and if self and other *both* have
     2481        embeddings into the same ambient field, only compositums respecting
     2482        both embeddings are returned.  If one (or both) of self or other does
     2483        not have an embedding, or they do not have embeddings into the same
     2484        ambient field, or preserve_embedding is not ``True`` all possible
     2485        composite number fields are returned.
    24972486
    24982487        INPUT:
    24992488           
     
    36753664        """
    36763665        Return the defining polynomial of this number field.
    36773666
    3678         This is exactly the same as \code{self.polynomal()}.
     3667        This is exactly the same as ``self.polynomal()``.
    36793668
    36803669        EXAMPLES::
    36813670       
     
    49514940
    49524941    def _galois_closure_and_embedding(self, names=None):
    49534942        r"""
    4954         Return number field $K$ that is the Galois closure of self and an
    4955         embedding of self into $K$.
     4943        Return number field `K` that is the Galois closure of self and an
     4944        embedding of self into `K`.
    49564945
    49574946        INPUT:
    49584947           
     
    50715060        r"""
    50725061        Compute all Galois automorphisms of self.
    50735062
    5074         This uses PARI's \code{nfgaloisconj} and is much faster than root
    5075         finding for many fields.
     5063        This uses PARI's ``nfgaloisconj`` and is much faster than root finding
     5064        for many fields.
    50765065
    50775066        EXAMPLES::
    50785067       
     
    54165405
    54175406        K -- relative number field
    54185407
    5419         Also, \code{K.structure()} returns from_K and to_K, where
     5408        Also, ``K.structure()`` returns from_K and to_K, where
    54205409        from_K is an isomorphism from K to self and to_K is an isomorphism
    54215410        from self to K.
    54225411
     
    59715960           
    59725961    def _coerce_map_from_(self, K):
    59735962        r"""
    5974         The cyclotomic field $\Q(\zeta_n)$ coerces into the cyclotomic field
    5975         $\Q(\zeta_m)$ iff $n'|m$, where $n'$ is the odd part of $n$ if $4 \not | n$
    5976         and $n'=n$ otherwise.
    5977        
    5978         The morphism is consistant with the chosen embedding into $\C$. In
    5979         particular, if $n|m$ then the resulting morphism is defined by
    5980         $\zeta_n \mapsto \zeta_m^(m/n)$.
    5981        
    5982         If $K$ is not a cyclotomic field, the normal coercion rules for
    5983         number fields are used.
    5984 
    5985         EXAMPLES:
     5963        The cyclotomic field `\Q(\zeta_n)` coerces into the cyclotomic field
     5964        `\Q(\zeta_m)` iff `n'|m`, where `n'` is the odd part of `n` if `4 \not
     5965        | n` and `n'=n` otherwise.
     5966       
     5967        The morphism is consistant with the chosen embedding into `\CC`. In
     5968        particular, if `n|m` then the resulting morphism is defined by `\zeta_n
     5969        \mapsto \zeta_m^(m/n)`.
     5970       
     5971        If `K` is not a cyclotomic field, the normal coercion rules for number
     5972        fields are used.
     5973
     5974        EXAMPLES::
     5975
    59865976            sage: K.<a> = CyclotomicField(12)
    59875977            sage: L.<b> = CyclotomicField(132)
    59885978            sage: L.coerce_map_from(K)
  • sage/rings/number_field/number_field_element_quadratic.pyx

    diff -r f77ae09d3d24 -r 0b6b4751a6ea sage/rings/number_field/number_field_element_quadratic.pyx
    a b  
    11"""
    22Optimized Quadratic Number Field Elements
    33
    4 AUTHORS:
    5     -- Robert Bradshaw (2007-09): Initial version
    6     -- David Harvey (2007-10): fix up a few bugs, polish around the edges
     4This file defines a Cython class ``NumberFieldElement_quadratic`` to speed up
     5computations in quadratic extensions of `\QQ`.
     6
     7AUTHORS:
     8
     9- Robert Bradshaw (2007-09): Initial version
     10- David Harvey (2007-10): fix up a few bugs, polish around the edges
     11- David Loeffler (2009-05): add more documentation and tests
    712
    813TODO:
    9     the _new() method should be overridden in this class to copy the D attribute
     14
     15    The ``_new()`` method should be overridden in this class to copy the ``D``
     16    attribute
    1017
    1118"""
    1219#*****************************************************************************
     
    4855    """
    4956    Used in unpickling elements of number fields.
    5057   
    51     TEST:
     58    TEST::
     59
    5260        sage: K.<a> = NumberField(x^2-x+13)
    5361        sage: loads(dumps(a)) == a
    5462        True
     
    5765
    5866
    5967cdef class NumberFieldElement_quadratic(NumberFieldElement_absolute):
     68    r"""
     69    A NumberFieldElement_quadratic object gives an efficient representation of
     70    an element of a quadratic extension of `\QQ`.
     71
     72    Elements are represented internally as triples `(a, b, c)` of integers,
     73    where `{\rm gcd}(a, b, c) = 1` and `c > 0`, representing the element `(a +
     74    b \sqrt{D}) / c`. Note that if the discriminant `D` is `1 \bmod 4`,
     75    integral elements do not necessarily have `c = 1`.
     76       
     77    TESTS::
     78           
     79        sage: from sage.rings.number_field.number_field_element_quadratic import NumberFieldElement_quadratic
     80
     81    We set up some fields::
     82           
     83        sage: K.<a> = NumberField(x^2+23)
     84        sage: a.parts()
     85        (0, 1)
     86        sage: F.<b> = NumberField(x^2-x+7)
     87        sage: b.parts()
     88        (1/2, 3/2)
     89
     90    We construct elements of these fields in various ways - firstly, from
     91    polynomials::
     92       
     93        sage: NumberFieldElement_quadratic(K, x-1)
     94        a - 1
     95        sage: NumberFieldElement_quadratic(F, x-1)
     96        b - 1
     97       
     98    From triples of Integers::
     99
     100        sage: NumberFieldElement_quadratic(K, (1,2,3))
     101        2/3*a + 1/3
     102        sage: NumberFieldElement_quadratic(F, (1,2,3))
     103        4/9*b + 1/9
     104        sage: NumberFieldElement_quadratic(F, (1,2,3)).parts()
     105        (1/3, 2/3)
     106       
     107    From pairs of Rationals::
     108
     109        sage: NumberFieldElement_quadratic(K, (1/2,1/3))
     110        1/3*a + 1/2
     111        sage: NumberFieldElement_quadratic(F, (1/2,1/3))
     112        2/9*b + 7/18
     113        sage: NumberFieldElement_quadratic(F, (1/2,1/3)).parts()
     114        (1/2, 1/3)
     115       
     116    Direct from Rationals::
     117
     118        sage: NumberFieldElement_quadratic(K, 2/3)
     119        2/3
     120        sage: NumberFieldElement_quadratic(F, 2/3)
     121        2/3
     122
     123    This checks a bug when converting from lists::
     124
     125        sage: w = CyclotomicField(3)([1/2,1])
     126        sage: w == w.__invert__().__invert__()
     127        True
     128    """
    60129
    61130    def __init__(self, parent, f):
    62131        """
    63         Construct a NumberFieldElement_quadratic object as an
    64         efficiently represented member of an absolute quadratic field.
     132        Standard initialisation function.
     133       
     134        EXAMPLE::
    65135
    66         Elements are represented internally as triples (a, b, denom)
    67         of integers, where gcd(a, b, denom) == 1 and denom > 0,
    68         representing the element (a + b*sqrt(disc)) / denom.
    69        
    70         TESTS:
    71             sage: from sage.rings.number_field.number_field_element_quadratic import NumberFieldElement_quadratic
    72            
    73           Setup some fields:
    74             sage: K.<a> = NumberField(x^2+23)
    75             sage: a.parts()
    76             (0, 1)
    77             sage: F.<b> = NumberField(x^2-x+7)
    78             sage: b.parts()
    79             (1/2, 3/2)
    80 
    81           By polynomials:
    82             sage: NumberFieldElement_quadratic(K, x-1)
    83             a - 1
    84             sage: NumberFieldElement_quadratic(F, x-1)
    85             b - 1
    86            
    87           By triples of Integers:
    88             sage: NumberFieldElement_quadratic(K, (1,2,3))
    89             2/3*a + 1/3
    90             sage: NumberFieldElement_quadratic(F, (1,2,3))
    91             4/9*b + 1/9
    92             sage: NumberFieldElement_quadratic(F, (1,2,3)).parts()
    93             (1/3, 2/3)
    94            
    95           By pairs of Rationals:
    96             sage: NumberFieldElement_quadratic(K, (1/2,1/3))
    97             1/3*a + 1/2
    98             sage: NumberFieldElement_quadratic(F, (1/2,1/3))
    99             2/9*b + 7/18
    100             sage: NumberFieldElement_quadratic(F, (1/2,1/3)).parts()
    101             (1/2, 1/3)
    102            
    103           Direct from Rational:
    104             sage: NumberFieldElement_quadratic(K, 2/3)
    105             2/3
    106             sage: NumberFieldElement_quadratic(F, 2/3)
    107             2/3
    108 
    109         This checks a bug when converting from lists:
    110             sage: w = CyclotomicField(3)([1/2,1])
    111             sage: w == w.__invert__().__invert__()
    112             True
    113             """
     136            sage: F.<a> = QuadraticField(-7)
     137            sage: c = a + 7
     138            sage: type(c) # indirect doctest
     139            <type 'sage.rings.number_field.number_field_element_quadratic.NumberFieldElement_quadratic'>
     140        """
    114141        self.D = parent._D
    115142        cdef Integer a, b, denom
    116143        cdef Rational ad, bd
     
    165192
    166193    cdef _new(self):
    167194        """
    168         Quickly creates a new initialized NumberFieldElement with the
    169         same parent as self.
     195        Quickly creates a new initialized NumberFieldElement with the same
     196        parent as self.
     197
     198        EXAMPLE::
     199
     200            sage: F.<b> = CyclotomicField(3)
     201            sage: b + b # indirect doctest
     202            2*b
    170203        """
    171204        cdef NumberFieldElement_quadratic x
    172205        x = <NumberFieldElement_quadratic>PY_NEW_SAME_TYPE(self)
     
    175208        return x
    176209
    177210    cdef number_field(self):
     211        r"""
     212        Return the number field to which this element belongs. Since this is a
     213        Cython cdef method, it is not directly accessible by the user, but the
     214        function "_number_field" calls this one.
     215
     216        EXAMPLE::
     217
     218            sage: F.<b> = QuadraticField(-7)
     219            sage: b._number_field() # indirect doctest
     220            Number Field in b with defining polynomial x^2 + 7
     221        """
    178222        return self._parent
    179223
    180224    def _maxima_init_(self, I=None):
     
    197241        r"""
    198242        Returns a new copy of self.
    199243
    200         TESTS:
     244        TESTS::
     245
    201246            sage: K.<a> = QuadraticField(-3)
    202247            sage: b = a + 3
    203248            sage: c = b.__copy__()
     
    231276       
    232277    def __reduce__(self):
    233278        """
     279        Used for pickling.
     280
    234281        TEST:
     282
    235283            sage: K.<a> = NumberField(x^2-13)
    236284            sage: loads(dumps(a)) == a
    237285            True
     
    258306        is implemented in the _coerce_from_other_cyclotomic_field
    259307        method of a CyclotomicField.
    260308
    261         EXAMPLES:
     309        EXAMPLES::
     310       
    262311            sage: C.<zeta4>=CyclotomicField(4)
    263312            sage: CyclotomicField(20)(zeta4+1)  # The function _lift_cyclotomic_element does the heavy lifting in the background
    264313            zeta20^5 + 1
     
    277326            zeta6 - 1
    278327
    279328        AUTHOR:
    280             -- Joel B. Mohler (original version)
    281             -- Craig Citro (reworked for quadratic elements)
     329
     330        - Joel B. Mohler (original version)
     331       
     332        - Craig Citro (reworked for quadratic elements)
    282333        """
    283334        if check:
    284335            if not isinstance(self.number_field(), number_field.NumberField_cyclotomic) \
     
    380431
    381432    def parts(self):
    382433        """
    383         This function returns a pair of rationals $a$ and $b$ such that
    384         self = $a+b\sqrt{D}$.
     434        This function returns a pair of rationals `a` and `b` such that self `=
     435        a+b\sqrt{D}`.
    385436       
    386437        This is much closer to the internal storage format of the
    387         elements, unless the generator is equal to $\sqrt{D}$ will
    388         be different than the polynomial representation coefficients.
     438        elements than the polynomial representation coefficients (the output of
     439        ``self.list()``), unless the generator with which this number field was
     440        constructed was equal to `\sqrt{D}`. See the last example below.
    389441       
    390         EXAMPLES:
     442        EXAMPLES::
     443
    391444            sage: K.<a> = NumberField(x^2-13)
    392445            sage: K.discriminant()
    393446            13
     
    424477
    425478    cdef bint is_sqrt_disc(self):
    426479        r"""
    427         Returns true if self is sqrt(D).
     480        Returns true if self is `\sqrt{D}`.
     481   
     482        EXAMPLE::
     483       
     484            sage: F.<b> = NumberField(x^2 - x + 7)
     485            sage: b.denominator() # indirect doctest
     486            1
    428487        """
    429488        return mpz_cmp_ui(self.denom, 1)==0 and mpz_cmp_ui(self.a, 0)==0 and mpz_cmp_ui(self.b, 1)==0
    430489               
     
    462521            sage: K.<a> = NumberField(x^2-5)
    463522            sage: K.discriminant()
    464523            5
    465             sage: a+a
     524            sage: a+a # indirect doctest
    466525            2*a
    467526            sage: s = (a+2)/6; s
    468527            1/6*a + 1/3
     
    516575        """
    517576        EXAMPLES:
    518577            sage: K.<a> = NumberField(x^2-13)
    519             sage: b = (a-3)/10; b
     578            sage: b = (a-3)/10; b # indirect doctest
    520579            1/10*a - 3/10
    521580            sage: b-1
    522581            1/10*a - 13/10
     
    560619       
    561620    def __neg__(self):
    562621        """
    563         EXAMPLES:
     622        EXAMPLES::
     623
    564624            sage: K.<a> = NumberField(x^2+163)
    565625            sage: -a
    566626            -a
     
    581641        """
    582642        EXAMPLES:
    583643            sage: K.<a> = NumberField(x^2+23)
    584             sage: a*a
     644            sage: a*a # indirect doctest
    585645            -23
    586646            sage: (a+1)*(a-1)
    587647            -24
     
    638698        """
    639699        EXAMPLE:
    640700            sage: K.<a> = NumberField(x^2+43)
    641             sage: (1+a)*3
     701            sage: (1+a)*3 # indirect doctest
    642702            3*a + 3
    643703        """
    644704        cdef Rational c =  <Rational>_c
     
    654714        """
    655715        EXAMPLE:
    656716            sage: K.<a> = NumberField(x^2+43)
    657             sage: 5*(a-1/5)
     717            sage: 5*(a-1/5) # indirect doctest
    658718            5*a - 1           
    659719        """
    660720        cdef Rational c =  <Rational>_c
     
    670730        """
    671731        EXAMPLES:
    672732            sage: K.<a> = NumberField(x^2-5)
    673             sage: 2/a
     733            sage: 2/a # indirect doctest
    674734            2/5*a
    675735            sage: (a+2)/(a+1)
    676736            1/4*a + 3/4
     
    774834
    775835    def __nonzero__(self):
    776836        """
    777         EXAMPLES:
     837        EXAMPLES::
     838
    778839            sage: K.<a> = NumberField(x^2+163)
    779840            sage: not a
    780841            False
     
    9761037            scale = bd/beta
    9771038            return [ad - scale*alpha, scale]
    9781039
    979        
    9801040    def denominator(self):
    9811041        """
    982         EXAMPLES:
     1042        Return the denominator of self. This is the LCM of the denominators of
     1043        the coefficients of self, and thus it may well be `> 1` even when the
     1044        element is an algebraic integer.
     1045       
     1046        EXAMPLES::
     1047
    9831048            sage: K.<a> = NumberField(x^2+x+41)
    9841049            sage: a.denominator()
    9851050            1
     
    9921057            2
    9931058            sage: K(0).denominator()
    9941059            1
     1060
     1061            sage: K.<a> = NumberField(x^2 - 5)
     1062            sage: b = (a + 1)/2
     1063            sage: b.denominator()
     1064            2
     1065            sage: b.is_integral()
     1066            True
    9951067        """
    9961068        # In terms of the generator...
    9971069        cdef NumberFieldElement_quadratic gen = self.number_field().gen() # should this be cached?
     
    10221094
    10231095    def trace(self):
    10241096        """
    1025         EXAMPLES:
     1097        EXAMPLES::
     1098
    10261099            sage: K.<a> = NumberField(x^2+x+41)
    10271100            sage: a.trace()
    10281101            -1
     
    10301103            [  0   1]
    10311104            [-41  -1]
    10321105           
    1033         The trace is additive:
     1106        The trace is additive::
     1107
    10341108            sage: K.<a> = NumberField(x^2+7)
    10351109            sage: (a+1).trace()
    10361110            2
     
    10531127        return res
    10541128
    10551129
    1056     def norm(self):
     1130    def norm(self, K=None):
    10571131        """
    1058         EXAMPLES:
     1132        Return the norm of self. If the second argument is None, this is the
     1133        norm down to `\QQ`. Otherwise, return the norm down to K (which had
     1134        better be either `\QQ` or this number field).
     1135
     1136        EXAMPLES::
     1137
    10591138            sage: K.<a> = NumberField(x^2-x+3)
    10601139            sage: a.norm()
    10611140            3
     
    10661145            sage: (1+a).norm()
    10671146            6
    10681147           
    1069         The norm is multiplicative:
     1148        The norm is multiplicative::
     1149
    10701150            sage: K.<a> = NumberField(x^2-3)
    10711151            sage: a.norm()
    10721152            -3
     
    10741154            9
    10751155            sage: (3*a).norm()
    10761156            -27
     1157
     1158        We test that the optional argument is handled sensibly::
     1159
     1160            sage: (3*a).norm(QQ)
     1161            -27
     1162            sage: (3*a).norm(K)
     1163            3*a
     1164            sage: (3*a).norm(CyclotomicField(3))
     1165            Traceback (most recent call last):
     1166            ...
     1167            ValueError: no way to embed L into parent's base ring K
     1168           
    10771169        """
     1170        cdef Rational res = <Rational>PY_NEW(Rational)
     1171
     1172        if K is None or K == QQ:
    10781173        # norm = (a^2 - d b^2) / self.denom^2
    1079         cdef Rational res = <Rational>PY_NEW(Rational)
    1080         mpz_pow_ui(mpq_numref(res.value), self.a, 2)
    1081         mpz_pow_ui(mpq_denref(res.value), self.b, 2) # use as temp
    1082         mpz_mul(mpq_denref(res.value), mpq_denref(res.value), self.D.value)
    1083         mpz_sub(mpq_numref(res.value), mpq_numref(res.value), mpq_denref(res.value))
    1084         mpz_pow_ui(mpq_denref(res.value), self.denom, 2)
    1085         mpq_canonicalize(res.value)
    1086         return res
     1174            mpz_pow_ui(mpq_numref(res.value), self.a, 2)
     1175            mpz_pow_ui(mpq_denref(res.value), self.b, 2) # use as temp
     1176            mpz_mul(mpq_denref(res.value), mpq_denref(res.value), self.D.value)
     1177            mpz_sub(mpq_numref(res.value), mpq_numref(res.value), mpq_denref(res.value))
     1178            mpz_pow_ui(mpq_denref(res.value), self.denom, 2)
     1179            mpq_canonicalize(res.value)
     1180            return res
     1181        else:
     1182            return NumberFieldElement.norm(self, K)
    10871183
    10881184
    10891185    def is_integral(self):
    10901186        r"""
    10911187        Returns whether this element is an algebraic integer.
    10921188
    1093         TESTS:
     1189        TESTS::
     1190
    10941191            sage: K.<a> = QuadraticField(-1)
    10951192            sage: a.is_integral()
    10961193            True
     
    11241221       
    11251222    def charpoly(self, var='x'):
    11261223        r"""
    1127         The characteristic polynomial of this element over $\Q$.
     1224        The characteristic polynomial of this element over `\QQ`.
    11281225
    1129         EXAMPLES:
     1226        EXAMPLES::
     1227
    11301228            sage: K.<a> = NumberField(x^2-x+13)
    11311229            sage: a.charpoly()
    11321230            x^2 - x + 13
     
    11411239       
    11421240    def minpoly(self, var='x'):
    11431241        r"""
    1144         The minimal polynomial of this element over $\Q$.
     1242        The minimal polynomial of this element over `\QQ`.
    11451243
    1146         EXAMPLES:
     1244        EXAMPLES::
     1245
    11471246            sage: K.<a> = NumberField(x^2+13)
    11481247            sage: a.minpoly()
    11491248            x^2 + 13
     
    11611260    """
    11621261    Element of an order in a quadratic field.
    11631262
    1164     EXAMPLES:
     1263    EXAMPLES::
     1264
    11651265        sage: K.<a> = NumberField(x^2 + 1)
    11661266        sage: O2 = K.order(2*a)
    11671267        sage: w = O2.1; w
     
    11701270        Order in Number Field in a with defining polynomial x^2 + 1
    11711271    """
    11721272    def __init__(self, order, f):
     1273        r"""
     1274        Standard initialisation function.
     1275
     1276        EXAMPLE::
     1277
     1278            sage: OK.<y> = EquationOrder(x^2 + 5)
     1279            sage: v = OK.1 # indirect doctest
     1280            sage: type(v)
     1281            <type 'sage.rings.number_field.number_field_element_quadratic.OrderElement_quadratic'>
     1282        """
    11731283        K = order.number_field()
    11741284        NumberFieldElement_quadratic.__init__(self, K, f)
    11751285        (<Element>self)._parent = order
     
    11781288        """
    11791289        The norm of an element of the ring of integers is an Integer.
    11801290       
    1181         EXAMPLES:
     1291        EXAMPLES::
     1292
    11821293            sage: K.<a> = NumberField(x^2 + 3)
    11831294            sage: O2 = K.order(2*a)
    11841295            sage: w = O2.gen(1); w
     
    11941305        """
    11951306        The trace of an element of the ring of integers is an Integer.
    11961307
    1197         EXAMPLES:
     1308        EXAMPLES::
     1309
    11981310            sage: K.<a> = NumberField(x^2 - 5)
    11991311            sage: R = K.ring_of_integers()
    12001312            sage: b = R((1+a)/2)
     
    12071319
    12081320    def charpoly(self, var='x'):
    12091321        r"""
    1210         The characteristic polynomial of this element, which is over $\Z$
     1322        The characteristic polynomial of this element, which is over `\ZZ`
    12111323        because this element is an algebraic integer.
    12121324
    1213         EXAMPLES:
     1325        EXAMPLES::
     1326
    12141327            sage: K.<a> = NumberField(x^2 - 5)
    12151328            sage: R = K.ring_of_integers()
    12161329            sage: b = R((5+a)/2)
     
    12261339
    12271340    def minpoly(self, var='x'):
    12281341        r"""
    1229         The minimal polynomial of this element over $\Z$.
     1342        The minimal polynomial of this element over `\ZZ`.
    12301343
    1231         EXAMPLES:
     1344        EXAMPLES::
     1345
    12321346            sage: K.<a> = NumberField(x^2 + 163)
    12331347            sage: R = K.ring_of_integers()
    12341348            sage: f = R(a).minpoly('x'); f
     
    12581372            sage: R = K.ring_of_integers()
    12591373            sage: aa = R.gen(1); aa
    12601374            1/3*a
    1261             sage: 5 * aa
     1375            sage: 5 * aa # indirect doctest
    12621376            5/3*a
    12631377        """
    12641378        cdef Integer c = <Integer>_c
     
    12771391            sage: R = K.ring_of_integers()
    12781392            sage: aa = R.gen(0); aa
    12791393            1/2*a + 1/2
    1280             sage: aa*3
     1394            sage: aa*3 # indirect doctest
    12811395            3/2*a + 3/2
    12821396        """
    12831397        cdef Integer c = <Integer>_c
     
    12951409        is, but it is crucial that the returned value really is an
    12961410        element of its supposed parent! This fixes trac \#4190.
    12971411
    1298         EXAMPLES:
     1412        EXAMPLES::
     1413
    12991414            sage: K = NumberField(x^2 - 17, 'a')
    13001415            sage: OK = K.ring_of_integers()
    13011416            sage: a = OK(K.gen())
    1302             sage: (17/a).parent() is K
     1417            sage: (17/a).parent() is K # indirect doctest
    13031418            True
    13041419            sage: 17/a in OK
    13051420            True
     
    13191434        Implement inversion, checking that the return value has the right parent.
    13201435        See trac \#4190.
    13211436       
    1322         EXAMPLES:
     1437        EXAMPLES::
     1438
    13231439            sage: K = NumberField(x^2 -x + 2, 'a')
    13241440            sage: OK = K.ring_of_integers()
    13251441            sage: a = OK(K.gen())
     
    13361452        r"""
    13371453        Return an inverse of self modulo the given ideal.
    13381454       
    1339         EXAMPLES:
     1455        EXAMPLES::
     1456
    13401457            sage: OE = QuadraticField(-7, 's').ring_of_integers()
    13411458            sage: w = OE.ring_generators()[0]
    13421459            sage: w.inverse_mod(13) + (7*w + 6) in 13*OE
     
    13501467
    13511468cdef class Q_to_quadratic_field_element(Morphism):
    13521469    """
    1353     Morphism that coerces from rationals to elements of a
    1354     quadratic number field K.
     1470    Morphism that coerces from rationals to elements of a quadratic number
     1471    field K.
    13551472    """
    13561473    cdef NumberFieldElement_quadratic zero_element    # the zero element of K
    13571474   
     1475    # TODO: implement __cmp__ properly so we can have a loads/dumps doctest
     1476
    13581477    def __init__(self, K):
    1359         """ K is the target quadratic field """
     1478        """
     1479        K is the target quadratic field
     1480       
     1481        EXAMPLE::
     1482   
     1483            sage: K.<a> = QuadraticField(3)
     1484            sage: phi = K.coerce_map_from(QQ) # indirect doctest
     1485            sage: type(phi)
     1486            <type 'sage.rings.number_field.number_field_element_quadratic.Q_to_quadratic_field_element'>
     1487            sage: phi == loads(dumps(phi)) # not implemented
     1488            True
     1489        """
    13601490        import sage.categories.homset
    13611491        Morphism.__init__(self, sage.categories.homset.Hom(QQ, K))
    13621492        self.zero_element = PY_NEW(NumberFieldElement_quadratic)
     
    13651495       
    13661496
    13671497    cpdef Element _call_(self, x):
     1498        r"""
     1499        Evaluate at a rational x.
     1500
     1501        EXAMPLE::
     1502
     1503            sage: K.<a> = QuadraticField(3)
     1504            sage: phi = K.coerce_map_from(QQ)
     1505            sage: a = phi(2/3); a # indirect doctest
     1506            2/3
     1507            sage: a.parent() is K
     1508            True
     1509        """
    13681510        cdef NumberFieldElement_quadratic y = self.zero_element._new()
    13691511        y.D = self.zero_element.D
    13701512        mpz_set(y.a, mpq_numref((<Rational>x).value))
     
    13721514        return y
    13731515
    13741516    def _repr_type(self):
     1517        r"""
     1518        Return a short name for this morphism.
     1519
     1520        EXAMPLE::
     1521
     1522            sage: K.<a> = QuadraticField(3)
     1523            sage: phi = K.coerce_map_from(QQ)
     1524            sage: repr(phi) # indirect doctest
     1525            'Natural morphism:\n  From: Rational Field\n  To:   Number Field in a with defining polynomial x^2 - 3'
     1526        """
    13751527        return "Natural"
  • sage/rings/number_field/number_field_ideal.py

    diff -r f77ae09d3d24 -r 0b6b4751a6ea sage/rings/number_field/number_field_ideal.py
    a b  
    202202        """
    203203        Return True if x is an element of this ideal.
    204204
    205         This function is called (indirectly) when the \code{in}
    206         operator is used.
     205        This function is called (indirectly) when the ``in`` operator is used.
    207206
    208207        EXAMPLES::
    209208
     
    707706        r"""
    708707        Return True if this ideal is principal.
    709708
    710         Since it uses the PARI method \code{bnfisprincipal}, specify
    711         \code{proof=True} (this is the default setting) to prove the
    712         correctness of the output.
     709        Since it uses the PARI method ``bnfisprincipal``, specify
     710        ``proof=True`` (this is the default setting) to prove the correctness
     711        of the output.
    713712
    714713        EXAMPLES:
    715714
  • sage/rings/number_field/number_field_ideal_rel.py

    diff -r f77ae09d3d24 -r 0b6b4751a6ea sage/rings/number_field/number_field_ideal_rel.py
    a b  
    11"""
    22Relative Number Field Ideals
    33
    4 AUTHOR:
    5    -- Steven Sivek (2005-05-16)
    6    -- William Stein (2007-09-06)
    7    -- Nick Alexander (2009-01)
     4AUTHORS:
    85
    9 EXAMPLES:
     6- Steven Sivek (2005-05-16)
     7- William Stein (2007-09-06)
     8- Nick Alexander (2009-01)
     9
     10EXAMPLES::
     11
    1012    sage: K.<a,b> = NumberField([x^2 + 1, x^2 + 2])
    1113    sage: A = K.absolute_field('z')
    1214    sage: I = A.factor(3)[0][0]
     
    4648    """
    4749    An ideal of a relative number field.
    4850
    49     EXAMPLES:
     51    EXAMPLES::
     52
    5053        sage: K.<a> = NumberField([x^2 + 1, x^2 + 2]); K
    5154        Number Field in a0 with defining polynomial x^2 + 1 over its base field
    5255        sage: i = K.ideal(38); i
    5356        Fractional ideal (38)
    5457       
    55     WARNING: Ideals in relative number fields are broken:
     58    WARNING: Ideals in relative number fields are broken::
     59
    5660        sage: K.<a0, a1> = NumberField([x^2 + 1, x^2 + 2]); K
    5761        Number Field in a0 with defining polynomial x^2 + 1 over its base field
    5862        sage: i = K.ideal([a0+1]); i # random
     
    6872        """
    6973        Compare an ideal of a relative number field to something else.
    7074
    71         EXAMPLES:
     75        EXAMPLES::
     76
    7277            sage: K.<a, b> = NumberField([x^2 + 23, x^2 - 7])
    7378            sage: I = K.ideal(2, (a + 2*b + 3)/2)
    7479            sage: J = K.ideal(2, a - b)
     
    8388        """
    8489        Return True if x is an element of this ideal.
    8590
    86         This function is called (indirectly) when the \code{in}
    87         operator is used.
     91        This function is called (indirectly) when the ``in`` operator is used.
    8892
    89         EXAMPLES:
     93        EXAMPLES::
     94
    9095            sage: K.<a, b> = NumberField([x^2 + 23, x^2 - 7])
    9196            sage: I = K.ideal(2, (a + 2*b + 3)/2)
    9297            sage: [z in I for z in [a, b, 2, a + b]]
     
    99104    def pari_rhnf(self):
    100105        """
    101106        Return PARI's representation of this relative ideal in Hermite
    102         normal form.
    103 
    104         EXAMPLES:
    105        
     107        normal form.       
    106108        """
    107109        try:
    108110            return self.__pari_rhnf
     
    118120        If this is an ideal in the extension L/K, return the ideal with
    119121        the same generators in the absolute field L/Q.
    120122
    121         EXAMPLES:
     123        EXAMPLES::
     124
    122125            sage: x = ZZ['x'].0
    123126            sage: K.<b> = NumberField(x^2 - 2)
    124127            sage: L.<c> = K.extension(x^2 - b)
    125128            sage: F = L.absolute_field('a')
    126129
    127             Let's check an inert ideal first:
     130        Let's check an inert ideal first::
    128131
    129132            sage: P = F.factor(13)[0][0]; P
    130133            Fractional ideal (13)
     
    132135            sage: J.absolute_ideal()
    133136            Fractional ideal (13)
    134137
    135             Now how about a non-trivial ideal in L, but one that is
    136             actually principal in the subfield K:
     138        Now how about a non-trivial ideal in L, but one that is actually
     139        principal in the subfield K::
    137140
    138141            sage: J = L.ideal(b); J
    139142            Fractional ideal (b)
     
    146149            sage: J.absolute_ideal().norm()
    147150            4
    148151
    149             Now an ideal not generated by an element of K:
     152        Now an ideal not generated by an element of K::
    150153
    151154            sage: J = L.ideal(c); J
    152155            Fractional ideal (c)
     
    175178
    176179        WARNING:  This is an internal helper function.
    177180
    178         TESTS:
     181        TESTS::
     182
    179183            sage: L.<a, b> = QQ.extension([x^2 + 71, x^3 + 2*x + 1])
    180184            sage: (2*a + b).norm()
    181185            22584817
     
    224228        """
    225229        Return the multiplicative inverse of self.  Call with ~self.
    226230
    227         EXAMPLES:
     231        EXAMPLES::
     232
    228233            sage: K.<a,b> = NumberField([x^2 + 1, x^2 + 2])
    229234            sage: I = K.fractional_ideal(4)
    230235            sage: I^(-1)
     
    248253        Compute the absolute norm of this fractional ideal in a relative number
    249254        field, returning a positive integer.
    250255
    251         EXAMPLES:
     256        EXAMPLES::
     257
    252258            sage: L.<a, b, c> = QQ.extension([x^2 - 23, x^2 - 5, x^2 - 7])
    253259            sage: I = L.ideal(a + b)
    254260            sage: I.absolute_norm()
     
    263269        Compute the relative norm of this fractional ideal in a relative number
    264270        field, returning an ideal in the base field.
    265271
    266         EXAMPLES:
     272        EXAMPLES::
     273
    267274            sage: R.<x> = QQ[]
    268275            sage: K.<a> = NumberField(x^2+6)
    269276            sage: L.<b> = K.extension(K['x'].gen()^4 + a)
     
    306313        """
    307314        Compute the ideal of K below this ideal of L.
    308315
    309         EXAMPLES:
     316        EXAMPLES::
     317
    310318            sage: R.<x> = QQ[]
    311319            sage: K.<a> = NumberField(x^2+6)
    312320            sage: L.<b> = K.extension(K['x'].gen()^4 + a)
     
    323331            sage: M.ring() is K
    324332            True
    325333
    326             This example concerns an inert ideal:
     334        This example concerns an inert ideal::
    327335
    328336            sage: K = NumberField(x^4 + 6*x^2 + 24, 'a')
    329337            sage: K.factor(7)
     
    342350            sage: L.ideal(7).ideal_below().number_field() is K0
    343351            True
    344352
    345             This example concerns an ideal that splits in the quadratic field
    346             but each factor ideal remains inert in the extension:
     353        This example concerns an ideal that splits in the quadratic field but
     354        each factor ideal remains inert in the extension::
    347355
    348356            sage: len(K.factor(19))
    349357            2
     
    357365            sage: L.ideal(K_into_L(K0_into_K(w1))).ideal_below() == P1
    358366            True
    359367
    360             The choice of embedding of quadratic field into quartic field
    361             matters:
     368        The choice of embedding of quadratic field into quartic field matters::
    362369
    363370            sage: rho, tau = K0.embeddings(K)
    364371            sage: L1 = K.relativize(rho, 'b')
     
    374381            sage: K0.ideal([-a0 + 1]) == K0.ideal([-a0 + 5])
    375382            False
    376383
    377             It works when the base_field is itself a relative number field
     384        It works when the base_field is itself a relative number field::
     385
    378386            sage: PQ.<X> = QQ[]
    379387            sage: F.<a, b> = NumberFieldTower([X^2 - 2, X^2 - 3])
    380388            sage: PF.<Y> = F[]
     
    398406        Factor the ideal by factoring the corresponding ideal
    399407        in the absolute number field.
    400408
    401         EXAMPLES:
     409        EXAMPLES::
     410
    402411            sage: K.<a, b> = QQ.extension([x^2 + 11, x^2 - 5])
    403412            sage: K.factor(5)
    404413            (Fractional ideal (5, 1/2*a - 1/2*b - 1))^2 * (Fractional ideal (5, 1/2*a - 1/2*b + 1))^2
     
    432441        Return a tuple (I, d), where I is an integral ideal, and d is the
    433442        smallest positive integer such that this ideal is equal to I/d.
    434443
    435         EXAMPLES:
     444        EXAMPLES::
     445
    436446            sage: K.<a, b> = NumberFieldTower([x^2 - 23, x^2 + 1])
    437447            sage: I = K.ideal([a + b/3])
    438448            sage: J, d = I.integral_split()
     
    449459        """
    450460        Return True if this ideal of a relative number field is prime.
    451461
    452         EXAMPLES:
     462        EXAMPLES::
     463
    453464            sage: K.<a, b> = NumberField([x^2 - 17, x^3 - 2])
    454465            sage: K.ideal(a + b).is_prime()
    455466            True
     
    462473        """
    463474        Return True if this ideal is integral.
    464475
    465         EXAMPLES:
     476        EXAMPLES::
     477
    466478           sage: K.<a, b> = QQ.extension([x^2 + 11, x^2 - 5])
    467479           sage: I = K.ideal(7).prime_factors()[0]
    468480           sage: I.is_integral()
     
    485497        prime occurring in the factorization of the prime ideal
    486498        of the  base field that this prime lies over.
    487499
    488         EXAMPLES:
     500        EXAMPLES::
     501
    489502            sage: PQ.<X> = QQ[]
    490503            sage: F.<a, b> = NumberFieldTower([X^2 - 2, X^2 - 3])
    491504            sage: PF.<Y> = F[]
     
    515528        prime occurring in the factorization of the rational prime
    516529        that this prime lies over.
    517530
    518         EXAMPLES:
     531        EXAMPLES::
     532
    519533            sage: PQ.<X> = QQ[]
    520534            sage: F.<a, b> = NumberFieldTower([X^2 - 2, X^2 - 3])
    521535            sage: PF.<Y> = F[]
     
    545559
    546560    def residue_class_degree(self):
    547561        """
    548         EXAMPLES:
     562        EXAMPLES::
     563
    549564            sage: PQ.<X> = QQ[]
    550565            sage: F.<a, b> = NumberFieldTower([X^2 - 2, X^2 - 3])
    551566            sage: PF.<Y> = F[]
     
    563578
    564579        An error is raised if this fractional ideal is not integral.
    565580
    566         EXAMPLES:
     581        EXAMPLES::
     582
    567583            sage: K.<a, w> = NumberFieldTower([x^2 - 3, x^2 + x + 1])
    568584            sage: I = K.ideal(6, -w*a - w + 4)
    569585            sage: list(I.residues())[:5]
     
    587603        are not coprime.
    588604                     
    589605        INPUT:
    590             other -- another ideal of the same field, or generators of an ideal.
    591         OUTPUT:
    592             r -- an element of the ideal self such that 1-r is in the ideal other.
    593606
    594         EXAMPLES:
     607        - other -- another ideal of the same field, or generators of an ideal.
     608       
     609        OUTPUT: an element of the ideal self such that 1-r is in the ideal
     610        other.
     611
     612        EXAMPLES::
     613
    595614            sage: K.<a, b> = NumberFieldTower([x^2 - 23, x^2 + 1])
    596615            sage: I = Ideal(2, (a - 3*b + 2)/2)
    597616            sage: J = K.ideal(a)
     
    620639
    621640    def smallest_integer(self):
    622641        r"""
    623         Return the smallest non-negative integer in $I \cap \ZZ$,
    624         where $I$ is this ideal.  If $I = 0$, returns $0$.
     642        Return the smallest non-negative integer in `I \cap \ZZ`, where `I` is
     643        this ideal.  If `I = 0`, returns `0`.
    625644       
    626         EXAMPLES:
     645        EXAMPLES::
     646
    627647            sage: K.<a, b> = NumberFieldTower([x^2 - 23, x^2 + 1])
    628648            sage: I = K.ideal([a + b])
    629649            sage: I.smallest_integer()
     
    636656    def valuation(self, p):
    637657        r"""
    638658        Return the valuation of this fractional ideal at the prime
    639         $\mathfrak{p}$.  If $\mathfrak{p}$ is not prime, raise a
    640         ValueError.
     659        `\mathfrak{p}`.  If `\mathfrak{p}` is not prime, raise a ValueError.
    641660
    642661        INPUT:
    643             p -- a prime ideal of this relative number field.
     662       
     663        - p -- a prime ideal of this relative number field.
    644664
    645         OUTPUT:
    646             integer
     665        OUTPUT: integer
    647666
    648         EXAMPLES:
     667        EXAMPLES::
     668
    649669            sage: K.<a, b> = NumberField([x^2 - 17, x^3 - 2])
    650670            sage: A = K.ideal(a + b)
    651671            sage: A.is_prime()
     
    671691    """
    672692    Return True if x is a fractional ideal of a relative number field.
    673693
    674     EXAMPLES:
     694    EXAMPLES::
     695
    675696        sage: from sage.rings.number_field.number_field_ideal_rel import is_NumberFieldFractionalIdeal_rel
    676697        sage: from sage.rings.number_field.number_field_ideal import is_NumberFieldFractionalIdeal
    677698        sage: is_NumberFieldFractionalIdeal_rel(2/3)
  • sage/rings/number_field/number_field_rel.py

    diff -r f77ae09d3d24 -r 0b6b4751a6ea sage/rings/number_field/number_field_rel.py
    a b  
    11r"""
    22Relative Number Fields
    33
    4 AUTHORS:
    5    -- William Stein (2004, 2005): initial version
    6    -- Steven Sivek (2006-05-12): added support for relative extensions
    7    -- William Stein (2007-09-04): major rewrite and documentation
    8    -- Robert Bradshaw (2008-10): specified embeddings into ambient fields
    9    -- Nick Alexander (2009-01): modernize coercion implementation
     4AUTHORS::
    105
    11 This example follows one in the Magma reference manual:
     6- William Stein (2004, 2005): initial version
     7- Steven Sivek (2006-05-12): added support for relative extensions
     8- William Stein (2007-09-04): major rewrite and documentation
     9- Robert Bradshaw (2008-10): specified embeddings into ambient fields
     10- Nick Alexander (2009-01): modernize coercion implementation
     11
     12This example follows one in the Magma reference manual::
     13
    1214    sage: K.<y> = NumberField(x^4 - 420*x^2 + 40000)
    1315    sage: z = y^5/11; z
    1416    420/11*y^3 - 40000/11*y
     
    1921    sage: KL.<b> = NumberField([x^4 - 420*x^2 + 40000, x^2 + x + 1]); KL
    2022    Number Field in b0 with defining polynomial x^4 - 420*x^2 + 40000 over its base field
    2123
    22 We do some arithmetic in a tower of relative number fields:
     24We do some arithmetic in a tower of relative number fields::
     25
    2326    sage: K.<cuberoot2> = NumberField(x^3 - 2)
    2427    sage: L.<cuberoot3> = K.extension(x^3 - 3)
    2528    sage: S.<sqrt2> = L.extension(x^2 - 2)
     
    4750explicitly coerce all elements into a common field, then do arithmetic
    4851with them there (which is quite fast).
    4952
    50 TESTS:
     53TESTS::
     54
    5155    sage: y = polygen(QQ,'y'); K.<beta> = NumberField([y^3 - 3, y^2 - 2])
    5256    sage: K(y^10)
    5357    27*beta0
     
    150154    """
    151155    Return True if x is a relative number field.
    152156
    153     EXAMPLES:
     157    EXAMPLES::
     158
    154159        sage: from sage.rings.number_field.number_field_rel import is_RelativeNumberField
    155160        sage: is_RelativeNumberField(NumberField(x^2+1,'a'))
    156161        False
     
    166171
    167172class NumberField_relative(NumberField_generic):
    168173    """
    169     EXAMPLES:
     174    EXAMPLES::
     175
    170176        sage: K.<a> = NumberField(x^3 - 2)
    171177        sage: t = K['x'].gen()
    172178        sage: L.<b> = K.extension(t^2+t+a); L
     
    176182                 latex_name=None, names=None, check=True, embedding=None):
    177183        r"""
    178184        INPUT:
    179             base -- the base field
    180             polynomial -- must be defined in the ring \code{K['x']}, where
    181                           K is the base field.
    182             name -- variable name
    183             latex_name -- latex variable name
    184             names --
    185             check -- whether to check irreducibility of polynomial.
     185       
     186        - base -- the base field
     187        - polynomial -- must be defined in the ring ``K['x']``, where K is
     188          the base field.
     189        - name -- variable name
     190        - latex_name -- latex variable name
     191        - names -- alternative to name
     192        - check -- whether to check irreducibility of polynomial.
    186193
    187         EXAMPLES:
     194        EXAMPLES::
     195
    188196            sage: K.<x> = CyclotomicField(5)[]
    189197            sage: W.<a> = NumberField(x^2 + 1)
    190198            sage: W
     
    192200            sage: type(W)
    193201            <class 'sage.rings.number_field.number_field_rel.NumberField_relative'>
    194202
    195         Test that check=False really skips the test:
     203        Test that check=False really skips the test::
     204
    196205            sage: W.<a> = NumberField(K.cyclotomic_polynomial(5), check=False)
    197206            sage: W
    198207            Number Field in a with defining polynomial x^4 + x^3 + x^2 + x + 1 over its base field
    199208
    200         A relative extension of a relative extension:
     209        A relative extension of a relative extension::
     210
    201211            sage: x = ZZ['x'].0
    202212            sage: k.<a> = NumberField([x^2 + 2, x^2 + 1])
    203213            sage: l.<b> = k.extension(x^2 + 3)
     
    209219            Number Field in a1 with defining polynomial x^2 + 1
    210220
    211221        TESTS:
    212         Let's ensure that irreducibility testing is working:
     222        Let's ensure that irreducibility testing is working::
     223
    213224            sage: x = ZZ['x'].0
    214225            sage: K.<a, b> = NumberField([x^2 + 2, x^2 + 3])
    215226            sage: K.<a> = NumberField(x^2 + 2)
     
    302313        given generator names.
    303314
    304315        INPUT:
    305             names -- number of names should be at most the number of
    306                      generators of self, i.e., the number of steps in
    307                      the tower of relative fields.
    308316
    309         Also, \code{K.structure()} returns from_K and to_K, where
     317        - names -- number of names should be at most the number of generators
     318          of self, i.e., the number of steps in the tower of relative fields.
     319
     320        Also, ``K.structure()`` returns from_K and to_K, where
    310321        from_K is an isomorphism from K to self and to_K is an
    311322        isomorphism from self to K.
    312323
    313         EXAMPLES:
     324        EXAMPLES::
     325
    314326            sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
    315327            Number Field in a with defining polynomial x^4 + 3 over its base field
    316328            sage: L.<c,d> = K.change_names()
     
    319331            sage: L.base_field()
    320332            Number Field in d with defining polynomial x^2 + 2
    321333
    322         An example with a 3-level tower:
     334        An example with a 3-level tower::
     335
    323336            sage: K.<a,b,c> = NumberField([x^2 + 17, x^2 + x + 1, x^3 - 2]); K
    324337            Number Field in a with defining polynomial x^2 + 17 over its base field
    325338            sage: L.<m,n,r> = K.change_names()
     
    330343            sage: L.base_field().base_field()
    331344            Number Field in r with defining polynomial x^3 - 2
    332345
    333         And a more complicated example:
     346        And a more complicated example::
     347
    334348            sage: PQ.<X> = QQ[]
    335349            sage: F.<a, b> = NumberField([X^2 - 2, X^2 - 3])
    336350            sage: PF.<Y> = F[]
     
    359373
    360374    def is_absolute(self):
    361375        """
    362         EXAMPLES:
     376        EXAMPLES::
     377
    363378            sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
    364379            Number Field in a with defining polynomial x^4 + 3 over its base field
    365380            sage: K.is_absolute()
     
    373388        """
    374389        Return the generators of this relative number field.
    375390
    376         EXAMPLES:
     391        EXAMPLES::
     392
    377393            sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
    378394            Number Field in a with defining polynomial x^4 + 3 over its base field
    379395            sage: K.gens()
     
    385401        """
    386402        Return the number of generators of this relative number field.
    387403
    388         EXAMPLES:
     404        EXAMPLES::
     405
    389406            sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
    390407            Number Field in a with defining polynomial x^4 + 3 over its base field
    391408            sage: K.gens()
     
    399416        """
    400417        Return the n'th generator of this relative number field.
    401418
    402         EXAMPLES:
     419        EXAMPLES::
     420
    403421            sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
    404422            Number Field in a with defining polynomial x^4 + 3 over its base field
    405423            sage: K.gens()
     
    413431
    414432    def galois_closure(self, names=None):
    415433        """
    416         Return the absolute number field $K$ that is the Galois
    417         closure of this relative number field.
     434        Return the absolute number field `K` that is the Galois closure of this
     435        relative number field.
    418436
    419         EXAMPLES:
     437        EXAMPLES::
     438
    420439            sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
    421440            Number Field in a with defining polynomial x^4 + 3 over its base field
    422441            sage: K.galois_closure('c')
     
    428447        """
    429448        The degree of this relative number field over the rational field.
    430449
    431         EXAMPLES:
     450        EXAMPLES::
     451
    432452            sage: K.<a> = NumberFieldTower([x^2 - 17, x^3 - 2])
    433453            sage: K.absolute_degree()
    434454            6
     
    438458    def relative_degree(self):
    439459        """
    440460
    441         EXAMPLES:
     461        EXAMPLES::
     462
    442463            sage: K.<a> = NumberFieldTower([x^2 - 17, x^3 - 2])
    443464            sage: K.relative_degree()
    444465            2
     
    458479        Return the maximal order, i.e., the ring of integers of this
    459480        number field.
    460481
    461         EXAMPLES:
     482        EXAMPLES::
     483
    462484            sage: K.<a,b> = NumberField([x^2 + 1, x^2 - 3])
    463485            sage: OK = K.maximal_order(); OK.basis()
    464486            [1, 1/2*a - 1/2*b, -1/2*b*a + 1/2, a]
     
    485507
    486508    def __reduce__(self):
    487509        """
    488         TESTS:
     510        TESTS::
     511
    489512            sage: Z = var('Z')
    490513            sage: K.<w> = NumberField(Z^3 + Z + 1)
    491514            sage: L.<z> = K.extension(Z^3 + 2)
     
    503526        Return string representation of this relative number field.
    504527
    505528        The base field is not part of the string representation.  To
    506         find out what the base field is use \code{self.base_field()}.
     529        find out what the base field is use ``self.base_field()``.
    507530
    508         EXAMPLES:
     531        EXAMPLES::
     532
    509533            sage: k.<a, b> = NumberField([x^5 + 2, x^7 + 3])
    510534            sage: k
    511535            Number Field in a with defining polynomial x^5 + 2 over its base field
     
    527551        The cat option is currently ignored.   The result is not cached.
    528552
    529553        EXAMPLES:
    530         This function is implicitly called by the Hom method or function.
     554        This function is implicitly called by the Hom method or function.::
     555
    531556            sage: K.<a,b> = NumberField([x^3 - 2, x^2+1])
    532557            sage: K.Hom(K)
    533558            Automorphism group of Number Field in a with defining polynomial x^3 - 2 over its base field
     
    541566        r"""
    542567        Return a \LaTeX representation of the extension.
    543568
    544         EXAMPLES:
     569        EXAMPLES::
     570
    545571            sage: x = QQ['x'].0
    546572            sage: K.<a> = NumberField(x^3 - 2)
    547573            sage: t = K['x'].gen()
     
    559585        barely implemented) -- it only works for constants.
    560586
    561587        INPUT:
    562             x -- an element of some number field
    563588
    564         EXAMPLES:
     589        - x -- an element of some number field
     590
     591        EXAMPLES::
     592
    565593            sage: K.<a> = NumberField(x^3 + 2)
    566594            sage: L.<b> = NumberField(x^2 + 1)
    567595            sage: K._coerce_from_other_number_field(L(2/3))
     
    581609        Coerce a non-number field element x into this number field.
    582610
    583611        INPUT:
    584             x -- a non number field element x, e.g., a list, integer,
    585             rational, or polynomial.
    586612
    587         EXAMPLES:
     613        - x -- a non number field element x, e.g., a list, integer, rational,
     614          or polynomial.
     615
     616        EXAMPLES::
     617
    588618            sage: K.<a> = NumberField(x^3 + 2/3)
    589619            sage: K._coerce_non_number_field_element_in(-7/8)
    590620            -7/8
    591621            sage: K._coerce_non_number_field_element_in([1,2,3])
    592622            3*a^2 + 2*a + 1
    593623
    594         The list is just turned into a polynomial in the generator.
     624        The list is just turned into a polynomial in the generator.::
     625
    595626            sage: K._coerce_non_number_field_element_in([0,0,0,1,1])
    596627            -2/3*a - 2/3
    597628
    598629        Any polynomial whose coefficients can be coerced to rationals will
    599         coerce, e.g., this one in characteristic 7.
     630        coerce, e.g., this one in characteristic 7.::
     631
    600632            sage: f = GF(7)['y']([1,2,3]); f
    601633            3*y^2 + 2*y + 1
    602634            sage: K._coerce_non_number_field_element_in(f)
    603635            3*a^2 + 2*a + 1
    604636 
    605         But not this one over a field of order 27.
     637        But not this one over a field of order 27.::
     638
    606639            sage: F27.<g> = GF(27)
    607640            sage: f = F27['z']([g^2, 2*g, 1]); f
    608641            z^2 + 2*g*z + g^2
     
    612645            TypeError: <class 'sage.rings.polynomial.polynomial_element_generic.Polynomial_generic_dense_field'>
    613646
    614647        One can also coerce an element of the polynomial quotient ring
    615         that's isomorphic to the number field:
     648        that's isomorphic to the number field::
     649
    616650            sage: K.<a> = NumberField(x^3 + 17)
    617651            sage: b = K.polynomial_quotient_ring().random_element()
    618652            sage: K(b)
    619653            -1/2*a^2 - 4
    620654
    621         MORE EXAMPLES:
     655        MORE EXAMPLES::
    622656
    623         sage: K.<a> = NumberField(ZZ['x'].0^5 + 2, 'a')
    624         sage: L.<b> = K.extension(ZZ['x'].0^2 + 3*a, 'b')
    625         sage: u = QQ['u'].gen()
    626         sage: t = u.parent()['t'].gen()
     657            sage: K.<a> = NumberField(ZZ['x'].0^5 + 2, 'a')
     658            sage: L.<b> = K.extension(ZZ['x'].0^2 + 3*a, 'b')
     659            sage: u = QQ['u'].gen()
     660            sage: t = u.parent()['t'].gen()
    627661
    628         sage: L(a + b)
    629         b + a
     662            sage: L(a + b)
     663            b + a
    630664
    631         sage: L(5*t*(1 + u) + 2/3*u)
    632         (5*a + 5)*b + 2/3*a
    633         sage: L(0*t + 2/3)
    634         2/3
    635         sage: L(1/2*t + 5)
    636         1/2*b + 5
     665            sage: L(5*t*(1 + u) + 2/3*u)
     666            (5*a + 5)*b + 2/3*a
     667            sage: L(0*t + 2/3)
     668            2/3
     669            sage: L(1/2*t + 5)
     670            1/2*b + 5
    637671
    638         This seems reasonable:
     672        This seems reasonable::
    639673
    640         sage: L(t*5)
    641         5*b
     674            sage: L(t*5)
     675            5*b
    642676
    643677        This is misleading, but correct!  It is more often desired
    644678        to make a number field element given by rational
    645679        coefficients of the relative power basis (so 2*b^2 + 3)
    646680        than it is to create the constant term of such an element,
    647         which is what would happen if L(u*5) gave 5*a.
     681        which is what would happen if L(u*5) gave 5*a.::
    648682
    649         sage: L(u*5)
    650         5*b
     683            sage: L(u*5)
     684            5*b
    651685
    652         sage: L([1, 1/2])
    653         1/2*b + 1
    654         sage: L([ a, 1/2 + a/3 ])
    655         (1/3*a + 1/2)*b + a
     686            sage: L([1, 1/2])
     687            1/2*b + 1
     688            sage: L([ a, 1/2 + a/3 ])
     689            (1/3*a + 1/2)*b + a
    656690
    657         sage: L([ 1 ])
    658         Traceback (most recent call last):
    659         ...
    660         ValueError: Length must be equal to the degree of this number field
     691            sage: L([ 1 ])
     692            Traceback (most recent call last):
     693            ...
     694            ValueError: Length must be equal to the degree of this number field
    661695
    662696        TESTS:
    663         Examples from Trac ticket \#4727:
     697        Examples from Trac ticket \#4727::
    664698
    665         sage: K.<j,b> = QQ[sqrt(-1), sqrt(2)]
    666         sage: j
    667         I
    668         sage: j.list()
    669         [0, 1]
    670         sage: K(j.list())
    671         I
    672         sage: (b*j + 1/2).list()
    673         [1/2, sqrt2]
    674         sage: K((b*j + 1/2).list())
    675         sqrt2*I + 1/2
     699            sage: K.<j,b> = QQ[sqrt(-1), sqrt(2)]
     700            sage: j
     701            I
     702            sage: j.list()
     703            [0, 1]
     704            sage: K(j.list())
     705            I
     706            sage: (b*j + 1/2).list()
     707            [1/2, sqrt2]
     708            sage: K((b*j + 1/2).list())
     709            sqrt2*I + 1/2
    676710
    677         Examples from Trac \#4869:
     711        Examples from Trac \#4869::
    678712
    679         sage: K.<z> = CyclotomicField(7)
    680         sage: Ky.<y> = PolynomialRing(K)
    681         sage: L.<a> = K.extension(y^2 + 1)
    682         sage: K(K.polynomial_ring().random_element())
    683         -12*z^2 + 1/2*z - 1/95
    684         sage: L(L.polynomial_ring().random_element())
    685         (z^5 + 1/3*z^4 - z^3 + z^2 - z + 2/3)*a + 1/4*z^5 - 7/2*z^4 + 5/3*z^3 - 1/4*z^2 + 3/2*z - 1
     713            sage: K.<z> = CyclotomicField(7)
     714            sage: Ky.<y> = PolynomialRing(K)
     715            sage: L.<a> = K.extension(y^2 + 1)
     716            sage: K(K.polynomial_ring().random_element())
     717            -12*z^2 + 1/2*z - 1/95
     718            sage: L(L.polynomial_ring().random_element())
     719            (z^5 + 1/3*z^4 - z^3 + z^2 - z + 2/3)*a + 1/4*z^5 - 7/2*z^4 + 5/3*z^3 - 1/4*z^2 + 3/2*z - 1
    686720
    687721        MORE TESTS:
    688722        We construct the composite of three quadratic fields, then
    689         coerce from the quartic subfield of the relative extension:
     723        coerce from the quartic subfield of the relative extension::
    690724       
    691725            sage: k.<a,b,c> = NumberField([x^2 + 5, x^2 + 3, x^2 + 1])
    692726            sage: m = k.base_field(); m
     
    748782        Currently integers, rationals, the base field, and this field
    749783        itself coerce canonical into this field.
    750784
    751         EXAMPLES:
     785        EXAMPLES::
     786
    752787            sage: S.<y> = NumberField(x^3 + x + 1)
    753788            sage: S.coerce(int(4))
    754789            4
     
    761796            sage: S.coerce(y) is y
    762797            True
    763798
    764         Fields with embeddings into an ambient field coerce natrually.
     799        Fields with embeddings into an ambient field coerce natrually.::
     800
    765801            sage: CyclotomicField(15).coerce(CyclotomicField(5).0 - 17/3)
    766802            zeta15^3 - 17/3
    767803            sage: K.<a> = CyclotomicField(16)
     
    775811
    776812        There are situations for which one might imagine canonical
    777813        coercion could make sense (at least after fixing choices), but
    778         which aren't yet implemented:
     814        which aren't yet implemented::
     815
    779816            sage: K.<a> = QuadraticField(2)
    780817            sage: K.coerce(sqrt(2))
    781818            Traceback (most recent call last):
    782819            ...
    783820            TypeError: no canonical coercion from Symbolic Ring to Number Field in a with defining polynomial x^2 - 2
    784821
    785         TESTS:
     822        TESTS::
     823
    786824            sage: K.<a> = NumberField(polygen(QQ)^3-2)
    787825            sage: type(K.coerce_map_from(QQ))
    788826            <type 'sage.structure.coerce_maps.DefaultConvertMap_unique'>
     
    815853        Elements of this field canonically coerce in, as does anything
    816854        that coerces into the base field of this field.
    817855
    818         EXAMPLES:
     856        EXAMPLES::
     857
    819858            sage: k.<a> = NumberField([x^5 + 2, x^7 + 3])
    820859            sage: b = k(k.base_field().gen())
    821860            sage: b = k.coerce(k.base_field().gen())
     
    838877        r"""
    839878        Return PARI's rnfeletreltoabs, but without requiring rnfinit().
    840879
    841         TESTS:
     880        TESTS::
     881
    842882            sage: x = ZZ['x'].0
    843883            sage: K.<a> = NumberField(x^2 + 2)
    844884            sage: L.<b> = K.extension(K['x'].0^3 + 3*a)
     
    869909        This is called by the canonical coercion map on elements from
    870910        the base field.
    871911
    872         EXAMPLES:
     912        EXAMPLES::
     913
    873914            sage: k.<a> = NumberField([x^2 + 3, x^2 + 1])
    874915            sage: m = k.base_field(); m
    875916            Number Field in a1 with defining polynomial x^2 + 1
     
    880921            sage: s^2
    881922            -1
    882923
    883         This implicitly tests this coercion map:
     924        This implicitly tests this coercion map::
     925
    884926            sage: K.<a> = NumberField([x^2 + p for p in [5,3,2]])
    885927            sage: K._coerce_(K.base_field().0)
    886928            a1
     
    905947        Return the Python class used to represent ideals of a relative
    906948        number field.
    907949       
    908         EXAMPLES:
     950        EXAMPLES::
     951
    909952            sage: k.<a> = NumberField([x^5 + 2, x^7 + 3])
    910953            sage: k._fractional_ideal_class_ ()
    911954            <class 'sage.rings.number_field.number_field_ideal_rel.NumberFieldFractionalIdeal_rel'>
     
    921964        All caching is done by the absolute base field.
    922965
    923966        INPUT:
    924             proof -- bool (default: True) if True, certify correctness
    925                      of calculations (not assuming GRH).
    926967
    927         EXAMPLES:
     968        - proof -- bool (default: True) if True, certify correctness of
     969          calculations (not assuming GRH).
     970
     971        EXAMPLES::
     972
    928973            sage: k.<a> = NumberField([x^3 + 2, x^2 + 2])
    929974            sage: k._pari_base_bnf()
    930975            [[;], matrix(0,9), [;], ... 0]
     
    947992        field, but for now we work around a PARI bug that makes
    948993        renamed (substed) nf structures fail in strange ways.
    949994
    950         EXAMPLES:
     995        EXAMPLES::
     996
    951997            sage: y = polygen(QQ,'y')
    952998            sage: k.<a> = NumberField([y^3 + 2, y^2 + 2])
    953999            sage: k._pari_base_nf()
     
    9831029        Return True if for this relative extension L/K, L is a Galois extension of K.
    9841030
    9851031        EXAMPLE::
     1032
    9861033            sage: K.<a> = NumberField(x^3 - 2)
    9871034            sage: y = polygen(K); L.<b> = K.extension(y^2 - a)
    9881035            sage: L.is_galois_relative()
     
    9951042        Return True if for this relative extension L/K, L is a Galois extension of `\QQ`.
    9961043       
    9971044        EXAMPLE::
     1045
    9981046            sage: K.<a> = NumberField(x^3 - 2)
    9991047            sage: y = polygen(K); L.<b> = K.extension(y^2 - a)
    10001048            sage: L.is_galois_absolute()
     
    10091057        Return vector space over the base field of self and isomorphisms
    10101058        from the vector space to self and in the other direction.
    10111059
    1012         EXAMPLES:
     1060        EXAMPLES::
     1061
    10131062            sage: K.<a,b,c> = NumberField([x^2 + 2, x^3 + 2, x^3 + 3]); K
    10141063            Number Field in a with defining polynomial x^2 + 2 over its base field
    10151064            sage: V, from_V, to_V = K.relative_vector_space()
     
    10241073            sage: to_V(from_V(V.1))
    10251074            (0, 1)
    10261075
    1027         The underlying vector space and maps is cached:
     1076        The underlying vector space and maps is cached::
     1077
    10281078            sage: W, from_V, to_V = K.relative_vector_space()
    10291079            sage: V is W
    10301080            True
     
    10411091
    10421092    def absolute_vector_space(self):
    10431093        """
    1044         EXAMPLES:
     1094        EXAMPLES::
     1095
    10451096            sage: K.<a,b> = NumberField([x^3 + 3, x^3 + 2]); K
    10461097            Number Field in a with defining polynomial x^3 + 3 over its base field
    10471098            sage: V,from_V,to_V = K.absolute_vector_space(); V
     
    10781129
    10791130    def vector_space(self):
    10801131        """
    1081         For a relative number field \code{L}, \code{L.vector_space()} is deliberately
    1082         not implemented, so that a user cannot confuse \code{L.relative_vector_space()}
    1083         with \code{L.absolute_vector_space()}.
     1132        For a relative number field `L`, ``L.vector_space()`` is deliberately
     1133        not implemented, so that a user cannot confuse
     1134        ``L.relative_vector_space()`` with ``L.absolute_vector_space()``.
    10841135        """
    10851136        raise NotImplementedError, "For a relative number field L you must use either L.relative_vector_space() or L.absolute_vector_space() as appropriate"
    10861137       
     
    10891140        Return the base field of this relative extension, but viewed
    10901141        as an absolute field over QQ.
    10911142
    1092         EXAMPLES:
     1143        EXAMPLES::
     1144
    10931145            sage: K.<a,b,c> = NumberField([x^2 + 2, x^3 + 3, x^3 + 2])
    10941146            sage: K
    10951147            Number Field in a with defining polynomial x^2 + 2 over its base field
     
    11081160        Internal helper that calls PARI's rnfequation for self without
    11091161        first initializing any PARI structures.
    11101162
    1111         TESTS:
     1163        TESTS::
     1164
    11121165            sage: K.<a> = NumberField(x^2 + 2)
    11131166            sage: L.<b> = K.extension(K['x'].0^5 + 2*a)
    11141167            sage: L._pari_rnfequation()
     
    11161169            sage: NumberField(x^10 + 8, 'a').is_isomorphic(L)
    11171170            True
    11181171
    1119         Initialization is lazy enough to allow arithmetic in massive fields:
     1172        Initialization is lazy enough to allow arithmetic in massive fields::
     1173
    11201174            sage: K.<a> = NumberField(x^10 + 2000*x + 100001)
    11211175            sage: L.<b> = K.extension(K['x'].0^10 + 2*a)
    11221176            sage: L._pari_rnfequation()
     
    11381192        Return root of defining polynomial, which is a generator of
    11391193        the relative number field over the base.
    11401194
    1141         EXAMPLES:
     1195        EXAMPLES::
     1196
    11421197            sage: k.<a> = NumberField(x^2+1); k
    11431198            Number Field in a with defining polynomial x^2 + 1
    11441199            sage: y = polygen(k)
     
    11591214        PARI polynomial corresponding to the polynomial over the
    11601215        rationals that defines this field as an absolute number field.
    11611216
    1162         EXAMPLES:
     1217        EXAMPLES::
     1218
    11631219            sage: k.<a, c> = NumberField([x^2 + 3, x^2 + 1])
    11641220            sage: k.pari_polynomial()
    11651221            x^4 + 8*x^2 + 4
     
    11801236        Return the PARI relative number field object associated
    11811237        to this relative extension.
    11821238
    1183         EXAMPLES:
     1239        EXAMPLES::
     1240
    11841241            sage: k.<a> = NumberField([x^4 + 3, x^2 + 2])
    11851242            sage: k.pari_rnf()
    11861243            [Mod(1, y^2 + 2)*x^4 + Mod(3, y^2 + 2), [], [[108, 0; 0, 108], [3, 0]~], ... 0]
     
    11911248        r"""
    11921249        Return the PARI polynomial defining the absolute base field, in y.
    11931250
    1194         EXAMPLES:
     1251        EXAMPLES::
     1252
    11951253            sage: x = ZZ['x'].0
    11961254            sage: K.<a, b> = NumberField([x^2 + 2, x^2 + 3]); K
    11971255            Number Field in a with defining polynomial x^2 + 2 over its base field
     
    12251283        of a relative extension, the base field is the absolute base
    12261284        field.
    12271285
    1228         EXAMPLES:
     1286        EXAMPLES::
     1287
    12291288            sage: k.<i> = NumberField(x^2 + 1)
    12301289            sage: m.<z> = k.extension(k['w']([i,0,1]))
    12311290            sage: m
     
    12471306        """
    12481307        Return number of roots of unity in this relative field.
    12491308
    1250         EXAMPLES:
     1309        EXAMPLES::
     1310
    12511311            sage: K.<a, b> = NumberField( [x^2 + x + 1, x^4 + 1] )
    12521312            sage: K.number_of_roots_of_unity()
    12531313            24
     
    12601320        """
    12611321        Return all the roots of unity in this relative field, primitive or not.
    12621322
    1263         EXAMPLES:
     1323        EXAMPLES::
     1324
    12641325            sage: K.<a, b> = NumberField( [x^2 + x + 1, x^4 + 1] )
    12651326            sage: K.roots_of_unity()[:5]
    12661327            [-b^3*a, b^2*a + b^2, -b, -a, -b^3*a - b^3]
     
    12731334        """
    12741335        Return the chosen generator over QQ for this relative number field.
    12751336
    1276         EXAMPLES:
     1337        EXAMPLES::
     1338
    12771339            sage: y = polygen(QQ,'y')
    12781340            sage: k.<a> = NumberField([y^2 + 2, y^4 + 3])
    12791341            sage: g = k.absolute_generator(); g
     
    12961358        and from K to self.
    12971359
    12981360        INPUT:
    1299             names -- string; name of generator of the absolute field
     1361
     1362        - names -- string; name of generator of the absolute field
    13001363           
    1301         OUTPUT:
    1302             K -- an absolute number field
     1364        OUTPUT: an absolute number field
    13031365
    1304         Also, \code{K.structure()} returns from_K and to_K, where
    1305         from_K is an isomorphism from K to self and to_K is an isomorphism
    1306         from self to K.
     1366        Also, ``K.structure()`` returns from_K and to_K, where from_K is an
     1367        isomorphism from K to self and to_K is an isomorphism from self to K.
    13071368
    1308         EXAMPLES:
     1369        EXAMPLES::
     1370
    13091371            sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
    13101372            Number Field in a with defining polynomial x^4 + 3 over its base field
    13111373            sage: L.<xyz> = K.absolute_field(); L
     
    13531415
    13541416        This is used mainly to implement some internal arithmetic.
    13551417
    1356         EXAMPLES:
     1418        EXAMPLES::
     1419
    13571420            sage: NumberField(x^2 + (2/3)*x - 9/17,'a').polynomial_ntl()
    13581421            ([-27 34 51], 51)
    13591422        """
     
    13691432    @cached_method
    13701433    def absolute_polynomial(self):
    13711434        r"""
    1372         Return the polynomial over $\QQ$ that defines this field as an
     1435        Return the polynomial over `\QQ` that defines this field as an
    13731436        extension of the rational numbers.
    13741437
    1375         EXAMPLES:
     1438        EXAMPLES::
     1439
    13761440            sage: k.<a, b> = NumberField([x^2 + 1, x^3 + x + 1]); k
    13771441            Number Field in a with defining polynomial x^2 + 1 over its base field
    13781442            sage: k.absolute_polynomial()
     
    13841448        """
    13851449        Return the defining polynomial of this relative number field over its base field.
    13861450
    1387         EXAMPLES:
     1451        EXAMPLES::
     1452
    13881453            sage: K.<a> = NumberFieldTower([x^2 + x + 1, x^3 + x + 1])
    13891454            sage: K.relative_polynomial()
    13901455            x^2 + x + 1
    13911456
    1392             Use absolute polynomial for a polynomial that defines the
    1393             absolute extension.
     1457        Use absolute polynomial for a polynomial that defines the absolute
     1458        extension.::
    13941459
    13951460            sage: K.absolute_polynomial()
    13961461            x^6 + 3*x^5 + 8*x^4 + 9*x^3 + 7*x^2 + 6*x + 3
     
    14011466        """
    14021467        Return the defining polynomial of this relative number field.
    14031468
    1404         This is exactly the same as \code{self.relative_polynomal()}.
     1469        This is exactly the same as ``self.relative_polynomal()``.
    14051470
    1406         EXAMPLES:
     1471        EXAMPLES::
     1472
    14071473            sage: C.<z> = CyclotomicField(5)
    14081474            sage: PC.<X> = C[]
    14091475            sage: K.<a> = C.extension(X^2 + X + z); K
     
    14151481
    14161482    def polynomial(self):
    14171483        """
    1418         For a relative number field \code{L}, \code{L.polynomial()} is deliberately
    1419         not implemented.  Either \code{L.relative_polynomial()}
    1420         or \code{L.absolute_polynomial()} must be used.
     1484        For a relative number field ``L``, ``L.polynomial()`` is deliberately
     1485        not implemented.  Either ``L.relative_polynomial()`` or
     1486        ``L.absolute_polynomial()`` must be used.
    14211487        """
    14221488        raise NotImplementedError, "For a relative number field L you must use either L.relative_polynomial() or L.absolute_polynomial() as appropriate"
    14231489
     
    14251491        """
    14261492        Return the base field of this relative number field.
    14271493
    1428         EXAMPLES:
     1494        EXAMPLES::
     1495
    14291496            sage: k.<a> = NumberField([x^3 + x + 1])
    14301497            sage: R.<z> = k[]
    14311498            sage: L.<b> = NumberField(z^3 + a)
     
    14351502            True
    14361503
    14371504        This is very useful because the print representation of
    1438         a relative field doesn't describe the base field.
     1505        a relative field doesn't describe the base field.::
     1506
    14391507            sage: L
    14401508            Number Field in b with defining polynomial z^3 + a over its base field
    14411509        """
     
    14451513        """
    14461514        This is exactly the same as base_field.
    14471515
    1448         EXAMPLES:
     1516        EXAMPLES::
     1517
    14491518            sage: k.<a> = NumberField([x^2 + 1, x^3 + x + 1])
    14501519            sage: k.base_ring()
    14511520            Number Field in a1 with defining polynomial x^3 + x + 1
     
    14651534        is put first in the list.
    14661535
    14671536        INPUT:
    1468             K -- a number field
    14691537
    1470         EXAMPLES:
     1538        - K -- a number field
     1539
     1540        EXAMPLES::
     1541
    14711542            sage: K.<a,b> = NumberField([x^3 - 2, x^2+1])
    14721543            sage: f = K.embeddings(ComplexField(58)); f
    14731544            [
     
    15701641
    15711642    def absolute_different(self):
    15721643        r"""
    1573         Return the absolute different of this relative number field as
    1574         an ideal of $L$.  To get the relative different of $L/K$,
    1575         use \code{L.relative_different()}.
     1644        Return the absolute different of this relative number field `L`, as an
     1645        ideal of `L`. To get the relative different of `L/K`, use
     1646        ``L.relative_different()``.
    15761647
    1577         EXAMPLES:
     1648        EXAMPLES::
     1649
    15781650            sage: K.<i> = NumberField(x^2 + 1)
    15791651            sage: t = K['t'].gen()
    15801652            sage: L.<b> = K.extension(t^4 - i)
     
    15871659
    15881660    def relative_different(self):
    15891661        r"""
    1590         Return the relative different of this extension $L/K$ as
    1591         an ideal of $L$.  If you want the absolute different of
    1592         $L/Q$, use \code{L.different()}.
     1662        Return the relative different of this extension `L/K` as
     1663        an ideal of `L`.  If you want the absolute different of
     1664        `L/\QQ`, use ``L.absolute_different()``.
    15931665
    1594         EXAMPLES:
     1666        EXAMPLES::
     1667
    15951668            sage: K.<i> = NumberField(x^2 + 1)
    15961669            sage: PK.<t> = K[]
    15971670            sage: L.<a> = K.extension(t^4  - i)
     
    16171690        on the elements of the list v. 
    16181691
    16191692        INPUT:
    1620             v (optional) -- list of element of this relative number field.
    1621         OUTPUT:
    1622             Integer if v is omitted, and Rational otherwise.
    16231693
    1624         EXAMPLES:
     1694        - v (optional) -- list of element of this relative number field.
     1695
     1696        OUTPUT: Integer if v is omitted, and Rational otherwise.
     1697
     1698        EXAMPLES::
     1699
    16251700            sage: K.<i> = NumberField(x^2 + 1)
    16261701            sage: t = K['t'].gen()
    16271702            sage: L.<b> = K.extension(t^4 - i)
     
    16381713
    16391714    def relative_discriminant(self, proof=None):
    16401715        r"""
    1641         Return the relative discriminant of this extension $L/K$ as
    1642         an ideal of $K$.  If you want the (rational) discriminant of
    1643         $L/Q$, use e.g. \code{L.discriminant()}.
     1716        Return the relative discriminant of this extension `L/K` as an ideal of
     1717        `K`. If you want the (rational) discriminant of `L/\QQ`, use e.g.
     1718        ``L.absolute_discriminant()``.
    16441719
    1645         TODO: Note that this uses PARI's \code{rnfdisc} function, which
    1646         according to the documentation takes an \code{nf} parameter in
    1647         GP but a \code{bnf} parameter in the C library.  If the C
    1648         library actually accepts an \code{nf}, then this function
    1649         should be fixed and the \code{proof} parameter removed.
     1720        TODO: Note that this uses PARI's ``rnfdisc`` function, which according
     1721        to the documentation takes an ``nf`` parameter in GP but a ``bnf``
     1722        parameter in the C library.  If the C library actually accepts an
     1723        ``nf``, then this function should be fixed and the ``proof`` parameter
     1724        removed.
    16501725
    16511726        INPUT:
    1652             proof -- (default: False)
    16531727
    1654         EXAMPLES:
     1728        - proof -- (default: False)
     1729
     1730        EXAMPLES::
     1731
    16551732            sage: K.<i> = NumberField(x^2 + 1)
    16561733            sage: t = K['t'].gen()
    16571734            sage: L.<b> = K.extension(t^4 - i)
     
    16881765        order of this number field.
    16891766
    16901767        INPUT:
    1691             gens -- list of elements of self; if no generators are
    1692                     given, just returns the cardinality of this number
    1693                     field (oo) for consistency.
    1694             check_is_integral -- bool (default: True), whether to check
    1695                   that each generator is integral.
    1696             check_rank -- bool (default: True), whether to check that
    1697                   the ring generated by gens is of full rank.
    1698             allow_subfield -- bool (default: False), if True and the generators
    1699                   do not generate an order, i.e., they generate a subring
    1700                   of smaller rank, instead of raising an error, return
    1701                   an order in a smaller number field.
     1768
     1769        - gens -- list of elements of self; if no generators are given, just
     1770          returns the cardinality of this number field (oo) for consistency.
     1771        - check_is_integral -- bool (default: True), whether to check that each
     1772          generator is integral.
     1773        - check_rank -- bool (default: True), whether to check that the ring
     1774          generated by gens is of full rank.
     1775        - allow_subfield -- bool (default: False), if True and the generators
     1776          do not generate an order, i.e., they generate a subring of smaller
     1777          rank, instead of raising an error, return an order in a smaller
     1778          number field.
    17021779
    17031780        The check_is_integral and check_rank inputs must be given as
    17041781        explicit keyword arguments.
    17051782
    1706         EXAMPLES:
     1783        EXAMPLES::
     1784
    17071785            sage: P.<a,b,c> = QQ[2^(1/2), 2^(1/3), 3^(1/2)]
    17081786            sage: R = P.order([a,b,c]); R
    17091787            Relative Order in Number Field in sqrt2 with defining polynomial x^2 - 2 over its base field
    17101788
    1711         The base ring of an order in a relative extension is still ZZ.
     1789        The base ring of an order in a relative extension is still ZZ.::
     1790
    17121791            sage: R.base_ring()
    17131792            Integer Ring
    17141793
    17151794        One must give enough generators to generate a ring of finite index
    1716         in the maximal order:
     1795        in the maximal order::
     1796
    17171797            sage: P.order([a,b])
    17181798            Traceback (most recent call last):
    17191799            ...
     
    17321812        r"""
    17331813        Return the Galois group of the Galois closure of this number
    17341814        field as an abstract group.  Note that even though this is an
    1735         extension $L/K$, the group will be computed as if it were $L/\QQ$.
     1815        extension `L/K`, the group will be computed as if it were `L/\QQ`.
    17361816
    17371817        INPUT:
    17381818       
     
    17461826        relative extensions than absolute ones, so try the galois_group method
    17471827        of the corresponding absolute field.
    17481828
    1749         EXAMPLES:
     1829        EXAMPLES::
     1830
    17501831            sage: x = QQ['x'].0
    17511832            sage: K.<a> = NumberField(x^2 + 1)
    17521833            sage: R.<t> = PolynomialRing(K)
     
    17621843
    17631844    def is_free(self, proof=None):
    17641845        r"""
    1765         Determine whether or not $L/K$ is free (i.e. if $\mathcal{O}_L$ is
    1766         a free $\mathcal{O}_K$-module).
     1846        Determine whether or not `L/K` is free (i.e. if `\mathcal{O}_L` is
     1847        a free `\mathcal{O}_K`-module).
    17671848
    17681849        INPUT:
    1769             proof -- default: True
    17701850
    1771         EXAMPLES:
     1851        - proof -- default: True
     1852
     1853        EXAMPLES::
     1854
    17721855            sage: x = QQ['x'].0
    17731856            sage: K.<a> = NumberField(x^2+6)
    17741857            sage: L.<b> = K.extension(K['x'].gen()^2 + 3)    ## extend by x^2+3
     
    17861869        Lift an element of this extension into the base field if possible,
    17871870        or raise a ValueError if it is not possible.
    17881871
    1789         EXAMPLES:
     1872        EXAMPLES::
     1873
    17901874            sage: x = QQ['x'].0
    17911875            sage: K = NumberField(x^3 - 2, 'a')
    17921876            sage: R = K['x']
     
    18121896    def relativize(self, alpha, names):
    18131897        r"""
    18141898        Given an element in self or an embedding of a subfield into self,
    1815         return a relative number field $K$ isomorphic to self that is relative
    1816         over the absolute field $\QQ(\alpha)$ or the domain of $alpha$, along
    1817         with isomorphisms from $K$ to self and from self to K.
     1899        return a relative number field `K` isomorphic to self that is relative
     1900        over the absolute field `\QQ(\alpha)` or the domain of `\alpha`, along
     1901        with isomorphisms from `K` to self and from self to K.
    18181902
    18191903        INPUT:
    1820             alpha -- an element of self, or an embedding of a subfield into self
    1821             names -- name of generator for output field K.
     1904
     1905        - alpha -- an element of self, or an embedding of a subfield into self
     1906        - names -- name of generator for output field K.
    18221907           
    1823         OUTPUT:
    1824             K -- relative number field
     1908        OUTPUT: K -- a relative number field
    18251909
    1826         Also, \code{K.structure()} returns from_K and to_K, where
     1910        Also, ``K.structure()`` returns from_K and to_K, where
    18271911        from_K is an isomorphism from K to self and to_K is an isomorphism
    18281912        from self to K.
    18291913
    1830         EXAMPLES:
     1914        EXAMPLES::
     1915
    18311916            sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
    18321917            Number Field in a with defining polynomial x^4 + 3 over its base field
    18331918            sage: L.<z,w> = K.relativize(a^2)
     
    18401925            sage: L.base_field()
    18411926            Number Field in w with defining polynomial x^2 + 3
    18421927
    1843             Now suppose we have K below L below M:
     1928        Now suppose we have K below L below M::
    18441929
    18451930            sage: M = NumberField(x^8 + 2, 'a'); M
    18461931            Number Field in a with defining polynomial x^8 + 2
     
    18581943            sage: M_over_L_over_K.base_field() is L_over_K
    18591944            True
    18601945
    1861             Let's test relativizing a degree 6 field over its degree 2 and
    1862             degree 3 subfields, using both an explicit element
     1946        Let's test relativizing a degree 6 field over its degree 2 and degree 3
     1947        subfields, using both an explicit element::
    18631948
    18641949            sage: K.<a> = NumberField(x^6 + 2); K
    18651950            Number Field in a with defining polynomial x^6 + 2
     
    18681953            sage: K3, K3_into_K, _ = K.subfields(3)[0]; K3
    18691954            Number Field in a0 with defining polynomial x^3 - 2
    18701955
    1871             Here we explicitly relativize over an element of K2 (not the
    1872             generator):
     1956        Here we explicitly relativize over an element of K2 (not the
     1957        generator)::
    18731958
    18741959            sage: L = K.relativize(K3_into_K, 'b'); L
    18751960            Number Field in b0 with defining polynomial x^2 + a0 over its base field
     
    18791964            sage: L_over_K2.base_field()
    18801965            Number Field in c1 with defining polynomial x^2 - 2*x + 3
    18811966
    1882             Here we use a morphism to preserve the base field information:
     1967        Here we use a morphism to preserve the base field information::
    18831968
    18841969            sage: K2_into_L = K_to_L * K2_into_K
    18851970            sage: L_over_K2 = L.relativize(K2_into_L, 'c'); L_over_K2
     
    19232008    """
    19242009    This is used in pickling relative fields.
    19252010   
    1926     EXAMPLES:
     2011    EXAMPLES::
     2012
    19272013        sage: from sage.rings.number_field.number_field_rel import NumberField_relative_v1
    19282014        sage: R.<x> = CyclotomicField(3)[]
    19292015        sage: NumberField_relative_v1(CyclotomicField(3), x^2 + 7, 'a', 'a')
  • sage/rings/number_field/order.py

    diff -r f77ae09d3d24 -r 0b6b4751a6ea sage/rings/number_field/order.py
    a b  
    11"""
    2 Orders in number fields.
     2Orders in Number Fields
    33
    44AUTHORS:
    5     -- William Stein and Robert Bradshaw (2007-09): initial version
     5
     6- William Stein and Robert Bradshaw (2007-09): initial version
    67
    78EXAMPLES:
    8 We define an absolute order:
     9We define an absolute order::
     10
    911    sage: K.<a> = NumberField(x^2 + 1); O = K.order(2*a)
    1012    sage: O.basis()
    1113    [1, 2*a]
    1214
    1315We compute a basis for an order in a relative extension
    14 that is generated by 2 elements:
     16that is generated by 2 elements::
     17
    1518    sage: K.<a,b> = NumberField([x^2 + 1, x^2 - 3]); O = K.order([3*a,2*b])
    1619    sage: O.basis()
    1720    [1, 3*a - 2*b, -6*b*a + 6, 3*a]
    1821
    19 We compute a maximal order of a degree 10 field:
     22We compute a maximal order of a degree 10 field::
     23
    2024    sage: K.<a> = NumberField((x+1)^10 + 17)
    2125    sage: K.maximal_order()
    2226    Maximal Order in Number Field in a with defining polynomial x^10 + 10*x^9 + 45*x^8 + 120*x^7 + 210*x^6 + 252*x^5 + 210*x^4 + 120*x^3 + 45*x^2 + 10*x + 18
    2327
    24 We compute a suborder, which has index a power of 17 in the maximal order:
     28We compute a suborder, which has index a power of 17 in the maximal order::
     29
    2530    sage: O = K.order(17*a); O
    2631    Order in Number Field in a with defining polynomial x^10 + 10*x^9 + 45*x^8 + 120*x^7 + 210*x^6 + 252*x^5 + 210*x^4 + 120*x^3 + 45*x^2 + 10*x + 18
    2732    sage: m = O.index_in(K.maximal_order()); m
     
    4651    """
    4752    Return True if R an order in a number field or R is the ring ZZ of integers.
    4853
    49     EXAMPLES:
     54    EXAMPLES::
     55
    5056        sage: from sage.rings.number_field.order import is_NumberFieldOrder
    5157        sage: is_NumberFieldOrder(NumberField(x^2+1,'a').maximal_order())
    5258        True
     
    6975    *not* be a root of f, since the generators of an order are -- in
    7076    SAGE -- module generators.
    7177   
    72     EXAMPLES:
     78    EXAMPLES::
     79
    7380        sage: O.<a,b> = EquationOrder([x^2+1, x^2+2])
    7481        sage: O
    7582        Relative Order in Number Field in a with defining polynomial x^2 + 1 over its base field
     
    7885        sage: O.1
    7986        -3*a + 2*b
    8087
    81     Of course the input polynomial must be integral:
     88    Of course the input polynomial must be integral::
     89
    8290        sage: R = EquationOrder(x^3 + x + 1/3, 'alpha'); R
    8391        Traceback (most recent call last):
    8492        ...
     
    110118    r"""
    111119    An order in a number field.
    112120
    113     An order is a subring of the number field that has $\ZZ$-rank equal
    114     to the degree of the number field over $\QQ$.
     121    An order is a subring of the number field that has `\ZZ`-rank equal
     122    to the degree of the number field over `\QQ`.
    115123
    116     EXAMPLES:
     124    EXAMPLES::
     125
    117126        sage: K.<theta> = NumberField(x^4 + x + 17)
    118127        sage: K.maximal_order()
    119128        Maximal Order in Number Field in theta with defining polynomial x^4 + x + 17
     
    140149        """
    141150        This is called when creating an order to set the ambient field.
    142151
    143         EXAMPLES:
     152        EXAMPLES::
     153
    144154            sage: k = CyclotomicField(5)
    145155            sage: k.maximal_order()
    146156            Maximal Order in Cyclotomic Field of order 5 and degree 4
     
    154164        Return the fractional ideal of the maximal order with given
    155165        generators.
    156166
    157         EXAMPLES:
     167        EXAMPLES::
     168
    158169            sage: K.<a> = NumberField(x^2 + 2)
    159170            sage: R = K.maximal_order()
    160171            sage: R.fractional_ideal(2/3 + 7*a, a)
     
    166177        """
    167178        Return the integral ideal with given generators.
    168179
    169         EXAMPLES:
     180        EXAMPLES::
     181
    170182            sage: K.<a> = NumberField(x^2 + 7)
    171183            sage: R = K.maximal_order()
    172184            sage: R.ideal(2/3 + 7*a, a)
     
    181193            ...
    182194            NotImplementedError: ideals of non-maximal orders not yet supported.
    183195
    184         This function is called implicitly below:
     196        This function is called implicitly below::
     197
    185198            sage: R = EquationOrder(x^2 + 2, 'a'); R
    186199            Order in Number Field in a with defining polynomial x^2 + 2
    187200            sage: (3,15)*R
     
    198211        """
    199212        Create an ideal in this order using the notation Ok*gens
    200213       
    201         EXAMPLES:
     214        EXAMPLES::
     215
    202216            sage: k.<a> = NumberField(x^2 + 5077); G = k.class_group(); G
    203217            Class group of order 22 with structure C22 of Number Field in a with defining polynomial x^2 + 5077
    204218            sage: G.0   # random output
     
    218232        """
    219233        Create an ideal in this order using the notation gens*Ok.
    220234
    221         EXAMPLES:
     235        EXAMPLES::
     236
    222237            sage: k.<a> = NumberField(x^2 + 431); G = k.class_group(); G
    223238            Class group of order 21 with structure C21 of Number Field in a with defining polynomial x^2 + 431
    224239            sage: G.0   # random output
     
    236251        """
    237252        Returns True if this is the maximal order.
    238253
     254        EXAMPLE::
     255
    239256            sage: k.<i> = NumberField(x^2 + 1)
    240257            sage: O3 = k.order(3*i); O5 = k.order(5*i); Ok = k.maximal_order(); Osum = O3 + O5
    241258            sage: Osum.is_maximal()
     
    247264            sage: Ok.is_maximal()
    248265            True
    249266
    250          An example involving a relative order:
     267         An example involving a relative order::
     268
    251269            sage: K.<a,b> = NumberField([x^2 + 1, x^2 - 3]); O = K.order([3*a,2*b]); O
    252270            Relative Order in Number Field in a with defining polynomial x^2 + 1 over its base field
    253271            sage: O.is_maximal()
     
    262280        r"""
    263281        Return False (because an order is never a field).
    264282
    265         EXAMPLES:
     283        EXAMPLES::
     284
    266285            sage: L.<alpha> = NumberField(x**4 - x**2 + 7)
    267286            sage: O = L.maximal_order() ; O.is_field()
    268287            False
     
    275294        r"""
    276295        Return True (because orders are always Noetherian)
    277296       
    278         EXAMPLES:
     297        EXAMPLES::
     298
    279299            sage: L.<alpha> = NumberField(x**4 - x**2 + 7)
    280300            sage: O = L.maximal_order() ; O.is_noetherian()
    281301            True
     
    291311        Return True if this ring is integrally closed, i.e., is equal
    292312        to the maximal order.
    293313
    294         EXAMPLES:
     314        EXAMPLES::
     315
    295316            sage: K.<a> = NumberField(x^2 + 189*x + 394)
    296317            sage: R = K.order(2*a)
    297318            sage: R.is_integrally_closed()
     
    309330        """
    310331        Return the Krull dimension of this order, which is 1.
    311332
    312         EXAMPLES:
     333        EXAMPLES::
     334
    313335            sage: K.<a> = QuadraticField(5)
    314336            sage: OK = K.maximal_order()
    315337            sage: OK.krull_dimension()
     
    324346        """
    325347        Return the integral closure of this order.
    326348
    327         EXAMPLES:
     349        EXAMPLES::
     350
    328351            sage: K.<a> = QuadraticField(5)
    329352            sage: O2 = K.order(2*a); O2
    330353            Order in Number Field in a with defining polynomial x^2 - 5
     
    343366        """
    344367        Return i-th module generator of this order.
    345368
    346         EXAMPLES:
     369        EXAMPLES::
     370
    347371            sage: K.<c> = NumberField(x^3 + 2*x + 17)
    348372            sage: O = K.maximal_order(); O
    349373            Maximal Order in Number Field in c with defining polynomial x^3 + 2*x + 17
     
    372396        Return a list of the module generators of this order.
    373397
    374398        NOTE: For a (much smaller) list of ring generators use
    375         \code{self.ring_generators()}.
     399        ``self.ring_generators()``.
    376400
    377         EXAMPLES:
     401        EXAMPLES::
     402
    378403            sage: K.<a> = NumberField(x^3 + x^2 - 2*x + 8)
    379404            sage: O = K.maximal_order()
    380405            sage: O.gens()
     
    386411        """
    387412        Return the number of module generators of this order.
    388413
    389         EXAMPLES:
     414        EXAMPLES::
     415
    390416            sage: K.<a> = NumberField(x^3 + x^2 - 2*x + 8)
    391417            sage: O = K.maximal_order()
    392418            sage: O.ngens()
     
    398424        """
    399425        Return a basis over ZZ of this order.
    400426
    401         EXAMPLES:
     427        EXAMPLES::
     428
    402429            sage: K.<a> = NumberField(x^3 + x^2 - 16*x + 16)
    403430            sage: O = K.maximal_order(); O
    404431            Maximal Order in Number Field in a with defining polynomial x^3 + x^2 - 16*x + 16
     
    409436
    410437    def coordinates(self, x):
    411438        r"""
    412         Returns the coordinate vector of $x$ with respect to this order.
     439        Returns the coordinate vector of `x` with respect to this order.
    413440
    414         INPUT:
    415             $x$ -- an element of the number field of this order.
     441        INPUT::
     442
     443        - `x` -- an element of the number field of this order.
    416444
    417445        OUTPUT:
    418             A vector of length $n$ (the degree of the field) giving
    419             the coordinates of $x$ with respect to the integral basis
    420             of the order.  In general this will be a vector of
    421             rationals; it will consist of integers if and only if $x$
    422             is in the order.
     446
     447        A vector of length `n` (the degree of the field) giving
     448        the coordinates of `x` with respect to the integral basis
     449        of the order.  In general this will be a vector of
     450        rationals; it will consist of integers if and only if `x`
     451        is in the order.
    423452
    424453        AUTHOR: John Cremona  2008-11-15
    425             Uses linear algebra.  The change-of-basis matrix is
    426             cached.  Provides simpler implementations for
    427             _contains_(), is_integral() and smallest_integer().
     454       
     455        Uses linear algebra.  The change-of-basis matrix is
     456        cached.  Provides simpler implementations for
     457        _contains_(), is_integral() and smallest_integer().
    428458
    429         EXAMPLES:
     459        EXAMPLES::
     460
    430461            sage: K.<i> = QuadraticField(-1)
    431462            sage: OK = K.ring_of_integers()
    432463            sage: OK_basis = OK.basis(); OK_basis
     
    467498        associated to the ambient number field, that corresponds
    468499        to this ideal.
    469500
    470         EXAMPLES:
     501        EXAMPLES::
     502
    471503            sage: K.<a> = NumberField(x^3 + x^2 - 2*x + 8)
    472504            sage: O = K.maximal_order(); O.basis()
    473505            [1, 1/2*a^2 + 1/2*a, a^2]
     
    480512
    481513        An example in a relative extension.  Notice that the module is
    482514        a ZZ-module in the absolute_field associated to the relative
    483         field:
     515        field::
     516
    484517            sage: K.<a,b> = NumberField([x^2 + 1, x^2 + 2])
    485518            sage: O = K.maximal_order(); O.basis()
    486519            [(-3/2*b - 5)*a + 7/2*b - 2, -3*a + 2*b, -2*b*a - 3, -7*a + 5*b]
     
    505538        """
    506539        Return generators for self as a ring.
    507540
    508         EXAMPLES:
     541        EXAMPLES::
     542
    509543            sage: K.<i> = NumberField(x^2 + 1)
    510544            sage: O = K.maximal_order(); O
    511545            Maximal Order in Number Field in i with defining polynomial x^2 + 1
     
    513547            [i]
    514548
    515549        This is an example where 2 generators are required (because 2 is an essential
    516         discriminant divisor).
     550        discriminant divisor).::
     551
    517552            sage: K.<a> = NumberField(x^3 + x^2 - 2*x + 8)
    518553            sage: O = K.maximal_order(); O.basis()
    519554            [1, 1/2*a^2 + 1/2*a, a^2]
     
    544579        Return a primitive n-th root of unity in this order, if it
    545580        contains one. If all is True, return all of them.
    546581
    547         EXAMPLES:
     582        EXAMPLES::
     583
    548584            sage: F.<alpha> = NumberField(x**2+3)
    549585            sage: F.ring_of_integers().zeta(6)
    550586            1/2*alpha + 1/2
     
    572608        Return the number field of this order, which is the ambient
    573609        number field that this order is embedded in.
    574610
    575         EXAMPLES:
     611        EXAMPLES::
     612
    576613            sage: K.<b> = NumberField(x^4 + x^2 + 2)
    577614            sage: O = K.order(2*b); O
    578615            Order in Number Field in b with defining polynomial x^4 + x^2 + 2
     
    589626        r"""
    590627        Return the ambient number field that contains self.
    591628
    592         This is the same as \code{self.number_field()} and
    593         \code{self.fraction_field()}
     629        This is the same as ``self.number_field()`` and
     630        ``self.fraction_field()``
    594631
    595         EXAMPLES:
     632        EXAMPLES::
     633
    596634            sage: k.<z> = NumberField(x^2 - 389)
    597635            sage: o = k.order(389*z + 1)
    598636            sage: o
     
    606644
    607645    def residue_field(self, prime, name = None, check = False):
    608646        """
    609         Return the residue field of this order at a given prime, ie $O/pO$.
     647        Return the residue field of this order at a given prime, ie `O/pO`.
    610648
    611649        INPUT:
    612             prime -- a prime ideal of the maximal order in this number field.
    613             name -- the name of the variable in the residue field
    614             check -- whether or not to check the primality of prime.
     650
     651        - prime -- a prime ideal of the maximal order in this number field.
     652        - name -- the name of the variable in the residue field
     653        - check -- whether or not to check the primality of prime.
     654
    615655        OUTPUT:
    616             The residue field at this prime.
     656       
     657        The residue field at this prime.
    617658
    618         EXAMPLES:
     659        EXAMPLES::
     660       
    619661            sage: R.<x> = QQ[]
    620662            sage: K.<a> = NumberField(x^4+3*x^2-17)
    621663            sage: P = K.ideal(61).factor()[0][0]
     
    633675        Return the fraction field of this order, which is the
    634676        ambient number field.
    635677
    636         EXAMPLES:
     678        EXAMPLES::
     679
    637680            sage: K.<b> = NumberField(x^4 + 17*x^2 + 17)
    638681            sage: O = K.order(17*b); O
    639682            Order in Number Field in b with defining polynomial x^4 + 17*x^2 + 17
     
    644687       
    645688    def degree(self):
    646689        r"""
    647         Return the degree of this order, which is the rank
    648         of this order as a $\ZZ$-module.
     690        Return the degree of this order, which is the rank of this order as a
     691        `\ZZ`-module.
    649692
    650         EXAMPLES:
     693        EXAMPLES::
     694
    651695            sage: k.<c> = NumberField(x^3 + x^2 - 2*x+8)
    652696            sage: o = k.maximal_order()
    653697            sage: o.degree()
     
    659703
    660704    def rank(self):
    661705        r"""
    662         Return the rank of this order, which is the rank of
    663         the underlying $\ZZ$-module, or the degree of the ambient
    664         number field that contains this order.
     706        Return the rank of this order, which is the rank of the underlying
     707        `\ZZ`-module, or the degree of the ambient number field that contains
     708        this order.
    665709
    666         This is a synonym for \code{self.degree()}.
     710        This is a synonym for ``self.degree()``.
    667711
    668         EXAMPLES:
     712        EXAMPLES::
     713
    669714            sage: k.<c> = NumberField(x^5 + x^2 + 1)
    670715            sage: o = k.maximal_order(); o
    671716            Maximal Order in Number Field in c with defining polynomial x^5 + x^2 + 1
     
    676721
    677722    def class_number(self, proof=None):
    678723        """
    679         EXAMPLES:
     724        EXAMPLES::
     725
    680726            sage: ZZ[2^(1/3)].class_number()
    681727            1
    682728            sage: QQ[sqrt(-23)].maximal_order().class_number()
    683729            3
    684730
    685         Note that non-maximal orders aren't supported yet:
     731        Note that non-maximal orders aren't supported yet::
     732
    686733            sage: ZZ[3*sqrt(-3)].class_number()
    687734            Traceback (most recent call last):
    688735            ...
     
    698745
    699746        (Currently only implemented for the maximal order.)
    700747
    701         EXAMPLES:
     748        EXAMPLES::
     749
    702750            sage: k.<a> = NumberField(x^2 + 5077)
    703751            sage: O = k.maximal_order(); O
    704752            Maximal Order in Number Field in a with defining polynomial x^2 + 5077
     
    715763        Return True if self and other are both orders in the
    716764        same ambient number field and self is a subset of other.
    717765
    718         EXAMPLES:
     766        EXAMPLES::
     767
    719768            sage: W.<i> = NumberField(x^2 + 1)
    720769            sage: O5 = W.order(5*i)
    721770            sage: O10 = W.order(10*i)
     
    727776            sage: O10.is_suborder(O15)
    728777            False
    729778
    730         We create another isomorphic but different field:
     779        We create another isomorphic but different field::
     780
    731781            sage: W2.<j> = NumberField(x^2 + 1)
    732782            sage: P5 = W2.order(5*j)
    733783
    734         This is False because the ambient number fields are not equal.
     784        This is False because the ambient number fields are not equal.::
     785
    735786            sage: O5.is_suborder(P5)
    736787            False
    737788
    738789        We create a field that contains (in no natural way!) W,
    739         and of course again is_suborder returns False:
     790        and of course again is_suborder returns False::
     791
    740792            sage: K.<z> = NumberField(x^4 + 1)
    741793            sage: M = K.order(5*z)
    742794            sage: O5.is_suborder(M)
     
    752804        r"""
    753805        Compare the order self to other.
    754806
    755         NOTE: This is a well defined way to compare any two objects,
    756         but it is not the partial inclusion ordering!.  Thus self <
    757         other being True does not necessarily mean that self is
    758         contained in other.  Use \code{self.is_suborder(other)} to
    759         determine inclusion.
     807        NOTE: This is a well defined way to compare any two objects, but it is
     808        not the partial inclusion ordering!.  Thus self < other being True does
     809        not necessarily mean that self is contained in other.  Use
     810        ``self.is_suborder(other)`` to determine inclusion.
    760811
    761         EXAMPLES:
     812        EXAMPLES::
     813
    762814            sage: K.<a> = NumberField(x^3 + 2)
    763815            sage: O1 = K.order(a); O1
    764816            Order in Number Field in a with defining polynomial x^3 + 2
     
    771823            sage: O2 < O1
    772824            False
    773825
    774         Note that "less than" does not mean "is a subset":
     826        Note that "less than" does not mean "is a subset"::
     827
    775828            sage: O2.is_suborder(O1)
    776829            True
    777830            sage: O1 == K
     
    791844        """
    792845        Returns the absolute degree of this order, ie the degree of this order over ZZ.
    793846
    794         EXAMPLES:
     847        EXAMPLES::
     848
    795849            sage: K.<a> = NumberField(x^3 + 2)
    796850            sage: O = K.maximal_order()
    797851            sage: O.absolute_degree()
     
    837891
    838892    def __init__(self, K, module_rep, is_maximal=None, check=True):
    839893        """
    840         EXAMPLES:
     894        EXAMPLES::
     895
    841896            sage: from sage.rings.number_field.order import *
    842897            sage: x = polygen(QQ)
    843898            sage: K.<a> = NumberField(x^3+2)
     
    879934        """
    880935        Coerce x into this order.
    881936
    882         EXAMPLES:
     937        EXAMPLES::
     938
    883939            sage: k.<z> = NumberField(x^2 - 389)
    884940            sage: m = k.order(3*z); m
    885941            Order in Number Field in z with defining polynomial x^2 - 389
     
    901957        """
    902958        Add two orders.
    903959       
    904         EXAMPLES:
     960        EXAMPLES::
     961
    905962            sage: K.<a> = NumberField(polygen(QQ,'z')^3 - 2)
    906963            sage: O6 = K.order(6*a); O6
    907964            Order in Number Field in a with defining polynomial z^3 - 2
     
    928985        """
    929986        Intersect orders.
    930987       
    931         EXAMPLES:
     988        EXAMPLES::
     989
    932990            sage: K.<i> = QuadraticField(-1)
    933991            sage: O3 = K.order(3*i); O5 = K.order(5*i)
    934992            sage: R = O3 & O5; R
     
    9491007        Return Magma version of this absolute order.
    9501008
    9511009        INPUT:
    952             magma -- a magma interpreter
     1010
     1011        - magma -- a magma interpreter
    9531012
    9541013        OUTPUT:
    955             a MagmaElement, the magma version of this absolute order
    9561014
    957         EXAMPLES:
     1015        a MagmaElement, the magma version of this absolute order
     1016
     1017        EXAMPLES::
     1018
    9581019            sage: K.<a> = NumberField(x^3 + 2)
    9591020            sage: magma(K.maximal_order())  # optional - magma
    9601021            Equation Order with defining polynomial x^3 + 2 over its ground order
    9611022
    962         _magma_init_ was called implicitly by the above call:
     1023        _magma_init_ was called implicitly by the above call::
     1024
    9631025            sage: K.maximal_order()._magma_init_(magma) # optional - magma
    9641026            'Order([(_sage_[...]![1, 0, 0]),(_sage_[...]![0, 1, 0]),(_sage_[...]![0, 0, 1])])'
    9651027        """
     
    9711033        """
    9721034        Return the discriminant of this order.
    9731035
    974         EXAMPLES:
     1036        EXAMPLES::
     1037
    9751038            sage: K.<a> = NumberField(x^8 + x^3 - 13*x + 26)
    9761039            sage: O = K.maximal_order()
    9771040            sage: factor(O.discriminant())
     
    10011064        Return a new order isomorphic to this one in the number field with
    10021065        given variable names.
    10031066
    1004         EXAMPLES:
     1067        EXAMPLES::
     1068
    10051069            sage: R = EquationOrder(x^3 + x + 1, 'alpha'); R
    10061070            Order in Number Field in alpha with defining polynomial x^3 + x + 1
    10071071            sage: R.basis()
     
    10221086        so it is a rational number if self isn't contained in other.
    10231087
    10241088        INPUT:
    1025             other -- another absolute order with the same ambient
    1026             number field.
     1089
     1090        - other -- another absolute order with the same ambient number field.
    10271091
    10281092        OUTPUT:
    1029             a rational number
     1093
     1094        a rational number
    10301095       
    1031         EXAMPLES:
     1096        EXAMPLES::
     1097
    10321098            sage: k.<i> = NumberField(x^2 + 1)
    10331099            sage: O1 = k.order(i)
    10341100            sage: O5 = k.order(5*i)
     
    10641130        order, embedded in the vector space corresponding to the
    10651131        ambient number field.
    10661132
    1067         EXAMPLES:
     1133        EXAMPLES::
     1134
    10681135            sage: k.<a> = NumberField(x^3 + x + 3)
    10691136            sage: m = k.order(3*a); m
    10701137            Order in Number Field in a with defining polynomial x^3 + x + 3
     
    10811148        """
    10821149        Return the intersection of this order with another order.
    10831150
    1084         EXAMPLES:
     1151        EXAMPLES::
     1152
    10851153            sage: k.<i> = NumberField(x^2 + 1)
    10861154            sage: O6 = k.order(6*i)
    10871155            sage: O9 = k.order(9*i)
     
    11021170        """
    11031171        Return print representation of this absolute order.
    11041172
    1105         EXAMPLES:
     1173        EXAMPLES::
     1174
    11061175            sage: K.<a> = NumberField(x^4 - 5)
    11071176            sage: K.maximal_order()._repr_()
    11081177            'Maximal Order in Number Field in a with defining polynomial x^4 - 5'
     
    11161185        """
    11171186        Return the basis over ZZ for this order.
    11181187
    1119         EXAMPLES:
     1188        EXAMPLES::
     1189
    11201190            sage: k.<c> = NumberField(x^3 + x^2 + 1)
    11211191            sage: O = k.maximal_order(); O
    11221192            Maximal Order in Number Field in c with defining polynomial x^3 + x^2 + 1
    11231193            sage: O.basis()
    11241194            [1, c, c^2]
    11251195
    1126         The basis is an immutable sequence:
     1196        The basis is an immutable sequence::
     1197
    11271198            sage: type(O.basis())
    11281199            <class 'sage.structure.sequence.Sequence'>
    11291200
    1130         The generator functionality uses the basis method:
     1201        The generator functionality uses the basis method::
     1202
    11311203            sage: O.0
    11321204            1
    11331205            sage: O.1
     
    11501222        Return the absolute order associated to this order, which is
    11511223        just this order again since this is an absolute order.
    11521224
    1153         EXAMPLES:
     1225        EXAMPLES::
     1226
    11541227            sage: K.<a> = NumberField(x^3 + 2)
    11551228            sage: O1 = K.order(a); O1
    11561229            Order in Number Field in a with defining polynomial x^3 + 2
     
    11721245    def __init__(self, K, absolute_order, is_maximal=None, check=True):
    11731246        """
    11741247        Create the relative order.
     1248
     1249        EXAMPLE::
     1250
     1251            sage: k.<a,b> = NumberFieldTower([x^2 - 3, x^2 + 1])
     1252            sage: k.maximal_order() # indirect doctest
     1253            Relative Order in Number Field in a with defining polynomial x^2 - 3 over its base field
    11751254        """
    11761255        Order.__init__(self, K, is_maximal=is_maximal)
    11771256        self._absolute_order = absolute_order
     
    12241303        """
    12251304        Return print representation of this relative order.
    12261305
    1227         EXAMPLES:
     1306        EXAMPLES::
     1307
    12281308            sage: O = EquationOrder([x^2 + x + 1, x^3 - 2],'a,b')
    12291309            sage: O._repr_()
    12301310            'Relative Order in Number Field in a with defining polynomial x^2 + x + 1 over its base field'
     
    12381318        order.
    12391319
    12401320        INPUT:
    1241             names -- string (default: 'z'); name of generator of absolute extension.
     1321       
     1322        - names -- string (default: 'z'); name of generator of absolute extension.
    12421323
    12431324        NOTE: There *is* a default variable name, since this absolute
    12441325        order is frequently used for internal algorithms.
    12451326
    1246         EXAMPLES:
     1327        EXAMPLES::
     1328
    12471329            sage: R = EquationOrder([x^2 + 1, x^2 - 5], 'i,g'); R
    12481330            Relative Order in Number Field in i with defining polynomial x^2 + 1 over its base field
    12491331            sage: R.basis()
     
    12551337            [1, 5/12*z^3 + 1/6*z, 1/2*z^2, 1/2*z^3]
    12561338
    12571339        We compute a relative order in alpha0, alpha1, then make the number field
    1258         that contains the absolute order be called gamma.
     1340        that contains the absolute order be called gamma.::
     1341
    12591342            sage: R = EquationOrder( [x^2 + 2, x^2 - 3], 'alpha'); R
    12601343            Relative Order in Number Field in alpha0 with defining polynomial x^2 + 2 over its base field
    12611344            sage: R.absolute_order('gamma')
     
    12751358
    12761359        WARNING: For now this basis is actually just a basis over ZZ.
    12771360
    1278         EXAMPLES:
     1361        EXAMPLES::
     1362
    12791363            sage: K.<a,b> = NumberField([x^2+1, x^2+3])
    12801364            sage: O = K.order([a,b])
    12811365            sage: O.basis()
     
    13001384        Add two relative orders or a relative order to an absolute
    13011385        order (which always results in an absolute order).
    13021386
    1303         EXAMPLES:
     1387        EXAMPLES::
     1388
    13041389            sage: K.<a,b> = NumberField([x^2+1, x^2+3])
    13051390            sage: O2 = K.order([2*a, b]); O2.absolute_discriminant()
    13061391            36864
     
    13521437        of the absolute order associated to self.
    13531438
    13541439        OUTPUT:
    1355             an integer
     1440
     1441        an integer
    13561442       
    1357         EXAMPLES:
     1443        EXAMPLES::
     1444
    13581445            sage: R = EquationOrder([x^2 + 1, x^3 + 2], 'a,b')
    13591446            sage: d = R.absolute_discriminant(); d
    13601447            -746496
     
    13691456        """
    13701457        Returns true if self is a subset of the order other.
    13711458       
    1372         EXAMPLES:
     1459        EXAMPLES::
     1460
    13731461            sage: K.<a,b> = NumberField([x^2 + 1, x^3 + 2])
    13741462            sage: R1 = K.order([a,b])
    13751463            sage: R2 = K.order([2*a,b])
     
    13931481        so it is a rational number if self isn't contained in other.
    13941482
    13951483        INPUT:
    1396             other -- another order with the same ambient absolute
    1397                     number field.
     1484
     1485        - other -- another order with the same ambient absolute number field.
    13981486
    13991487        OUTPUT:
    1400             a rational number
     1488
     1489        a rational number
    14011490       
    1402         EXAMPLES:
     1491        EXAMPLES::
     1492
    14031493            sage: K.<a,b> = NumberField([x^3 + x + 3, x^2 + 1])
    14041494            sage: R1 = K.order([3*a, 2*b])
    14051495            sage: R2 = K.order([a, 4*b])
     
    14191509    Return True if each element of the list v of elements of a number
    14201510    field is integral.
    14211511
    1422     EXAMPLES:
     1512    EXAMPLES::
     1513
    14231514        sage: W.<sqrt5> = NumberField(x^2 - 5)
    14241515        sage: from sage.rings.number_field.order import each_is_integral
    14251516        sage: each_is_integral([sqrt5, 2, (1+sqrt5)/2])
     
    14371528                                        allow_subfield=False):
    14381529    """
    14391530    INPUT:
    1440         gens -- list of integral elements of an absolute order.
    1441         check_is_integral -- bool (default: True), whether to check
    1442                              that each generator is integral.
    1443         check_rank -- bool (default: True), whether to check that
    1444                       the ring generated by gens is of full rank.
    1445         is_maximal -- bool (or None); set if maximality of the generated order is known
    1446         allow_subfield -- bool (default: False), if True and the generators
    1447               do not generate an order, i.e., they generate a subring
    1448               of smaller rank, instead of raising an error, return
    1449               an order in a smaller number field.
     1531
     1532    - gens -- list of integral elements of an absolute order.
     1533    - check_is_integral -- bool (default: True), whether to check that each
     1534      generator is integral.
     1535    - check_rank -- bool (default: True), whether to check that the ring
     1536      generated by gens is of full rank.
     1537    - is_maximal -- bool (or None); set if maximality of the generated order is
     1538      known
     1539    - allow_subfield -- bool (default: False), if True and the generators do
     1540      not generate an order, i.e., they generate a subring of smaller rank,
     1541      instead of raising an error, return an order in a smaller number field.
    14501542       
    1451     EXAMPLES:
     1543    EXAMPLES::
     1544
    14521545        sage: K.<a> = NumberField(x^4 - 5)
    14531546        sage: K.order(a)
    14541547        Order in Number Field in a with defining polynomial x^4 - 5
    14551548       
    1456     We have to explicitly import this function, since typically
    1457     it is called with \code{K.order} as above.
     1549    We have to explicitly import this function, since typically it is called
     1550    with ``K.order`` as above.::
     1551
    14581552        sage: from sage.rings.number_field.order import absolute_order_from_ring_generators
    14591553        sage: absolute_order_from_ring_generators([a])
    14601554        Order in Number Field in a with defining polynomial x^4 - 5
    14611555        sage: absolute_order_from_ring_generators([3*a, 2, 6*a+1])
    14621556        Order in Number Field in a with defining polynomial x^4 - 5
    14631557
    1464     If one of the inputs is non-integral, it is an error.
     1558    If one of the inputs is non-integral, it is an error.::
     1559
    14651560        sage: absolute_order_from_ring_generators([a/2])
    14661561        Traceback (most recent call last):
    14671562        ...
    14681563        ValueError: each generator must be integral
    14691564
    14701565    If the gens do not generate an order, i.e., generate a ring of full
    1471     rank, then it is an error.
     1566    rank, then it is an error.::
     1567
    14721568        sage: absolute_order_from_ring_generators([a^2])
    14731569        Traceback (most recent call last):
    14741570        ...
     
    14761572
    14771573    Both checking for integrality and checking for full rank can be
    14781574    turned off in order to save time, though one can get nonsense as
    1479     illustrated below.
     1575    illustrated below.::
     1576
    14801577        sage: absolute_order_from_ring_generators([a/2], check_is_integral=False)
    14811578        Order in Number Field in a with defining polynomial x^4 - 5
    14821579        sage: absolute_order_from_ring_generators([a^2], check_rank=False)
     
    15001597              allow_subfield = False):
    15011598    """
    15021599    INPUT:
    1503         gens -- list of elements of an absolute number field
    1504                 that generates an order in that number field as a ZZ
    1505                 *module*.
    1506         check_integral -- check that each gen is integral
    1507         check_rank -- check that the gens span a module of the correct rank
    1508         check_is_ring -- check that the module is closed under multiplication
    1509                          (this is very expensive)
    1510         is_maximal -- bool (or None); set if maximality of the generated order is known                 
     1600
     1601    - gens -- list of elements of an absolute number field that generates an
     1602      order in that number field as a ZZ *module*.
     1603    - check_integral -- check that each gen is integral
     1604    - check_rank -- check that the gens span a module of the correct rank
     1605    - check_is_ring -- check that the module is closed under multiplication
     1606      (this is very expensive)
     1607    - is_maximal -- bool (or None); set if maximality of the generated order is known                 
    15111608
    15121609    OUTPUT:
    1513         an absolute order
     1610   
     1611    an absolute order
    15141612
    15151613    EXAMPLES:
    15161614    We have to explicitly import the function, since it isn't meant
    1517     for regular usage:
     1615    for regular usage::
     1616
    15181617        sage: from sage.rings.number_field.order import absolute_order_from_module_generators
    15191618
    15201619        sage: K.<a> = NumberField(x^4 - 5)
     
    15351634        Order in Number Field in a with defining polynomial x^4 - 5
    15361635
    15371636    We illustrate each check flag -- the output is the same but in case
    1538     the function would run ever so slightly faster:
     1637    the function would run ever so slightly faster::
     1638
    15391639        sage: absolute_order_from_module_generators(g,  check_is_ring=False)
    15401640        Order in Number Field in a with defining polynomial x^4 - 5
    15411641        sage: absolute_order_from_module_generators(g,  check_rank=False)
     
    15441644        Order in Number Field in a with defining polynomial x^4 - 5
    15451645
    15461646    Next we illustrate constructing "fake" orders to illustrate turning
    1547     off various check flags:
     1647    off various check flags::
     1648
    15481649        sage: k.<i> = NumberField(x^2 + 1)
    15491650        sage: R = absolute_order_from_module_generators([2, 2*i],  check_is_ring=False); R
    15501651        Order in Number Field in i with defining polynomial x^2 + 1
     
    15571658
    15581659    If the order contains a non-integral element, even if we don't check
    15591660    that, we'll find that the rank is wrong or that the order isn't closed
    1560     under multiplication:
     1661    under multiplication::
     1662
    15611663        sage: absolute_order_from_module_generators([1/2, i],  check_integral=False)
    15621664        Traceback (most recent call last):
    15631665        ...
     
    15671669        sage: R.basis()
    15681670        [1/2, i]
    15691671
    1570     We turn off all check flags and make a really messed up order.
     1672    We turn off all check flags and make a really messed up order.::
     1673
    15711674        sage: R = absolute_order_from_module_generators([1/2, i],  check_is_ring=False, check_integral=False, check_rank=False); R
    15721675        Order in Number Field in i with defining polynomial x^2 + 1
    15731676        sage: R.basis()
    15741677        [1/2, i]
    15751678
    1576     An order that lives in a subfield:
     1679    An order that lives in a subfield::
     1680
    15771681        sage: F.<alpha> = NumberField(x**4+3)
    15781682        sage: F.order([alpha**2], allow_subfield=True)
    15791683        Order in Number Field in alpha with defining polynomial x^4 + 3
     
    16331737                                        allow_subfield=False):
    16341738    """
    16351739    INPUT:
    1636         gens -- list of integral elements of an absolute order.
    1637         check_is_integral -- bool (default: True), whether to check
    1638                              that each generator is integral.
    1639         check_rank -- bool (default: True), whether to check that
    1640                       the ring generated by gens is of full rank.
    1641         is_maximal -- bool (or None); set if maximality of the generated order is known
     1740   
     1741    - gens -- list of integral elements of an absolute order.
     1742    - check_is_integral -- bool (default: True), whether to check that each
     1743      generator is integral.
     1744    - check_rank -- bool (default: True), whether to check that the ring
     1745      generated by gens is of full rank.
     1746    - is_maximal -- bool (or None); set if maximality of the generated order is
     1747      known
    16421748       
    16431749    EXAMPLES:
    16441750    We have to explicitly import this function, since it isn't meant
    1645     for regular usage:
     1751    for regular usage::
    16461752   
    16471753        sage: from sage.rings.number_field.order import relative_order_from_ring_generators
    16481754        sage: K.<i, a> = NumberField([x^2 + 1, x^2 - 17])
     
    16511757        Relative Order in Number Field in i with defining polynomial x^2 + 1 over its base field
    16521758
    16531759    Basis for the relative order, which is obtained by computing the algebra generated
    1654     by i and a.
     1760    by i and a.::
     1761
    16551762        sage: S.basis()
    16561763        [1, 7*i - 2*a, -a*i + 8, 25*i - 7*a]
    16571764    """
  • sage/rings/number_field/unit_group.py

    diff -r f77ae09d3d24 -r 0b6b4751a6ea sage/rings/number_field/unit_group.py
    a b  
    11"""
    2 The unit group of a number field.
     2Unit Groups of Number Fields
    33
    4 EXAMPLES:
     4EXAMPLES::
     5
    56    sage: x = polygen(QQ)
    67    sage: K.<a> = NumberField(x^4-8*x^2+36)
    78    sage: UK = UnitGroup(K); UK
    89    Unit group with structure C4 x Z of Number Field in a with defining polynomial x^4 - 8*x^2 + 36
    910
    10     # The first generator is a primitive root of unity in the field:
     11The first generator is a primitive root of unity in the field::
     12
    1113    sage: UK.gens() # random
    1214    [1/12*a^3 - 1/6*a, 1/24*a^3 + 1/4*a^2 - 1/12*a - 1]
    1315    sage: [u.multiplicative_order() for u in UK.gens()]
     
    1820    sage: UK.ngens()
    1921    2
    2022
    21     # Units in the field can be converted into elements of the unit
    22     # group represented as elements of an abstract multiplicative
    23     # group:
     23Units in the field can be converted into elements of the unit group represented
     24as elements of an abstract multiplicative group::
     25
    2426    sage: UK(1)
    2527    1
    2628    sage: UK(-1)
     
    3739    sage: UK.roots_of_unity()
    3840    [1/12*a^3 - 1/6*a, -1, -1/12*a^3 + 1/6*a, 1]
    3941   
    40     # exp and log functions provide maps between units as field
    41     # elements and exponent vectors with respect to the generators:
     42Exp and log functions provide maps between units as field elements and exponent
     43vectors with respect to the generators::
    4244
    4345    sage: u = UK.exp([13,10]); u # random
    4446    -41/8*a^3 - 55/4*a^2 + 41/4*a + 55
     
    5759    sage: UK.fundamental_units()
    5860    [a^3 + a^2 - 1, a - 1]   
    5961
    60     # A relative number field example:
     62A relative number field example::
     63
    6164    sage: L.<a, b> = NumberField([x^2 + x + 1, x^4 + 1])
    6265    sage: UL = L.unit_group(); UL
    6366    Unit group with structure C24 x Z x Z x Z of Number Field in a with defining polynomial x^2 + x + 1 over its base field
     
    9295    1]
    9396
    9497
    95     # A relative extension example, which worked thanks to the code review by F.W.Clarke:
     98A relative extension example, which worked thanks to the code review by F.W.Clarke::
     99
    96100    sage: PQ.<X> = QQ[]
    97101    sage: F.<a, b> = NumberField([X^2 - 2, X^2 - 3])
    98102    sage: PF.<Y> = F[]
     
    101105    Unit group with structure C2 x Z x Z x Z x Z x Z x Z x Z of Number Field in c with defining polynomial Y^2 + (-2*b - 3)*a - 2*b - 6 over its base field
    102106
    103107AUTHOR:
    104     -- John Cremona
     108
     109- John Cremona
    105110"""
    106111#*****************************************************************************
    107112#       Copyright (C) 2009 William Stein, John Cremona
     
    137142        Create a unit group of a number field.
    138143
    139144        INPUT:
    140             number_field - a number field
    141             proof - boolean (default True): proof flag
     145
     146        - number_field - a number field
     147        - proof - boolean (default True): proof flag
    142148
    143149        The proof flag is passed to pari via the pari_bnf() function
    144150        which computes the unit group.  See the documentation for the
    145151        number_field module.
    146152
    147         EXAMPLES:
     153        EXAMPLES::
     154
    148155            sage: x = polygen(QQ)
    149156            sage: K.<a> = NumberField(x^2-38)
    150157            sage: UK = K.unit_group(); UK
     
    203210        Returns the abstract group element corresponding to the unit u.
    204211
    205212        INPUT:
    206             u -- Any object from which an element of the unit group's
    207             number field K may be constructed; an error is raised if
    208             an element of K cannot be constructed from u, or if the
    209             element constructed is not a unit.
    210213
    211         EXAMPLES:
     214        - u -- Any object from which an element of the unit group's number
     215          field K may be constructed; an error is raised if an element of K
     216          cannot be constructed from u, or if the element constructed is not a
     217          unit.
     218
     219        EXAMPLES::
     220
    212221            sage: x = polygen(QQ)
    213222            sage: K.<a> = NumberField(x^2-38)
    214223            sage: UK = UnitGroup(K)
     
    257266        """
    258267        Return generators for the unit group, as a list.
    259268
    260         EXAMPLES:
     269        EXAMPLES::
     270
    261271            sage: x = polygen(QQ)
    262272            sage: K.<a> = NumberField(x^4 + 23)
    263273            sage: K.unit_group().gens() # random
     
    269279        """
    270280        Return the number of generators of the unit group.
    271281
    272         EXAMPLES:
     282        EXAMPLES::
     283
    273284            sage: x = polygen(QQ)
    274285            sage: U = NumberField(x^2 + x + 23899, 'a').unit_group(); U
    275286            Unit group with structure C2 of Number Field in a with defining polynomial x^2 + x + 23899
     
    282293        """
    283294        Return the rank of the unit group.
    284295
    285         EXAMPLES:
    286         sage: K.<z> = CyclotomicField(13)
    287         sage: UnitGroup(K).rank()
    288         5
     296        EXAMPLES::
     297
     298            sage: K.<z> = CyclotomicField(13)
     299            sage: UnitGroup(K).rank()
     300            5
    289301        """
    290302        return len(self.__gens)-1
    291303
     
    295307
    296308        NOTE: i=0 gives the torsion generator, i.e. a primitive root of unity.
    297309
    298         EXAMPLES:
     310        EXAMPLES::
     311
    299312            sage: K.<z> = CyclotomicField(13)
    300313            sage: UK = K.unit_group()
    301314            sage: UK.ngens()
     
    321334        """
    322335        Return string representation of this unit group.
    323336
    324         EXAMPLES:
     337        EXAMPLES::
     338
    325339            sage: x = polygen(QQ)
    326340            sage: U = UnitGroup(NumberField(x^3 - 2, 'a'))
    327341            sage: U
     
    337351        """
    338352        Return generators for the free part of the unit group, as a list.
    339353
    340         EXAMPLES:
     354        EXAMPLES::
     355
    341356            sage: x = polygen(QQ)
    342357            sage: K.<a> = NumberField(x^4 + 23)
    343358            sage: U = UnitGroup(K)
     
    350365        """
    351366        Return all the roots of unity in this unit group, primitive or not.
    352367       
    353         EXAMPLES:       
     368        EXAMPLES::
     369
    354370            sage: x = polygen(QQ)
    355371            sage: K.<b> = NumberField(x^2+1)
    356372            sage: U = UnitGroup(K)
     
    367383        """
    368384        Return a generator for the torsion part of the unit group.
    369385
    370         EXAMPLES:
     386        EXAMPLES::
     387
    371388            sage: x = polygen(QQ)
    372389            sage: K.<a> = NumberField(x^4 - x^2 + 4)
    373390            sage: U = UnitGroup(K)
     
    380397        """
    381398        Returns the order of the torsion part of the unit group.
    382399
    383         EXAMPLES:
     400        EXAMPLES::
     401
    384402            sage: x = polygen(QQ)
    385403            sage: K.<a> = NumberField(x^4 - x^2 + 4)
    386404            sage: U = UnitGroup(K)
     
    393411        """
    394412        Return one, or a list of all, primitive n-th root of unity in this unit group.
    395413
    396         EXAMPLES:       
     414        EXAMPLES::
     415
    397416            sage: x = polygen(QQ)
    398417            sage: K.<z> = NumberField(x^2 + 3)
    399418            sage: U = UnitGroup(K)
     
    458477        """
    459478        Return the number field associated with this unit group.
    460479       
    461         EXAMPLES:
     480        EXAMPLES::
     481
    462482            sage: x = polygen(QQ)
    463483            sage: U = UnitGroup(NumberField(x^2 + 23, 'w')); U
    464484            Unit group with structure C2 of Number Field in w with defining polynomial x^2 + 23
     
    473493        Return the exponents of the unit u with respect to group generators.
    474494
    475495        INPUT:
    476             u -- Any object from which an element of the unit group's
    477             number field K may be constructed; an error is raised if
    478             an element of K cannot be constructed from u, or if the
    479             element constructed is not a unit.
     496
     497        - u -- Any object from which an element of the unit group's number
     498          field K may be constructed; an error is raised if an element of K
     499          cannot be constructed from u, or if the element constructed is not a
     500          unit.
    480501
    481502        OUTPUT: a list of integers giving the exponents of u with
    482503        respect to the unit group's basis.
    483504       
    484         EXAMPLES:
     505        EXAMPLES::
     506
    485507            sage: x = polygen(QQ)
    486508            sage: K.<z> = CyclotomicField(13)
    487509            sage: UK = UnitGroup(K)
     
    505527        Return unit with given exponents with respect to group generators.
    506528
    507529        INPUT:
    508             u -- Any object from which an element of the unit group's
    509             number field K may be constructed; an error is raised if
    510             an element of K cannot be constructed from u, or if the
    511             element constructed is not a unit.
     530
     531        - u -- Any object from which an element of the unit group's number
     532          field K may be constructed; an error is raised if an element of K
     533          cannot be constructed from u, or if the element constructed is not a
     534          unit.
    512535
    513536        OUTPUT: a list of integers giving the exponents of u with
    514537        respect to the unit group's basis.
    515538       
    516         EXAMPLES:
     539        EXAMPLES::
     540
    517541            sage: x = polygen(QQ)
    518542            sage: K.<z> = CyclotomicField(13)
    519543            sage: UK = UnitGroup(K)