#31345: implementation of Selmer groups of number fields

Author: JohnCremona

src/sage/rings/number_field/number_field.py

@@ -4753,9 +4753,8 @@ def _S_class_group_quotient_matrix(self, S):
         assert A[:c] == 1 and A[c:] == 0
         return Q[:c, :a]
 
-    def selmer_group(self, S, m, proof=True, orders=False):
-        r"""
-        Compute the group `K(S,m)`.
+    def selmer_generators(self, S, m, proof=True, orders=False):
+        r"""Compute generators of the group `K(S,m)`.
 
         INPUT:
 
@@ -4791,14 +4790,23 @@ def selmer_group(self, S, m, proof=True, orders=False):
         outside of `S`, but may contain it properly when not all
         primes dividing `m` are in `S`.
 
+        .. NOTE::
+
+            When `m=p` is prime, see also the method
+            :meth:`NumberField_generic.selmer_space` which gives
+            additional output: as well as generators, it gives an
+            abstract vector space over `\F_p` isomorphic to `K(S,p)`
+            and maps implementing the isomorphism between this space
+            and `K(S,p)` as a subgroup of `K^*/(K^*)^p`.
+
         EXAMPLES::
 
             sage: K.<a> = QuadraticField(-5)
-            sage: K.selmer_group((), 2)
+            sage: K.selmer_generators((), 2)
             [-1, 2]
 
         The previous example shows that the group generated by the
-        output may be strictly larger than the 'true' Selmer group of
+        output may be strictly larger than the group of
         elements giving extensions unramified outside `S`, since that
         has order just 2, generated by `-1`::
 
@@ -4812,31 +4820,31 @@ def selmer_group(self, S, m, proof=True, orders=False):
             sage: K.<a> = QuadraticField(-5)
             sage: P2 = K.ideal(2, -a+1)
             sage: P3 = K.ideal(3, a+1)
-            sage: K.selmer_group((), 2, orders=True)
+            sage: K.selmer_generators((), 2, orders=True)
             ([-1, 2], [2, 2])
-            sage: K.selmer_group((), 4, orders=True)
+            sage: K.selmer_generators((), 4, orders=True)
             ([-1, 4], [2, 2])
-            sage: K.selmer_group([P2], 2)
+            sage: K.selmer_generators([P2], 2)
             [2, -1]
-            sage: K.selmer_group((P2,P3), 4)
+            sage: K.selmer_generators((P2,P3), 4)
             [2, -a - 1, -1]
-            sage: K.selmer_group((P2,P3), 4, orders=True)
+            sage: K.selmer_generators((P2,P3), 4, orders=True)
             ([2, -a - 1, -1], [4, 4, 2])
-            sage: K.selmer_group([P2], 3)
+            sage: K.selmer_generators([P2], 3)
             [2]
-            sage: K.selmer_group([P2, P3], 3)
+            sage: K.selmer_generators([P2, P3], 3)
             [2, -a - 1]
-            sage: K.selmer_group([P2, P3, K.ideal(a)], 3)  # random signs
+            sage: K.selmer_generators([P2, P3, K.ideal(a)], 3)  # random signs
             [2, a + 1, a]
 
         Example over `\QQ` (as a number field)::
 
             sage: K.<a> = NumberField(polygen(QQ))
-            sage: K.selmer_group([],5)
+            sage: K.selmer_generators([],5)
             []
-            sage: K.selmer_group([K.prime_above(p) for p in [2,3,5]],2)
+            sage: K.selmer_generators([K.prime_above(p) for p in [2,3,5]],2)
             [2, 3, 5, -1]
-            sage: K.selmer_group([K.prime_above(p) for p in [2,3,5]],6, orders=True)
+            sage: K.selmer_generators([K.prime_above(p) for p in [2,3,5]],6, orders=True)
             ([2, 3, 5, -1], [6, 6, 6, 2])
 
         TESTS::
@@ -4845,15 +4853,15 @@ def selmer_group(self, S, m, proof=True, orders=False):
             sage: P2 = K.ideal(2, -a+1)
             sage: P3 = K.ideal(3, a+1)
             sage: P5 = K.ideal(a)
-            sage: S = K.selmer_group([P2, P3, P5], 3)
+            sage: S = K.selmer_generators([P2, P3, P5], 3)
             sage: S in ([2, a + 1, a], [2, a + 1, -a], [2, -a - 1, a], [2, -a - 1, -a]) or S
             True
 
         Verify that :trac:`14489` is fixed;
         the representation depends on the PARI version::
 
             sage: K.<a> = NumberField(x^3 - 381 * x + 127)
-            sage: gens = K.selmer_group(K.primes_above(13), 2)
+            sage: gens = K.selmer_generators(K.primes_above(13), 2)
             sage: len(gens) == 8
             True
             sage: gens[:5]
@@ -4873,9 +4881,10 @@ def selmer_group(self, S, m, proof=True, orders=False):
 
             sage: K.<a> = QuadraticField(-5)
             sage: p = K.primes_above(2)[0]
-            sage: S = K.selmer_group((), 4)
+            sage: S = K.selmer_generators((), 4)
             sage: all(4.divides(x.valuation(p)) for x in S)
             True
+
         """
         units, clgp_gens = self._S_class_group_and_units(tuple(S), proof=proof)
         gens = []
@@ -4921,6 +4930,9 @@ def selmer_group(self, S, m, proof=True, orders=False):
         else:
             return gens
 
+    # For backwards compatibility:
+    selmer_group = selmer_generators
+
     def selmer_group_iterator(self, S, m, proof=True):
         r"""
         Return an iterator through elements of the finite group `K(S,m)`.
@@ -4936,7 +4948,7 @@ def selmer_group_iterator(self, S, m, proof=True):
         OUTPUT:
 
         An iterator yielding the distinct elements of `K(S,m)`.  See
-        the docstring for :meth:`NumberField_generic.selmer_group` for
+        the docstring for :meth:`NumberField_generic.selmer_generators` for
         more information.
 
         EXAMPLES::
@@ -4961,12 +4973,116 @@ def selmer_group_iterator(self, S, m, proof=True):
             sage: list(K.selmer_group_iterator([K.prime_above(p) for p in [11,13]],2))
             [1, -1, 13, -13, 11, -11, 143, -143]
         """
-        KSgens, ords = self.selmer_group(S=S, m=m, proof=proof, orders=True)
+        KSgens, ords = self.selmer_generators(S=S, m=m, proof=proof, orders=True)
         one = self.one()
         from sage.misc.all import cartesian_product_iterator
         for ev in cartesian_product_iterator([range(o) for o in ords]):
             yield prod([p ** e for p, e in zip(KSgens, ev)], one)
 
+    def selmer_space(self, S, p, proof=None):
+        r"""Compute the group `K(S,p)` as a vector space with maps to and from `K^*`.
+
+        INPUT:
+
+        - ``S`` -- a set of primes ideals of ``self``
+
+        - ``p`` -- a prime number
+
+        - ``proof`` -- if False, assume the GRH in computing the class group
+
+        OUTPUT:
+
+        (tuple) ``KSp``, ``KSp_gens``, ``from_KSp``, ``to_KSp`` where
+
+        - ``KSp`` is an abstract vector space over `GF(p)` isomorphic to `K(S,p)`;
+
+        - ``KSp_gens`` is a list of elements of `K^*` generating `K(S,p)`;
+
+        - ``from_KSp`` is a function from ``KSp`` to `K^*`
+          implementing the isomorphism from the abstract `K(S,p)` to
+          `K(S,p)` as a subgroup of `K^*/(K^*)^p`;
+
+        - ``to_KSP`` is a partial function from `K^*` to ``KSp``,
+          defined on elements `a` whose image in `K^*/(K^*)^p` lies in
+          `K(S,p)`, mapping them via the inverse isomorphism to the
+          abstract vector space ``KSp``.
+
+        The group `K(S,p)` is the finite subgroup of `K^*/(K^*)^p$
+        consisting of elements whose valuation at all orimes not in
+        `S` is a multiple of `p`.  It contains the subgroup of those
+        `a\in K^*` such that `K(\sqrt[p]{a})/K` is unramified at all
+        primes of `K` outside of `S`, but may contain it properly when
+        not all primes dividing `p` are in `S`.
+
+        EXAMPLES:
+
+        A real quadratic field with class number 2, where the fundamental
+        unit is a generator, and the class group provides another
+        generator when `p==2`::
+
+            sage: K.<a> = QuadraticField(-5)
+            sage: K.class_number()
+            2
+            sage: P2 = K.ideal(2, -a+1)
+            sage: P3 = K.ideal(3, a+1)
+            sage: P5 = K.ideal(a)
+            sage: KS2, gens, fromKS2, toKS2 = K.selmer_space([P2, P3, P5], 2)
+            sage: KS2
+            Vector space of dimension 4 over Finite Field of size 2
+            sage: gens
+            [a + 1, a, 2, -1]
+
+        Each generator must have even valuation at primes not in `S`::
+
+            sage: [K.ideal(g).factor() for g in gens]
+            [(Fractional ideal (2, a + 1)) * (Fractional ideal (3, a + 1)),
+            Fractional ideal (-a),
+            (Fractional ideal (2, a + 1))^2,
+            1]
+
+            sage: toKS2(10)
+            (0, 0, 1, 1)
+            sage: fromKS2([0,0,1,1])
+            -2
+            sage: K(10/(-2)).is_square()
+            True
+
+            sage: KS3, gens, fromKS3, toKS3 = K.selmer_space([P2, P3, P5], 3)
+            sage: KS3
+            Vector space of dimension 3 over Finite Field of size 3
+            sage: gens
+            [1/2, 1/4*a + 1/4, a]
+
+        An example to show that the group 'K(S,2)` may be strictly
+        larger than the group of elements giving extensions unramified
+        outside `S`.  In this case, with `K` of class number `2` and
+        `S` empty, there is only one quadratic extension of `K`
+        unramified outside `S`, the Hilbert Class Field
+        `K(\sqrt{-1})`::
+
+            sage: K.<a> = QuadraticField(-5)
+            sage: KS2, gens, fromKS2, toKS2 = K.selmer_space([], 2)
+            sage: KS2
+            Vector space of dimension 2 over Finite Field of size 2
+            sage: gens
+            [2, -1]
+            sage: for v in KS2:
+            ....:     if not v:
+            ....:         continue
+            ....:     a = fromKS2(v)
+            ....:     print((a,K.extension(x^2-a, 'roota').relative_discriminant().factor()))
+            ....:
+            (2, (Fractional ideal (2, a + 1))^4)
+            (-1, 1)
+            (-2, (Fractional ideal (2, a + 1))^4)
+
+            sage: K.hilbert_class_field('b')
+            Number Field in b with defining polynomial x^2 + 1 over its base field
+
+        """
+        from sage.rings.number_field.selmer_group import pSelmerGroup
+        return pSelmerGroup(self, S, p, proof)
+
     def composite_fields(self, other, names=None, both_maps=False, preserve_embedding=True):
         """
         Return the possible composite number fields formed from
@@ -5493,7 +5609,7 @@ def elements_of_norm(self, n, proof=None):
         - ``n`` -- integer in this number field
 
         - ``proof`` -- boolean (default: ``True``, unless you called
-          ``number_field_proof`` and set it otherwise)
+          :meth:`proof.number_field` and set it otherwise)
 
         OUTPUT:
 
@@ -6904,6 +7020,7 @@ def S_unit_group(self, proof=None, S=None):
         INPUT:
 
         - ``proof`` (bool, default True) flag passed to ``pari``.
+
         - ``S`` - list or tuple of prime ideals, or an ideal, or a single
           ideal or element from which an ideal can be constructed, in
           which case the support is used.  If None, the global unit
@@ -11657,12 +11774,15 @@ def is_galois(self):
         return True
 
     def class_number(self, proof=None):
-        r"""
-        Return the size of the class group of self.
+        r"""Return the size of the class group of self.
+
+        INPUT:
 
-        If proof = False (*not* the default!) and the discriminant of the
-        field is negative, then the following warning from the PARI manual
-        applies:
+        - ``proof`` -- boolean (default: ``True``, unless you called
+          :meth:`proof.number_field` and set it otherwise).  If
+          ``proof`` is ``False`` (*not* the default!), and the
+          discriminant of the field is negative, then the following
+          warning from the PARI manual applies:
 
         .. warning::
 
@@ -11701,6 +11821,7 @@ def class_number(self, proof=None):
             <type 'sage.rings.integer.Integer'>
             sage: type(CyclotomicField(10).class_number())
             <type 'sage.rings.integer.Integer'>
+
         """
         proof = proof_flag(proof)
         try:

src/sage/rings/number_field/number_field_ideal.py

@@ -1861,6 +1861,8 @@ def prime_factors(self):
         """
         return [x[0] for x in self.factor()]
 
+    support = prime_factors
+
     def _div_(self, other):
         """
         Return the quotient self / other.

src/sage/rings/polynomial/polynomial_quotient_ring.py

@@ -1138,7 +1138,7 @@ def _S_decomposition(self, S):
         Compute the decomposition of self into a product of number fields.
 
         This is an internal function used by
-        :meth:`S_class_group`, :meth:`S_units` and :meth:`selmer_group`.
+        :meth:`S_class_group`, :meth:`S_units` and :meth:`selmer_generators`.
 
         EXAMPLES::
 
@@ -1632,7 +1632,7 @@ def units(self, proof=True):
         """
         return self.S_units((), proof=proof)
 
-    def selmer_group(self, S, m, proof=True):
+    def selmer_generators(self, S, m, proof=True):
         r"""
         If self is an étale algebra `D` over a number field `K` (i.e.
         a quotient of `K[x]` by a squarefree polynomial) and `S` is a
@@ -1658,19 +1658,19 @@ def selmer_group(self, S, m, proof=True):
             sage: K.<a> = QuadraticField(-5)
             sage: R.<x> = K[]
             sage: D.<T> = R.quotient(x)
-            sage: D.selmer_group((), 2)
+            sage: D.selmer_generators((), 2)
             [-1, 2]
-            sage: D.selmer_group([K.ideal(2, -a+1)], 2)
+            sage: D.selmer_generators([K.ideal(2, -a+1)], 2)
             [2, -1]
-            sage: D.selmer_group([K.ideal(2, -a+1), K.ideal(3, a+1)], 2)
+            sage: D.selmer_generators([K.ideal(2, -a+1), K.ideal(3, a+1)], 2)
             [2, a + 1, -1]
-            sage: D.selmer_group((K.ideal(2, -a+1),K.ideal(3, a+1)), 4)
+            sage: D.selmer_generators((K.ideal(2, -a+1),K.ideal(3, a+1)), 4)
             [2, a + 1, -1]
-            sage: D.selmer_group([K.ideal(2, -a+1)], 3)
+            sage: D.selmer_generators([K.ideal(2, -a+1)], 3)
             [2]
-            sage: D.selmer_group([K.ideal(2, -a+1), K.ideal(3, a+1)], 3)
+            sage: D.selmer_generators([K.ideal(2, -a+1), K.ideal(3, a+1)], 3)
             [2, a + 1]
-            sage: D.selmer_group([K.ideal(2, -a+1), K.ideal(3, a+1), K.ideal(a)], 3)
+            sage: D.selmer_generators([K.ideal(2, -a+1), K.ideal(3, a+1), K.ideal(a)], 3)
             [2, a + 1, a]
 
         """
@@ -1679,7 +1679,7 @@ def selmer_group(self, S, m, proof=True):
 
         component_selmer_groups = []
         for D_iso, S_iso in iso_classes:
-            sel = D_iso.selmer_group(S_iso, m, proof=proof)
+            sel = D_iso.selmer_generators(S_iso, m, proof=proof)
             component_selmer_groups.append(sel)
 
         gens = []
@@ -1696,6 +1696,9 @@ def selmer_group(self, S, m, proof=True):
 
         return gens
 
+    # For backwards compatibility:
+    selmer_group = selmer_generators
+
     def _factor_multivariate_polynomial(self, f, proof=True):
         r"""
         Return the factorization of ``f`` over this ring.