This is A1BrouwerDegrees.info, produced by Macaulay2, version 1.25.05

A1BrouwerDegrees -- package for working with A1-Brouwer degree computations
***************************************************************************

Description
===========

This package is intended to allow the computation and manipulation of
local, and global,
$\mathbb{A}^1$-Brouwer degrees. Global Brouwer degrees are non-degenerate
symmetric bilinear forms valued in the Grothendieck-Witt ring of a field
$\text{GW}(k)$.

In order to simplify the forms produced, this package produces invariants of
symmetric bilinear forms, including their Witt indices,
their discriminants, and their Hasse-Witt invariants.
Quadratic forms can be decomposed,
into their isotropic and anisotropic parts.
Finally, and perhaps most crucially, we can certify
whether two symmetric bilinear forms are isomorphic, in
the Grothendieck-Witt ring.

Below is an example using the methods provided by this package to compute the
local, and global,
$\mathbb{A}^1$-Brouwer degrees for an endomorphism
$\mathbb{A}_{\mathbb{Q}}^1\rightarrow \mathbb{A}_{\mathbb{Q}}^1.$ defined by $$
f(x)=(x^2+x+1)(x-3)(x+2).$$ We first compute the global degree.

+-------------------------------------+
|i1 : R = QQ[x]                       |
|                                     |
|o1 = R                               |
|                                     |
|o1 : PolynomialRing                  |
+-------------------------------------+
|i2 : f = {x^4 - 6*x^2 - 7*x - 6}     |
|                                     |
|       4     2                       |
|o2 = {x  - 6x  - 7x - 6}             |
|                                     |
|o2 : List                            |
+-------------------------------------+
|i3 : alpha = getGlobalA1Degree f     |
|                                     |
|o3 = | -7 -6 0 1 |                   |
|     | -6 0  1 0 |                   |
|     | 0  1  0 0 |                   |
|     | 1  0  0 0 |                   |
|                                     |
|o3 : GrothendieckWittClass           |
+-------------------------------------+
|i4 : beta = getSumDecomposition alpha|
|                                     |
|o4 = | 1 0  0 0  |                   |
|     | 0 -1 0 0  |                   |
|     | 0 0  1 0  |                   |
|     | 0 0  0 -1 |                   |
|                                     |
|o4 : GrothendieckWittClass           |
+-------------------------------------+

We can also compute the local degrees at the respective ideals.

+--------------------------------------+
|i5 : I1 = ideal(x^2 + x + 1);         |
|                                      |
|o5 : Ideal of R                       |
+--------------------------------------+
|i6 : alpha1 = getLocalA1Degree(f, I1) |
|                                      |
|o6 = | -5 -7 |                        |
|     | -7 -2 |                        |
|                                      |
|o6 : GrothendieckWittClass            |
+--------------------------------------+
|i7 : I2 = ideal(x - 3)                |
|                                      |
|o7 = ideal(x - 3)                     |
|                                      |
|o7 : Ideal of R                       |
+--------------------------------------+
|i8 : alpha2 = getLocalA1Degree(f, I2) |
|                                      |
|o8 = | 65 |                           |
|                                      |
|o8 : GrothendieckWittClass            |
+--------------------------------------+
|i9 : I3 = ideal(x + 2);               |
|                                      |
|o9 : Ideal of R                       |
+--------------------------------------+
|i10 : alpha3 = getLocalA1Degree(f, I3)|
|                                      |
|o10 = | -15 |                         |
|                                      |
|o10 : GrothendieckWittClass           |
+--------------------------------------+

We can then use the isIsomorphicForm,  method to verify
that the local, degrees sum to the global,
degree.

+---------------------------------------------------+
|i11 : alpha' = addGW(alpha1, addGW(alpha2, alpha3))|
|                                                   |
|o11 = | -5 -7 0  0   |                             |
|      | -7 -2 0  0   |                             |
|      | 0  0  65 0   |                             |
|      | 0  0  0  -15 |                             |
|                                                   |
|o11 : GrothendieckWittClass                        |
+---------------------------------------------------+
|i12 : isIsomorphicForm(alpha,alpha')               |
|                                                   |
|o12 = true                                         |
+---------------------------------------------------+
|i13 : beta' = getSumDecomposition alpha'           |
|                                                   |
|o13 = | 1 0  0 0  |                                |
|      | 0 -1 0 0  |                                |
|      | 0 0  1 0  |                                |
|      | 0 0  0 -1 |                                |
|                                                   |
|o13 : GrothendieckWittClass                        |
+---------------------------------------------------+

Authors
=======

  * Nikita Borisov (see https://www.math.upenn.edu/people/nikita-borisov )
    <nborisov@sas.upenn.edu>
  * Thomas Brazelton (see https://tbrazel.github.io/ )
    <brazelton@math.harvard.edu>
  * Frenly Espino (see https://www.math.upenn.edu/people/frenly-espino )
    <frenly@sas.upenn.edu>
  * Tom Hagedorn (see https://hagedorn.pages.tcnj.edu/ ) <hagedorn@tcnj.edu>
  * Zhaobo Han (see https://www.linkedin.com/in/zhaobo-han-77b1301a2/ )
    <zbtomhan@sas.upenn.edu>
  * Jordy Lopez Garcia (see https://jordylopez27.github.io/ )
    <jordy.lopez@tamu.edu>
  * Joel Louwsma (see https://www.joellouwsma.com/ ) <jlouwsma@niagara.edu>
  * Wern Juin Gabriel Ong (see https://wgabrielong.github.io/ )
    <gong@bowdoin.edu>
  * Andrew Tawfeek (see https://www.atawfeek.com/ ) <atawfeek@uw.edu>

Certification a gold star
=========================

Version 1.1 of this package was accepted for publication in volume 14 (see
https://msp.org/jsag/2024/14-1/ ) of Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 2024-08-07, in the article
$\mathbb{A}^1$-Brouwer degrees in Macaulay2 (see
https://msp.org/jsag/2024/14-1/p15.xhtml ) (DOI: 10.2140/jsag.2024.14.175 (see
https://doi.org/10.2140/jsag.2024.14.175 )). That version can be obtained from
the journal (see https://msp.org/jsag/2024/14-1/jsag-v14-n1-x15-
A1BrouwerDegrees.zip ).

Version
=======

This documentation describes version 1.1 of A1BrouwerDegrees.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{A1BrouwerDegreesSource,                                                |
|  title = {{A1BrouwerDegrees: A1-Brouwer degree computations. Version~1.1}}, |
|  author = {Nikita Borisov and Thomas Brazelton and Frenly Espino and Tom Hag|
|  howpublished = {A \emph{Macaulay2} package available at                    |
|    \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages}} |
|}                                                                            |
|                                                                             |
|@article{A1BrouwerDegreesArticle,                                            |
|  title = {{$\mathbb{A}^1$-Brouwer degrees in \emph{Macaulay2}}},            |
|  author = {Nikita Borisov and Thomas Brazelton and Frenly Espino and Tom Hag|
|  journal = {Journal of Software for Algebra and Geometry},                  |
|  volume = {14},                                                             |
|  year = {2024},                                                             |
|}                                                                            |
|-----------------------------------------------------------------------------|
|edorn and Zhaobo Han and Jordy Lopez Garcia and Joel Louwsma and Wern Juin   |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|edorn and Zhaobo Han and Jordy Lopez Garcia and Joel Louwsma and Wern Juin   |
|-----------------------------------------------------------------------------|
|Gabriel Ong and Andrew Tawfeek},                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|Gabriel Ong and Andrew Tawfeek},                                             |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * GrothendieckWittClass -- a new type,
        intended to capture the isomorphism class of an element of the
        Grothendieck-Witt ring of a base field
  * Functions and commands
      * addGW -- the direct sum of two Grothendieck-Witt classes
      * diagonalizeViaCongruence, --
        diagonalizes a symmetric matrix via congruence
      * getAnisotropicDimension -- returns the
        anisotropic dimension of a symmetric bilinear form
      * getAnisotropicDimensionQQp, --
        returns the anisotropic dimension of a rational symmetric bilinear form
        over the p-adic rational numbers
      * getAnisotropicPart -- returns the
        anisotropic part of a Grothendieck-Witt class
      * getBaseField -- the base field of a
        Grothendieck-Witt class
      * getDiagonalClass -- produces a diagonalized
        form for any Grothendieck-Witt class, with simplified terms on the
        diagonal
      * getDiagonalEntries -- extracts a list of
        diagonal entries for a GrothendieckWittClass
      * getGlobalA1Degree -- computes the global
        A1-Brouwer degree of a list of n polynomials in n variables over a
        field k
      * getHasseWittInvariant -- computes the
        Hasse-Witt invariant at a prime p for the quadratic form of the
        Grothendieck-Witt class
      * getHilbertSymbol -- computes the Hilbert
        symbol of two rational numbers at a prime
      * getHilbertSymbolReal -- computes the
        Hilbert symbol of two rational numbers over the real numbers
      * getIntegralDiscriminant -- computes the
        integral discriminant for a rational symmetric bilinear form
      * getLocalA1Degree -- computes a local
        A1-Brouwer degree of a list of n polynomials in n variables over a
        field k at a prime ideal in the zero locus
      * getLocalAlgebraBasis -- produces a basis
        for a local finitely generated algebra over a field k
      * getMatrix -- the underlying matrix of a
        Grothendieck-Witt class
      * getPadicValuation -- p-adic valuation of a
        rational number
      * getRank -- calculates the rank of a symmetric bilinear
        form
      * getRelevantPrimes -- outputs a list
        containing all primes p where the Hasse-Witt invariant of a symmetric
        bilinear form is nontrivial
      * getSignature -- computes the signature of a
        symmetric bilinear form over the real numbers or rational numbers
      * getSumDecomposition -- produces a
        simplified diagonal representative of a Grothendieck-Witt class
      * getSumDecompositionString -- produces
        a simplified diagonal representative of a Grothendieck-Witt class
      * getWittIndex -- returns the Witt index of a
        symmetric bilinear form
      * isAnisotropic -- determines whether a
        Grothendieck-Witt class is anisotropic
      * isIsomorphicForm -- determines whether two
        Grothendieck-Witt classes over CC, RR, QQ, or a finite field of
        characteristic not 2 are isomorphic.
      * isIsotropic -- determines whether a
        Grothendieck-Witt class is isotropic
      * makeDiagonalForm -- the Grothendieck-Witt
        class of a diagonal form
      * makeGWClass -- the Grothendieck-Witt class of a
        symmetric matrix
      * makeHyperbolicForm -- the Grothendieck-Witt
        class of a hyperbolic form
      * makePfisterForm -- the Grothendieck-Witt class
        of a Pfister form
      * multiplyGW -- the tensor product of two
        Grothendieck-Witt classes
  * Methods
      * "addGW(GrothendieckWittClass,GrothendieckWittClass)" -- see
        addGW, -- the direct sum of two Grothendieck-Witt classes
      * "diagonalizeViaCongruence(Matrix)" -- see
        diagonalizeViaCongruence, -- diagonalizes a
        symmetric matrix via congruence
      * "getAnisotropicDimension(GrothendieckWittClass)" -- see
        getAnisotropicDimension, -- returns the
        anisotropic dimension of a symmetric bilinear form
      * "getAnisotropicDimension(Matrix)" -- see getAnisotropicDimension,
        -- returns the anisotropic dimension of a
        symmetric bilinear form
      * "getAnisotropicDimensionQQp(GrothendieckWittClass,ZZ)" -- see
        getAnisotropicDimensionQQp, -- returns the
        anisotropic dimension of a rational symmetric bilinear form over the
        p-adic rational numbers
      * "getAnisotropicPart(GrothendieckWittClass)" -- see
        getAnisotropicPart, -- returns the anisotropic part
        of a Grothendieck-Witt class
      * "getAnisotropicPart(Matrix)" -- see getAnisotropicPart,
        -- returns the anisotropic part of a
        Grothendieck-Witt class
      * "getBaseField(GrothendieckWittClass)" -- see getBaseField,
        -- the base field of a Grothendieck-Witt class
      * "getDiagonalClass(GrothendieckWittClass)" -- see
        getDiagonalClass, -- produces a diagonalized form for
        any Grothendieck-Witt class, with simplified terms on the diagonal
      * "getDiagonalEntries(GrothendieckWittClass)" -- see
        getDiagonalEntries, -- extracts a list of diagonal
        entries for a GrothendieckWittClass
      * "getGlobalA1Degree(List)" -- see getGlobalA1Degree,
        -- computes the global A1-Brouwer degree of a list
        of n polynomials in n variables over a field k
      * "getHasseWittInvariant(GrothendieckWittClass,ZZ)" -- see
        getHasseWittInvariant, -- computes the
        Hasse-Witt invariant at a prime p for the quadratic form of the
        Grothendieck-Witt class
      * "getHasseWittInvariant(List,ZZ)" -- see getHasseWittInvariant,
        -- computes the Hasse-Witt invariant at a prime
        p for the quadratic form of the Grothendieck-Witt class
      * "getHilbertSymbol(QQ,QQ,ZZ)" -- see getHilbertSymbol,
        -- computes the Hilbert symbol of two rational
        numbers at a prime
      * "getHilbertSymbol(QQ,ZZ,ZZ)" -- see getHilbertSymbol,
        -- computes the Hilbert symbol of two rational
        numbers at a prime
      * "getHilbertSymbol(ZZ,QQ,ZZ)" -- see getHilbertSymbol,
        -- computes the Hilbert symbol of two rational
        numbers at a prime
      * "getHilbertSymbol(ZZ,ZZ,ZZ)" -- see getHilbertSymbol,
        -- computes the Hilbert symbol of two rational
        numbers at a prime
      * "getHilbertSymbolReal(QQ,QQ)" -- see getHilbertSymbolReal,
        -- computes the Hilbert symbol of two rational
        numbers over the real numbers
      * "getHilbertSymbolReal(QQ,ZZ)" -- see getHilbertSymbolReal,
        -- computes the Hilbert symbol of two rational
        numbers over the real numbers
      * "getHilbertSymbolReal(ZZ,QQ)" -- see getHilbertSymbolReal,
        -- computes the Hilbert symbol of two rational
        numbers over the real numbers
      * "getHilbertSymbolReal(ZZ,ZZ)" -- see getHilbertSymbolReal,
        -- computes the Hilbert symbol of two rational
        numbers over the real numbers
      * "getIntegralDiscriminant(GrothendieckWittClass)" -- see
        getIntegralDiscriminant, -- computes the
        integral discriminant for a rational symmetric bilinear form
      * "getLocalA1Degree(List,Ideal)" -- see getLocalA1Degree,
        -- computes a local A1-Brouwer degree of a list of n
        polynomials in n variables over a field k at a prime ideal in the zero
        locus
      * "getLocalAlgebraBasis(List,Ideal)" -- see getLocalAlgebraBasis,
        -- produces a basis for a local finitely
        generated algebra over a field k
      * "getMatrix(GrothendieckWittClass)" -- see getMatrix,
        -- the underlying matrix of a Grothendieck-Witt class
      * "getPadicValuation(QQ,ZZ)" -- see getPadicValuation,
        -- p-adic valuation of a rational number
      * "getPadicValuation(ZZ,ZZ)" -- see getPadicValuation,
        -- p-adic valuation of a rational number
      * "getRank(GrothendieckWittClass)" -- see getRank, --
        calculates the rank of a symmetric bilinear form
      * "getRank(Matrix)" -- see getRank, -- calculates the rank
        of a symmetric bilinear form
      * "getRelevantPrimes(GrothendieckWittClass)" -- see
        getRelevantPrimes, -- outputs a list containing all
        primes p where the Hasse-Witt invariant of a symmetric bilinear form is
        nontrivial
      * "getSignature(GrothendieckWittClass)" -- see getSignature,
        -- computes the signature of a symmetric bilinear form
        over the real numbers or rational numbers
      * "getSumDecomposition(GrothendieckWittClass)" -- see
        getSumDecomposition, -- produces a simplified
        diagonal representative of a Grothendieck-Witt class
      * "getSumDecompositionString(GrothendieckWittClass)" -- see
        getSumDecompositionString, -- produces a
        simplified diagonal representative of a Grothendieck-Witt class
      * "getWittIndex(GrothendieckWittClass)" -- see getWittIndex,
        -- returns the Witt index of a symmetric bilinear form
      * "net(GrothendieckWittClass)" -- see GrothendieckWittClass,
        -- a new type, intended to capture the
        isomorphism class of an element of the Grothendieck-Witt ring of a base
        field
      * "texMath(GrothendieckWittClass)" -- see GrothendieckWittClass,
        -- a new type, intended to capture the
        isomorphism class of an element of the Grothendieck-Witt ring of a base
        field
      * "isAnisotropic(GrothendieckWittClass)" -- see isAnisotropic,
        -- determines whether a Grothendieck-Witt class is
        anisotropic
      * "isAnisotropic(Matrix)" -- see isAnisotropic, --
        determines whether a Grothendieck-Witt class is anisotropic
      * "isIsomorphicForm(GrothendieckWittClass,GrothendieckWittClass)" -- see
        isIsomorphicForm, -- determines whether two
        Grothendieck-Witt classes over CC, RR, QQ, or a finite field of
        characteristic not 2 are isomorphic.
      * "isIsomorphicForm(Matrix,Matrix)" -- see isIsomorphicForm,
        -- determines whether two Grothendieck-Witt classes
        over CC, RR, QQ, or a finite field of characteristic not 2 are
        isomorphic.
      * "isIsotropic(GrothendieckWittClass)" -- see isIsotropic,
        -- determines whether a Grothendieck-Witt class is
        isotropic
      * "isIsotropic(Matrix)" -- see isIsotropic, --
        determines whether a Grothendieck-Witt class is isotropic
      * "makeDiagonalForm(InexactFieldFamily,QQ)" -- see
        makeDiagonalForm, -- the Grothendieck-Witt class of a
        diagonal form
      * "makeDiagonalForm(InexactFieldFamily,RingElement)" -- see
        makeDiagonalForm, -- the Grothendieck-Witt class of a
        diagonal form
      * "makeDiagonalForm(InexactFieldFamily,Sequence)" -- see
        makeDiagonalForm, -- the Grothendieck-Witt class of a
        diagonal form
      * "makeDiagonalForm(InexactFieldFamily,ZZ)" -- see
        makeDiagonalForm, -- the Grothendieck-Witt class of a
        diagonal form
      * "makeDiagonalForm(Ring,QQ)" -- see makeDiagonalForm,
        -- the Grothendieck-Witt class of a diagonal form
      * "makeDiagonalForm(Ring,RingElement)" -- see makeDiagonalForm,
        -- the Grothendieck-Witt class of a diagonal form
      * "makeDiagonalForm(Ring,Sequence)" -- see makeDiagonalForm,
        -- the Grothendieck-Witt class of a diagonal form
      * "makeDiagonalForm(Ring,ZZ)" -- see makeDiagonalForm,
        -- the Grothendieck-Witt class of a diagonal form
      * "makeGWClass(Matrix)" -- see makeGWClass, -- the
        Grothendieck-Witt class of a symmetric matrix
      * "makeHyperbolicForm(InexactFieldFamily)" -- see
        makeHyperbolicForm, -- the Grothendieck-Witt class
        of a hyperbolic form
      * "makeHyperbolicForm(InexactFieldFamily,ZZ)" -- see
        makeHyperbolicForm, -- the Grothendieck-Witt class
        of a hyperbolic form
      * "makeHyperbolicForm(Ring)" -- see makeHyperbolicForm,
        -- the Grothendieck-Witt class of a hyperbolic form
      * "makeHyperbolicForm(Ring,ZZ)" -- see makeHyperbolicForm,
        -- the Grothendieck-Witt class of a hyperbolic form
      * "makePfisterForm(InexactFieldFamily,QQ)" -- see makePfisterForm,
        -- the Grothendieck-Witt class of a Pfister form
      * "makePfisterForm(InexactFieldFamily,RingElement)" -- see
        makePfisterForm, -- the Grothendieck-Witt class of a
        Pfister form
      * "makePfisterForm(InexactFieldFamily,Sequence)" -- see
        makePfisterForm, -- the Grothendieck-Witt class of a
        Pfister form
      * "makePfisterForm(InexactFieldFamily,ZZ)" -- see makePfisterForm,
        -- the Grothendieck-Witt class of a Pfister form
      * "makePfisterForm(Ring,QQ)" -- see makePfisterForm,
        -- the Grothendieck-Witt class of a Pfister form
      * "makePfisterForm(Ring,RingElement)" -- see makePfisterForm,
        -- the Grothendieck-Witt class of a Pfister form
      * "makePfisterForm(Ring,Sequence)" -- see makePfisterForm,
        -- the Grothendieck-Witt class of a Pfister form
      * "makePfisterForm(Ring,ZZ)" -- see makePfisterForm,
        -- the Grothendieck-Witt class of a Pfister form
      * "multiplyGW(GrothendieckWittClass,GrothendieckWittClass)" -- see
        multiplyGW, -- the tensor product of two Grothendieck-Witt
        classes

For the programmer
==================

The object A1BrouwerDegrees, is a package (Macaulay2Doc),
defined in A1BrouwerDegrees.m2, with auxiliary files in
A1BrouwerDegrees/.

-------------------------------------------------------------------------------

The source of this document is in A1BrouwerDegrees.m2:200:0.

addGW -- the direct sum of two Grothendieck-Witt classes
********************************************************

  * Usage:
        addGW(beta, gamma)
  * Inputs:
      * beta, a Grothendieck-Witt Class, the
        isomorphism class of a non-degenerate symmetric bilinear form
        represented by a matrix M
      * gamma, a Grothendieck-Witt Class, the
        isomorphism class of a non-degenerate symmetric bilinear form
        represented by a matrix N
  * Outputs:
      * a Grothendieck-Witt Class, the
        isomorphism class of the direct sum of the bilinear forms represented
        by the matrices M and N

Description
===========

This computes the direct sum of the Grothendieck-Witt classes beta and gamma.

+-----------------------------------+
|i1 : M = matrix(QQ, {{1,0},{0,1}});|
|                                   |
|              2       2            |
|o1 : Matrix QQ  <-- QQ             |
+-----------------------------------+
|i2 : N = matrix(QQ, {{1,2},{2,5}});|
|                                   |
|              2       2            |
|o2 : Matrix QQ  <-- QQ             |
+-----------------------------------+
|i3 : beta = makeGWClass M;         |
+-----------------------------------+
|i4 : gamma = makeGWClass N;        |
+-----------------------------------+
|i5 : addGW(beta, gamma)            |
|                                   |
|o5 = | 1 0 0 0 |                   |
|     | 0 1 0 0 |                   |
|     | 0 0 1 2 |                   |
|     | 0 0 2 5 |                   |
|                                   |
|o5 : GrothendieckWittClass         |
+-----------------------------------+

See also
========

  * GrothendieckWittClass -- a new type, intended
    to capture the isomorphism class of an element of the Grothendieck-Witt
    ring of a base field
  * makeGWClass -- the Grothendieck-Witt class of a
    symmetric matrix
  * multiplyGW -- the tensor product of two
    Grothendieck-Witt classes

Ways to use addGW:
==================

  * "addGW(GrothendieckWittClass,GrothendieckWittClass)"

For the programmer
==================

The object addGW, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GrothendieckWittClassesDoc.m2:128:0.

diagonalizeViaCongruence -- diagonalizes a symmetric matrix via congruence
**************************************************************************

  * Usage:
        diagonalizeViaCongruence M
  * Inputs:
      * M, a matrix (Macaulay2Doc), a symmetric matrix over any
        field
  * Outputs:
      * a matrix (Macaulay2Doc), a diagonal matrix congruent to M

Description
===========

Given a symmetric matrix $M$ over any field, this command gives a diagonal
matrix congruent to $M$. Note that the order in which the diagonal terms appear
is not specified.

+---------------------------------------+
|i1 : M = matrix(GF(17), {{7,9},{9,6}});|
|                                       |
|                   2            2      |
|o1 : Matrix (GF 17)  <-- (GF 17)       |
+---------------------------------------+
|i2 : diagonalizeViaCongruence M        |
|                                       |
|o2 = | 7 0  |                          |
|     | 0 -8 |                          |
|                                       |
|                   2            2      |
|o2 : Matrix (GF 17)  <-- (GF 17)       |
+---------------------------------------+

See also
========

  * getDiagonalClass -- produces a diagonalized form
    for any Grothendieck-Witt class, with simplified terms on the diagonal
  * getDiagonalEntries -- extracts a list of
    diagonal entries for a GrothendieckWittClass

Ways to use diagonalizeViaCongruence:
=====================================

  * "diagonalizeViaCongruence(Matrix)"

For the programmer
==================

The object diagonalizeViaCongruence, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/MatrixMethodsDoc.m2:18:0.

getAnisotropicDimension -- returns the anisotropic dimension of a symmetric bilinear form
*****************************************************************************************

  * Usage:
        getAnisotropicDimension beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, over a
        field $k$ where $k$ is $\mathbb{Q}$, $ \mathbb{R}$, $\mathbb{C}$, or a
        finite field of characteristic not 2
  * Outputs:
      * an integer (Macaulay2Doc), the rank of the anisotropic part
        of $\beta$

Description
===========

By the Witt Decomposition Theorem, any non-degenerate form decomposes uniquely
as $\beta \cong n \mathbb{H} \oplus \beta_a$ where the form $\beta_a$ is
anisotropic. The rank of $\beta_a$ is called the anisotropic dimension of
$\beta$.

The anisotropic dimension of a form defined over the rational numbers is the
maximum of the anistropic dimension at each of the completions,
of $\mathbb{Q}$.

See also
========

  * getWittIndex -- returns the Witt index of a symmetric
    bilinear form
  * getAnisotropicDimensionQQp -- returns
    the anisotropic dimension of a rational symmetric bilinear form over the
    p-adic rational numbers
  * getAnisotropicPart -- returns the anisotropic
    part of a Grothendieck-Witt class

Ways to use getAnisotropicDimension:
====================================

  * "getAnisotropicDimension(GrothendieckWittClass)"
  * "getAnisotropicDimension(Matrix)"

For the programmer
==================

The object getAnisotropicDimension, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/AnisotropicDimensionDoc.m2:35:0.

getAnisotropicDimensionQQp -- returns the anisotropic dimension of a rational symmetric bilinear form over the p-adic rational numbers
**************************************************************************************************************************************

  * Usage:
        getAnisotropicDimensionQQp(beta, p)
  * Inputs:
      * beta, a Grothendieck-Witt Class, over
        $\mathbb{Q}$
      * p, an integer (Macaulay2Doc), a prime number
  * Outputs:
      * an integer (Macaulay2Doc), the rank of the anisotropic part
        of $\beta$ over $\mathbb{Q}_p$

Description
===========

This is an implementation of [KC18, Algorithm 8], which computes the
anisotropic dimension of rational forms over the $p$-adic rational numbers.
Note that any form of rank $\ge 5$ is isotropic, so this method will always
return 0, 1, 2, 3, or 4.

Citations:

  * [KC18] P. Koprowski, A. Czogala, Computing with quadratic forms over number
    fields, Journal of Symbolic Computation, 2018.

See also
========

  * getAnisotropicDimension -- returns the
    anisotropic dimension of a symmetric bilinear form

Ways to use getAnisotropicDimensionQQp:
=======================================

  * "getAnisotropicDimensionQQp(GrothendieckWittClass,ZZ)"

For the programmer
==================

The object getAnisotropicDimensionQQp, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/AnisotropicDimensionDoc.m2:19:0.

getAnisotropicPart -- returns the anisotropic part of a Grothendieck-Witt class
*******************************************************************************

  * Usage:
        getAnisotropicPart beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, a
        symmetric bilinear form defined over $\mathbb{Q}$, $ \mathbb{R}$,
        $\mathbb{C}$, or a finite field of characteristic not 2
  * Outputs:
      * a Grothendieck-Witt Class, the
        anisotropic part of $\beta$

Description
===========

By the Witt Decomposition Theorem, any non-degenerate form decomposes uniquely
as $\beta \cong n \mathbb{H} \oplus \beta_a$ where the form $\beta_a$ is
anisotropic. We compute the anisotropic part $\beta_a$ inductively by reference
to its anisotropic dimension. Over the complex
numbers and real numbers this is straightforward, and over finite fields it is
a fairly routine computation. Over the rational numbers some more sophisticated
algorithms are needed from the literature. For this we implement algorithms
developed for number fields by Koprowski and Rothkegel [KR23].

+---------------------------------------------------+
|i1 : alpha = makeDiagonalForm(QQ, (3,-3,2,5,1,-9));|
+---------------------------------------------------+
|i2 : getAnisotropicPart alpha                      |
|                                                   |
|o2 = | 2 0 |                                       |
|     | 0 5 |                                       |
|                                                   |
|o2 : GrothendieckWittClass                         |
+---------------------------------------------------+

Citations:

  * [KR23] P. Koprowski and B. Rothkegel, The anisotropic part of a quadratic
    form over a number field, Journal of Symbolic Computation, 2023.

See also
========

  * getAnisotropicDimension -- returns the
    anisotropic dimension of a symmetric bilinear form
  * getWittIndex -- returns the Witt index of a symmetric
    bilinear form
  * getSumDecomposition -- produces a simplified
    diagonal representative of a Grothendieck-Witt class
  * getSumDecompositionString -- produces a
    simplified diagonal representative of a Grothendieck-Witt class

Ways to use getAnisotropicPart:
===============================

  * "getAnisotropicPart(GrothendieckWittClass)"
  * "getAnisotropicPart(Matrix)"

For the programmer
==================

The object getAnisotropicPart, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/DecompositionDoc.m2:85:0.

getBaseField -- the base field of a Grothendieck-Witt class
***********************************************************

  * Usage:
        getBaseField beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, the
        isomorphism class of a non-degenerate symmetric bilinear form over a
        field of characteristic not 2
  * Outputs:
      * a ring (Macaulay2Doc), the base field of the
        Grothendieck-Witt class beta

Description
===========

Given the isomorphism class of a symmetric bilinear form, beta, this command
outputs the base field of the form.

+--------------------------------------------------+
|i1 : beta = makeGWClass matrix(QQ, {{0,2},{2,0}});|
+--------------------------------------------------+
|i2 : getBaseField beta                            |
|                                                  |
|o2 = QQ                                           |
|                                                  |
|o2 : Ring                                         |
+--------------------------------------------------+

See also
========

  * GrothendieckWittClass -- a new type, intended
    to capture the isomorphism class of an element of the Grothendieck-Witt
    ring of a base field

Ways to use getBaseField:
=========================

  * "getBaseField(GrothendieckWittClass)"

For the programmer
==================

The object getBaseField, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GrothendieckWittClassesDoc.m2:105:0.

getDiagonalClass -- produces a diagonalized form for any Grothendieck-Witt class, with simplified terms on the diagonal
***********************************************************************************************************************

  * Usage:
        getDiagonalClass beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, over
        $\mathbb{Q}$, $ \mathbb{R}$, $\mathbb{C}$, or a finite field of
        characteristic not 2
  * Outputs:
      * a Grothendieck-Witt Class, a form
        isomorphic to $\beta$ with a diagonal Gram matrix

Description
===========

Given a symmetric bilinear form, this method uses the
diagonalizeViaCongruence, command in order to produce
a diagonal symmetric bilinear form isomorphic to $\beta$, with reduced square
classes appearing as the diagonal entries.

+----------------------------------------------------------------+
|i1 : M = matrix(QQ, {{9,1,7,4},{1,10,3,2},{7,3,6,7},{4,2,7,5}});|
|                                                                |
|              4       4                                         |
|o1 : Matrix QQ  <-- QQ                                          |
+----------------------------------------------------------------+
|i2 : beta = makeGWClass M;                                      |
+----------------------------------------------------------------+
|i3 : getDiagonalClass beta                                      |
|                                                                |
|o3 = | 1 0  0   0   |                                           |
|     | 0 89 0   0   |                                           |
|     | 0 0  445 0   |                                           |
|     | 0 0  0   -55 |                                           |
|                                                                |
|o3 : GrothendieckWittClass                                      |
+----------------------------------------------------------------+

Note that the  GrothendieckWittClass, type caches
diagonal versions of a form once they've been computed. We can recover this
quickly in the following way.

+--------------------------------+
|i4 : beta.cache.getDiagonalClass|
|                                |
|o4 = | 1 0  0   0   |           |
|     | 0 89 0   0   |           |
|     | 0 0  445 0   |           |
|     | 0 0  0   -55 |           |
|                                |
|o4 : GrothendieckWittClass      |
+--------------------------------+

See also
========

  * diagonalizeViaCongruence -- diagonalizes a
    symmetric matrix via congruence
  * getDiagonalEntries -- extracts a list of
    diagonal entries for a GrothendieckWittClass

Ways to use getDiagonalClass:
=============================

  * "getDiagonalClass(GrothendieckWittClass)"

For the programmer
==================

The object getDiagonalClass, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/SimplifiedRepresentativesDoc.m2:23:0.

getDiagonalEntries -- extracts a list of diagonal entries for a GrothendieckWittClass
*************************************************************************************

  * Usage:
        getDiagonalEntries beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, over a
        field of characteristic not 2
  * Outputs:
      * L, a list (Macaulay2Doc),  of elements $a_i\in k$, where $i
        = 1,\dots,n $, such that $\beta \cong \langle a_1,\ldots,a_n\rangle$

Description
===========

Given a diagonal form, getDiagonalEntries will extract the elements along the
diagonal.

+-------------------------------------------------------------+
|i1 : beta = makeGWClass matrix(QQ, {{3,0,0},{0,2,0},{0,0,7}})|
|                                                             |
|o1 = | 3 0 0 |                                               |
|     | 0 2 0 |                                               |
|     | 0 0 7 |                                               |
|                                                             |
|o1 : GrothendieckWittClass                                   |
+-------------------------------------------------------------+
|i2 : getDiagonalEntries beta                                 |
|                                                             |
|o2 = {3, 2, 7}                                               |
|                                                             |
|o2 : List                                                    |
+-------------------------------------------------------------+

If the form is not given with a diagonal representative, this method will first
diagonalize it.

+--------------------------------------------------------------+
|i3 : gamma = makeGWClass matrix(RR, {{0,0,1},{0,1,0},{1,0,0}})|
|                                                              |
|o3 = | 0 0 1 |                                                |
|     | 0 1 0 |                                                |
|     | 1 0 0 |                                                |
|                                                              |
|o3 : GrothendieckWittClass                                    |
+--------------------------------------------------------------+
|i4 : getDiagonalEntries gamma                                 |
|                                                              |
|o4 = {2, 1, -.5}                                              |
|                                                              |
|o4 : List                                                     |
+--------------------------------------------------------------+

See also
========

  * getDiagonalClass -- produces a diagonalized form
    for any Grothendieck-Witt class, with simplified terms on the diagonal
  * diagonalizeViaCongruence -- diagonalizes a
    symmetric matrix via congruence

Ways to use getDiagonalEntries:
===============================

  * "getDiagonalEntries(GrothendieckWittClass)"

For the programmer
==================

The object getDiagonalEntries, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/SimplifiedRepresentativesDoc.m2:47:0.

getGlobalA1Degree -- computes the global A1-Brouwer degree of a list of n polynomials in n variables over a field k
*******************************************************************************************************************

  * Usage:
        getGlobalA1Degree L
  * Inputs:
      * L, a list (Macaulay2Doc), of polynomials $f = (f_1, \ldots,
        f_n)$ in the polynomial ring $k[x_1,\ldots,x_n]$ where $k$ is
        $\mathbb{Q}$, $\mathbb{C}$, or a finite field of characteristic not 2.
        Over $\mathbb{R},$ the user is prompted to instead do the computation
        over $\mathbb{Q}$ and then base change to $\mathbb{R}$.
  * Outputs:
      * a Grothendieck-Witt Class, the class
        $\text{deg}^{\mathbb{A}^1}(f)$ in the Grothendieck-Witt ring
        $\text{GW}(k)$

Description
===========

Given an endomorphism of affine space $f=(f_1,\dots ,f_n) \colon \mathbb{A}^n_k
\to \mathbb{A}^n_k$ with isolated zeros, we may compute its
$\mathbb{A}^1$-Brouwer degree valued in the Grothendieck-Witt ring
$\text{GW}(k)$.

The $\mathbb{A}^1$-Brouwer degree first defined by Morel [M12] is an
algebro-geometric enrichment of the classical topological Brouwer degree. Using
the tools of motivic homotopy theory, one may associate to an endomorphism of
affine space the isomorphism class of a symmetric bilinear form whose
invariants encode geometric data about how the morphism transforms space.

Such an association appears in the work of Eisenbud-Levine [EL77] and
Khimshiashvili [K77], wherein the authors develop a symmetric bilinear form
whose signature computes the local degree of a smooth map of real manifolds in
the case where the Jacobian may vanish on an affine chart. This was proven to
agree with Morel's $\mathbb{A}^1$-Brouwer degree in work of Kass and Wickelgren
[KW19]. A similar production of a symmetric bilinear form is given by work of
Scheja and Storch [SS76], which develops a symmetric bilinear form attached to
a complete intersection. This was also shown to align with the
$\mathbb{A}^1$-Brouwer degree in [BW23].

Following recent work of B. McKean and Pauli [BMP23], the
$\mathbb{A}^1$-Brouwer degree can be computed as a multivariate Bezoutian
bilinear form. The algorithms for producing such a form are developed here.

+--------------------------+
|i1 : QQ[x];               |
+--------------------------+
|i2 : f = {x^2 + 1};       |
+--------------------------+
|i3 : getGlobalA1Degree f  |
|                          |
|o3 = | 0 1 |              |
|     | 1 0 |              |
|                          |
|o3 : GrothendieckWittClass|
+--------------------------+

The previous example produces a rank two form with signature zero. This
corresponds to the fact that the degree of the complex map
$\mathbb{C}\to\mathbb{C},\ z\mapsto z^2$ has degree two, while the associated
real map $\mathbb{R}\to\mathbb{R},\ x\mapsto x^2$ has global degree zero.

Following [M21] we may think about the $\mathbb{A}^1$-Brouwer degree
$\text{deg}^{\mathbb{A}^1}(f)$ as a quadratically enriched intersection
multiplicity of the hyperplanes $V(f_1)\cap \cdots \cap V(f_n).$ As a toy
example, consider the curve $y=x(x-1)(x+1)$ intersecting the $x$-axis.

+----------------------------+
|i4 : QQ[x,y];               |
+----------------------------+
|i5 : f = {x^3 - x^2 - y, y};|
+----------------------------+
|i6 : getGlobalA1Degree f    |
|                            |
|o6 = | 0  -1 1 |            |
|     | -1 1  0 |            |
|     | 1  0  0 |            |
|                            |
|o6 : GrothendieckWittClass  |
+----------------------------+

The rank of this form is three, as cubics over the complex numbers have three
roots counted with multiplicity. This form has signature one, which indicates
that when the cubic intersects the $x$-axis, when the three points of
intersection are counted with a sign corresponding to a right hand rule, the
sum equals one.

The global $\mathbb{A}^1$-Brouwer degree can be computed as a sum over the
local degrees, at the points in the zero locus of the
morphism. In the previous example, we see that $V(f)$ consists of three points
on the affine line. We can compute local degrees at all of these and verify
that the local degrees sum to the global degree:

+-----------------------------------------------------------------------------+
|i7 : QQ[x,y];                                                                |
+-----------------------------------------------------------------------------+
|i8 : f = {x^3 - x^2 - y, y};                                                 |
+-----------------------------------------------------------------------------+
|i9 : point1 = ideal(x - 1, y);                                               |
|                                                                             |
|o9 : Ideal of QQ[x..y]                                                       |
+-----------------------------------------------------------------------------+
|i10 : point2 = ideal(x, y);                                                  |
|                                                                             |
|o10 : Ideal of QQ[x..y]                                                      |
+-----------------------------------------------------------------------------+
|i11 : getGlobalA1Degree f                                                    |
|                                                                             |
|o11 = | 0  -1 1 |                                                            |
|      | -1 1  0 |                                                            |
|      | 1  0  0 |                                                            |
|                                                                             |
|o11 : GrothendieckWittClass                                                  |
+-----------------------------------------------------------------------------+
|i12 : getLocalA1Degree(f, point1)                                            |
|                                                                             |
|o12 = | 1 |                                                                  |
|                                                                             |
|o12 : GrothendieckWittClass                                                  |
+-----------------------------------------------------------------------------+
|i13 : getLocalA1Degree(f, point2)                                            |
|                                                                             |
|o13 = | 0  -1 |                                                              |
|      | -1 1  |                                                              |
|                                                                             |
|o13 : GrothendieckWittClass                                                  |
+-----------------------------------------------------------------------------+
|i14 : isIsomorphicForm(getGlobalA1Degree f, addGW(getLocalA1Degree(f,        |
|                                                                             |
|o14 = true                                                                   |
|-----------------------------------------------------------------------------|
|point1), getLocalA1Degree(f, point2)))                                       |
+-----------------------------------------------------------------------------+

Citations:

  * [BW23] T. Bachmann, K. Wickelgren, Euler classes: six-functors formalism,
    dualities, integrality and linear subspaces of complete intersections, J.
    Inst. Math. Jussieu, 2023.
  * [EL77] D. Eisenbud, H. Levine, An algebraic formula for the degree of a
    C^infinity map germ, Annals of Mathematics, 1977.
  * [K77] G. Khimshiashvili, The local degree of a smooth mapping, Sakharth.
    SSR Mcn. Akad. Moambe, 1977.
  * [KW19] J. Kass, K. Wickelgren, The class of Eisenbud-Khimshashvili-Levine
    is the local A1-Brouwer degree, Duke Math J., 2019.
  * [M21] S. McKean, An arithmetic enrichment of Bezout's Theorem, Math. Ann.,
    2021.
  * [M12] F. Morel, A1-Algebraic topology over a field, Springer Lecture Notes
    in Mathematics, 2012.
  * [BMP23] T. Brazelton, S. McKean, S. Pauli, Bezoutians and the A1-Degree,
    Algebra & Number Theory, 2023.
  * [SS76] S. Scheja, S. Storch, Uber Spurfunktionen bei vollstandigen
    Durchschnitten, J. Reine Angew. Math., 1975.

See also
========

  * getLocalA1Degree -- computes a local A1-Brouwer
    degree of a list of n polynomials in n variables over a field k at a prime
    ideal in the zero locus
  * getSumDecomposition -- produces a simplified
    diagonal representative of a Grothendieck-Witt class
  * getSumDecompositionString -- produces a
    simplified diagonal representative of a Grothendieck-Witt class

Ways to use getGlobalA1Degree:
==============================

  * "getGlobalA1Degree(List)"

For the programmer
==================

The object getGlobalA1Degree, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/LocalGlobalDegreesDoc.m2:61:0.

getHasseWittInvariant -- computes the Hasse-Witt invariant at a prime p for the quadratic form of the Grothendieck-Witt class
*****************************************************************************************************************************

  * Usage:
        getHasseWittInvariant(beta, p)
  * Inputs:
      * beta, a Grothendieck-Witt Class, denoted
        by $\beta\in\text{GW}(\mathbb{Q})$
      * p, an integer (Macaulay2Doc), a prime number
  * Outputs:
      * an integer (Macaulay2Doc), the Hasse-Witt invariant of
        $\beta$ at the prime $p$

Description
===========

The Hasse-Witt invariant of a diagonal form $\langle a_1,\ldots,a_n\rangle$
over a field $K$ is defined to be the product $\prod_{i<j}
\left(a_i,a_j\right)_p $ where $(-,-)_p$ is the Hilbert symbol.

The Hasse-Witt invariant of a form will be equal to 1 for almost all primes. In
particular, after diagonalizing a form $\beta \cong \left\langle
a_1,\ldots,a_n\right\rangle$ the Hasse-Witt invariant at a prime $p$ will be 1
automatically if $p\nmid a_i$ for all $i$. Thus we only have to compute the
Hasse-Witt invariant at primes dividing diagonal entries.

+----------------------------------------------------------------+
|i1 : beta = makeGWClass matrix(QQ, {{1,4,7},{4,3,-1},{7,-1,5}});|
+----------------------------------------------------------------+
|i2 : getHasseWittInvariant(beta, 7)                             |
|                                                                |
|o2 = 1                                                          |
+----------------------------------------------------------------+

See also
========

  * isIsomorphicForm -- determines whether two
    Grothendieck-Witt classes over CC, RR, QQ, or a finite field of
    characteristic not 2 are isomorphic.
  * getRelevantPrimes -- outputs a list containing
    all primes p where the Hasse-Witt invariant of a symmetric bilinear form is
    nontrivial

Ways to use getHasseWittInvariant:
==================================

  * "getHasseWittInvariant(GrothendieckWittClass,ZZ)"
  * "getHasseWittInvariant(List,ZZ)"

For the programmer
==================

The object getHasseWittInvariant, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GWInvariantsDoc.m2:59:0.

getHilbertSymbol -- computes the Hilbert symbol of two rational numbers at a prime
**********************************************************************************

  * Usage:
        getHilbertSymbol(a, b, p)
  * Inputs:
      * a, a rational number (Macaulay2Doc), a nonzero integer or
        rational number, considered as an element of $\mathbb{Q}_p$
      * b, a rational number (Macaulay2Doc), a nonzero integer or
        rational number, considered as an element of $\mathbb{Q}_p$
      * p, an integer (Macaulay2Doc), a prime number
  * Outputs:
      * an integer (Macaulay2Doc), the Hilbert symbol $(a,b)_p$

Description
===========

The Hasse-Witt invariant of a diagonal form $\langle a_1,\ldots,a_n\rangle$
over a field $k$ is defined to be the product $\prod_{i<j}  \left( a_i,a_j
\right)_p$ where $(-,-)_p$ is the Hilbert symbol ([S73, Chapter III]) computed
as follows:

$(a,b)_p = \begin{cases} 1 & \text{if }z^2 = ax^2 + by^2 \text{ has a nonzero
solution in } K^3 \\ -1 & \text{otherwise.} \end{cases}$

Consider the following example, where we observe that $z^2 = 2x^2 + y^2$ does
admit nonzero solutions mod 7, in particular $(x,y,z) = (1,0,3),$ and then by
Hensel's lemma, has a solution over $\mathbb{Q}_7$.

+----------------------------+
|i1 : getHilbertSymbol(2,1,7)|
|                            |
|o1 = 1                      |
+----------------------------+

In contrast, since $z^2 = 7x^2 + 3y^2$ does not have a  nonzero solution mod 7,
the Hilbert symbol will be $-1.$

+----------------------------+
|i2 : getHilbertSymbol(7,3,7)|
|                            |
|o2 = -1                     |
+----------------------------+

Over $\mathbb{Q}_2$ the equation $z^2 = 2x^2 + 2y^2$ has a non-trivial
solution, whereas the equation $z^2=2x^2+3y^2$ does not. Hence, their Hilbert
symbols are 1 and -1, respectively.

+----------------------------+
|i3 : getHilbertSymbol(2,2,2)|
|                            |
|o3 = 1                      |
+----------------------------+
|i4 : getHilbertSymbol(2,3,2)|
|                            |
|o4 = -1                     |
+----------------------------+

Computing Hasse-Witt invariants is a key step in classifying symmetric bilinear
forms over the rational numbers, and in particular certifying their
(an)isotropy.

Citations:

  * [S73] J.P. Serre, A course in arithmetic, Springer-Verlag, 1973.
  * [MH73] Milnor and Husemoller, Symmetric bilinear forms, Springer-Verlag,
    1973.

See also
========

  * getHilbertSymbolReal -- computes the Hilbert
    symbol of two rational numbers over the real numbers
  * getHasseWittInvariant -- computes the
    Hasse-Witt invariant at a prime p for the quadratic form of the
    Grothendieck-Witt class

Ways to use getHilbertSymbol:
=============================

  * "getHilbertSymbol(QQ,QQ,ZZ)"
  * "getHilbertSymbol(QQ,ZZ,ZZ)"
  * "getHilbertSymbol(ZZ,QQ,ZZ)"
  * "getHilbertSymbol(ZZ,ZZ,ZZ)"

For the programmer
==================

The object getHilbertSymbol, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/HilbertSymbolsDoc.m2:44:0.

getHilbertSymbolReal -- computes the Hilbert symbol of two rational numbers over the real numbers
*************************************************************************************************

  * Usage:
        getHilbertSymbolReal(a, b)
  * Inputs:
      * a, a rational number (Macaulay2Doc), a nonzero integer or
        rational number, considered as an element of $\mathbb{R}$
      * b, a rational number (Macaulay2Doc), a nonzero integer or
        rational number, considered as an element of $\mathbb{R}$
  * Outputs:
      * an integer (Macaulay2Doc), the Hilbert symbol
        $(a,b)_{\mathbb{R}}$

Description
===========

The Hasse-Witt invariant of a diagonal form $\langle a_1,\ldots,a_n\rangle$
over a field $k$ is defined to be the product $\prod_{i<j}  \left( a_i,a_j
\right)_{\mathbb{R}}$ where $(-,-)_{\mathbb{R}}$ is the Hilbert symbol ([S73,
Chapter III]) computed as follows:

$(a,b)_{\mathbb{R}} = \begin{cases} 1 & z^2 = ax^2 + by^2 \text{ has a nonzero
solution in } {\mathbb{R}}^3 \\ -1 & \text{otherwise.} \end{cases}$

$(a,b)_{\mathbb{R}}$ will equal 1 unless both $a,\,b$ are negative.

Consider the example, that $z^2=-3x^2-2y^2/3$ does not admit a non-zero
solution. Thus:

+-----------------------------------------+
|i1 : getHilbertSymbolReal(-3, -2/3) == -1|
|                                         |
|o1 = true                                |
+-----------------------------------------+

Computing Hasse-Witt invariants is a key step in classifying symmetric bilinear
forms over the rational numbers, and in particular certifying their
(an)isotropy.

Citations:

  * [S73] J.P. Serre, A course in arithmetic, Springer-Verlag, 1973.
  * [MH73] Milnor and Husemoller, Symmetric bilinear forms, Springer-Verlag,
    1973.

See also
========

  * getHilbertSymbol -- computes the Hilbert symbol of
    two rational numbers at a prime
  * getSignature -- computes the signature of a symmetric
    bilinear form over the real numbers or rational numbers

Ways to use getHilbertSymbolReal:
=================================

  * "getHilbertSymbolReal(QQ,QQ)"
  * "getHilbertSymbolReal(QQ,ZZ)"
  * "getHilbertSymbolReal(ZZ,QQ)"
  * "getHilbertSymbolReal(ZZ,ZZ)"

For the programmer
==================

The object getHilbertSymbolReal, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/HilbertSymbolsDoc.m2:74:0.

getIntegralDiscriminant -- computes the integral discriminant for a rational symmetric bilinear form
****************************************************************************************************

  * Usage:
        getIntegralDiscriminant beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, denoted
        by $\beta\in\text{GW}(\mathbb{Q})$
  * Outputs:
      * an integer (Macaulay2Doc), an integral square class
        representative of $\text{disc}(\beta)$

Description
===========

+----------------------------------------------------------------+
|i1 : beta = makeGWClass matrix(QQ, {{1,4,7},{4,3,-1},{7,-1,5}});|
+----------------------------------------------------------------+
|i2 : getIntegralDiscriminant beta                               |
|                                                                |
|o2 = -269                                                       |
+----------------------------------------------------------------+
|i3 : getDiagonalClass beta                                      |
|                                                                |
|o3 = | 1 0   0    |                                             |
|     | 0 -13 0    |                                             |
|     | 0 0   3497 |                                             |
|                                                                |
|o3 : GrothendieckWittClass                                      |
+----------------------------------------------------------------+

See also
========

  * isIsomorphicForm -- determines whether two
    Grothendieck-Witt classes over CC, RR, QQ, or a finite field of
    characteristic not 2 are isomorphic.

Ways to use getIntegralDiscriminant:
====================================

  * "getIntegralDiscriminant(GrothendieckWittClass)"

For the programmer
==================

The object getIntegralDiscriminant, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GWInvariantsDoc.m2:38:0.

getLocalA1Degree -- computes a local A1-Brouwer degree of a list of n polynomials in n variables over a field k at a prime ideal in the zero locus
**************************************************************************************************************************************************

  * Usage:
        locallA1Degree(L, p)
  * Inputs:
      * L, a list (Macaulay2Doc), of polynomials $f = (f_1, \ldots,
        f_n)$ in the polynomial ring $k[x_1,\ldots,x_n]$ where $k$ is
        $\mathbb{Q}$, $\mathbb{C}$, or a finite field of characteristic not 2.
        Over $\mathbb{R},$ the user is prompted to instead do the computation
        over $\mathbb{Q}$ and then base change to $\mathbb{R}$.
      * p, an ideal (Macaulay2Doc), a prime ideal $p \subset
        k[x_1,\ldots,x_n]$ corresponding to a point in the zero locus $V(f)$
  * Outputs:
      * a Grothendieck-Witt Class, the class
        $\text{deg}_p^{\mathbb{A}^1}(f)$ in the Grothendieck-Witt ring
        $\text{GW}(k)$

Description
===========

Given an endomorphism of affine space $f=(f_1,\dots ,f_n) \colon \mathbb{A}^n_k
\to \mathbb{A}^n_k$ and an isolated zero $p\in V(f)$, we may compute its local
$\mathbb{A}^1$-Brouwer degree valued in the Grothendieck-Witt ring
$\text{GW}(k)$.

For historical and mathematical background, see global A1-degrees.

+----------------------------------------------------------+
|i1 : T1 = QQ[z_1..z_2];                                   |
+----------------------------------------------------------+
|i2 : f1 = {(z_1 - 1)*z_1*z_2, (3/5)*z_1^2 - (17/3)*z_2^2};|
+----------------------------------------------------------+
|i3 : f1GD = getGlobalA1Degree f1;                         |
+----------------------------------------------------------+
|i4 : q = ideal(z_1, z_2);                                 |
|                                                          |
|o4 : Ideal of T1                                          |
+----------------------------------------------------------+
|i5 : r = ideal(z_1-1, z_2^2 - 9/85);                      |
|                                                          |
|o5 : Ideal of T1                                          |
+----------------------------------------------------------+
|i6 : f1LDq = getLocalA1Degree(f1, q)                      |
|                                                          |
|o6 = | 0    0     0    17/3  |                            |
|     | 0    3/5   0    -17/3 |                            |
|     | 0    0     17/3 0     |                            |
|     | 17/3 -17/3 0    0     |                            |
|                                                          |
|o6 : GrothendieckWittClass                                |
+----------------------------------------------------------+
|i7 : f1LDr = getLocalA1Degree(f1, r)                      |
|                                                          |
|o7 = | -3/5 0     |                                       |
|     | 0    -17/3 |                                       |
|                                                          |
|o7 : GrothendieckWittClass                                |
+----------------------------------------------------------+
|i8 : f1LDsum = addGW(f1LDq,f1LDr)                         |
|                                                          |
|o8 = | 0    0     0    17/3  0    0     |                 |
|     | 0    3/5   0    -17/3 0    0     |                 |
|     | 0    0     17/3 0     0    0     |                 |
|     | 17/3 -17/3 0    0     0    0     |                 |
|     | 0    0     0    0     -3/5 0     |                 |
|     | 0    0     0    0     0    -17/3 |                 |
|                                                          |
|o8 : GrothendieckWittClass                                |
+----------------------------------------------------------+

The sum of the local A1-degrees is equal to the global A1-degree:

+-----------------------------------+
|i9 : isIsomorphicForm(f1GD,f1LDsum)|
|                                   |
|o9 = true                          |
+-----------------------------------+

See also
========

  * getGlobalA1Degree -- computes the global
    A1-Brouwer degree of a list of n polynomials in n variables over a field k
  * getSumDecomposition -- produces a simplified
    diagonal representative of a Grothendieck-Witt class
  * getSumDecompositionString -- produces a
    simplified diagonal representative of a Grothendieck-Witt class

Ways to use getLocalA1Degree:
=============================

  * "getLocalA1Degree(List,Ideal)"

For the programmer
==================

The object getLocalA1Degree, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/LocalGlobalDegreesDoc.m2:95:0.

getLocalAlgebraBasis -- produces a basis for a local finitely generated algebra over a field k
**********************************************************************************************

  * Usage:
        getLocalAlgebraBasis(L, p)
  * Inputs:
      * L, a list (Macaulay2Doc), of polynomials $f=(f_1, \dots
        ,f_n)$ over the same ring
      * p, an ideal (Macaulay2Doc), a prime ideal of an isolated
        zero
  * Outputs:
      * a list (Macaulay2Doc), of basis elements of the local
        $k$-algebra $Q_p(f)$

Description
===========

Given an endomorphism of affine space, $f=(f_1,\dots ,f_n)$, given as a list of
polynomials called L and the prime ideal of an isolated zero, this command
returns a list of basis elements of the local k-algebra $Q_p(f)$ by computing a
normal basis for $(I:(I:p^{\infty}))$ (see [S02, Proposition 2.5]).

+--------------------------------+
|i1 : QQ[x,y];                   |
+--------------------------------+
|i2 : f = {x^2 + 1 - y, y};      |
+--------------------------------+
|i3 : p = ideal(x^2 + 1, y);     |
|                                |
|o3 : Ideal of QQ[x..y]          |
+--------------------------------+
|i4 : getLocalAlgebraBasis(f, p) |
|                                |
|o4 = {1, x}                     |
|                                |
|o4 : List                       |
+--------------------------------+

Citations:

  * [S02] B. Sturmfels, Solving Systems of Polynomial Equations, American
    Mathematical Society, 2002.

See also
========

  * getLocalA1Degree -- computes a local A1-Brouwer
    degree of a list of n polynomials in n variables over a field k at a prime
    ideal in the zero locus

Ways to use getLocalAlgebraBasis:
=================================

  * "getLocalAlgebraBasis(List,Ideal)"

For the programmer
==================

The object getLocalAlgebraBasis, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/ArithmeticMethodsDoc.m2:44:0.

getMatrix -- the underlying matrix of a Grothendieck-Witt class
***************************************************************

  * Usage:
        getMatrix beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, the
        isomorphism class of a non-degenerate symmetric bilinear form over a
        field of characteristic not 2
  * Outputs:
      * a ring (Macaulay2Doc), the underlying matrix of the
        Grothendieck-Witt class beta

Description
===========

Given the isomorphism class of a symmetric bilinear form, beta, this command
outputs the underlying matrix of the form.

+--------------------------------------------------+
|i1 : beta = makeGWClass matrix(QQ, {{0,2},{2,0}});|
+--------------------------------------------------+
|i2 : getMatrix beta                               |
|                                                  |
|o2 = | 0 2 |                                      |
|     | 2 0 |                                      |
|                                                  |
|              2       2                           |
|o2 : Matrix QQ  <-- QQ                            |
+--------------------------------------------------+

See also
========

  * GrothendieckWittClass -- a new type, intended
    to capture the isomorphism class of an element of the Grothendieck-Witt
    ring of a base field
  * makeGWClass -- the Grothendieck-Witt class of a
    symmetric matrix

Ways to use getMatrix:
======================

  * "getMatrix(GrothendieckWittClass)"

For the programmer
==================

The object getMatrix, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GrothendieckWittClassesDoc.m2:87:0.

getPadicValuation -- p-adic valuation of a rational number
**********************************************************

  * Usage:
        getPadicValuation(a, p)
  * Inputs:
      * a, a rational number (Macaulay2Doc), a non-zero rational
        number in $\mathbb{Q}_p$
      * p, an integer (Macaulay2Doc), a prime number
  * Outputs:
      * an integer (Macaulay2Doc), $n$ where $a=p^n u$ and $u$ is a
        unit in $\mathbb{Z}_p$

Description
===========

+-----------------------------+
|i1 : a = 363/7;              |
+-----------------------------+
|i2 : getPadicValuation(a, 11)|
|                             |
|o2 = 2                       |
+-----------------------------+

Ways to use getPadicValuation:
==============================

  * "getPadicValuation(QQ,ZZ)"
  * "getPadicValuation(ZZ,ZZ)"

For the programmer
==================

The object getPadicValuation, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/ArithmeticMethodsDoc.m2:17:0.

getRank -- calculates the rank of a symmetric bilinear form
***********************************************************

  * Usage:
        getRank beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, denoted
        by $\beta \in  GW(\mathbb{Q})$ or a symmetric matrix $\beta$
  * Outputs:
      * an integer (Macaulay2Doc), the rank of the form $\beta$

Description
===========

This computes the rank of the form $\beta$

+--------------------------------------------+
|i1 : beta = makeDiagonalForm(QQ, (3,5,7,11))|
|                                            |
|o1 = | 3 0 0 0  |                           |
|     | 0 5 0 0  |                           |
|     | 0 0 7 0  |                           |
|     | 0 0 0 11 |                           |
|                                            |
|o1 : GrothendieckWittClass                  |
+--------------------------------------------+
|i2 : getRank beta                           |
|                                            |
|o2 = 4                                      |
+--------------------------------------------+
+------------------------------------------------+
|i3 : M = matrix(QQ, {{1,4,7},{4,3,-1},{7,-1,5}})|
|                                                |
|o3 = | 1 4  7  |                                |
|     | 4 3  -1 |                                |
|     | 7 -1 5  |                                |
|                                                |
|              3       3                         |
|o3 : Matrix QQ  <-- QQ                          |
+------------------------------------------------+
|i4 : getRank M                                  |
|                                                |
|o4 = 3                                          |
+------------------------------------------------+

See also
========

  * isIsomorphicForm -- determines whether two
    Grothendieck-Witt classes over CC, RR, QQ, or a finite field of
    characteristic not 2 are isomorphic.
  * getSignature -- computes the signature of a symmetric
    bilinear form over the real numbers or rational numbers

Ways to use getRank:
====================

  * "getRank(GrothendieckWittClass)"
  * "getRank(Matrix)"

For the programmer
==================

The object getRank, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GWInvariantsDoc.m2:105:0.

getRelevantPrimes -- outputs a list containing all primes p where the Hasse-Witt invariant of a symmetric bilinear form is nontrivial
*************************************************************************************************************************************

  * Usage:
        getRelevantPrimes beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, denoted
        by $\beta\in\text{GW}(\mathbb{Q})$
  * Outputs:
      * a list (Macaulay2Doc), a finite list of primes
        $(p_1,\ldots,p_r)$ containing all primes $p$ where the Hasse-Witt invariant,
        $\phi_p(\beta)$ is nontrivial

Description
===========

It is a classical result that the Hasse-Witt invariants,
of a quadratic form are equal to 1 for all but finitely
many primes (see e.g. [S73, IV Section 3.3]). As the Hasse-Witt invariants are
computed as a product of Hilbert symbols, of the
pairwise entries appearing on a diagonalization of the symbol, it suffices to
consider primes dividing diagonal entries.

+-------------------------------------------+
|i1 : beta = makeDiagonalForm(QQ, (6,7,22));|
+-------------------------------------------+
|i2 : getRelevantPrimes beta                |
|                                           |
|o2 = {2, 3, 7, 11}                         |
|                                           |
|o2 : List                                  |
+-------------------------------------------+

Citations:

  * [S73] J.P. Serre, A course in arithmetic, Springer-Verlag, 1973.

See also
========

  * getHasseWittInvariant -- computes the
    Hasse-Witt invariant at a prime p for the quadratic form of the
    Grothendieck-Witt class

Ways to use getRelevantPrimes:
==============================

  * "getRelevantPrimes(GrothendieckWittClass)"

For the programmer
==================

The object getRelevantPrimes, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GWInvariantsDoc.m2:83:0.

getSignature -- computes the signature of a symmetric bilinear form over the real numbers or rational numbers
*************************************************************************************************************

  * Usage:
        getSignature beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, a
        symmetric bilinear form defined over $\mathbb{Q}$ or $\mathbb{R}$
  * Outputs:
      * n, an integer (Macaulay2Doc), the signature of the symmetric
        bilinear form $\beta$

Description
===========

Given a symmetric bilinear form, after diagonalizing it, we can consider the
number of positive entries minus the number of negative entries appearing along
the diagonal. This is the signature of a symmetric bilinear form, and is one of
the primary invariants used to classify forms. For more information see
isIsomorphicForm.

+-----------------------------------------------+
|i1 : M = matrix(RR, {{0,0,1},{0,1,0},{1,0,0}});|
|                                               |
|                3         3                    |
|o1 : Matrix RR    <-- RR                       |
|              53        53                     |
+-----------------------------------------------+
|i2 : beta = makeGWClass M;                     |
+-----------------------------------------------+
|i3 : getSignature beta                         |
|                                               |
|o3 = 1                                         |
+-----------------------------------------------+

See also
========

  * isIsomorphicForm -- determines whether two
    Grothendieck-Witt classes over CC, RR, QQ, or a finite field of
    characteristic not 2 are isomorphic.
  * getHilbertSymbolReal -- computes the Hilbert
    symbol of two rational numbers over the real numbers
  * getSumDecomposition -- produces a simplified
    diagonal representative of a Grothendieck-Witt class
  * getSumDecompositionString -- produces a
    simplified diagonal representative of a Grothendieck-Witt class

Ways to use getSignature:
=========================

  * "getSignature(GrothendieckWittClass)"

For the programmer
==================

The object getSignature, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GWInvariantsDoc.m2:19:0.

getSumDecomposition -- produces a simplified diagonal representative of a Grothendieck-Witt class
*************************************************************************************************

  * Usage:
        getSumDecomposition beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, a
        symmetric bilinear form defined over $\mathbb{Q}$, $ \mathbb{R}$,
        $\mathbb{C}$, or a finite field of characteristic not 2
  * Outputs:
      * a Grothendieck-Witt Class, a diagonal
        representative of the Grothendieck Witt class of the input form

Description
===========

Given a symmetric bilinear form beta over $\mathbb{Q},$ $ \mathbb{R},$
$\mathbb{C}$ or a finite field of characteristic not 2, we decompose it as a
sum of some number of hyperbolic and rank one forms.

+-----------------------------------------------------------------------------+
|i1 : M = matrix(RR, {{2.091,2.728,6.747},{2.728,7.329,6.257},{6.747,6.257,   |
|                                                                             |
|                3         3                                                  |
|o1 : Matrix RR    <-- RR                                                     |
|              53        53                                                   |
|-----------------------------------------------------------------------------|
|0.294}});                                                                    |
+-----------------------------------------------------------------------------+
|i2 : beta = makeGWClass M;                                                   |
+-----------------------------------------------------------------------------+
|i3 : getSumDecomposition beta                                                |
|                                                                             |
|o3 = | 1 0 0  |                                                              |
|     | 0 1 0  |                                                              |
|     | 0 0 -1 |                                                              |
|                                                                             |
|o3 : GrothendieckWittClass                                                   |
+-----------------------------------------------------------------------------+

Over $\mathbb{R}$ there are only two square classes and a form is determined
uniquely by its rank and signature [L05, II Proposition 3.2]. A form defined by
the $3\times 3$ Gram matrix M above is isomorphic to the form $\langle
1,-1,1\rangle $.

+--------------------------------------------------------------------+
|i4 : M = matrix(GF(13), {{9,1,7,4},{1,10,3,2},{7,3,6,7},{4,2,7,5}});|
|                                                                    |
|                   4            4                                   |
|o4 : Matrix (GF 13)  <-- (GF 13)                                    |
+--------------------------------------------------------------------+
|i5 : beta = makeGWClass M;                                          |
+--------------------------------------------------------------------+
|i6 : getSumDecomposition beta                                       |
|                                                                    |
|o6 = | 1 0  0 0  |                                                  |
|     | 0 -5 0 0  |                                                  |
|     | 0 0  1 0  |                                                  |
|     | 0 0  0 -1 |                                                  |
|                                                                    |
|o6 : GrothendieckWittClass                                          |
+--------------------------------------------------------------------+

Over $\mathbb{F}_{q}$ forms can similarly be diagonalized, in the above case as
$\langle 1,-1,1,-6 \rangle$.

Citations:

  * [L05] T.Y. Lam, Introduction to quadratic forms over fields, American
    Mathematical Society, 2005.

See also
========

  * getSumDecompositionString -- produces a
    simplified diagonal representative of a Grothendieck-Witt class
  * getAnisotropicPart -- returns the anisotropic
    part of a Grothendieck-Witt class
  * getWittIndex -- returns the Witt index of a symmetric
    bilinear form

Ways to use getSumDecomposition:
================================

  * "getSumDecomposition(GrothendieckWittClass)"

For the programmer
==================

The object getSumDecomposition, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/DecompositionDoc.m2:32:0.

getSumDecompositionString -- produces a simplified diagonal representative of a Grothendieck-Witt class
*******************************************************************************************************

  * Usage:
        getSumDecompositionString beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, a
        symmetric bilinear form defined over $\mathbb{Q}$, $ \mathbb{R}$,
        $\mathbb{C}$, or a finite field of characteristic not 2
  * Outputs:
      * a string (Macaulay2Doc), the decomposition as a sum of
        hyperbolic and rank one forms

Description
===========

Given a symmetric bilinear form beta over a field $k$, we return a simplified
diagonal form of beta.

+-----------------------------------------------------------------------------+
|i1 : M = matrix(RR, {{2.091,2.728,6.747},{2.728,7.329,6.257},{6.747,6.257,   |
|                                                                             |
|                3         3                                                  |
|o1 : Matrix RR    <-- RR                                                     |
|              53        53                                                   |
|-----------------------------------------------------------------------------|
|0.294}});                                                                    |
+-----------------------------------------------------------------------------+
|i2 : beta = makeGWClass M;                                                   |
+-----------------------------------------------------------------------------+
|i3 : getSumDecompositionString beta                                          |
|                                                                             |
|o3 = 1H + <1>                                                                |
+-----------------------------------------------------------------------------+

Over $\mathbb{R}$ there are only two square classes and a form is determined
uniquely by its rank and signature [L05, II Proposition 3.2]. A form defined by
the $3\times 3$ Gram matrix M above is isomorphic to the form $\langle
1,-1,1\rangle $.

+--------------------------------------------------------------------+
|i4 : M = matrix(GF(13), {{9,1,7,4},{1,10,3,2},{7,3,6,7},{4,2,7,5}});|
|                                                                    |
|                   4            4                                   |
|o4 : Matrix (GF 13)  <-- (GF 13)                                    |
+--------------------------------------------------------------------+
|i5 : beta = makeGWClass M;                                          |
+--------------------------------------------------------------------+
|i6 : getSumDecompositionString beta                                 |
|                                                                    |
|o6 = 1H + <1> + <-5>                                                |
+--------------------------------------------------------------------+

Over $\mathbb{F}_{q}$ forms can similarly be diagonalized, in the above case as
$\langle 1,-1,1,-6 \rangle$.

Citations:

  * [L05] T.Y. Lam, Introduction to quadratic forms over fields, American
    Mathematical Society, 2005.

See also
========

  * getSumDecomposition -- produces a simplified
    diagonal representative of a Grothendieck-Witt class
  * getAnisotropicPart -- returns the anisotropic
    part of a Grothendieck-Witt class
  * getWittIndex -- returns the Witt index of a symmetric
    bilinear form

Ways to use getSumDecompositionString:
======================================

  * "getSumDecompositionString(GrothendieckWittClass)"

For the programmer
==================

The object getSumDecompositionString, is a
method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/DecompositionDoc.m2:62:0.

getWittIndex -- returns the Witt index of a symmetric bilinear form
*******************************************************************

  * Usage:
        getWittIndex beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, denoted
        by $\beta\in\text{GW}(k)$ where $k$ is $\mathbb{Q}$, $ \mathbb{R}$,
        $\mathbb{C}$, or a finite field of characteristic not 2
  * Outputs:
      * an integer (Macaulay2Doc), the rank of the totally isotropic
        part of $\beta$

Description
===========

By the Witt Decomposition Theorem, any non-degenerate form decomposes uniquely
as $\beta \cong n \mathbb{H} \oplus \beta_a$ where the form $\beta_a$ is
anisotropic. The integer $n$ is called the Witt index of $\beta$. See for
instance [L05, I.4.3].

Citations:

  * [L05] T.Y. Lam, Introduction to quadratic forms over fields, American
    Mathematical Society, 2005.

See also
========

  * getAnisotropicDimension -- returns the
    anisotropic dimension of a symmetric bilinear form

Ways to use getWittIndex:
=========================

  * "getWittIndex(GrothendieckWittClass)"

For the programmer
==================

The object getWittIndex, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/AnisotropicDimensionDoc.m2:55:0.

GrothendieckWittClass -- a new type, intended to capture the isomorphism class of an element of the Grothendieck-Witt ring of a base field
******************************************************************************************************************************************

Description
===========

A GrothendieckWittClass object is a type of HashTable (Macaulay2Doc),
encoding the isomorphism class of a non-degenerate
symmetric bilinear form $V \times V \to k$ over a field $k$.

Given any basis $e_1,\ldots,e_n$ for $V$ as a $k$-vector space, we can encode
the symmetric bilinear form $\beta$ by how it acts on basis elements. That is,
we can produce a matrix $\left(\beta(e_i,e_j)\right)_{i,j}$. This is called a
Gram matrix for the symmetric bilinear form. A change of basis produces a
congruent Gram matrix, so thus a matrix represents a symmetric bilinear form
uniquely up to matrix congruence.

A GrothendieckWittClass object can be built from a symmetric matrix (Macaulay2Doc),
over a field using the makeGWClass,
method.

+-------------------------------------------------+
|i1 : beta = makeGWClass matrix(QQ, {{0,1},{1,0}})|
|                                                 |
|o1 = | 0 1 |                                     |
|     | 1 0 |                                     |
|                                                 |
|o1 : GrothendieckWittClass                       |
+-------------------------------------------------+
|i2 : class beta                                  |
|                                                 |
|o2 = GrothendieckWittClass                       |
|                                                 |
|o2 : Type                                        |
+-------------------------------------------------+

The underlying matrix representative of a form can be recovered via the
getMatrix, command or the matrix command, and its underlying field
can be recovered using getBaseField.

+-----------------------+
|i3 : getMatrix beta    |
|                       |
|o3 = | 0 1 |           |
|     | 1 0 |           |
|                       |
|              2       2|
|o3 : Matrix QQ  <-- QQ |
+-----------------------+
|i4 : getBaseField beta |
|                       |
|o4 = QQ                |
|                       |
|o4 : Ring              |
+-----------------------+

For computational purposes, it is often desirable to diagonalize a Gram matrix.
Any symmetric bilinear form admits a diagonal Gram matrix representative, and
this is implemented via the getDiagonalClass, method.

+--------------------------+
|i5 : getDiagonalClass beta|
|                          |
|o5 = | 2 0  |             |
|     | 0 -2 |             |
|                          |
|o5 : GrothendieckWittClass|
+--------------------------+

Once a form has been diagonalized, it is recorded in the cache for
GrothendieckWittClass and can therefore be quickly recovered.

+--------------------------------+
|i6 : beta.cache.getDiagonalClass|
|                                |
|o6 = | 2 0  |                   |
|     | 0 -2 |                   |
|                                |
|o6 : GrothendieckWittClass      |
+--------------------------------+

We additionally have the following methods which can be applied to
Grothendieck-Witt classes:

  * getRank,: returns the rank of a form,
  * getSignature,: returns the signature of a form over the
    real numbers or rational numbers,
  * getIntegralDiscriminant,: returns an
    integral representative for the discriminant of a form over the rational
    numbers,
  * getHasseWittInvariant,: returns the Hasse-Witt
    invariant for a form over the rational numbers at a particular prime,
  * getAnisotropicDimension,: returns the
    anisotropic dimension of a form,
  * getAnisotropicPart,: returns the anisotropic part
    of a form,
  * getSumDecomposition,: returns a simplified
    diagonal representative of a form,
  * getSumDecompositionString,: returns a
    string to quickly read a form,

and Boolean methods for Grothendieck-Witt classes:

  * isIsotropic,: returns whether the form is isotropic,
  * isAnisotropic,: returns whether the form is
    anisotropic.

Forms can be created via the following methods:

  * makeDiagonalForm,: creates a diagonal form over a
    field out of an element or list of field elements,
  * makeHyperbolicForm,: creates a hyperbolic form
    over a field,
  * makePfisterForm,: creates a Pfister form over a
    field out of an element or list of field elements.

See also
========

  * makeGWClass -- the Grothendieck-Witt class of a
    symmetric matrix
  * getBaseField -- the base field of a Grothendieck-Witt
    class
  * getMatrix -- the underlying matrix of a Grothendieck-Witt
    class
  * getDiagonalClass -- produces a diagonalized form
    for any Grothendieck-Witt class, with simplified terms on the diagonal

Functions and methods returning a Grothendieck-Witt Class:
==========================================================

  * "addGW(GrothendieckWittClass,GrothendieckWittClass)" -- see addGW,
    -- the direct sum of two Grothendieck-Witt classes
  * "getAnisotropicPart(GrothendieckWittClass)" -- see
    getAnisotropicPart, -- returns the anisotropic part of
    a Grothendieck-Witt class
  * "getDiagonalClass(GrothendieckWittClass)" -- see getDiagonalClass,
    -- produces a diagonalized form for any Grothendieck-Witt
    class, with simplified terms on the diagonal
  * "getGlobalA1Degree(List)" -- see getGlobalA1Degree,
    -- computes the global A1-Brouwer degree of a list of n
    polynomials in n variables over a field k
  * "getLocalA1Degree(List,Ideal)" -- see getLocalA1Degree,
    -- computes a local A1-Brouwer degree of a list of n
    polynomials in n variables over a field k at a prime ideal in the zero
    locus
  * "getSumDecomposition(GrothendieckWittClass)" -- see
    getSumDecomposition, -- produces a simplified diagonal
    representative of a Grothendieck-Witt class
  * "makeDiagonalForm(InexactFieldFamily,QQ)" -- see makeDiagonalForm,
    -- the Grothendieck-Witt class of a diagonal form
  * "makeDiagonalForm(InexactFieldFamily,RingElement)" -- see
    makeDiagonalForm, -- the Grothendieck-Witt class of a
    diagonal form
  * "makeDiagonalForm(InexactFieldFamily,Sequence)" -- see
    makeDiagonalForm, -- the Grothendieck-Witt class of a
    diagonal form
  * "makeDiagonalForm(InexactFieldFamily,ZZ)" -- see makeDiagonalForm,
    -- the Grothendieck-Witt class of a diagonal form
  * "makeDiagonalForm(Ring,QQ)" -- see makeDiagonalForm,
    -- the Grothendieck-Witt class of a diagonal form
  * "makeDiagonalForm(Ring,RingElement)" -- see makeDiagonalForm,
    -- the Grothendieck-Witt class of a diagonal form
  * "makeDiagonalForm(Ring,Sequence)" -- see makeDiagonalForm,
    -- the Grothendieck-Witt class of a diagonal form
  * "makeDiagonalForm(Ring,ZZ)" -- see makeDiagonalForm,
    -- the Grothendieck-Witt class of a diagonal form
  * "makeGWClass(Matrix)" -- see makeGWClass, -- the
    Grothendieck-Witt class of a symmetric matrix
  * "makeHyperbolicForm(InexactFieldFamily)" -- see makeHyperbolicForm,
    -- the Grothendieck-Witt class of a hyperbolic form
  * "makeHyperbolicForm(InexactFieldFamily,ZZ)" -- see
    makeHyperbolicForm, -- the Grothendieck-Witt class of a
    hyperbolic form
  * "makeHyperbolicForm(Ring)" -- see makeHyperbolicForm,
    -- the Grothendieck-Witt class of a hyperbolic form
  * "makeHyperbolicForm(Ring,ZZ)" -- see makeHyperbolicForm,
    -- the Grothendieck-Witt class of a hyperbolic form
  * "makePfisterForm(InexactFieldFamily,QQ)" -- see makePfisterForm,
    -- the Grothendieck-Witt class of a Pfister form
  * "makePfisterForm(InexactFieldFamily,RingElement)" -- see
    makePfisterForm, -- the Grothendieck-Witt class of a
    Pfister form
  * "makePfisterForm(InexactFieldFamily,Sequence)" -- see
    makePfisterForm, -- the Grothendieck-Witt class of a
    Pfister form
  * "makePfisterForm(InexactFieldFamily,ZZ)" -- see makePfisterForm,
    -- the Grothendieck-Witt class of a Pfister form
  * "makePfisterForm(Ring,QQ)" -- see makePfisterForm,
    -- the Grothendieck-Witt class of a Pfister form
  * "makePfisterForm(Ring,RingElement)" -- see makePfisterForm,
    -- the Grothendieck-Witt class of a Pfister form
  * "makePfisterForm(Ring,Sequence)" -- see makePfisterForm,
    -- the Grothendieck-Witt class of a Pfister form
  * "makePfisterForm(Ring,ZZ)" -- see makePfisterForm,
    -- the Grothendieck-Witt class of a Pfister form
  * "multiplyGW(GrothendieckWittClass,GrothendieckWittClass)" -- see
    multiplyGW, -- the tensor product of two Grothendieck-Witt
    classes

Methods that use a Grothendieck-Witt Class:
===========================================

  * "getAnisotropicDimension(GrothendieckWittClass)" -- see
    getAnisotropicDimension, -- returns the
    anisotropic dimension of a symmetric bilinear form
  * "getAnisotropicDimensionQQp(GrothendieckWittClass,ZZ)" -- see
    getAnisotropicDimensionQQp, -- returns the
    anisotropic dimension of a rational symmetric bilinear form over the p-adic
    rational numbers
  * "getBaseField(GrothendieckWittClass)" -- see getBaseField,
    -- the base field of a Grothendieck-Witt class
  * "getDiagonalEntries(GrothendieckWittClass)" -- see
    getDiagonalEntries, -- extracts a list of diagonal
    entries for a GrothendieckWittClass
  * "getHasseWittInvariant(GrothendieckWittClass,ZZ)" -- see
    getHasseWittInvariant, -- computes the Hasse-Witt
    invariant at a prime p for the quadratic form of the Grothendieck-Witt
    class
  * "getIntegralDiscriminant(GrothendieckWittClass)" -- see
    getIntegralDiscriminant, -- computes the integral
    discriminant for a rational symmetric bilinear form
  * "getMatrix(GrothendieckWittClass)" -- see getMatrix, --
    the underlying matrix of a Grothendieck-Witt class
  * "getRank(GrothendieckWittClass)" -- see getRank, --
    calculates the rank of a symmetric bilinear form
  * "getRelevantPrimes(GrothendieckWittClass)" -- see getRelevantPrimes,
    -- outputs a list containing all primes p where the
    Hasse-Witt invariant of a symmetric bilinear form is nontrivial
  * "getSignature(GrothendieckWittClass)" -- see getSignature,
    -- computes the signature of a symmetric bilinear form over
    the real numbers or rational numbers
  * "getSumDecompositionString(GrothendieckWittClass)" -- see
    getSumDecompositionString, -- produces a
    simplified diagonal representative of a Grothendieck-Witt class
  * "getWittIndex(GrothendieckWittClass)" -- see getWittIndex,
    -- returns the Witt index of a symmetric bilinear form
  * "net(GrothendieckWittClass)"
  * "texMath(GrothendieckWittClass)"
  * "isAnisotropic(GrothendieckWittClass)" -- see isAnisotropic,
    -- determines whether a Grothendieck-Witt class is
    anisotropic
  * "isIsomorphicForm(GrothendieckWittClass,GrothendieckWittClass)" -- see
    isIsomorphicForm, -- determines whether two
    Grothendieck-Witt classes over CC, RR, QQ, or a finite field of
    characteristic not 2 are isomorphic.
  * "isIsotropic(GrothendieckWittClass)" -- see isIsotropic,
    -- determines whether a Grothendieck-Witt class is isotropic

For the programmer
==================

The object GrothendieckWittClass, is a type (Macaulay2Doc),
with ancestor classes HashTable (Macaulay2Doc),
< Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GrothendieckWittClassesDoc.m2:49:0.

isAnisotropic -- determines whether a Grothendieck-Witt class is anisotropic
****************************************************************************

  * Usage:
        isAnisotropic beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, denoted
        by $\beta\in\text{GW}(k)$, where $k$ is $\mathbb{Q}$, $ \mathbb{R}$,
        $\mathbb{C}$, or a finite field of characteristic not 2
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether $\beta$ is
        anisotropic

Description
===========

Recall a symmetric bilinear form $\beta$ is said to be isotropic if there
exists a nonzero vector $v$ for which $\beta(v,v) = 0$. Witt's decomposition
theorem implies that a non-degenerate symmetric bilinear form decomposes
uniquely into an isotropic and an anisotropic part. Certifying (an)isotropy is
then an important computational problem when working with the Grothendieck-Witt
ring.

Over $\mathbb{C}$, any form of rank two or higher contains a copy of the
hyperbolic form, and hence is isotropic. Thus we can determine anisotropy
simply by a consideration of rank.

+--------------------------------------------------------+
|i1 : isAnisotropic makeGWClass matrix(CC, {{3}})        |
|                                                        |
|o1 = true                                               |
+--------------------------------------------------------+
|i2 : isAnisotropic makeGWClass matrix(CC, {{2,0},{0,5}})|
|                                                        |
|o2 = false                                              |
+--------------------------------------------------------+

Forms over $\mathbb{R}$ are anisotropic if and only if all its diagonal entries
are positive or are negative.

+--------------------------------------------------------------------+
|i3 : isAnisotropic makeGWClass matrix(RR, {{3,0,0},{0,5,0},{0,0,7}})|
|                                                                    |
|o3 = true                                                           |
+--------------------------------------------------------------------+
|i4 : isAnisotropic makeGWClass matrix(RR, {{0,2},{2,0}})            |
|                                                                    |
|o4 = false                                                          |
+--------------------------------------------------------------------+

Over finite fields, a form is anisotropic so long as it is nondegenerate, of
rank $\le 2$ and not isomorphic to the hyperbolic form.

+-----------------------------------------------------------------------+
|i5 : isAnisotropic makeGWClass matrix(GF(7), {{1,0,0},{0,1,0},{0,0,1}})|
|                                                                       |
|o5 = false                                                             |
+-----------------------------------------------------------------------+
|i6 : isAnisotropic makeGWClass matrix(GF(7), {{3,0},{0,3}})            |
|                                                                       |
|o6 = true                                                              |
+-----------------------------------------------------------------------+

Over $\mathbb{Q}$ things become a bit more complicated. We can exploit the
local-to-global principle for isotropy (the Hasse-Minkowski principle), which
states that a form is isotropic over $\mathbb{Q}$ if and only if it is
isotropic over all its completions, meaning all the $p$-adic numbers and
$\mathbb{R}$ [L05, VI.3.1]. We note, however, the classical result that all
forms of rank $\ge 5$ in $\mathbb{Q}_p$ are isotropic [S73, IV Theorem 6]. Thus
isotropy in this range of ranks is equivalent to checking it over the real
numbers.

+-----------------------------------------------------------------------------+
|i7 : beta = makeGWClass matrix(QQ,                                           |
|-----------------------------------------------------------------------------|
|{{1,0,2,0,3},{0,6,1,1,-1},{2,1,5,2,0},{0,1,2,4,-1},{3,-1,0,-1,1}});          |
+-----------------------------------------------------------------------------+
|i8 : isAnisotropic beta                                                      |
|                                                                             |
|o8 = false                                                                   |
+-----------------------------------------------------------------------------+
|i9 : getDiagonalClass beta                                                   |
|                                                                             |
|o9 = | 1 0 0  0  0   |                                                       |
|     | 0 6 0  0  0   |                                                       |
|     | 0 0 30 0  0   |                                                       |
|     | 0 0 0  -5 0   |                                                       |
|     | 0 0 0  0  671 |                                                       |
|                                                                             |
|o9 : GrothendieckWittClass                                                   |
+-----------------------------------------------------------------------------+

For forms of rank $\le 4$ the problem reduces to computing the maximum
anisotropic dimension of the form over local fields. Ternary forms are
isotropic away from primes dividing the coefficients of the form in a diagonal
basis by e.g. [L05, VI.2.5(2)], so there are only finitely many places to
check. Over these relevant primes, isotropy of a form
$\beta \in \text{GW}(\mathbb{Q})$ over $\mathbb{Q}_p$ is equivalent to the
statement that $(-1,-\text{disc}(\beta))_p = H(\beta)$ where $H(\beta)$ denotes
the Hasse-Witt invariant, attached to $\beta$ and
$(-,-)_p$ is the Hilbert Symbol.

A binary form $q$ is isotropic if and only if it is isomorphic to the
hyperbolic form, which implies in particular that the rank, see signature,
and discriminant, of $q$ agree
with that of $\mathbb{H}=\langle 1,-1\rangle$.

Citations:

  * [S73] J.P. Serre, A course in arithmetic, Springer-Verlag, 1973.
  * [L05] T.Y. Lam, Introduction to quadratic forms over fields, American
    Mathematical Society, 2005.

See also
========

  * isIsotropic -- determines whether a Grothendieck-Witt
    class is isotropic
  * getAnisotropicDimension -- returns the
    anisotropic dimension of a symmetric bilinear form
  * getAnisotropicPart -- returns the anisotropic
    part of a Grothendieck-Witt class
  * getWittIndex -- returns the Witt index of a symmetric
    bilinear form

Ways to use isAnisotropic:
==========================

  * "isAnisotropic(GrothendieckWittClass)"
  * "isAnisotropic(Matrix)"

For the programmer
==================

The object isAnisotropic, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/IsotropyDoc.m2:57:0.

isIsomorphicForm -- determines whether two Grothendieck-Witt classes over CC, RR, QQ, or a finite field of characteristic not 2 are isomorphic.
***********************************************************************************************************************************************

  * Usage:
        isIsomorphicForm(alpha, beta)
  * Inputs:
      * alpha, a Grothendieck-Witt Class, denoted
        by $\alpha$ over $\mathbb{Q}$, $ \mathbb{R}$, $\mathbb{C}$, or a finite
        field of characteristic not 2
      * beta, a Grothendieck-Witt Class, denoted
        by $\beta$ over $\mathbb{Q}$, $ \mathbb{R}$, $\mathbb{C}$, or a finite
        field of characteristic not 2
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the two
        Grothendieck-Witt classes are equal as elements of the
        Grothendieck-Witt ring

Description
===========

Given two matrices representing symmetric bilinear forms over a field $k$, it
is a fundamental question to ask when they represent isomorphic symmetric
bilinear forms, i.e. when they are equal in the Grothendieck-Witt ring
$\text{GW}(k)$.

Sylvester's Law of Inertia proves that any symmetric bilinear form can be
diagonalized into a block sum of rank one symmetric bilinear forms. Since the
rank one forms $\langle a \rangle \colon k \times k \to k$, $(x,y) \mapsto axy$
and $\langle ab^2 \rangle \colon k \times k \to k$, $(x,y) \mapsto ab^2xy$
differ by a change of basis in the ground field, it follows they are isomorphic
(provided that $a,b\ne 0$). Thus after diagonalizing a form, it suffices to
consider the square class of each entry appearing along the diagonal. Consider
the following example over the complex numbers:

+---------------------------------------------------------------+
|i1 : alpha = makeGWClass matrix(CC, {{2,3,1},{3,-1,0},{1,0,0}})|
|                                                               |
|o1 = | 2 3  1 |                                                |
|     | 3 -1 0 |                                                |
|     | 1 0  0 |                                                |
|                                                               |
|o1 : GrothendieckWittClass                                     |
+---------------------------------------------------------------+
|i2 : beta = makeGWClass matrix(CC, {{2,4,-1},{4,5,7},{-1,7,9}})|
|                                                               |
|o2 = | 2  4 -1 |                                               |
|     | 4  5 7  |                                               |
|     | -1 7 9  |                                               |
|                                                               |
|o2 : GrothendieckWittClass                                     |
+---------------------------------------------------------------+
|i3 : isIsomorphicForm(alpha,beta)                              |
|                                                               |
|o3 = true                                                      |
+---------------------------------------------------------------+

The two forms are isomorphic since they can be diagonalized, after which they
can be rewritten as the identity matrix after a change of basis, since every
nonzero element is a square over $\mathbb{C}$ (the same is true for any
quadratically closed field). Thus we have that the rank of a form completely
determines it over the complex numbers. That is, it provides an isomorphism
$\text{GW}(\mathbb{C}) \to \mathbb{Z}$.

Over the real numbers, the story is a bit different. Since there are two square
classes of nonzero real numbers, $ \mathbb{R}^\times /
\left(\mathbb{R}^\times\right)^2 \cong \left\{\pm 1\right\}$ we have a further
invariant which classifies symmetric bilinear forms, called the
signature. This is computed as first diagonalizing, then taking
the number of positive entries appearing on the diagonal minus the number of
negative entries appearing on the diagonal.

+----------------------------------------------------------------+
|i4 : gamma = makeGWClass matrix(RR, {{1,0,0},{0,-1,0},{0,0,1}});|
+----------------------------------------------------------------+
|i5 : getSignature gamma                                         |
|                                                                |
|o5 = 1                                                          |
+----------------------------------------------------------------+

Rank and signature completely classify symmetric bilinear forms over the real
numbers.

+---------------------------------------------------------------+
|i6 : delta = makeGWClass matrix(RR, {{0,0,1},{0,1,0},{1,0,0}});|
+---------------------------------------------------------------+
|i7 : isIsomorphicForm(gamma, delta)                            |
|                                                               |
|o7 = true                                                      |
+---------------------------------------------------------------+

Over finite fields, rank is still an invariant of a form, however signature no
longer makes sense as the field is not totally ordered. Instead we consider the
discriminant of the non-degenerate symmetric bilinear form, which is the
determinant of any Gram matrix representing the form. The discriminant is
well-defined once we consider its target as landing in square classes of the
field. $\text{GW}(\mathbb{F}_q) \to \mathbb{F}_q^\times /
\left(\mathbb{F}_q^\times\right)^2$. Over finite fields we compare both rank
and discriminant of forms.

+-------------------------------------------------------------------+
|i8 : alphaF = makeGWClass matrix(GF(7), {{1,2,2},{2,0,1},{2,1,5}}) |
|                                                                   |
|o8 = | 1 2 2  |                                                    |
|     | 2 0 1  |                                                    |
|     | 2 1 -2 |                                                    |
|                                                                   |
|o8 : GrothendieckWittClass                                         |
+-------------------------------------------------------------------+
|i9 : betaF = makeGWClass matrix(GF(7), {{2,5,1},{5,6,1},{1,1,3}})  |
|                                                                   |
|o9 = | 2  -2 1 |                                                   |
|     | -2 -1 1 |                                                   |
|     | 1  1  3 |                                                   |
|                                                                   |
|o9 : GrothendieckWittClass                                         |
+-------------------------------------------------------------------+
|i10 : gammaF = makeGWClass matrix(GF(7), {{0,2,4},{2,3,3},{4,3,1}})|
|                                                                   |
|o10 = | 0  2 -3 |                                                  |
|      | 2  3 3  |                                                  |
|      | -3 3 1  |                                                  |
|                                                                   |
|o10 : GrothendieckWittClass                                        |
+-------------------------------------------------------------------+
|i11 : det getMatrix alphaF                                         |
|                                                                   |
|o11 = 1                                                            |
|                                                                   |
|o11 : GF 7                                                         |
+-------------------------------------------------------------------+
|i12 : det getMatrix betaF                                          |
|                                                                   |
|o12 = -2                                                           |
|                                                                   |
|o12 : GF 7                                                         |
+-------------------------------------------------------------------+
|i13 : det getMatrix gammaF                                         |
|                                                                   |
|o13 = 3                                                            |
|                                                                   |
|o13 : GF 7                                                         |
+-------------------------------------------------------------------+

We see that $\text{disc}(\alpha)$ is a square, while the discriminants of
$\beta$ and $\gamma$ are not. Therefore we see that $\beta \cong \gamma$ but
neither of them are isomorphic to $\alpha$.

+-------------------------------------+
|i14 : isIsomorphicForm(alphaF,betaF) |
|                                     |
|o14 = false                          |
+-------------------------------------+
|i15 : isIsomorphicForm(alphaF,gammaF)|
|                                     |
|o15 = false                          |
+-------------------------------------+
|i16 : isIsomorphicForm(betaF,gammaF) |
|                                     |
|o16 = true                           |
+-------------------------------------+

Over the rational numbers, further invariants must be considered. We first
check if the rank, discriminant, and signature (when considered as a real form)
all agree. If so, we must further check whether the Hasse-Witt invariants agree
at all primes. This is an instance of the Hasse-Minkowski principle which
states that quadratic forms are isomorphic over a global field if and they are
isomorphic over all its completions (see [S73, IV Theorem 7] or [L05, VI.3.3]).

The Hasse-Witt invariant of a diagonal form $\langle a_1,\ldots,a_n\rangle$
over a field $K$ is defined to be the product $\prod_{i<j} \left( \phi(a_i,a_j)
\right)$ where $\phi \colon K \times K \to \left\{\pm 1\right\}$ is any symbol
(see e.g. [MH73, III.5.4] for a definition). It is a classical result of
Hilbert that over a local field of characteristic not equal to two, there is a
unique symbol, $(-,-)_p$ called the Hilbert symbol,
([S73, Chapter III]) computed as follows:

$(a,b)_p = \begin{cases} 1 & z^2 = ax^2 + by^2 \text{ has a nonzero solution in
} K^3 \\ -1 & \text{otherwise.} \end{cases}$

Consider the following example, where we observe that $z^2 = 2x^2 + y^2$ does
admit nonzero solutions mod 7, in particular $(x,y,z) = (1,0,3)$:

+-----------------------------+
|i17 : getHilbertSymbol(2,1,7)|
|                             |
|o17 = 1                      |
+-----------------------------+

The Hasse invariant will be 1 for almost all primes. In particular, after
diagonalizing a form $\beta \cong \left\langle a_1,\ldots,a_n\right\rangle$
then the Hasse invariant at a prime $p$ will automatically be 1 if $p\nmid a_i$
for all $i$. Thus we only have finitely many Hasse invariants to compare for
any pair of symmetric bilinear forms.

+-----------------------------------------------------------------+
|i18 : alphaQ = makeGWClass matrix(QQ, {{1,4,7},{4,3,2},{7,2,-1}})|
|                                                                 |
|o18 = | 1 4 7  |                                                 |
|      | 4 3 2  |                                                 |
|      | 7 2 -1 |                                                 |
|                                                                 |
|o18 : GrothendieckWittClass                                      |
+-----------------------------------------------------------------+
|i19 : betaQ = makeGWClass matrix(QQ, {{0,0,1},{0,2,7},{1,7,3}})  |
|                                                                 |
|o19 = | 0 0 1 |                                                  |
|      | 0 2 7 |                                                  |
|      | 1 7 3 |                                                  |
|                                                                 |
|o19 : GrothendieckWittClass                                      |
+-----------------------------------------------------------------+
|i20 : isIsomorphicForm(alphaQ,betaQ)                             |
|                                                                 |
|o20 = false                                                      |
+-----------------------------------------------------------------+

Citations:

  * [S73] J.P. Serre, A course in arithmetic, Springer-Verlag, 1973.
  * [L05] T.Y. Lam, Introduction to quadratic forms over fields, American
    Mathematical Society, 2005.
  * [MH73] Milnor and Husemoller, Symmetric bilinear forms, Springer-Verlag,
    1973.

See also
========

  * getRank -- calculates the rank of a symmetric bilinear form
  * getSignature -- computes the signature of a symmetric
    bilinear form over the real numbers or rational numbers
  * getIntegralDiscriminant -- computes the
    integral discriminant for a rational symmetric bilinear form
  * getRelevantPrimes -- outputs a list containing
    all primes p where the Hasse-Witt invariant of a symmetric bilinear form is
    nontrivial
  * getHasseWittInvariant -- computes the
    Hasse-Witt invariant at a prime p for the quadratic form of the
    Grothendieck-Witt class
  * getSumDecomposition -- produces a simplified
    diagonal representative of a Grothendieck-Witt class
  * getSumDecompositionString -- produces a
    simplified diagonal representative of a Grothendieck-Witt class

Ways to use isIsomorphicForm:
=============================

  * "isIsomorphicForm(GrothendieckWittClass,GrothendieckWittClass)"
  * "isIsomorphicForm(Matrix,Matrix)"

For the programmer
==================

The object isIsomorphicForm, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/IsomorphismOfFormsDoc.m2:67:0.

isIsotropic -- determines whether a Grothendieck-Witt class is isotropic
************************************************************************

  * Usage:
        isIsotropic beta
  * Inputs:
      * beta, a Grothendieck-Witt Class, denoted
        by $\beta\in\text{GW}(k)$, where $k$ is $\mathbb{Q}$, $ \mathbb{R}$,
        $\mathbb{C}$, or a finite field of characteristic not 2
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether $\beta$ is
        isotropic

Description
===========

This is the negation of the boolean-valued isAnisotropic.
See documentation there.

See also
========

  * isAnisotropic -- determines whether a
    Grothendieck-Witt class is anisotropic
  * getWittIndex -- returns the Witt index of a symmetric
    bilinear form
  * getAnisotropicDimension -- returns the
    anisotropic dimension of a symmetric bilinear form

Ways to use isIsotropic:
========================

  * "isIsotropic(GrothendieckWittClass)"
  * "isIsotropic(Matrix)"

For the programmer
==================

The object isIsotropic, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/IsotropyDoc.m2:14:0.

makeDiagonalForm -- the Grothendieck-Witt class of a diagonal form
******************************************************************

  * Usage:
        makeDiagonalForm(k, a)
        makeDiagonalForm(k, L)
  * Inputs:
      * k, a ring (Macaulay2Doc), a field of characteristic not 2
      * a, a ring element (Macaulay2Doc), any element $a\in
        k$
      * L, a sequence (Macaulay2Doc), of elements $a_{i} \in
        k$, where $i = 1,\dots, n$
  * Outputs:
      * a Grothendieck-Witt Class, the diagonal
        form $\langle a_1,\ldots,a_n\rangle \in \text{GW}(k)$

Description
===========

Given a sequence of elements $a_1,\ldots,a_n \in k$ we can form the diagonal
form $\langle a_1,\ldots,a_n\rangle$ defined to be the block sum of each of the
rank one forms $\langle a_i \rangle \colon k \times k \to k,$ $(x,y) \mapsto
a_i xy$.

+----------------------------------+
|i1 : makeDiagonalForm(QQ, (3,5,7))|
|                                  |
|o1 = | 3 0 0 |                    |
|     | 0 5 0 |                    |
|     | 0 0 7 |                    |
|                                  |
|o1 : GrothendieckWittClass        |
+----------------------------------+

Inputting a ring element, an integer, or a rational number instead of a
sequence will produce a rank one form instead. For instance:

+-----------------------------------+
|i2 : makeDiagonalForm(GF(29), 5/13)|
|                                   |
|o2 = | -13 |                       |
|                                   |
|o2 : GrothendieckWittClass         |
+-----------------------------------+
|i3 : makeDiagonalForm(RR, 2)       |
|                                   |
|o3 = | 2 |                         |
|                                   |
|o3 : GrothendieckWittClass         |
+-----------------------------------+

See also
========

  * getDiagonalClass -- produces a diagonalized form
    for any Grothendieck-Witt class, with simplified terms on the diagonal
  * diagonalizeViaCongruence -- diagonalizes a
    symmetric matrix via congruence
  * getDiagonalEntries -- extracts a list of
    diagonal entries for a GrothendieckWittClass

Ways to use makeDiagonalForm:
=============================

  * "makeDiagonalForm(InexactFieldFamily,QQ)"
  * "makeDiagonalForm(InexactFieldFamily,RingElement)"
  * "makeDiagonalForm(InexactFieldFamily,Sequence)"
  * "makeDiagonalForm(InexactFieldFamily,ZZ)"
  * "makeDiagonalForm(Ring,QQ)"
  * "makeDiagonalForm(Ring,RingElement)"
  * "makeDiagonalForm(Ring,Sequence)"
  * "makeDiagonalForm(Ring,ZZ)"

For the programmer
==================

The object makeDiagonalForm, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/BuildingFormsDoc.m2:25:0.

makeGWClass -- the Grothendieck-Witt class of a symmetric matrix
****************************************************************

  * Usage:
        makeGWClass M
  * Inputs:
      * M, a matrix (Macaulay2Doc), a non-singular symmetric
        matrix defined over an arbitrary field of characteristic not 2
  * Outputs:
      * a Grothendieck-Witt Class, the
        isomorphism class of the non-degenerate symmetric bilinear form
        represented by  $M$

Description
===========

Given a symmetric matrix, $M$, this command outputs an object of type
GrothendieckWittClass. This output has the representing matrix, $M$, and the
base field of the matrix stored in its CacheTable. (Macaulay2Doc),

+------------------------------------------------+
|i1 : M := matrix(QQ, {{0,0,1},{0,1,0},{1,0,0}});|
|                                                |
|              3       3                         |
|o1 : Matrix QQ  <-- QQ                          |
+------------------------------------------------+
|i2 : beta = makeGWClass M                       |
|                                                |
|o2 = | 0 0 1 |                                  |
|     | 0 1 0 |                                  |
|     | 1 0 0 |                                  |
|                                                |
|o2 : GrothendieckWittClass                      |
+------------------------------------------------+

See also
========

  * GrothendieckWittClass -- a new type, intended
    to capture the isomorphism class of an element of the Grothendieck-Witt
    ring of a base field
  * getMatrix -- the underlying matrix of a Grothendieck-Witt
    class
  * getBaseField -- the base field of a Grothendieck-Witt
    class

Ways to use makeGWClass:
========================

  * "makeGWClass(Matrix)"

For the programmer
==================

The object makeGWClass, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GrothendieckWittClassesDoc.m2:69:0.

makeHyperbolicForm -- the Grothendieck-Witt class of a hyperbolic form
**********************************************************************

  * Usage:
        makeHyperbolicForm k
        makeHyperbolicForm(k, n)
  * Inputs:
      * k, a ring (Macaulay2Doc), a field of characteristic not 2
      * n, an integer (Macaulay2Doc), an even number, giving an
        optional rank $n$ for a totally hyperbolic form
  * Outputs:
      * a Grothendieck-Witt Class, the hyperbolic
        form $\mathbb{H} = \langle 1, -1\rangle \in \text{GW}(k)$ or the
        totally hyperbolic form
        $\left(\displaystyle\frac{n}{2}\right)\mathbb{H}$ if an optional rank
        $n$ is specified

Description
===========

By default outputs the rank two hyperbolic form over the input field $k$.

+-----------------------------+
|i1 : makeHyperbolicForm GF(7)|
|                             |
|o1 = | 1 0  |                |
|     | 0 -1 |                |
|                             |
|o1 : GrothendieckWittClass   |
+-----------------------------+

Specifying a rank yields a copy of sums of the rank two hyperbolic form. Only
even rank inputs are accepted.

+------------------------------+
|i2 : makeHyperbolicForm(RR, 4)|
|                              |
|o2 = | 1 0  0 0  |            |
|     | 0 -1 0 0  |            |
|     | 0 0  1 0  |            |
|     | 0 0  0 -1 |            |
|                              |
|o2 : GrothendieckWittClass    |
+------------------------------+

See also
========

  * isAnisotropic -- determines whether a
    Grothendieck-Witt class is anisotropic
  * getSumDecomposition -- produces a simplified
    diagonal representative of a Grothendieck-Witt class
  * getSumDecompositionString -- produces a
    simplified diagonal representative of a Grothendieck-Witt class

Ways to use makeHyperbolicForm:
===============================

  * "makeHyperbolicForm(InexactFieldFamily)"
  * "makeHyperbolicForm(InexactFieldFamily,ZZ)"
  * "makeHyperbolicForm(Ring)"
  * "makeHyperbolicForm(Ring,ZZ)"

For the programmer
==================

The object makeHyperbolicForm, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/BuildingFormsDoc.m2:74:0.

makePfisterForm -- the Grothendieck-Witt class of a Pfister form
****************************************************************

  * Usage:
        makePfisterForm(k, a)
        makePfisterForm(k, L)
  * Inputs:
      * k, a ring (Macaulay2Doc), a field of characteristic not 2
      * a, a ring element (Macaulay2Doc), any element $a\in
        k$
      * L, a sequence (Macaulay2Doc), of elements $L =
        (a_1,\ldots,a_n)$ with $a_i \in k$
  * Outputs:
      * a Grothendieck-Witt Class, the Pfister
        form $\langle\langle a_1,\ldots,a_n\rangle\rangle \in \text{GW}(k)$

Description
===========

Given a sequence of elements $a_1,\ldots,a_n \in k$ we can form the Pfister
form $\langle\langle a_1,\ldots,a_n\rangle\rangle$ defined to be the rank $2^n$
form defined as the product $\langle 1, -a_1\rangle \otimes \cdots \otimes
\langle 1, -a_n \rangle$.

+-------------------------------+
|i1 : makePfisterForm(QQ, (2,6))|
|                               |
|o1 = | 1 0  0  0  |            |
|     | 0 -6 0  0  |            |
|     | 0 0  -2 0  |            |
|     | 0 0  0  12 |            |
|                               |
|o1 : GrothendieckWittClass     |
+-------------------------------+

Inputting a ring element, an integer, or a rational instead of a sequence will
produce a one-fold Pfister form instead. For instance:

+----------------------------------+
|i2 : makePfisterForm(GF(13), -2/3)|
|                                  |
|o2 = | 1 0 |                      |
|     | 0 5 |                      |
|                                  |
|o2 : GrothendieckWittClass        |
+----------------------------------+
|i3 : makePfisterForm(CC, 3)       |
|                                  |
|o3 = | 1 0  |                     |
|     | 0 -3 |                     |
|                                  |
|o3 : GrothendieckWittClass        |
+----------------------------------+

Ways to use makePfisterForm:
============================

  * "makePfisterForm(InexactFieldFamily,QQ)"
  * "makePfisterForm(InexactFieldFamily,RingElement)"
  * "makePfisterForm(InexactFieldFamily,Sequence)"
  * "makePfisterForm(InexactFieldFamily,ZZ)"
  * "makePfisterForm(Ring,QQ)"
  * "makePfisterForm(Ring,RingElement)"
  * "makePfisterForm(Ring,Sequence)"
  * "makePfisterForm(Ring,ZZ)"

For the programmer
==================

The object makePfisterForm, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/BuildingFormsDoc.m2:50:0.

multiplyGW -- the tensor product of two Grothendieck-Witt classes
*****************************************************************

  * Usage:
        multiplyGW(beta, gamma)
  * Inputs:
      * beta, a Grothendieck-Witt Class, the
        isomorphism class of a non-degenerate symmetric bilinear form
        represented by a matrix M
      * gamma, a Grothendieck-Witt Class, the
        isomorphism class of a non-degenerate symmetric bilinear form
        represented by a matrix N
  * Outputs:
      * a Grothendieck-Witt Class, the
        isomorphism class of the tensor product $M\otimes N$ of the bilinear
        forms represented by the matrices M and N

Description
===========

This computes the tensor product $\beta\otimes\gamma$ of the Grothendieck-Witt
classes beta and gamma.

+-----------------------------------+
|i1 : M = matrix(QQ, {{1,0},{0,1}});|
|                                   |
|              2       2            |
|o1 : Matrix QQ  <-- QQ             |
+-----------------------------------+
|i2 : N = matrix(QQ, {{1,2},{2,5}});|
|                                   |
|              2       2            |
|o2 : Matrix QQ  <-- QQ             |
+-----------------------------------+
|i3 : beta = makeGWClass M;         |
+-----------------------------------+
|i4 : gamma = makeGWClass N;        |
+-----------------------------------+
|i5 : multiplyGW(beta, gamma)       |
|                                   |
|o5 = | 1 2 0 0 |                   |
|     | 2 5 0 0 |                   |
|     | 0 0 1 2 |                   |
|     | 0 0 2 5 |                   |
|                                   |
|o5 : GrothendieckWittClass         |
+-----------------------------------+

See also
========

  * GrothendieckWittClass -- a new type, intended
    to capture the isomorphism class of an element of the Grothendieck-Witt
    ring of a base field
  * makeGWClass -- the Grothendieck-Witt class of a
    symmetric matrix
  * addGW -- the direct sum of two Grothendieck-Witt classes

Ways to use multiplyGW:
=======================

  * "multiplyGW(GrothendieckWittClass,GrothendieckWittClass)"

For the programmer
==================

The object multiplyGW, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
A1BrouwerDegrees/Documentation/GrothendieckWittClassesDoc.m2:150:0.