Improve documentation and argument checks for `StabChainBaseStrongGenerators` #4602

wilfwilson · 2021-07-07T17:42:33Z

I made a note to myself to document the 2-argument version of StabChainBaseStrongGenerators (which was already implemented and is probably what most people would want to use). I finally got around to it, and in the process I made a few other small improvements: added a manual example; added tests; added some argument checks.

(Can anyone think when you might want the one to not be ()?)

ssiccha

LGTM. I've got a suggestion, but am not sure whether that's an improvement.

lib/stbc.gd

ssiccha · 2021-07-07T20:17:13Z

And I have no idea when one would be something else than (). Could one also be an identity of a semi-group, which accidentally also is a group or something like that? 🤷‍♂️

When sgs only is empty if G is trivial. Or am I misunderstanding the function.

fingolfin · 2021-07-07T20:18:41Z

lib/stbc.gi

    else
-      one:= One(arg[2][1]);
+      ErrorNoReturn("the identity element must be given as the third argument ",
+                    "when the second argument <sgs> is empty");


But... why? Why don't we simply always do one:= ()?

Good question, I have no idea. As I asked at the top of this thread:

(Can anyone think when you might want the one to not be ()?)

I can't think of a use case. Maybe @ChrisJefferson has an idea?

And @ssiccha – this function is documented to only apply to permutation groups, so it can't be because of semigroups.

Sorry, I missed that question at the top 😊

The only package calling StabChainBaseStrongGenerators is grape and it also passes () as third argument.

But in TryPcgsPermGroup, though, we pass U.identity... That gave me a clue: we have

lib/memory.gi:108: S.identity := S.identity!.el;

So perhaps this is meant to allow supporting "permutations with memory" as produced by GeneratorsWithMemory?

Looking at git blame, the line in TryPcgsPermGroup was added by @hulpke 21 years ago in this commit:

Author: Alexander Hulpke <hulpke@math.colostate.edu> AuthorDate: 2000-01-25 18:50:09 +0000 Commit: Alexander Hulpke <hulpke@math.colostate.edu> CommitDate: 2000-01-25 18:50:09 +0000 StabChainBaseStrongGenerators gets the appropriate `One' (this permits other permutation representations). SM&AH.

Perhaps he recalls something?

If we use other representations (e.g. elements with memory, or straight line program elements) the identity element will be given in this representation.
Please do not change this -- I am relying on it sometimes in private code.

No intention to change it -- but clearly the documentation for this function then is wrong / incomplete

Thanks for the explanation @hulpke, and don't worry, my purpose of the PR is to make the documentation match the behaviour of the code by changing the documentation, rather than to change the behaviour of the code.

However, I now feel a bit out of my depth, since I don't yet know anything about other representations for permutations in GAP.

I am also now worried that #4331 broke StabChainBaseStrongGenerators for your private code @hulpke – could you please check? In particular, the assertion Assert(2, S.labels[1] = ()); is perhaps invalid, if a one other than () is specified.

That should (apart from anyhow being in an assertion) be harmless as objects with memory would have to compare as equal to ().
The reason for the different one is if elements get created that will be used later on. By starting with the correct `one' allos to build a proper word expression on the way.

wilfwilson · 2021-07-08T08:45:36Z

@ssiccha Yes a stabiliser chain can only have an empty set of strong generators if it is trivial. The 2-argument behaviour prior to this PR is:

gap> StabChainBaseStrongGenerators([1], []);
Error, List Element: <list>[1] must have an assigned value in
  one := One( arg[2][1] ); at /Users/Wilf/gap/lib/stbc.gi:406 called from
<function "StabChainBaseStrongGenerators">( <arguments> )

So I feel that a specific error message is more helpful. A stabiliser chain needs to know its corresponding identity, so we can't guess it in that case.

wilfwilson · 2021-07-08T08:46:24Z

lib/stbc.gi

@@ -398,12 +398,20 @@ end);
 InstallGlobalFunction(StabChainBaseStrongGenerators,function(arg)
 local   base,sgs,one,S,  T,  pnt, genlabels;

+    if not Length(arg) in [2, 3]
+        or not ForAll([1, 2], i -> IsHomogeneousList(arg[i])) then


Is it valid to assume that valid bases and strong generating sets will be homogeneous lists?

I think it is but perhaps @hulpke and/or @ChrisJefferson may want to comment?

I think it's reasonable

fingolfin · 2021-07-21T10:37:54Z

This PR looks good to me. But I'd prefer if @hulpke could approve it, too (or point out any issues, of course!). If @ChrisJefferson also has time to look at it: even better :-)

wilfwilson · 2021-07-26T09:15:08Z

That's fine, there's certainly no rush to get this merged.

From my point of view, this PR is doing three things:

✅ More accurately document the current behaviour (and I think we are now happy that the current behaviour is correct)
✅ Add tests (harmless)
❓ ✅ Check that the second and optional third arguments are homogeneous lists ('list' is fine, but 'homogeneous' is possibly dubious; therefore I could remove the Homogeneous part to make this completely uncontroversial). Chris says it's okay in Improve documentation and argument checks for StabChainBaseStrongGenerators #4602 (comment) 🙂

ChrisJefferson · 2021-08-18T15:40:54Z

I'm happy with this PR, as long as it doesn't break anything @hulpke is doing (I wouldn't expect so)

wilfwilson added topic: documentation Issues and PRs related to documentation topic: library release notes: not needed PRs introducing changes that are wholly irrelevant to the release notes labels Jul 7, 2021

wilfwilson requested a review from ChrisJefferson July 7, 2021 17:42

ssiccha approved these changes Jul 7, 2021

View reviewed changes

lib/stbc.gd Outdated Show resolved Hide resolved

fingolfin reviewed Jul 7, 2021

View reviewed changes

Improve doc and argchecks for StabChainBaseStrongGenerators

14bdfc6

wilfwilson force-pushed the ww/improve-StabChainBSGS-doc-and-arg-handling branch from 5ac7db1 to 14bdfc6 Compare July 8, 2021 08:14

wilfwilson commented Jul 8, 2021

View reviewed changes

wilfwilson added the priority: low label Jul 26, 2021

fingolfin merged commit 6f2a849 into gap-system:master Aug 25, 2021

wilfwilson deleted the ww/improve-StabChainBSGS-doc-and-arg-handling branch August 28, 2021 12:56

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve documentation and argument checks for `StabChainBaseStrongGenerators` #4602

Improve documentation and argument checks for `StabChainBaseStrongGenerators` #4602

wilfwilson commented Jul 7, 2021

ssiccha left a comment

ssiccha commented Jul 7, 2021

fingolfin Jul 7, 2021

wilfwilson Jul 7, 2021 •

edited

Loading

fingolfin Jul 7, 2021

fingolfin Jul 7, 2021

hulpke Jul 7, 2021 •

edited

Loading

fingolfin Jul 8, 2021

wilfwilson Jul 8, 2021 •

edited

Loading

hulpke Jul 12, 2021

wilfwilson commented Jul 8, 2021

wilfwilson Jul 8, 2021

fingolfin Jul 21, 2021

ChrisJefferson Aug 18, 2021

fingolfin commented Jul 21, 2021

wilfwilson commented Jul 26, 2021 •

edited

Loading

ChrisJefferson commented Aug 18, 2021

Improve documentation and argument checks for StabChainBaseStrongGenerators #4602

Improve documentation and argument checks for StabChainBaseStrongGenerators #4602

Conversation

wilfwilson commented Jul 7, 2021

ssiccha left a comment

Choose a reason for hiding this comment

ssiccha commented Jul 7, 2021

Choose a reason for hiding this comment

wilfwilson Jul 7, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

hulpke Jul 7, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wilfwilson Jul 8, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wilfwilson commented Jul 8, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fingolfin commented Jul 21, 2021

wilfwilson commented Jul 26, 2021 • edited Loading

ChrisJefferson commented Aug 18, 2021

Improve documentation and argument checks for `StabChainBaseStrongGenerators` #4602

Improve documentation and argument checks for `StabChainBaseStrongGenerators` #4602

wilfwilson Jul 7, 2021 •

edited

Loading

hulpke Jul 7, 2021 •

edited

Loading

wilfwilson Jul 8, 2021 •

edited

Loading

wilfwilson commented Jul 26, 2021 •

edited

Loading