Implemented the (local) Hilbert symbol for global function fields

[S17A05]

Implemented the computation of the (local) Hilbert symbol at a place of a global function field of odd characteristic following formula 12.4.10 in John Voight's "Quaternion Algebras" (in preparation of extending some quaternion algebra functionality to these global function fields).

The global Hilbert symbol will be implemented via a call to .is_matrix_ring() of the appropriate quaternion algebra once the latter method has been extended using an extension of PR #37173, which will be done once both this PR and the referenced PR have been merged.

[kwankyu]

I fixed typos and refined the docstring. If you pardon me, please consider:

diff --git a/src/sage/rings/function_field/function_field.py b/src/sage/rings/function_field/function_field.py
index d1652873c71..4f91e51c111 100644
--- a/src/sage/rings/function_field/function_field.py
+++ b/src/sage/rings/function_field/function_field.py
@@ -1229,23 +1229,10 @@ class FunctionField(Field):
 
     def hilbert_symbol(self, a, b, P):
         r"""
-        Return the Hilbert symbol `(a,b)_{F_P}` (where `F_P` is the
-        completion of this function field at the place `P`).
+        Return the Hilbert symbol `(a,b)_{F_P}` for the local field `F_P`.
 
-        The Hilbert symbol `(a,b)_{F_P}` is `0` if one of `a` or `b` is
-        zero. Otherwise it takes the value `1` if  the quaternion algebra
-        defined by `(a,b)` over `F_P` is split, and `-1` if it is division.
-
-        For the valuation `\nu` belonging to the completion of the function
-        field at `P`, we compute the valuations `\nu(a)` and `\nu(b)` as well
-        as elements `a_0` and `b_0` such that, for a uniformizer `\pi` of
-        `\nu`, the elememts `a*\pi^{-\nu(a))}` and `a_0` respectively the
-        elements `b*\pi^{-\nu(b)}` and `b_0` are congruent modulo `\pi`.
-        Motivated by formula 12.4.10 in [Voi2021]_.
-
-        Currently only tested for function fields separable over their base
-        since places are not fully supported for other function fields. Only
-        implemented for global function fields of odd characteristic.
+        The local field `F_P` is the completion of this function field `F` at
+        the place `P`.
 
         INPUT:
 
@@ -1253,6 +1240,23 @@ class FunctionField(Field):
 
         - ``P`` -- a place of this function field
 
+        The Hilbert symbol `(a,b)_{F_P}` is `0` if `a` or `b` is zero.
+        Otherwise it takes the value `1` if  the quaternion algebra defined by
+        `(a,b)` over `F_P` is split, and `-1` if it is a division ring.
+
+        ALGORITHM:
+
+        For the valuation `\nu = \nu_P` of `F`, we compute the valuations
+        `\nu(a)` and `\nu(b)` as well as elements `a_0` and `b_0` of the
+        residue field such that for a uniformizer `\pi` at `P`,
+        `a\pi^{-\nu(a)}` and `a_0` respectively `b\pi^{-\nu(b)}` and `b_0` are
+        congruent modulo `\pi`.  Then the Hilbert symbol is computed by the
+        formula 12.4.10 in [Voi2021]_.
+
+        Currently only implemented for global function fields of odd
+        characteristic since places are not fully supported for other function
+        fields.
+
         EXAMPLES::

[S17A05]

I fixed typos and refined the docstring. If you pardon me, please consider:

diff --git a/src/sage/rings/function_field/function_field.py b/src/sage/rings/function_field/function_field.py
index d1652873c71..4f91e51c111 100644
--- a/src/sage/rings/function_field/function_field.py
+++ b/src/sage/rings/function_field/function_field.py
@@ -1229,23 +1229,10 @@ class FunctionField(Field):
 
     def hilbert_symbol(self, a, b, P):
         r"""
-        Return the Hilbert symbol `(a,b)_{F_P}` (where `F_P` is the
-        completion of this function field at the place `P`).
+        Return the Hilbert symbol `(a,b)_{F_P}` for the local field `F_P`.
 
-        The Hilbert symbol `(a,b)_{F_P}` is `0` if one of `a` or `b` is
-        zero. Otherwise it takes the value `1` if  the quaternion algebra
-        defined by `(a,b)` over `F_P` is split, and `-1` if it is division.
-
-        For the valuation `\nu` belonging to the completion of the function
-        field at `P`, we compute the valuations `\nu(a)` and `\nu(b)` as well
-        as elements `a_0` and `b_0` such that, for a uniformizer `\pi` of
-        `\nu`, the elememts `a*\pi^{-\nu(a))}` and `a_0` respectively the
-        elements `b*\pi^{-\nu(b)}` and `b_0` are congruent modulo `\pi`.
-        Motivated by formula 12.4.10 in [Voi2021]_.
-
-        Currently only tested for function fields separable over their base
-        since places are not fully supported for other function fields. Only
-        implemented for global function fields of odd characteristic.
+        The local field `F_P` is the completion of this function field `F` at
+        the place `P`.
 
         INPUT:
 
@@ -1253,6 +1240,23 @@ class FunctionField(Field):
 
         - ``P`` -- a place of this function field
 
+        The Hilbert symbol `(a,b)_{F_P}` is `0` if `a` or `b` is zero.
+        Otherwise it takes the value `1` if  the quaternion algebra defined by
+        `(a,b)` over `F_P` is split, and `-1` if it is a division ring.
+
+        ALGORITHM:
+
+        For the valuation `\nu = \nu_P` of `F`, we compute the valuations
+        `\nu(a)` and `\nu(b)` as well as elements `a_0` and `b_0` of the
+        residue field such that for a uniformizer `\pi` at `P`,
+        `a\pi^{-\nu(a)}` and `a_0` respectively `b\pi^{-\nu(b)}` and `b_0` are
+        congruent modulo `\pi`.  Then the Hilbert symbol is computed by the
+        formula 12.4.10 in [Voi2021]_.
+
+        Currently only implemented for global function fields of odd
+        characteristic since places are not fully supported for other function
+        fields.
+
         EXAMPLES::

Thanks, I'll integrate your changes. Just one small thing: Technically speaking there is a difference to formula 12.4.10 in [Voi2021]_, because the element $a_0$ computed in the code is only congruent modulo $\pi$ to $a \pi^{-\nu(a)}$ (which is the $a_0$ defined in the book) - effectively, this of course doesn't make a difference. Should I still keep the last sentence of the first ALGORITHM paragpraph as you wrote it?

[kwankyu]

Anyone reading the paragraph and the formula will understand that. Not a big deal. Also you explained the point.

[kwankyu]

typo necessary

[S17A05]

I implemented a slightly modified version of your suggested docstring, mainly because I wanted to emphasize that $a_0$ and $b_0$ are elements of the residue field here, rather than of the discrete valuation ring.

[github-actions]

Documentation preview for this PR (built with commit 4f1e025; changes) is ready! 🎉

[kwankyu]

Thanks. LGTM.