Add OnTuplesDigraphs and OnSetsDigraphs

[wilfwilson]

I keep writing temporary functions to implement these actions for my research, so I thought it was about time I just add them to the package.

Tasks:

• Decide how to handle mutable digraphs
• Decide whether we need something like IsDigraphByOutNeighboursRepCollection
• Document OnTuplesDigraphs
• Document OnSetsDigraphs

[james-d-mitchell]

@wilfwilson looks good, I'll be happy to discuss your first two points this afternoon if you want?

[wilfwilson]

For the second point, I think it's not necessary; these new operations use OnDigraphs to do the actual work, so in my opinion it's fine for OnDigraphs to do those checks, which it does. So if we did OnTuplesDigraphs for a non-IsDigraphByOutNeighboursRepCollection we'd get a no method found error for OnDigraphs.

[wilfwilson]

For the first point, I'm not sure. The current (and simplest to implement) behaviour, as demonstrated with digraph D that consists of 3 vertices and a single loop at vertex 1:

gap> D := EmptyDigraph(IsMutableDigraph, 3);; DigraphAddEdge(D, 1, 1);;
gap> l := [D, D];;
gap> out := OnTuplesDigraphs(l, (1,2,3));;
gap> l = out and out = [D, D];
true
gap> List(out, DigraphLoops);
[ [ 3 ], [ 3 ] ]

This just seems really weird to me, that you ask to apply the perm p to a list [D,D], but you end up with the list [D^(p^2),D^(p^2)]. But also it seems the most Digraphsy, and easiest to document: i.e. "OnTuplesDigraphs applies OnDigraphs in turn to each digraph in the tuple".

Of course, for immutable digraphs, you get the list [D^p, D^p] (each being a new immutable object).

[wilfwilson]

This now has documentation and tests, and it is now ready for review.

Hopefully it is clear from the documentation and implementation how I dealt with mutable digraphs: I copy them before acting on them by OnDigraphs.

I just didn't see a sensible use-case for OnTuplesDigraphs where mutable digraphs get changed in place, see e.g. my example in #449 (comment) (here the digraphs in the list essentially each get acted on twice, which I find deeply weird).

For OnSetsDigraphs, a set can't contain duplicate digraphs, so this particular weirdness can't occur. So perhaps there is a use-case for changing mutable digraphs in place for OnSetsDigraphs. Nevertheless, I think OnTuplesDigraphs and OnSetsDigraphs should be consistent.

It's also the list/set itself that we're acting on by OnTuplesDigraphs/OnSetsDigraphs, so although I think it would be alright for the list itself to mutate, it feels less appropriate for the GAP objects that it contains to get changed too. (What if a different list contains some of the same digraphs?).

In addition, I think OnTuplesDigraphs and OnSetsDigraphs will play more nicely with things like GAP's RepresentativeAction and Stabiliser if they don't mutate stuff.