<!-- 
  HAPPRIME - intro.xml
  Introduction documentation section 
  Paul Smith
  
  Copyright (C)  2007-2008
  Paul Smith
  National University of Ireland Galway
     
  This file is part of HAPprime. 

  HAPprime is free software; you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation; either version 2 of the License, or
  (at your option) any later version.

  HAPprime is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  GNU General Public License for more details.

  You should have received a copy of the GNU General Public License
  along with this program.  If not, see <http://www.gnu.org/licenses/>.

  $Id: intro.xml 224 2008-03-04 12:09:42Z pas $
-->
  
<!-- ********************************************************** -->
<Chapter> 
  <Heading>Introduction</Heading>
  <Section>
    <Heading>Introduction to the &HAPprime; package</Heading>

    &HAPprime; is a package for the &GAP; computer algebra system 
    (<URL>http://www.gap-system.org/</URL>), and which 
    extends the &HAP; `Homological Algebra Progamming' package 
    written by Graham Ellis (<URL>http://hamilton.nuigalway.ie/Hap/www/</URL>). 
    It provides algorithms and data structures for calculating cohomology ring 
    presentations and resolutions of small prime-power groups. As well as new 
    functions, &HAPprime; also provides some equivalents for some existing &HAP; 
    functions that are much more memory-efficient and occasionally faster.
    <P/>
    In particular, the main reasons  you may want to use &HAPprime; are
    <List>
      <Item>the calculation of resolutions of prime-power groups in &HAPprime; 
        uses significantly less memory than the equivalent function in &HAP;, 
        allowing resolutions (and cohomology ring presentations) of larger
        groups to be calculated (see Section <Ref Sect="ExResolution"/>);</Item>
      <Item>&HAPprime; can compute polynomial ring presentations for cohomology 
        rings calculated using either &HAP; or &HAPprime; (see Section 
        <Ref Sect="ExPresentation"/>);</Item>
      <Item>we provide a method which ensures that complete and correct 
        cohomology rings are computed. This is a an implementation of 
        Len Evens' original proof of the finite presentation of the cohomology 
        rings  (see Section <Ref Sect="ExPresentationLHS"/>).</Item>
    </List>
  </Section>

  <Section>
    <Heading>Required software</Heading>

    The &HAPprime; package requires &GAP; version 4.4 or greater and &HAP; 
    version 1.8.9 or greater. For calculating provably-correct cohomology rings,
    the <Package>Singular</Package> commutative algebra system 
    (<URL>http://www.singular.uni-kl.de/</URL>) and the 
    <Package>singular</Package> &GAP; package are also required. 
  </Section>
  
  <Section>
    <Heading>Installing &HAPprime;</Heading>

    To install the &HAPprime; Package, unpack the archive file
    into your &GAP; packages directory (either usually the <F>pkg</F> directory
    of your &GAP; 4 installation if you have access to it, or some local 
    <F>pkg</F> directory that &GAP; can find). The &HAPprime; files
    will all be installed in a subdirectory called 
    <F>happrime-<#Include SYSTEM "../../VERSION"></F>.
  </Section>
  
  <Section Label="LoadingAndTesting">
    <Heading>Loading and testing &HAPprime;</Heading>

    The &HAPprime; package is not loaded by default when &GAP; is started. To
    load the package, type the following at the &GAP; prompt:
<Log>
gap> LoadPackage( "HAPprime");
</Log>
    
    If &HAPprime; isn't already in memory, it is 
    loaded and the author information is displayed.
    If you are a frequent user of &HAPprime;,
    you might consider putting this line in your <F>.gaprc</F> file.
    <P/>
    The correct installation of &HAPprime; can be tested by using the test 
    routine <F>tst/testall.g</F>:
<Log>
gap> ReadPackage("HAPprime", "tst/testall.g");
+ HAPprime version <#Include SYSTEM "../../VERSION"> general tests
+ GAP4stones: 371057
+ HAPprime version <#Include SYSTEM "../../VERSION"> userguide examples
+ GAP4stones: 387662
+ HAPprime version <#Include SYSTEM "../../VERSION"> datatypes reference manual examples
+ GAP4stones: 382653
true
</Log>
    The number of <C>GAP4stones</C> will vary depending on your machine, but
    any additional lines of messages indicate problems with your installation.
    <P/>
    The test routine calls a set of test files 
    <Ref Sect="Test Files" BookName="ref"/> which can be found in the 
    <F>tst</F> directory of the &HAPprime; installation. All of the routines 
    listed in this user guide are tested, as are many of those in the datatype
    reference manual.
  </Section>
  
  <Section>
    <Heading>Documentation</Heading>

    The documentation for &HAPprime; is in two parts. This document is the
    user guide, which covers the main functions provided by &HAPprime; and
    examples of their use. There is also a more technical &HAPprime; datatypes 
    reference manual which gives details of the new &GAP; datatypes
    defined and used internally by &HAPprime;, as well as outlining the 
    algorithms used by the package.
    
    <#Include Label="MakeHAPprimeDoc_manMisc">
  </Section>
  
  <Section>
    <Heading>Displaying progress and calculation information</Heading>

    By default, the functions in &HAPprime; display no output (except for 
    returning the result). The <C>InfoHAPprime</C> info class can be used to 
    enable the printing of progress and calculation information during 
    processing. Since some computations with &HAPprime; can take several hours,
    setting this to a higher level can be particularly useful for monitoring 
    the progress of computations.
    
    <#Include Label="InfoHAPprime_manMisc">
  </Section>
  
  
  
</Chapter>