Add a minimal matrix object implementation

lib/matobjminimal.gd

@@ -0,0 +1,81 @@
+#############################################################################
+##
+##  This file is part of GAP, a system for computational discrete algebra.
+##
+##  SPDX-License-Identifier: GPL-2.0-or-later
+##
+##  Copyright of GAP belongs to its developers, whose names are too numerous
+##  to list here. Please refer to the COPYRIGHT file for details.
+##
+
+############################################################################
+#
+# This is a minimal implementation for nxm matrices 
+# stored as a flat n*m element list. In this 
+# file the representation, types and global 
+# functions are declared.
+# This implementation should not be used for actual computations. It serves
+# as an example for a minimal MatrixObj implementation and can be used to test
+# various things.
+
+
+#############################################################################
+##
+##  <#GAPDoc Label="IsMinimalExampleMatrixRep">
+##  <ManSection>
+##  <Filt Name="IsMinimalExampleMatrixRep" Arg='obj' Type="representation"/>
+##
+##  <Description>
+##  An object <A>obj</A> in <Ref Filt="IsMinimalExampleMatrixRep"/> describes
+##  a matrix object that stores the matrix entries as a flat list. It is 
+##  internally represented as a positional object
+##  (see <Ref Filt="IsPositionalObjectRep"/> that stores 4 entries:
+##  <Enum>
+##  <Item>
+##    its base domain
+##    (see <Ref Attr="BaseDomain" Label="for a matrix object"/>),
+##  </Item>
+##  <Item>
+##    the number of rows (see <Ref Attr="NumberRows" Label="for a matrix object"/>), 
+##  </Item>
+##  <Item>
+##    the number of columns
+##    (see <Ref Attr="NumberColumns" Label="for a matrix object"/>), and
+##  </Item>
+##  <Item>
+##    a plain list (see <Ref Filt="IsPlistRep"/> of its entries.
+##  </Item>
+##  </Enum>
+##  It implements the MatrixObj specification in a minimal way, that is it 
+##  implements exactly the required methods. This is intended for testing and
+##  development and should not be used for actual calculations!
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+# Here we declare the new representation and tell GAP which properties it
+# implies. This minimal example is implemented as a positional object 
+# like IsFlistMatrixRep and IsPlistMatrixRep.
+DeclareRepresentation( "IsMinimalExampleMatrixRep",
+        IsMatrixObj and IsMatrixOrMatrixObj and IsPositionalObjectRep
+    and IsNoImmediateMethodsObject
+    and HasNumberRows and HasNumberColumns
+    and HasBaseDomain and HasOneOfBaseDomain and HasZeroOfBaseDomain,
+    [] );
+
+# If we implement our object as a positional object we often have to access its
+# properties in the code. To make that more readable we declare global
+# variables. If you do this too make sure you use variables that are unique and
+# unlikely to be used someplace else, even though that might mean using longer
+# names. Here we prefixed the names with the name of the representation. See
+# also Reference Manual Chapter 79 for more information about Objects.
+
+# Some constants for matrix access:
+# Position in the positional object of the base domain
+BindGlobal( "MINREP_BDPOS", 1 );
+# Position in the positional object of the number of rows
+BindGlobal( "MINREP_NRPOS", 2 );
+# Position in the positional object of the number of columns
+BindGlobal( "MINREP_NCPOS", 3 );
+# Position in the positional object of the list of entries
+BindGlobal( "MINREP_ELSPOS", 4 );

lib/matobjminimal.gi

@@ -0,0 +1,106 @@
+#############################################################################
+##
+##  This file is part of GAP, a system for computational discrete algebra.
+##
+##  SPDX-License-Identifier: GPL-2.0-or-later
+##
+##  Copyright of GAP belongs to its developers, whose names are too numerous
+##  to list here. Please refer to the COPYRIGHT file for details.
+##
+
+############################################################################
+#
+# This file is a minimal implementation for new style vectors and matrices.
+# It stores matrices as a dense flat list.
+# This implementation implements only the methods required by the specification
+# for matrix objects. This is intended for testing and as an example.
+# The assertions in the code can help catch errors. It it up to the programmer
+# whether or not wrong inputs are always caught, never caught or only handled
+# via assertions as is done here. 
+
+InstallMethod( NewMatrix,
+  "for IsMinimalExampleMatrixRep, a ring, an int, and a list",
+  [ IsMinimalExampleMatrixRep, IsRing, IsInt, IsList ],
+  function( filter, basedomain, nrcols, list_in )
+    local obj, filter2, list, rowindex, colindex;
+
+    # If applicable then replace a nested list 'list_in' by a flat list 'list'.
+    if Length(list_in) > 0 and (IsVectorObj(list_in[1]) or IsList(list_in[1])) then
+        list := [];
+        for rowindex in [1..Length(list_in)] do 
+            if Length(list_in[rowindex]) <> nrcols then
+                Error( "NewMatrix: Each row must have nrcols entries." );
+            fi;
+            for colindex in [1..nrcols] do
+                Assert(2, list_in[rowindex][colindex] in basedomain); 
+                list[(rowindex-1)*nrcols + colindex] := list_in[rowindex][colindex];
+            od;
+        od;
+    else
+        if Length(list_in) mod nrcols <> 0 then 
+            Error( "NewMatrix: Length of list must be a multiple of ncols." );
+        fi;
+        list := list_in;
+    fi;
+
+    obj := [basedomain,Length(list)/nrcols,nrcols,list];
+    filter2 := IsMinimalExampleMatrixRep and IsMutable;
+    if HasCanEasilyCompareElements(Representative(basedomain)) and
+       CanEasilyCompareElements(Representative(basedomain)) then
+        filter2 := filter2 and CanEasilyCompareElements;
+    fi;
+    Objectify( NewType(CollectionsFamily(FamilyObj(basedomain)),
+                       filter2),  obj);
+    return obj;
+end );
+
+InstallMethod( BaseDomain, "for a minimal example matrix rep",
+  [ IsMinimalExampleMatrixRep ],
+  function( m )
+    return m![MINREP_BDPOS];
+  end );
+
+InstallMethod( NumberRows, "for a minimal example matrix rep",
+  [ IsMinimalExampleMatrixRep ],
+  function( m )
+    return m![MINREP_NRPOS];
+  end );
+
+InstallMethod( NumberColumns, "for a minimal example matrix rep",
+  [ IsMinimalExampleMatrixRep ],
+  function( m )
+    return m![MINREP_NCPOS];
+  end );
+
+InstallMethod( MatElm, "for an minimal example matrix rep and two positions",
+  [ IsMinimalExampleMatrixRep, IsPosInt, IsPosInt ],
+  function( mat, row, col )
+    Assert(2, 1 <= row and row <= mat![MINREP_NRPOS]);
+    Assert(2, 1 <= col and col <= mat![MINREP_NCPOS]);
+    return mat![MINREP_ELSPOS][(row-1)*mat![MINREP_NCPOS]+col];
+end );
+
+InstallMethod( SetMatElm, "for an minimal example matrix rep, two positions, and an object",
+  [ IsMinimalExampleMatrixRep and IsMutable, IsPosInt, IsPosInt, IsObject ],
+  function( mat, row, col, obj )
+    Assert(2, 1 <= row and row <= mat![MINREP_NRPOS]);
+    Assert(2, 1 <= col and col <= mat![MINREP_NCPOS]);
+    Assert(2, obj in mat![MINREP_BDPOS]);
+    mat![MINREP_ELSPOS][(row-1)*mat![MINREP_NCPOS]+col] := obj;
+end );
+
+InstallMethod( \<, "for two minimal example matrices",
+  [ IsMinimalExampleMatrixRep, IsMinimalExampleMatrixRep ],
+  function( a, b )
+    return LT_LIST_LIST_DEFAULT(a![MINREP_ELSPOS],b![MINREP_ELSPOS]);
+end );
+
+InstallMethod( ConstructingFilter, "for a minimal example matrix rep",
+  [ IsMinimalExampleMatrixRep ],
+  function( mat )
+    return IsMinimalExampleMatrixRep;
+end );
+
+InstallMethod( CompatibleVectorFilter, [ IsMinimalExampleMatrixRep ],
+  M -> IsPlistVectorRep );
+

lib/read3.g

@@ -107,6 +107,7 @@ ReadLib( "wordass.gd"  );
 ReadLib( "matobj2.gd"  );
 ReadLib( "matobjplist.gd" );
 ReadLib( "matobjnz.gd" );
+ReadLib( "matobjminimal.gd" );
 
 # files dealing with rewriting systems
 ReadLib( "rws.gd"      );

lib/read5.g

@@ -114,6 +114,7 @@ ReadLib( "vec8bit.gi"  );
 ReadLib( "mat8bit.gi"  );
 ReadLib( "matobjplist.gi" );
 ReadLib( "matobjnz.gi" );
+ReadLib( "matobjminimal.gi" );
 ReadLib( "meataxe.gi"  );
 ReadLib( "meatauto.gi" );