add a manual section: how to write code for matrix objects

[ThomasBreuer]

Collect some rules how to write code that works for for matrix objects and if applicable also for "list of list" matrices.

Ideas for more entries are welcome.

(motivated by the discussion in gap-packages/nofoma/pull/87)

[james-d-mitchell]

This reads a little like "functions for dealing with X accept X" which is tautological. I think you mean: "functions for dealing with vector and matrix objects are intended to accept objects in any representation" or something similar. It might be useful to mention where one can read about the different representations here and/or may amend what you've written to say:

Vector and matrix objects have a number of different representations in ⪆ which are optimised for different things; see for example .... 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, if the input to XXX belongs to the representation IsYYY, then the output will belong to IsYYY also.

[james-d-mitchell]

I see you've already got the "For example.." sorry, should have read everything first.

[james-d-mitchell]

I'm not sure I follow this sentence: couldn't we call ZeroMatrix(IsPlistRep, BaseDomain(M), m, n); if M belonged to IsPlistRep? If so, then who or what is not allowing us to do this?

[ThomasBreuer]

The sentence is "... we are not allowed to call a variant that involves such choices, ...", this is the main point.

Yes, we can write ZeroMatrix( ConstructingFilter( M ), BaseDomain( M ), m, n ) but ZeroMatrix( m, n, M ) is simpler if the matrix M is given. I will rewrite the last part of the sentence accordingly.

[james-d-mitchell]

Thanks @ThomasBreuer, I still don't really understand the first part of the sentence, specifically what is not allowed and by who? Otherwise, the changes are great, and I'd be happy if this was merged.

[ThomasBreuer]

What I want to say:

• In principle the different signatures of ZeroMatrix make sense.
• ZeroMatrix( R, m, n ) can be used if we want to leave the decision about the representation of the result to GAP; this can be useful if the result is the first matrix we create, and then later matrices are created relative to this matrix.
• If we have already a matrix object M and want ZeroMatrix to return a new matrix object that fits to M then we cannot leave the decision to GAP. (For example, even if we use the same R as before, GAP might decide to use a sparse representation for large enough m and n.)
• In this situation, we have to prescribe the intended representation. Thus ZeroMatrix( R, m, n ) cannot be used. I would express this by saying say that ZeroMatrix( R, m, n ) is not allowed in this situation. What would be better?

[james-d-mitchell]

Thanks @ThomasBreuer I understand now, how about the following version of what you've just written?

ZeroMatrix( R, m, n ) can be used, for example, if we want to leave the decision about the representation of the result to GAP. 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, GAP 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 ).

Probably this can be improved further, but I think it clearly says what you had in mind, and it is possible to understand what it meant.

This is perhaps no longer important, but I think the issue I have with the original wording was that "cannot" and "not allowed" are too strong. Of course nothing can stop me from typing ZeroMatrix(R, m, n) I just won't get the answer I hoped for, if you see what I mean. Saying "we are not allowed" makes it sounds like we'd get an error or something would prevent us from doing this, which of course it won't.

[james-d-mitchell]

I think this is super helpful, and could be merged as is, although I've made a few suggestions that might make it clearer still. In the "rules" at the end, it might be helpful to have some rationale for why these rules are preferable to the alternatives, but that could also be done later.

[james-d-mitchell]

Again presumably better because the intermediate object M{rows} is not created?

[fingolfin]

That, and also the {...} syntax may not be available at all (it can only be supported in general for row-list matrices).

Perhaps there should be a general pattern: terse "rule" to follow (just what to do), optionally followed by an explanation; perhaps in a visually distinct style: new paragraph, and then a key phrase ("The reason for this is/are"; or just "Background:" or "Motivation:", possibly in italics or so)

[fingolfin]

Maybe expand it?

Suggested change

	Use <C>ZeroVector( R, n )</C> not <C>[ 1 .. n ] * Zero( R )</C> for
	Use <C>ZeroVector( R, n )</C> not <C>[ 1 .. n ] * Zero( R )</C> or
	<C>ListWithIdenticalEntries( n, Zero( R ) )</C> or similar constructs for

[fingolfin]

Should we also point out that IdentityMat / NullMat should be replaced by IdentityMatrix / ZeroMatrix ?

[fingolfin]

Perhaps also ExtractSubVector and CopySubVector should be mentioned?

[fingolfin]

Great start, happy to merge it (though let's wait if @james-d-mitchell has further comments)

I wonder if some code snippets / examples here and there would be useful. But perhaps the best way to find out is to find someone (e.g. during GAP Days) who doesn't know MatrixObj stuff yet, and let them try to figure out, with the help of this guide, how to convert some functions in the GAP library or in a package to support MatrixObj

[ThomasBreuer]

I wonder if some code snippets / examples here and there would be useful.

I am not sure what "examples" means here.

If it is about examples how to write functions for new matrix object implementations then I think it is better to point to available implementations in the GAP library (if they are in a reasonable state). Copying and modifying such code should be the recommended way to proceed.
(For example, point to the "generic" implementation from #6322 as soon as it is available.)

If it is about using matrix objects for example in MeatAxe like situations then perhaps it would be useful to turn the description of the dangerous unary ConvertToMatrixRep into an explicit example, and to add more such examples.

[james-d-mitchell]

Looks good no further changes from me!

[cdwensley]

I wonder if some code snippets / examples here and there would be useful.
As someone not involved with this development, I find the 22 pages of chapter 26 (from 26.3 onwards), without any examples at all, quite unacceptable - it makes the operations introduced far too difficult to assimilate. Perhaps, as "someone who doesn't know MatrixObj stuff yet" I could help?

[fingolfin]

@cdwensley yeah I fully agree: that chapter needs lots and lots of usage examples; and some of those will surely also benefit from discussing (and showing!) difference compared to the "old" way of doing things. However, of course this doesn't have to be done in this PR.

If you were willing to help with that, it would be greatly appreciated. And of course it wouldn't have be "everything" -- just improving one function at a time can be super helpful. My suggestion would be to just start it (and if you get stuck because something is unclear, just ask -- e.g. open a "draft" PR with the incomplete changes and ask for comments on specific sections, @ThomasBreuer and me will be happy to help!