From 6b0a629a44f3da92307777822fefab4aaa0268f8 Mon Sep 17 00:00:00 2001 From: ThomasBreuer Date: Mon, 13 Apr 2026 17:58:54 +0200 Subject: [PATCH 1/3] a new section about matrix objects --- doc/ref/matobj.xml | 86 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) diff --git a/doc/ref/matobj.xml b/doc/ref/matobj.xml index 8ed8908e47..4c69f103ec 100644 --- a/doc/ref/matobj.xml +++ b/doc/ref/matobj.xml @@ -402,4 +402,90 @@ The following conventions hold for such a group G. + +
+How to Write Code for Vector and Matrix Objects + +Most ⪆ functions which deal with vector and matrix objects +are intended to accept any kind of these objects, +and if the output involves vector and matrix objects then these +are expected to be compatible with the inputs. +For example, a function that computes the Kronecker product of two +matrix objects mat1, mat2 may take the two inputs, +which must have the same + value, +create a new matrix object which also lies in this filter, +for example by calling ZeroMatrix( m, n, mat1 ), +and then set the entries in this matrix. + +

+ +Functions like +, +, +and +admit different kinds of inputs, +some of which leave the decision about the type of the output to ⪆. +For example, ZeroMatrix( R, m, n ) returns a matrix object in an +internal representation that is suitable for the base domain R. +However, if we want a matrix object that is compatible with a given +matrix object M then we are not allowed to call a variant +that involves such choices, +and we have to call ZeroMatrix( m, n, M ). + +

+ +This approach works also in many situation where the input involves +the list of list matrices in the filter . +In practice, the question is often the other way round: +One has old ⪆ code that was written for objects in , +and wants to rewrite it such that it works also for general matrix objects. +In such cases, the following rules may be useful. + + + + Use M[i, j] not M[i][j] + for accessing/assigning matrix entries. + + + Use ExtractSubMatrix( M, rows, cols ) not M{ rows }{ cols } + for accessing submatrices, + similarly use CopySubMatrix( src, dst, srows, drows, scols, dcols ). + + + Use ZeroVector( R, n ) not [ 1 .. n ] * Zero( R ) for a + given domain R. + + + Use ZeroVector( n, M ) not 0 * M[1] for a + given matrix object M with n columns. + + + Use + not . + + + Do not use the unary versions of + + and . + + + Use and the binary versions of + + and + only when creating initial objects + which need not be compatible with given vectors or matrices. + + + +Conversely, do not use functions for vector and matrix objects +when you want to create an object that shall be used just as a list. +For example, use ListWithIdenticalEntries( n, Zero( R ) ) +not Vector( R, n ) in this case. +For creating a list with n entries, you can also first call + for creating a big enough list, +and then enter the values. + +

+ From d2d1f457c08007807ec468c28511bc101bac0933 Mon Sep 17 00:00:00 2001 From: ThomasBreuer Date: Tue, 14 Apr 2026 11:13:06 +0200 Subject: [PATCH 2/3] address comments --- doc/ref/matobj.xml | 72 ++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 60 insertions(+), 12 deletions(-) diff --git a/doc/ref/matobj.xml b/doc/ref/matobj.xml index 4c69f103ec..25034e2bc8 100644 --- a/doc/ref/matobj.xml +++ b/doc/ref/matobj.xml @@ -406,14 +406,20 @@ The following conventions hold for such a group G.
How to Write Code for Vector and Matrix Objects -Most ⪆ functions which deal with vector and matrix objects -are intended to accept any kind of these objects, -and if the output involves vector and matrix objects then these -are expected to be compatible with the inputs. +Vector and matrix objects have a number of different representations in ⪆ +which are optimised for different things; +see the list for +examples of available + values +of matrix objects. +Most ⪆ functions accepting vector or matrix objects as arguments +do not depend on any particular representation for these objects. +If the output of such a function involves vector and matrix objects, +then these are expected to have the same representations as the inputs. For example, a function that computes the Kronecker product of two matrix objects mat1, mat2 may take the two inputs, which must have the same - value, + value, create a new matrix object which also lies in this filter, for example by calling ZeroMatrix( m, n, mat1 ), and then set the entries in this matrix. @@ -431,21 +437,25 @@ internal representation that is suitable for the base domain R. However, if we want a matrix object that is compatible with a given matrix object M then we are not allowed to call a variant that involves such choices, -and we have to call ZeroMatrix( m, n, M ). +and we have to call ZeroMatrix( m, n, M ) +or ZeroMatrix( ConstructingFilter( M ), BaseDomain( M ), m, n ).

This approach works also in many situation where the input involves the list of list matrices in the filter . In practice, the question is often the other way round: -One has old ⪆ code that was written for objects in , -and wants to rewrite it such that it works also for general matrix objects. -In such cases, the following rules may be useful. +one has old ⪆ code that was written for objects in , +and wants to rewrite it such that it works for general matrix objects also. +In such cases, the following guidelines may be useful. Use M[i, j] not M[i][j] for accessing/assigning matrix entries. +

+ Note that M[i][j] means to fetch or even create M[i] + and then take the j-th entry of it. Use ExtractSubMatrix( M, rows, cols ) not M{ rows }{ cols } @@ -453,28 +463,66 @@ In such cases, the following rules may be useful. similarly use CopySubMatrix( src, dst, srows, drows, scols, dcols ). - Use ZeroVector( R, n ) not [ 1 .. n ] * Zero( R ) for a - given domain R. + Use ZeroVector( R, n ) not [ 1 .. n ] * Zero( R ) for + creating a zero vector over a given domain R. +

+ The latter syntax creates an unnecessary new object [ 1 .. n ], + multiplies each of its entries with Zero( R ) + (not knowing that the result will be Zero( R ) in each case), + and creates not a vector object but a plain list of the results. Use ZeroVector( n, M ) not 0 * M[1] for a given matrix object M with n columns. +

+ Again, calling M[1] may have to create an unnecessary new object + M[1]. Use not . +

+ This is just a conceptual issue, the results should in fact coincide. + A matrix object M which is not a list of lists stores its + value. + For convenience, DefaultFieldOfMatrix( M ) is defined + to return this value (although this need not be a field). + On the other hand, a list of lists M in + does not store the two attribute values, + value is computed from the entries + of M, + and for convenience, BaseDomain( M ) is defined to return the + value. Do not use the unary versions of and . +

+ For example, consider the two matrices M1 = [ [ Z(4) ] ] and + M2 = [ [ Z(4)^3 ] ] over the field with four elements. + The latter is in fact a matrix over the field with two elements, + and ConvertToMatrixRep( M2 ) turns it into a matrix in + , whereas ConvertToMatrixRep( M1 ) + yields a matrix in . + Thus computing products or sums of these matrices is more expensive + than computations with two matrices in . - Use and the binary versions of + Use and the binary versions of and only when creating initial objects which need not be compatible with given vectors or matrices. +

+ The idea behind these functions is to choose a good representation + for initial data (for example for some expensive MeatAxe computations, + see Chapter ). + The results of computations with these data should then automatically + be in the same representation. + If not then the code in question has problems, + and adjusting the representation of intermediate results by + calling the abovementioned conversion functions just hides these problems. From 3b18126506b22885241ae8a1f1c023b2377948de Mon Sep 17 00:00:00 2001 From: ThomasBreuer Date: Tue, 14 Apr 2026 16:03:21 +0200 Subject: [PATCH 3/3] address new comments --- doc/ref/matobj.xml | 41 ++++++++++++++++++++++++++++++----------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/doc/ref/matobj.xml b/doc/ref/matobj.xml index 25034e2bc8..2818815902 100644 --- a/doc/ref/matobj.xml +++ b/doc/ref/matobj.xml @@ -430,15 +430,24 @@ Functions like , , and -admit different kinds of inputs, -some of which leave the decision about the type of the output to ⪆. -For example, ZeroMatrix( R, m, n ) returns a matrix object in an -internal representation that is suitable for the base domain R. -However, if we want a matrix object that is compatible with a given -matrix object M then we are not allowed to call a variant -that involves such choices, -and we have to call ZeroMatrix( m, n, M ) -or ZeroMatrix( ConstructingFilter( M ), BaseDomain( M ), m, n ). +admit different kinds of inputs. +ZeroMatrix( R, m, n ) can be used, for example, +if we want to leave the decision about the representation of the result +to ⪆. +This might be useful if the result of ZeroMatrix( R, m, n ) is +the first matrix we create, and then later matrices are created +relative to this matrix. +If we already have a matrix object M and want ZeroMatrix +to return a new matrix object that has the same representation as M, +then ZeroMatrix( R, m, n ) may not return a matrix with the expected +representation. +For example, even if we use the same R as before, ⪆ might decide +to use a sparse representation for large enough m and n. +It is possible to create a ZeroMatrix in the same representation +as M by fully specifying this representation as follows +ZeroMatrix( ConstructingFilter( M ), BaseDomain( M ), m, n ). +It is also possible to produce the same result using the more convenient +ZeroMatrix( m, n, M ).

@@ -454,18 +463,24 @@ In such cases, the following guidelines may be useful. Use M[i, j] not M[i][j] for accessing/assigning matrix entries.

- Note that M[i][j] means to fetch or even create M[i] + Reason: + M[i][j] means to fetch or even create M[i] and then take the j-th entry of it. Use ExtractSubMatrix( M, rows, cols ) not M{ rows }{ cols } for accessing submatrices, similarly use CopySubMatrix( src, dst, srows, drows, scols, dcols ). +

+ Reason: + The M{ rows } syntax is supported only for + row-list matrices, see . Use ZeroVector( R, n ) not [ 1 .. n ] * Zero( R ) for creating a zero vector over a given domain R.

+ Reason: The latter syntax creates an unnecessary new object [ 1 .. n ], multiplies each of its entries with Zero( R ) (not knowing that the result will be Zero( R ) in each case), @@ -475,13 +490,15 @@ In such cases, the following guidelines may be useful. Use ZeroVector( n, M ) not 0 * M[1] for a given matrix object M with n columns.

- Again, calling M[1] may have to create an unnecessary new object + Reason: + Calling M[1] may have to create an unnecessary new object M[1]. Use not .

+ Reason: This is just a conceptual issue, the results should in fact coincide. A matrix object M which is not a list of lists stores its value. @@ -499,6 +516,7 @@ In such cases, the following guidelines may be useful. and .

+ Reason: For example, consider the two matrices M1 = [ [ Z(4) ] ] and M2 = [ [ Z(4)^3 ] ] over the field with four elements. The latter is in fact a matrix over the field with two elements, @@ -515,6 +533,7 @@ In such cases, the following guidelines may be useful. only when creating initial objects which need not be compatible with given vectors or matrices.

+ Reason: The idea behind these functions is to choose a good representation for initial data (for example for some expensive MeatAxe computations, see Chapter ).