Ticket #6188: trac_6188_review.patch

File trac_6188_review.patch, 55.2 KB (added by cremona, 13 years ago)

Apply after previous

  • sage/rings/number_field/number_field.py

    # HG changeset patch
    # User John Cremona <john.cremona@gmail.com>
    # Date 1244151511 -3600
    # Node ID e9c8a156d9d3c9c316186deed452cd80b18ccbf7
    # Parent  0b6b4751a6eafc40481b322ad6110092b79d56e5
    [mq]: docrev
    
    diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/number_field.py
    a b  
    14351435
    14361436    def specified_complex_embedding(self):
    14371437        r"""
    1438         Returns the embedding of this field into the complex numbers has
     1438        Returns the embedding of this field into the complex numbers which has
    14391439        been specified.
    14401440       
    14411441        Fields created with the ``QuadraticField`` or
     
    39193919        """
    39203920        Return generators for the unit group modulo torsion.
    39213921       
     3922        INPUT:
     3923
     3924        - ``proof`` (bool, default True) flag passed to ``pari``.
     3925
     3926        .. note::
     3927
     3928            For more functionality see the unit_group() function.
     3929       
    39223930        ALGORITHM: Uses PARI's bnfunit command.
    39233931       
    3924         INPUTS: proof - default: True
    3925 
    3926         NOTE: For more functionality see the unit_group() function.
    3927        
    39283932        EXAMPLES::
    39293933       
    39303934            sage: x = QQ['x'].0
     
    39953999
    39964000        ALGORITHM: Uses PARI's bnfunit command.
    39974001
    3998         INPUTS: proof -- default: True
    3999 
    4000         NOTE: the group is cached.
     4002        INPUT:
     4003
     4004        - ``proof`` (bool, default True) flag passed to ``pari``.
     4005
     4006        .. note::
     4007
     4008           The group is cached.
    40014009       
    40024010        EXAMPLES::
    40034011
     
    63216329       
    63226330        If prec is 53 (the default), then the complex double field is used;
    63236331        otherwise the arbitrary precision (but slow) complex field is used.
     6332
    63246333        EXAMPLES::
    63256334       
    63266335            sage: C = CyclotomicField(4)
     
    67886797        return self.gen()
    67896798
    67906799class NumberField_quadratic(NumberField_absolute):
    6791     """
     6800    r"""
    67926801    Create a quadratic extension of the rational field.
    67936802   
    6794     The command QuadraticField(a) creates the field Q(sqrt(a)).
     6803    The command ``QuadraticField(a)`` creates the field `\QQ(\sqrt{a})`.
    67956804   
    67966805    EXAMPLES::
    67976806   
     
    69456954        field is negative, then the following warning from the PARI manual
    69466955        applies:
    69476956
    6948             IMPORTANT WARNING: For `D<0`, this function may give
    6949             incorrect results when the class group has a low exponent
    6950             (has many cyclic factors), because implementing Shank's
    6951             method in full generality slows it down immensely.
     6957        .. warning::
     6958
     6959            For `D<0`, this function may give incorrect results when
     6960            the class group has a low exponent (has many cyclic
     6961            factors), because implementing Shank's method in full
     6962            generality slows it down immensely.
    69526963       
    69536964        EXAMPLES::
    69546965       
     
    69636974       
    69646975        It is an open problem to *prove* that there are infinity many
    69656976        positive square-free `d` such that
    6966         `\QQ(\sqrt{d})` has class number `1`:n
     6977        `\QQ(\sqrt{d})` has class number `1`:
    69676978       
    69686979        ::
    69696980       
     
    72217232
    72227233
    72237234def refine_embedding(e, prec=None):
    7224     """
    7225     Given an embedding e: K->RR or CC, returns an equivalent embedding
    7226     with higher precision.
     7235    r"""
     7236    Given an embedding from a number field to either `\RR` or
     7237    `\CC`, returns an equivalent embedding with higher precision.
    72277238   
    72287239    INPUT:
    7229     
     7240   
    72307241   
    72317242    -  ``e`` - an embedding of a number field into either
    72327243       RR or CC (with some precision)
  • sage/rings/number_field/number_field_ideal.py

    diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/number_field_ideal.py
    a b  
    166166            is in the ideal.
    167167
    168168        AUTHOR: John Cremona  2008-10-31
    169             Uses linear algebra.  The change-of-basis matrix is
    170             cached.  Provides simpler implementations for
    171             _contains_(), is_integral() and smallest_integer().
     169
     170        ALGORITHM:
     171       
     172        Uses linear algebra.  The change-of-basis matrix is cached.
     173        Provides simpler implementations for ``_contains_()``,
     174        ``is_integral()`` and ``smallest_integer()``.
    172175
    173176        EXAMPLES::
    174177
     
    363366            return self.__pari_hnf
    364367
    365368    def basis(self):
    366         """
     369        r"""
    367370        Return an immutable sequence of elements of this ideal (note:
    368371        their parent is the number field) that form a basis for this
    369         ideal viewed as a ZZ-module.
     372        ideal viewed as a `\ZZ` -module.
    370373
    371374        OUTPUT:
    372375            basis -- an immutable sequence.
     
    397400        return self.__basis
    398401
    399402    def free_module(self):
    400         """
    401         Return the free ZZ-module contained in the vector space
     403        r"""
     404        Return the free `\ZZ`-module contained in the vector space
    402405        associated to the ambient number field, that corresponds
    403406        to this ideal.
    404407
     
    418421            [ 5  1  1  0  1  0]
    419422            [ 5  6  2  1  1  1]
    420423
    421         However, the actual ZZ-module is not at all random::
     424        However, the actual `\ZZ`-module is not at all random::
    422425
    423426            sage: A.basis_matrix().change_ring(ZZ).echelon_form()
    424427            [ 1  0  0  5  1  1]
     
    599602        return self.__elements_from_hnf(hnf)
    600603
    601604    def integral_split(self):
    602         """
    603         Return a tuple (I, d), where I is an integral ideal, and d is the
    604         smallest positive integer such that this ideal is equal to I/d.
     605        r"""
     606        Return a tuple `(I, d)`, where `I` is an integral ideal, and `d` is the
     607        smallest positive integer such that this ideal is equal to `I/d`.
    605608
    606609        EXAMPLES::
    607610
     
    913916   
    914917    def valuation(self, p):
    915918        r"""
    916         Return the valuation of this fractional ideal at the prime
     919        Return the valuation of self at ``p``.
     920
     921        INPUT:
     922
     923        - ``p`` -- a prime ideal `\mathfrak{p}` of this number field.
     924
     925        OUTPUT:
     926       
     927        (integer) The valuation of this fractional ideal at the prime
    917928        `\mathfrak{p}`.  If `\mathfrak{p}` is not prime, raise a
    918929        ValueError.
    919930
    920         INPUT:
    921             p -- a prime ideal of this number field.
    922 
    923         OUTPUT:
    924             integer
    925 
    926931        EXAMPLES::
    927932
    928933            sage: K.<a> = NumberField(x^5 + 2); K
     
    952957        return ZZ(nf.idealval(self.pari_hnf(), p._pari_prime))
    953958
    954959    def decomposition_group(self):
    955         """
    956         Return the decomposition group of self, as a subset of the automorphism
    957         group of the number field of self. Raises an error if the field isn't
    958         Galois. See the decomposition_group method of the GaloisGroup_v2 class
    959         for further examples and doctests.
     960        r"""
     961        Return the decomposition group of self, as a subset of the
     962        automorphism group of the number field of self. Raises an
     963        error if the field isn't Galois. See the decomposition_group
     964        method of the ``GaloisGroup_v2`` class for further examples
     965        and doctests.
    960966       
    961967        EXAMPLE::
    962968
     
    966972        return self.number_field().galois_group().decomposition_group(self)
    967973
    968974    def ramification_group(self, v):
    969         """
    970         Return the vth ramification group of self, i.e. the set of elements s
    971         of the Galois group of the number field of self (which we assume is Galois)
    972         such that s acts trivially modulo self^(v+1). See the
    973         ramification_group method of the GaloisGroup class for further examples
    974         and doctests.
     975        r"""
     976        Return the `v`'th ramification group of self, i.e. the set of
     977        elements `s` of the Galois group of the number field of self
     978        (which we assume is Galois) such that `s` acts trivially
     979        modulo the `(v+1)`'st power of self. See the
     980        ramification_group method of the ``GaloisGroup`` class for
     981        further examples and doctests.
    975982       
    976983        EXAMPLE::
    977984
     
    984991        return self.number_field().galois_group().ramification_group(self, v)
    985992
    986993    def inertia_group(self):
    987         """
     994        r"""
    988995        Return the inertia group of self, i.e. the set of elements s of the
    989996        Galois group of the number field of self (which we assume is Galois)
    990997        such that s acts trivially modulo self. This is the same as the 0th
    991998        ramification group of self. See the inertia_group method of the
    992         GaloisGroup_v2 class for further examples and doctests.
     999        ``GaloisGroup_v2`` class for further examples and doctests.
    9931000         
    9941001        EXAMPLE::
    9951002
     
    9991006        return self.ramification_group(0)
    10001007
    10011008    def artin_symbol(self):
    1002         """
    1003         Return the Artin symbol ( K / Q, self), where K is the number field of self.
    1004         This is the unique element s of the decomposition group of self such that
    1005         s(x) = x^p mod self where p is the residue characteristic of self.
    1006         (Here self should be prime and unramified.)
     1009        r"""
     1010        Return the Artin symbol `( K / \QQ, P)`, where `K` is the
     1011        number field of `P` =self.  This is the unique element `s` of
     1012        the decomposition group of `P` such that `s(x) = x^p \pmod{P}`
     1013        where `p` is the residue characteristic of `P`.  (Here `P`
     1014        (self) should be prime and unramified.)
    10071015
    1008         See the artin_symbol method of the GaloisGroup_v2 class for further
    1009         documentation and examples.
     1016        See the ``artin_symbol`` method of the ``GaloisGroup_v2``
     1017        class for further documentation and examples.
    10101018
    10111019        EXAMPLE::
    10121020
     
    10161024        return self.number_field().galois_group().artin_symbol(self)
    10171025
    10181026def basis_to_module(B, K):
    1019     """
    1020     Given a basis B of elements for a ZZ-submodule of a number field K, return
    1021     the corresponding ZZ-submodule.
     1027    r"""
     1028    Given a basis `B` of elements for a `\ZZ`-submodule of a number
     1029    field `K`, return the corresponding `\ZZ`-submodule.
    10221030
    10231031    EXAMPLES::
    10241032
     
    13701378          `I`, i.e. a list of elements in the ring of integers `R` representing
    13711379          the elements of `(R/I)^*`.
    13721380
    1373         METHOD: Use pari's ``idealstar`` to find the group structure and
     1381        ALGORITHM: Use pari's ``idealstar`` to find the group structure and
    13741382        generators of the multiplicative group modulo the ideal.
    13751383       
    13761384        EXAMPLES::
     
    15011509
    15021510    def denominator(self):
    15031511        r"""
    1504         Return the denominator ideal of this fractional ideal. Each fractional
    1505         ideal has a unique expression as `N/D` where N, D are coprime integral
    1506         ideals; the denominator is D.
     1512        Return the denominator ideal of this fractional ideal. Each
     1513        fractional ideal has a unique expression as `N/D` where `N`,
     1514        `D` are coprime integral ideals; the denominator is `D`.
    15071515
    15081516        EXAMPLES::
    15091517
     
    15291537        return self._denom_ideal
    15301538       
    15311539    def numerator(self):
    1532         """
     1540        r"""
    15331541        Return the numerator ideal of this fractional ideal.
    15341542
    1535         Each fractional ideal has a unique expression as N/D where N,
    1536         D are coprime integral ideals.  The numerator is N.
     1543        Each fractional ideal has a unique expression as `N/D` where `N`,
     1544        `D` are coprime integral ideals.  The numerator is `N`.
    15371545
    15381546        EXAMPLES::
    15391547
     
    15631571        Returns True if this ideal is coprime to the other, else False.
    15641572
    15651573        INPUT:
    1566            other -- another ideal of the same field, or generators of an ideal.
     1574
     1575        - ``other`` -- another ideal of the same field, or generators
     1576          of an ideal.
    15671577
    15681578        OUTPUT:
    1569            True if self and other are coprime, else False.
     1579       
     1580        True if self and other are coprime, else False.
    15701581
    1571         NOTE:       
     1582        .. note::
     1583       
    15721584           This function works for fractional ideals as well as
    15731585           integral ideals.
    15741586
     
    16581670        return k(l)
    16591671
    16601672    def small_residue(self, f):
    1661         """
    1662         Given an element f of the ambient number field, returns an
    1663         element g such that f - g belongs to the ideal self (which
    1664         must be integral), and g is small.
     1673        r"""
     1674        Given an element `f` of the ambient number field, returns an
     1675        element `g` such that `f - g` belongs to the ideal self (which
     1676        must be integral), and `g` is small.
    16651677
    16661678        .. note::
    16671679
     
    17361748
    17371749        INPUT:
    17381750
    1739         - flag -- when flag=2, it also computes the generators of the
    1740           group `(O_K/I)^*`, which takes more time. By default flag=1
    1741           (no generators are computed). In both cases the special pari
    1742           structure ``bid`` is computed as well.  If flag=0
    1743           (deprecated) it computes only the group structure of
    1744           `(O_K/I)^*` (with generators) and not the special ``bid``
    1745           structure.  OUTPUT: The finite abelian group `(O_K/I)^*`.
     1751        - ``flag`` (int default 1) -- when ``flag`` =2, it also
     1752          computes the generators of the group `(O_K/I)^*`, which
     1753          takes more time. By default ``flag`` =1 (no generators are
     1754          computed). In both cases the special pari structure ``bid``
     1755          is computed as well.  If ``flag`` =0 (deprecated) it computes
     1756          only the group structure of `(O_K/I)^*` (with generators)
     1757          and not the special ``bid`` structure.
     1758
     1759        OUTPUT:
     1760
     1761        The finite abelian group `(O_K/I)^*`.
    17461762
    17471763        .. note::
    17481764
     
    17891805        INPUT:
    17901806
    17911807        - ``x`` - a non-zero element of the number field of self,
    1792                   which must have valuation equal to 0 at all prime
    1793                   ideals in the support of the ideal self.
     1808          which must have valuation equal to 0 at all prime ideals in
     1809          the support of the ideal self.
    17941810
    17951811        OUTPUT:
    17961812
    17971813        - ``l`` - a list of integers `(x_i)` such that `0 \leq x_i < d_i` and
    1798           `x = \prod_i g_i^{x_i}` in `(R/I)^*`, where I = self, R = ring of
     1814          `x = \prod_i g_i^{x_i}` in `(R/I)^*`, where `I` = self, `R` = ring of
    17991815          integers of the field, and `g_i` are the generators of `(R/I)^*`, of
    18001816          orders `d_i` respectively, as given in the ``bid`` structure of
    18011817          the ideal self.
     
    18241840        return [ZZ(l) for l in k.pari_nf().ideallog(x._pari_(), self._pari_bid_(2))]
    18251841
    18261842    def element_1_mod(self, other):
    1827         """
    1828         Returns an element r in this ideal such that 1-r is in other
     1843        r"""
     1844        Returns an element `r` in this ideal such that `1-r` is in other
    18291845
    18301846        An error is raised if either ideal is not integral of if they
    18311847        are not coprime.
    18321848                     
    18331849        INPUT:
    1834             other -- another ideal of the same field, or generators of an ideal.
     1850
     1851        - ``other`` -- another ideal of the same field, or generators
     1852          of an ideal.
     1853
    18351854        OUTPUT:
    1836             r -- an element of the ideal self such that 1-r is in the ideal other
     1855       
     1856        An element `r` of the ideal self such that `1-r` is in the ideal other
    18371857
    18381858        AUTHOR: Maite Aranes
    18391859 
     
    19481968                                  for p,e in self.factor()]])
    19491969
    19501970    def prime_to_idealM_part(self, M):
    1951         """
    1952         Version for integral ideals of the prime_to_m_part function over ZZ.
    1953         Returns the largest divisor of self that is coprime to the ideal M.
     1971        r"""
     1972        Version for integral ideals of the ``prime_to_m_part`` function over `\ZZ`.
     1973        Returns the largest divisor of self that is coprime to the ideal ``M``.
    19541974
    19551975        INPUT:
    1956             M -- an integral ideal of the same field, or generators of an ideal
     1976       
     1977        - ``M`` -- an integral ideal of the same field, or generators of an ideal
    19571978
    19581979        OUTPUT:
    1959             An ideal which is the largest divisor of self that is coprime to M.
     1980       
     1981        An ideal which is the largest divisor of self that is coprime to `M`.
    19601982
    19611983        AUTHOR: Maite Aranes
    19621984
     
    22142236        return "Lifting map to %s from quotient of integers by %s"%(self.__OK, self.__I)
    22152237
    22162238def quotient_char_p(I, p):
    2217     """
    2218     Given an integral ideal I that contains a prime number p, compute
    2219     a vector space V = (OK mod p) / (I mod p), along with a
    2220     homomorphism OK --> V and a section V --> OK.
     2239    r"""
     2240    Given an integral ideal `I` that contains a prime number `p`, compute
     2241    a vector space `V = (O_K \mod p) / (I \mod p)`, along with a
     2242    homomorphism `O_K \to V` and a section `V \to O_K`.
    22212243
    22222244    EXAMPLES::
    22232245
  • sage/rings/number_field/number_field_ideal_rel.py

    diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/number_field_ideal_rel.py
    a b  
    1 """
     1r"""
    22Relative Number Field Ideals
    33
    44AUTHORS:
     
    5555        sage: i = K.ideal(38); i
    5656        Fractional ideal (38)
    5757       
    58     WARNING: Ideals in relative number fields are broken::
     58    .. warning::
     59
     60       Ideals in relative number fields are broken::
    5961
    6062        sage: K.<a0, a1> = NumberField([x^2 + 1, x^2 + 2]); K
    6163        Number Field in a0 with defining polynomial x^2 + 1 over its base field
     
    116118            return self.__pari_rhnf
    117119
    118120    def absolute_ideal(self):
    119         """
    120         If this is an ideal in the extension L/K, return the ideal with
    121         the same generators in the absolute field L/Q.
     121        r"""
     122        If this is an ideal in the extension `L/K`, return the ideal with
     123        the same generators in the absolute field `L/\QQ`.
    122124
    123125        EXAMPLES::
    124126
     
    127129            sage: L.<c> = K.extension(x^2 - b)
    128130            sage: F = L.absolute_field('a')
    129131
    130         Let's check an inert ideal first::
     132        An example of an inert ideal::
    131133
    132134            sage: P = F.factor(13)[0][0]; P
    133135            Fractional ideal (13)
     
    135137            sage: J.absolute_ideal()
    136138            Fractional ideal (13)
    137139
    138         Now how about a non-trivial ideal in L, but one that is actually
    139         principal in the subfield K::
     140        Now a non-trivial ideal in `L` that is principal in the
     141        subfield `K`::
    140142
    141143            sage: J = L.ideal(b); J
    142144            Fractional ideal (b)
     
    149151            sage: J.absolute_ideal().norm()
    150152            4
    151153
    152         Now an ideal not generated by an element of K::
     154        Now an ideal not generated by an element of `K`::
    153155
    154156            sage: J = L.ideal(c); J
    155157            Fractional ideal (c)
     
    310312        raise NotImplementedError, "For a fractional ideal in a relative number field you must use relative_norm or absolute_norm as appropriate"
    311313
    312314    def ideal_below(self):
    313         """
    314         Compute the ideal of K below this ideal of L.
     315        r"""
     316        Compute the ideal of `K` below this ideal of `L`.
    315317
    316318        EXAMPLES::
    317319
     
    437439        raise NotImplementedError
    438440
    439441    def integral_split(self):
    440         """
    441         Return a tuple (I, d), where I is an integral ideal, and d is the
    442         smallest positive integer such that this ideal is equal to I/d.
     442        r"""
     443        Return a tuple `(I, d)`, where `I` is an integral ideal, and `d` is the
     444        smallest positive integer such that this ideal is equal to `I/d`.
    443445
    444446        EXAMPLES::
    445447
     
    549551        raise ValueError, "the fractional ideal (= %s) is not prime"%self
    550552
    551553    def ramification_index(self):
    552         """
    553         For ideals in relative number fields ramification_index is
    554         deliberately not implemented in order to avoid ambiguity.  Either
    555         relative_ramification_index or absolute_ramification_index should
    556         be used instead.
     554        r"""
     555        For ideals in relative number fields, ``ramification_index``
     556        is deliberately not implemented in order to avoid ambiguity.
     557        Either ``relative_ramification_index`` or
     558        ``absolute_ramification_index`` should be used instead.
    557559        """
    558560        raise NotImplementedError, "For an ideal in a relative number field you must use relative_ramification_index or absolute_ramification_index as appropriate"
    559561
    560562    def residue_class_degree(self):
    561         """
     563        r"""
     564        Return the resifue class degree of this prime.
     565
    562566        EXAMPLES::
    563567
    564568            sage: PQ.<X> = QQ[]
     
    596600        return xmrange_iter(abs_residues.iter_list, lambda c: from_abs(abs_residues.typ(c)))
    597601
    598602    def element_1_mod(self, other):
    599         """
    600         Returns an element r in this ideal such that 1-r is in other.
     603        r"""
     604        Returns an element `r` in this ideal such that `1-r` is in other.
    601605
    602606        An error is raised if either ideal is not integral of if they
    603607        are not coprime.
    604608                     
    605609        INPUT:
    606610
    607         - other -- another ideal of the same field, or generators of an ideal.
     611        - ``other`` -- another ideal of the same field, or generators of an ideal.
    608612       
    609         OUTPUT: an element of the ideal self such that 1-r is in the ideal
    610         other.
     613        OUTPUT:
     614
     615        an element `r` of the ideal self such that `1-r` is in the
     616        ideal other.
    611617
    612618        EXAMPLES::
    613619
     
    655661
    656662    def valuation(self, p):
    657663        r"""
    658         Return the valuation of this fractional ideal at the prime
    659         `\mathfrak{p}`.  If `\mathfrak{p}` is not prime, raise a ValueError.
     664        Return the valuation of this fractional ideal at ``p``.
    660665
    661666        INPUT:
    662667       
    663         - p -- a prime ideal of this relative number field.
     668        - ``p`` -- a prime ideal `\mathfrak{p}` of this relative number field.
    664669
    665         OUTPUT: integer
     670        OUTPUT:
     671
     672        (integer) The valuation of this fractional ideal at the prime
     673        `\mathfrak{p}`.  If `\mathfrak{p}` is not prime, raise a
     674        ValueError.
     675
    666676
    667677        EXAMPLES::
    668678
  • sage/rings/number_field/number_field_rel.py

    diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/number_field_rel.py
    a b  
    11r"""
    22Relative Number Fields
    33
    4 AUTHORS::
     4AUTHORS:
    55
    66- William Stein (2004, 2005): initial version
    77- Steven Sivek (2006-05-12): added support for relative extensions
     
    151151# from sage.rings.number_field.number_field import is_CyclotomicField
    152152
    153153def is_RelativeNumberField(x):
    154     """
    155     Return True if x is a relative number field.
     154    r"""
     155    Return True if `x` is a relative number field.
    156156
    157157    EXAMPLES::
    158158
     
    171171
    172172class NumberField_relative(NumberField_generic):
    173173    """
     174    INPUT:
     175       
     176    - ``base`` -- the base field
     177    - ``polynomial`` -- must be defined in the ring `K[x]`, where `K` is
     178      the base field.
     179    - ``name`` -- variable name
     180    - ``latex_name`` -- latex variable name
     181    - ``names`` -- alternative to name
     182    - ``check`` -- whether to check irreducibility of polynomial.
     183
    174184    EXAMPLES::
    175185
    176186        sage: K.<a> = NumberField(x^3 - 2)
     
    183193        r"""
    184194        INPUT:
    185195       
    186         - base -- the base field
    187         - polynomial -- must be defined in the ring ``K['x']``, where K is
     196        - ``base`` -- the base field
     197        - ``polynomial`` -- must be defined in the ring `K[x]`, where `K` is
    188198          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.
     199        - ``name`` -- variable name
     200        - ``latex_name`` -- latex variable name
     201        - ``names`` -- alternative to name
     202        - ``check`` -- whether to check irreducibility of polynomial.
    193203
    194204        EXAMPLES::
    195205
     
    219229            Number Field in a1 with defining polynomial x^2 + 1
    220230
    221231        TESTS:
    222         Let's ensure that irreducibility testing is working::
     232
     233        Test that irreducibility testing is working::
    223234
    224235            sage: x = ZZ['x'].0
    225236            sage: K.<a, b> = NumberField([x^2 + 2, x^2 + 3])
     
    314325
    315326        INPUT:
    316327
    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.
     328        - ``names`` -- number of names should be at most the number of
     329          generators of self, i.e., the number of steps in the tower
     330          of relative fields.
    319331
    320         Also, ``K.structure()`` returns from_K and to_K, where
    321         from_K is an isomorphism from K to self and to_K is an
    322         isomorphism from self to K.
     332        Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where
     333        from_K is an isomorphism from `K` to self and ``to_K`` is an
     334        isomorphism from self to `K`.
    323335
    324336        EXAMPLES::
    325337
     
    372384        return L
    373385
    374386    def is_absolute(self):
    375         """
     387        r"""
     388        Returns False, since this is not an absolute field.
     389
    376390        EXAMPLES::
    377391
    378392            sage: K.<a,b> = NumberField([x^4 + 3, x^2 + 2]); K
     
    414428
    415429    def gen(self, n=0):
    416430        """
    417         Return the n'th generator of this relative number field.
     431        Return the `n`'th generator of this relative number field.
    418432
    419433        EXAMPLES::
    420434
     
    430444        return self.__gens[n]
    431445
    432446    def galois_closure(self, names=None):
    433         """
     447        r"""
    434448        Return the absolute number field `K` that is the Galois closure of this
    435449        relative number field.
    436450
     
    456470        return self.absolute_polynomial().degree()
    457471
    458472    def relative_degree(self):
    459         """
     473        r"""
     474        Returns the relative degree of this relative number field.
    460475
    461476        EXAMPLES::
    462477
     
    564579
    565580    def _latex_(self):
    566581        r"""
    567         Return a \LaTeX representation of the extension.
     582        Return a `\LaTeX` representation of the extension.
    568583
    569584        EXAMPLES::
    570585
     
    586601
    587602        INPUT:
    588603
    589         - x -- an element of some number field
     604        - ``x`` -- an element of some number field
    590605
    591606        EXAMPLES::
    592607
     
    605620        raise TypeError, "Cannot coerce element into this number field"
    606621   
    607622    def _coerce_non_number_field_element_in(self, x):
    608         """
    609         Coerce a non-number field element x into this number field.
     623        r"""
     624        Coerce the non-number field element `x` into this number field.
    610625
    611626        INPUT:
    612627
    613         - x -- a non number field element x, e.g., a list, integer, rational,
    614           or polynomial.
     628        - ``x`` -- a non number field element, e.g., a list,
     629          integer, rational, or polynomial.
    615630
    616631        EXAMPLES::
    617632
     
    645660            TypeError: <class 'sage.rings.polynomial.polynomial_element_generic.Polynomial_generic_dense_field'>
    646661
    647662        One can also coerce an element of the polynomial quotient ring
    648         that's isomorphic to the number field::
     663        that is isomorphic to the number field::
    649664
    650665            sage: K.<a> = NumberField(x^3 + 17)
    651666            sage: b = K.polynomial_quotient_ring().random_element()
     
    811826
    812827        There are situations for which one might imagine canonical
    813828        coercion could make sense (at least after fixing choices), but
    814         which aren't yet implemented::
     829        which are not yet implemented::
    815830
    816831            sage: K.<a> = QuadraticField(2)
    817832            sage: K.coerce(sqrt(2))
     
    825840            sage: type(K.coerce_map_from(QQ))
    826841            <type 'sage.structure.coerce_maps.DefaultConvertMap_unique'>
    827842           
    828         Make sure we still get our optimized morphisms for special fields:
     843        Make sure we still get our optimized morphisms for special fields::
     844       
    829845            sage: K.<a> = NumberField(polygen(QQ)^2-2)
    830846            sage: type(K.coerce_map_from(QQ))
    831847            <type 'sage.rings.number_field.number_field_element_quadratic.Q_to_quadratic_field_element'>
     
    848864
    849865    def _coerce_map_from_(self, R):
    850866        """
    851         Canonical implicit coercion of x into self.
     867        Canonical implicit coercion of ``R`` into self.
    852868
    853869        Elements of this field canonically coerce in, as does anything
    854870        that coerces into the base field of this field.
     
    875891           
    876892    def _rnfeltreltoabs(self, element, check=False):
    877893        r"""
    878         Return PARI's rnfeletreltoabs, but without requiring rnfinit().
     894        Return PARI's ``rnfeletreltoabs()``, but without requiring ``rnfinit()``.
    879895
    880896        TESTS::
    881897
     
    956972        return sage.rings.number_field.number_field_ideal_rel.NumberFieldFractionalIdeal_rel
    957973
    958974    def _pari_base_bnf(self, certify=False, units=True):
    959         """
     975        r"""
    960976        Return the PARI bnf (big number field) representation of the
    961         absolute base field in terms of the pari variable y, suitable
    962         for extension by the pari variable x.
     977        absolute base field in terms of the pari variable ``y``, suitable
     978        for extension by the pari variable ``x``.
    963979
    964980        All caching is done by the absolute base field.
    965981
    966982        INPUT:
    967983
    968         - proof -- bool (default: True) if True, certify correctness of
    969           calculations (not assuming GRH).
     984        - ``certify`` (bool, default True) -- if True, certify
     985          correctness of calculations (not assuming GRH).
    970986
    971987        EXAMPLES::
    972988
     
    983999
    9841000    @cached_method
    9851001    def _pari_base_nf(self):
    986         """
     1002        r"""
    9871003        Return the PARI number field representation of the absolute
    988         base field, in terms of the pari variable y, suitable for
    989         extension by the pari variable x.
     1004        base field, in terms of the pari variable ``y``, suitable for
     1005        extension by the pari variable ``x``.
    9901006
    9911007        In future, all caching will be done by the absolute base
    9921008        field, but for now we work around a PARI bug that makes
     
    10091025
    10101026    def is_galois(self):
    10111027        r"""
    1012         For a relative number field, is_galois() is deliberately not
     1028        For a relative number field, ``is_galois()`` is deliberately not
    10131029        implemented, since it is not clear whether this would mean "Galois over
    1014         QQ" or "Galois over the given base field". Use either
    1015         is_galois_absolute() or is_galois_relative() respectively.
     1030        `\QQ`" or "Galois over the given base field". Use either ``is_galois_absolute()`` or ``is_galois_relative()`` respectively.
    10161031
    10171032        EXAMPLES::
    10181033
     
    10261041
    10271042    def is_galois_relative(self):
    10281043        r"""
    1029         Return True if for this relative extension L/K, L is a Galois extension of K.
     1044        Return True if for this relative extension `L/K`, `L` is a
     1045        Galois extension of `K`.
    10301046
    10311047        EXAMPLE::
    10321048
     
    10391055
    10401056    def is_galois_absolute(self):
    10411057        r"""
    1042         Return True if for this relative extension L/K, L is a Galois extension of `\QQ`.
     1058        Return True if for this relative extension `L/K`, `L` is a Galois extension of `\QQ`.
    10431059       
    10441060        EXAMPLE::
    10451061
     
    10911107
    10921108    def absolute_vector_space(self):
    10931109        """
     1110        Return vector space over `\QQ` of self and isomorphisms from
     1111        the vector space to self and in the other direction.
     1112
    10941113        EXAMPLES::
    10951114
    10961115            sage: K.<a,b> = NumberField([x^3 + 3, x^3 + 2]); K
     
    11281147        return ans
    11291148
    11301149    def vector_space(self):
    1131         """
    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()``.
     1150        r"""
     1151        For a relative number field, ``vector_space()`` is
     1152        deliberately not implemented, so that a user cannot confuse
     1153        ``relative_vector_space()`` with ``absolute_vector_space()``.
    11351154        """
    11361155        raise NotImplementedError, "For a relative number field L you must use either L.relative_vector_space() or L.absolute_vector_space() as appropriate"
    11371156       
    11381157    def absolute_base_field(self):
    1139         """
     1158        r"""
    11401159        Return the base field of this relative extension, but viewed
    1141         as an absolute field over QQ.
     1160        as an absolute field over `\QQ`.
    11421161
    11431162        EXAMPLES::
    11441163
     
    12461265
    12471266    def pari_absolute_base_polynomial(self):
    12481267        r"""
    1249         Return the PARI polynomial defining the absolute base field, in y.
     1268        Return the PARI polynomial defining the absolute base field, in ``y``.
    12501269
    12511270        EXAMPLES::
    12521271
     
    13311350        return [from_abs(x) for x in abs.roots_of_unity()]
    13321351
    13331352    def absolute_generator(self):
    1334         """
    1335         Return the chosen generator over QQ for this relative number field.
     1353        r"""
     1354        Return the chosen generator over `\QQ` for this relative number field.
    13361355
    13371356        EXAMPLES::
    13381357
     
    13531372       
    13541373    def absolute_field(self, names):
    13551374        r"""
    1356         Return an absolute number field K that is isomorphic to this
    1357         field along with a field-theoretic bijection from self to K
    1358         and from K to self.
     1375        Return an absolute number field `K` that is isomorphic to this
     1376        field along with a field-theoretic bijection from self to `K`
     1377        and from `K` to self.
    13591378
    13601379        INPUT:
    13611380
    1362         - names -- string; name of generator of the absolute field
     1381        - ``names`` -- string; name of generator of the absolute field
    13631382           
    13641383        OUTPUT: an absolute number field
    13651384
    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.
     1385        Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where
     1386        ``from_K`` is an isomorphism from `K` to self and ``to_K`` is
     1387        an isomorphism from self to `K`.
    13681388
    13691389        EXAMPLES::
    13701390
     
    14661486        """
    14671487        Return the defining polynomial of this relative number field.
    14681488
    1469         This is exactly the same as ``self.relative_polynomal()``.
     1489        This is exactly the same as ``relative_polynomal()``.
    14701490
    14711491        EXAMPLES::
    14721492
     
    14811501
    14821502    def polynomial(self):
    14831503        """
    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.
     1504        For a relative number field, ``polynomial()`` is deliberately
     1505        not implemented.  Either ``relative_polynomial()`` or
     1506        ``absolute_polynomial()`` must be used.
    14871507        """
    14881508        raise NotImplementedError, "For a relative number field L you must use either L.relative_polynomial() or L.absolute_polynomial() as appropriate"
    14891509
     
    15241544        return self.base_field()
    15251545
    15261546    def embeddings(self, K):
    1527         """
     1547        r"""
    15281548        Compute all field embeddings of the relative number field self
    1529         into the field K (which need not even be a number field, e.g.,
    1530         it could be the complex numbers). This will return an
    1531         identical result when given K as input again.
     1549        into the field `K` (which need not even be a number field,
     1550        e.g., it could be the complex numbers). This will return an
     1551        identical result when given `K` as input again.
    15321552
    1533         If possible, the most natural embedding of K into self
     1553        If possible, the most natural embedding of self into `K`
    15341554        is put first in the list.
    15351555
    15361556        INPUT:
    15371557
    1538         - K -- a number field
     1558        - ``K`` -- a field
    15391559
    15401560        EXAMPLES::
    15411561
     
    16861706    def absolute_discriminant(self, v=None):
    16871707        r"""
    16881708        Return the absolute discriminant of this relative number field
    1689         or if v is specified, the determinant of the trace pairing
    1690         on the elements of the list v
     1709        or if ``v`` is specified, the determinant of the trace pairing
     1710        on the elements of the list ``v``
    16911711
    16921712        INPUT:
    16931713
    1694         - v (optional) -- list of element of this relative number field.
     1714        - ``v`` (optional) -- list of element of this relative number field.
    16951715
    1696         OUTPUT: Integer if v is omitted, and Rational otherwise.
     1716        OUTPUT: Integer if ``v`` is omitted, and Rational otherwise.
    16971717
    16981718        EXAMPLES::
    16991719
     
    17251745
    17261746        INPUT:
    17271747
    1728         - proof -- (default: False)
     1748        - ``proof`` -- (default: False)
    17291749
    17301750        EXAMPLES::
    17311751
     
    17661786
    17671787        INPUT:
    17681788
    1769         - gens -- list of elements of self; if no generators are given, just
     1789        - ``gens`` -- list of elements of self; if no generators are given, just
    17701790          returns the cardinality of this number field (oo) for consistency.
    1771         - check_is_integral -- bool (default: True), whether to check that each
     1791        - ``check_is_integral`` -- bool (default: True), whether to check that each
    17721792          generator is integral.
    1773         - check_rank -- bool (default: True), whether to check that the ring
     1793        - ``check_rank`` -- bool (default: True), whether to check that the ring
    17741794          generated by gens is of full rank.
    1775         - allow_subfield -- bool (default: False), if True and the generators
     1795        - ``allow_subfield`` -- bool (default: False), if True and the generators
    17761796          do not generate an order, i.e., they generate a subring of smaller
    17771797          rank, instead of raising an error, return an order in a smaller
    17781798          number field.
     
    17861806            sage: R = P.order([a,b,c]); R
    17871807            Relative Order in Number Field in sqrt2 with defining polynomial x^2 - 2 over its base field
    17881808
    1789         The base ring of an order in a relative extension is still ZZ.::
     1809        The base ring of an order in a relative extension is still `\ZZ`.:
    17901810
    17911811            sage: R.base_ring()
    17921812            Integer Ring
     
    18481868
    18491869        INPUT:
    18501870
    1851         - proof -- default: True
     1871        - ``proof`` -- default: True
    18521872
    18531873        EXAMPLES::
    18541874
     
    18981918        Given an element in self or an embedding of a subfield into self,
    18991919        return a relative number field `K` isomorphic to self that is relative
    19001920        over the absolute field `\QQ(\alpha)` or the domain of `\alpha`, along
    1901         with isomorphisms from `K` to self and from self to K.
     1921        with isomorphisms from `K` to self and from self to `K`.
    19021922
    19031923        INPUT:
    19041924
    1905         - alpha -- an element of self, or an embedding of a subfield into self
    1906         - names -- name of generator for output field K.
     1925        - ``alpha`` -- an element of self, or an embedding of a subfield into self
     1926        - ``names`` -- name of generator for output field `K`.
    19071927           
    1908         OUTPUT: K -- a relative number field
     1928        OUTPUT: `K` -- a relative number field
    19091929
    1910         Also, ``K.structure()`` returns from_K and to_K, where
    1911         from_K is an isomorphism from K to self and to_K is an isomorphism
    1912         from self to K.
     1930        Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where
     1931        ``from_K`` is an isomorphism from `K` to self and ``to_K`` is
     1932        an isomorphism from self to `K`.
    19131933
    19141934        EXAMPLES::
    19151935
     
    19251945            sage: L.base_field()
    19261946            Number Field in w with defining polynomial x^2 + 3
    19271947
    1928         Now suppose we have K below L below M::
     1948        Now suppose we have `K` below `L` below `M`::
    19291949
    19301950            sage: M = NumberField(x^8 + 2, 'a'); M
    19311951            Number Field in a with defining polynomial x^8 + 2
     
    19431963            sage: M_over_L_over_K.base_field() is L_over_K
    19441964            True
    19451965
    1946         Let's test relativizing a degree 6 field over its degree 2 and degree 3
     1966        Test relativizing a degree 6 field over its degree 2 and degree 3
    19471967        subfields, using both an explicit element::
    19481968
    19491969            sage: K.<a> = NumberField(x^6 + 2); K
  • sage/rings/number_field/order.py

    diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/order.py
    a b  
    66- William Stein and Robert Bradshaw (2007-09): initial version
    77
    88EXAMPLES:
     9
    910We define an absolute order::
    1011
    1112    sage: K.<a> = NumberField(x^2 + 1); O = K.order(2*a)
     
    4849
    4950
    5051def is_NumberFieldOrder(R):
    51     """
    52     Return True if R an order in a number field or R is the ring ZZ of integers.
     52    r"""
     53    Return True if R is either an order in a number field or is the ring `\ZZ` of integers.
    5354
    5455    EXAMPLES::
    5556
     
    6667    return isinstance(R, Order) or R == ZZ
    6768
    6869def EquationOrder(f, names):
    69     """
     70    r"""
    7071    Return the equation order generated by a root of the irreducible
    71     polynomial f or list of polynomials f (to construct a relative
     72    polynomial f or list of polynomials `f` (to construct a relative
    7273    equation order).
    7374
    7475    IMPORTANT: Note that the generators of the returned order need
    75     *not* be a root of f, since the generators of an order are -- in
    76     SAGE -- module generators.
     76    *not* be roots of `f`, since the generators of an order are -- in
     77    Sage -- module generators.
    7778   
    7879    EXAMPLES::
    7980
     
    209210
    210211    def __mul__(self, right):
    211212        """
    212         Create an ideal in this order using the notation Ok*gens
     213        Create an ideal in this order using the notation ``Ok*gens``
    213214       
    214215        EXAMPLES::
    215216
     
    230231   
    231232    def __rmul__(self, left):
    232233        """
    233         Create an ideal in this order using the notation gens*Ok.
     234        Create an ideal in this order using the notation ``gens*Ok``.
    234235
    235236        EXAMPLES::
    236237
     
    363364            return self.number_field().maximal_order()
    364365
    365366    def gen(self, i):
    366         """
    367         Return i-th module generator of this order.
     367        r"""
     368        Return `i`'th module generator of this order.
    368369
    369370        EXAMPLES::
    370371
     
    395396        """
    396397        Return a list of the module generators of this order.
    397398
    398         NOTE: For a (much smaller) list of ring generators use
    399         ``self.ring_generators()``.
     399        .. note::
     400
     401           For a (much smaller) list of ring generators use
     402           ``ring_generators()``.
    400403
    401404        EXAMPLES::
    402405
     
    421424        return self.absolute_degree()
    422425
    423426    def basis(self):  # this must be defined in derived class
    424         """
    425         Return a basis over ZZ of this order.
     427        r"""
     428        Return a basis over `\ZZ` of this order.
    426429
    427430        EXAMPLES::
    428431
     
    438441        r"""
    439442        Returns the coordinate vector of `x` with respect to this order.
    440443
    441         INPUT::
     444        INPUT:
    442445
    443         - `x` -- an element of the number field of this order.
     446        - ``x`` -- an element of the number field of this order.
    444447
    445448        OUTPUT:
    446449
     
    452455
    453456        AUTHOR: John Cremona  2008-11-15
    454457       
     458        ALGORITHM:
     459       
    455460        Uses linear algebra.  The change-of-basis matrix is
    456461        cached.  Provides simpler implementations for
    457         _contains_(), is_integral() and smallest_integer().
     462        ``_contains_()``, ``is_integral()`` and ``smallest_integer()``.
    458463
    459464        EXAMPLES::
    460465
     
    493498        return to_V(K(x))*M
    494499
    495500    def free_module(self):
    496         """
    497         Return the free ZZ-module contained in the vector space
     501        r"""
     502        Return the free `\ZZ`-module contained in the vector space
    498503        associated to the ambient number field, that corresponds
    499504        to this ideal.
    500505
     
    511516            [  0   0   1]
    512517
    513518        An example in a relative extension.  Notice that the module is
    514         a ZZ-module in the absolute_field associated to the relative
     519        a `\ZZ`-module in the absolute_field associated to the relative
    515520        field::
    516521
    517522            sage: K.<a,b> = NumberField([x^2 + 1, x^2 + 2])
     
    648653
    649654        INPUT:
    650655
    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.
     656        - ``prime`` -- a prime ideal of the maximal order in this number field.
     657        - ``name`` -- the name of the variable in the residue field
     658        - ``check`` -- whether or not to check the primality of prime.
    654659
    655660        OUTPUT:
    656661       
     
    707712        `\ZZ`-module, or the degree of the ambient number field that contains
    708713        this order.
    709714
    710         This is a synonym for ``self.degree()``.
     715        This is a synonym for ``degree()``.
    711716
    712717        EXAMPLES::
    713718
     
    720725        return self.degree()
    721726
    722727    def class_number(self, proof=None):
    723         """
     728        r"""
     729        Return the class number of this order.
     730       
    724731        EXAMPLES::
    725732
    726733            sage: ZZ[2^(1/3)].class_number()
     
    804811        r"""
    805812        Compare the order self to other.
    806813
    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.
     814        .. note::
     815
     816           This is a well defined way to compare any two objects, but
     817           it is not the partial inclusion ordering!.  Thus self <
     818           other being True does not necessarily mean that self is
     819           contained in other.  Use ``self.is_suborder(other)`` to
     820           determine inclusion.
    811821
    812822        EXAMPLES::
    813823
     
    841851        return cmp(self._module_rep, other._module_rep)
    842852
    843853    def absolute_degree(self):
    844         """
    845         Returns the absolute degree of this order, ie the degree of this order over ZZ.
     854        r"""
     855        Returns the absolute degree of this order, ie the degree of this order over `\ZZ`.
    846856
    847857        EXAMPLES::
    848858
     
    931941                raise ValueError, "the module must have full rank."
    932942       
    933943    def __call__(self, x):
    934         """
    935         Coerce x into this order.
     944        r"""
     945        Coerce ``x`` into this order.
    936946
    937947        EXAMPLES::
    938948
     
    10081018
    10091019        INPUT:
    10101020
    1011         - magma -- a magma interpreter
     1021        - ``magma`` -- a magma interpreter
    10121022
    10131023        OUTPUT:
    10141024
     
    10871097
    10881098        INPUT:
    10891099
    1090         - other -- another absolute order with the same ambient number field.
     1100        - ``other`` -- another absolute order with the same ambient number field.
    10911101
    10921102        OUTPUT:
    10931103
     
    11821192        return "%sOrder in %r" % ("Maximal " if self._is_maximal else "", self._K)
    11831193       
    11841194    def basis(self):
    1185         """
    1186         Return the basis over ZZ for this order.
     1195        r"""
     1196        Return the basis over `\ZZ` for this order.
    11871197
    11881198        EXAMPLES::
    11891199
     
    13191329
    13201330        INPUT:
    13211331       
    1322         - names -- string (default: 'z'); name of generator of absolute extension.
     1332        - ``names`` -- string (default: 'z'); name of generator of absolute extension.
    13231333
    1324         NOTE: There *is* a default variable name, since this absolute
    1325         order is frequently used for internal algorithms.
     1334        .. note::
     1335
     1336           There *is* a default variable name, since this absolute
     1337           order is frequently used for internal algorithms.
    13261338
    13271339        EXAMPLES::
    13281340
     
    13361348            sage: S.basis()
    13371349            [1, 5/12*z^3 + 1/6*z, 1/2*z^2, 1/2*z^3]
    13381350
    1339         We compute a relative order in alpha0, alpha1, then make the number field
    1340         that contains the absolute order be called gamma.::
     1351        We compute a relative order in alpha0, alpha1, then make the
     1352        number field that contains the absolute order be called
     1353        gamma.::
    13411354
    13421355            sage: R = EquationOrder( [x^2 + 2, x^2 - 3], 'alpha'); R
    13431356            Relative Order in Number Field in alpha0 with defining polynomial x^2 + 2 over its base field
     
    13561369        Return module basis for this relative order.  This is a list
    13571370        of elements that generate this order over the base order.
    13581371
    1359         WARNING: For now this basis is actually just a basis over ZZ.
     1372        .. warning::
     1373
     1374           For now this basis is actually just a basis over `\ZZ`.
    13601375
    13611376        EXAMPLES::
    13621377
     
    14821497
    14831498        INPUT:
    14841499
    1485         - other -- another order with the same ambient absolute number field.
     1500        - ``other`` -- another order with the same ambient absolute number field.
    14861501
    14871502        OUTPUT:
    14881503
     
    15061521
    15071522def each_is_integral(v):
    15081523    """
    1509     Return True if each element of the list v of elements of a number
     1524    Return True if each element of the list ``v`` of elements of a number
    15101525    field is integral.
    15111526
    15121527    EXAMPLES::
     
    15291544    """
    15301545    INPUT:
    15311546
    1532     - gens -- list of integral elements of an absolute order.
    1533     - check_is_integral -- bool (default: True), whether to check that each
     1547    - ``gens`` -- list of integral elements of an absolute order.
     1548    - ``check_is_integral`` -- bool (default: True), whether to check that each
    15341549      generator is integral.
    1535     - check_rank -- bool (default: True), whether to check that the ring
     1550    - ``check_rank`` -- bool (default: True), whether to check that the ring
    15361551      generated by gens is of full rank.
    1537     - is_maximal -- bool (or None); set if maximality of the generated order is
     1552    - ``is_maximal`` -- bool (or None); set if maximality of the generated order is
    15381553      known
    1539     - allow_subfield -- bool (default: False), if True and the generators do
     1554    - ``allow_subfield`` -- bool (default: False), if True and the generators do
    15401555      not generate an order, i.e., they generate a subring of smaller rank,
    15411556      instead of raising an error, return an order in a smaller number field.
    15421557       
     
    15981613    """
    15991614    INPUT:
    16001615
    1601     - gens -- list of elements of an absolute number field that generates an
     1616    - ``gens`` -- list of elements of an absolute number field that generates an
    16021617      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
     1618    - ``check_integral`` -- check that each gen is integral
     1619    - ``check_rank`` -- check that the gens span a module of the correct rank
     1620    - ``check_is_ring`` -- check that the module is closed under multiplication
    16061621      (this is very expensive)
    1607     - is_maximal -- bool (or None); set if maximality of the generated order is known                 
     1622    - ``is_maximal`` -- bool (or None); set if maximality of the generated order is known                 
    16081623
    16091624    OUTPUT:
    16101625   
     
    16691684        sage: R.basis()
    16701685        [1/2, i]
    16711686
    1672     We turn off all check flags and make a really messed up order.::
     1687    We turn off all check flags and make a really messed up order::
    16731688
    16741689        sage: R = absolute_order_from_module_generators([1/2, i],  check_is_ring=False, check_integral=False, check_rank=False); R
    16751690        Order in Number Field in i with defining polynomial x^2 + 1
     
    17381753    """
    17391754    INPUT:
    17401755   
    1741     - gens -- list of integral elements of an absolute order.
    1742     - check_is_integral -- bool (default: True), whether to check that each
     1756    - ``gens`` -- list of integral elements of an absolute order.
     1757    - ``check_is_integral`` -- bool (default: True), whether to check that each
    17431758      generator is integral.
    1744     - check_rank -- bool (default: True), whether to check that the ring
     1759    - ``check_rank`` -- bool (default: True), whether to check that the ring
    17451760      generated by gens is of full rank.
    1746     - is_maximal -- bool (or None); set if maximality of the generated order is
     1761    - ``is_maximal`` -- bool (or None); set if maximality of the generated order is
    17471762      known
    17481763       
    17491764    EXAMPLES:
     
    17571772        Relative Order in Number Field in i with defining polynomial x^2 + 1 over its base field
    17581773
    17591774    Basis for the relative order, which is obtained by computing the algebra generated
    1760     by i and a.::
     1775    by i and a::
    17611776
    17621777        sage: S.basis()
    17631778        [1, 7*i - 2*a, -a*i + 8, 25*i - 7*a]
  • sage/rings/number_field/unit_group.py

    diff -r 0b6b4751a6ea -r e9c8a156d9d3 sage/rings/number_field/unit_group.py
    a b  
    1 """
     1r"""
    22Unit Groups of Number Fields
    33
    44EXAMPLES::
     
    143143
    144144        INPUT:
    145145
    146         - number_field - a number field
    147         - proof - boolean (default True): proof flag
     146        - ``number_field`` - a number field
     147        - ``proof`` - boolean (default True): proof flag
    148148
    149         The proof flag is passed to pari via the pari_bnf() function
     149        The proof flag is passed to pari via the ``pari_bnf()`` function
    150150        which computes the unit group.  See the documentation for the
    151151        number_field module.
    152152
     
    211211
    212212        INPUT:
    213213
    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
     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`
    216216          cannot be constructed from u, or if the element constructed is not a
    217217          unit.
    218218
     
    255255
    256256    def _coerce_impl(self, x):
    257257        """
    258         Canonical coercion of x into this unit group.
     258        Canonical coercion of ``x`` into this unit group.
    259259
    260260        EXAMPLES:
    261261       
     
    303303
    304304    def gen(self, i=0):
    305305        """
    306         Return the i-th generator for this unit group.
     306        Return the `i`'th generator for this unit group.
    307307
    308         NOTE: i=0 gives the torsion generator, i.e. a primitive root of unity.
     308        .. note::
     309
     310           `i=0` gives the torsion generator, i.e. a primitive root of unity.
    309311
    310312        EXAMPLES::
    311313
     
    489491
    490492
    491493    def log(self, u):
    492         """
    493         Return the exponents of the unit u with respect to group generators.
     494        r"""
     495        Return the exponents of the unit ``u`` with respect to group generators.
    494496
    495497        INPUT:
    496498
    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        - ``u`` -- Any object from which an element of the unit group's number
     500          field `K` may be constructed; an error is raised if an element of `K`
    499501          cannot be constructed from u, or if the element constructed is not a
    500502          unit.
    501503
    502         OUTPUT: a list of integers giving the exponents of u with
     504        OUTPUT: a list of integers giving the exponents of ``u`` with
    503505        respect to the unit group's basis.
    504506       
    505507        EXAMPLES::
     
    523525        return self(u).list()
    524526
    525527    def exp(self, exponents):
    526         """
     528        r"""
    527529        Return unit with given exponents with respect to group generators.
    528530
    529531        INPUT:
    530532
    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.
     533        - ``u`` -- Any object from which an element of the unit
     534          group's number field `K` may be constructed; an error is
     535          raised if an element of `K` cannot be constructed from u, or
     536          if the element constructed is not a unit.
    535537
    536         OUTPUT: a list of integers giving the exponents of u with
     538        OUTPUT: a list of integers giving the exponents of ``u`` with
    537539        respect to the unit group's basis.
    538540       
    539541        EXAMPLES::