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

  Copyright (C) 2017,	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 sub geometries of projective spaces.
-->

<Chapter Label="subgeometries">
<Heading>Subgeometries of projective spaces</Heading>

Let <M>S=(P,L,I)</M> be a point-line incidence geometry. In case <M>S</M> is a projective
space over a finite field, it is clear that every line (and every subspace as well) can
be identified with the set of points incident with it. Furthermore, the incidence
relation <M>I</M> is then symmetrised containment. To define a subgeometry
mathematically, we follow <Cite Key="Dembowski68"/>. Let <M>P' \subset P</M> and let
<M>L'</M> be a set of subsets of <M>P'</M>, such that every <M>l' \in L'</M>
is a subset of exactly one line <M>l \in L</M>. If <M>S'=(P',L',I)</M> is a projective space
again, then we call <M>S'</M> a <E>subgeometry</E> of <M>S</M>. Note that in general the subspaces of <M>S'</M> will be subsets of subspaces of <M>S</M>.
<P/>
A typical example of a subgeometry is a Baer subplane of a projective plane. In this example,
with <M>S'</M> the Baer subplane of the projective plane <M>S</M>, one could say that
a point of <M>S'</M> is indeed a point of <M>S</M>, but
a line of <M>S'</M>, is not a line of <M>S</M>. 
If one considers a line of <M>S'</M> as a set of
points of <M>S'</M>, then a line of <M>S'</M> is a subset of the set
of points on a line of <M>S</M>.

Another example is the subgeometry of a projective space induced by a subspace <M>\pi</M>.
In this example, clearly, the set of elements of the induced subgeometry can, mathematically,
be considered as a subset of the set of elements of <M>S</M>. 

<P/>The same considerations apply
for classical polar spaces. These consideration have implications for the behaviour of
certain operations in  <Package>FinInG</Package>, e.g. when computing the span and meet of different elements.

<P/>Using geometry morphisms, and more particular a
function like <F>NaturalEmbeddingBySubField</F>, one can deal in an indirect way with subgeometries. 
However, using <F>NaturalEmbeddingBySubField</F> is not flexible, and typical problems such as 
considering a subgeometry determined by a user chosen frame and a subfield, cannot be handled
easily. Therefore <Package>FinInG</Package> provides
some functions to naturally construct subgeometries of projective spaces.
<P/>
A subgeometry in a projective space is completely determined by a frame of the projective space
and a subfield of the base field of the projective space. The <E>standard frame</E> in an
<M>n</M>-dimensional projective space <M>PG(n,q)</M> is the set of <M>n+2</M> points represented by
<M>(1,0,\ldots,0),(0,1,\ldots,0),\ldots,(0,0,\ldots,1),(1,1,\ldots,1)</M>. The subgeometry
determined by the standard frame will be called <E>canonical</E>. Note that different
frames may determine the same subgeometry (over a fixed subfield). 
<P/>
For a given subfield <M>GF(q') \subset GF(q)</M>,
the canonical subgeometry determined by the standard frame in <M>PG(n,q)</M> is mathematically spoken
the image of the <Package>FinInG</Package> geometry morphism <F>NaturalEmbeddingBySubField</F> of the
projective space <M>PG(n,q')</M>. The coordinates of the points of the subgeometry will be exclusively
over the subfield <M>GF(q')</M>, as are the coordinates of the vectors after normalizing defining
any subspace of the subgeometry. Clearly, the Frobenius automorphism which maps <M>x</M> to <M>x^{q'}</M> fixes all elements
of the subgeometry.
<P/>
For an arbitrary frame of <M>PG(n,q)</M> and a subfield <M>GF(q')</M>, there exists a natural collineation
of <M>PG(n,q)</M> which fixes the subgeometry pointwise. This collineation is the conjugation
of the Frobenius automorphism by the unique collineation mapping the defining frame of the subgeometry
to the standard frame of <M>PG(n,q)</M>, i.e. the frame defining the canonical subgeometry over <M>GF(q')</M>. Upon construction of a subgeometry, both collineations will
be computed, and are of use when dealing with the full collineation group of a subgeometry. As for
any incidence geometry in <Package>FinInG</Package>, operations to compute this collineation group
as well as particular action functions for subgeometries are provided.
<P/>
Subgeometries of projective spaces are constructed in a subcategory of <C>IsProjectiveSpace</C>, as such,
all operations applicable to projective spaces, are naturally applicable to subgeometries. Subspaces
of subgeometries are constructed in a subcategory of <C>IsSubspaceOfProjectiveSpace</C>. Hence, operations
applicable to subspaces of projective spaces, are naturally applicable to subspaces of subgeometries.

<Section>
<Heading>Particular Categories</Heading>

<ManSection>
<Filt Name="IsSubgeometryOfProjectiveSpace" Type="Category"/>
<Description>
This category is a subcategory of <C>IsProjectiveSpace</C>, and contains all subgeometries of 
projective spaces. Note that mathematically, a subspace of a projective space is also a subgeometry.
However, in <Package>FinInG</Package>, subspaces of a projective space are constructed in a category that
is not a subcategory of <C>IsProjectiveSpace</C>. Since <C>IsSubgeometryOfProjectiveSpace</C> is a subcategory
of <C>IsProjectiveSpace</C>, all operations applicable to projective spaces, are naturally applicable to
subgeometries of projective spaces.
</Description>
</ManSection>

<ManSection>
<Heading>Categories for elements and collections of elements</Heading>
<Filt Name="IsSubspaceOfSubgeometryOfProjectiveSpace" Type="Category"/>
<Filt Name="IsSubspacesOfSubgeometryOfProjectiveSpace" Type="Category"/>
<Description>
A subspace of a subgeometry belongs to the category <C>IsSubspaceOfSubgeometryOfProjectiveSpace</C>.
</Description>
</ManSection>

</Section>

<Section>
<Heading>Subgeometries of projective spaces</Heading>

<ManSection>
<Oper Name="CanonicalSubgeometryOfProjectiveSpace" Arg="pg, subfield"/>
<Oper Name="CanonicalSubgeometryOfProjectiveSpace" Arg="pg, q"/>
<Returns>a subgeometry of <A>pg</A></Returns>
<Description>This operation returns the subgeometry of <A>pg</A> induced by the standard frame
over the subfield <A>subfield</A>. Alternatively, a prime power <A>q</A> can be used as the order of the
subfield. It is checked whether the user specified subfield is indeed a subfield of the base field of
<A>pg</A>. If the subfield equals the base field of <A>pg</A>, the projective space <A>pg</A> is returned.  
<Example>
<#Include SYSTEM "../examples/include/subgeometries_canonical.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="RandomFrameOfProjectiveSpace" Arg="pg"/>
<Returns>a set of points of <A>pg</A>, being a frame. Note that the returned object is also a
set in the GAP sense, i.e. an ordered list without duplicates.</Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/subgeometries_randomframe.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="IsFrameOfProjectiveSpace" Arg="list"/>
<Returns>true or false</Returns>
<Description>
When <A>list</A> is a list of points of a projective space, this operation returns true if and only
if <A>list</A> constitutes a frame of the projective space. It is checked as well whether all points
in <A>list</A> belong to the same projective space.
<Example>
<#Include SYSTEM "../examples/include/subgeometries_isframe.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="SubgeometryOfProjectiveSpaceByFrame" Arg="pg, list, field"/>
<Oper Name="SubgeometryOfProjectiveSpaceByFrame" Arg="pg, list, q"/>
<Returns>a subgeometry of <A>pg</A></Returns>
<Description>
The argument <A>pg</A> is a projective space which is not a subgeometry itself, the argument
<A>list</A> is a list of points of <A>pg</A> defining a frame of <A>pg</A>, and finally the
argument <A>field</A> is a subfield of the base field of <A>pg</A>. Alternatively, the
argument <A>q</A> is the order of a subfield of the base field of <A>pg</A>.
This method returns the subgeometry defined by the frame in <A>list</A> and the subfield <A>field</A>
of the subfield <M>GF(<A>q</A>)</M>. This method checks whether the subfield <A>field</A> or the field <M>GF(<A>q</A>)</M>
is really a subfield of the base field of <A>pg</A> and whether the list of points in <A>list</A> is a
frame of <A>pg</A>. Note also that it is currently not possible to construct subgeometries recursively,
so <A>pg</A> may not be a subgeometry itself. If the specified subfield equals the base field of
<A>pg</A>, then the projective space <A>pg</A> itself is returned.
<Example>
<#Include SYSTEM "../examples/include/subgeometries_byframe.include">
</Example>
</Description>
</ManSection>

</Section>

<Section>

<Heading>Basic operations</Heading>

<ManSection>
<Heading>Underlying vector space and ambient projective space</Heading>
<Oper Name="UnderlyingVectorSpace" Arg="sub"/>
<Oper Name="AmbientSpace" Arg="sub"/>
<Description>
Let <M>P</M> be a projective space over the field <M>F</M>. Let <A>sub</A> be a subgeometry
of <M>P</M> over the subfield <M>F'</M>. The underlying vector space of <A>sub</A>
is defined as the underlying vector space of <M>P</M> (which is a vector space over the field <M>F</M>).
The ambient space of a subgeometry <A>sub</A> is the projective space <M>P</M>.
<Example>
<#Include SYSTEM "../examples/include/subgeometries_ambientspace.include">
</Example>
</Description>
</ManSection>

<ManSection>
<Attr Name="DefiningFrameOfSubgeometry" Arg="sub"/>
<Returns>a set of projective points</Returns>
<Description>
This attribute returns a frame of the ambient space of <A>sub</A> defining it. Note that different frames
might define the same subgeometry, but the frame used to constructed <A>sub</A> is stored at construction,
and it is exactly this stored object that is returned by this attribute. The returned object is a set
of points, and it is also a set in the GAP sense, i.e. an ordered list without duplicates.
<Example>
<#Include SYSTEM "../examples/include/subgeometries_definingframe.include">
</Example>
</Description>
</ManSection>

<ManSection>
<Heading>Projective dimension and rank</Heading>
<Oper Name="ProjectiveDimension" Arg="sub"/>
<Oper Name="Dimension" Arg="sub"/>
<Oper Name="Rank" Arg="sub"/>
<Returns>an integer</Returns>
<Description>
If <A>sub</A> is a subgeometry of a projective space, then it is a projective space
itself. Therefore, these three operations return the projective dimension of <A>sub</A>,
see also <Ref Sect="proj:dimension"/>.
<Example>
<#Include SYSTEM "../examples/include/subgeometries_dimension.include">
</Example>
</Description>
</ManSection>

<ManSection>
<Heading>Underlying algebraic structures</Heading>
<Oper Name="UnderlyingVectorSpace" Arg="sub"/>
<Oper Name="BaseField" Arg="sub"/>
<Oper Name="SubfieldOfSubgeometry" Arg="sub"/>
<Returns>the first operation returns a vector space, the second and third operations return a finite field</Returns>
<Description>
The operations <F>UnderlyingVectorSpace</F> and <F>BaseField</F> are defined for
projective spaces, see <Ref Sect="proj:underlyingvs"/> and <Ref Sect="proj:basefield"/>.
For a subgeometry of a projective space <A>sub</A> with ambient space <A>ps</A>,
these operations return <F>UnderlyingVectorSpace(ps)</F>, <F>BaseField(ps)</F> respectively.
The operation <F>SubfieldOfSubgeometry</F> returns the subfield over which <A>sub</A> is defined.
<Example>
<#Include SYSTEM "../examples/include/subgeometries_underlyingstructures.include">
</Example>
</Description>
</ManSection>

<ManSection>
<Attr Name="CollineationFixingSubgeometry" Arg="sub"/>
<Returns>a collineation of the ambient space of <A>sub</A></Returns>
<Description>
Let <M>GF(q)</M> be the field over which <A>sub</A> is defined, this is a
subfield of <M>GF(q^t)</M> over which the ambient projective space <M>P</M>
is defined. It is well known that there exists a collineation of <M>P</M> of
order <M>t</M>, fixing all elements of <A>sub</A>, which is returned by this operation.
This collineation is the collineation induced by the Frobenius map <M>x\mapsto x^q</M>, 
 conjugated by the collineation of <M>P</M> mapping
the subgeometry <A>sub</A> to the canonical subgeometry of <M>P</M> over <M>GF(q)</M>. In case of a quadratic field extension (i.e. <M>t=2</M>),
this collineation is known in the literature as the Baer involution of the subgeometry.
<Example>
<#Include SYSTEM "../examples/include/subgeometries_collineationfixingsubgeometry.include">
</Example>
</Description>
</ManSection>

</Section>

<Section>
<Heading>Constructing elements of a subgeometry</Heading>

<ManSection>
<Oper Name="VectorSpaceToElement" Arg="sub, v"/>
<Returns>a subspace of a subgeometry</Returns>
<Description>
<A>sub</A> is a subgeometry of a projective space, and <A>v</A> is either a row vector
(for points) or a matrix (for higher dimensional subspaces). In the case that <A>v</A> is a matrix, the rows represent generators
for the subspace. An exceptional case is when <A>v</A> is the zero-vector, in which case the trivial 
subspace is returned. This method checks whether <A>v</A> determines an element of <A>sub</A>. <Example>
<#Include SYSTEM "../examples/include/subgeometries_vectorspacetoelement.include">
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="ExtendElementOfSubgeometry" Arg="el"/>
<Returns>a subspace of a projective space</Returns>
<Description>
The argument <A>el</A> is an element of a subgeometry <M>P'</M> with ambient projective space <M>P</M>.
The projective space is defined over a field <M>F</M>, the subgeometry <M>P'</M> is defined over
a subfield <M>F'</M> of <M>F</M>. The underlying vector space of <A>el</A> is a vector space over <M>F'</M>
generated by a set <M>S</M> of vectors. This operation returns the element of <M>P</M>, corresponding to the vector space over <M>F</M> generated by the vectors in <M>S</M>.
Note that the set <M>S</M> can be obtained using <F>UnderlyingObject</F>, see <Ref Sect="underlyingobject1"/>.
<Example>
<#Include SYSTEM "../examples/include/subgeometries_extendelement.include">
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="AmbientGeometry" Arg="el"/>
<Returns>an incidence geometry</Returns>
<Description>
For <A>el</A> an element of a subgeometry <M>P</M>, which is also a projective space, this operation
returns <M>P</M>.
</Description>
</ManSection>

<ManSection>
<Heading>Flags</Heading>
<Oper Name="FlagOfIncidenceStructure" Arg="sub, els"/>
<Oper Name="IsEmptyFlag" Arg="flag"/>
<Oper Name="IsChamberOfIncidenceStructure" Arg="flag"/>
<Returns>true or false</Returns>
<Description>
These operations are defined for projective spaces and so they are also applicable to subgeometries.
</Description>
</ManSection>




</Section>

<Section>
<Heading>Groups and actions</Heading>

Let <M>P'</M> be a subgeometry of <M>P</M>. Although one could argue that any semilinear map inducing a collineation preserving <M>P'</M> can be called a collineation of <M>P'</M>, this would cause problems with the nice monomorphism functionality, since such a collineation does not necessarily have a faithful action on the subgeometry. For this reason, we decided to define the collineation group of
the subgeometry <M>P'</M> as the collineation group of the projective space isomorphic to <M>P'</M> conjugated
by the collineation of <M>P</M> mapping <M>P'</M> on the canonical subgeometry of <M>P</M> over the same field as
<M>P'</M>. Similarly, the projectivity group, respectively the special projectivity group, of <M>P'</M>
is defined as the conjugate of the projectivity group, respectively special projectivity group, of
the projective space isomorphic to <M>P'</M>.

<ManSection>
<Heading>Groups of collineations</Heading>
<Oper Name="CollineationGroup" Arg="sub"/>
<Oper Name="ProjectivityGroup" Arg="sub"/>
<Oper Name="SpecialProjectivityGroup" Arg="sub"/>

<Returns>a group of collineations</Returns>

</ManSection>



</Section>

</Chapter>
