<!--
  construct_basic.xml    Forms package documentation
                                                                  John Bamberg
                                                               and Jan De Beule
                                                                
  Copyright (C) 2021, The University of Western Australia
  Copyright (C) 2021, Vrije Universiteit Brussel

This is the chapter of the documentation describing all of the functions of forms.
-->

<Chapter Label="functionality">
<Heading>Constructing forms and basic functionality</Heading>

In this chapter, all operations to construct sesquilinear and quadratic forms
are listed, along with their basic attributes and properties.

<Section Label="sec:filters">
<Heading>Important filters</Heading>

<ManSection>
<Heading>Categories for forms</Heading>
<Filt Name="IsBilinearForm" Type="Category"/>
<Filt Name="IsHermitianForm" Type="Category"/>
<Filt Name="IsSesquilinearForm" Type="Category"/>
<Filt Name="IsQuadraticForm" Type="Category"/>
<Filt Name="IsForm" Type="Category"/>
<Filt Name="IsTrivialForm" Type="Category"/>
<Description>The categories <C>IsBilinearForm</C> and <C>IsHermitianForm</C> are
categories for bilinear and hermitian forms, respectively. They are disjoint and
are both contained in the category <C>IsSesquilinearForm</C>.
<P/>
Quadratic forms are contained in the category <C>IsQuadraticForm</C>. The
categories <C>IsSesquilinearForm</C> and <C>IsQuadraticForm</C> are disjoint and
are both contained in the category <C>IsForm</C>.
<P/>
The user is allowed to construct the trivial form (mapping all vectors to the
zero element of the field). The trivial form is an object in the category
<C>IsTrivialForm</C>. This category is contained in <C>IsForm</C> and disjoint
from <C>IsSesquilinearForm</C> and <C>IsQuadraticForm</C>.
</Description>
</ManSection>

<ManSection>
<Heading>Representation for forms</Heading>
<Filt Name="IsFormRep" Type="Representation"/>
<Description>Every form is represented by a matrix, 
the base field and a string describing the ``type'' of the form.</Description>
</ManSection>
</Section>

<Section Label="sec:formsbymatrix">
<Heading>Constructing forms using a matrix</Heading>
<ManSection>
<Oper Name="BilinearFormByMatrix" Arg="matrix[, field]"/>
<Returns>a bilinear form</Returns>
<Description>
The argument <A>matrix</A> must be a symmetric, or skew-symmetric, square matrix
over the finite field <A>field</A>. The argument <A>field</A> is an optional
argument, and if it is not given, then we assume that the <E>defining field</E>
of the bilinear form is the smallest field containing the entries of matrix.
Below we give an example where the defining field can make a difference in some
applications. As it is only possible to construct reflexive bilinear forms, it
is checked whether the matrix <A>matrix</A> is symmetric or skew symmetric. If
matrix <A>matrix</A> is not symmetric nor skew symmetric, then an error message
is returned. The output is a bilinear form (i.e., an object in
<C>IsBilinearForm</C>) with Gram matrix <A>matrix</A> and defining field
<A>field</A>. (See <Ref Sect="theory:sesquilinearforms"/> for more on bilinear
forms).
<Example>
<#Include SYSTEM "../examples/include/bilformbymatrix.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="QuadraticFormByMatrix" Arg="matrix[, field]"/>
<Returns>a quadratic form</Returns>
<Description>
The argument <A>matrix</A> must be a square matrix over the finite field
<A>field</A>. The argument <A>field</A> is an optional argument, and if it is
not given, then we assume that the <E>defining field</E> of the bilinear form is
the smallest field containing the entries of matrix. Below we give an example
where the defining field can make a difference in some applications. Any square
matrix determines a quadratic form, but the Gram matrix is recomputed so that it
is an upper triangle matrix. The output is a quadratic form (i.e., an object in
<C>IsQuadraticForm</C>) with defining field <A>field</A>. (See <Ref
Sect="quadforms"/> for more on bilinear forms).
<Example>
<#Include SYSTEM "../examples/include/quadformbymatrix.include"> 
</Example>
The following example shows how using the argument <A>field</A> has influence on
the properties of the constructed form.
<Example>
<#Include SYSTEM "../examples/include/quadformfields.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="HermitianFormByMatrix" Arg="matrix, field"/>
<Returns>a hermitian sesquilinear form</Returns>
<Description>
The argument <A>matrix</A> must be a hermitian square matrix over
the finite field <A>field</A>, and <A>field</A> has square order. 
The field must be specified, since we can
only determine the smallest field containing the entries of <A>matrix</A>. 
As it is only possible to construct reflexive
sesquilinear forms, it is checked whether the matrix is a hermitian matrix, and if
not, an error message is returned. The output is a hermitian sesquilinear form (i.e., an object in
<C>IsHermitianForm</C>) with Gram matrix <A>matrix</A> and
defining field <A>field</A>. (See <Ref Sect="theory:sesquilinearforms"/> for more on hermitian forms).
<Example>
<#Include SYSTEM "../examples/include/hermitianformbymatrix.include"> 
</Example>
</Description>
</ManSection>
</Section>

<Section Label="sec:formsbypolynomial">
<Heading>Constructing forms using a polynomial</Heading>
Suppose that <M>f</M> is a sesquilinear form on an <M>n</M>-dimensional vectorspace. 
Consider a vector <M>x</M> with coordinates <Alt Only="Text"><M>x_1,\ldots,x_{n}</M></Alt>
<Alt Only="LaTeX"><M>x_1,\ldots,x_{n}</M></Alt><Alt Only="HTML MathJax"><M>x_1,\ldots,x_{n}</M></Alt>
<Alt Only="HTML noMathJax">x&lt;sub>1&lt;/sub>,...,x&lt;sub>n&lt;/sub></Alt> with 
<Alt Only="Text"><M>x_i</M></Alt><Alt Only="LaTeX"><M>x_i</M></Alt>
<Alt Only="HTML MathJax"><M>x_i</M></Alt><Alt Only="HTML noMathJax">x&lt;sub>i&lt;/sub></Alt>
indeterminates over the field. Then <M>f(x,x)</M> is a polynomial in <M>n</M> 
indeterminates. When <M>f</M> is alternating, <M>f(x,x)</M> is identically zero, 
but in all other cases, <M>f(x,x)</M> determines <M>f</M> completely.
<P/>
Conversely, suppose that <M>Q</M> is a quadratic form on an <M>n</M>-dimensional vectorspace. 
Consider a vector <M>x</M> with coordinates <Alt Only="Text"><M>x_1,\ldots,x_{n}</M></Alt>
<Alt Only="LaTeX"><M>x_1,\ldots,x_{n}</M></Alt><Alt Only="HTML MathJax"><M>x_1,\ldots,x_{n}</M></Alt>
<Alt Only="HTML noMathJax">x&lt;sub>1&lt;/sub>,...,x&lt;sub>n&lt;/sub></Alt> with 
<Alt Only="Text"><M>x_i</M></Alt><Alt Only="LaTeX"><M>x_i</M></Alt>
<Alt Only="HTML MathJax"><M>x_i</M></Alt><Alt Only="HTML noMathJax">x&lt;sub>i&lt;/sub></Alt>
indeterminates over the field. Then <M>Q(x)</M> is a polynomial in <M>n</M> 
indeterminates, and <M>Q(x)</M> determines <M>Q</M> completely.
<P/>
<Package>Forms</Package> provides functionality to construct bilinear, hermitian and 
quadratic forms using an appropriate polynomial.
<ManSection>
<Oper Name="BilinearFormByPolynomial" Arg="poly, r[, n]"/>
<Returns>a bilinear form</Returns>
<Description>
The argument <A>poly</A> must be a polynomial in the polynomial
ring <A>r</A>. The (optional) last argument is the dimension
for the underlying vector space of the resulting form, which
by default is the number of indeterminates specified by <A>poly</A>. It is
checked whether the polynomial is a homogeneous polynomial of degree two over the
given field, and if not, an error message is returned. It is not possible to 
construct a nontrivial bilinear form from a polynomial in even characteristic. The output is 
a bilinear (orthogonal) form in the category <C>IsBilinearForm</C>. 
(See <Ref Sect="theory:sesquilinearforms"/> for more on bilinear forms).
<Example>
<#Include SYSTEM "../examples/include/bilformbypoly.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="QuadraticFormByPolynomial" Arg="poly, r[, n]"/>
<Returns>a quadratic form</Returns>
<Description>
The argument <A>poly</A> must be a polynomial in the polynomial
ring <A>r</A>. The (optional) last argument is the dimension
for the underlying vector space of the resulting form, which
by default is the number of indeterminates specified by <A>poly</A>. It is
checked whether the polynomial is a homogeneous polynomial of degree two over the
given field, and if not, an error message is returned. The output is a quadratic form in the category
<C>IsQuadraticForm</C>. (See <Ref Sect="quadforms"/> for more on quadratic forms).
<Example>
<#Include SYSTEM "../examples/include/quadformbypoly.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="HermitianFormByPolynomial" Arg="poly, r[, n]"/>
<Returns>an hermitian form</Returns>
<Description>
The argument <A>poly</A> must be a polynomial in the polynomial
ring <A>r</A> defined over a finite field of square order 
<Alt Only="Text"><M>q^2</M></Alt><Alt Only="LaTeX"><M>q^2</M></Alt>
<Alt Only="HTML MathJax"><M>q^2</M></Alt><Alt Only="HTML noMathJax">q&lt;sup>2&lt;/sup></Alt>
The (optional) last argument is the dimension
for the underlying vector space of the resulting form, which
by default is the number of indeterminates specified by <A>poly</A>. It is
checked whether the polynomial is a homogeneous polynomial of degree <M>q+1</M>,
and if not, an error message is returned. The output
is a hermitian form in the category <C>IsHermitianForm</C>.
(See <Ref Sect="theory:sesquilinearforms"/> for more on hermitian forms).
<Example>
<#Include SYSTEM "../examples/include/hermitianformbypoly.include"> 
</Example>
</Description>
</ManSection>

</Section>


<!--
      ATTRIBUTES AND PROPERTIES 
-->

<Section Label="switch">
<Heading>Switching between bilinear and quadratic forms</Heading>
When the characteristic of the field is odd, a homogeneous quadratic polynomial
determines a bilinear form, and a quadratic form. In some situations, when a
quadratic form <M>Q</M> is given, it is useful to consider the bilinear form
<M>f</M> such that <M>f(v,v)=Q(v)</M>, i.e., the bilinear form which is
determined by exactly the same polynomial determining the quadratic form
<M>Q</M>. <Package>Forms</Package> provides functionality to construct a bilinear form <M>f</M> from a given quadratic form
<M>Q</M> such that <M>f(v,v)=Q(v)</M>. Conversely, we can extract a quadratic form 
from a given bilinear form.
<ManSection>
<Oper Name="QuadraticFormByBilinearForm" Arg="form"/>
<Returns>a quadratic form</Returns>
<Description>The argument <M>form</M> is an orthogonal bilinear form (and thus it belongs to
<C>IsBilinearForm</C>), otherwise a ``No method found'' error is returned. 
The output is the quadratic form <M>Q</M> (an object
in <C>IsQuadraticForm</C>), such that <M>Q(v) = form(v,v)</M> for all vectors
<M>v</M> in a vector space equipped with <M>form</M>. An error is returned when the 
characteristic of the field is even, or
when <M>form</M> is not orthogonal.
<Example>
<#Include SYSTEM "../examples/include/quadformbybilform.include"> 
</Example>
Note that the given bilinear form <A>form</A> is <B>not</B> the
associated bilinear form of the constructed quadratic form <M>Q</M>, according to
the definition in Section <Ref Sect="quadforms"/>. We can construct the associated
bilinear forms by using <Ref Oper="AssociatedBilinearForm"/>.
(See <Ref Sect="quadforms"/> for more on quadratic forms).
</Description>
</ManSection>

<ManSection>
<Oper Name="BilinearFormByQuadraticForm" Arg="Q"/>
<Returns>a bilinear form</Returns>
<Description>The argument <M>Q</M> must be a quadratic form (and thus it belongs to
<C>IsQuadraticForm</C>). The output is the orthogonal bilinear form <M>f</M> (an object
in <C>IsBilinearForm</C>), such that <M>f(v,v) = Q(v)</M> for all vectors
<M>v</M> in a vector space equipped with <M>Q</M>. An error is returned when the characteristic of the field is even.
<Example>
<#Include SYSTEM "../examples/include/bilformbyquadform.include"> 
</Example>
Note that the constructed bilinear form <M>f</M> is <B>not</B> the
associated bilinear form of the given quadratic form <M>Q</M>, according to
the definition in Section <Ref Sect="quadforms"/>. We can construct the associated
bilinear forms by using <Ref Oper="AssociatedBilinearForm"/>.
(See <Ref Sect="quadforms"/> for more on quadratic forms).
</Description>
</ManSection>

<ManSection>
<Oper Name="AssociatedBilinearForm" Arg="Q"/>
<Returns>a bilinear form</Returns>
<Description>The argument <M>Q</M> must be a quadratic form (and thus it belongs to
<C>IsQuadraticForm</C>). The output is the associated bilinear form <M>f</M> (an object
in <C>IsBilinearForm</C>), as defined in Section <Ref Sect="quadforms"/>, i.e.
the bilinear form <M>f</M> such that <M>f(v,w) = Q(v+w)-Q(v)-Q(w)</M> for all
vectors <M>v,w</M> in a vector space equipped with <M>Q</M>. 
(See <Ref Sect="quadforms"/> for more on quadratic forms).
<Example>
<#Include SYSTEM "../examples/include/assocbilform.include"> 
</Example>
</Description>
</ManSection>
</Section>

<Section Label="evaluate">
<Heading>Evaluating forms</Heading>
<ManSection>
<Oper Name="EvaluateForm" Arg="f, u[, v]"/>
<Returns>a finite field element</Returns>
<Description>
The argument <A>f</A> is either a sesquilinear or quadratic form
defined over a finite field &gfq;. The other argument is
a pair of vectors or matrices, or a single vector or matrix. In case that <A>u</A> (and <A>v</A> when using three arguments) is a
matrix, its rows represent a basis for the subspace (or subspaces) where <M>f</M> is evaluated in.
This operation evaluates
the form on the given vector or pair of vectors and returns an
element in <M>GF(q)</M>. There is also an overloading
of the operation <A>\^</A> where <F>(u,v)^f</F> represents
<M>f(u,v)</M> in the case that <A>f</A> is sesquilinear, and
<F>u^f</F> stands for <M>f(u)</M> in the quadratic case. So for convenience, the user
may use this compressed version of this operation, which we show in the following example:
<Example>
<#Include SYSTEM "../examples/include/evalform.include"> 
</Example>
</Description>
</ManSection>

</Section>

<Section Label="ortho">
<Heading>Orthogonality, totally isotropic subspaces, and totally singular subspaces</Heading>
<ManSection>
<Oper Name="OrthogonalSubspaceMat" Arg="form, v" Label="for a vector"/>
<Oper Name="OrthogonalSubspaceMat" Arg="form, mat" Label="for a matrix"/>
<Returns>a base of the subspace orthogonal to the given vector or subspace
with relation to the given form</Returns>
<Description>
The argument <A>form</A> is a sesquilinear or quadratic form. For a given vector <A>v</A>,
this operation returns a base of the subspace orthogonal to <A>v</A> with
relation to the sesquilinear <A>form</A> or with relation to the associated
bilinear form of the quadratic form <A>form</A>. For a given matrix <A>mat</A>,
this operation returns a base of the subspace orthogonal to the subspace spanned
by the rows of <A>mat</A> with relation to the sesquilinear <A>form</A> or with relation to the
associated bilinear form of the quadratic form <A>form</A>
<Example>
<#Include SYSTEM "../examples/include/orthogonaltovector.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="IsIsotropicVector" Arg="form, v"/>
<Returns>true or false</Returns> 
<Description>
The operation return <A>true</A> if and only if <A>v</A> is isotropic with
relation to the sesquilinear or quadratic form <A>form</A>.
<Example>
<#Include SYSTEM "../examples/include/isisotropicvector.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="IsSingularVector" Arg="form, v"/>
<Returns>true or false</Returns> 
<Description>
The operation return <A>true</A> if and only if <A>v</A> is singular with
relation to the quadratic form <A>form</A>. Note that only when the
characteristic of the field is odd, the singular vectors with relation to a
quadratic form are the isotropic vectors with relation to its associated form.
<Example>
<#Include SYSTEM "../examples/include/issingularvector.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="IsTotallyIsotropicSubspace" Arg="form, sub"/>
<Returns>true or false</Returns> 
<Description>
The operation return <A>true</A> if and only if the subspace spanned by the
vectors in the list <A>sub</A> is totally isotropic with
relation to the sesquilinear or quadratic form <A>form</A>. Note that when
<A>form</A> is a quadratic form, it is checked whether <A>sub</A> generates a
subspace that is totally isotropic with relation to the associated bilinear form
of <A>form</A>.
<Example>
<#Include SYSTEM "../examples/include/istotallyisotropic.include">
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="IsTotallySingularSubspace" Arg="form, sub"/>
<Returns>true or false</Returns> 
<Description>
The operation return <A>true</A> if and only if the subspace spanned by the
vectors in the list <A>sub</A> is totally singular with
relation to quadratic form <A>form</A>. Note that only when the
characteristic of the field is odd, the totally singular subspaces of given
dimension <M>n</M> with relation to a quadratic form are exactly the totally
isotropic subspaces of dimension <M>n</M> with relation to its associated form.
<Example>
<#Include SYSTEM "../examples/include/istotallysingular.include">
</Example>
</Description>
</ManSection>

</Section>

<Section Label="properties">
<Heading>Attributes and properties of forms</Heading>

<ManSection>
<Prop Name="IsReflexiveForm" Arg="f"/>
<Returns>true or false.</Returns>
<Description>
A sesquilinear form <M>f</M> on a vector space <M>V</M> is <E>reflexive</E><Index Key="Form"
Subkey="Reflexive">Form</Index> if <M>f(v,w)=0 \Rightarrow f(w,v)=0</M> 
for all <M>v,w \in V</M>. 
The argument <M>f</M> must be a sesquilinear form (and thus it belongs to
<C>IsSesquilinearForm</C>). A sesquilinear form <M>f</M> is <E>reflexive</E>
if whenever we have <M>f(u,v)=0</M>, for two vectors <M>u,v</M> in the associated vector space,
then we also have <M>f(v,u)=0</M>. This
attribute simply returns <A>true</A> or <A>false</A> according to whether <A>f</A> is reflexive
or not, and is stored as a property of <A>f</A>. It is not possible in this
version of <Package>Forms</Package> to construct non-reflexive forms.
(See <Ref Sect="theory:sesquilinearforms"/> for more on reflexive sesquilinear forms).
</Description>
</ManSection>

<ManSection>
<Prop Name="IsAlternatingForm" Arg="f"/>
<Returns>true or false.</Returns>
<Description>
A sesquilinear form <M>f</M> on a vector space <M>V</M>
is <E>alternating</E><Index Key="Form" Subkey="Alternating">Form</Index> if
<M>f(v,v)=0</M> for all <M>v \in V</M>.
The argument <M>f</M> must be a sesquilinear form (and thus it belongs to
<C>IsSesquilinearForm</C>). A bilinear form <M>f</M> is <E>alternating</E> if 
<M>f(v,v)=0</M> for all <M>v</M>. This method simply returns <A>true</A> or
<A>false</A> according to whether <A>f</A> is alternating or not, and is stored
as a property of <A>f</A>. (See <Ref Sect="theory:sesquilinearforms"/> for more
on alternating sesquilinear forms).
</Description>
</ManSection>

<ManSection>
<Prop Name="IsSymmetricForm" Arg="f"/>
<Returns>true or false.</Returns>
<Description>
A sesquilinear form <M>f</M> on a vector space <M>V</M> is <E>symmetric</E><Index Key="Form"
Subkey="Symmetric">Form</Index> if <M>f(v,w)=f(w,v)</M> for all <M>v,w \in
V</M>. The argument <M>f</M> must be a sesquilinear form (and thus it belongs to
<C>IsSesquilinearForm</C>). A bilinear form <M>f</M> is <E>symmetric</E> if 
<M>f(u,v)=f(v,u)</M> for all pairs of vectors <M>u</M> and <M>v</M>.  This
attribute simply returns <A>true</A> or <A>false</A> according to whether
<A>f</A> is symmetric or not, and is stored as a property of <A>f</A>.
(See <Ref Sect="theory:sesquilinearforms"/> for more on symmetric sesquilinear forms).
</Description>
</ManSection>

<ManSection>
<Prop Name="IsOrthogonalForm" Arg="f"/>
<Returns>true or false.</Returns>
<Description>
The argument <M>f</M> must be a sesquilinear form (and thus it belongs to
<C>IsSesquilinearForm</C>). A bilinear form <M>f</M> is called <E>orthogonal</E><Index Key="Form"
Subkey="orthogonal">Form</Index>
if the characteristic of the underlying field is odd, and <M>f</M> is a
symmetric form. (See <Ref Sect="theory:sesquilinearforms"/> for more on bilinear forms).
This operation simply returns <A>true</A> or <A>false</A> according to whether <A>f</A> is
an orthogonal bilinear form or not, and is stored as a property of <A>f</A>.
</Description>
</ManSection>

<ManSection>
<Prop Name="IsPseudoForm" Arg="f"/>
<Returns>true or false.</Returns>
<Description>
When the characteristic of the field is odd, we call a form
<M>f</M> <E>orthogonal</E> if and only <M>f</M> is symmetric, and when the
characteristic of the field is even, we call a form <M>f</M> <E>pseudo</E><Index Key="Form"
Subkey="pseudo">Form</Index> if
and only if <M>f</M> is symmetric but not alternating. 
The argument <M>f</M> must be a sesquilinear form (and thus it belongs to
<C>IsSesquilinearForm</C>). (See <Ref Sect="theory:sesquilinearforms"/> for more on pseudo forms).
This method simply returns <A>true</A> or <A>false</A> according to whether <A>f</A> is
a pseudo form or not, and is stored as a property of <A>f</A>.
</Description>
</ManSection>

<ManSection>
<Prop Name="IsSymplecticForm" Arg="f"/>
<Returns>true or false.</Returns>
<Description>
We call a bilinear form <M>f</M> <E>symplectic</E><Index Key="Form" Subkey="symplectic">Form</Index> if and only if <M>f</M> is
alternating. The argument <M>f</M> must be a sesquilinear form (and thus it belongs to
<C>IsSesquilinearForm</C>). (See <Ref Sect="theory:sesquilinearforms"/> for more on symplectic forms).
This method simply returns <A>true</A> or <A>false</A> according to whether <A>f</A> is symplectic
or not, and is stored as a property of <A>f</A>. 
</Description>
</ManSection>

<ManSection>
<Prop Name="IsDegenerateForm" Arg="f"/>
<Returns>true or false.</Returns>
<Description>
The argument <M>f</M> must be a form (and thus it belongs to
<C>IsForm</C>). A sesquilinear form <M>f</M> is <E>degenerate</E> if its radical
is non-trivial. A quadratic form is degenerate if and only if the radical of the
associated bilinear form is non-trivial. Note that degeneracy for quadratic
forms is too restrictive if the characteristic is even. See also <Ref
Oper="IsSingularForm"/>. This
attribute simply returns <A>true</A> or <A>false</A> according to whether <A>f</A> is degenerate
or not, and is stored as a property of <A>f</A>. 
</Description>
</ManSection>

<ManSection>
<Prop Name="IsSingularForm" Arg="f"/>
<Returns>true or false.</Returns>
<Description>
The argument <M>f</M> must be a quadratic form (and thus it belongs to
<C>IsQuadraticForm</C>). A quadratic form <M>f</M> is <E>singular</E> if its
radical is non-trivial. When the characteristic of the field is odd, a quadratic
form is singular if and only if it is degenerate. This is not the case when the
characteristic of the field is even.
This method simply returns <A>true</A> or <A>false</A> according to whether <A>f</A> is singular
or not, and is stored as a property of <A>f</A>. 
</Description>
</ManSection>

<ManSection>
<Attr Name="BaseField" Arg="f"/>
<Returns>the underlying field of <A>f</A>.</Returns>
<Description>
The argument <M>f</M> must be a form (and thus it belongs to
<C>IsForm</C>). The method returns the field which is stored as 
the <E>defining field</E> of <M>f</M>. We sometimes stipulate in 
<Package>Forms</Package> that a form have a defining field,
for mathematical reasons. Clearly, to define a hermitian form
one needs to specify the field of scalars for the vector space that
you wish your hermitian form to act on. The default, if the user
has not specified a field on creation of a form, is the smallest
field containing the entries or coefficients of the input (a matrix or polynomial).
Having a particular defining field for a form can be very useful, for example,
when one wants to find a change of basis from one form to another (isometric) form.
In this case, one needs to know in which &gldq; the base-transition matrix
should be taken.
</Description>
</ManSection>

<ManSection>
<Attr Name="GramMatrix" Arg="f"/>
<Returns>the Gram matrix of <A>f</A>.</Returns>
<Description>
The argument <M>f</M> must be a form (and thus it belongs to
<C>IsForm</C>). This method returns the Gram matrix of <M>f</M>
(see <Ref Sect="theory:sesquilinearforms"/> and <Ref Sect="quadforms"/>).
</Description>
</ManSection>

<ManSection>
<Attr Name="RadicalOfForm" Arg="f"/>
<Returns>The radical of the form <A>f</A>
</Returns>
<Description>
The argument <M>f</M> must be a form (and thus it belongs to
<C>IsForm</C>) on some vector space <M>V</M>. The radical of a sesquilinear form <M>f</M> 
is the subspace consisting of vectors which are orthogonal to every vector, i.e.,
<Alt Only="Text"><Display>Rad(f) = \{v \in V | f(v,w) = 0,\, \forall w \in V\}.</Display></Alt>
<Alt Only="LaTeX"><Display>&rad;(f) = \{v \in V | f(v,w) = 0,\, \forall w \in V\}.</Display></Alt>
<Alt Only="HTML MathJax"><Display>&rad;(f) = \{v \in V | f(v,w) = 0,\, \forall w \in V\}.</Display></Alt>
<Alt Only="HTML noMathJax">&lt;center>Rad(f) = {v &#8712; V | f(v,w) = 0 for all w &#8712; V}.&lt;/center></Alt>
<P/>
The <E>radical</E> of the quadratic form <M>Q</M>, is the intersection
of the set of all singular vectors with relation to <M>Q</M> and the radical of
the associated bilinear form <M>f</M> (see <Ref Oper="AssociatedBilinearForm"/>), i.e.
<Alt Only="Text"><Display>Rad(Q) = \{v \in V | Q(v) = 0\,\, \mathrm{and}\,\, v \in Rad(f)\}.</Display></Alt>
<Alt Only="LaTeX"><Display>&rad;(Q) = \{v \in V | Q(v) = 0\,\, \mathrm{and}\,\, v \in &rad;(f)\}.</Display></Alt>
<Alt Only="HTML MathJax"><Display>&rad;(Q) = \{v \in V | Q(v) = 0\,\, \mathrm{and}\,\, v \in &rad;(f)\}.</Display></Alt>
<Alt Only="HTML noMathJax">&lt;center>Rad(Q) = {v &#8712; V | Q(v) = 0 and v &#8712; Rad(f)}.&lt;/center></Alt>
<Example>
<#Include SYSTEM "../examples/include/radicalofform.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Attr Name="PolynomialOfForm" Arg="f"/>
<Returns>the polynomial associated with <A>f</A>.</Returns>
<Description>
The argument <A>f</A> must be a form (and thus it belongs to
<C>IsForm</C>). All forms, except for bilinear forms in even characteristic, have
an associated polynomial defining a quadratic or hermitian form (see <Ref Sect="theory:sesquilinearforms"/> and <Ref Sect="quadforms"/>).
This method returns the polynomial associated with <A>f</A>, and if not already bound, stores it as a property of <A>f</A>.
<Example> 
<#Include SYSTEM "../examples/include/polyofform.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Attr Name="DiscriminantOfForm" Arg="f"/>
<Returns>a string</Returns>
<Description>
The argument <M>f</M> must be a form (and thus it belongs to <C>IsForm</C>). Given a
quadratic or bilinear form <A>f</A> of even dimension, this operation returns a string: 
``square'' or ``nonsquare''. More specifically, 
let <M>f</M> be a from over &gfq;, and let <M>M</M> be the Gram matrix of <M>f</M>.
Define the <E>discriminant</E> of <M>Q</M> (n.b., <E>quasideterminant</E> in
<Cite Key="Atlas"/>) as `square' if <Alt Only="Text"><M>det(M)</M></Alt><Alt Only="LaTeX"><M>det(M)</M></Alt>
<Alt Only="HTML MathJax"><M>\mathrm{det}(M)</M></Alt><Alt Only="HTML noMathJax">det(M)</Alt> is a square of &gfq;,
and `non-square' otherwise. The discriminant is an invariant of nondegenerate 
orthogonal spaces over finite fields of odd order, up to isometry. 
Thus, discriminants can be used to delineate the isometry
type of an orthogonal form in even (algebraic) dimension. The discriminant of a
hermitian form is not defined, and applying this operation on a hermitian form,
will result in an error message.
<Example>
<#Include SYSTEM "../examples/include/discofform.include"> 
</Example>
</Description>
</ManSection>

</Section>

<Section Label="recognition">
<Heading>Recognition of forms preserved by a classical group</Heading>

In this section, we describe a function that was initially developed by Frank Celler
(and which has now been adapted to <Package>Forms</Package>) for the recognition of
quadratic and sesquilinear forms left invariant by a matrix group. More importantly, we should
stress that this routine differs to that already offered by the <Package>MeatAxe</Package> 
in that it finds sesquilinear forms preserved up to <B>scalars</B>. Eventually, the procedure used
for finding preserved sesquilinear forms does use the <Package>MeatAxe</Package> but 
in some cases it can rule out the existence of preserved forms without calling
the <Package>MeatAxe</Package>. For more information on the algorithm, please see 
<Cite Key="CLGNNPP"/>.

<ManSection>
<Oper Name="PreservedForms" Arg="group"/>
<Returns>a list of forms
</Returns>
<Description>
The argument <A>group</A> is a matrix group. The function uses random methods
to find all of the bilinear, unitary or quadratic forms preserved by <A>group</A> (the
trivial form is also a possibility) up to a scalar. Since the procedure relies on a pseudo-random
generator, the user may need to execute the operation more than once to find
all invariant sesquilinear forms. Note that when possible, a quadratic form will be given.
<Example>
<#Include SYSTEM "../examples/include/preservedforms1.include">
</Example>
The next example demonstrates the impact of randomized methods on the number of preserved forms
returned. For the particular matrix group, two preserved forms are returned after four calls of
the operation.
<Example>
<#Include SYSTEM "../examples/include/preservedforms2.include">
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="PreservedSesquilinearForms" Arg="group"/>
<Returns>a list of forms
</Returns>
<Description>
The argument <A>group</A> is a matrix group. The function uses random methods
to find all of the bilinear or unitary forms preserved by <A>group</A> (the
trivial form is also a possibility) up to a scalar. Since the procedure relies on a pseudo-random
generator, the user may need to execute the operation more than once to find
all invariant sesquilinear forms.
<Example>
<#Include SYSTEM "../examples/include/pres_sesforms1.include"> 
</Example>
Here is another example which shows that this procedure is suitable in some cases where
using the <Package>MeatAxe</Package> is not applicable. Here, our matrix group is the group of similarities
preserving a (hyperbolic) bilinear form on a 6-dimensional vector space over <Alt Only="Text"><M>GF(3)</M></Alt>
<Alt Only="LaTeX"><M>&gf;(3)</M></Alt><Alt Only="HTML MathJax"><M>&gf;(3)</M></Alt>
<Alt Only="HTML noMathJax"><M>GF(3)</M></Alt>.
<Example>
<#Include SYSTEM "../examples/include/pres_sesforms2.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="PreservedQuadraticForms" Arg="group"/>
<Returns>a list of forms
</Returns>
<Description>
The argument <A>group</A> is a matrix group. The function uses random methods
to find all of the quadratic forms preserved by <A>group</A> up to a scalar.
Since the procedure relies on a pseudo-random
generator, the user may need to execute the operation more than once to find
all invariant sesquilinear forms.
<Example>
<#Include SYSTEM "../examples/include/pres_quadform.include">
</Example>
</Description>
</ManSection>

</Section>

<Section Label="trivialform">
<Heading>The trivial form and some of its properties</Heading>

It can be useful to work with trivial a quadratic or sesquilinear form, i.e. a
form mapping all vectors, couples of vectors respectively, to the zero element
of their basefield. As mentioned in Section <Ref Sect="sec:filters"/>,
<Package>Forms</Package> allows the construction of an object in the Category
<C>IsTrivialForm</C>.
<Example>
<#Include SYSTEM "../examples/include/trivialform.include"> 
</Example>
 
As we have seen by the above example, there is only one trivial form for a given
vector space over a finite field, and such a trivial form can result from the
construction of a quadratic form or a sesquilinear form, but the trivial form
itself is none of these, although it can behave as a sesquilinear or a quadratic
form, depending on its arguments. 

<Example>
<#Include SYSTEM "../examples/include/trivialform2.include"> 
</Example>
 
The attributes and properties described in Section <Ref Sect="properties"/> are
all applicable to trivial forms.

<Example>
<#Include SYSTEM "../examples/include/trivialform_prop.include"> 
</Example>
 
</Section>

</Chapter>
