<!--

  examples.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 chapter gives examples for the usage of this package.

-->

<Chapter Label="examples">
<Heading>Examples</Heading>

In this chapter we provide some simple examples of the use of
<Package>FinInG</Package>.

<Section>
<Heading>Elementary examples</Heading>

<Subsection>
<Heading>subspaces of projective spaces</Heading>
The following example shows how to create some subspaces of a projective space, test their
incidence, and determine their span and intersection. Projective spaces are considered as 
incidence geometries too. Incidence, to be tested with <F>IsIncident</F> or equivalently <F>\*</F>, 
is symmetrized set-theoretic containment, the latter which can be tested through the operation <F>in</F>.

<Example>
<#Include SYSTEM "../examples/include/examples_sub1.include">
</Example>
</Subsection>

<Subsection>
<Heading>Subspaces of classical polar spaces</Heading>
<Package>FinInG</Package> provides classical polar spaces. Subspaces can be constructed the same
way as subspaces of projective spaces. Upon construction, it is checked whether the given vector space
does determine a subspace of the polar space. Subspaces of polar spaces are also subspaces of the ambient projective
space. Operations like <F>Span</F> and <F>Meet</F> are naturally applicable. However, the span of two subspaces might not
be a subspace of the polar space anymore, and if the two subspaces belong to two different polar spaces in the same
ambient projective space, it cannot be determined in which polar space the span should be constructed. Therefore
the result of <F>Span</F> of two subspaces of a polar space is a subspace of the ambient projective space.
It can be checked whether the result belongs to a polar space using <F>in</F>. This illustrates very well
a general philosophy: a subspace of a polar space, and more generally, an element of any incidence structure is always
aware of its ambient geometry. This example also illustrates how to create an element that belongs to the polar space
from the subspace of the ambient projective geometry by using <F>ElementToElement</F>. Finally note the behaviour of <F>=</F>
applied on the two subspaces. Clearly, a subspace of a polar space is really also a subspace of the ambient projective space.
<Example>
<#Include SYSTEM "../examples/include/examples_sub2.include">
</Example>
</Subsection>

<Subsection>
<Heading>Underlying objects</Heading>
Subspaces of projective spaces and polar spaces (and in general, elements of incidence structures), 
are determined by a mathematical object, called in <Package>FinInG</Package> the <E>underlying object</E>.
The operation <F>UnderlyingObject</F> simply returns this underlying object. For elements determined by
vectors or sub vector spaces, the underlying objects are a vector or a matrix. To represent these 
objects and to do very efficient orbit calculations under groups, we use the <Package>cvec</Package>. 
This can be noted when applying <F>UnderlyingObject</F>. The operation <F>Unpack</F> simply converts
the cvec objects into GAP vectors and matrices. The example also illustrates how the underlying object
of an element of an affine spaces looks like.
<Example>
<#Include SYSTEM "../examples/include/examples_underlyingobject.include">
</Example>
</Subsection>


<Subsection>
<Heading>Constructing polar spaces</Heading>
<Package>FinInG</Package> provides the classical polar spaces as the geometries of which the subspaces
are represented by the totally isotropic (resp. totally singular) vector subspaces with relation 
to a chosen sesquilinear (resp. quadratic form). The user may choose any non-degenerate (resp. non-singular)
form to construct the polar space. The usage of the forms makes <Package>FinInG</Package> dependent on the
package <Package>forms</Package>. Shortcuts to polar spaces in <E>standard</E> representation are included.
Detailed information can be found in Section <Ref Sect="can_standard"/>. 
<Example>
<#Include SYSTEM "../examples/include/examples_cps1.include">
</Example>
</Subsection>

<Subsection>
<Heading>Some collineation groups</Heading>
In principle, the full group of collineations of almost any incidence structure can be computed in 
<Package>FinInG</Package>. Mathematically, this is almost obvious for projective spaces and affine spaces.
For classical polar spaces, the particular forms plays a role. The coordinate change capabilities of the 
package <Package>forms</Package>, together with the standard theory (see <Cite Key="KleidmanLiebeck"/>), ensure
that the full collineation group of a classical polar space can be relatively easily obtained. The computation
of the full collineation group of particular incidence structures, such as generalised polygons, may rely on
the computation of the automorphism group of an underlying incidence graph, which is done by using nauty through the 
package <Package>GRAPE</Package>. Note that the elements of a projective collineation group are semilinear
maps, they consist of a matrix together with a field automorphism. 
<Example>
<#Include SYSTEM "../examples/include/examples_collgroup.include">
</Example>
</Subsection>

</Section>

<Section>
<Heading>Some objects with interesting combinatorial properties</Heading>

The examples here are meant to give a flavour of how to explore geometrical objects from different point
of views.

<Subsection>
<Heading>The Tits ovoid</Heading>
In this example we consider the Tits ovoid in <M>PG(3,8)</M>. We explicitly check the intersection number
of the Tits-ovoid with planes of the projective space, and compute its stabiliser group inside the homography
group of <M>PG(3,8)</M>. The use of <F>;;</F> after a command suppresses its output, which is particularly interesting
if the output is a long list. The operation <F>Collected</F> is self-explanatory, and a very useful GAP command.
The computed stabiliser is the Suzuki group <M>Sz(8)</M>, a finite simple group.
<Example>
<#Include SYSTEM "../examples/include/examples_tits.include">
</Example>
</Subsection>

<Subsection>
<Heading>Lines meeting a hermitian curve</Heading>
Here we see how the lines of a projective plane 
<Alt Not="HTML"><M>PG(2,q^2)</M></Alt> 
<Alt Only="HTML">PG(2,q&lt;sup>2 &lt;/sup>)</Alt>
meet a hermitian curve. It is well known that every line meets in either
1 or <M>q+1</M> points. Note that the last comment takes a while
to complete.
<Example>
<#Include SYSTEM "../examples/include/examples_hermitian.include"> 
</Example>
</Subsection>

<Subsection>
<Heading>The Patterson ovoid</Heading>
In this example, we construct the unique ovoid
of the parabolic quadric <M>Q(6,3)</M>, first discovered by Patterson, but for
which was given a nice construction by E. E. Shult. We begin with the ``sums of squares'' 
quadratic form over <M>GF(3)</M> and the associated polar space.
<Example>
<#Include SYSTEM "../examples/include/examples_patterson_commented.include"> 
</Example>
</Subsection>

<Subsection>
<Heading>A hyperoval</Heading>
In this example, we consider a hyperoval of the projective
plane <M>PG(2,4)</M>, that is, six points no three collinear.
We will construct such a hyperoval by some basic explorations into particular
properties of the projective plane <M>PG(2,4)</M>. The projective
plane is initialised, its points are computed and listed; then a standard
frame is constructed, of which we may assume that it is a subset
of the hyperoval. Finally, the stabiliser group of the hyperoval is
computed, and it is checked that this group is isomorphic with the 
symmetric group on six elements.
<Example>
<#Include SYSTEM "../examples/include/examples_hyperoval24_commented.include"> 
</Example>
</Subsection>

</Section>

<Section>
<Heading>Geometry morphisms</Heading>

A geometry morphism in <Package>FinInG</Package> is a map between (a subset of) the elements
of one geometry to (a subset of) the elements of a second geometry, preserving the incidence.
Geometry morphisms are not necessarily type preserving. This section is meant to illustrate,
in a non exhaustive way the basis philosophy behind geometry morphisms in <Package>FinInG</Package>.

<Subsection>
<Heading>Isomorphic polar spaces</Heading>
We've seen already that a polar space can be constructed from any non-degenerate sesquilinear or
non-singular quadratic form. An isomorphism between polar spaces of the same type, can easily be obtained.
This example illustrates <F>IsomorphismPolarSpaces</F>, which is in its basic use self-explanatory, and
the use of the obtained map to compute images and pre-images of elements.
<Example>
<#Include SYSTEM "../examples/include/examples_morphism1.include"> 
</Example>
</Subsection>

<Subsection>
<Heading>Intertwiners</Heading>
We reconsider the previous example. The observant reader might have noticed the message
<E>#I  No intertwiner computed...</E>. Given a geometry morphism
<M>f</M> from <M>S</M> to <M>S'</M>, an intertwiner <Alt Not="HTML"><M>\phi</M></Alt>
<Alt Only="HTML">&#966;</Alt> is a map
from the automorphism group of <M>S</M> to the automorphism group of
<M>S'</M>, such that for every element <M>p</M> of <M>S</M> and every
automorphism <M>g</M> of <M>S</M>, we have
<Alt Not="HTML"><Display> f(p^g) = f(p)^{\phi(g)} .</Display></Alt>
<Alt Only="HTML"><Display>f(p&lt;sup>g&lt;/sup>)=f(p)&lt;sup>&#966;(g)&lt;/sup>.</Display></Alt>
<Example>
<#Include SYSTEM "../examples/include/examples_morphism2.include"> 
</Example>
</Subsection>

<Subsection>
<Heading>Klein correspondence</Heading>
The Klein correspondence is well known. The user may define its own hyperbolic quadric
as range for the geometry morphism in <Package>FinInG</Package>. Note that more is possible
than illustrated in the elementary example, see Section <Ref Sect="sec:klein"/>.
<Example>
<#Include SYSTEM "../examples/include/examples_klein.include"> 
</Example>
</Subsection>


<Subsection>
<Heading>Embedding in a subspace</Heading>
A projective space can be embedded as a subspace in a higher dimensional projective space.
A comparable embedding is possible for polar spaces, clearly only when a given subspace
intersects the polar space of higher rank in a polar space of the same type as the polar space to
be embedded.
<Example>
<#Include SYSTEM "../examples/include/examples_embedW.include"> 
</Example>
</Subsection>

<Subsection>
<Heading>Subgeometries</Heading>
A projective space can be embedded as a subgeometry in a projective space of the same dimension but over a field extension.
A polar space, determined by a form <M>f</M> can be embedded in a polar space considered over a field extension by interpreting
the form <M>f</M> over this field extension. This is an interesting tool to construct geometrical objects in projective and polar spaces.
<Example>
<#Include SYSTEM "../examples/include/examples_embedsubfield.include">
</Example>
</Subsection>

<Subsection>
<Heading>Embedding by field reduction</Heading>
Field reduction is a power full tool to embed low dimensional projective (and polar spaces)
over a field <M>K</M> in to high dimensional spaces over a subfield of <M>K</M>. The mathematics behind
field reduction is explained in sections <Ref Sect="proj_red"/> and <Ref Sect="polar_red"/>.
The examples here show the use of these embeddings to construct a regular spread of a projective space
and a so-called Hermitian spread of a hyperbolic quadric.
<Example>
<#Include SYSTEM "../examples/include/examples_embedfieldreduction.include">
</Example>
</Subsection>

</Section>

<Section>
<Heading>Some geometrical objects</Heading>

<Subsection>
<Heading>Spreads of <M>W(5,3)</M></Heading>
A spread of <M>W(5,q)</M> is a set of <Alt Not="HTML"><M>q^3+1</M></Alt><Alt
Only="HTML">q&lt;sup>3&lt;/sup>+1</Alt> planes which
partition the points of <M>W(5,q)</M>. Here we enumerate all spreads of
<M>W(5,3)</M> which have a set-wise stabiliser of order a multiple of 13.
<Example>
<#Include SYSTEM "../examples/include/examples_spreads.include"> 
</Example>
</Subsection>

<Subsection>
<Heading>Distance-6 spread of the split Cayley hexagon</Heading>
A distance 6 spread of a split Cayley hexagon is a set of lines mutually at maximal distance
in the incidence graph. It is well known that the lines of the hexagon contained in a
hyperplane meeting the ambient polar space in an elliptic quadric, yield such a spread.
This example also illustrates how an element of a geometry <E>remembers</E> its ambient geometry,
and how <F>ElementToElement</F> can be used to embed an element in another geometry, see
<Ref Label="inc:elementtoelement"/>.
<Example>
<#Include SYSTEM "../examples/include/examples_translationspread.include">
</Example>
</Subsection>

</Section>

<Section>
<Heading>Some particular incidence geometries</Heading>

<Subsection>
<Heading>The split Cayley hexagon</Heading>
The split Cayley hexagon is one the well known classical generalised hexagons that are obtained using a triality of
the hyperbolic quadric in 7 dimensions. This example shows some basic properties of this geometry.
<Example>
<#Include SYSTEM "../examples/include/examples_splitcayley.include"> 
</Example>
</Subsection>

<Subsection>
<Heading>An (apartment of) a building of type <M>E_6</M></Heading>
This example shows the constructions of an incidence geometry whose automorphism group is an exceptional
group of type <M>E_6</M>. The construction is done as a coset geometry. This example also illustrates how
to get a diagram of such a coset geometry.
<Example>
<#Include SYSTEM "../examples/include/examples_e6.include"> 
</Example>
</Subsection>

<Alt Only="HTML">&lt;img src="./graphics/E6.jpg">&lt;/img></Alt>
<Alt Only="LaTeX">\includegraphics{./graphics/E6.jpg}</Alt>

<Subsection>
<Heading>A rank 4 geometry for <M>PSL(2,11)</M></Heading>
Here we look at a particular flag-transitive geometry constructed from
four subgroups of <M>PSL(2,11)</M>, and we construct the diagram for this geometry.
To view this diagram, you need to either use a postscript viewer or
a dotty viewer (such as GraphViz).
<Example>
<#Include SYSTEM "../examples/include/examples_PSL211.include"> 
</Example>
The output of this example uses <C>dotty</C> which is a sophisticated graph
drawing program. We also provide <F>DrawDiagramWithNeato</F> to make a diagram with straight lines, using <C>neato</C>.
Here is what the output looks like with the standard <F>DrawDiagram</F> command:
<Alt Only="HTML">&lt;img src="./graphics/PSL211.jpg">&lt;/img></Alt>
<Alt Only="LaTeX">\includegraphics{./graphics/PSL211.jpg}</Alt>
</Subsection>

<Subsection>
<Heading>The Ree-Tits octagon of order <M>[2,4]</M> as coset geometry</Heading>
In this example we construct the Ree-Tits octagon of order <M>[2,4]</M>
as a coset geometry. From the computation of the so-called rank 2 parameters,
it can be observed already that the constructed geometry must be a generalised octagon.
Then the points and lines are computed explicitly, and together with the incidence
and the available group as a subgroup of the collineation group, a generalised octagon
is constructed.<Example>
<#Include SYSTEM "../examples/include/examples_octagon.include">
</Example>
</Subsection>

</Section>

<Section>
<Heading>Elation generalised quadrangles</Heading>

In this section, we construct a classical elation
generalised quadrangle from a q-clan, and we see that
the associated BLT-set is a conic.

<Subsection>
<Heading>The classical q-clan</Heading>
<Example>
<#Include SYSTEM "../examples/include/examples_qclan.include"> 
</Example>
</Subsection>

<Subsection>
<Heading>Two ways to construct a flock generalised quadrangle from a Kantor-Knuth semifield q-clan</Heading>

We will construct an elation generalised quadrangle directly from the <E>Kantor-Knuth semifield q-clan</E>
and also via its corresponding BLT-set. The q-clan in question here are the set of matrices <Alt Not="HTML"><M>C_t</M></Alt><Alt
Only="HTML">C&lt;sub>t&lt;/sub></Alt> of the form

<Alt Only="HTML">
&lt;table style="color:#000">&lt;tr>
&lt;td>&lt;table border=0 cellpadding=0 cellspacing=0px style="border-left:1px solid #000; border-right:1px solid #000; color:#000">&lt;tr>
&lt;td style ="border-top:1px solid #000; border-bottom:1px solid #000;">&nbsp;&lt;/td>&lt;td>&lt;table border=0 cellpadding=0 cellspacing=0 style="color:#000;">
&lt;/tr>
&lt;td align="center" valign="center" width=30>t&lt;/td>
&lt;td align="center" valign="center" width=30>0&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td align="center" valign="center" width=30>0&lt;/td>
&lt;td align="center" valign="center" width=30>-nt&lt;sup>&#966;&lt;/sup>&lt;/td>
&lt;/tr>
&lt;/table>&lt;/td>
&lt;td style ="border-top:1px solid #000; border-bottom:1px solid #000;">&nbsp;&lt;/td>&lt;/tr>&lt;/table>&lt;/td>
&lt;td align="center" valign="center">&lt;table border=0 cellpadding=0 cellspacing=0px style="color:#000">
<!--&lt;tr>&lt;td>&lt;sup>-1&lt;/sup>&lt;/td>&lt;/tr>-->
&lt;tr>&lt;td>&nbsp;&lt;/td>&lt;/tr>
&lt;tr>&lt;td>&nbsp;&lt;/td>&lt;/tr>
&lt;/table>&lt;/td>
&lt;/tr>&lt;/table>
</Alt>
<Alt Only="LaTeX"><M>
\left(\begin{array}{cc} 
t &amp; 0 \\
0 &amp; -nt^\phi
\end{array}\right)
</M>
</Alt>

where t runs over the elements of <M>GF(q)</M>, <M>q</M> is odd and not prime, <M>n</M> is a fixed nonsquare 
and <Alt Not="HTML"><M>\phi</M></Alt><Alt Only="HTML">&#966;</Alt> is a nontrivial automorphism of <M>GF(q)</M>.

<Example>
<#Include SYSTEM "../examples/include/examples_KantorKnuth.include"> 
</Example>
</Subsection>

</Section>

<Section>
<Heading>Algebraic varieties</Heading>

<Subsection>
<Heading>A projective variety</Heading>
In this example we demonstrate the construction of projective varieties.
<Example>
<#Include SYSTEM "../examples/include/examples_varieties.include"> 
</Example>
</Subsection>

</Section>


</Chapter>
