Make first pass at full doc coverage for structure.g[di]

To do this, the structure of the manual needed to be elaborated, which was
accomplished with a skeleton file, doc/chapters.autodoc, which is explicitly
loaded first.

Note that this portion of the manual may still need polishing; in particular,
perhaps it could use more examples, which would then double as tests in
tst/testall.g
This commit is contained in:
Glen Whitney 2018-09-01 11:12:31 -04:00
parent 0cef163077
commit 82c69a16a9
6 changed files with 196 additions and 35 deletions

View File

@ -2,7 +2,7 @@ SetPackageInfo( rec(
PackageName := "RAQ", PackageName := "RAQ",
Subtitle := "Racks And Quandles in GAP", Subtitle := "Racks And Quandles in GAP",
Version := "0.1.0", Version := "0.1.0",
Date := "2018-Oct-1", Date := "2018/10/01",
PackageWWWPrefix := Concatenation("http://code.studioinfinity.org/", PackageWWWPrefix := Concatenation("http://code.studioinfinity.org/",
~.PackageName), ~.PackageName),
PackageWWWHome := Concatenation(~.PackageWWWPrefix, "/wiki"), PackageWWWHome := Concatenation(~.PackageWWWPrefix, "/wiki"),
@ -49,7 +49,7 @@ SetPackageInfo( rec(
"quasigroups, but more more particularly with racks and quandles. ", "quasigroups, but more more particularly with racks and quandles. ",
"This package builds on fundamentals of non-associative algebra ", "This package builds on fundamentals of non-associative algebra ",
"established in the <span class=\"pkgname\">LOOPS</span> package, and ", "established in the <span class=\"pkgname\">LOOPS</span> package, and ",
"and provides enhanced functionality, libraries, and implementations ", "provides enhanced functionality, libraries, and implementations ",
"as compared to the earlier <span class=\"pkgname\">RIG</span> package ", "as compared to the earlier <span class=\"pkgname\">RIG</span> package ",
"on which <span class=\"pkgname\">RAQ</span> is generally modeled." "on which <span class=\"pkgname\">RAQ</span> is generally modeled."
), ),

View File

@ -8,7 +8,10 @@
#! @Chapter Introduction #! @Chapter Introduction
#! @AutoDocPlainText --> #! @AutoDocPlainText -->
The &RAQ; package provides a variety of facilities for constructing and The &RAQ; package provides a variety of facilities for constructing and
computing with one-sided quasigroups, racks, and quandles in &GAP;. computing with one-sided quasigroups, racks, and quandles in &GAP;. Highlights
include:
* Constructing quandles from operation tables, groups, or other quandles.
* And more to come..
<!--@Section Installation <!--@Section Installation
@AutoDocPlainText --> @AutoDocPlainText -->
@ -53,4 +56,12 @@ Note in particular that &RAQ; generally, unless otherwise specifically
requested, produces __left__ quandles and racks. (That is to say, quandles in requested, produces __left__ quandles and racks. (That is to say, quandles in
which for any fixed element $l$, the "left-multiplication by $l$" operation which for any fixed element $l$, the "left-multiplication by $l$" operation
$x\mapsto l*x$ is a permutation of the quandle.) $x\mapsto l*x$ is a permutation of the quandle.)
<!--@Copyright
@AutoDocPlainText -->
&copyright; 2018 by Glen Whitney.
This package may be distributed under the terms and conditions of the GNU
Public License version 3. See the <C>LICENSE</C> file in the package directory
for details.
<!--@EndAutoDocPlainText --> <!--@EndAutoDocPlainText -->

11
doc/chapters.autodoc Normal file
View File

@ -0,0 +1,11 @@
@Chapter construct
@ChapterTitle Constructing One-Sided Quasigroups, Racks, and Quandles.
@Chapter operate
@ChapterTitle Operations on One-Sided Quasigroups, Racks, and Quandles.
@Chapter basic
@ChapterTitle Basic Notions
@Chapter technical
@ChapterTitle Technical Details

View File

@ -3,7 +3,7 @@
LoadPackage("AutoDoc"); LoadPackage("AutoDoc");
AutoDoc(rec( AutoDoc(rec(
autodoc := rec(files := ["README.md"]), autodoc := rec(files := ["README.md", "doc/chapters.autodoc"]),
maketest := rec(name := "tst/AutoDoc_tests.g") maketest := rec(name := "tst/AutoDoc_tests.g")
)); ));
QUIT; QUIT;

View File

@ -2,7 +2,14 @@
## GAP Categories and representations ## GAP Categories and representations
## Info class for RAQ #! @Chapter technical
#! This chapter covers computational/operational aspects of &RAQ;
#! rather than mathematical ones.
#! @Section Messages
#! @Description Controls the level of verbosity of &RAQ;'s informative
#! messages. Use `SetInfoLevel` to set it to 0 to quiet &RAQ;
#! entirely, or to values greater than 1 to yield more details of &RAQ;'s
#! internal algorithms.
DeclareInfoClass("InfoRAQ"); DeclareInfoClass("InfoRAQ");
## Self-distributivity ## Self-distributivity
@ -14,63 +21,146 @@ DeclareInfoClass("InfoRAQ");
# (cf. https://arxiv.org/abs/0910.4760). Hence, we implement them in RAQ with # (cf. https://arxiv.org/abs/0910.4760). Hence, we implement them in RAQ with
# new, non-conflicting terms. # new, non-conflicting terms.
# An element that knows that multiplication in its family is left #! @Chapter basic
# self-distributive: #! 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
#! @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) =
#! (x*y)*(x*z)</C>.
DeclareCategory("IsLSelfDistElement", IsMultiplicativeElement); DeclareCategory("IsLSelfDistElement", IsMultiplicativeElement);
# Have to skip a line because of AutoDoc's convention on documenting
# consecutive declarations.
DeclareCategoryCollections("IsLSelfDistElement"); DeclareCategoryCollections("IsLSelfDistElement");
# An element that knows that multiplication in its family is right #! @Description An element <C>x</C> with the property
# self-distributive: #! that for all elements <C>y</C> and <C>z</C> in its family, <C>(y*z)*x =
#! (y*x)*(z*x)</C>.
DeclareCategory("IsRSelfDistElement", IsMultiplicativeElement); DeclareCategory("IsRSelfDistElement", IsMultiplicativeElement);
DeclareCategoryCollections("IsRSelfDistElement"); DeclareCategoryCollections("IsRSelfDistElement");
# Left self-distributive collections of elements: #! @Section collections
#! @SectionTitle Categories of collections
#! @Description A collection which satisfies the left self-distributive
#! property (see the description of
#! <Ref Filt="IsLSelfDistElement" Label="for IsMultiplicativeElement"/>)
#! for all triples of elements of the collection.
DeclareProperty("IsLSelfDistributive", IsMultiplicativeElementCollection); DeclareProperty("IsLSelfDistributive", IsMultiplicativeElementCollection);
InstallTrueMethod(IsLSelfDistributive, IsLSelfDistElementCollection); InstallTrueMethod(IsLSelfDistributive, IsLSelfDistElementCollection);
# Right self-distributive collections of elements: #! @Description A collection which satisfies the right self-distributive
#! property (see the description of
#! <Ref Filt="IsRSelfDistElement" Label="for IsMultiplicativeElement"/>)
#! for all triples of elements of the collection.
DeclareProperty("IsRSelfDistributive", IsMultiplicativeElementCollection); DeclareProperty("IsRSelfDistributive", IsMultiplicativeElementCollection);
InstallTrueMethod(IsRSelfDistributive, IsRSelfDistElementCollection); InstallTrueMethod(IsRSelfDistributive, IsRSelfDistElementCollection);
## Idempotence ## Idempotence
# There is already a property IsIdempotent on elements, but to definw # There is already a property IsIdempotent on elements, but to define
# structures which will automatically be quandles we need a corresponding # structures which will automatically be quandles we need a corresponding
# collections category: # collections category:
DeclareCategoryCollections("IsIdempotent"); DeclareCategoryCollections("IsIdempotent");
# Collections in which every element is idempotent # Collections in which every element is idempotent
#! @Description A collection in which every element <C>x</C> is
#! **idempotent**, i.e. satisfies <C>x*x=x</C>.
DeclareProperty("IsElementwiseIdempotent", IsMultiplicativeElementCollection); DeclareProperty("IsElementwiseIdempotent", IsMultiplicativeElementCollection);
InstallTrueMethod(IsElementwiseIdempotent, IsIdempotentCollection); InstallTrueMethod(IsElementwiseIdempotent, IsIdempotentCollection);
## Left and right racks and quandles #! @Description Tests whether <A>obj</A> is a left rack, which by definition
#! is precisely that <A>obj</A> is a left quasigroup (i.e.,
#! <C>IsLeftQuasigroup(obj)</C>, defined in the &LOOPS;
#! package, is true) and is left self-distributive
#! (i.e., <C>IsLSelfDistributive(obj)</C> is true).
#! @Arguments obj
#! @ItemType Filt
DeclareSynonym("IsLeftRack", IsLeftQuasigroup and IsLSelfDistributive); DeclareSynonym("IsLeftRack", IsLeftQuasigroup and IsLSelfDistributive);
#! @Description Tests whether <A>obj</A> is a right rack, by definition
#! precisely that it is a right quasigroup and right self-distributive.
#! @Arguments obj
#! @ItemType Filt
DeclareSynonym("IsRightRack", IsRightQuasigroup and IsRSelfDistributive); DeclareSynonym("IsRightRack", IsRightQuasigroup and IsRSelfDistributive);
#! @Description Tests whether <A>obj</A> is a left quandle, which by definition
#! is precisely that <A>obj</A> is a left rack (i.e.,
#! <C>IsLeftRack(obj)</C> is true) and every element is idempotent
#! (i.e., <C>IsElementwiseIdempotent(obj)</C> is true).
#! @Arguments obj
#! @ItemType Filt
DeclareSynonym("IsLeftQuandle", IsLeftRack and IsElementwiseIdempotent); DeclareSynonym("IsLeftQuandle", IsLeftRack and IsElementwiseIdempotent);
#! @Description Tests whether <A>obj</A> is a right quandle, by definition
#! precisely that it is a right rack and every element is idempotent.
#! @Arguments obj
#! @ItemType Filt
DeclareSynonym("IsRightQuandle", IsRightRack and IsElementwiseIdempotent); DeclareSynonym("IsRightQuandle", IsRightRack and IsElementwiseIdempotent);
## One-sided quasigroups and racks and quandles by generators #! @Chapter construct
#! @Section from_scratch
# Returns the closure of <gens> under * and LeftQuotient; #! @SectionTitle Direct constructors
# the family of elements of M may be specified, and must be if <gens> #! All of the functions in this section produce magmas (of one of the
# is empty (in which case M will be empty as well). #! categories with which &RAQ; is concerned) from data of other (non-domain)
#! types.
#! @BeginAutoDoc
#! @BeginGroup basic_constructors
#! @GroupTitle Basic constructors (from generators)
#! @Description These are the fundamental constructors of these
#! categories. They produce the closure of the specified <A>generators</A>,
#! which are considered to be of the given <A>family</A>, under both the
#! binary operation of the magma, which is always considered to be * in
#! &RAQ;, and the quotient on the specified side. (If
#! <A>family</A> is omitted, these functions attempt to infer it from the
#! <A>generators</A>; if there are no <A>generators</A> then the
#! <A>family</A> must be specified, and note that the resulting magma will
#! be empty.) The resulting magma must satisfy the defining
#! characteristics of the respective category: for the quasigroups, all
#! quotients on the specified side must exist; racks must also satisfy the
#! appropriate self-distributive law; and quandles must also have every
#! element idempotent.
#! @Returns a magma of the named category
#! @GroupInitialArguments [family], [generators]
DeclareGlobalFunction("LeftQuasigroup"); DeclareGlobalFunction("LeftQuasigroup");
DeclareGlobalFunction("LeftQuasigroupNC");
DeclareGlobalFunction("RightQuasigroup"); DeclareGlobalFunction("RightQuasigroup");
DeclareGlobalFunction("RightQuasigroupNC");
DeclareGlobalFunction("LeftRack"); DeclareGlobalFunction("LeftRack");
DeclareGlobalFunction("LeftRackNC");
DeclareGlobalFunction("RightRack"); DeclareGlobalFunction("RightRack");
DeclareGlobalFunction("RightRackNC");
DeclareGlobalFunction("LeftQuandle"); DeclareGlobalFunction("LeftQuandle");
DeclareGlobalFunction("LeftQuandleNC");
DeclareGlobalFunction("RightQuandle"); DeclareGlobalFunction("RightQuandle");
#! @EndGroup
#! @BeginGroup unchecked_basic_constructors
#! @GroupTitle Unchecked basic constructors
#! @Description Each function is the same as its checked counterpart, but the
#! <A>family</A> of elements must be specified and no checks that the
#! appropriate axioms are satisfied are performed. They may be used for
#! efficiency when those properties are guaranteed to be satisfied by the
#! <A>generators</A>. NOTE that the behavior of &RAQ; is undefined if the
#! unchecked versions are called on <A>generators</A> that do **not**
#! satisfy the proper axioms.
#! @Returns a magma of the named category
#! @GroupInitialArguments family, generators
DeclareGlobalFunction("LeftQuasigroupNC");
DeclareGlobalFunction("RightQuasigroupNC");
DeclareGlobalFunction("LeftRackNC");
DeclareGlobalFunction("RightRackNC");
DeclareGlobalFunction("LeftQuandleNC");
DeclareGlobalFunction("RightQuandleNC"); DeclareGlobalFunction("RightQuandleNC");
#! @EndGroup
#! @EndAutoDoc
# Underlying operation # Underlying operation
DeclareGlobalFunction("CloneOfTypeByGenerators"); DeclareGlobalFunction("CloneOfTypeByGenerators");
## Opposite structures ## Opposite structures
#! @Section from_quasigroups
#! @SectionTitle Constructors from other one-sided quasigroups
#! All of the functions in this section produce magmas from other objects of
#! similar domain categories.
DeclareCategory("IsOppositeObject", IsMultiplicativeElement); DeclareCategory("IsOppositeObject", IsMultiplicativeElement);
DeclareCategoryCollections("IsOppositeObject"); DeclareCategoryCollections("IsOppositeObject");
DeclareAttribute("OppositeFamily", IsFamily); DeclareAttribute("OppositeFamily", IsFamily);
@ -80,20 +170,44 @@ DeclareSynonym("IsDefaultOppositeObject",
DeclareAttribute("OppositeObj", IsMultiplicativeElement); DeclareAttribute("OppositeObj", IsMultiplicativeElement);
DeclareAttribute("UnderlyingMultiplicativeElement", IsOppositeObject); DeclareAttribute("UnderlyingMultiplicativeElement", IsOppositeObject);
#! @Chapter operate
#! @Section basic_info
#! @SectionTitle Basic information
# Attributes for the generators # Attributes for the generators
# Generates the structure by \* and LeftQuotient. Note that for finite #! @Arguments q
# structures, these are the same as the GeneratorsOfMagma but in general more #! @Returns list of elements generating <A>q</A>
# elements might be required to generate the structure just under * #! @Description This produces a list of elements that generate <A>q</A> by
#! `\*` and `LeftQuotient`. There are no guarantees that the list is minimal
#! in any respect. Note that for finite structures, the
#! `GeneratorsOfMagma(q)` will suffice, but in general more
#! elements might be required to generate the structure just under `\*`.
DeclareAttribute("GeneratorsOfLeftQuasigroup", IsLeftQuasigroup); DeclareAttribute("GeneratorsOfLeftQuasigroup", IsLeftQuasigroup);
# Generates the structure by \* and \/, same considerations as above #! @Arguments q
#! @Returns list of elements generating <A>q</A>
#! @Description This produces a list of elements that generate <A>q</A> by
#! `\*` and `\/`, with the same caveats as above.
DeclareAttribute("GeneratorsOfRightQuasigroup", IsRightQuasigroup); DeclareAttribute("GeneratorsOfRightQuasigroup", IsRightQuasigroup);
## Conversions into quasigroup/rack/quandle ## Conversions into quasigroup/rack/quandle
#! @Chapter construct
#! @Section from_scratch
#! @BeginAutoDoc
#! @BeginGroup conversions
#! @GroupTitle Conversions
#! @Description These functions convert a potentially arbitrary
#! <A>collection</A> of elements to one of the categories of objects with
#! which &RAQ; is concerned. The <A>collection</A> must be closed under *
#! and satisfy the appropriate axioms for the conversion to succeed.
#! @Returns a magma of the named category
#! @GroupInitialArguments collection
DeclareAttribute("AsLeftQuasigroup", IsCollection); DeclareAttribute("AsLeftQuasigroup", IsCollection);
DeclareAttribute("AsLeftRack", IsCollection); DeclareAttribute("AsLeftRack", IsCollection);
DeclareAttribute("AsLeftQuandle", IsCollection); DeclareAttribute("AsLeftQuandle", IsCollection);
DeclareAttribute("AsRightQuasigroup", IsCollection); DeclareAttribute("AsRightQuasigroup", IsCollection);
DeclareAttribute("AsRightRack", IsCollection); DeclareAttribute("AsRightRack", IsCollection);
DeclareAttribute("AsRightQuandle", IsCollection); DeclareAttribute("AsRightQuandle", IsCollection);
#! @EndGroup
#! @EndAutoDoc

View File

@ -489,7 +489,23 @@ OppHelper@ := function(Q, whichgens, cnstr)
return opp; return opp;
end; end;
#! @Chapter construct
#! @Section from_quasigroups
#! @Arguments magma
#! @ItemType Attr
#! @Label for various finitely-generated magmas
#! @Description Given `q`, one of the structures covered in &RAQ;,
#! `Opposite(q)` returns a structure which is just the same except the order
#! of the operation is exactly reversed: `a*b` in the new structure means
#! exactly what `b*a` did in the original structure. (This is the same
#! operation as transposing the Cayley table.) Actually, this operation is
#! originally defined in &LOOPS;, and it is extended in &RAQ; to one-sided
#! quasigroups, racks, and quandles. Moreover, since Opposite actually makes
#! sense for an arbitrary magma, &RAQ; makes an effort to extend it to as
#! wide a class of arguments as are easily implemented. Note for example
#! Opposite has no effect on a commutative magma, and &RAQ;
#! recognizes this fact.
#! @Returns a magma of the same category
InstallMethod(Opposite, "for a left quasigroup", InstallMethod(Opposite, "for a left quasigroup",
[IsLeftQuasigroup and HasGeneratorsOfLeftQuasigroup], [IsLeftQuasigroup and HasGeneratorsOfLeftQuasigroup],
Q -> OppHelper@(Q, GeneratorsOfLeftQuasigroup, RightQuasigroupNC) Q -> OppHelper@(Q, GeneratorsOfLeftQuasigroup, RightQuasigroupNC)
@ -549,6 +565,15 @@ RoughJoinOfFilters@ := function(list, first)
return jof; return jof;
end; end;
#! @ItemType Meth
#! @Arguments list-of-factors, distinguished-factor
#! @Returns a magma with only the structure common to all factors
#! @Description Extends the `DirectProduct` operation to allow factors that
#! are not even quasigroups, such as the one-sided quasigroups, racks, and
#! quandles with which &RAQ; is concerned. This direct product operation
#! makes its best effort to find the most structured category for the result
#! that it can, given that every factor in the product must lie in that
#! category.
InstallOtherMethod(DirectProductOp, "for a list and non-quasigroup magma", InstallOtherMethod(DirectProductOp, "for a list and non-quasigroup magma",
[IsList, IsMagma], [IsList, IsMagma],
function (list, first) function (list, first)
@ -669,18 +694,18 @@ end);
## Coversions among the structure types ## Coversions among the structure types
InstallMethod(AsLeftQuasigroup, "for a left quasigroup", InstallMethod(AsLeftQuasigroup, "for a left quasigroup",
[IsLeftQuasigroup], IdFunc); [IsLeftQuasigroup], IdFunc);
InstallMethod(AsLeftRack, "for a left rack", InstallMethod(AsLeftRack, "for a left rack",
[IsLeftRack], IdFunc); [IsLeftRack], IdFunc);
InstallMethod(AsLeftQuandle, "for a left quandle", InstallMethod(AsLeftQuandle, "for a left quandle",
[IsLeftQuandle], IdFunc); [IsLeftQuandle], IdFunc);
InstallMethod(AsRightQuasigroup, "for a right quasigroup", InstallMethod(AsRightQuasigroup, "for a right quasigroup",
[IsRightQuasigroup], IdFunc); [IsRightQuasigroup], IdFunc);
InstallMethod(AsRightRack, "for a right rack", InstallMethod(AsRightRack, "for a right rack",
[IsRightRack], IdFunc); [IsRightRack], IdFunc);
InstallMethod(AsRightQuandle, "for a left quandle", InstallMethod(AsRightQuandle, "for a right quandle",
[IsLeftQuandle], IdFunc); [IsRightQuandle], IdFunc);
AsAStructure@ := function(struc, D) AsAStructure@ := function(struc, D)
local T,S; local T,S;