<!-- 
  HAPPRIME - functions.xml.in
  Function documentation template file for HAPprime
  Paul Smith

  Copyright (C)  2007-2009
  Paul Smith
  National University of Ireland Galway

  $Id: functions.xml.in 200 2008-02-05 14:29:47Z pas $
-->

<!-- ********************************************************** -->
<Chapter Label="GeneralFunctions">
  <Heading>General Functions</Heading>

  Some of the functions provided by &HAPprime; are not specifically aimed
  at homological algebra or extending the &HAP; package. The functions
  in this chapter, which are used internally by &HAPprime; extend some of the 
  standard &GAP; functions and datatypes.

  <Section>
    <Heading>Matrices</Heading>

    For details of the standard &GAP; vector and matrix functions, see 
    <Ref Chap="Matrices" BookName="tut"/> and <Ref Chap="Matrices" BookName="ref"/> 
    in the &GAP; tutorial and reference manuals. &HAPprime; provides improved
    versions of a couple of standard matrix operations, and two small helper
    functions.

    <#Include Label="SumIntersectionMatDestructive_manBaseMat">
    <#Include Label="SolutionMat_manBaseMat">
    <#Include Label="IsSameSubspace_manBaseMat">
    <#Include Label="PrintDimensionsMat_manBaseMat">

    <Subsection>
      <Heading>Example: matrices and vector spaces</Heading>
    
      &GAP; uses rows of a matrix to represent basis vectors for a vector space. 
      In this example we have two matrics <M>U</M> and <M>V</M> that we suspect
      represent the same subspace. Using 
      <Ref Func="SolutionMat" Label="for multiple vectors"/> we can see that
      <M>V</M> lies in <M>U</M>, but <Ref Func="IsSameSubspace"/> shows that 
      they are the same subspace, as is confirmed by having identical 
      sums and intersections.
<!--
gap> U := [[1,2,3],[4,5,6]];;
gap> V := [[3,3,3],[5,7,9]];;
gap> SolutionMat(U, V);
gap> IsSameSubspace(U, V);
gap> SumIntersectionMatDestructive(U, V);
gap> IsSameSubspace(last[1], last[2]);
gap> PrintDimensionsMat(V);
-->      
<Example><![CDATA[
gap> U := [[1,2,3],[4,5,6]];;
gap> V := [[3,3,3],[5,7,9]];;
gap> SolutionMat(U, V);
[ [ -1, 1 ], [ 1, 1 ] ]
gap> IsSameSubspace(U, V);
true
gap> SumIntersectionMatDestructive(U, V);
[ [ [ 1, 2, 3 ], [ 0, 1, 2 ] ], [ [ 0, 1, 2 ], [ 1, 0, -1 ] ] ]
gap> IsSameSubspace(last[1], last[2]);
true
gap> PrintDimensionsMat(V);
"2x3"
]]></Example>
   </Subsection>
  </Section>

  <Section>
    <Heading>Polynomials</Heading>

    &GAP; provides some functions for manipulating polynomials and polynomial 
    ideals - see <Ref Chap="Polynomials and Rational Functions" BookName="ref"/>.
    The &HAPprime; packages adds further functions to decompose polynomials 
    into terms and monomials, and some functions for tidying up polynomial 
    ideals.

    <#Include Label="TermsOfPolynomial_manPolynomial">
    <#Include Label="IsMonomial_manPolynomial">
    <#Include Label="UnivariateMonomialsOfMonomial_manPolynomial">
    <#Include Label="IndeterminateAndExponentOfUnivariateMonomial_manPolynomial">
    <#Include Label="IndeterminatesOfPolynomial_manPolynomial">
    <#Include Label="ReduceIdeal_manPolynomial">
    <#Include Label="ReducedPolynomialRingPresentation_manPolynomial">

    <Subsection>
      <Heading>Example: monomials, polynomials and ring presentations</Heading>
    
      A monomial is some product of ring indeterminates. A polynomial is a sum 
      of monomials, where each monomial may also be multiplied by an element
      from the field of the polynomial. It can be useful to decompose 
      polynomials as follows:
      <List>
        <Item>decompose a polynomial into its individual terms (where a term
          is a product of a monomial and a field element). The function
          <Ref Oper="TermsOfPolynomial"/> does this.</Item>
        <Item>decompose a monomial into its component univariate monomials,
          each of which is some (power of) a single indeterminates. This 
          operation is performed by
          <Ref Oper="UnivariateMonomialsOfMonomial"/>.</Item>
        <Item>decompose a univariate monomial into it the indeterminates and
          exponent (<Ref Oper="IndeterminateAndExponentOfUnivariateMonomial"/>).</Item>
      </List>
      In the example below, we decompose 
      <M>x + xy^2 + 3y^3</M> into its three terms, and then further decompose 
      the <M>xy^2</M> term.
<!--
gap> R := PolynomialRing(Integers, 2);;
gap> x := R.1;; y := R.2;;
gap> poly := x + x*y^2 + 3*y^3;
gap> terms := TermsOfPolynomial(poly);
gap> UnivariateMonomialsOfMonomial(terms[3][1]);
gap> IndeterminateAndExponentOfUnivariateMonomial(last[2]);
-->      
<Example><![CDATA[
gap> R := PolynomialRing(Integers, 2);;
gap> x := R.1;; y := R.2;;
gap> poly := x + x*y^2 + 3*y^3;
x_1*x_2^2+3*x_2^3+x_1
gap> terms := TermsOfPolynomial(poly);
[ [ x_1, 1 ], [ x_2^3, 3 ], [ x_1*x_2^2, 1 ] ]
gap> UnivariateMonomialsOfMonomial(terms[3][1]);
[ x_1, x_2^2 ]
gap> IndeterminateAndExponentOfUnivariateMonomial(last[2]);
[ x_2, 2 ]
]]></Example>
      <P/>
      &HAPprime; also provides some functions to help the generation of 
      ring presentations. In the following example we consider the 
      polynomial ring <M>\mathbb{Z}[w,x,y,z]</M> an an ideal
      <M>I = \langle w^2 + x, w^3 + x^3 \rangle</M>. We first convert this
      ideal into reduced form (where no monomial in a polynomial is divisible by 
      the leading term of any other polynomial). Then we calculate a
      reduced ring presentation for the quotient ring <M>R/I</M>, where we 
      find that the indeterminate <M>x</M> is can be removed and a new ring 
      <M>S/J = \mathbb{Z}[w,y,z]/\langle w^6-w^3 \rangle</M> is isomorphic to 
      <M>R/I</M>
<!--
gap> R := PolynomialRing(Integers, 4);;
gap> w := R.1;; x := R.2;;
gap> I := [w^2 + x, w^3 + x^3];
gap> ReduceIdeal(I, MonomialLexOrdering());

gap> ReducedPolynomialRingPresentation(R, I);
-->      
<!-- This should be an Example, but the autoloaded ResClasses package modifies
     Print for PolynomialRings, so the output differs if this package is
     available -->
<Log><![CDATA[
gap> R := PolynomialRing(Integers, 4);;
gap> w := R.1;; x := R.2;;
gap> I := [w^2 + x, w^3 + x^3];
[ x_1^2+x_2, x_1^3+x_2^3 ]
gap> ReduceIdeal(I, MonomialLexOrdering());
[ x_1^2+x_2, -x_2^3+x_1*x_2 ]
gap> 
gap> ReducedPolynomialRingPresentation(R, I);
[ Integers[x_5,x_6,x_7], [ x_5^6-x_5^3 ] ]
]]></Log>
    </Subsection>
  </Section>

  <Section>
    <Heading>Singular</Heading>

    <#Include Label="SingularSetNormalFormIdeal_manSingular">
    <#Include Label="SingularPolynomialNormalForm_manSingular">
    <#Include Label="SingularGroebnerBasis_manSingular">
    <#Include Label="SingularReducedGroebnerBasis_manSingular">

  </Section>

  <Section>
    <Heading>Groups</Heading>

    Small groups in &GAP; can be indexed by their small groups library number
    <Ref Sect="Small groups" BookName="ref"/>. An alternative indexing scheme,
    the Hall-Senior number, is used by Jon Carlson to publish his 
    cohomology ring calculations at 
    <URL>http://www.math.uga.edu/~lvalero/cohointro.html</URL>. To allow 
    comparison with these results, we
    provide a function that converts from the &GAP; small groups library numbers
    to Hall-Senior number for
    the groups of order 8, 16, 32 and 64.

    <#Include Label="HallSeniorNumber_manGroups">

  </Section>

</Chapter>