Fix and document argument handling of Blocks, Cycle, Permutation and related functions; Blocks and RepresentativesMinimalBlocks now reject intransitive actions

[fingolfin]

• Fixes Documentation of ActionHomomorphism is misleading #3484: ActionHomomorphism: "this homomorphism is a permutation equivalence" reads as a claim about the returned map, which is false for unfaithful actions. Name the actual identification of Omega with [1..|Omega|] instead.
• Fixes Clarify documentation for MaximalBlocks #4700: MaximalBlocks: "blocks are maximal with respect to inclusion" also describes [ Omega ]. Say maximal among the proper subsets of Omega, i.e. the induced action is primitive, and what happens for a primitive action.
• Fixes Improve argument checking in Cycles and other related functions #3720: Permutation, PermutationCycle, Cycle, Cycles indexed arg unguarded, so Cycles(g) died with List Element: <list>[2] must have an assigned value. Adds usage guards, and documents the gens, acts forms, the external set forms, and one argument CycleIndex, all previously implemented but undocumented. Also fixes a recursion trap in the gens, acts form of Cycle and CycleLength, which built the action homomorphism from an external orbit rather than an external set.
• Fixes Error message for Blocks is incorrect #3541: OrbitishFO used one hard coded usage message for every operation it creates; the Blocks family may now pass its own. Also Blocks(<G>,1) reports the usage instead of "no method found for BlocksOp on 5 arguments".
• Fixes Blocks should either work for intransitive actions or consistently reject them #3364: BlocksOp returned [ Omega ] for a domain of prime size before checking transitivity, so an intransitive group either errored or returned nonsense depending on the degree. Check first, take the shortcut second; same in RepresentativesMinimalBlocksOp; add the check to the seeded BlocksOp method, which had none.

Behaviour change: Blocks and friends now raise an error in cases where they used to return a meaningless result. The two spellings of that error message now agree ("must act transitively").

Prepared with AI assistance (Claude).

[codecov]

Codecov Report

❌ Patch coverage is 96.87500% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.00%. Comparing base (e0bc786) to head (242ccc1).

Files with missing lines	Patch %	Lines
lib/ghomperm.gi	87.50%	1 Missing ⚠️
lib/oprt.gd	94.73%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #6520      +/-   ##
==========================================
+ Coverage   78.96%   79.00%   +0.03%     
==========================================
  Files         685      685              
  Lines      294270   294310      +40     
  Branches     8669     8669              
==========================================
+ Hits       232364   232508     +144     
+ Misses      60102    59996     -106     
- Partials     1804     1806       +2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[ThomasBreuer]

The following example from the just closed #4904 is not yet addressed, a fix would fit into the current pull request.

gap> g:= Group( [ (2,4,3), (3,4) ] );
Group([ (2,4,3), (3,4) ])
gap> hom:= ActionHomomorphism( g, [ 3, 4 ], OnPoints );
<action homomorphism>
gap> MappingGeneratorsImages( hom );
[ [ (2,4,3), (3,4) ], [ fail, (1,2) ] ]
gap> Image( hom );
Error, no method found! For debugging hints type ?Recovery from NoMethodFound
Error, no 1st choice method found for `MagmaWithInversesByGenerators' on 1 arguments
[...]

[ThomasBreuer]

Looks good. Thanks.

[fingolfin]

@ThomasBreuer you were completely right to question the use of Orbit here before; it was in fact measurably impacting performance (negatively, of course).

But with OrbitPerms called directly, the overhead is very small; and in addition it can now be turned off by passing check:=false as a global option.

[ThomasBreuer]

Nice.