Clean up S-class group, S-unit and Selmer group code

[pjbruin]

The code for S-class groups, S-units and Selmer groups of number fields, and more generally étale algebras, is not entirely satisfactory in the following respects:

1. The code for computing Selmer groups is somewhat convoluted. Conceptually, the computation of the generators for principal ideals of the form gen^order belongs in selmer_group, not _S_class_group_and_units. It would be more correct to return, as S-class group generators, pairs (gen, order) instead of triples (gen, order, pr), and leave the computation of the principal ideal generators to selmer_group.

2. The docstrings are not very clear. The sentences are very long and contain awkward constructions ("a fractional ideal representative of the S-class group generator whose order (in the S-class group) is order"; "principal generator").

3. The docstring of NumberField._S_class_group_and_units suggests that to obtain a principal ideal, gen^order can be multiplied by any fractional ideal J whose class is in the subgroup of the class group generated by ideals in S. However, the condition is more strict: J must be in the subgroup of the ideal group generated by ideals in S.

The attached patch does the following things:

1. Move computation of generators of principal ideals from NumberField._S_class_group_and_units to NumberField.selmer_group.

2. Add a method _S_decomposition to PolynomialQuotientRing_generic, which computes the decomposition of an étale algebra as a product of number fields. Use this function in S_class_group, S_units and selmer_group.

3. Delete PolynomialQuotientRing_generic._S_class_group_and_units, and move its code and doctests to S_class_group, class_group, S_units and units.

4. Reimplement PolynomialQuotientRing_generic.selmer_group to compute the Selmer group as the product of the Selmer groups of the distinct components, instead of imitating the algorithm of NumberField.selmer_group.

5. Make the documentation more precise.

Apply: attachment: trac_14746_doctests_32_64_bit_undo.patch, attachment: trac_14746_selmer_group_cleanup.patch, attachment: trac_14746_docstring_fixes.patch

Depends on #14489

CC: @sagetrac-ArgaezG @sagetrac-akoutsianas

Component: number fields

Keywords: S-class group, S-units, Selmer group, sd51

Author: Peter Bruin

Reviewer: John Cremona, Alejandro Argaez, Angelos Koutsianas

Merged: sage-5.12.beta2

Issue created by migration from https://trac.sagemath.org/ticket/14746

[pjbruin]

based on 5.10.rc1 + #14489

[pjbruin]

comment:1

Attachment: trac_14746_selmer_group_cleanup.patch.gz

[pjbruin]

Description changed:

--- 
+++ 
@@ -4,7 +4,7 @@
 
 2. The docstrings are not very clear. The sentences are very long and contain awkward constructions ("a fractional ideal representative of the S-class group generator whose order (in the S-class group) is order"; "principal generator").
 
-3. The docstring of NumberField._S_class_group_and_units suggests that to obtain a principal ideal, genorder can be multiplied by any fractional ideal J whose class is in the subgroup of the class group generated by ideals in S. However, the condition is more strict: J must be in the subgroup of the ideal group generated by ideals in S.
+3. The docstring of NumberField._S_class_group_and_units suggests that to obtain a principal ideal, gen<sup>order</sup> can be multiplied by any fractional ideal J whose class is in the subgroup of the class group generated by ideals in S. However, the condition is more strict: J must be in the subgroup of the ideal group generated by ideals in S.
 
 The attached patch does the following things:
 

[pjbruin]

Description changed:

--- 
+++ 
@@ -17,3 +17,5 @@
 4. Reimplement PolynomialQuotientRing_generic.selmer_group to compute the Selmer group as the product of the Selmer groups of the distinct components, instead of imitating the algorithm of NumberField.selmer_group.
 
 5. Make the documentation more precise.
+
+Apply: trac_14746_selmer_group_cleanup.patch

[pjbruin]

Attachment: trac_14746_doctests_32_64_bit_undo.patch.gz

undo the effect of trac_14489_doctests_32_64_bit.patch

[pjbruin]

Description changed:

--- 
+++ 
@@ -18,4 +18,5 @@
 
 5. Make the documentation more precise.
 
-Apply: trac_14746_selmer_group_cleanup.patch
+Apply: [attachment: trac_14746_doctests_32_64_bit_undo.patch](https://github.com/sagemath/sage-prod/files/10657946/trac_14746_doctests_32_64_bit_undo.patch.gz), [attachment: trac_14746_selmer_group_cleanup.patch](https://github.com/sagemath/sage-prod/files/10657945/trac_14746_selmer_group_cleanup.patch.gz)
+

[pjbruin]

comment:4

For patchbot:

Apply trac_14746_doctests_32_64_bit_undo.patch, trac_14746_selmer_group_cleanup.patch

[pjbruin]

Description changed:

--- 
+++ 
@@ -18,5 +18,5 @@
 
 5. Make the documentation more precise.
 
-Apply: [attachment: trac_14746_doctests_32_64_bit_undo.patch](https://github.com/sagemath/sage-prod/files/10657946/trac_14746_doctests_32_64_bit_undo.patch.gz), [attachment: trac_14746_selmer_group_cleanup.patch](https://github.com/sagemath/sage-prod/files/10657945/trac_14746_selmer_group_cleanup.patch.gz)
+Apply: [attachment: trac_14746_doctests_32_64_bit_undo.patch](https://github.com/sagemath/sage-prod/files/10657946/trac_14746_doctests_32_64_bit_undo.patch.gz), [attachment: trac_14746_selmer_group_cleanup.patch](https://github.com/sagemath/sage-prod/files/10657945/trac_14746_selmer_group_cleanup.patch.gz), [attachment: trac_14746_docstring_fixes.patch](https://github.com/sagemath/sage-prod/files/10657947/trac_14746_docstring_fixes.patch.gz)
 

[vbraun]

comment:6

The source file needs to specify UTF-8 encoding if you want to use non-ascii characters, but rings/polynomial/polynomial_quotient_ring.py does not. See http://www.python.org/dev/peps/pep-0263/