Skip to content

Commit

Permalink
Deprecate (Set)InfoACELevel (#38)
Browse files Browse the repository at this point in the history
  • Loading branch information
fingolfin authored Jun 18, 2024
1 parent 33e0bd7 commit fe16771
Show file tree
Hide file tree
Showing 10 changed files with 50 additions and 64 deletions.
4 changes: 2 additions & 2 deletions CHANGES.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,10 +63,10 @@ development.
* PackageInfo.g,README,VERSION,doc/{manual,ace,install}.tex:
- routine changes
* tst/aceds.tst
- Info lines in example only appear when `InfoACELevel` is set to 3.
- Info lines in example only appear when `InfoACE` is set to 3.
This has been wrong for a while. It was wrong in Version 5.0.
Line `SetInfoACELevel(3)` added. Some additional lines also appear
at this `InfoACELevel`. These and some further tidy-ups done.
at this `InfoACE` level. These and some further tidy-ups done.

## Version 5.1 (2012-01-22)
Last GAP 4.4 version.
Expand Down
36 changes: 11 additions & 25 deletions doc/ace.tex
Original file line number Diff line number Diff line change
Expand Up @@ -259,11 +259,11 @@
line (i.e.~there is exactly one coset number) {\ACE} *did* need to
define more than 2 coset numbers. To find out just how many were
required before the final collapse, let's set the `InfoLevel' of
`InfoACE' (see~"SetInfoACELevel") to 2, so that the {\ACE} enumeration
`InfoACE' (see~"InfoACE") to 2, so that the {\ACE} enumeration
result is printed.

\beginexample
gap> SetInfoACELevel(2);
gap> SetInfoLevel(InfoACE, 2);
gap> ACECosetTable(fgens, rels, [c]);
#I INDEX = 1 (a=1 r=2 h=2 n=2; l=6 c=0.00; m=2049 t=3127)
[ [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ], [ 1 ],
Expand Down Expand Up @@ -585,16 +585,16 @@
*Notes*

Most examples use the `mess' ($= `messages'$) option. To see the
effect of this, it is recommended to do: `SetInfoACELevel(3);' before
calling `ACEExample', with an example.
effect of this, it is recommended to do: `SetInfoLevel(InfoACE, 3);'
before calling `ACEExample', with an example.

The coset table output from `ACEExample', when called with many of the
examples and with the {\ACE} function `ACECosetTableFromGensAndRels'
is often quite long. Recall that the output may be suppressed by
following the (`ACEExample') command with a double semicolon (`;;').

Also, try `SetInfoACELevel(2);' before calling `ACEExample', with an
example.
Also, try `SetInfoLevel(InfoACE, 2);' before calling `ACEExample',
with an example.

If you unexpectedly observe `aceexampleoptions' in your output, then
most probably you have unintentionally passed options by the global
Expand Down Expand Up @@ -783,36 +783,22 @@
1, and it is recommended that you leave it at this level, or higher.
Only messages which we think that the user will really want to see are
directed to `Info' at `InfoACE' level 1. To turn off *all* `InfoACE'
messaging, set the `InfoACE' level to 0 (see~"SetInfoACELevel"). For
convenience, we provide the function
messaging, set the `InfoACE' level to 0 (see~"InfoACE").

\>InfoACELevel() F

which returns the current `InfoLevel' of `InfoACE', i.e.~it is simply
a shorthand for `InfoLevel(InfoACE)'.

To set the `InfoLevel' of `InfoACE' we also provide

\>SetInfoACELevel( <level> ) F
\>SetInfoACELevel() F

which for a non-negative integer <level>, sets the `InfoLevel' of
`InfoACE' to <level> (i.e.~it is a shorthand for
`SetInfoLevel(InfoACE, <level>)'), or with no arguments sets the
`InfoACE' level to the default value 1. Currently, information from
Currently, information from
{\ACE} is directed to `Info' at four `InfoACE' levels: 1, 2, 3 and 4.
The command

\beginexample
gap> SetInfoACELevel(2);
gap> SetInfoLevel(InfoACE, 2);

\endexample

enables the display of the results line of an enumeration from {\ACE},
whereas

\beginexample
gap> SetInfoACELevel(3);
gap> SetInfoLevel(InfoACE, 3);

\endexample

Expand All @@ -823,7 +809,7 @@
will be displayed via `Info'. Finally,

\beginexample
gap> SetInfoACELevel(4);
gap> SetInfoLevel(InfoACE, 4);

\endexample

Expand Down
26 changes: 13 additions & 13 deletions doc/examples.tex
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@
going on behind the scenes.

\beginexample
gap> SetInfoACELevel(3); # Just to see what's going on behind the scenes
gap> SetInfoLevel(InfoACE, 3); # Just to see what's going on behind the scenes
gap> # Recall that we did: TCENUM:=ACETCENUM;;
gap> G := PerfectGroup(IsPermGroup, 16*60, 1 # Arguments ... as per usual
> : max := 50, mess := 10 # ... but we use ACE options
Expand Down Expand Up @@ -128,7 +128,7 @@
The following example calls {\ACE} for up to 800 coset numbers (`max
:= 800') using Mendelsohn style relator processing (`mendelsohn') and
sets progress messages to be printed every 500 iterations (`messages
:=500'); we do ```SetInfoACELevel(3);''' so that we may see these
:=500'); we do ```SetInfoLevel(InfoACE, 3);''' so that we may see these
messages. The value of `table', i.e.~the {\GAP} coset table,
immediately follows the last {\ACE} message (```\#I ''') line, but
both the coset table from {\ACE} and the {\GAP} coset table have been
Expand All @@ -139,7 +139,7 @@
that the final table output here is `lenlex' standardised.)

\beginexample
gap> SetInfoACELevel(3); # So we can see the progress messages
gap> SetInfoLevel(InfoACE, 3); # So we can see the progress messages
gap> G := PerfectGroup(IsSubgroupFpGroup,2^5*60, 2);;# See previous example:
gap> # "Example where ACE is made the
gap> # Standard Coset Enumerator"
Expand Down Expand Up @@ -208,15 +208,15 @@
here) only, without parameter information. The result line is visible
in the `Info'-ed component of the output below because we set the
`InfoLevel' of `InfoACE' to a value of at least 2 (in fact we set it
to 3; doing ```SetInfoACELevel(2);''' would make *only* the result
to 3; doing ```SetInfoLevel(InfoACE, 2);''' would make *only* the result
line visible). We have however used the option `echo', so that we can
see how the interface handled the arguments and options. On-line try:
`SetInfoACELevel(3); ACEExample("A5-C5", ACEStart);' (this is nearly
`SetInfoLevel(InfoACE, 3); ACEExample("A5-C5", ACEStart);' (this is nearly
equivalent to the sequence following, but the variables `F', `a', `b',
`G' are not accessible, being ``local'' to `ACEExample').

\beginexample
gap> SetInfoACELevel(3); # So we can see output from ACE binary
gap> SetInfoLevel(InfoACE, 3); # So we can see output from ACE binary
gap> F := FreeGroup("a","b");; a := F.1;; b := F.2;;
gap> G := F / [a^2, b^3, (a*b)^5 ];
<fp group on the generators [ a, b ]>
Expand Down Expand Up @@ -345,12 +345,12 @@
#I 4. Try the *-ed examples to explore how to modify options when an
#I enumeration fails (just follow the instructions you get within the
#I break-loop, or see Notes 2. and 3.).
#I 5. Try `SetInfoACELevel(3);' before calling ACEExample, to see the
#I 5. Try `SetInfoLevel(InfoACE, 3);' before calling ACEExample, to see the
#I effect of setting the "mess" (= "messages") option.
#I 6. To suppress a long output, use a double semicolon (`;;') after the
#I ACEExample command. (However, this does not suppress Info-ed output.)
#I 7. Also, try `SetInfoACELevel(2);' or `SetInfoACELevel(4);' before
#I calling ACEExample.
#I 7. Also, try `SetInfoLevel(InfoACE, 2);' or `SetInfoLevel(InfoACE, 4);'
#I before calling ACEExample.
gap>

\endexample
Expand Down Expand Up @@ -382,7 +382,7 @@
{\ACE} ``Run Parameters'' block).

\beginexample
gap> SetInfoACELevel(3);
gap> SetInfoLevel(InfoACE, 3);
gap> ACEExample("F27-purec");
#I # ACEExample "F27-purec" : enumeration of cosets of H in G,
#I # where G = F(2,7) = C_29, H = Id, using purec strategy.
Expand Down Expand Up @@ -481,7 +481,7 @@
our new options are *last*.

\beginexample
gap> SetInfoACELevel(2);
gap> SetInfoLevel(InfoACE, 2);
gap> ACEExample("F27-purec", ACECosetTableFromGensAndRels
> : sg := ["c"], subgroup := "< c >", messages := 0);
#I # ACEExample "F27-purec" : enumeration of cosets of H in G,
Expand Down Expand Up @@ -791,7 +791,7 @@
\endexample
%display{nontext}
The output (`Info'-ed at `InfoACELevel' 1) states that a number of new
The output (`Info'-ed at `InfoACE' level 1) states that a number of new
functions are defined. During a {\GAP} session, you can find out
details of these functions by typing:
Expand All @@ -801,7 +801,7 @@
%enddisplay
%display{nonhtml}
%The output (`Info'-ed at `InfoACELevel' 1) states that a number of
%The output (`Info'-ed at `InfoACE' level 1) states that a number of
%functions and variables have been defined, which we will now describe.
%
%\>PGRelFind( <fgens>, <rels>, <sgens> ) F
Expand Down
4 changes: 2 additions & 2 deletions doc/interact.tex
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@

The user will probably benefit most from interactive use of {\ACE} by
setting the `InfoLevel' of `InfoACE' to at least 3
(see~"SetInfoACELevel"), particularly if she uses the `messages'
(see~"InfoACE"), particularly if she uses the `messages'
option with a non-zero value.

Have you read the various options warnings yet? If not, please take
Expand Down Expand Up @@ -1516,7 +1516,7 @@
write <string> to the <i>th or default interactive {\ACE} process;
<string> must be in exactly the form the {\ACE} standalone expects.
The command is echoed via `Info' at `InfoACE' level 4 (with a
```ToACE> ''' prompt); i.e.~`SetInfoACELevel(4);' will allow you to
```ToACE> ''' prompt); i.e.~`SetInfoLevel(InfoACE, 4);' will allow you to
see what is transmitted to the {\ACE} binary. `ACEWrite' returns `true'
if successful in writing to the stream of the interactive {\ACE} process,
and `fail' otherwise.
Expand Down
2 changes: 1 addition & 1 deletion doc/messages.tex
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@
`InfoLevel' of `InfoACE' to at least 3, e.g.

\beginexample
gap> SetInfoACELevel(3);
gap> SetInfoLevel(InfoACE, 3);
\endexample

This causes each line of {\ACE} output to be prepended with
Expand Down
22 changes: 11 additions & 11 deletions doc/moreexamples.tex
Original file line number Diff line number Diff line change
Expand Up @@ -65,10 +65,10 @@
(see~"option echo") option if you want that. Also, by default, the
{\ACE} binary only prints a *results message*, but we won't see that
unless we set `InfoACE' to a level of at least 2
(see~"SetInfoACELevel"):
(see~"InfoACE"):

\beginexample
gap> SetInfoACELevel(2);
gap> SetInfoLevel(InfoACE, 2);

\endexample

Expand Down Expand Up @@ -96,7 +96,7 @@
To dump out the presentation and parameters associated with an
enumeration, {\ACE} provides the `sr' (see~"option sr") option.
However, you won't see output of this command, unless you set the
`InfoACELevel' to at least 3. Also, to ensure the reliability of the
`InfoACE' level to at least 3. Also, to ensure the reliability of the
output of the `sr' option, an enumeration should *precede* it; for
`ACEStats' (and `ACECosetTableFromGensAndRels') the directive `start'
(see~"option start") required to initiate an enumeration is inserted
Expand All @@ -110,7 +110,7 @@
presentation and parameters:

\beginexample
gap> SetInfoACELevel(3);
gap> SetInfoLevel(InfoACE, 3);
gap> ACEStats(fgens, [], [] : start, sr := 1);
#I ACE 3.001 Wed Oct 31 09:36:39 2001
#I =========================================
Expand Down Expand Up @@ -538,7 +538,7 @@
`print' (see "option print") directive. If you wish to see all the
options that are directed to {\ACE}, set the `InfoACE' level to 4
(then all such commands are `Info'-ed behind a ```ToACE> ''' prompt;
see~"SetInfoACELevel").
see~"InfoACE").

Following the standalone manual, we now set things up to do the
alternating group $A_5$, of order $60$. (We saw the group $A_5$ with
Expand All @@ -562,7 +562,7 @@
`F.1' (and `b' to be `F.2').

\beginexample
gap> SetInfoACELevel(4);
gap> SetInfoLevel(InfoACE, 4);
gap> a := F.1;; b := F.2;;
gap> # Enumerating A_5 = < a, b || a^2, b^3, (a*b)^5 >
gap> # over Id (trivial subgp)
Expand Down Expand Up @@ -705,10 +705,10 @@
save anything by doing this, since afterwards the variables `fgens',
`a', `b' and `F' would no longer be associated with `ACEStart' process
1. Instead, we will use the more convenient 4-argument form, and also
switch the `InfoACELevel' back to 3:
switch the `InfoACE' level back to 3:

\beginexample
gap> SetInfoACELevel(3);
gap> SetInfoLevel(InfoACE, 3);
gap> ACEStart(1, ACEGroupGenerators(1), ACERelators(1), [ a*b ]
> : messages := 1);
#I ***
Expand Down Expand Up @@ -866,11 +866,11 @@
as an involution, allowing `a' and `A' (the inverse of `a') to take up
the first two columns of the coset table, effectively stopping {\ACE}
from reordering the generators. To see what is passed to {\ACE}, at
the enumeration stage, we set the `InfoACELevel' to 4, but since we
the enumeration stage, we set the `InfoACE' level to 4, but since we
don't really want to see messages this time we set `messages := 0'.

\beginexample
gap> SetInfoACELevel(4);
gap> SetInfoLevel(InfoACE, 4);
gap> ACEStart(1, ACEGroupGenerators(1), ACERelators(1), [ a*b ]
> : messages := 0, lenlex);
#I ToACE> group:ab;
Expand Down Expand Up @@ -962,7 +962,7 @@
strategy.

\beginexample
gap> SetInfoACELevel(1); # No behind-the-scenes info. please
gap> SetInfoLevel(InfoACE, 1); # No behind-the-scenes info. please
gap> F := FreeGroup("r", "s", "t");; r := F.1;; s := F.2;; t := F.3;;
gap> ACEStats([r, s, t], [(r^t*r^-2)^-1, (s^r*s^-2)^-1, (t^s*t^-2)^-1], []
> : sims := 3);
Expand Down
4 changes: 2 additions & 2 deletions doc/options.tex
Original file line number Diff line number Diff line change
Expand Up @@ -341,7 +341,7 @@
are stored in files whose full path names are recorded in the record
fields `ACEData.infile' and `ACEData.outfile', respectively.
Alternatively, both interactively and non-interactively one can set
the `InfoLevel' of `InfoACE' to 3 (see~"SetInfoACELevel"), to see the
the `InfoLevel' of `InfoACE' to 3 (see~"InfoACE"), to see the
output from {\ACE}, or to 4 to also see the commands directed to
{\ACE}.

Expand Down Expand Up @@ -1271,7 +1271,7 @@
`InfoLevel' of `InfoACE' to 3 via

\beginexample
gap> SetInfoACELevel(3);
gap> SetInfoLevel(InfoACE, 3);

\endexample

Expand Down
6 changes: 3 additions & 3 deletions examples/index
Original file line number Diff line number Diff line change
Expand Up @@ -41,9 +41,9 @@ Notes
4. Try the *-ed examples to explore how to modify options when an
enumeration fails (just follow the instructions you get within the
break-loop, or see Notes 2. and 3.).
5. Try `SetInfoACELevel(3);' before calling ACEExample, to see the
5. Try `SetInfoLevel(InfoACE, 3);' before calling ACEExample, to see the
effect of setting the "mess" (= "messages") option.
6. To suppress a long output, use a double semicolon (`;;') after the
ACEExample command. (However, this does not suppress Info-ed output.)
7. Also, try `SetInfoACELevel(2);' or `SetInfoACELevel(4);' before
calling ACEExample.
7. Also, try `SetInfoLevel(InfoACE, 2);' or `SetInfoLevel(InfoACE, 4);'
before calling ACEExample.
4 changes: 2 additions & 2 deletions gap/streams.gi
Original file line number Diff line number Diff line change
Expand Up @@ -47,9 +47,9 @@ end);
## <readline>, <IsMyLine>) . . . . . . flush a stream until a desired line
##
## reads lines in iostream <iostream> via function <readline> and `Info's
## those lines at `InfoACELevel' <infoLevelFlushed> until a line <line> for
## those lines at `InfoACE' level <infoLevelFlushed> until a line <line> for
## which `<IsMyLine>(<line>) is `true'. The line <line> is then `Info'-ed at
## `InfoACELevel' <infoLevelMyLine> and returned.
## `InfoACE' level <infoLevelMyLine> and returned.
##
InstallGlobalFunction(FLUSH_ACE_STREAM_UNTIL,
function(iostream, infoLevelFlushed, infoLevelMyLine, readline, IsMyLine)
Expand Down
6 changes: 3 additions & 3 deletions tst/aceds.tst
Original file line number Diff line number Diff line change
Expand Up @@ -28,9 +28,9 @@ rec( activecosets := 80, cputimeUnits := "10^-2 seconds", index := 80,
maxcosets := 123, totcosets := 187 )
gap> ACEDeleteSubgroupGenerators( i, [ t ] );
[ b ]
gap> lev := InfoACELevel();
gap> lev := InfoLevel(InfoACE);
1
gap> SetInfoACELevel(3);
gap> SetInfoLevel(InfoACE, 3);
gap> ACEDeleteSubgroupGenerators( i, [ 2 ] );
#I ** ERROR (continuing with next line)
#I first argument out of range
Expand All @@ -47,6 +47,6 @@ gap> ACEDeleteSubgroupGenerators( i, [ 2 ] );
#I Subgroup Generators: b;
#I #---------------------------------
[ b ]
gap> SetInfoACELevel(lev);
gap> SetInfoLevel(InfoACE, lev);
gap> ACEQuit(i);
gap> STOP_TEST( "aceds.tst", 1000000 );

0 comments on commit fe16771

Please sign in to comment.