4. Functionality
  
  
  4.1 Functions for creating forms
  
  4.1-1 BilinearFormByMatrix
  
  > BilinearFormByMatrix( m, f ) ____________________________________operation
  Returns:  a bilinear form
  
  The  argument  m  must be a square matrix over the finite field f. The field
  must be specified, as only the characteristic of the underlying field can be
  determined  by  the  entries  of m. The output will be a record rec( matrix,
  basefield, type ).
  
  ---------------------------  Example  ----------------------------
    gap> gf := GF(3^2);
    GF(3^2)
    gap> mat := IdentityMat(4, gf);
    [ [ Z(3)^0, 0*Z(3), 0*Z(3), 0*Z(3) ], [ 0*Z(3), Z(3)^0, 0*Z(3), 0*Z(3) ], 
      [ 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3) ], [ 0*Z(3), 0*Z(3), 0*Z(3), Z(3)^0 ] ]
    gap> f := BilinearFormByMatrix( mat, gf );
    < bilinear form >
    gap> Display(f);
    Bilinear form
    Gram Matrix:
     1 . . .
     . 1 . .
     . . 1 .
     . . . 1
  ------------------------------------------------------------------
  
  4.1-2 QuadraticFormByMatrix
  
  > QuadraticFormByMatrix( m, f ) ___________________________________operation
  Returns:  a quadratic form
  
  The  argument  m  must be a square matrix over the finite field f. The field
  must be specified, as only the characteristic of the underlying field can be
  determined  by  the  entries  of m. The output will be a record rec( matrix,
  basefield, type ).
  
  ---------------------------  Example  ----------------------------
    gap> gf := GF(2^2);
    GF(2^2)
    gap> mat := InvariantQuadraticForm( SO(-1, 4, 4) )!.matrix;
    [ [ 0*Z(2), Z(2)^0, 0*Z(2), 0*Z(2) ], [ 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2) ], 
      [ 0*Z(2), 0*Z(2), Z(2^2)^2, Z(2)^0 ], [ 0*Z(2), 0*Z(2), 0*Z(2), Z(2^2)^2 ] ]
    gap> f := QuadraticFormByMatrix( mat, gf );
    < quadratic form >
    gap> Display(f);
    Quadratic form
    Gram Matrix:
    z = Z(4)
       .   1   .   .
       .   .   .   .
       .   . z^2   1
       .   .   . z^2
  ------------------------------------------------------------------
  
  4.1-3 HermitianFormByMatrix
  
  > HermitianFormByMatrix( m, f ) ___________________________________operation
  Returns:  a quadratic form
  
  The  argument  m  must  be a square matrix over the finite field f of square
  order.  The  field  must  be  specified,  as  only the characteristic of the
  underlying field can be determined by the entries of m. The output will be a
  record rec( matrix, basefield, type ).
  
  ---------------------------  Example  ----------------------------
    gap> gf := GF(3^2);
    gap> mat := IdentityMat(4, gf);
    gap> f := HermitianFormByMatrix( mat, gf );
    < hermitian form >
    gap> Display(f);
    Hermitian form
    Gram Matrix:
     1 . . .
     . 1 . .
     . . 1 .
     . . . 1
    Witt Index: 2
  ------------------------------------------------------------------
  
  4.1-4 BilinearFormByPolynomial
  
  > BilinearFormByPolynomial( poly, r, n ) __________________________operation
  > BilinearFormByPolynomial( poly, r ) _____________________________operation
  Returns:  a bilinear form
  
  The  argument  poly  must  be  a  polynomial  in  the polynomial ring r. The
  (optional) last argument is the dimension for the underlying vector space of
  the  resulting  form,  which  by  default  is  the  number of indeterminates
  specified by poly.
  
  ---------------------------  Example  ----------------------------
    gap> r := PolynomialRing( GF(11), 4);
    GF(11)[x_1,x_2,x_3,x_4]
    gap> vars := IndeterminatesOfPolynomialRing( r );
    [ x_1, x_2, x_3, x_4 ]
    gap> pol := vars[1]*vars[2]+vars[3]*vars[4];
    x_1*x_2+x_3*x_4
    gap> form := BilinearFormByPolynomial(pol, r, 4);
    < bilinear form >
    gap> Display(form);
    Bilinear form
    Gram Matrix:
      .  6  .  .
      6  .  .  .
      .  .  .  6
      .  .  6  .
    Polynomial: x_1*x_2+x_3*x_4
    gap> ## Projective Points...
    gap> projpoints := List(Subspaces( GF(11)^4, 1 ), Representative);;
    gap> ## Number of totally isotropic points
    gap> Number(projpoints, t -> IsZero( [t, t]^form ));
    144
  ------------------------------------------------------------------
  
  4.1-5 QuadraticFormByPolynomial
  
  > QuadraticFormByPolynomial( poly, r, n ) _________________________operation
  > QuadraticFormByPolynomial( poly, r ) ____________________________operation
  Returns:  a quadratic form
  
  The  argument  poly  must  be  a  polynomial  in  the polynomial ring r. The
  (optional) last argument is the dimension for the underlying vector space of
  the  resulting  form,  which  by  default  is  the  number of indeterminates
  specified by poly.
  
  ---------------------------  Example  ----------------------------
    gap> r := PolynomialRing( GF(8), 3);
    GF(2^3)[x_1,x_2,x_3]
    gap> poly := r.1^2 + r.2^2 + r.3^2;
    x_1^2+x_2^2+x_3^2
    gap> form := QuadraticFormByPolynomial(poly, r);
    < quadratic form >
    gap> RadicalOfForm(form);
    <vector space over GF(2^3), with 3 generators>
  ------------------------------------------------------------------
  
  4.1-6 HermitianFormByPolynomial
  
  > HermitianFormByPolynomial( poly, r, n ) _________________________operation
  > HermitianFormByPolynomial( poly, r ) ____________________________operation
  Returns:  an hermitian form
  
  The  argument  poly  must  be a polynomial in the polynomial ring r (defined
  over  a  finite  field of square order). The (optional) last argument is the
  dimension  for  the  underlying vector space of the resulting form, which by
  default is the number of indeterminates specified by poly.
  
  ---------------------------  Example  ----------------------------
    gap> r := PolynomialRing( GF(9), 4);
    GF(3^2)[x_1,x_2,x_3,x_4]
    gap> vars := IndeterminatesOfPolynomialRing( r );
    [ x_1, x_2, x_3, x_4 ]
    gap> poly := vars[1]*vars[2]^3+vars[1]^3*vars[2]+vars[3]*vars[4]^3+vars[3]^3*vars[4];
    x_1^3*x_2+x_1*x_2^3+x_3^3*x_4+x_3*x_4^3
    gap> form := HermitianFormByPolynomial(poly,r);
    < hermitian form >
    gap> Display(form);
    Hermitian form
    Gram Matrix:
     . 1 . .
     1 . . .
     . . . 1
     . . 1 .
    Polynomial: x_1^3*x_2+x_1*x_2^3+x_3^3*x_4+x_3*x_4^3
  ------------------------------------------------------------------
  
  
  4.2 Attributes and properties of forms
  
  4.2-1 IsReflexiveForm
  
  > IsReflexiveForm( f ) ____________________________________________attribute
  Returns:  true or false.
  
  A  sesquilinear  form  f  is reflexive if whenever we have f(u,v)=0, then we
  also have f(v,u)=0. This operation simply returns true or false.
  
  4.2-2 IsAlternatingForm
  
  > IsAlternatingForm( f ) __________________________________________attribute
  Returns:  true or false.
  
  A  bilinear  form  f  is  alternating  if f(v,v)=0 for all v. This operation
  simply returns true or false.
  
  4.2-3 IsSymmetricForm
  
  > IsSymmetricForm( f ) ____________________________________________attribute
  Returns:  true or false.
  
  A  bilinear  form f is symmetric if f(u,v)=f(v,u) for all pairs of vectors u
  and v. This operation simply returns true or false.
  
  4.2-4 IsDegenerateForm
  
  > IsDegenerateForm( f ) ___________________________________________attribute
  Returns:  true or false.
  
  A sesquilinear form f is degenerate if there exists a nonzero vector v which
  is  orthogonal to every other vector. That is, f(v,w)=0 for all w. Likewise,
  a  quadratic  form  Q is degenerate if there is a nonzero vector v such that
  Q(v)=0. This operation simply returns true or false.
  
  4.2-5 BaseField
  
  > BaseField( f ) __________________________________________________attribute
  Returns:  the underlying field of f.
  
  4.2-6 GramMatrix
  
  > GramMatrix( f ) _________________________________________________attribute
  Returns:  the associated Gram matrix of f.
  
  4.2-7 WittIndex
  
  > WittIndex( f ) __________________________________________________attribute
  Returns:  the Witt index of f.
  
  The  Witt  index is the maximum dimension of a totally singular subspace. So
  for  example,  if  f  is  a  symplectic  form  and d is the dimension of its
  underlying vector space, then the Witt index of f is d/2.
  
  4.2-8 RadicalOfForm
  
  > RadicalOfForm( f ) ______________________________________________attribute
  Returns:  a subspace, the radical, of the vectors space associated with f.
  
  ---------------------------  Example  ----------------------------
    gap> r := PolynomialRing( GF(8), 3 );
    GF(2^3)[x_1,x_2,x_3]
    gap> poly := r.1^2 + r.2 * r.3;
    x_1^2+x_2*x_3
    gap> form := QuadraticFormByPolynomial( poly, r );
    < quadratic form >
    gap> RadicalOfForm( form );
    <vector space of dimension 1 over GF(2^3)>
  ------------------------------------------------------------------
  
  4.2-9 PolynomialOfForm
  
  > PolynomialOfForm( f ) ___________________________________________attribute
  Returns:  the polynomial associated with f.
  
  ---------------------------  Example  ----------------------------
    gap> mat := [ [ Z(8) , 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2) ], 
     [ 0*Z(2), Z(2)^0, Z(2^3)^5, 0*Z(2), 0*Z(2) ], 
     [ 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2) ], 
     [ 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0 ], 
     [ 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2) ] ];;
    gap> form := QuadraticFormByMatrix(mat,GF(8));
    < quadratic form >
    gap> PolynomialOfForm(form);
    Z(2^3)*x_1^2+x_2^2+Z(2^3)^5*x_2*x_3+x_4*x_5
  ------------------------------------------------------------------
  
  4.2-10 DiscriminantOfForm
  
  > DiscriminantOfForm( f ) _________________________________________attribute
  Returns:  a string
  
  Given  a  quadratic or sesquilinear form f, this operation returns a string:
  ``square''  or  ``nonsquare''.  Discriminants  can  be used to delineate the
  isometry type of an orthogonal form in even (algebraic) dimension.
  
  ---------------------------  Example  ----------------------------
    gap> gram := InvariantQuadraticForm(GO(-1,4,5))!.matrix;;
    gap> f := QuadraticFormByMatrix(gram, GF(5));
    < quadratic form >
    gap> DiscriminantOfForm(f);
    "nonsquare"
  ------------------------------------------------------------------
  
  
  4.3 Functions for changing forms
  
  4.3-1 BaseChangeToCanonical
  
  > BaseChangeToCanonical( f ) ______________________________________operation
  Returns:  a base-transition matrix
  
  The argument f is a sesquilinear or quadratic form. For every isometry class
  of  forms,  there  is a canonical representative, which is in block diagonal
  form.  If  M is the Gram matrix of the form f, then b * M * TransposedMat(b)
  is the Gram matrix of the canonical representative.
  
  ---------------------------  Example  ----------------------------
    gap> f := GF(3);
    GF(3)
    gap> gram := [
    [0,0,0,1,0,0], 
    [0,0,0,0,1,0],
    [0,0,0,0,0,1],
    [-1,0,0,0,0,0],
    [0,-1,0,0,0,0],
    [0,0,-1,0,0,0]] * One(f);;
    gap> form := BilinearFormByMatrix( gram, f );
    < bilinear form >
    gap> b := BaseChangeToCanonical( form );;
    gap> Display( b * gram * TransposedMat(b) );
     . 1 . . . .
     2 . . . . .
     . . . 1 . .
     . . 2 . . .
     . . . . . 1
     . . . . 2 .
  ------------------------------------------------------------------
  
  4.3-2 IsometricCanonicalForm
  
  > IsometricCanonicalForm( f ) _____________________________________attribute
  Returns:  the canonical form isometric to the sesquilinear or quadratic form
            f.
  
  For  every  isometry  type  of  sesquilinear  or  quadratic form, there is a
  canonical  one.  In  Forms,  the  canonical form of each class is that which
  preserves the natural hyperbolic line decomposition (see Secton 3.5).
  
  ---------------------------  Example  ----------------------------
    gap> mat := [ [ Z(8) , 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2) ], 
    [ 0*Z(2), Z(2)^0, Z(2^3)^5, 0*Z(2), 0*Z(2) ], 
    [ 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2) ], 
    [ 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), Z(2)^0 ], 
    [ 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2), 0*Z(2) ] ];;
    gap> form := QuadraticFormByMatrix(mat,GF(8));
    < quadratic form >
    gap> iso := IsometricCanonicalForm(form);
    < quadratic form >
    gap> Display(form);
    Quadratic form
    Gram Matrix:
    z = Z(8)
     z^1   .   .   .   .
       .   1 z^5   .   .
       .   .   .   .   .
       .   .   .   .   1
       .   .   .   .   .
    Witt Index: 2
    gap> Display(iso);
    Quadratic form
    Gram Matrix:
     1 . . . .
     . . 1 . .
     . . . . .
     . . . . 1
     . . . . .
    Witt Index: 2
  ------------------------------------------------------------------
  
  
  4.4 Operations on forms
  
  4.4-1 BaseChangeHomomorphism
  
  > BaseChangeHomomorphism( b, gf ) _________________________________operation
  Returns:  the    inner   automorphism   of   GL(d,q)   associated   to   the
            base-transition b.
  
  The argument b must be an invertible matrix over the finite field gf.
  
  ---------------------------  Example  ----------------------------
    gap> gl:=GL(3,3);
    GL(3,3)
    gap> go:=GO(3,3);
    GO(0,3,3)
    gap> gram:=InvariantBilinearForm(go)!.matrix;
    [ [ 0*Z(3), Z(3)^0, 0*Z(3) ], [ Z(3)^0, 0*Z(3), 0*Z(3) ], [ 0*Z(3), 0*Z(3), Z(3) ] ]
    gap> f:=FormByMatrix(gram,GF(3),"parabolic");
    < bilinear form >
    gap> b:=BaseChangeToCanonical(f);;
    gap> hom := BaseChangeHomomorphism(b, GF(3));
    ^[ [ 0*Z(3), 0*Z(3), Z(3) ], [ Z(3), Z(3), Z(3)^0 ], [ Z(3), 0*Z(3), Z(3) ] ]
    gap> newgo := Image(hom, go); 
    Group(
    [ [ [ Z(3)^0, 0*Z(3), Z(3) ], [ Z(3)^0, Z(3), Z(3)^0 ], [ 0*Z(3), 0*Z(3), Z(3) ] ], 
      [ [ Z(3), Z(3)^0, 0*Z(3) ], [ 0*Z(3), Z(3), 0*Z(3) ], [ Z(3)^0, Z(3)^0, Z(3) ] ] ])
    gap> gens:=GeneratorsOfGroup(newgo);;
    gap> canonical := b * gram * TransposedMat(b);
    [ [ Z(3), 0*Z(3), 0*Z(3) ], [ 0*Z(3), 0*Z(3), Z(3)^0 ], [ 0*Z(3), Z(3)^0, 0*Z(3) ] ]
    gap> ForAll(gens, y -> y * canonical * TransposedMat(y) = canonical);
    true
  ------------------------------------------------------------------
  
  4.4-2 EvaluateForm
  
  > EvaluateForm( f, u, v ) _________________________________________operation
  > EvaluateForm( f, u ) ____________________________________________operation
  Returns:  a finite field element
  
  The  argument  f  is  either a sesquilinear or quadratic form defined over a
  finite  field GF(q). The other argument is a pair of vectors or matrices, or
  a  single  vector or matrix, which represent the bases of given subspaces of
  GF(q)^d.  There  is also an overloading of the operation \^ which we show in
  the following example:
  
  ---------------------------  Example  ----------------------------
    gap> mat := [[Z(8),0,0,0],[0,0,Z(8)^4,0],[0,0,0,1],[0,0,0,0]]*Z(8)^0;;
    gap> form := QuadraticFormByMatrix(mat,GF(8));
    < quadratic form >
    gap> u := [ Z(2^3)^4, Z(2^3)^4, Z(2)^0, Z(2^3)^3 ];
    [ Z(2^3)^4, Z(2^3)^4, Z(2)^0, Z(2^3)^3 ]
    gap> EvaluateForm( form, u );
    Z(2^3)^6
    gap> u^form;
    Z(2^3)^6
  ------------------------------------------------------------------
  
  Here is an example using sesquilinear forms...
  
  ---------------------------  Example  ----------------------------
    gap> gram := [[0,0,0,0,0,2],[0,0,0,0,2,0],[0,0,0,1,0,0],[0,0,1,0,0,0],
     [0,2,0,0,0,0],[2,0,0,0,0,0]]*Z(3)^0;;
    gap> form := BilinearFormByMatrix(gram,GF(3));
    < bilinear form >
    gap> u := [ [ Z(3)^0, 0*Z(3), 0*Z(3), Z(3)^0, 0*Z(3), Z(3)^0 ], 
      [ 0*Z(3), 0*Z(3), Z(3)^0, Z(3)^0, Z(3), 0*Z(3) ] ];;
    gap> v := [ [ Z(3)^0, 0*Z(3), Z(3)^0, Z(3), 0*Z(3), Z(3) ], 
      [ 0*Z(3), Z(3)^0, 0*Z(3), Z(3), Z(3), Z(3) ] ];;
    gap> EvaluateForm( form, u, v);
    [ [ Z(3)^0, Z(3)^0 ], [ 0*Z(3), 0*Z(3) ] ]
    gap> [u,v]^form;
    [ [ Z(3)^0, Z(3)^0 ], [ 0*Z(3), 0*Z(3) ] ]
  ------------------------------------------------------------------