# HG changeset patch
# User John Cremona
# Date 1244151511 3600
# Node ID e9c8a156d9d3c9c316186deed452cd80b18ccbf7
# Parent 0b6b4751a6eafc40481b322ad6110092b79d56e5
[mq]: docrev
diff r 0b6b4751a6ea r e9c8a156d9d3 sage/rings/number_field/number_field.py
 a/sage/rings/number_field/number_field.py Tue Jun 02 18:22:42 2009 +0100
+++ b/sage/rings/number_field/number_field.py Thu Jun 04 22:38:31 2009 +0100
@@ 1435,7 +1435,7 @@
def specified_complex_embedding(self):
r"""
 Returns the embedding of this field into the complex numbers has
+ Returns the embedding of this field into the complex numbers which has
been specified.
Fields created with the ``QuadraticField`` or
@@ 3919,12 +3919,16 @@
"""
Return generators for the unit group modulo torsion.
+ INPUT:
+
+  ``proof`` (bool, default True) flag passed to ``pari``.
+
+ .. note::
+
+ For more functionality see the unit_group() function.
+
ALGORITHM: Uses PARI's bnfunit command.
 INPUTS: proof  default: True

 NOTE: For more functionality see the unit_group() function.

EXAMPLES::
sage: x = QQ['x'].0
@@ 3995,9 +3999,13 @@
ALGORITHM: Uses PARI's bnfunit command.
 INPUTS: proof  default: True

 NOTE: the group is cached.
+ INPUT:
+
+  ``proof`` (bool, default True) flag passed to ``pari``.
+
+ .. note::
+
+ The group is cached.
EXAMPLES::
@@ 6321,6 +6329,7 @@
If prec is 53 (the default), then the complex double field is used;
otherwise the arbitrary precision (but slow) complex field is used.
+
EXAMPLES::
sage: C = CyclotomicField(4)
@@ 6788,10 +6797,10 @@
return self.gen()
class NumberField_quadratic(NumberField_absolute):
 """
+ r"""
Create a quadratic extension of the rational field.
 The command QuadraticField(a) creates the field Q(sqrt(a)).
+ The command ``QuadraticField(a)`` creates the field `\QQ(\sqrt{a})`.
EXAMPLES::
@@ 6945,10 +6954,12 @@
field is negative, then the following warning from the PARI manual
applies:
 IMPORTANT WARNING: For `D<0`, this function may give
 incorrect results when the class group has a low exponent
 (has many cyclic factors), because implementing Shank's
 method in full generality slows it down immensely.
+ .. warning::
+
+ For `D<0`, this function may give incorrect results when
+ the class group has a low exponent (has many cyclic
+ factors), because implementing Shank's method in full
+ generality slows it down immensely.
EXAMPLES::
@@ 6963,7 +6974,7 @@
It is an open problem to *prove* that there are infinity many
positive squarefree `d` such that
 `\QQ(\sqrt{d})` has class number `1`:n
+ `\QQ(\sqrt{d})` has class number `1`:
::
@@ 7221,12 +7232,12 @@
def refine_embedding(e, prec=None):
 """
 Given an embedding e: K>RR or CC, returns an equivalent embedding
 with higher precision.
+ r"""
+ Given an embedding from a number field to either `\RR` or
+ `\CC`, returns an equivalent embedding with higher precision.
INPUT:

+
 ``e``  an embedding of a number field into either
RR or CC (with some precision)
diff r 0b6b4751a6ea r e9c8a156d9d3 sage/rings/number_field/number_field_ideal.py
 a/sage/rings/number_field/number_field_ideal.py Tue Jun 02 18:22:42 2009 +0100
+++ b/sage/rings/number_field/number_field_ideal.py Thu Jun 04 22:38:31 2009 +0100
@@ 166,9 +166,12 @@
is in the ideal.
AUTHOR: John Cremona 20081031
 Uses linear algebra. The changeofbasis matrix is
 cached. Provides simpler implementations for
 _contains_(), is_integral() and smallest_integer().
+
+ ALGORITHM:
+
+ Uses linear algebra. The changeofbasis matrix is cached.
+ Provides simpler implementations for ``_contains_()``,
+ ``is_integral()`` and ``smallest_integer()``.
EXAMPLES::
@@ 363,10 +366,10 @@
return self.__pari_hnf
def basis(self):
 """
+ r"""
Return an immutable sequence of elements of this ideal (note:
their parent is the number field) that form a basis for this
 ideal viewed as a ZZmodule.
+ ideal viewed as a `\ZZ` module.
OUTPUT:
basis  an immutable sequence.
@@ 397,8 +400,8 @@
return self.__basis
def free_module(self):
 """
 Return the free ZZmodule contained in the vector space
+ r"""
+ Return the free `\ZZ`module contained in the vector space
associated to the ambient number field, that corresponds
to this ideal.
@@ 418,7 +421,7 @@
[ 5 1 1 0 1 0]
[ 5 6 2 1 1 1]
 However, the actual ZZmodule is not at all random::
+ However, the actual `\ZZ`module is not at all random::
sage: A.basis_matrix().change_ring(ZZ).echelon_form()
[ 1 0 0 5 1 1]
@@ 599,9 +602,9 @@
return self.__elements_from_hnf(hnf)
def integral_split(self):
 """
 Return a tuple (I, d), where I is an integral ideal, and d is the
 smallest positive integer such that this ideal is equal to I/d.
+ r"""
+ Return a tuple `(I, d)`, where `I` is an integral ideal, and `d` is the
+ smallest positive integer such that this ideal is equal to `I/d`.
EXAMPLES::
@@ 913,16 +916,18 @@
def valuation(self, p):
r"""
 Return the valuation of this fractional ideal at the prime
+ Return the valuation of self at ``p``.
+
+ INPUT:
+
+  ``p``  a prime ideal `\mathfrak{p}` of this number field.
+
+ OUTPUT:
+
+ (integer) The valuation of this fractional ideal at the prime
`\mathfrak{p}`. If `\mathfrak{p}` is not prime, raise a
ValueError.
 INPUT:
 p  a prime ideal of this number field.

 OUTPUT:
 integer

EXAMPLES::
sage: K. = NumberField(x^5 + 2); K
@@ 952,11 +957,12 @@
return ZZ(nf.idealval(self.pari_hnf(), p._pari_prime))
def decomposition_group(self):
 """
 Return the decomposition group of self, as a subset of the automorphism
 group of the number field of self. Raises an error if the field isn't
 Galois. See the decomposition_group method of the GaloisGroup_v2 class
 for further examples and doctests.
+ r"""
+ Return the decomposition group of self, as a subset of the
+ automorphism group of the number field of self. Raises an
+ error if the field isn't Galois. See the decomposition_group
+ method of the ``GaloisGroup_v2`` class for further examples
+ and doctests.
EXAMPLE::
@@ 966,12 +972,13 @@
return self.number_field().galois_group().decomposition_group(self)
def ramification_group(self, v):
 """
 Return the vth ramification group of self, i.e. the set of elements s
 of the Galois group of the number field of self (which we assume is Galois)
 such that s acts trivially modulo self^(v+1). See the
 ramification_group method of the GaloisGroup class for further examples
 and doctests.
+ r"""
+ Return the `v`'th ramification group of self, i.e. the set of
+ elements `s` of the Galois group of the number field of self
+ (which we assume is Galois) such that `s` acts trivially
+ modulo the `(v+1)`'st power of self. See the
+ ramification_group method of the ``GaloisGroup`` class for
+ further examples and doctests.
EXAMPLE::
@@ 984,12 +991,12 @@
return self.number_field().galois_group().ramification_group(self, v)
def inertia_group(self):
 """
+ r"""
Return the inertia group of self, i.e. the set of elements s of the
Galois group of the number field of self (which we assume is Galois)
such that s acts trivially modulo self. This is the same as the 0th
ramification group of self. See the inertia_group method of the
 GaloisGroup_v2 class for further examples and doctests.
+ ``GaloisGroup_v2`` class for further examples and doctests.
EXAMPLE::
@@ 999,14 +1006,15 @@
return self.ramification_group(0)
def artin_symbol(self):
 """
 Return the Artin symbol ( K / Q, self), where K is the number field of self.
 This is the unique element s of the decomposition group of self such that
 s(x) = x^p mod self where p is the residue characteristic of self.
 (Here self should be prime and unramified.)
+ r"""
+ Return the Artin symbol `( K / \QQ, P)`, where `K` is the
+ number field of `P` =self. This is the unique element `s` of
+ the decomposition group of `P` such that `s(x) = x^p \pmod{P}`
+ where `p` is the residue characteristic of `P`. (Here `P`
+ (self) should be prime and unramified.)
 See the artin_symbol method of the GaloisGroup_v2 class for further
 documentation and examples.
+ See the ``artin_symbol`` method of the ``GaloisGroup_v2``
+ class for further documentation and examples.
EXAMPLE::
@@ 1016,9 +1024,9 @@
return self.number_field().galois_group().artin_symbol(self)
def basis_to_module(B, K):
 """
 Given a basis B of elements for a ZZsubmodule of a number field K, return
 the corresponding ZZsubmodule.
+ r"""
+ Given a basis `B` of elements for a `\ZZ`submodule of a number
+ field `K`, return the corresponding `\ZZ`submodule.
EXAMPLES::
@@ 1370,7 +1378,7 @@
`I`, i.e. a list of elements in the ring of integers `R` representing
the elements of `(R/I)^*`.
 METHOD: Use pari's ``idealstar`` to find the group structure and
+ ALGORITHM: Use pari's ``idealstar`` to find the group structure and
generators of the multiplicative group modulo the ideal.
EXAMPLES::
@@ 1501,9 +1509,9 @@
def denominator(self):
r"""
 Return the denominator ideal of this fractional ideal. Each fractional
 ideal has a unique expression as `N/D` where N, D are coprime integral
 ideals; the denominator is D.
+ Return the denominator ideal of this fractional ideal. Each
+ fractional ideal has a unique expression as `N/D` where `N`,
+ `D` are coprime integral ideals; the denominator is `D`.
EXAMPLES::
@@ 1529,11 +1537,11 @@
return self._denom_ideal
def numerator(self):
 """
+ r"""
Return the numerator ideal of this fractional ideal.
 Each fractional ideal has a unique expression as N/D where N,
 D are coprime integral ideals. The numerator is N.
+ Each fractional ideal has a unique expression as `N/D` where `N`,
+ `D` are coprime integral ideals. The numerator is `N`.
EXAMPLES::
@@ 1563,12 +1571,16 @@
Returns True if this ideal is coprime to the other, else False.
INPUT:
 other  another ideal of the same field, or generators of an ideal.
+
+  ``other``  another ideal of the same field, or generators
+ of an ideal.
OUTPUT:
 True if self and other are coprime, else False.
+
+ True if self and other are coprime, else False.
 NOTE:
+ .. note::
+
This function works for fractional ideals as well as
integral ideals.
@@ 1658,10 +1670,10 @@
return k(l)
def small_residue(self, f):
 """
 Given an element f of the ambient number field, returns an
 element g such that f  g belongs to the ideal self (which
 must be integral), and g is small.
+ r"""
+ Given an element `f` of the ambient number field, returns an
+ element `g` such that `f  g` belongs to the ideal self (which
+ must be integral), and `g` is small.
.. note::
@@ 1736,13 +1748,17 @@
INPUT:
  flag  when flag=2, it also computes the generators of the
 group `(O_K/I)^*`, which takes more time. By default flag=1
 (no generators are computed). In both cases the special pari
 structure ``bid`` is computed as well. If flag=0
 (deprecated) it computes only the group structure of
 `(O_K/I)^*` (with generators) and not the special ``bid``
 structure. OUTPUT: The finite abelian group `(O_K/I)^*`.
+  ``flag`` (int default 1)  when ``flag`` =2, it also
+ computes the generators of the group `(O_K/I)^*`, which
+ takes more time. By default ``flag`` =1 (no generators are
+ computed). In both cases the special pari structure ``bid``
+ is computed as well. If ``flag`` =0 (deprecated) it computes
+ only the group structure of `(O_K/I)^*` (with generators)
+ and not the special ``bid`` structure.
+
+ OUTPUT:
+
+ The finite abelian group `(O_K/I)^*`.
.. note::
@@ 1789,13 +1805,13 @@
INPUT:
 ``x``  a nonzero element of the number field of self,
 which must have valuation equal to 0 at all prime
 ideals in the support of the ideal self.
+ which must have valuation equal to 0 at all prime ideals in
+ the support of the ideal self.
OUTPUT:
 ``l``  a list of integers `(x_i)` such that `0 \leq x_i < d_i` and
 `x = \prod_i g_i^{x_i}` in `(R/I)^*`, where I = self, R = ring of
+ `x = \prod_i g_i^{x_i}` in `(R/I)^*`, where `I` = self, `R` = ring of
integers of the field, and `g_i` are the generators of `(R/I)^*`, of
orders `d_i` respectively, as given in the ``bid`` structure of
the ideal self.
@@ 1824,16 +1840,20 @@
return [ZZ(l) for l in k.pari_nf().ideallog(x._pari_(), self._pari_bid_(2))]
def element_1_mod(self, other):
 """
 Returns an element r in this ideal such that 1r is in other
+ r"""
+ Returns an element `r` in this ideal such that `1r` is in other
An error is raised if either ideal is not integral of if they
are not coprime.
INPUT:
 other  another ideal of the same field, or generators of an ideal.
+
+  ``other``  another ideal of the same field, or generators
+ of an ideal.
+
OUTPUT:
 r  an element of the ideal self such that 1r is in the ideal other
+
+ An element `r` of the ideal self such that `1r` is in the ideal other
AUTHOR: Maite Aranes
@@ 1948,15 +1968,17 @@
for p,e in self.factor()]])
def prime_to_idealM_part(self, M):
 """
 Version for integral ideals of the prime_to_m_part function over ZZ.
 Returns the largest divisor of self that is coprime to the ideal M.
+ r"""
+ Version for integral ideals of the ``prime_to_m_part`` function over `\ZZ`.
+ Returns the largest divisor of self that is coprime to the ideal ``M``.
INPUT:
 M  an integral ideal of the same field, or generators of an ideal
+
+  ``M``  an integral ideal of the same field, or generators of an ideal
OUTPUT:
 An ideal which is the largest divisor of self that is coprime to M.
+
+ An ideal which is the largest divisor of self that is coprime to `M`.
AUTHOR: Maite Aranes
@@ 2214,10 +2236,10 @@
return "Lifting map to %s from quotient of integers by %s"%(self.__OK, self.__I)
def quotient_char_p(I, p):
 """
 Given an integral ideal I that contains a prime number p, compute
 a vector space V = (OK mod p) / (I mod p), along with a
 homomorphism OK > V and a section V > OK.
+ r"""
+ Given an integral ideal `I` that contains a prime number `p`, compute
+ a vector space `V = (O_K \mod p) / (I \mod p)`, along with a
+ homomorphism `O_K \to V` and a section `V \to O_K`.
EXAMPLES::
diff r 0b6b4751a6ea r e9c8a156d9d3 sage/rings/number_field/number_field_ideal_rel.py
 a/sage/rings/number_field/number_field_ideal_rel.py Tue Jun 02 18:22:42 2009 +0100
+++ b/sage/rings/number_field/number_field_ideal_rel.py Thu Jun 04 22:38:31 2009 +0100
@@ 1,4 +1,4 @@
"""
+r"""
Relative Number Field Ideals
AUTHORS:
@@ 55,7 +55,9 @@
sage: i = K.ideal(38); i
Fractional ideal (38)
 WARNING: Ideals in relative number fields are broken::
+ .. warning::
+
+ Ideals in relative number fields are broken::
sage: K. = NumberField([x^2 + 1, x^2 + 2]); K
Number Field in a0 with defining polynomial x^2 + 1 over its base field
@@ 116,9 +118,9 @@
return self.__pari_rhnf
def absolute_ideal(self):
 """
 If this is an ideal in the extension L/K, return the ideal with
 the same generators in the absolute field L/Q.
+ r"""
+ If this is an ideal in the extension `L/K`, return the ideal with
+ the same generators in the absolute field `L/\QQ`.
EXAMPLES::
@@ 127,7 +129,7 @@
sage: L. = K.extension(x^2  b)
sage: F = L.absolute_field('a')
 Let's check an inert ideal first::
+ An example of an inert ideal::
sage: P = F.factor(13)[0][0]; P
Fractional ideal (13)
@@ 135,8 +137,8 @@
sage: J.absolute_ideal()
Fractional ideal (13)
 Now how about a nontrivial ideal in L, but one that is actually
 principal in the subfield K::
+ Now a nontrivial ideal in `L` that is principal in the
+ subfield `K`::
sage: J = L.ideal(b); J
Fractional ideal (b)
@@ 149,7 +151,7 @@
sage: J.absolute_ideal().norm()
4
 Now an ideal not generated by an element of K::
+ Now an ideal not generated by an element of `K`::
sage: J = L.ideal(c); J
Fractional ideal (c)
@@ 310,8 +312,8 @@
raise NotImplementedError, "For a fractional ideal in a relative number field you must use relative_norm or absolute_norm as appropriate"
def ideal_below(self):
 """
 Compute the ideal of K below this ideal of L.
+ r"""
+ Compute the ideal of `K` below this ideal of `L`.
EXAMPLES::
@@ 437,9 +439,9 @@
raise NotImplementedError
def integral_split(self):
 """
 Return a tuple (I, d), where I is an integral ideal, and d is the
 smallest positive integer such that this ideal is equal to I/d.
+ r"""
+ Return a tuple `(I, d)`, where `I` is an integral ideal, and `d` is the
+ smallest positive integer such that this ideal is equal to `I/d`.
EXAMPLES::
@@ 549,16 +551,18 @@
raise ValueError, "the fractional ideal (= %s) is not prime"%self
def ramification_index(self):
 """
 For ideals in relative number fields ramification_index is
 deliberately not implemented in order to avoid ambiguity. Either
 relative_ramification_index or absolute_ramification_index should
 be used instead.
+ r"""
+ For ideals in relative number fields, ``ramification_index``
+ is deliberately not implemented in order to avoid ambiguity.
+ Either ``relative_ramification_index`` or
+ ``absolute_ramification_index`` should be used instead.
"""
raise NotImplementedError, "For an ideal in a relative number field you must use relative_ramification_index or absolute_ramification_index as appropriate"
def residue_class_degree(self):
 """
+ r"""
+ Return the resifue class degree of this prime.
+
EXAMPLES::
sage: PQ. = QQ[]
@@ 596,18 +600,20 @@
return xmrange_iter(abs_residues.iter_list, lambda c: from_abs(abs_residues.typ(c)))
def element_1_mod(self, other):
 """
 Returns an element r in this ideal such that 1r is in other.
+ r"""
+ Returns an element `r` in this ideal such that `1r` is in other.
An error is raised if either ideal is not integral of if they
are not coprime.
INPUT:
  other  another ideal of the same field, or generators of an ideal.
+  ``other``  another ideal of the same field, or generators of an ideal.
 OUTPUT: an element of the ideal self such that 1r is in the ideal
 other.
+ OUTPUT:
+
+ an element `r` of the ideal self such that `1r` is in the
+ ideal other.
EXAMPLES::
@@ 655,14 +661,18 @@
def valuation(self, p):
r"""
 Return the valuation of this fractional ideal at the prime
 `\mathfrak{p}`. If `\mathfrak{p}` is not prime, raise a ValueError.
+ Return the valuation of this fractional ideal at ``p``.
INPUT:
  p  a prime ideal of this relative number field.
+  ``p``  a prime ideal `\mathfrak{p}` of this relative number field.
 OUTPUT: integer
+ OUTPUT:
+
+ (integer) The valuation of this fractional ideal at the prime
+ `\mathfrak{p}`. If `\mathfrak{p}` is not prime, raise a
+ ValueError.
+
EXAMPLES::
diff r 0b6b4751a6ea r e9c8a156d9d3 sage/rings/number_field/number_field_rel.py
 a/sage/rings/number_field/number_field_rel.py Tue Jun 02 18:22:42 2009 +0100
+++ b/sage/rings/number_field/number_field_rel.py Thu Jun 04 22:38:31 2009 +0100
@@ 1,7 +1,7 @@
r"""
Relative Number Fields
AUTHORS::
+AUTHORS:
 William Stein (2004, 2005): initial version
 Steven Sivek (20060512): added support for relative extensions
@@ 151,8 +151,8 @@
# from sage.rings.number_field.number_field import is_CyclotomicField
def is_RelativeNumberField(x):
 """
 Return True if x is a relative number field.
+ r"""
+ Return True if `x` is a relative number field.
EXAMPLES::
@@ 171,6 +171,16 @@
class NumberField_relative(NumberField_generic):
"""
+ INPUT:
+
+  ``base``  the base field
+  ``polynomial``  must be defined in the ring `K[x]`, where `K` is
+ the base field.
+  ``name``  variable name
+  ``latex_name``  latex variable name
+  ``names``  alternative to name
+  ``check``  whether to check irreducibility of polynomial.
+
EXAMPLES::
sage: K. = NumberField(x^3  2)
@@ 183,13 +193,13 @@
r"""
INPUT:
  base  the base field
  polynomial  must be defined in the ring ``K['x']``, where K is
+  ``base``  the base field
+  ``polynomial``  must be defined in the ring `K[x]`, where `K` is
the base field.
  name  variable name
  latex_name  latex variable name
  names  alternative to name
  check  whether to check irreducibility of polynomial.
+  ``name``  variable name
+  ``latex_name``  latex variable name
+  ``names``  alternative to name
+  ``check``  whether to check irreducibility of polynomial.
EXAMPLES::
@@ 219,7 +229,8 @@
Number Field in a1 with defining polynomial x^2 + 1
TESTS:
 Let's ensure that irreducibility testing is working::
+
+ Test that irreducibility testing is working::
sage: x = ZZ['x'].0
sage: K. = NumberField([x^2 + 2, x^2 + 3])
@@ 314,12 +325,13 @@
INPUT:
  names  number of names should be at most the number of generators
 of self, i.e., the number of steps in the tower of relative fields.
+  ``names``  number of names should be at most the number of
+ generators of self, i.e., the number of steps in the tower
+ of relative fields.
 Also, ``K.structure()`` returns from_K and to_K, where
 from_K is an isomorphism from K to self and to_K is an
 isomorphism from self to K.
+ Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where
+ from_K is an isomorphism from `K` to self and ``to_K`` is an
+ isomorphism from self to `K`.
EXAMPLES::
@@ 372,7 +384,9 @@
return L
def is_absolute(self):
 """
+ r"""
+ Returns False, since this is not an absolute field.
+
EXAMPLES::
sage: K. = NumberField([x^4 + 3, x^2 + 2]); K
@@ 414,7 +428,7 @@
def gen(self, n=0):
"""
 Return the n'th generator of this relative number field.
+ Return the `n`'th generator of this relative number field.
EXAMPLES::
@@ 430,7 +444,7 @@
return self.__gens[n]
def galois_closure(self, names=None):
 """
+ r"""
Return the absolute number field `K` that is the Galois closure of this
relative number field.
@@ 456,7 +470,8 @@
return self.absolute_polynomial().degree()
def relative_degree(self):
 """
+ r"""
+ Returns the relative degree of this relative number field.
EXAMPLES::
@@ 564,7 +579,7 @@
def _latex_(self):
r"""
 Return a \LaTeX representation of the extension.
+ Return a `\LaTeX` representation of the extension.
EXAMPLES::
@@ 586,7 +601,7 @@
INPUT:
  x  an element of some number field
+  ``x``  an element of some number field
EXAMPLES::
@@ 605,13 +620,13 @@
raise TypeError, "Cannot coerce element into this number field"
def _coerce_non_number_field_element_in(self, x):
 """
 Coerce a nonnumber field element x into this number field.
+ r"""
+ Coerce the nonnumber field element `x` into this number field.
INPUT:
  x  a non number field element x, e.g., a list, integer, rational,
 or polynomial.
+  ``x``  a non number field element, e.g., a list,
+ integer, rational, or polynomial.
EXAMPLES::
@@ 645,7 +660,7 @@
TypeError:
One can also coerce an element of the polynomial quotient ring
 that's isomorphic to the number field::
+ that is isomorphic to the number field::
sage: K. = NumberField(x^3 + 17)
sage: b = K.polynomial_quotient_ring().random_element()
@@ 811,7 +826,7 @@
There are situations for which one might imagine canonical
coercion could make sense (at least after fixing choices), but
 which aren't yet implemented::
+ which are not yet implemented::
sage: K. = QuadraticField(2)
sage: K.coerce(sqrt(2))
@@ 825,7 +840,8 @@
sage: type(K.coerce_map_from(QQ))
 Make sure we still get our optimized morphisms for special fields:
+ Make sure we still get our optimized morphisms for special fields::
+
sage: K. = NumberField(polygen(QQ)^22)
sage: type(K.coerce_map_from(QQ))
@@ 848,7 +864,7 @@
def _coerce_map_from_(self, R):
"""
 Canonical implicit coercion of x into self.
+ Canonical implicit coercion of ``R`` into self.
Elements of this field canonically coerce in, as does anything
that coerces into the base field of this field.
@@ 875,7 +891,7 @@
def _rnfeltreltoabs(self, element, check=False):
r"""
 Return PARI's rnfeletreltoabs, but without requiring rnfinit().
+ Return PARI's ``rnfeletreltoabs()``, but without requiring ``rnfinit()``.
TESTS::
@@ 956,17 +972,17 @@
return sage.rings.number_field.number_field_ideal_rel.NumberFieldFractionalIdeal_rel
def _pari_base_bnf(self, certify=False, units=True):
 """
+ r"""
Return the PARI bnf (big number field) representation of the
 absolute base field in terms of the pari variable y, suitable
 for extension by the pari variable x.
+ absolute base field in terms of the pari variable ``y``, suitable
+ for extension by the pari variable ``x``.
All caching is done by the absolute base field.
INPUT:
  proof  bool (default: True) if True, certify correctness of
 calculations (not assuming GRH).
+  ``certify`` (bool, default True)  if True, certify
+ correctness of calculations (not assuming GRH).
EXAMPLES::
@@ 983,10 +999,10 @@
@cached_method
def _pari_base_nf(self):
 """
+ r"""
Return the PARI number field representation of the absolute
 base field, in terms of the pari variable y, suitable for
 extension by the pari variable x.
+ base field, in terms of the pari variable ``y``, suitable for
+ extension by the pari variable ``x``.
In future, all caching will be done by the absolute base
field, but for now we work around a PARI bug that makes
@@ 1009,10 +1025,9 @@
def is_galois(self):
r"""
 For a relative number field, is_galois() is deliberately not
+ For a relative number field, ``is_galois()`` is deliberately not
implemented, since it is not clear whether this would mean "Galois over
 QQ" or "Galois over the given base field". Use either
 is_galois_absolute() or is_galois_relative() respectively.
+ `\QQ`" or "Galois over the given base field". Use either ``is_galois_absolute()`` or ``is_galois_relative()`` respectively.
EXAMPLES::
@@ 1026,7 +1041,8 @@
def is_galois_relative(self):
r"""
 Return True if for this relative extension L/K, L is a Galois extension of K.
+ Return True if for this relative extension `L/K`, `L` is a
+ Galois extension of `K`.
EXAMPLE::
@@ 1039,7 +1055,7 @@
def is_galois_absolute(self):
r"""
 Return True if for this relative extension L/K, L is a Galois extension of `\QQ`.
+ Return True if for this relative extension `L/K`, `L` is a Galois extension of `\QQ`.
EXAMPLE::
@@ 1091,6 +1107,9 @@
def absolute_vector_space(self):
"""
+ Return vector space over `\QQ` of self and isomorphisms from
+ the vector space to self and in the other direction.
+
EXAMPLES::
sage: K. = NumberField([x^3 + 3, x^3 + 2]); K
@@ 1128,17 +1147,17 @@
return ans
def vector_space(self):
 """
 For a relative number field `L`, ``L.vector_space()`` is deliberately
 not implemented, so that a user cannot confuse
 ``L.relative_vector_space()`` with ``L.absolute_vector_space()``.
+ r"""
+ For a relative number field, ``vector_space()`` is
+ deliberately not implemented, so that a user cannot confuse
+ ``relative_vector_space()`` with ``absolute_vector_space()``.
"""
raise NotImplementedError, "For a relative number field L you must use either L.relative_vector_space() or L.absolute_vector_space() as appropriate"
def absolute_base_field(self):
 """
+ r"""
Return the base field of this relative extension, but viewed
 as an absolute field over QQ.
+ as an absolute field over `\QQ`.
EXAMPLES::
@@ 1246,7 +1265,7 @@
def pari_absolute_base_polynomial(self):
r"""
 Return the PARI polynomial defining the absolute base field, in y.
+ Return the PARI polynomial defining the absolute base field, in ``y``.
EXAMPLES::
@@ 1331,8 +1350,8 @@
return [from_abs(x) for x in abs.roots_of_unity()]
def absolute_generator(self):
 """
 Return the chosen generator over QQ for this relative number field.
+ r"""
+ Return the chosen generator over `\QQ` for this relative number field.
EXAMPLES::
@@ 1353,18 +1372,19 @@
def absolute_field(self, names):
r"""
 Return an absolute number field K that is isomorphic to this
 field along with a fieldtheoretic bijection from self to K
 and from K to self.
+ Return an absolute number field `K` that is isomorphic to this
+ field along with a fieldtheoretic bijection from self to `K`
+ and from `K` to self.
INPUT:
  names  string; name of generator of the absolute field
+  ``names``  string; name of generator of the absolute field
OUTPUT: an absolute number field
 Also, ``K.structure()`` returns from_K and to_K, where from_K is an
 isomorphism from K to self and to_K is an isomorphism from self to K.
+ Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where
+ ``from_K`` is an isomorphism from `K` to self and ``to_K`` is
+ an isomorphism from self to `K`.
EXAMPLES::
@@ 1466,7 +1486,7 @@
"""
Return the defining polynomial of this relative number field.
 This is exactly the same as ``self.relative_polynomal()``.
+ This is exactly the same as ``relative_polynomal()``.
EXAMPLES::
@@ 1481,9 +1501,9 @@
def polynomial(self):
"""
 For a relative number field ``L``, ``L.polynomial()`` is deliberately
 not implemented. Either ``L.relative_polynomial()`` or
 ``L.absolute_polynomial()`` must be used.
+ For a relative number field, ``polynomial()`` is deliberately
+ not implemented. Either ``relative_polynomial()`` or
+ ``absolute_polynomial()`` must be used.
"""
raise NotImplementedError, "For a relative number field L you must use either L.relative_polynomial() or L.absolute_polynomial() as appropriate"
@@ 1524,18 +1544,18 @@
return self.base_field()
def embeddings(self, K):
 """
+ r"""
Compute all field embeddings of the relative number field self
 into the field K (which need not even be a number field, e.g.,
 it could be the complex numbers). This will return an
 identical result when given K as input again.
+ into the field `K` (which need not even be a number field,
+ e.g., it could be the complex numbers). This will return an
+ identical result when given `K` as input again.
 If possible, the most natural embedding of K into self
+ If possible, the most natural embedding of self into `K`
is put first in the list.
INPUT:
  K  a number field
+  ``K``  a field
EXAMPLES::
@@ 1686,14 +1706,14 @@
def absolute_discriminant(self, v=None):
r"""
Return the absolute discriminant of this relative number field
 or if v is specified, the determinant of the trace pairing
 on the elements of the list v.
+ or if ``v`` is specified, the determinant of the trace pairing
+ on the elements of the list ``v``.
INPUT:
  v (optional)  list of element of this relative number field.
+  ``v`` (optional)  list of element of this relative number field.
 OUTPUT: Integer if v is omitted, and Rational otherwise.
+ OUTPUT: Integer if ``v`` is omitted, and Rational otherwise.
EXAMPLES::
@@ 1725,7 +1745,7 @@
INPUT:
  proof  (default: False)
+  ``proof``  (default: False)
EXAMPLES::
@@ 1766,13 +1786,13 @@
INPUT:
  gens  list of elements of self; if no generators are given, just
+  ``gens``  list of elements of self; if no generators are given, just
returns the cardinality of this number field (oo) for consistency.
  check_is_integral  bool (default: True), whether to check that each
+  ``check_is_integral``  bool (default: True), whether to check that each
generator is integral.
  check_rank  bool (default: True), whether to check that the ring
+  ``check_rank``  bool (default: True), whether to check that the ring
generated by gens is of full rank.
  allow_subfield  bool (default: False), if True and the generators
+  ``allow_subfield``  bool (default: False), if True and the generators
do not generate an order, i.e., they generate a subring of smaller
rank, instead of raising an error, return an order in a smaller
number field.
@@ 1786,7 +1806,7 @@
sage: R = P.order([a,b,c]); R
Relative Order in Number Field in sqrt2 with defining polynomial x^2  2 over its base field
 The base ring of an order in a relative extension is still ZZ.::
+ The base ring of an order in a relative extension is still `\ZZ`.:
sage: R.base_ring()
Integer Ring
@@ 1848,7 +1868,7 @@
INPUT:
  proof  default: True
+  ``proof``  default: True
EXAMPLES::
@@ 1898,18 +1918,18 @@
Given an element in self or an embedding of a subfield into self,
return a relative number field `K` isomorphic to self that is relative
over the absolute field `\QQ(\alpha)` or the domain of `\alpha`, along
 with isomorphisms from `K` to self and from self to K.
+ with isomorphisms from `K` to self and from self to `K`.
INPUT:
  alpha  an element of self, or an embedding of a subfield into self
  names  name of generator for output field K.
+  ``alpha``  an element of self, or an embedding of a subfield into self
+  ``names``  name of generator for output field `K`.
 OUTPUT: K  a relative number field
+ OUTPUT: `K`  a relative number field
 Also, ``K.structure()`` returns from_K and to_K, where
 from_K is an isomorphism from K to self and to_K is an isomorphism
 from self to K.
+ Also, ``K.structure()`` returns ``from_K`` and ``to_K``, where
+ ``from_K`` is an isomorphism from `K` to self and ``to_K`` is
+ an isomorphism from self to `K`.
EXAMPLES::
@@ 1925,7 +1945,7 @@
sage: L.base_field()
Number Field in w with defining polynomial x^2 + 3
 Now suppose we have K below L below M::
+ Now suppose we have `K` below `L` below `M`::
sage: M = NumberField(x^8 + 2, 'a'); M
Number Field in a with defining polynomial x^8 + 2
@@ 1943,7 +1963,7 @@
sage: M_over_L_over_K.base_field() is L_over_K
True
 Let's test relativizing a degree 6 field over its degree 2 and degree 3
+ Test relativizing a degree 6 field over its degree 2 and degree 3
subfields, using both an explicit element::
sage: K. = NumberField(x^6 + 2); K
diff r 0b6b4751a6ea r e9c8a156d9d3 sage/rings/number_field/order.py
 a/sage/rings/number_field/order.py Tue Jun 02 18:22:42 2009 +0100
+++ b/sage/rings/number_field/order.py Thu Jun 04 22:38:31 2009 +0100
@@ 6,6 +6,7 @@
 William Stein and Robert Bradshaw (200709): initial version
EXAMPLES:
+
We define an absolute order::
sage: K. = NumberField(x^2 + 1); O = K.order(2*a)
@@ 48,8 +49,8 @@
def is_NumberFieldOrder(R):
 """
 Return True if R an order in a number field or R is the ring ZZ of integers.
+ r"""
+ Return True if R is either an order in a number field or is the ring `\ZZ` of integers.
EXAMPLES::
@@ 66,14 +67,14 @@
return isinstance(R, Order) or R == ZZ
def EquationOrder(f, names):
 """
+ r"""
Return the equation order generated by a root of the irreducible
 polynomial f or list of polynomials f (to construct a relative
+ polynomial f or list of polynomials `f` (to construct a relative
equation order).
IMPORTANT: Note that the generators of the returned order need
 *not* be a root of f, since the generators of an order are  in
 SAGE  module generators.
+ *not* be roots of `f`, since the generators of an order are  in
+ Sage  module generators.
EXAMPLES::
@@ 209,7 +210,7 @@
def __mul__(self, right):
"""
 Create an ideal in this order using the notation Ok*gens
+ Create an ideal in this order using the notation ``Ok*gens``
EXAMPLES::
@@ 230,7 +231,7 @@
def __rmul__(self, left):
"""
 Create an ideal in this order using the notation gens*Ok.
+ Create an ideal in this order using the notation ``gens*Ok``.
EXAMPLES::
@@ 363,8 +364,8 @@
return self.number_field().maximal_order()
def gen(self, i):
 """
 Return ith module generator of this order.
+ r"""
+ Return `i`'th module generator of this order.
EXAMPLES::
@@ 395,8 +396,10 @@
"""
Return a list of the module generators of this order.
 NOTE: For a (much smaller) list of ring generators use
 ``self.ring_generators()``.
+ .. note::
+
+ For a (much smaller) list of ring generators use
+ ``ring_generators()``.
EXAMPLES::
@@ 421,8 +424,8 @@
return self.absolute_degree()
def basis(self): # this must be defined in derived class
 """
 Return a basis over ZZ of this order.
+ r"""
+ Return a basis over `\ZZ` of this order.
EXAMPLES::
@@ 438,9 +441,9 @@
r"""
Returns the coordinate vector of `x` with respect to this order.
 INPUT::
+ INPUT:
  `x`  an element of the number field of this order.
+  ``x``  an element of the number field of this order.
OUTPUT:
@@ 452,9 +455,11 @@
AUTHOR: John Cremona 20081115
+ ALGORITHM:
+
Uses linear algebra. The changeofbasis matrix is
cached. Provides simpler implementations for
 _contains_(), is_integral() and smallest_integer().
+ ``_contains_()``, ``is_integral()`` and ``smallest_integer()``.
EXAMPLES::
@@ 493,8 +498,8 @@
return to_V(K(x))*M
def free_module(self):
 """
 Return the free ZZmodule contained in the vector space
+ r"""
+ Return the free `\ZZ`module contained in the vector space
associated to the ambient number field, that corresponds
to this ideal.
@@ 511,7 +516,7 @@
[ 0 0 1]
An example in a relative extension. Notice that the module is
 a ZZmodule in the absolute_field associated to the relative
+ a `\ZZ`module in the absolute_field associated to the relative
field::
sage: K. = NumberField([x^2 + 1, x^2 + 2])
@@ 648,9 +653,9 @@
INPUT:
  prime  a prime ideal of the maximal order in this number field.
  name  the name of the variable in the residue field
  check  whether or not to check the primality of prime.
+  ``prime``  a prime ideal of the maximal order in this number field.
+  ``name``  the name of the variable in the residue field
+  ``check``  whether or not to check the primality of prime.
OUTPUT:
@@ 707,7 +712,7 @@
`\ZZ`module, or the degree of the ambient number field that contains
this order.
 This is a synonym for ``self.degree()``.
+ This is a synonym for ``degree()``.
EXAMPLES::
@@ 720,7 +725,9 @@
return self.degree()
def class_number(self, proof=None):
 """
+ r"""
+ Return the class number of this order.
+
EXAMPLES::
sage: ZZ[2^(1/3)].class_number()
@@ 804,10 +811,13 @@
r"""
Compare the order self to other.
 NOTE: This is a well defined way to compare any two objects, but it is
 not the partial inclusion ordering!. Thus self < other being True does
 not necessarily mean that self is contained in other. Use
 ``self.is_suborder(other)`` to determine inclusion.
+ .. note::
+
+ This is a well defined way to compare any two objects, but
+ it is not the partial inclusion ordering!. Thus self <
+ other being True does not necessarily mean that self is
+ contained in other. Use ``self.is_suborder(other)`` to
+ determine inclusion.
EXAMPLES::
@@ 841,8 +851,8 @@
return cmp(self._module_rep, other._module_rep)
def absolute_degree(self):
 """
 Returns the absolute degree of this order, ie the degree of this order over ZZ.
+ r"""
+ Returns the absolute degree of this order, ie the degree of this order over `\ZZ`.
EXAMPLES::
@@ 931,8 +941,8 @@
raise ValueError, "the module must have full rank."
def __call__(self, x):
 """
 Coerce x into this order.
+ r"""
+ Coerce ``x`` into this order.
EXAMPLES::
@@ 1008,7 +1018,7 @@
INPUT:
  magma  a magma interpreter
+  ``magma``  a magma interpreter
OUTPUT:
@@ 1087,7 +1097,7 @@
INPUT:
  other  another absolute order with the same ambient number field.
+  ``other``  another absolute order with the same ambient number field.
OUTPUT:
@@ 1182,8 +1192,8 @@
return "%sOrder in %r" % ("Maximal " if self._is_maximal else "", self._K)
def basis(self):
 """
 Return the basis over ZZ for this order.
+ r"""
+ Return the basis over `\ZZ` for this order.
EXAMPLES::
@@ 1319,10 +1329,12 @@
INPUT:
  names  string (default: 'z'); name of generator of absolute extension.
+  ``names``  string (default: 'z'); name of generator of absolute extension.
 NOTE: There *is* a default variable name, since this absolute
 order is frequently used for internal algorithms.
+ .. note::
+
+ There *is* a default variable name, since this absolute
+ order is frequently used for internal algorithms.
EXAMPLES::
@@ 1336,8 +1348,9 @@
sage: S.basis()
[1, 5/12*z^3 + 1/6*z, 1/2*z^2, 1/2*z^3]
 We compute a relative order in alpha0, alpha1, then make the number field
 that contains the absolute order be called gamma.::
+ We compute a relative order in alpha0, alpha1, then make the
+ number field that contains the absolute order be called
+ gamma.::
sage: R = EquationOrder( [x^2 + 2, x^2  3], 'alpha'); R
Relative Order in Number Field in alpha0 with defining polynomial x^2 + 2 over its base field
@@ 1356,7 +1369,9 @@
Return module basis for this relative order. This is a list
of elements that generate this order over the base order.
 WARNING: For now this basis is actually just a basis over ZZ.
+ .. warning::
+
+ For now this basis is actually just a basis over `\ZZ`.
EXAMPLES::
@@ 1482,7 +1497,7 @@
INPUT:
  other  another order with the same ambient absolute number field.
+  ``other``  another order with the same ambient absolute number field.
OUTPUT:
@@ 1506,7 +1521,7 @@
def each_is_integral(v):
"""
 Return True if each element of the list v of elements of a number
+ Return True if each element of the list ``v`` of elements of a number
field is integral.
EXAMPLES::
@@ 1529,14 +1544,14 @@
"""
INPUT:
  gens  list of integral elements of an absolute order.
  check_is_integral  bool (default: True), whether to check that each
+  ``gens``  list of integral elements of an absolute order.
+  ``check_is_integral``  bool (default: True), whether to check that each
generator is integral.
  check_rank  bool (default: True), whether to check that the ring
+  ``check_rank``  bool (default: True), whether to check that the ring
generated by gens is of full rank.
  is_maximal  bool (or None); set if maximality of the generated order is
+  ``is_maximal``  bool (or None); set if maximality of the generated order is
known
  allow_subfield  bool (default: False), if True and the generators do
+  ``allow_subfield``  bool (default: False), if True and the generators do
not generate an order, i.e., they generate a subring of smaller rank,
instead of raising an error, return an order in a smaller number field.
@@ 1598,13 +1613,13 @@
"""
INPUT:
  gens  list of elements of an absolute number field that generates an
+  ``gens``  list of elements of an absolute number field that generates an
order in that number field as a ZZ *module*.
  check_integral  check that each gen is integral
  check_rank  check that the gens span a module of the correct rank
  check_is_ring  check that the module is closed under multiplication
+  ``check_integral``  check that each gen is integral
+  ``check_rank``  check that the gens span a module of the correct rank
+  ``check_is_ring``  check that the module is closed under multiplication
(this is very expensive)
  is_maximal  bool (or None); set if maximality of the generated order is known
+  ``is_maximal``  bool (or None); set if maximality of the generated order is known
OUTPUT:
@@ 1669,7 +1684,7 @@
sage: R.basis()
[1/2, i]
 We turn off all check flags and make a really messed up order.::
+ We turn off all check flags and make a really messed up order::
sage: R = absolute_order_from_module_generators([1/2, i], check_is_ring=False, check_integral=False, check_rank=False); R
Order in Number Field in i with defining polynomial x^2 + 1
@@ 1738,12 +1753,12 @@
"""
INPUT:
  gens  list of integral elements of an absolute order.
  check_is_integral  bool (default: True), whether to check that each
+  ``gens``  list of integral elements of an absolute order.
+  ``check_is_integral``  bool (default: True), whether to check that each
generator is integral.
  check_rank  bool (default: True), whether to check that the ring
+  ``check_rank``  bool (default: True), whether to check that the ring
generated by gens is of full rank.
  is_maximal  bool (or None); set if maximality of the generated order is
+  ``is_maximal``  bool (or None); set if maximality of the generated order is
known
EXAMPLES:
@@ 1757,7 +1772,7 @@
Relative Order in Number Field in i with defining polynomial x^2 + 1 over its base field
Basis for the relative order, which is obtained by computing the algebra generated
 by i and a.::
+ by i and a::
sage: S.basis()
[1, 7*i  2*a, a*i + 8, 25*i  7*a]
diff r 0b6b4751a6ea r e9c8a156d9d3 sage/rings/number_field/unit_group.py
 a/sage/rings/number_field/unit_group.py Tue Jun 02 18:22:42 2009 +0100
+++ b/sage/rings/number_field/unit_group.py Thu Jun 04 22:38:31 2009 +0100
@@ 1,4 +1,4 @@
"""
+r"""
Unit Groups of Number Fields
EXAMPLES::
@@ 143,10 +143,10 @@
INPUT:
  number_field  a number field
  proof  boolean (default True): proof flag
+  ``number_field``  a number field
+  ``proof``  boolean (default True): proof flag
 The proof flag is passed to pari via the pari_bnf() function
+ The proof flag is passed to pari via the ``pari_bnf()`` function
which computes the unit group. See the documentation for the
number_field module.
@@ 211,8 +211,8 @@
INPUT:
  u  Any object from which an element of the unit group's number
 field K may be constructed; an error is raised if an element of K
+  ``u``  Any object from which an element of the unit group's number
+ field `K` may be constructed; an error is raised if an element of `K`
cannot be constructed from u, or if the element constructed is not a
unit.
@@ 255,7 +255,7 @@
def _coerce_impl(self, x):
"""
 Canonical coercion of x into this unit group.
+ Canonical coercion of ``x`` into this unit group.
EXAMPLES:
@@ 303,9 +303,11 @@
def gen(self, i=0):
"""
 Return the ith generator for this unit group.
+ Return the `i`'th generator for this unit group.
 NOTE: i=0 gives the torsion generator, i.e. a primitive root of unity.
+ .. note::
+
+ `i=0` gives the torsion generator, i.e. a primitive root of unity.
EXAMPLES::
@@ 489,17 +491,17 @@
def log(self, u):
 """
 Return the exponents of the unit u with respect to group generators.
+ r"""
+ Return the exponents of the unit ``u`` with respect to group generators.
INPUT:
  u  Any object from which an element of the unit group's number
 field K may be constructed; an error is raised if an element of K
+  ``u``  Any object from which an element of the unit group's number
+ field `K` may be constructed; an error is raised if an element of `K`
cannot be constructed from u, or if the element constructed is not a
unit.
 OUTPUT: a list of integers giving the exponents of u with
+ OUTPUT: a list of integers giving the exponents of ``u`` with
respect to the unit group's basis.
EXAMPLES::
@@ 523,17 +525,17 @@
return self(u).list()
def exp(self, exponents):
 """
+ r"""
Return unit with given exponents with respect to group generators.
INPUT:
  u  Any object from which an element of the unit group's number
 field K may be constructed; an error is raised if an element of K
 cannot be constructed from u, or if the element constructed is not a
 unit.
+  ``u``  Any object from which an element of the unit
+ group's number field `K` may be constructed; an error is
+ raised if an element of `K` cannot be constructed from u, or
+ if the element constructed is not a unit.
 OUTPUT: a list of integers giving the exponents of u with
+ OUTPUT: a list of integers giving the exponents of ``u`` with
respect to the unit group's basis.
EXAMPLES::