Extend coverage of documentation to lib/structure.g[di]

This commit is contained in:
Glen Whitney 2018-09-01 23:51:58 -04:00
parent 82c69a16a9
commit e9e38ec41c
6 changed files with 210 additions and 39 deletions

View File

@ -35,7 +35,8 @@ Perhaps the following ⪆ interactive session, which constructs the
conjugation quandle of the symmetric group on three elements and then performs conjugation quandle of the symmetric group on three elements and then performs
a few simple computations on that quandle, will give the flavor of &RAQ;. (It is a few simple computations on that quandle, will give the flavor of &RAQ;. (It is
presumed that the &RAQ; package has already been loaded with presumed that the &RAQ; package has already been loaded with
`LoadPackage("RAQ");` prior to these example commands being executed.) `LoadPackage("RAQ");` prior to these example commands being executed, and that
remains true throughout the package documentation.)
<!--@BeginExampleSession ``` --> <!--@BeginExampleSession ``` -->
``` ```
gap> S3 := SymmetricGroup(3); gap> S3 := SymmetricGroup(3);

View File

@ -1,11 +1,29 @@
@Chapter construct @Chapter construct
@ChapterTitle Constructing One-Sided Quasigroups, Racks, and Quandles. @ChapterTitle Constructing One-Sided Quasigroups, Racks, and Quandles.
@Section from_scratch
@SectionTitle Direct constructors
All of the functions in this section produce magmas (of one of the
categories with which &RAQ; is concerned) from data of other (non-domain)
types.
@Chapter operate @Chapter operate
@ChapterTitle Operations on One-Sided Quasigroups, Racks, and Quandles. @ChapterTitle Operations on One-Sided Quasigroups, Racks, and Quandles.
@Chapter basic @Chapter basic
@ChapterTitle Basic Notions @ChapterTitle Basic Notions
In order to build up and define one-sided quasigroups, racks, and
quandles, &RAQ; must define several lower-level objects and properties,
which are documented in this section. Although logically they come before
the domain constructors and operations, they are presented afterwards
because it's rare that one needs to use them directly when working with
&RAQ;.
@Section elements
@SectionTitle Categories of elements
@Section collections
@SectionTitle Categories of collections
@Chapter technical @Chapter technical
This chapter covers computational/operational aspects of &RAQ;
rather than mathematical ones.
@ChapterTitle Technical Details @ChapterTitle Technical Details

View File

@ -6,4 +6,8 @@ AutoDoc(rec(
autodoc := rec(files := ["README.md", "doc/chapters.autodoc"]), autodoc := rec(files := ["README.md", "doc/chapters.autodoc"]),
maketest := rec(name := "tst/AutoDoc_tests.g") maketest := rec(name := "tst/AutoDoc_tests.g")
)); ));
QUIT;
if not IsBound(RAQ_makedoc_no_quit) or
not RAQ_makedoc_no_quit then
QUIT_GAP();
fi;

View File

@ -1,43 +1,192 @@
## bytable.gd RAQ Quasigroups, racks, and quandles by multiplication tables. ## bytable.gd RAQ Quasigroups, racks, and quandles by multiplication tables.
## Self-distributivity #! @Chapter basic
# Predicates on tables: #! @Section table_predicates
#! @SectionTitle Predicates on multiplication tables
#! @Arguments matrix
#! @Description This property is true if <A>matrix</A> is the multiplication
#! table of a magma which satisfies the left self-distributive property (see
#! <Ref Filt="IsLSelfDistElement" Label="for IsMultiplicativeElement"/>))
#! for all triples of elements.
DeclareProperty( "IsLeftSelfDistributiveTable", IsMatrix ); DeclareProperty( "IsLeftSelfDistributiveTable", IsMatrix );
#! @Arguments matrix
#! @Description This property is true if <A>matrix</A> is the multiplication
#! table of a magma which satisfies the rightt self-distributive property (see
#! <Ref Filt="IsLSelfDistElement" Label="for IsMultiplicativeElement"/>))
#! for all triples of elements.
DeclareProperty( "IsRightSelfDistributiveTable", IsMatrix ); DeclareProperty( "IsRightSelfDistributiveTable", IsMatrix );
#! @Arguments matrix
#! @Description This property is true if for all $i$ less than or equal to the
#! number of rows of <A>matrix</A>, the $(i,i)$ entry of <A>matrix</A> is
#! $i$.
DeclareProperty( "IsElementwiseIdempotentTable", IsMatrix ); DeclareProperty( "IsElementwiseIdempotentTable", IsMatrix );
## Attributes (typically used on the families of elements created from a #! @Chapter operate
## multiplication table) to store sections and division tables #! @Section table
#! @Section Information related to the multiplication table.
#! Note that typically the functions in this section will fail unless the
#! argument was either created with a multiplication table, or at least has
#! had its multiplication table explicitly computed.
#! @Arguments obj
#! @Returns a list of permutations of length equal to `Size(obj)`, or fail
#! @Description The $i$th element of the list returned is the permutation
#! determined by the $i$th row of the multiplication table of
#! <A>obj</A> (in the sense of the core &GAP;
#! function `PermList`). Returns fail if any row of the multiplication table
#! does not determine a permuation.
DeclareAttribute("LeftPerms", HasMultiplicationTable); DeclareAttribute("LeftPerms", HasMultiplicationTable);
DeclareAttribute("RightPerms", HasMultiplicationTable); #! @BeginExampleSession
DeclareAttribute("LeftDivisionTable", HasMultiplicationTable); #! gap> D3 := LeftQuandleByMultiplicationTable([[1,3,2],[3,2,1],[2,1,3]]);
DeclareAttribute("RightDivisionTable", HasMultiplicationTable); #! <left quandle with 3 generators>
#! gap> LeftPerms(D3);
#! [ (2,3), (1,3), (1,2) ]
#! @EndExampleSession
## Create Quasigroups and racks from multiplication tables #! @Arguments obj
#! @Returns a list of permutations of length equal to `Size(obj)`, or fail
#! @Description The $i$th element of the list returned is the permutation
#! determined by the $i$th column of the multiplication table of
#! <A>obj</A> (in the sense of the core &GAP;
#! function `PermList`). Returns fail if any column of the multiplication table
#! does not determine a permuation.
DeclareAttribute("RightPerms", HasMultiplicationTable);
#! @Arguments obj
#! @Returns an operation table matrix, or fail
#! @Description Presuming it is well-defined, this produces the operation
#! table (following similar conventions for multiplication tables, e.g.,
#! every entry is a natural number less than `Size(obj)`) for `LeftQuotient`
#! on the given <A>obj</A>. Returns fail if `LeftQuotient` is not
#! well-defined for <A>obj</A>.
DeclareAttribute("LeftDivisionTable", HasMultiplicationTable);
#! @Arguments obj
#! @Returns an operation table matrix, or fail
#! @Description Presuming it is well-defined, this produces the operation
#! table for `\/` (the typical elementwise (right) quotient) on the given
#! <A>obj</A>. Returns fail if `\/` is not
#! well-defined for <A>obj</A>.
DeclareAttribute("RightDivisionTable", HasMultiplicationTable);
#! @BeginExampleSession
#! gap> A4 := RightQuandleByMultiplicationTable([[1,4,2,3],
#! > [3,2,4,1],
#! > [4,1,3,2],
#! > [2,3,1,4]]);
#! <right quandle with 4 generators>
#! gap> RightDivisionTable(A4);
#! [ [ 1, 3, 4, 2 ], [ 4, 2, 1, 3 ], [ 2, 4, 3, 1 ], [ 3, 1, 2, 4 ] ]
#! @EndExampleSession
#! @Chapter construct
#! @Section from_scratch
#! @BeginGroup table_constructors
#! @GroupTitle Constructors from tables
#! @Returns a magma of the designated category
#! @Description These functions produce magmas from their multiplication
#! tables, exactly analogously with the core &GAP; function
#! `MagmaByMultiplicationTable` (q.v.); all of the same conventions are
#! followed, such as the table should be an $n\times n$ matrix in which
#! every entry is a natural number less than or equal to $n$. These
#! functions verify that the tables supplied in fact define an example of
#! the designated category.
#! @GroupInitialArguments table
DeclareGlobalFunction("LeftQuasigroupByMultiplicationTable"); DeclareGlobalFunction("LeftQuasigroupByMultiplicationTable");
DeclareGlobalFunction("LeftQuasigroupByMultiplicationTableNC");
DeclareGlobalFunction("LeftRackByMultiplicationTable"); DeclareGlobalFunction("LeftRackByMultiplicationTable");
DeclareGlobalFunction("LeftRackByMultiplicationTableNC");
DeclareGlobalFunction("LeftQuandleByMultiplicationTable"); DeclareGlobalFunction("LeftQuandleByMultiplicationTable");
DeclareGlobalFunction("LeftQuandleByMultiplicationTableNC");
DeclareGlobalFunction("RightQuasigroupByMultiplicationTable"); DeclareGlobalFunction("RightQuasigroupByMultiplicationTable");
DeclareGlobalFunction("RightQuasigroupByMultiplicationTableNC");
DeclareGlobalFunction("RightRackByMultiplicationTable"); DeclareGlobalFunction("RightRackByMultiplicationTable");
DeclareGlobalFunction("RightRackByMultiplicationTableNC");
DeclareGlobalFunction("RightQuandleByMultiplicationTable"); DeclareGlobalFunction("RightQuandleByMultiplicationTable");
#! @EndGroup
#! @BeginExampleSession
#! gap> D3 := LeftQuandleByMultiplicationTable([[1,3,2],[3,2,1],[2,1,3]]);
#! <left quandle with 3 generators>
#! gap> SpecifyElmNamePrefix(D3, "d");
#! gap> Elements(D3);
#! [ d1, d2, d3 ]
#! gap> IsBound(d1);
#! false
#! gap> BindElmNames(D3);
#! gap> d1 * d2;
#! d3
#! @EndExampleSession
#! @BeginGroup unchecked_table_constructors
#! @GroupTitle Unchecked constructors from tables
#! @Returns a magma of the designated category
#! @Description Each of these functions is exactly like its counterpart
#! without the `NC` suffix, except that it does not perform any verification
#! that the supplied table in fact satisfies the necessary axioms for the
#! designated category. (The verification is skipped to save computation
#! time, for use in cases when the properties are known to hold.) Hence, use
#! with caution: the behavior of this
#! package if you supply a table which does not satisfy the appropiate
#! axioms is undefined.
#! @GroupInitialArguments table
DeclareGlobalFunction("LeftQuasigroupByMultiplicationTableNC");
DeclareGlobalFunction("LeftRackByMultiplicationTableNC");
DeclareGlobalFunction("LeftQuandleByMultiplicationTableNC");
DeclareGlobalFunction("RightQuasigroupByMultiplicationTableNC");
DeclareGlobalFunction("RightRackByMultiplicationTableNC");
DeclareGlobalFunction("RightQuandleByMultiplicationTableNC"); DeclareGlobalFunction("RightQuandleByMultiplicationTableNC");
#! @EndGroup
## Property of a collection that its elements know their multiplication table ## Property of a collection that its elements know their multiplication table
#! @Chapter technical
#! @Section reps
#! @SectionTitle Representational issues
#! @Arguments collection
#! @Description True if the family of the elements in the collection possesses
#! a global multiplication table. This value is used to control whether more
#! efficient algorithms are used in particular cases.
DeclareProperty("IsBuiltFromMultiplicationTable", IsCollection); DeclareProperty("IsBuiltFromMultiplicationTable", IsCollection);
## Create quasigroups etc by permutations ## Create quasigroups etc by permutations
#! @Chapter construct
#! @Section from_scratch
#! @BeginGroup perms_constructors
#! @GroupTitle Constructors from permutations
#! @Returns a magma of the designated category
#! @Description These functions produce magmas from a sequence of
#! permutations. That is to say, because all of the categories supported in
#! &RAQ; are quasigroups on at least one side, either the left
#! multiplicative action of an element on the magma is always a permutation
#! (in the case of left quasigroups) or the right multiplicative action of
#! an element on the magma is always a permutation. Hence, a magma in these
#! categories can always be specified by a list of $n$ permutations on
#! the natural numbers less than or equal to $n$ (i.e., ordinary &GAP;
#! permutations) and that's what these
#! functions do. In effect, the argument to the `Left` functions gives the
#! rows of the multiplication table (as permutation objects), and the to the
#! `Right` functions gives the columns.
#! @GroupInitialArguments permutation-list
DeclareGlobalFunction("LeftQuasigroupByPerms"); DeclareGlobalFunction("LeftQuasigroupByPerms");
DeclareGlobalFunction("LeftRackByPerms"); DeclareGlobalFunction("LeftRackByPerms");
DeclareGlobalFunction("LeftRackByPermsNC");
DeclareGlobalFunction("LeftQuandleByPerms"); DeclareGlobalFunction("LeftQuandleByPerms");
DeclareGlobalFunction("LeftQuandleByPermsNC");
DeclareGlobalFunction("RightQuasigroupByPerms"); DeclareGlobalFunction("RightQuasigroupByPerms");
DeclareGlobalFunction("RightRackByPerms"); DeclareGlobalFunction("RightRackByPerms");
DeclareGlobalFunction("RightRackByPermsNC");
DeclareGlobalFunction("RightQuandleByPerms"); DeclareGlobalFunction("RightQuandleByPerms");
#! @EndGroup
#! @BeginExampleSession
#! gap> D3 := LeftQuandleByPerms( [ (2,3), (1,3), (1,2) ] );
#! <left quandle with 3 generators>
#! gap> SpecifyElmNamePrefix(D3, "p");
#! gap> BindElmNames(D3);
#! gap> p2*p3;
#! p1
#! @EndExampleSession
#! @BeginGroup unchecked_perms_constructors
#! @GroupTitle Unchecked constructors from permutations
#! @Returns a magma of the designated category
#! @Description These functions are exactly the same as their counterparts
#! without `NC` except that to save time they do not verify that the given
#! permutations satisfy the appropriate axioms. Hence use caution, as
#! supplying a list of permutations which does not form the proper structure
#! can lead to undefined behavior. Note that there are no unchecked versions
#! for the bare quasigroup constructors because the only properties required
#! are that all of the rows (or columns, in the `Right` case) are permutations.
#! @GroupInitialArguments permutation-list
DeclareGlobalFunction("LeftRackByPermsNC");
DeclareGlobalFunction("LeftQuandleByPermsNC");
DeclareGlobalFunction("RightRackByPermsNC");
DeclareGlobalFunction("RightQuandleByPermsNC"); DeclareGlobalFunction("RightQuandleByPermsNC");
#! @EndGroup

View File

@ -3,8 +3,6 @@
## GAP Categories and representations ## GAP Categories and representations
#! @Chapter technical #! @Chapter technical
#! This chapter covers computational/operational aspects of &RAQ;
#! rather than mathematical ones.
#! @Section Messages #! @Section Messages
#! @Description Controls the level of verbosity of &RAQ;'s informative #! @Description Controls the level of verbosity of &RAQ;'s informative
#! messages. Use `SetInfoLevel` to set it to 0 to quiet &RAQ; #! messages. Use `SetInfoLevel` to set it to 0 to quiet &RAQ;
@ -22,14 +20,7 @@ DeclareInfoClass("InfoRAQ");
# new, non-conflicting terms. # new, non-conflicting terms.
#! @Chapter basic #! @Chapter basic
#! In order to build up and define one-sided quasigroups, racks, and
#! quandles, &RAQ; must define several lower-level objects and properties,
#! which are documented in this section. Although logically they come before
#! the domain constructors and operations, they are presented afterwards
#! because it's rare that one needs to use them directly when working with
#! &RAQ;.
#! @Section elements #! @Section elements
#! @SectionTitle Categories of elements
#! @Description An element <C>x</C> with the property #! @Description An element <C>x</C> with the property
#! that for all elements <C>y</C> and <C>z</C> in its family, <C>x*(y*z) = #! that for all elements <C>y</C> and <C>z</C> in its family, <C>x*(y*z) =
#! (x*y)*(x*z)</C>. #! (x*y)*(x*z)</C>.
@ -46,7 +37,6 @@ DeclareCategory("IsRSelfDistElement", IsMultiplicativeElement);
DeclareCategoryCollections("IsRSelfDistElement"); DeclareCategoryCollections("IsRSelfDistElement");
#! @Section collections #! @Section collections
#! @SectionTitle Categories of collections
#! @Description A collection which satisfies the left self-distributive #! @Description A collection which satisfies the left self-distributive
#! property (see the description of #! property (see the description of
#! <Ref Filt="IsLSelfDistElement" Label="for IsMultiplicativeElement"/>) #! <Ref Filt="IsLSelfDistElement" Label="for IsMultiplicativeElement"/>)
@ -80,11 +70,13 @@ InstallTrueMethod(IsElementwiseIdempotent, IsIdempotentCollection);
#! (i.e., <C>IsLSelfDistributive(obj)</C> is true). #! (i.e., <C>IsLSelfDistributive(obj)</C> is true).
#! @Arguments obj #! @Arguments obj
#! @ItemType Filt #! @ItemType Filt
#! @Returns true or false
DeclareSynonym("IsLeftRack", IsLeftQuasigroup and IsLSelfDistributive); DeclareSynonym("IsLeftRack", IsLeftQuasigroup and IsLSelfDistributive);
#! @Description Tests whether <A>obj</A> is a right rack, by definition #! @Description Tests whether <A>obj</A> is a right rack, by definition
#! precisely that it is a right quasigroup and right self-distributive. #! precisely that it is a right quasigroup and right self-distributive.
#! @Arguments obj #! @Arguments obj
#! @ItemType Filt #! @ItemType Filt
#! @Returns true or false
DeclareSynonym("IsRightRack", IsRightQuasigroup and IsRSelfDistributive); DeclareSynonym("IsRightRack", IsRightQuasigroup and IsRSelfDistributive);
#! @Description Tests whether <A>obj</A> is a left quandle, which by definition #! @Description Tests whether <A>obj</A> is a left quandle, which by definition
@ -93,20 +85,18 @@ DeclareSynonym("IsRightRack", IsRightQuasigroup and IsRSelfDistributive);
#! (i.e., <C>IsElementwiseIdempotent(obj)</C> is true). #! (i.e., <C>IsElementwiseIdempotent(obj)</C> is true).
#! @Arguments obj #! @Arguments obj
#! @ItemType Filt #! @ItemType Filt
#! @Returns true or false
DeclareSynonym("IsLeftQuandle", IsLeftRack and IsElementwiseIdempotent); DeclareSynonym("IsLeftQuandle", IsLeftRack and IsElementwiseIdempotent);
#! @Description Tests whether <A>obj</A> is a right quandle, by definition #! @Description Tests whether <A>obj</A> is a right quandle, by definition
#! precisely that it is a right rack and every element is idempotent. #! precisely that it is a right rack and every element is idempotent.
#! @Arguments obj #! @Arguments obj
#! @ItemType Filt #! @ItemType Filt
#! @Returns true or false
DeclareSynonym("IsRightQuandle", IsRightRack and IsElementwiseIdempotent); DeclareSynonym("IsRightQuandle", IsRightRack and IsElementwiseIdempotent);
#! @Chapter construct #! @Chapter construct
#! @Section from_scratch #! @Section from_scratch
#! @SectionTitle Direct constructors
#! All of the functions in this section produce magmas (of one of the
#! categories with which &RAQ; is concerned) from data of other (non-domain)
#! types.
#! @BeginAutoDoc #! @BeginAutoDoc
#! @BeginGroup basic_constructors #! @BeginGroup basic_constructors
#! @GroupTitle Basic constructors (from generators) #! @GroupTitle Basic constructors (from generators)
@ -123,13 +113,13 @@ DeclareSynonym("IsRightQuandle", IsRightRack and IsElementwiseIdempotent);
#! quotients on the specified side must exist; racks must also satisfy the #! quotients on the specified side must exist; racks must also satisfy the
#! appropriate self-distributive law; and quandles must also have every #! appropriate self-distributive law; and quandles must also have every
#! element idempotent. #! element idempotent.
#! @Returns a magma of the named category #! @Returns a magma of the designated category
#! @GroupInitialArguments [family], [generators] #! @GroupInitialArguments [family], [generators]
DeclareGlobalFunction("LeftQuasigroup"); DeclareGlobalFunction("LeftQuasigroup");
DeclareGlobalFunction("RightQuasigroup");
DeclareGlobalFunction("LeftRack"); DeclareGlobalFunction("LeftRack");
DeclareGlobalFunction("RightRack");
DeclareGlobalFunction("LeftQuandle"); DeclareGlobalFunction("LeftQuandle");
DeclareGlobalFunction("RightQuasigroup");
DeclareGlobalFunction("RightRack");
DeclareGlobalFunction("RightQuandle"); DeclareGlobalFunction("RightQuandle");
#! @EndGroup #! @EndGroup
#! @BeginGroup unchecked_basic_constructors #! @BeginGroup unchecked_basic_constructors
@ -144,10 +134,10 @@ DeclareGlobalFunction("RightQuandle");
#! @Returns a magma of the named category #! @Returns a magma of the named category
#! @GroupInitialArguments family, generators #! @GroupInitialArguments family, generators
DeclareGlobalFunction("LeftQuasigroupNC"); DeclareGlobalFunction("LeftQuasigroupNC");
DeclareGlobalFunction("RightQuasigroupNC");
DeclareGlobalFunction("LeftRackNC"); DeclareGlobalFunction("LeftRackNC");
DeclareGlobalFunction("RightRackNC");
DeclareGlobalFunction("LeftQuandleNC"); DeclareGlobalFunction("LeftQuandleNC");
DeclareGlobalFunction("RightQuasigroupNC");
DeclareGlobalFunction("RightRackNC");
DeclareGlobalFunction("RightQuandleNC"); DeclareGlobalFunction("RightQuandleNC");
#! @EndGroup #! @EndGroup
#! @EndAutoDoc #! @EndAutoDoc

View File

@ -9,6 +9,15 @@ TestDirectory(tst_path,
testOptions := rec(compareFunction := "uptowhitespace")) testOptions := rec(compareFunction := "uptowhitespace"))
); );
# Now make sure the manual tests are up to date
doc_path := DirectoriesPackageLibrary("RAQ", "doc");
makedoc_file := Filename(doc_path, "makedoc.g");
RAQ_makedoc_no_quit := true;
Info(InfoRAQ, 1, "Generating RAQ documentation..\n\n");
Read(makedoc_file);
auto_file := Filename(tst_path, "AutoDoc_tests.g"); auto_file := Filename(tst_path, "AutoDoc_tests.g");
if auto_file <> fail then if auto_file <> fail then