<!-- 
  affine.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 affine spaces/affine groups.
-->

<Chapter Label="affine">
<Heading>Affine Spaces</Heading>

In this chapter we show how one can work with finite affine
spaces in <Package>FinInG</Package>. 


<Section>
<Heading>Affine spaces and basic operations</Heading>

An <E>affine space</E> is a point-line incidence geometry, satisfying few well known axioms. 
An axiomatic treatment can e.g. be found in <Cite Key="VY65a"/> and <Cite Key="VY65b"/>. As 
is the case with projective spaces, affine spaces are axiomatically point-line geometries,
but may contain higher dimensional affine subspaces too. An affine space can also be described 
as the <Q>geometry you get</Q> when you remove a hyperplane from a projective space. Conversely, 
each affine space can be extended to a projective space in a unique way (by "adding its 
hyperplane at infinity"). In  <Package>FinInG</Package>, we deal with <E>finite Desarguesian 
affine spaces</E>, i.e. an affine space, such that its projective completion is Desarguesian. 
Other concepts can be easily defined using this projective completion. E.g. lines of the 
projective space which are concurrent in a point of the hyperplane at infinity, become 
now <E>parallel</E> in the affine space.

In order to implement (Desarguesian) affine spaces in <Package>FinInG</Package>,
we have to represent the elements of the affine space (the affine subspaces),
in a standard way. By definition, the points (i.e. the elements of type 1)
of the <M>n</M>-dimensional affine space &agnq; are the vectors of the 
underlying <M>n</M>-dimensional vector space
over the finite field &gfq;. The <M>i</M>-dimensional subspaces of &agnq; 
(i.e. the elements of type <M>i-1</M>) are defined as the cosets of the <M>i</M>-dimensional 
subspaces of the underlying vector space. Hence, the common representation of such a subspace is
<Display>v+S,</Display>
where v is a vector and S is a subspace of a vector space.
Equivalently one can also think of a subspace of an affine space as consisting of: (i) an affine point,
representing the coset, and and (ii) a <Q>direction</Q>, which is an element of an <M>n-1</M>-dimensional
projective space, representing the hyperplane at infinity. In <Package>FinInG</Package>,
we represent an <M>i</M>-dimensional subspace, <M>1 \leq i \leq n-1</M> as
<Display>[v, mat]</Display>
where <A>v</A> is a row vector and <A>mat</A> is a matrix (representing a basis of the
projective element representing the direction at infinity). For affine points, we simply use vectors.

<ManSection>
<Filt Name="IsAffineSpace" Type="Category"/>
<Description>
This category is a subcategory of <C>IsIncidenceGeometry</C>, and contains all finite Desarguesian affine spaces.
</Description>
</ManSection>

<ManSection>
<Oper Name="AffineSpace" Arg="d, F"/>
<Oper Name="AffineSpace" Arg="d, q"/>    
<Oper Name="AG" Arg="d, F"/>   
<Oper Name="AG" Arg="d, q"/>    
<Returns>an affine space</Returns>
<Description><A>d</A> must be a positive integer. 
In the first form, <A>F</A> is a field and the function returns the affine
space of dimension <A>d</A> over <A>F</A>. In the second form, <A>q</A> is
a prime power specifying the size of the field. The user may also use an alias,
namely, the common abbreviation <C>AG(d, q)</C>.
<Example>
<#Include SYSTEM "../examples/include/affine_affinespace.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Attr Name="Dimension" Arg="as"/>
<Attr Name="Rank" Arg="as"/>
<Returns>the dimension of the affine space <A>as</A> (which is equal to its rank)</Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/affine_dimension.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="BaseField" Arg="as"/>
<Returns>returns the base field for the affine space <A>as</A>
</Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/affine_basefield.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="UnderlyingVectorSpace" Arg="as"/>
<Returns>a vector space</Returns>
<Description>
The underlying vectorspace of &agnq; is simply <M>V(n,q)</M>.
<Example>
<#Include SYSTEM "../examples/include/affine_underlyingvs.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Attr Name="AmbientSpace" Arg="as"/>
<Returns>an affine space</Returns>
<Description>The ambient space of an affine space <A>as</A> is the affine space itself.
Hence, simply <A>as</A> will be returned.
<Example>
<#Include SYSTEM "../examples/include/affine_ambientspace.include"> 
</Example>
</Description>
</ManSection>

</Section>

<Section>
<Heading>Subspaces of affine spaces</Heading>

<ManSection>
<Oper Name="AffineSubspace" Arg="geo, v"/>
<Oper Name="AffineSubspace" Arg="geo, v, M"/>
<Returns> a subspace of an affine space </Returns>
<Description>
<A>geo</A> is an affine space,
<A>v</A> is a row vector, and <A>M</A> is a matrix.
There are two representations necessary for affine subspaces
in <Package>FinInG</Package>: (i) points represented as
vectors and (ii) subspaces of dimension at least 1 represented as
a coset of a vector subspace:
<Display>v+S.</Display>
For the former, the underlying object is
just a vector, whereas the second is a pair <M>[v, M]</M> where
<M>v</M> is a vector and <M>M</M> is a matrix representing the basis
of <M>S</M>. Now there is a canonical representative for the coset
<M>v+ S</M>, and the matrix <M>M</M> is in semi-echelon form, therefore
we can easily compare two affine subspaces. 
If no matrix is given in the arguments, then it is assumed that the
user is constructing an affine point.
<Example>
<#Include SYSTEM "../examples/include/affine_subspaces.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="ElementsOfIncidenceStructure" Arg="as, j"/>
<Returns>the collection of elements of the affine space <A>as</A> of type <A>j</A></Returns>
<Description>
For the affine space <A>as</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. 
An error message is produced when the projective space <A>ps</A> has no elements of a required type.<Example>
<#Include SYSTEM "../examples/include/affine_elements.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Heading>Short names for ElementsOfIncidenceStructure</Heading>
<Oper Name="Points" Arg="ps"/>
<Oper Name="Lines" Arg="ps"/>
<Oper Name="Planes" Arg="ps"/>
<Oper Name="Solids" Arg="ps"/>
<Oper Name="Hyperplanes" Arg="ps"/>
<Returns>The elements of <A>ps</A> of respective type 1, 2, 3, 4, and the hyperplanes</Returns>
<Description>
An error message is produced when the projective space <A>ps</A> has no elements of a required type.
<Example>
<#Include SYSTEM "../examples/include/affine_short.include"> 
</Example>
</Description>
</ManSection>

<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 affine spaces, incidence is symmetrized containment, where the whole affine space is
excluded as one of the arguments for the operation <F>IsIncident</F>, since they it is not considered 
as an element of the geometry, but the whole affine space is allowed as one of the arguments
for <F>\in</F>. The method for <F>\*</F> is using <F>IsIncident</F>.
<Example>
<#Include SYSTEM "../examples/include/affine_incident.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="AmbientSpace" Arg="el"/>
<Returns>returns the ambient space of an element <A>el</A> of an affine space</Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/affine_ambientspaceelas.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="BaseField" Arg="el"/>
<Returns>returns the base field of an element <A>el</A> of an affine space</Returns>
<Description>
<Example>
<#Include SYSTEM "../examples/include/affine_basefieldelas.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="Span" Arg="u, v"/>
<Returns> a subspace </Returns>
<Description>
<A>u</A> and <A>v</A> are subspaces of an affine space.
This function returns the span of the two subspaces. 
<Example>
<#Include SYSTEM "../examples/include/affine_span.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="Meet" Arg="u, v"/>
<Returns> an affine subspace or the empty list</Returns>
<Description>
<A>u</A> and <A>v</A> are subspaces of an affine space.
This function returns the meet of the two subspaces. If the two
subspaces are disjoint, then Meet returns the empty list.
<Example>
<#Include SYSTEM "../examples/include/affine_meet.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="IsParallel" Arg="u, v"/>
<Returns> true or false
</Returns>
<Description>
The arguments <A>u</A> and <A>v</A> must be affine subspaces of a common affine space. Two subspaces are parallel if and only if the direction space of the first is contained in the direction space of the second or viceversa.
<Example>
<#Include SYSTEM "../examples/include/affine_isparallel.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="ParallelClass" Arg="as, v"/>
<Oper Name="ParallelClass" Arg="v"/>
<Returns> a collection of affine subspaces
</Returns>
<Description>
The argument <A>v</A> is an affine subspace of <A>as</A>. This operation
returns a collection for which an iterator is installed.
The collection represents the set of elements of <A>as</A> of the same
type as <A>v</A> which are parallel to <A>v</A>; they have the same
direction. If <A>v</A> is a point, then this operation returns the
collection of all points of <A>as</A>. If one argument is given,
then it is assumed that the affine space which we are working
with is the ambient space of <A>v</A>.
<Example>
<#Include SYSTEM "../examples/include/affine_parallel.include"> 
</Example>
</Description>
</ManSection>


</Section>

<Section>

<Heading>Shadows of Affine Subspaces</Heading>

<ManSection>
<Oper Name="ShadowOfElement" Arg="as, v, type"/>
<Returns> the subspaces of the affine space <A>as</A> of dimension <A>type</A> which 
are incident with <A>v</A>
</Returns>
<Description>
<A>as</A> is an affine space and <A>v</A> is an element of <A>as</A>. 
This operation computes and returns the subspaces of dimension <A>type</A> which
are incident with <A>v</A>. In fact, this operation returns a collection
which is only computed when iterated (e.g. when applying <C>AsList</C> to
the collection). Some shorthand notation for <C>ShadowOfElement</C> is available
for affine spaces: <C>Points(as,v)</C>, <C>Points(v)</C>, <C>Lines(v)</C>, etc.
<Example>
<#Include SYSTEM "../examples/include/affine_shadow1.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="ShadowOfFlag" Arg="as, list, type"/>
<Returns> the subspaces of the affine space <A>as</A> of dimension <A>type</A> which 
are incident with each element of <A>list</A>
</Returns>
<Description>
<A>as</A> is an affine space and <A>list</A> is a list of pairwise incident elements of <A>as</A>. 
This operation computes and returns the subspaces of dimension <A>type</A> which
are incident with every element of <A>list</A>. In fact, this operation returns a collection
which is only computed when iterated (e.g. when applying <C>AsList</C> to
the collection).
<Example>
<#Include SYSTEM "../examples/include/affine_shadow2.include"> 
</Example>
</Description>
</ManSection>

</Section>


<Section>
<Heading>Iterators and enumerators</Heading>

Recall from Section <Ref Sect="proj_enum"/> (<Q>Enumerating subspaces of a projective space</Q>,
 Chapter <Ref Chap="projective_spaces"/>), that an iterator allows us to 
obtain elements from a collection one at a time in sequence, whereas
an enumerator for a collection give us a way of picking out the i-th element.
In <Package>FinInG</Package> we have enumerators and iterators for
subspace collections of affine spaces.


<ManSection>
<Oper Name="Iterator" Arg="subs"/>
<Returns> an iterator for the given subspaces collection </Returns>
<Description>
<A>subs</A>  is a collection of subspaces of an affine space, such as
<F>Points( AffineSpace(3, 3) )</F>.
<Example>
<#Include SYSTEM "../examples/include/affine_iterator.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="Enumerator" Arg="subs"/>
<Returns> an enumerator for the given subspaces collection </Returns>
<Description>
<A>subs</A>  is a collection of subspaces of an affine space, such as
<F>Points( AffineSpace(3, 3) )</F>.
<Example>
<#Include SYSTEM "../examples/include/affine_enumerator.include"> 
</Example>
</Description>
</ManSection>

</Section>

<Section>
<Heading>Affine groups</Heading>

A <E>collineation</E> of an affine space is a permutation of
the points which preserves the relation of collinearity
within the affine space. The fundamental theorem of affine geometry states
that the group &agammalnq; of collineations of an affine space &agnq; is generated by the
translations <M>T</M>, the matrices of &glnq; and the automorphisms
of the field &gfq;. The translations <M>T</M> form
a normal subgroup of &agammalnq;, and &agammalnq; is the semidirect product of <M>T</M> and &gammalnq;.
<P/>
Suppose we have an affine transformation of the form <M>x+A</M>
where <M>x</M> is a vector representing a translation, and <M>A</M>
is a matrix in &glnq; Then by using the natural
embedding of &aglnq; in &pglnplus1q;, we can write this collineation as a matrix:
<Alt Only="HTML noMathJax">
&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> &lt;/td>
&lt;td align="center" valign="center" width=30> &lt;/td>
&lt;td align="center" valign="center" width=30> &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> &lt;/td>
&lt;td align="center" valign="center" width=30>A&lt;/td>
&lt;td align="center" valign="center" width=30> &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> &lt;/td>
&lt;td align="center" valign="center" width=30> &lt;/td>
&lt;td align="center" valign="center" width=30> &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>---&lt;/td>
&lt;td align="center" valign="center" width=30>x&lt;/td>
&lt;td align="center" valign="center" width=30>---&lt;/td>
&lt;td align="center" valign="center" width=30>1&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;/tr>&lt;/table> 
</Alt>
<Alt Only="HTML MathJax"><Display>
\left(\begin{array}{ccccc|c}
&amp; &amp; &amp; &amp; &amp; 0\\
&amp; &amp; A &amp; &amp; &amp; 0\\
&amp; &amp; &amp; &amp; &amp; 0\\
\hline
&amp; &amp; x &amp; &amp; &amp; 1
\end{array}\right).
</Display></Alt>
<Alt Not="HTML"><Display>
\left(\begin{array}{ccccc|c} 
&amp; &amp; &amp; &amp; &amp; 0\\
&amp; &amp; A &amp; &amp; &amp; 0\\
&amp; &amp; &amp; &amp; &amp; 0\\
\hline
&amp; &amp; x &amp; &amp; &amp; 1
\end{array}\right).
</Display></Alt>

We can extend this idea to the full affine collineation group by adjoining
the field automorphisms as we would for projective collineations. Here is an example:

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

Here we see that this affine transformation is 
<Alt Only="HTML noMathJax">
&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>1&lt;/td>
&lt;td align="center" valign="center" width=30>2&lt;/td>
&lt;td align="center" valign="center" width=30>1&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" width=30>+&lt;/td>
&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>0&lt;/td>
&lt;td align="center" valign="center" width=30>1&lt;/td>
&lt;td align="center" valign="center" width=30>1&lt;/td>
&lt;/tr>
&lt;tr>
&lt;td align="center" valign="center" width=30>2&lt;/td>
&lt;td align="center" valign="center" width=30>2&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>2&lt;/td>
&lt;td align="center" valign="center" width=30>1&lt;/td>
&lt;td align="center" valign="center" width=30>0&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;/tr>&lt;/table>
</Alt>
<Alt Only="LaTeX">
<Display>(1,2,1) + \left(
\begin{array}{ccc}
0&amp; 1&amp; 1\\
2&amp; 2&amp; 0\\
2&amp; 1&amp; 1
\end{array}\right).
</Display>
</Alt>
<Alt Only="HTML MathJax">
<Display>(1,2,1) + \left(
\begin{array}{ccc}
0&amp; 1&amp; 1\\
2&amp; 2&amp; 0\\
2&amp; 1&amp; 1
\end{array}\right).
</Display>
</Alt>

<P/>
As we have seen, in <Package>FinInG</Package>, we represent an element of an affine collineation group
as a projective semilinear element, i.e. as an object in the category <C>ProjElsWithFrob</C>, 
so that we can use all the functionality that exists for such objects. 
However, an affine collineation group (i.e. a group of collineations of the affine space &agnq;
is not by default constructed as a subgroup of &pgammalnplus1q;, but the compatibility
between the elements of both groups enables testing for such relations.

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

<ManSection>
<Oper Name="AffineGroup" Arg="as"/>
<Returns> a group
</Returns>
<Description>
If <A>as</A> is the affine space &agnq;
This operation returnes the affine linear group &aglnq; acting
on <A>as</A>. The elements of this group are projectivities of
the associated projective space. In order to get the full group
of collineations of the affine space, one needs to use the
operation <C>CollineationGroup</C>.
<Example>
<#Include SYSTEM "../examples/include/affine_affinegroup.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="CollineationGroup" Arg="as"/>
<Returns> a group
</Returns>
<Description>
If <A>as</A> is the affine space &agnq;, then
this operation returns the affine semilinear group 
&agammalnq;.
The elements of this group are collineations of the associated projective space.
Note that if the defining field has prime order, then the
groups &agammalnq; and &aglnq; coincide.
<Example>
<#Include SYSTEM "../examples/include/affine_collineationgroup.include"> 
</Example>
</Description>
</ManSection>

<ManSection>
<Oper Name="OnAffineSpaces" Arg="subspace, el"/>
<Oper Name="\^" Arg="subspace, el"/>
<Returns> an element of an affine space
</Returns>
<Description>
<A>subspace</A> must be an element of an affine space and <A>el</A>
 a collineation of an affine space (which is in fact also a collineation
of an associated projective space). This is the action one should use for
collineations of affine spaces, and it acts on subspaces of all types of
affine spaces: points, lines, planes, etc.
<Example>
<#Include SYSTEM "../examples/include/affine_actions.include"> 
</Example>
</Description>
</ManSection>

</Section>


<Section>
<Heading>Low level operations</Heading>

One technical aspect of the design behind affine spaces in <Package>FinInG</Package>
is having canonical transversals for subspaces of vector spaces. We provide some
documentation below for the interested user.

<ManSection>
<Filt Name = "IsVectorSpaceTransversal"/>
<Description>
The category <C>IsVectorSpaceTransversal</C> represents a special object
in <Package>FinInG</Package> which carries a record with two components:
<A>space</A> and <A>subspace</A>. This category is a subcategory of
<C>IsSubspacesOfVectorSpace</C>, however, we do not recommend the
user to apply methods to objects in <C>IsVectorSpaceTransversal</C>, which are normally used for the category <C>IsSubspacesOfVectorSpace</C> (they won't work!). 
The objects in <C>IsVectorSpaceTransversal</C>
are only used in order to facilitate computing enumerators
of subspace collections.
</Description>
</ManSection>

<ManSection>
<Oper Name="VectorSpaceTransversal" Arg="space, mat"/>
<Returns> a collection for representing a transversal of a subspaces of a vector space </Returns>
<Description>
<A>space</A> is a vector space <M>V</M> and <A>mat</A> is a matrix whose rows are a basis for a subspace
<M>U</M> of <M>V</M>. A transversal for <M>U</M> in <M>V</M> is a set of coset representatives
for the quotient <M>V/U</M>. This collection comes equipped with an enumerator operation.
</Description>
</ManSection>

<ManSection>
<Oper Name="VectorSpaceTransversalElement" Arg="space, mat, vector"/>
<Returns> a canonical coset representative </Returns>
<Description>
<A>space</A> is a vector space <M>V</M>, <A>mat</A> is a matrix whose rows are a basis for a subspace
<M>U</M> of <M>V</M>, and <A>vector</A> is a vector <M>v</M> of <M>V</M>. 
A canonical representative <M>v'</M> is returned for the coset <M>U+v</M>.
</Description>
</ManSection>

<ManSection>
<Oper Name="ComplementSpace" Arg="space, mat"/>
<Returns> a collection for representing a transversal of a subspaces of a vector space </Returns>
<Description>
<A>space</A> is a vector space <M>V</M> and <A>mat</A> is a matrix whose rows are a basis for a subspace
<M>U</M> of <M>V</M>. The operation is almost a complete copy of the function <C>BaseSteinitzVector</C>
except that just a basis for the complement of <M>U</M> is returned instead of a full record.
</Description>
</ManSection>

</Section>

</Chapter>
