Update recog doc and include user-friendly chapter #364

AnnaKDS · 2025-12-11T19:32:58Z

I am working on improving the documentation to include a chapter that is particularly directed to people who want to recognise groups with this package and don't have much theoretical background.

It's still WIP but if you have any suggestions, please feel free to comment.

codecov · 2025-12-11T19:35:19Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 69.12%. Comparing base (6d84867) to head (cecdf1f).
⚠️ Report is 10 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #364      +/-   ##
==========================================
- Coverage   78.55%   69.12%   -9.43%     
==========================================
  Files          43       43              
  Lines       18281    18321      +40     
==========================================
- Hits        14361    12665    -1696     
- Misses       3920     5656    +1736

see 18 files with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

aniemeyer · 2025-12-11T19:48:37Z

doc/user.xml

+<Heading>Examples</Heading>
+
+In order to understand the output we consider some examples. Note that many
+methods used to compute a recognition tree a randomised algorithms. This means


change a randomised to are randomised

Suggested change

methods used to compute a recognition tree a randomised algorithms. This means

methods used to compute a recognition tree are randomised. This means

or

Suggested change

methods used to compute a recognition tree a randomised algorithms. This means

methods used to compute a recognition tree are using randomised algorithms. This means

aniemeyer · 2025-12-11T19:51:20Z

doc/user.xml

+factor of <M>H</M> (abbreviated with <Q>F</Q> which stands for Factor) and a normal
+subgroup of <M>H</M> (abbreviated with <Q>K</Q> which stands for Kernel). <P/>
+
+In this example the root node presents the input group <M>SL(10,5)</M>. Starting


presents -> represents (note: represents is also used below)

Suggested change

In this example the root node presents the input group <M>SL(10,5)</M>. Starting

In this example the root node represents the input group <M>SL(10,5)</M>. Starting

aniemeyer · 2025-12-11T20:14:08Z

doc/user.xml

+H</M>, and then recursively analysing both the kernel
+<M>\ker(\varphi) = N \unlhd G</M> and the image
+im<M>(\varphi) \cong G/N</M>. This continues until the remaining groups
+are (quasi-)simple, which are the fundamental building blocks of all


We might also allow almost simple, e.g. we treat S_n as a leaf

aniemeyer · 2025-12-11T20:19:30Z

doc/user.xml

+<recognition node MovesOnlySmallPoints Size=3628800>]]>
+</Log>
+
+This recognition tree only consists of the root node representing the input


Here `root node' is mentioned. Should it be stated above that RecogniseGroup always returns the root node?

aniemeyer · 2025-12-11T20:20:39Z

doc/user.xml

+</Log>
+
+Note that the first few lines are not part of the returned recognition node. You
+can obtain these further information by setting the InfoLevel accordingly.


replace these' by such'

aniemeyer · 2025-12-11T20:30:47Z

doc/intro.xml

-The setup is described in <Cite Key="NS06"/>. <P/>
-
-The framework allows to build composition trees and handles the builtup
+This package is about group recognition.<P/>


I think this statement is a bit misleading. Really, this package is about computing a data structure to enable the user to answer questions about a given group. The actual `recognition' as described in the paragraph below really occurs at the leaf nodes and not necessarily for the input group. Maybe we could say: This package is about building a data structure for a group which encodes a composition tree and the recognition of groups closely related to the composition factors?

ThomasBreuer · 2025-12-12T08:50:38Z

makedoc.g

+            "user.xml",
            "recognition.xml",
            "methsel.xml",
-            "afterrecog.xml",


If this chapter shall be left out then also the cross-reference in Section "Overview over this manual" must be removed (label "afterrecog").

ThomasBreuer · 2025-12-12T08:54:42Z

doc/user.xml

+
+<#Include Label="RecognisePermGroup">
+<#Include Label="RecogniseMatrixGroup">
+<#Include Label="RecogniseProjectiveGroup">


Currently the four Recognize*Group functions are included in two chapters, GAPDoc prints warnings about that,
I suggest to include RecognizeGroup here and to include the other three functions in Chapter "Group recognition".

ThomasBreuer · 2025-12-12T09:02:46Z

doc/intro.xml

 Chapter <Ref Chap="install"/> describes the installation of this package.<P/>

+Chapter <Ref Chap="user"/> presents a user-friendly introduction to this
+package.<P/>


Perhaps emphasize that examples are shown in the Section "Examples".
(And remove the now outdated reference at the end of the "Overview" section ("Finally, Chapter ... shows some instructive examples ...").

ThomasBreuer · 2025-12-12T10:54:48Z

some general remarks:

The introduction distinguishes "naming" and "constructive recognition".
Can a user ask just for the result of the "naming" phase, or is the result of the user functions always that of the "constructive recognition"? In the latter case, the distinction of the two phases belongs to a more technical part of the manual.
Chapter "Group recognition" distinguishes a "recognition phase" and a "verification phase".
What is the status of the results of RecognizeGroup: Is the return value always verified, or may it be incorrect? Asked the other way round: Can one ask for a result without verification?

ThomasBreuer · 2025-12-12T11:05:05Z

doc/user.xml

+
+In order to work with group elements efficiently and constructively throughout
+this process, 
+<Package>recog</Package> uses <Q>Straight-Line Programs</Q> (or <Q>SLPs</Q>). An <Q>SLP</Q> is a


Perhaps add a cross-reference to the section on straight line programs in the GAP Reference Manual.

doc/intro.xml

+
 Chapter <Ref Chap="recognition"/> describes the generic, recursive procedure
 used for group recognition throughout this package. At the heart of this
 procedure is the definition of <Q>FindHomomorphism</Q> methods, which is also


fingolfin · 2025-12-12T12:16:03Z

@ThomasBreuer currently verification is not implemented. But it definitely should be made possible for the user to control whether verification happens; and also perhaps certain probabilities.

frankluebeck

This is a welcome improvement of the recog documentation.

I have added a few more comments.

After addressing the current comments this should be merged soon. Of course, it can be further improved any time later.

fingolfin · 2025-12-12T15:42:50Z

I agree with @frankluebeck: I'd rather merge this sooner than later. Even if there are still TODO comment in there. Once it is merged, follow-up PRs can further improve things.

Update recog doc and include user-friendly chapter

cecdf1f

AnnaKDS requested review from ThomasBreuer, aniemeyer, fingolfin and frankluebeck December 11, 2025 19:32

AnnaKDS self-assigned this Dec 11, 2025

aniemeyer approved these changes Dec 11, 2025

View reviewed changes

ThomasBreuer reviewed Dec 12, 2025

View reviewed changes

fingolfin reviewed Dec 12, 2025

View reviewed changes

doc/intro.xml

Chapter <Ref Chap="recognition"/> describes the generic, recursive procedure

used for group recognition throughout this package. At the heart of this

procedure is the definition of <Q>FindHomomorphism</Q> methods, which is also

This comment was marked as duplicate.

Sign in to view

frankluebeck reviewed Dec 12, 2025

View reviewed changes

	methods used to compute a recognition tree a randomised algorithms. This means
	methods used to compute a recognition tree are randomised. This means

	In this example the root node presents the input group <M>SL(10,5)</M>. Starting
	In this example the root node represents the input group <M>SL(10,5)</M>. Starting

Update recog doc and include user-friendly chapter #364

Are you sure you want to change the base?

Update recog doc and include user-friendly chapter #364

Uh oh!

Conversation

AnnaKDS commented Dec 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov bot commented Dec 11, 2025

Codecov Report

Uh oh!

aniemeyer Dec 11, 2025 • edited by fingolfin Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ThomasBreuer commented Dec 12, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as duplicate.

Uh oh!

fingolfin commented Dec 12, 2025

Uh oh!

frankluebeck left a comment

Choose a reason for hiding this comment

Uh oh!

fingolfin commented Dec 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

AnnaKDS commented Dec 11, 2025 •

edited

Loading

aniemeyer Dec 11, 2025 •

edited by fingolfin

Loading