improved (documentation of) two MTX functions

- fixed `MTX.OrthogonalSign` in the case of antisymmetric bilinear forms in odd characteristic (now returns `fail`)
- improved the documentation of `MTX.InvariantQuadraticForm` and `MTX.OrthogonalSign`, as discussed in issue #4936
- added some tests

doc/ref/makedocreldata.g

@@ -116,6 +116,7 @@ GAPInfo.ManualDataRef:= rec(
     "../../lib/matobj2.gd",
     "../../lib/matobjplist.gd",
     "../../lib/matrix.gd",
+    "../../lib/meataxe.gi",
     "../../lib/memusage.gd",
     "../../lib/methsel2.g",
     "../../lib/methwhy.g",

doc/ref/meataxe.xml

@@ -597,17 +597,7 @@ or <K>fail</K> if no such form exists.
 </ManSection>
 
 
-<ManSection>
-<Func Name="MTX.InvariantQuadraticForm" Arg='module'/>
-
-<Description>
-returns an invariant quadratic form of <A>module</A>,
-or <K>fail</K> if no such form exists. If the characteristic of the field over
-which <A>module</A> is defined is not 2, then the invariant bilinear form (if
-any) divided by two will be returned. In characteristic 2, the form
-returned will be lower triangular.
-</Description>
-</ManSection>
+<#Include Label="MTX.InvariantQuadraticForm">
 
 
 <ManSection>
@@ -621,17 +611,7 @@ This is used by <Ref Func="MTX.InvariantQuadraticForm"/> in characteristic 2.
 </ManSection>
 
 
-<ManSection>
-<Func Name="MTX.OrthogonalSign" Arg='module'/>
-
-<Description>
-for an even dimensional module, returns 1 or -1, according as
-<C>MTX.InvariantQuadraticForm(<A>module</A>)</C> is of + or - type. For an odd
-dimensional module, returns 0. For a module with no invariant
-quadratic form, returns <K>fail</K>. This calculation uses an algorithm due
-to Jon Thackray.
-</Description>
-</ManSection>
+<#Include Label="MTX.OrthogonalSign">
 
 </Section>
 

lib/meataxe.gi

@@ -3413,10 +3413,50 @@ end;
 
 #############################################################################
 ##
-#F  InvariantQuadraticForm( module ) . . . .
+#F  MTX.InvariantQuadraticForm( <module> )
+##
+##  <#GAPDoc Label="MTX.InvariantQuadraticForm">
+##  <ManSection>
+##  <Func Name="MTX.InvariantQuadraticForm" Arg='module'/>
+##
+##  <Description>
+##  returns either the matrix of an invariant quadratic form of the
+##  absolutely irreducible module <A>module</A>, or <K>fail</K>.
+##  <P/>
+##  If the characteristic of <A>module</A> is odd then <K>fail</K> is
+##  returned if there is no nonzero invariant bilinear form,
+##  otherwise a matrix of the bilinear form
+##  divided by <M>2</M> is returned;
+##  note that this matrix may be antisymmetric and thus describe the zero
+##  quadratic form.
+##  If the characteristic of <A>module</A> is <M>2</M> then <K>fail</K> is
+##  returned if <A>module</A> does not admit a nonzero quadratic form,
+##  otherwise a lower triangular matrix describing the form is returned.
+##  <P/>
+##  An error is signalled if <A>module</A> is not absolutely irreducible.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> g:= SO(-1, 4, 2);;
+##  gap> m:= GModuleByMats( GeneratorsOfGroup( g ), GF(2) );;
+##  gap> Display( MTX.InvariantQuadraticForm( m ) );
+##   . . . .
+##   1 . . .
+##   . . 1 .
+##   . . 1 1
+##  gap> g:= SP(4, 2);;
+##  gap> m:= GModuleByMats( GeneratorsOfGroup( g ), GF(2) );;
+##  gap> MTX.InvariantQuadraticForm( m );
+##  fail
+##  gap> g:= SP(4, 3);;
+##  gap> m:= GModuleByMats( GeneratorsOfGroup( g ), GF(3) );;
+##  gap> q:= MTX.InvariantQuadraticForm( m );;
+##  gap> q = - TransposedMat( q );  # antisymmetric inv. bilinear form
+##  true
+##  ]]></Example>
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
 ##
-## Look for an invariant quadratic form of the absolutely irreducible
-## GModule module. Return fail, or the matrix of the form.
 SMTX_InvariantQuadraticForm:=function( module  )
    local iso, bas, cgens, ciso, dim, f, z, x, i, j, qf, g, id, cqf, fix;
 
@@ -3483,23 +3523,47 @@ SMTX.InvariantQuadraticForm:=SMTX_InvariantQuadraticForm;
 
 #############################################################################
 ##
-#F  OrthogonalSign( module ) . . . .
-##
-## When an absolutely irreducible G-module has an invariant quadratic
-## form, this implies that it embeds in a General Orthogonal group. In
-## even dimension there are two non-isomorphic General Orthogonal groups
-## "plus" and "minus" type `GeneralOrthogonalGroup(+1,<n>,<q>)' and
-## `GeneralOrthogobalGroup(-1,<n>,<q>)' in GAP terms. This function
-## decides which one the module embeds into.
-##
-## It returns:
-##  fail if the module is not absolutely irreducible, or
-##       does not stabilize a quadratic form.
-##  0    otherwise, if the dimension of the module is odd
-##  +1 or -1 otherwise, according to which GO the module embeds in
+#F  MTX.OrthogonalSign( <module> ) . . . .
+##
+##  <#GAPDoc Label="MTX.OrthogonalSign">
+##  <ManSection>
+##  <Func Name="MTX.OrthogonalSign" Arg='module'/>
+##
+##  <Description>
+##  Let <A>module</A> be an absolutely irreducible <M>G</M>-module.
+##  If <A>module</A> does not fix a nondegenerate quadratic form
+##  see <Ref Func="MTX.InvariantQuadraticForm"/>
+##  then <K>fail</K> is returned.
+##  Otherwise the sign <M>\epsilon \in \{ -1, 0, 1 \}</M> is returned
+##  such that <M>G</M> embeds into the general orthogonal group
+##  <M>GO^{\epsilon}(d, q)</M> w.r.t. the invariant quadratic form,
+##  see <Ref Func="GeneralOrthogonalGroup"/>.
+##  That is, <C>0</C> is returned if <A>module</A> has odd dimension,
+##  and <C>1</C> or <C>-1</C> is returned if the orthogonal group has
+##  plus or minus type, respectively.
+##  <P/>
+##  An error is signalled if <A>module</A> is not absolutely irreducible.
+##  <P/>
+##  The <C>SMTX</C> implementation uses an algorithm due to Jon Thackray.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> mats:= GeneratorsOfGroup( GO(1,4,2) );;
+##  gap> MTX.OrthogonalSign( GModuleByMats( mats, GF(2) ) );
+##  1
+##  gap> mats:= GeneratorsOfGroup( GO(-1,4,2) );;
+##  gap> MTX.OrthogonalSign( GModuleByMats( mats, GF(2) ) );
+##  -1
+##  gap> mats:= GeneratorsOfGroup( GO(5,3) );;
+##  gap> MTX.OrthogonalSign( GModuleByMats( mats, GF(3) ) );
+##  0
+##  gap> mats:= GeneratorsOfGroup( SP(4,2) );;
+##  gap> MTX.OrthogonalSign( GModuleByMats( mats, GF(2) ) );
+##  fail
+##  ]]></Example>
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
 ##
-## This is an implementation of an algorithm by Jon Thackray
-
 SMTX.SetOrthogonalSign:=function(module,s)
   module.OrthogonalSign:=s;
 end;
@@ -3514,6 +3578,10 @@ SMTX_OrthogonalSign:=function(gm)
     q:=MTX.InvariantQuadraticForm(gm);
     if q = fail then
         return fail;
+    elif IsOddInt( Characteristic( gm.field ) ) and
+         q <> TransposedMat( q ) then
+        # There is no *nondegenerate* invariant quadratic form.
+        return fail;
     fi;
     n:=Length(b);
     if n mod 2 = 1 then

tst/testinstall/meataxe.tst

@@ -1,4 +1,4 @@
-#@local G,M,M2,M3,M4,M5,V,bf,bo,cf,homs,m,mat,qf,randM,res,sf,subs
+#@local G,M,M2,M3,M4,M5,V,bf,bo,cf,homs,m,mat,qf,randM,res,sf,subs,mats,Q
 gap> START_TEST("meataxe.tst");
 
 #
@@ -184,5 +184,68 @@ gap> Display(res[5]);
  . . . . 1 .
  . . . . . 1
 
+#
+# Tests for MTX.InvariantQuadraticForm and MTX.OrthogonalSign
+# (the documentation is a bit unorthodox)
+#
+# the easy cases:
+gap> mats:= GeneratorsOfGroup( GO( 1, 4, 3 ) );;
+gap> m:= GModuleByMats( mats, GF(3) );;
+gap> Q:= MTX.InvariantQuadraticForm( m );;
+gap> Q = TransposedMat( Q );  # bilinear form divided by 2
+true
+gap> MTX.OrthogonalSign( m );
+1
+gap> mats:= GeneratorsOfGroup( GO( -1, 4, 3 ) );;
+gap> m:= GModuleByMats( mats, GF(3) );;
+gap> Q:= MTX.InvariantQuadraticForm( m );;
+gap> Q = TransposedMat( Q );  # bilinear form divided by 2
+true
+gap> MTX.OrthogonalSign( m );
+-1
+gap> mats:= GeneratorsOfGroup( GO( 5, 3 ) );;
+gap> m:= GModuleByMats( mats, GF(3) );;
+gap> Q:= MTX.InvariantQuadraticForm( m );;
+gap> Q = TransposedMat( Q );  # bilinear form divided by 2
+true
+gap> MTX.OrthogonalSign( m );
+0
+gap> mats:= GeneratorsOfGroup( GO( 1, 4, 2 ) );;
+gap> m:= GModuleByMats( mats, GF(2) );;
+gap> Q:= MTX.InvariantQuadraticForm( m );;
+gap> IsLowerTriangularMat( Q );  # characteristic 2
+true
+gap> MTX.OrthogonalSign( m );
+1
+gap> mats:= GeneratorsOfGroup( GO( 5, 2 ) );;
+gap> m:= GModuleByMats( mats, GF(2) );;
+gap> MTX.InvariantQuadraticForm( m );
+Error, Argument of InvariantQuadraticForm is not an absolutely irreducible mod\
+ule
+gap> MTX.OrthogonalSign( m );
+Error, Argument of InvariantBilinearForm is not an absolutely irreducible modu\
+le
+gap> mats:= GeneratorsOfGroup( SP( 4, 2 ) );;
+gap> m:= GModuleByMats( mats, GF(2) );;
+gap> Q:= MTX.InvariantQuadraticForm( m );
+fail
+gap> MTX.OrthogonalSign( m );
+fail
+gap> g:= SU(4, 3);;
+gap> m:= GModuleByMats( GeneratorsOfGroup( g ), GF(9) );;
+gap> MTX.InvariantBilinearForm( m );
+fail
+gap> MTX.InvariantQuadraticForm( m );
+fail
+
+# the subtle case: odd characteristic, antisymmetric bilinear form
+gap> mats:= GeneratorsOfGroup( SP( 4, 3 ) );;
+gap> m:= GModuleByMats( mats, GF(3) );;
+gap> Q:= MTX.InvariantQuadraticForm( m );;  # matrix for the zero form
+gap> Q = TransposedMat( Q );
+false
+gap> MTX.OrthogonalSign( m );
+fail
+
 #
 gap> STOP_TEST("meataxe.tst", 1);