<!--
classicalpolarspaces.xml    FinInG package documentation
                                                                   John Bamberg
                                                                   Anton Betten
                                                                  Philippe Cara
                                                                   Jan De Beule
                                                                 Michel Lavrauw
                                                                Max Neunhoeffer

  Copyright (C) 2018,	Colorado State University
                        Sabancı Üniversitesi
						Università degli Studi di Padova
						Universiteit Gent
						University of St. Andrews
						University of Western Australia
                        Vrije Universiteit Brussel
 
This is the chapter of the documentation describing the classical polar spaces.

-->

<Chapter Label="classicalpolarspaces">
<Heading>Finite Classical Polar Spaces</Heading>

In this chapter we describe how to use <Package>FinInG</Package> to work 
with finite classical polar spaces. 

<Section>
<Heading>Finite Classical Polar Spaces</Heading>

A <E>polar space</E> is a point-line incidence geometry, satisfying the famous 
one-or-all axiom, i.e. for any point <M>P</M>, not incident with a line <M>l</M>,
<M>P</M> is collinear with exactly one point of <M>l</M> or with all points of <M>l</M>.
The axiomatic treatment of polar spaces has its foundations in 
<Cite Key="Veldkamp"/>, <Cite Key="Tits74"/>, and <Cite Key="BS1974"/>, the latter in which
the one-or-all axiom is described. Polar spaces are axiomatically, point-line geometries, but
may contain higher dimensional projective subspaces too. All maximal subspaces have the same
projective dimension, and this determines the rank of the polar space. 
<P/>
Well known examples of <E>finite</E> polar spaces are the
geometries attached to sesquilinear and quadratic forms of vector spaces over a
finite field, these geometries are called the <E>finite classical polar
spaces</E>. For a given sesquilinear, respectively quadratic, form <M>f</M>, the elements of the associated
geometry are the totally isotropic, respectively totally singular, subspaces of the vectors space with relation
to the form <M>f</M>. The treatment of the forms is done through the package <Package>Forms</Package>.
<P/>
From the axiomatic point of view, a polar space is a point-line geometry, and has 
rank at least 2. Considering a sesquilinear or quadratic form <M>f</M>, of Witt index 1, the associated 
geometry consists only of projective points, and is then in the axiomatic treatment, not a polar space.
However, as is the case for projective spaces, we will consider the rank one geometries associated to
forms of Witt index 1 as examples of classical polar spaces. Even the elliptic quadric on the projective line,
a <E>geometry</E> associated to an elliptic quadratic form on a two dimensional vector space over a finite field, is
considered as a classical polar space, though it has no singular subspaces.
The reason for this treatment is that most, if not all, methods for
operations applicable on these geometries, rely on the same algebraic methodology. So, in <Package>FinInG</Package>, 
a classical polar space (sometimes abbreviated to polar space), is the geometry
associated with a sesquilinear or quadratic
form on a finite dimensional vector space over a finite field.

<ManSection>
<Filt Name="IsClassicalPolarSpace" Type="Category"/>
<Description>
This category is a subcategory of <C>IsLieGeometry</C>, and contains all the geometries associated to a non-degenerate
sesquilinear or quadratic form.
</Description>
</ManSection>

The underlying vector space and matrix
group are to our advantage in the treatment of classical polar spaces.
We refer the reader to <Cite Key="HirschfeldThas"/>
and <Cite Key="Cameron"/> for the necessary background theory (if it is not
otherwise provided), and we follow the approach of <Cite Key="Cameron"/> to
introduce all different flavours.<P/> 

Consider the projective space &pgnq; with underlying vector space
<M>V(n+1,q)</M>. Consider a non-degenerate sesquilinear form <M>f</M>. Then
<M>f</M> is Hermitian, alternating or symmetric. When the characteristic
of the field is odd, respectively even, a symmetric bilinear form is called
orthogonal, respectively, pseudo. We do not consider the pseudo case, so we
suppose that <M>f</M> is Hermitian, symplectic or orthogonal. The classical
polar space associated with <M>f</M> is the incidence geometry whose elements
are of the subspaces of &pgnq; whose underlying
vector subspace is totally isotropic with relation to <M>f</M>. 
We call a polar space <E>Hermitian</E>, respectively,
<E>symplectic</E>, <E>orthogonal</E>, if the underlying sesquilinear form is
Hermitian, respectively, symplectic, orthogonal.<P/> 

Symmetric bilinear forms have completely different geometric properties in even
characteristic than in odd characteristic. On the other hand, polar spaces
geometrically comparable to orthogonal polar spaces in odd characteristic, do
exist in even characteristic. The algebraic background is now established by
quadratic forms on a vector space instead of bilinear forms. Consider a
non-singular quadratic form <M>q</M> on a vector space <M>V(n+1,q)</M>. The 
classical polar space associated with <M>f</M> is the incidence geometry whose 
elements are the subspaces of &pgnq; whose
underlying vector subspace is totally singular with relation to <M>q</M>. 
The connection with orthogonal polar spaces in odd
characteristic is clear, since in odd characteristic, quadratic forms and
symmetric bilinear forms are equivalent. Therefore, we call polar spaces with an
underlying quadratic form in even characteristic also <E>orthogonal</E> polar spaces.

<ManSection>
<Oper Name="PolarSpace" Arg="form"/>
<Oper Name="PolarSpace" Arg="pol"/>
<Returns>a classical polar space</Returns>
<Description><A>form</A> must be a sesquilinear or quadratic form
created by use of the GAP package <Package>Forms</Package>. In the second variant,
the argument <A>pol</A> must be a polarity of a projective space. An error message
will be displayed if <A>pol</A> is a pseudo polarity. We refer to 
Chapter <Ref Chap="polaritiesofps"/> for more information on polarities of 
projective spaces, and more particularly to Section <Ref Sect="polarties_absolute"/> for
the connection between polarities and forms.
<Example>
<#Include SYSTEM "../examples/include/cps_polarspaceform.include"> 
</Example>
</Description>
</ManSection>

<Package>FinInG</Package> relies on the package <Package>Forms</Package> for its facility
with sesquilinear and quadratic forms. One can specify a polar space with a user-defined
form, and we refer to the documentation for <Package>Forms</Package> for information
on how one can create and use forms. Here we just display a worked example.

<Example>
<#Include SYSTEM "../examples/include/cps_example.include"> 
</Example>

</Section>

<Section Label="can_standard">
<Heading>Canonical and standard Polar Spaces</Heading>

To introduce the classification of polar spaces, we use the classification of
the underlying forms in similarity classes. We follow mostly the approach and
terminology of <Cite Key="KleidmanLiebeck"/>, as we did in the manual of the package
<Package>Forms</Package>.<P/>

Consider a vector space <M>V=V(n+1,q)</M> and a sesquilinear form <M>f</M> on
<M>V</M>. The pair <M>(V,f)</M> is called a formed space. Consider now two
formed spaces <M>(V,f)</M> and <M>(V,f')</M>, where <M>f</M> and <M>f'</M> are
two sesquilinear forms on <M>V</M>. A non-singular linear map &phi; from <M>V</M> to itself
induces a <E>similarity</E> of the formed space <M>(V,f)</M> to the formed space
<M>(V,f')</M> if and only if
<Alt Only="LaTeX"><Display>f(v,w) = \lambda f'(\phi(v),\phi(w)),</Display></Alt>
<Alt Only="Text"><M>f(v,w) = \lambda f'(\phi(v),\phi(w)),</M></Alt>
<Alt Only="HTML MathJax"><Display>f(v,w) = \lambda f'(\phi(v),\phi(w)),</Display></Alt>
<Alt Only="HTML noMathJax"><Display>f(v,w) = &#955; (f'(&#966;(v),&#966;(w))),</Display></Alt>
for all vectors <M>v,w</M> and some non-zero
<Alt Only="LaTeX"><M>\lambda \in &gf;(q)</M></Alt>
<Alt Only="Text"><M>\lambda \in GF(q)</M></Alt>
<Alt Only="HTML MathJax"><M>\lambda \in GF(q)</M></Alt>
<Alt Only="HTML noMathJax">&#955; in <M>GF(q)</M></Alt>. Up to similarity, there is only one
class of non-degenerate Hermitian forms, and one class of non-degenerate
symplectic forms on a given vector space <M>V</M>. For symmetric bilinear forms
in odd characteristic, the number of similarity classes depends on the
dimension of <M>V</M>. In odd dimension, there is only one similarity class, and
non-degenerate forms in this class are called parabolic (bilinear) forms. In
even dimension, there are two similarity classes, and non-degenerate forms are
either elliptic (bilinear) forms or hyperbolic (bilinear) forms.<P/>

Consider now a vector space <M>V</M> and a quadratic form <M>q</M> on <M>V</M>.
The pair <M>(V,q)</M> is called a formed space. Consider now two formed spaces
<M>(V,q)</M> and <M>(V,q')</M>, where <M>q</M> and <M>q'</M> are two quadratic
forms on <M>V</M>. A non-degenerate linear map &phi; from <M>V</M> to itself induces a
<E>similarity</E> of the formed space <M>(V,q)</M> to the formed space 
<M>(V,q')</M> if and only if
<Alt Only="LaTeX"><Display>q(v) = \lambda q'(\phi(v))),</Display></Alt>
<Alt Only="Text"><M>q(v) = \lambda q'(\phi(v)))</M>,</Alt>
<Alt Only="HTML MathJax"><Display>q(v) = \lambda q'(\phi(v))),</Display></Alt>
<Alt Only="HTML noMathJax"><Display>q(v) = &#955; (q'(&#966;(v))),</Display></Alt>
for all vectors <M>v</M> and some non-zero 
<Alt Only="LaTeX"><M>\lambda \in &gf;(q)</M></Alt>
<Alt Only="Text"><M>\lambda \in GF(q)</M></Alt>
<Alt Only="HTML MathJax"><M>\lambda \in GF(q)</M></Alt>
<Alt Only="HTML noMathJax">&#955; in <M>GF(q)</M></Alt>.
For quadratic forms in even characteristic, the number of similarity classes depends
on the dimension of <M>V</M>. In odd dimension, there is only one
similarity class, and non-degenerate forms in this class are called parabolic
(bilinear) forms. In even dimension, there are two similarity classes, and
non-degenerate forms are either elliptic (bilinear) forms or hyperbolic
(bilinear) forms.<P/>

If &phi; induces a similarity of
a formed vector space such that <M>\lambda = 1</M>,
then the similarity is called an <E>isometry</E> of the
formed vector space. In almost all cases, each similarity class contains exactly one 
isometry class. Only the orthogonal sesquilinear forms (in odd characteristic) have
two isometry classes. Consequently, if an isometry exists between formed vector spaces,
they are called <E>isometric</E>.

Projectively, a formed vector space becomes a classical polar space embedded in a 
projective space. Obviously, forms in the same similarity class determine
exactly the same classical polar space. Conversely, it is well known that
a classical polar space determines a form up to a constant factor, i.e. it determines
a similarity class of forms. In <Package>FinInG</Package>, the word <E>canonical</E>
is used in the mathematical sense, i.e. a classical polar space is <E>canonical</E>
if its determining form belongs to a fixed similarity class. A classical polar space
is called <E>standard</E> if its determining form is the fixed representative of the
canonical similarity class. Hence a <E>standard</E> classical polar space is 
always a <E>canonical</E> classical polar space, a canonical polar space is determined
by a standard form up to a constant factor.

In the following table, we summaries the above information on polar spaces,
together with the standard forms that are chosen in
<Package>FinInG</Package>. Note that <Alt Only="LaTeX"><M>\mathrm{Tr}</M></Alt><Alt Not="LaTeX">Tr</Alt> refers to the absolute trace map from
&gfq; to &gfp;.

<Table Align="|l|l|l|l|">
<Caption>finite classical polar spaces</Caption>
<HorLine/>
<Row><Item>polar space</Item><Item>standard form</Item><Item>characteristic <M>p</M></Item><Item><Alt Not="LaTeX">projective dimension</Alt><Alt Only="LaTeX">\makecell[cc]{projective \\ dimension}</Alt></Item></Row>
<HorLine/>
<Row><Item>hermitian polar space</Item>
<Item><Alt Not="HTML"><M>X_0^{q+1} + X_1^{q+1} + \ldots + X_{n}^{q+1}</M></Alt>
    <Alt Only="HTML MathJax"><M>X_0^{q+1} + X_1^{q+1} + \ldots + X_{n}^{q+1}</M></Alt>
    <Alt Only="HTML noMathJax">X&lt;sub>0&lt;/sub>&lt;sup>q+1&lt;/sup> +	 X&lt;sub>1&lt;/sub>&lt;sup>q+1&lt;/sup> ... +
        X&lt;sub>n&lt;/sub>&lt;sup>q+1&lt;/sup></Alt>
    </Item><Item>odd or even</Item><Item>odd or even</Item></Row>

<Row><Item>symplectic space</Item>
<Item><Alt Not="HTML"><M> X_0 Y_1 - Y_0X_1+ \ldots + X_{n-1}Y_n - Y_{n-1}X_n</M></Alt>
    <Alt Only="HTML MathJax"><M> X_0 Y_1 - Y_0X_1+ \ldots + X_{n-1}Y_n - Y_{n-1}X_n</M></Alt>
    <Alt Only="HTML noMathJax">X&lt;sub>0&lt;/sub> Y&lt;sub>1&lt;/sub> -
        X&lt;sub>1&lt;/sub>Y&lt;sub>0&lt;/sub> + ... +
        X&lt;sub>n-1&lt;/sub>Y&lt;sub>n&lt;/sub> -
        X&lt;sub>n&lt;/sub>Y&lt;sub>n-1&lt;/sub></Alt>
</Item><Item>odd or even</Item><Item>odd</Item></Row>

<Row><Item>hyperbolic quadric</Item>
<Item><Alt Not="HTML"><M> X_0 X_1 + \ldots + X_{n-1}X_n</M></Alt>
    <Alt Only="HTML MathJax"><M> X_0 X_1 + \ldots + X_{n-1}X_n</M></Alt>
    <Alt Only="HTML noMathJax">X&lt;sub>0&lt;/sub> X&lt;sub>1&lt;/sub> + ... +
        X&lt;sub>n-1&lt;/sub>X&lt;sub>n&lt;/sub></Alt></Item>
<Item><Alt Not="HTML"><M>p \equiv 3 \pmod{4}</M> or <M>p=2</M></Alt>
    <Alt Only="HTML MathJax"><M>p \equiv 3 \pmod{4}</M> or <M>p=2</M></Alt>
    <Alt Only="HTML noMathJax">p &#8801; 3 mod 4 or p=2</Alt>
</Item><Item>odd</Item></Row>

<Row><Item>hyperbolic quadric</Item>
<Item><Alt Not="HTML"><M>2(X_0 X_1 + \ldots + X_{n-1}X_n)</M></Alt>
    <Alt Only="HTML MathJax"><M>2(X_0 X_1 + \ldots + X_{n-1}X_n)</M></Alt>
    <Alt Only="HTML noMathJax">2(X&lt;sub>0&lt;/sub> X&lt;sub>1&lt;/sub> + ... +
        X&lt;sub>n-1&lt;/sub>X&lt;sub>n&lt;/sub> )</Alt>
   </Item><Item><Alt Only="HTML noMathJax">p &#8801; 1 mod 4</Alt>
       <Alt Only="HTML MathJax"><M>p \equiv 1 \pmod{4}</M></Alt>
       <Alt Not="HTML"><M>p \equiv 1 \pmod{4}</M></Alt>
   </Item><Item>odd</Item></Row>
   
   <Row><Item>parabolic quadric</Item>
   <Item><Alt Not="HTML"><M> X_0^2 + X_1X_2 + \ldots + X_{n-1}X_n
         </M></Alt><Alt Only="HTML">X&lt;sub>0&lt;/sub>&lt;sup>2&lt;/sup> +
	 X&lt;sub>1&lt;/sub> X&lt;sub>2&lt;/sub> + ... +
	 X&lt;sub>n-1&lt;/sub>X&lt;sub>n&lt;/sub></Alt>
   </Item><Item><Alt Only="HTML noMathJax">p &#8801; 1,3 mod 8</Alt>
   <Alt Only="HTML MathJax"><M>p \equiv 1,3 \pmod{8}</M></Alt>
   <Alt Not="HTML"><M>p \equiv 1,3 \pmod{8}</M></Alt>or <M>p=2</M></Item>
   <Item>even</Item></Row>
   
<Row><Item>parabolic quadric</Item>
    <Item><Alt Only="Text"><M>t(X_0^2 + X_1X_2 + \ldots + X_{n-1}X_n)</M>, t a primitive element of GF(p)</Alt>
    <Alt Only="LaTeX">\makecell[cl]{<M>t(X_0^2 + X_1X_2 + \ldots + X_{n-1}X_n),</M> \\ <M>t</M> a primitive element of <M>\mathrm{GF}(p)</M>}</Alt>
    <Alt Only="HTML noMathJax">t(X&lt;sub>0&lt;/sub>&lt;sup>2&lt;/sup> +
	 X&lt;sub>1&lt;/sub> X&lt;sub>2&lt;/sub> + ... +
	 X&lt;sub>n-1&lt;/sub>X&lt;sub>n&lt;/sub>), <M>t</M> a primitive element of <M>GF(p)</M></Alt>
    <Alt Only="HTML MathJax"><M>t(X_0^2 + X_1X_2 + \ldots + X_{n-1}X_n)</M>, <M>t</M> a primitive element of <M>\mathrm{GF}(p)</M></Alt>
    </Item><Item><Alt Only="HTML noMathJax">p &#8801; 5,7 mod 8</Alt>
        <Alt Only="HTML MathJax"><M>p \equiv 5,7 \pmod{8}</M></Alt>
        <Alt Not="HTML"><M>p \equiv 5,7 \pmod{8}</M></Alt>
    </Item>
    <Item>even</Item></Row>

<Row><Item>elliptic quadric</Item>
   <Item><Alt Not="HTML"><M>X_0^2 + X_1^2 + X_2X_3 + \ldots + X_{n-1}X_n</M></Alt>
       <Alt Only="HTML noMathJax">X&lt;sub>0&lt;/sub>&lt;sup>2&lt;/sup> + X&lt;sub>1&lt;/sub>&lt;sup>2&lt;/sup> +  X&lt;sub>2&lt;/sub>
	 X&lt;sub>3&lt;/sub> + ... + X&lt;sub>n-1&lt;/sub>X&lt;sub>n&lt;/sub></Alt>
       <Alt Only="HTML MathJax"><M>X_0^2 + X_1^2 + X_2X_3 + \ldots + X_{n-1}X_n</M></Alt></Item>
   <Item><Alt Only="HTML noMathJax">p &#8801; 3 mod 4</Alt>
       <Alt Only="HTML MathJax"><M>p \equiv 3 \pmod{4}</M></Alt>
       <Alt Not="HTML"><M>p \equiv 3 \pmod{4}</M></Alt></Item>
    <Item>odd</Item></Row>

<Row><Item>elliptic quadric</Item>
    <Item><Alt Only="LaTeX">\makecell[cl]{<M>X_0^2 + tX_1^2 + X_2X_3 + \ldots + X_{n-1}X_n</M>,\\ <M>t</M> a primitive element of <M>\mathrm{GF}(p)</M>}</Alt>
        <Alt Only="HTML MathJax"><M>X_0^2 + tX_1^2 + X_2X_3 + \ldots + X_{n-1}X_n</M>, <M>t</M> a primitive element of <M>\mathrm{GF}(p)</M></Alt>
        <Alt Only="Text"><M>X_0^2 + tX_1^2 + X_2X_3 + \ldots + X_{n-1}X_n</M>, <M>t</M> a primitive element of <M>GF(p)</M></Alt>
        <Alt Only="HTML noMathJax">X&lt;sub>0&lt;/sub>&lt;sup>2&lt;/sup> + tX&lt;sub>1&lt;/sub>&lt;sup>2&lt;/sup> +  X&lt;sub>2&lt;/sub> X&lt;sub>3&lt;/sub> + ... + X&lt;sub>n-1&lt;/sub>X&lt;sub>n&lt;/sub>, <M>t</M> a primitive element of GF(p)</Alt>
   </Item>
    <Item><Alt Only="HTML noMathJax">p &#8801; 1 mod 4</Alt>
        <Alt Only="HTML MathJax"><M>p \equiv 1 \pmod{4}</M></Alt>
        <Alt Not="HTML"><M>p \equiv 1 \pmod{4}</M></Alt>
    </Item>
    <Item>odd</Item></Row>
 
   <Row><Item>elliptic quadric</Item>
   <Item><Alt Only="Text"><M>X_0^2 + X_0X_1 + dX_1^2 + X_2X_3 + \ldots + X_{n-1}X_n
         </M>, <M>Tr(d)=1</M></Alt>
   <Alt Only="LaTeX">\makecell[cl]{<M>X_0^2 + X_0X_1 + dX_1^2 + X_2X_3 + \ldots + X_{n-1}X_n</M>,\\ <M>\mathrm{Tr}(d)=1</M>}</Alt>
   <Alt Only="HTML MathJax"><M>X_0^2 + X_0X_1 + dX_1^2 + X_2X_3 + \ldots + X_{n-1}X_n</M>, <M>\mathrm{Tr}(d)=1</M></Alt>
   <Alt Only="HTML noMathJax">X&lt;sub>0&lt;/sub>&lt;sup>2&lt;/sup> + X&lt;sub>0&lt;/sub>X&lt;sub>1&lt;/sub> +
	 d X&lt;sub>1&lt;/sub>&lt;sup>2&lt;/sup> +  X&lt;sub>2&lt;/sub> 
	 X&lt;sub>3&lt;/sub> + ... + X&lt;sub>n-1&lt;/sub>X&lt;sub>n&lt;/sub>
	 , Tr(d) = 1</Alt>
   </Item><Item>even</Item><Item>odd</Item></Row>
<HorLine/>
</Table>
We refer to Appendix <Ref Chap="groups_app"/> for information on the operations that construct gram matrices that are used to
obtain the above standard forms.<P/>
The <Package>FinInG</Package> provides a wealth of flexibility in constructing polar spaces. The user may choose a particular quadratic
or sesquilinear form, but may also chose to construct polars spaces that have one of the above mentioned forms as underlying form.
Furthermore, <Package>FinInG</Package> will detect when necessary if the user-constructed polar space is canonical. This mechanism 
gives the user complete flexibility while avoiding unnecessary computations when, for example, constructing the collineation group of a user-defined polar space.<P/>

The following five operations always return polar spaces induced by one of the above standard forms.

<ManSection>
<Oper Name="SymplecticSpace" Arg="d,F"/>
<Oper Name="SymplecticSpace" Arg="d,q"/>
<Returns>a symplectic polar space</Returns>
<Description>
This function returns the symplectic polar space of dimension <A>d</A>
over <A>F</A> for a field <A>F</A> or over GF(<A>q</A>) for a prime power
<A>q</A>.
<Example>
<#Include SYSTEM "../examples/include/cps_symplectic.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="HermitianPolarSpace" Arg="d,F"/>
<Oper Name="HermitianPolarSpace" Arg="d,q"/>
<Returns>a Hermitian polar space</Returns>
<Description>
This function returns the Hermitian polar space of dimension <A>d</A>
over <A>F</A> for a field <A>F</A> or over GF(<A>q</A>) for a prime power
<A>q</A>.
<Example>
<#Include SYSTEM "../examples/include/cps_hermitian.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="ParabolicQuadric" Arg="d,F"/>
<Oper Name="ParabolicQuadric" Arg="d,q"/>
<Returns>a parabolic quadric</Returns>
<Description> <A>d</A> must be an even positive integer.
This function returns the parabolic quadric of dimension <A>d</A>
over <A>F</A> for a field <A>F</A> or over GF(<A>q</A>) for a prime power
<A>q</A>.
<Example>
<#Include SYSTEM "../examples/include/cps_parabolic.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="HyperbolicQuadric" Arg="d,F"/>
<Oper Name="HyperbolicQuadric" Arg="d,q"/>
<Returns>a hyperbolic quadric</Returns>
<Description> <A>d</A> must be an odd positive integer.
This function returns the hyperbolic quadric of dimension <A>d</A>
over <A>F</A> for a field <A>F</A> or over GF(<A>q</A>) for a prime power
<A>q</A>.
<Example>
<#Include SYSTEM "../examples/include/cps_hyperbolic.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="EllipticQuadric" Arg="d,F"/>
<Oper Name="EllipticQuadric" Arg="d,q"/>
<Returns>an elliptic quadric</Returns>
<Description> <A>d</A> must be an odd positive integer.
This function returns the elliptic quadric of dimension <A>d</A>
over <A>F</A> for a field <A>F</A> or over GF(<A>q</A>) for a prime power
<A>q</A>.
<Example>
<#Include SYSTEM "../examples/include/cps_elliptic.include"> 
</Example>
</Description>
</ManSection>

The following operations are applicable on any classical polar space in <Package>FinInG</Package>. 

<ManSection>
<Attr Name="IsCanonicalPolarSpace" Arg="ps"/>
<Returns>true or false</Returns>
<Description>
This attribute returns true when a polar space with a particular underlying form is canonical.
The execution of this attribute on a general user constructed polar space needs to check the type
of <A>ps</A>. The obtained extra information is stored automatically as attribute for <A>ps</A>, 
as can be noted by the different printing of <A>ps</A> before and after execution.
<Example>
<#Include SYSTEM "../examples/include/cps_iscanonicalps.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="CanonicalPolarSpace" Arg="form"/>
<Oper Name="CanonicalPolarSpace" Arg="P"/>
<Returns>a classical polar space</Returns>
<Description>the canonical polar space isometric to the given polar space <A>P</A> or
the classical polar space with underlying form <A>form</A>. 
</Description>
</ManSection>

<ManSection>
<Oper Name="StandardPolarSpace" Arg="form"/>
<Oper Name="StandardPolarSpace" Arg="P"/>
<Returns>a classical polar space</Returns>
<Description>the polar space induced by a standard form and similar to the given polar space <A>P</A> or
the classical polar space with underlying form <A>form</A>. 
</Description>
</ManSection>

</Section>

<Section>
<Heading>Basic operations for finite classical polar spaces</Heading>

<ManSection>
<Oper Name="UnderlyingVectorSpace" Arg="ps"/>
<Returns>a vector space</Returns>
<Description>The polar space <A>ps</A> is the geometry associated with a sesquilinear or quadratic form <M>f</M>.
The vector space on which <M>f</M> is acting is returned.
<Example>
<#Include SYSTEM "../examples/include/cps_underlyingvs.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="AmbientSpace" Arg="ps"/>
<Returns>the ambient projective space</Returns>
<Description>
When <A>ps</A> is a polar space, this operation returns the ambient projective space, i.e. the
underlying projective space of the sesquilinear or quadratic form that defines <A>ps</A>.
<Example>
<#Include SYSTEM "../examples/include/cps_ambientspace.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="ProjectiveDimension" Arg="ps"/>
<Oper Name="Dimension" Arg="ps"/>
<Returns>the dimension of the ambient projective space of <A>ps</A></Returns>
<Description>When <A>ps</A> is a polar space, an ambient projective space <M>P</M> is 
uniquely defined and can be asked using <F>AmbientSpace</F>. This operation and
its synonym <F>Dimension</F> returns the dimension of <M>P</M>.
<Example>
<#Include SYSTEM "../examples/include/cps_projectivedimension.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="Rank" Arg="ps"/>
<Returns>the rank of <A>ps</A></Returns>
<Description>When <A>ps</A> is a polar space, its rank, i.e. the number of different types, equals 
the Witt index of the defining sesquilinear or quadratic form.
<Example>
<#Include SYSTEM "../examples/include/cps_rank.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="BaseField" Arg="ps"/>
<Returns>the base field of the polar space <A>ps</A></Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/cps_basefield.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Prop Name="IsHyperbolicQuadric" Arg="ps"/>
<Returns>true or false</Returns>
<Description>returns true if and only if <A>ps</A> is a hyperbolic quadric.
<Example>
<#Include SYSTEM "../examples/include/cps_ishyperbolicquadric.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Prop Name="IsEllipticQuadric" Arg="ps"/>
<Returns>true or false</Returns>
<Description>returns true if and only if <A>ps</A> is an elliptic quadric.
<Example>
<#Include SYSTEM "../examples/include/cps_isellipticquadric.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Prop Name="IsParabolicQuadric" Arg="ps"/>
<Returns>true or false</Returns>
<Description>returns true if and only if <A>ps</A> is a parabolic quadric.
<Example>
<#Include SYSTEM "../examples/include/cps_isparabolicquadric.include"> 
</Example>
</Description>
</ManSection>

</Section>

<Section>
<Heading>Subspaces of finite classical polar spaces</Heading>

The elements of a finite classical polar space <M>P</M> are the subspaces of the ambient projective space
that are totally isotropic with relation to the sesquilinear or quadratic form that defines <M>P</M>. Constructing
subspaces of finite classical polar spaces is done as in the projective space case, except that additional 
checks are implemented in the methods to check that the subspace of the vector space is totally isotropic.
The empty subspace, also called the trivial subspace, which has dimension -1, corresponds with the zero dimensional 
vector space of the underlying vector space of the ambient projective space of <M>P</M>, and is of course 
totally isotropic. As such, is is considered as a subspace of a finite classical polar space in the mathematical 
sense, but not as an element of the incidence geometry, and hence do in <Package>FinInG</Package>
not belong to the category <C>IsSubspaceOfClassicalPolarSpace</C>.

<ManSection>
<Oper Name="VectorSpaceToElement" Arg="ps, v"/>
<Returns>an element of the polar space <A>geo</A></Returns>
<Description>
Let <A>ps</A> be a polar space, and <A>v</A> is either a row vector (for points) or an <M>m</M>x<M>n</M> matrix (for an <M>(m-1)</M>-subspace of a polar space with an <M>(n-1)</M>-dimensional ambient projective space.
In the case that <A>v</A> is a matrix, the rows represent basis vectors for the subspace. An
exceptional case is when <A>v</A> is a zero-vector, whereby the trivial subspace is
returned. It is checked that the subspace defined by <M>v</M> is totally isotropic with relation to the form
defining <A>ps</A>.
<Example>
<#Include SYSTEM "../examples/include/cps_element1.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name = "EmptySubspace" Arg="ps"/>
<Returns>the trivial subspace in the projective <A>ps</A></Returns>
<Description>
The object returned by this operation is contained in
every projective subspace of the projective space <A>ps</A>, but is not an element of <A>ps</A>. Hence, testing
incidence results in an error message.
<Example>
<#Include SYSTEM "../examples/include/cps_emptysubspace.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="ProjectiveDimension" Arg="sub"/>
<Oper Name="Dimension" Arg="sub"/>
<Returns>the projective dimension of a subspace of a polar space. The operation <F>ProjectiveDimension</F> 
is also applicable on the EmptySubspace
</Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/cps_projdimension_element.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="ElementsOfIncidenceStructure" Arg="ps, j"/>
<Returns>the collection of elements of the projective space <A>ps</A> of type <A>j</A></Returns>
<Description>
For the projective space <A>ps</A> of dimension <M>d</M> and the type <A>j</A>, <M>1 \leq j \leq d</M>
this operation returns the collection of <M>j-1</M> dimensional subspaces.  <Example>
<#Include SYSTEM "../examples/include/cps_elements.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="AmbientSpace" Arg="el"/>
<Returns>returns the ambient space of an element <A>el</A> of a polar space</Returns>
<Description>
This operation is also applicable on the trivial subspace. For a Lie geometry, the ambient space of
an element is defined as the ambient space of the Lie geometry, i.e. a projective space.
<Example>
<#Include SYSTEM "../examples/include/cps_ambientspaceelps.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="Coordinates" Arg="p"/>
<Returns>the homogeneous coordinates of the point <A>p</A>
</Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/cps_coordinates.include"> 
</Example>
</Description>
</ManSection>

</Section>

<Section>
<Heading>Basic operations for polar spaces and subspaces of projective spaces</Heading>

<ManSection>
<Heading>Incidence and containment</Heading>
<Oper Name="IsIncident" Arg="el1, el2"/>
<Oper Name="\*" Arg="el1, el2"/>
<Oper Name="\in" Arg="el1, el2"/>
<Returns>true or false</Returns>
<Description>
Recall that for projective spaces, incidence is symmetrized containment, where the empty subspace and the 
whole projective space are excluded as arguments for this operation, since they are not considered as elements
of the geometry, but both the empty subspace and the whole projective space are allowed as arguments for <F>\in</F>.
<Example>
<#Include SYSTEM "../examples/include/cps_incident.include"> 
</Example>
</Description>
</ManSection>

<ManSection Label="polar:span">
<Oper Name="Span" Arg="u,v"/>
<Returns> an element </Returns>
<Description>
<A>u</A> and <A>v</A> are elements of a projective or polar space.
This function returns the join of the two elements, that is, the span
of the two subspaces. 
<Example>
<#Include SYSTEM "../examples/include/cps_span.include"> 
</Example>
</Description>
</ManSection>

<ManSection Label="polar:meet">
<Oper Name="Meet" Arg="u,v"/>
<Returns>an element</Returns>
<Description>
<A>u</A> and <A>v</A> are elements of a projective or polar space.
This function returns the meet of the two elements. If two
elements do not meet, then Meet returns <C>EmptySubspace</C>, which in <Package>FinInG</Package>,
is an element with projective dimension -1. (Note that the poset
of subspaces of a polar space is a meet-semilattice, but not closed under
taking spans).
<Example>
<#Include SYSTEM "../examples/include/cps_meet.include">
</Example>
Note: the above example will return different answers depending on the two
planes chosen at random.
</Description>
</ManSection>

<ManSection>
<Oper Name="IsCollinear" Arg="ps,u,v"/>
<Returns> Boolean </Returns>
<Description>
<A>u</A> and <A>v</A> are points of the ambient space of the polar space
<A>ps</A>. This function returns True if <A>u</A> and <A>v</A> are collinear
in <A>ps</A>. Note that belonging to <A>ps</A> is a necessary condition for
<A>u</A> and <A>v</A> to be collinear.
<Example>
<#Include SYSTEM "../examples/include/cps_iscollinear.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="PolarityOfProjectiveSpace" Arg="ps"/>
<Returns>a polarity of a projective space</Returns>
<Description> <A>ps</A> must be a polar space. This operation 
returns, when possible a polarity of the ambient projective
space of <A>ps</A>. It is well known that except for orthogonal polar
spaces in even characteristic, a classical polar space is in fact the 
geometry of absolute points of a polarity of a projective space, and
that no polarity can be associated to parabolic quadrics in even characteristic.
Polarities of projective spaces are discussed in more detail in Chapter <Ref Chap="polaritiesofps"/>.
<Example>
<#Include SYSTEM "../examples/include/cps_polarityofps.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="TypeOfSubspace" Arg="ps, v"/>
<Returns>a string</Returns>
<Description>
This operation is a convenient way to find out the intersection type
of a projective subspace with a polar space. The argument <A>ps</A> is 
a nondegenerate polar space, and the argument <A>v</A> is a subspace of
the ambient projective space. The operation returns a string in accordance
with the type of subspace: <Q>degenerate</Q>, <Q>symplectic</Q>, <Q>hermitian</Q>,
<Q>elliptic</Q>, <Q>hyperbolic</Q> or <Q>parabolic</Q>. 
<Example>
<#Include SYSTEM "../examples/include/cps_typesubspace.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="TangentSpace" Arg="el"/>
<Oper Name="TangentSpace" Arg="ps, el"/>
<Returns>A subspace of a projective space</Returns>
<Description>
Let <A>el</A> be an element of a classical polar space. The first version
returns the tangent space at <A>el</A> to this polar space. Let <A>el</A>
be a subspace of the ambient space of the polar space <A>ps</A>. The second
version checks whether <A>el</A> belongs to <A>ps</A> and returns the tangent space
at <A>el</A> to <A>ps</A>. Some obvious properties are demonstrated in the example.
<Example>
<#Include SYSTEM "../examples/include/cps_tangentspace.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="Pole" Arg="ps, el"/>
<Returns>A subspace of a projective space</Returns>
<Description>
Let <A>el</A> be a subspace of the ambient space of the polar space <A>ps</A>. This operation
returns the pole of <A>el</A> with relation to the polar space <A>ps</A>. 
<Example>
<#Include SYSTEM "../examples/include/cps_pole.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="EvaluateForm" Arg="form, el1"/>
<Oper Name="EvaluateForm" Arg="form, el1, el2"/>
<Oper Name="\^" Arg="form, el1"/>
<Oper Name="\^" Arg="form, el1, el2"/>
<Returns>a finite field element or a list (of lists) of finite field elements</Returns>
<Description>
This method passes <A>form</A> and the underlying vector or matrix of <A>el1</A>, when <A>form</A> is a quadratic form,
and <A>el1</A> and <A>el2</A> when <A>form</A> is a sesquilinear form to the operation <F>Evaluate</F> of
the package <Package>Forms</Package>. The same applies to the respective methods for <F>\^</F>. The example
below illustrates how the points of a projective space that evaluate to zero under a given form, are
precisely the points of the quadric associated with the given form.
<Example>
<#Include SYSTEM "../examples/include/cps_evaluateform.include">
</Example>
</Description>
</ManSection>

</Section>

<Section Label="polar:shadows">
<Heading>Shadow of elements</Heading>

The functionality in this section is comparable to the shadow functionality for elements of projective spaces, which
are described in Section <Ref Sect="projsp:shadows"/>. The generic description of shadows of elements of incidence structures
can be found in Section <Ref Sect="inc_geom:shadows"/>.

<ManSection>
<Oper Name="ShadowOfElement" Arg="ps, el, i"/>
<Oper Name="ShadowOfElement" Arg="ps, el, str"/>
<Returns>the elements of type <A>i</A> incident with <A>el</A>. The second variant determines 
the type <A>i</A> from the position of <A>str</A> in the list returned by 
<F>TypesOfElementsOfIncidenceStructurePlural</F></Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/cps_shadowofelement.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="ElementsIncidentWithElementOfIncidenceStructure" Arg="el, i"/>
<Returns>the elements of type <A>i</A> incident with <A>el</A>, in other words,
the type <A>i</A> shadow of the element <A>el</A>
</Returns>
<Description>
Internally, the function <F>FlagOfIncidenceStructure</F> is used to create a flag from <A>list</A>. This function
also performs the checking.
<Example>
<#Include SYSTEM "../examples/include/cps_elementsincidentwithelement.include">
</Example>
</Description>
</ManSection>

</Section>

<Section Label="polar:classicalgroups">
<Heading>Projective Orthogonal/Unitary/Symplectic groups in <Package>FinInG</Package></Heading>

The classical groups (apart from the general lines group), are the matrix groups that <E>respect</E>, in a certain
way, a sesquilinear or quadratic form. We formally recall the definitions used in <Package>FinInG</Package>. These
definitions are exactly the same as in <Package>Forms</Package>.<P/>

Let <M>(V,f)</M> and <M>(W,g)</M> be two formed vector spaces over the same
field <M>F</M>, where both <M>f</M> and <M>g</M> are sesquilinear forms. Suppose
that &phi; is a linear map from <M>V</M> to <M>W</M>. 

The map &phi; is an <E>isometry</E><Index>Isometry</Index> from the formed
space <M>(V,f)</M> to the formed space 
<M>(W,g)</M> if for all <M>v,w</M> in <M>V</M> we have
<Alt Only="LaTeX"><Display>f(v,w) = f'(\phi(v), \phi(w)).</Display></Alt>
<Alt Only="Text"><M>f(v,w) = f'(\phi(v), \phi(w))</M>.</Alt>
<Alt Only="HTML MathJax"><Display>f(v,w) = f'(\phi(v), \phi(w)).</Display></Alt>
<Alt Only="HTML noMathJax"><Display>f(v,w) = f'(&#966;(v),&#966;(w)).</Display></Alt>
The map &phi; is a <E>similarity</E><Index>Similarity</Index> from the
formed space <M>(V,f)</M> to the formed space <M>(W,g)</M> if for all <M>v,w</M>
in <M>V</M> we have
<Alt Only="LaTeX"><Display>f(v,w) = \lambda f'(\phi(v), \phi(w))</Display></Alt>
<Alt Only="Text"><M>f(v,w) = \lambda f'(\phi(v), \phi(w))</M></Alt>
<Alt Only="HTML MathJax"><Display>f(v,w) = \lambda f'(\phi(v), \phi(w))</Display></Alt>
<Alt Only="HTML noMathJax"><Display>f(v,w) = &#955; (f'(&#966;(v),&#966;(w)))</Display></Alt>
for some non-zero <Alt Only="HTML noMathJax">&#955; in <M>F</M></Alt><Alt
Not="HTML"><M>\lambda \in F</M></Alt><Alt Only="HTML MathJax"><M>\lambda \in F</M></Alt>. 
Finally, the map &phi; is a <E>semi-similarity</E><Index>Semi-similarity</Index> from the formed space  
<M>(V,f)</M> to the formed space <M>(W,g)</M> if for all <M>v,w</M> in <M>V</M>
we have
<Alt Only="LaTeX"><Display>f(v,w) = \lambda f'(\phi(v), \phi(w))^\alpha</Display></Alt>
<Alt Only="Text"><M>f(v,w) = \lambda f'(\phi(v), \phi(w))^\alpha</M></Alt>
<Alt Only="HTML MathJax"><Display>f(v,w) = \lambda f'(\phi(v), \phi(w))^\alpha</Display></Alt>
<Alt Only="HTML noMathJax"><Display>f(v,w) = &#955; f'(&#966;(v),&#966;(w))&lt;SUP>&#945;&lt;/SUP></Display></Alt>
for some non-zero <Alt Only="HTML">&#955; in <M>F</M></Alt><Alt Not="HTML"><M>\lambda \in F</M></Alt>
<Alt Only="HTML MathJax"><M>\lambda \in F</M></Alt> and a field automorphism <Alt
Only="HTML noMathJax">&#945;</Alt><Alt Only="HTML MathJax"><M>\alpha</M></Alt><Alt Not="HTML"><M>\alpha</M></Alt> of <M>F</M>.<P/>

Let <M>(V,f)</M> and <M>(W,g)</M> be two formed vector spaces over the same
field <M>F</M>, where both <M>f</M> and <M>g</M> are quadratic forms. Suppose
that &phi; is a linear
map from <M>V</M> to <M>W</M>. The map &phi; is an
<E>isometry</E><Index>Isometry</Index> from the formed space <M>(V,f)</M> to the
formed space <M>(W,g)</M> if for all <M>v,w</M> in <M>V</M> we have
<Alt Only="LaTeX"><Display>f(v) = f'(\phi(v)).</Display></Alt>
<Alt Only="Text"><M>f(v) = f'(\phi(v)).</M></Alt>
<Alt Only="HTML MathJax"><Display>f(v) = f'(\phi(v)).</Display></Alt>
<Alt Only="HTML noMathJax"><Display>f(v) = f'(&#966;(v)).</Display></Alt>
The map &phi; is a
<E>similarity</E><Index>Similarity</Index> from the formed space <M>(V,f)</M> to
a formed space <M>(W,g)</M> if for all <M>v,w</M> 
in <M>V</M> we have 
<Alt Only="HTML"><Display>f(v) = \lambda f'(\phi(v))</Display></Alt>
<Alt Only="Text"><M>f(v) = \lambda f'(\phi(v))</M></Alt>
<Alt Only="HTML MathJax"><Display>f(v) = \lambda f'(\phi(v))</Display></Alt>
<Alt Only="HTML noMathJax"><Display>f(v) = &#955; (f'(&#966;(v)))</Display></Alt>
for some non-zero <Alt Only="HTML noMathJax">&#955; in <M>F</M></Alt><Alt
Only="HTML MathJax"><M>\lambda \in F</M></Alt><Alt Not="HTML"><M>\lambda \in F</M></Alt>. 
Finally, the map &phi; is a <E>semi-similarity</E><Index>Semi-similarity</Index> 
from the formed space <M>(V,f)</M> to the formed space <M>(W,g)</M> 
if for all <M>v,w</M> in <M>V</M> we have
<Alt Only="LaTeX"><Display>f(v)=\lambda f'(\phi(v))^\alpha</Display></Alt>
<Alt Only="Text"><M>f(v)=\lambda f'(\phi(v))^\alpha</M></Alt>
<Alt Only="HTML MathJax"><Display>f(v)=\lambda f'(\phi(v))^\alpha</Display></Alt>
<Alt Only="HTML noMathJax"><Display>f(v) = &#955; f'(&#966;(v))&lt;SUP>&#945;&lt;/SUP></Display></Alt>
for some non-zero <Alt Only="HTML noMathJax">&#955; in <M>F</M></Alt><Alt Only="HTML MathJax"><M>\lambda \in F</M></Alt><Alt Not="HTML"><M>\lambda \in F</M></Alt>
and a field automorphism <Alt Only="HTML noMathJax">&#945;</Alt><Alt Only="HTML MathJax"><M>\alpha</M></Alt><Alt Not="HTML"><M>\alpha</M></Alt> 
of <M>F</M>.
<P/>

Collineations of classical polar spaces are induced by semi-similarities of the underlying
formed vector space, and vice versa, analogously by factoring out scalar matrices. The only exceptions
are the two-dimensional unitary groups where the the full semi-similarity group can contain
elements of its centre that are not scalars. In <Package>FinInG</Package>, the subgroups 
corresponding with similarities and isometries are also implemented, including a <E>special</E> variant, 
corresponding with the matrices having determinant
one. We use a consistent terminology, where isometries, similarities, respectively, of the polar
space, correspond with isometries, similarities, respectively, of the underlying formed vector space.
Special isometries of a polar space are induced by isometries of the formed vector space that have a matrix
with determinant one. If <M>P</M> is a polar space with special isometry group, isometry group, similarity group, 
collineation group, respectively, <M>S</M>, <M>I</M>, <M>G</M>,
<Alt Not="HTML"><M>\Gamma</M></Alt><Alt Only="HTML MathJax"><M>\Gamma</M></Alt><Alt Only="HTML noMahJax">&#915;</Alt>,
respectively, then clearly <Alt Only="LaTeX"><M>S \leqslant I \leqslant G \leqslant \Gamma</M></Alt>
<Alt Only="Text"><M>S \leq I \leq G \leq \Gamma</M></Alt>
<Alt Only="HTML MathJax"><M>S \leqslant I \leqslant G \leqslant \Gamma</M></Alt>
<Alt Only="HTML noMathJax">S &#8804; I &#8804; G &#8804; &#915;</Alt>. Equalities can
occur in certain cases, and will, as we will see in the following overview.

<Table Align="|l|l|l|l|l|l|">
 <Caption>projective finite classical groups</Caption>
 <HorLine/>
  <Row><Item>(sub)group</Item><Item>symplectic</Item><Item>hyperbolic</Item><Item>elliptic</Item><Item>parabolic</Item><Item>hermitian</Item></Row>
  <Row><Item>special isometry</Item><Item>&pspdq;</Item><Item>&psoplusdq;</Item><Item>&psominusdq;</Item><Item>&pso0dq;</Item><Item>&psudq2;</Item></Row>
  <Row><Item>isometry</Item><Item>&pspdq;</Item><Item>&pgoplusdq;</Item><Item>&pgominusdq;</Item><Item>&pgo0dq;</Item><Item>&pgudq2;</Item></Row>
  <Row><Item>similarity</Item><Item>&pgspdq;</Item><Item>&pdeltaoplusdq;</Item><Item>&pdeltaominusdq;</Item><Item>&pgo0dq;</Item><Item>&pgudq2;</Item></Row>
  <Row><Item>collineation</Item><Item>&pgammaspdq;</Item><Item>&pgammaoplusdq;</Item><Item>&pgammaominusdq;</Item><Item>&pgammaodq;</Item><Item>&pgammaudq2;</Item></Row>
 <HorLine/>
</Table>

<ManSection>
<Oper Name="SpecialIsometryGroup" Arg="ps"/>
<Returns>the special isometry group of the polar space <A>ps</A></Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/cps_specialisometry.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="IsometryGroup" Arg="ps"/>
<Returns>the isometry group of the polar space <A>ps</A></Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/cps_isometry.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="SimilarityGroup" Arg="ps"/>
<Returns>the similarity group of the polar space <A>ps</A></Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/cps_similarity.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="CollineationGroup" Arg="ps"/>
<Returns>the collineation group of the polar space <A>ps</A></Returns>
<Description>
    In most cases, the full projective semisimilarity group is returned. For two-dimensional
    unitary groups, the centre may contain elements that are not scalars. In this case, we
    return a central extension of the projective semisimilarity group. If the base field
    of <A>ps</A> is <Alt Not="HTML"><M>GF(q^2)</M></Alt><Alt Only="HTML">GF(q&lt;sup>2&lt;/sup>)</Alt>,
    <M>q</M> prime, the similarity group is returned.

<Example>
<#Include SYSTEM "../examples/include/cps_collineation.include"> 
</Example>
</Description>
</ManSection>

</Section>

<Section>
<Heading>Enumerating subspaces of polar spaces</Heading>

<Subsection>
<Heading>Enumerators for polar spaces</Heading>

An enumerator for a collection of subspaces of a given type of a polar space is provided in <Package>FinInG</Package>. If <A>C</A> is
such a collection, then <F>List(C)</F> will use the enumerator to compute a list with all the elements of <A>C</A>.
</Subsection>


<ManSection>
<Oper Name="Enumerator" Arg="C"/>
<Oper Name="List" Arg="C"/>
<Returns> an enumerator for the collection <A>C</A> and a list with all elements of <A>C</A></Returns>
<Description>
The argument <A>C</A> is a collection of subspaces of a polar space.
<Example>
<#Include SYSTEM "../examples/include/cps_enumerator.include"> 
</Example>
</Description>
</ManSection>

<Subsection>
<Heading>Iterators for polar spaces</Heading>
For all polar spaces an iterator is constructed using <F>IteratorList(enum)</F>, where <A>enum</A> is an appropriate enumerator.
</Subsection>

<ManSection>
<Oper Name="Iterator" Arg="elements"/>
<Returns> an iterator </Returns>
<Description>
<A>C</A> is a collection of subspaces of a polar space.
<Example>
<#Include SYSTEM "../examples/include/cps_iterator.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="AsList" Arg="subspaces"/>
<Returns>an Orb object or list</Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/cps_aslist.include"> 
</Example>
</Description>
</ManSection>



</Section>
</Chapter>
