<Section><Heading>Face Lattice and Resolution</Heading>

For Bieberbach groups (torsion free crystallographic groups), the following
functions calcualte free resolutions. This calculation is done by finding a
fundamental domain for the group. 

For a description of the <K>HapResolution</K> datatype, see the
<Package>Hap</Package> data types documentation or the experimental datatypes
documentation <Ref Label="Resolutions in Hap" BookName="HAPprog"/>

<ManSection>
<Meth Name="ResolutionBieberbachGroup" Arg="G [v]"/>
 <Returns>a <K>HAPresolution</K></Returns>
 <Description>
  Let <Arg>G</Arg> be a Bieberbach group given as an
  <K>AffineCrystGroupOnRight</K> and <A>v</A> a vector. Then a Dirichlet domain
  with respect to <A>v</A> is calculated using 
  <Ref Meth="FundamentalDomainBieberbachGroup"/>. From this domain, a
  resolution is calculated using 
  <Ref Meth="FaceLatticeAndBoundaryBieberbachGroup"/> and 
  <Ref Meth="ResolutionFromFLandBoundary"/>. If <A>v</A> is not given, the
  origin is used.
 </Description>
</ManSection> 

<Example><![CDATA[
gap> R:=ResolutionBieberbachGroup(SpaceGroup(3,9));
Resolution of length 3 in characteristic
0 for SpaceGroupOnRightBBNWZ( 3, 2, 2, 2, 2 ) .
No contracting homotopy available.

gap> List([0..3],Dimension(R));
[ 1, 3, 3, 1 ]
gap> R:=ResolutionBieberbachGroup(SpaceGroup(3,9),[1/2,0,0]);
Resolution of length 3 in characteristic
0 for SpaceGroupOnRightBBNWZ( 3, 2, 2, 2, 2 ) .
No contracting homotopy available.

gap> List([0..3],Dimension(R));
[ 6, 12, 7, 1 ]
]]>
</Example>

<ManSection>
  <Meth Name="FaceLatticeAndBoundaryBieberbachGroup" Arg="poly, group"/>
  <Returns> Record with entries <K>.hasse</K> and <K>.elts</K>
  representing a part of the hasse diagram and a lookup table of group
  elements</Returns>
  <Description>
   Let <A>group</A> be a torsion free <K>AffineCrystGroupOnRight</K> (that
   is, a Bieberbach group).
   Given a <K>PolymakeObject</K> <A>poly</A> representing a fundamental
   domain for <A>group</A>, this method uses <Package>polymaking</Package>
   to calculate the face lattice of <A>poly</A>.
   From the set of faces, a system of representatives for <A>group</A>-
  orbits is chosen. For each representative, the boundary is then
  calculated. The list <K>.elts</K> contains elements of <A>group</A> (in
  fact, it is even a set). The structure of the returned list
  <K>.hasse</K> is as follows:
  <List>
   <Item>The <M>i</M>-th entry contains a system of representatives
         for the <M>i-1</M> dimensional faces of <A>poly</A>.
	 </Item>
   <Item>Each face is represented by a pair of lists
         <C>[vertices,boundary]</C>. The list of integers
         <C>vertices</C> represents the vertices of
         <A>poly</A> which are contained in this face. The enumeration
	 is chosen such that an <C>i</C> in the list represents the
	 <M>i</M>-th entry of the list
	 <C>Polymake(poly,"VERTICES");</C> 
	 </Item>
   <Item> The list <C>boundary</C> represents the boundary of
	 the respective face. It is a list of pairs of integers
	 <C>[j,g]</C>. The first entry lies between <M>-n</M> and
	  <M>n</M>, where <M>n</M> is the number of faces of dimension
	  <M>i-1</M>. This entry represents a face of dimension
	  <M>i-1</M> (or its additive inverse as a module generator).
	  The second entry <C>g</C> is the position of the matrix in
	  <K>.elts</K>.
	  </Item>
  </List>
  This representation is compatible with the representation of free
  <M>\mathbb Z G</M> modules in <Package>Hap</Package> and this method essentially
  calculates a free resolution of <A>group</A>. If the value of  
  <Ref InfoClass="InfoHAPcryst" /> is 2 or more, additional information about
  the number of faces in every codimension, the number of orbits of the group
  on the free module generated by those faces, and the time it took to
  calculate the orbit decomposition is output.
  </Description>  
</ManSection>

<Example><![CDATA[
gap> SetInfoLevel(InfoHAPcryst,2);
gap> G:=SpaceGroup(3,165);
SpaceGroupOnRightBBNWZ( 3, 6, 1, 1, 4 )
gap> fd:=FundamentalDomainBieberbachGroup(G);
<polymake object>
gap> fl:=FaceLatticeAndBoundaryBieberbachGroup(fd,G);;
#I  1(4/8): 0:00:00.004
#I  2(5/18): 0:00:00.000
#I  3(2/12): 0:00:00.000
#I  Face lattice done ( 0:00:00.004). Calculating boundary
#I  done ( 0:00:00.004) Reformating...
gap> RecNames(fl);
[ "hasse", "elts", "groupring" ]
gap> fl.groupring;
<free left module over Integers, and ring-with-one, with 10 generators>
]]></Example>


<ManSection>
 <Meth Name="ResolutionFromFLandBoundary" Arg="fl group"/>
 <Returns>Free resolution</Returns>
 <Description>
  If <A>fl</A> is the record output by <Ref
  Meth="FaceLatticeAndBoundaryBieberbachGroup"/> and <A>group</A> is
  the corresponding group, this function returns a <K>HapResolution</K>.
  
  Of course, <A>fl</A> has to be generated from a fundamental domain
 for <A>group</A>
 </Description>
</ManSection>

<Example><![CDATA[
gap> G:=SpaceGroup(3,165);
SpaceGroupOnRightBBNWZ( 3, 6, 1, 1, 4 )
gap> fd:=FundamentalDomainBieberbachGroup(G);
<polymake object>
gap> fl:=FaceLatticeAndBoundaryBieberbachGroup(fd,G);;
gap> ResolutionFromFLandBoundary(fl,G);
Resolution of length 3 in characteristic
0 for SpaceGroupOnRightBBNWZ( 3, 6, 1, 1, 4 ) .
No contracting homotopy available.

gap> ResolutionFromFLandBoundary(fl,G);
Resolution of length 3 in characteristic
0 for SpaceGroupOnRightBBNWZ( 3, 6, 1, 1, 4 ) .
No contracting homotopy available.

gap> List([0..4],Dimension(last));
[ 2, 5, 4, 1, 0 ]
]]></Example>

</Section>
