From 4f0d17fd61d2869534aabb01aedcd1254567a9bc Mon Sep 17 00:00:00 2001 From: Max Horn Date: Fri, 15 May 2026 15:15:05 +0200 Subject: [PATCH] Clarify LocalNR manual entries Improve the manual text for LocalNR by fixing grammar, making library references explicit, and explaining several return values and parameter conventions more precisely. Clarify that AdditiveGroupsOfLibraryOfLNRsOfOrder returns groups. Fill in or tighten several function descriptions in the manual source and regenerate the extracted example tests accordingly. Co-authored-by: Codex --- lib/lib_local.gd | 45 ++++++++++++++++++++++------------------ lib/local.gd | 53 ++++++++++++++++++++++++++--------------------- tst/localnr01.tst | 14 ++++++------- tst/localnr02.tst | 52 +++++++++++++++++++++++----------------------- 4 files changed, 87 insertions(+), 77 deletions(-) diff --git a/lib/lib_local.gd b/lib/lib_local.gd index a4e15a6..5ddf891 100644 --- a/lib/lib_local.gd +++ b/lib/lib_local.gd @@ -79,9 +79,9 @@ ################################### #! @Description -#! The argument is $n$. -#! The output a list of IdGroup of the additive groups -#! of local nearrings from Library of order $n$. +#! The argument is $n$. +#! The output is a list of additive groups of local nearrings in the +#! library of this package of order $n$. #! @Returns a list #! @Arguments n #! @Label @@ -96,9 +96,9 @@ DeclareGlobalFunction( "AdditiveGroupsOfLibraryOfLNRsOfOrder"); ################################### #! @Description -#! The argument is a group $G$. -#! The output a list of the catalogues of local nearrings -#! from Library on $G$. +#! The argument is a group $G$. +#! The output is a list of catalogue entries for the local nearrings in +#! the library of this package whose additive group is isomorphic to $G$. #! @Returns a list #! @Arguments G #! @Label @@ -122,9 +122,10 @@ DeclareGlobalFunction( "LibraryOfLNRsOnGroup"); #! @Description #! The arguments are $k$, $l$, $m$, $n$, $w$. -#! The output is local nearring from Library without -#! check. The arguments $k$, $l$, $m$, $n$ are from IdGroup of the additive group and the multiplicative group, -#! respectively, $w$ is the position in the list. +#! The output is the $w$-th local nearring from the library of this +#! package whose additive group has IdGroup value [k,l] +#! and whose multiplicative group has IdGroup value [m,n]. +#! No validation of the arguments is performed. #! @Returns a nearring #! @Arguments k,l,m,n,w #! @Label @@ -140,8 +141,10 @@ DeclareOperation( "LocalNearRing", [ IsInt, IsInt, IsInt, IsInt, IsInt ]); #! @Description #! The arguments are $k$, $l$, $m$, $n$. -#! The output are all local nearrings from Library without -#! check. The arguments $k$, $l$, $m$, $n$ are as above. +#! The output is the list of all local nearrings from the library of this +#! package whose additive group has IdGroup value [k,l] +#! and whose multiplicative group has IdGroup value [m,n]. +#! No validation of the arguments is performed. #! @Returns a list #! @Arguments k,l,m,n #! @Label @@ -157,8 +160,10 @@ DeclareOperation( "AllLocalNearRings", [ IsInt, IsInt, IsInt, IsInt ]); #! @Description #! The arguments are $k$, $l$, $m$, $n$. -#! The output are number of all local nearrings from Library without -#! check. The arguments $k$, $l$, $m$, $n$ are as above. +#! The output is the number of local nearrings in the library of this +#! package whose additive group has IdGroup value [k,l] +#! and whose multiplicative group has IdGroup value [m,n]. +#! No validation of the arguments is performed. #! @Returns a number #! @Arguments k,l,m,n #! @Label @@ -174,10 +179,10 @@ DeclareSynonym("NrLocalNearRings", NumberLocalNearRings); ################################### #! @Description -#! The argument is a group $G$. -#! The output is true if in Library there exists a local nearring -#! whose additive group is isomorphic to $G$ -#! otherwise the output is false. +#! The argument is a group $G$. +#! The output is true if the library of this package contains a +#! local nearring whose additive group is isomorphic to $G$, and +#! false otherwise. #! @Returns a boolean #! @Arguments G #! @Label @@ -195,9 +200,9 @@ DeclareGlobalFunction( "IsAdditiveGroupOfLibraryOfLNRs"); ################################### #! @Description -#! The argument is a group $G$. -#! The output some information about local nearrings -#! from Library on $G$. +#! The argument is a group $G$. +#! The output is summary information about the local nearrings in the +#! library of this package whose additive group is isomorphic to $G$. #! @Returns information #! @Arguments G #! @Label diff --git a/lib/local.gd b/lib/local.gd index 76d68a5..81076d0 100644 --- a/lib/local.gd +++ b/lib/local.gd @@ -30,8 +30,8 @@ #! @Label DeclareProperty( "IsMinimalNonAbelianGroup", IsGroup ); -#! Recall that each finite non-abelian group whose proper subgroups are -#! abelian is called a Miller-Moreno group or in other terminology +#! Recall that each finite non-abelian group whose proper subgroups are +#! abelian is called a Miller-Moreno group or, in other terminology, #! a minimal non-abelian group. #! @BeginExample @@ -73,7 +73,9 @@ DeclareProperty( "IsMetacyclicPGroup", IsPGroup ); #! @Description #! The argument is a group $G$. -#! The output is +#! The output is a list of pairs [x,H], where x is a +#! representative of an endo-orbit of $G$ and H is the set of all +#! images of x under endomorphisms of $G$. #! @Returns EndoOrbitsOfGroup #! @Arguments G #! @Label @@ -93,19 +95,19 @@ DeclareOperation( "EndoOrbitsOfGroup", [ IsGroup ] ); #! @Description #! The argument is a group $G$. -#! The output is true if $G$ is a endocyclic group, +#! The output is true if $G$ is an endocyclic group, #! otherwise the output is false. #! @Returns a boolean #! @Arguments G #! @Label DeclareProperty( "IsEndoCyclicGroup", IsGroup ); -#!Let $G$ be a group and $End G$ be the set of all its endomorphisms, -#!which can be considered as a semigroup with respect to the composition operation of endomorphisms. -#!For each $g\in G$ we denote by $g^{End G}$ the set $\{g^\alpha| \alpha\in End G\}$ +#! Let $G$ be a group and $End G$ be the set of all its endomorphisms, +#! which can be considered as a semigroup with respect to composition. +#! For each $g\in G$ we denote by $g^{End G}$ the set $\{g^\alpha| \alpha\in End G\}$ #!of all images of the element $g$ with respect to endomorphisms of $End G$. -#!A group $G$ is called endocyclic if it contains an element $g$ with $G=g^{End G}$. +#! A group $G$ is called endocyclic if it contains an element $g$ with $G=g^{End G}$. #! @BeginExample #! gap> IsEndoCyclicGroup(D); @@ -347,16 +349,17 @@ DeclareProperty( "IsOneGeneratedNearRing", IsNearRing ); #! @Description #! The arguments are a nearring $R$ with identity and a set of units $Un$ of $R$. -#! The output are the automorphisms associated with nearring units. -#! @Returns automorphisms +#! The output is the list of automorphisms of the additive group of $R$ +#! associated with the units in $Un$. +#! @Returns a list of automorphisms #! @Arguments R,Un #! @Label DeclareOperation( "AutomorphismsAssociatedWithNearRingUnits", [ IsNearRing, IsNearRingElementCollection ] ); #! A subgroup $A$ of the automorphism group $Aut R^+$ of the additive group of -#! the nearring $R$ with identity isomorphic to the multiplicative group $R^*$ -#! and satisfies the condition $$i^A=\{i^a\mid a\in A\}=R^*$$ is called -#! the subgroup of $Aut R^+$ associated with the group $R^*$. +#! the nearring $R$ with identity isomorphic to the multiplicative group $R^*$ +#! and satisfying the condition $$i^A=\{i^a\mid a\in A\}=R^*$$ is called +#! the subgroup of $Aut R^+$ associated with $R^*$. #! @BeginExample @@ -377,7 +380,7 @@ DeclareOperation( "AutomorphismsAssociatedWithNearRingUnits", [ IsNearRing, IsNe #! @Description #! The arguments are a nearring $R$ and a set $Elm$ of nearring elements. #! The output is the endomorphisms associated with nearring elements. -#! @Returns endomorphisms +#! @Returns a list of endomorphisms #! @Arguments R, Elm #! @Label DeclareOperation( "EndomorphismsAssociatedWithNearRingElements", [ IsNearRing, IsNearRingElementCollection ] ); @@ -394,7 +397,7 @@ DeclareOperation( "EndomorphismsAssociatedWithNearRingElements", [ IsNearRing, I #! @Description #! The argument is a nearring $R$ with identity. -#! The output is the semidirect product associated with nearring $R$. +#! The output is the semidirect product associated with the nearring $R$. #! @Returns a semidirect product #! @Arguments R #! @Label @@ -413,8 +416,8 @@ DeclareOperation( "SemidirectProductAssociatedWithNearRing", [ IsNearRing ]); #! @Description #! The arguments are a nearring $R$ with identity and -#! a subgroup $H$ of additive group of $R$. -#! The output is true if $H$ is a constructive subgroup of nearring $R$, +#! a subgroup $H$ of the additive group of $R$. +#! The output is true if $H$ is a circle subgroup of the nearring $R$, #! otherwise the output is false. #! @Returns a boolean #! @Arguments R,H @@ -433,8 +436,9 @@ DeclareOperation( "IsCircleSubgroupOfNearRing", [IsNearRing, IsGroup ]); #! @Description #! The arguments are a nearring $R$ with identity and -#! a constructive subgroup $H$ of $R$. -#! The output is the group +#! a circle subgroup $H$ of $R$. +#! The output is the semidirect product associated with $H$ and the +#! automorphisms determined by the corresponding units. #! @Returns a group #! @Arguments R,H #! @Label @@ -451,7 +455,7 @@ DeclareOperation( "FactorizedGroupAssociatedWithCircleSubgroupOfNearRing", [ IsN #! @Description #! The argument is a nearring $R$. -#! The output is the constant part of nearring $R$. +#! The output is the constant part of the nearring $R$. #! @Returns a constant part #! @Arguments R #! @Label @@ -470,7 +474,7 @@ DeclareAttribute("ConstantPartOfNearRing", IsNearRing ); #! @Description #! The argument is a nearring $R$. -#! The output is the zero-symmetric part of nearring $R$. +#! The output is the zero-symmetric part of the nearring $R$. #! @Returns a zero-symmetric part #! @Arguments R #! @Label @@ -486,8 +490,9 @@ DeclareAttribute("ZeroSymmetricPartOfNearRing", IsNearRing ); #! @Description #! The argument is a nearring $R$. -#! The output is the group of units as group of automorphisms $R$. -#! @Returns a group of units +#! The output is a group of automorphisms of the additive group of $R$ +#! that is isomorphic to the group of units of $R$. +#! @Returns a group #! @Arguments R #! @Label DeclareAttribute("GroupOfUnitsAsGroupOfAutomorphisms", IsNearRing ); @@ -505,7 +510,7 @@ DeclareAttribute("GroupOfUnitsAsGroupOfAutomorphisms", IsNearRing ); ################################### #! @Description #! The argument is a nearring $R$ and an element $r$. -#! The output is true if $r$ is a distributive element of nearring $R$, +#! The output is true if $r$ is a distributive element of the nearring $R$, #! otherwise the output is false. #! @Returns a boolean #! @Arguments R, r diff --git a/tst/localnr01.tst b/tst/localnr01.tst index cfe5435..d9f3f13 100644 --- a/tst/localnr01.tst +++ b/tst/localnr01.tst @@ -10,12 +10,12 @@ # gap> START_TEST("localnr01.tst"); -# doc/_Chapter_Local_nearrings.xml:76-80 +# doc/_Chapter_Local_nearrings.xml:77-81 gap> List(AdditiveGroupsOfLibraryOfLNRsOfOrder(81),IdGroup); [ [ 81, 1 ], [ 81, 2 ], [ 81, 3 ], [ 81, 5 ], [ 81, 6 ], [ 81, 11 ], [ 81, 12 ], [ 81, 13 ], [ 81, 15 ] ] -# doc/_Chapter_Local_nearrings.xml:96-105 +# doc/_Chapter_Local_nearrings.xml:95-104 gap> G:=SmallGroup(81,2); gap> LibraryOfLNRsOnGroup(G); @@ -25,21 +25,21 @@ gap> LibraryOfLNRsOnGroup(G); "AllLocalNearRings(81,2,72,14)", "AllLocalNearRings(81,2,72,19)", "AllLocalNearRings(81,2,72,24)", "AllLocalNearRings(81,2,72,26)" ] -# doc/_Chapter_Local_nearrings.xml:121-125 +# doc/_Chapter_Local_nearrings.xml:119-123 gap> L:=LocalNearRing(81,12,54,8,3); ExplicitMultiplicationNearRing ( , multiplication ) -# doc/_Chapter_Local_nearrings.xml:140-144 +# doc/_Chapter_Local_nearrings.xml:138-142 gap> L:=AllLocalNearRings(81,12,54,8);; gap> Size(L); 30 -# doc/_Chapter_Local_nearrings.xml:159-162 +# doc/_Chapter_Local_nearrings.xml:157-160 gap> NumberLocalNearRings(81,15,54,8); 10 -# doc/_Chapter_Local_nearrings.xml:178-185 +# doc/_Chapter_Local_nearrings.xml:174-181 gap> G:=SmallGroup(25,2); gap> IsAdditiveGroupOfLibraryOfLNRs(G); @@ -47,7 +47,7 @@ true gap> IsAdditiveGroupOfLibraryOfLNRs(SmallGroup(81,14)); false -# doc/_Chapter_Local_nearrings.xml:200-209 +# doc/_Chapter_Local_nearrings.xml:194-203 gap> InfoLocalNearRing(SmallGroup(361,2)); The local nearrings are sorted by their multiplicative groups. [ "AllLocalNearRings(361,2,342,1) (2)", "AllLocalNearRings(361,2,342,2) (2)", \ diff --git a/tst/localnr02.tst b/tst/localnr02.tst index b75840d..7ac174c 100644 --- a/tst/localnr02.tst +++ b/tst/localnr02.tst @@ -10,7 +10,7 @@ # gap> START_TEST("localnr02.tst"); -# doc/_Chapter_Functions.xml:25-36 +# doc/_Chapter_Functions.xml:24-35 gap> H:=SmallGroup(120,4); gap> IsMinimalNonAbelianGroup(H); @@ -22,7 +22,7 @@ true gap> IsMinimalNonAbelianGroup(SmallGroup(16,8)); false -# doc/_Chapter_Functions.xml:51-58 +# doc/_Chapter_Functions.xml:48-55 gap> IsMetacyclicPGroup(K); true gap> IsMetacyclicPGroup(SmallGroup(81,4)); @@ -30,7 +30,7 @@ true gap> IsMetacyclicPGroup(SmallGroup(81,15)); false -# doc/_Chapter_Functions.xml:72-80 +# doc/_Chapter_Functions.xml:69-77 gap> D:=SmallGroup(81,2); gap> T:=EndoOrbitsOfGroup(D);; @@ -39,11 +39,11 @@ gap> Length(T); gap> Size(T[1][2]); 81 -# doc/_Chapter_Functions.xml:100-103 +# doc/_Chapter_Functions.xml:95-98 gap> IsEndoCyclicGroup(D); true -# doc/_Chapter_Functions.xml:124-140 +# doc/_Chapter_Functions.xml:116-132 gap> N:=LocalNearRing(32,5,16,3,8); ExplicitMultiplicationNearRing ( , multiplication ) @@ -60,7 +60,7 @@ LibraryNearRing(6/2, 3) gap> UnitsOfNearRing(L); [ ] -# doc/_Chapter_Functions.xml:155-169 +# doc/_Chapter_Functions.xml:145-159 gap> H:=SmallGroup(16,6); gap> A:= AutomorphismNearRing(H); @@ -75,7 +75,7 @@ LibraryNearRing(8/2, 814) gap> IsLocalNearRing(K); false -# doc/_Chapter_Functions.xml:184-191 +# doc/_Chapter_Functions.xml:172-179 gap> L:=AllLocalNearRings(16,14,8,4);; gap> Size(L); 24 @@ -83,7 +83,7 @@ gap> F:=Filtered(L,x->IsLocalRing(x));; gap> Size(F); 1 -# doc/_Chapter_Functions.xml:205-220 +# doc/_Chapter_Functions.xml:191-206 gap> T:=LocalNearRing(49,2,42,1,1); ExplicitMultiplicationNearRing ( , multiplication ) @@ -99,7 +99,7 @@ gap> N:=SortedList(NearRingNonUnits(R)); ((1,5,3,7)(2,8,4,6)), ((1,6,3,8)(2,5,4,7)), ((1,7,3,5)(2,6,4,8)), ((1,8,3,6)(2,7,4,5)) ] -# doc/_Chapter_Functions.xml:234-247 +# doc/_Chapter_Functions.xml:218-231 gap> B:=LocalNearRing(25,2,20,3,1); ExplicitMultiplicationNearRing ( , multiplication ) gap> D:=DistributiveElements(B);; @@ -113,7 +113,7 @@ false gap> IsDgNearRing(Rs); true -# doc/_Chapter_Functions.xml:261-271 +# doc/_Chapter_Functions.xml:243-253 gap> T:=LocalNearRing(125,4,100,9,1); ExplicitMultiplicationNearRing ( , multiplication ) @@ -124,26 +124,26 @@ Group([ of ..., f2, f3, f2^2, f2*f3, f3^2, f2^3, f2^2*f3, f2*f3^2, f3 gap> IdGroup(L); [ 25, 2 ] -# doc/_Chapter_Functions.xml:285-290 +# doc/_Chapter_Functions.xml:265-270 gap> I:=NonUnitsAsNearRingIdeal(T); < nearring ideal > gap> Size(I); 25 -# doc/_Chapter_Functions.xml:304-310 +# doc/_Chapter_Functions.xml:282-288 gap> B:=LocalNearRing(16,10,8,2,7);; gap> M:=MultiplicativeSemigroupOfNearRing(B); gap> Size(M); 16 -# doc/_Chapter_Functions.xml:324-329 +# doc/_Chapter_Functions.xml:300-305 gap> Nm:=NonUnitsAsMultiplicativeSemigroup(B); gap> Size(Nm); 8 -# doc/_Chapter_Functions.xml:344-354 +# doc/_Chapter_Functions.xml:318-328 gap> D:=LocalNearRing(49,2,42,4,1); ExplicitMultiplicationNearRing ( , multiplication ) gap> IsOneGeneratedNearRing(D); @@ -154,7 +154,7 @@ ExplicitMultiplicationNearRing ( IsOneGeneratedNearRing(H); false -# doc/_Chapter_Functions.xml:372-383 +# doc/_Chapter_Functions.xml:345-356 gap> S:=UnitsOfNearRing(D); [ (f1), (f1*f2), (f1*f2^2), (f1*f2^3), (f1*f2^4), (f1*f2^5), (f1*f2^6), (f1^2), (f1^2*f2), (f1^2*f2^2), (f1^2*f2^3), (f1^2*f2^4), (f1^2*f2^5), (f1^2*f2^6), (f1^3), (f1^3*f2), @@ -166,14 +166,14 @@ gap> A:=AutomorphismsAssociatedWithNearRingUnits(D,S);; gap> Size(A); 42 -# doc/_Chapter_Functions.xml:397-403 +# doc/_Chapter_Functions.xml:368-374 gap> Nu:=NearRingNonUnits(D); [ ( of ...), (f2), (f2^2), (f2^3), (f2^4), (f2^5), (f2^6) ] gap> En:=EndomorphismsAssociatedWithNearRingElements(D,Nu);; gap> Size(En); 7 -# doc/_Chapter_Functions.xml:417-424 +# doc/_Chapter_Functions.xml:386-393 gap> T:=LocalNearRing(25,2,20,2,1); ExplicitMultiplicationNearRing ( , multiplication ) gap> SemidirectProductAssociatedWithNearRing(T); @@ -181,20 +181,20 @@ gap> SemidirectProductAssociatedWithNearRing(T); gap> Size(last); 500 -# doc/_Chapter_Functions.xml:440-446 +# doc/_Chapter_Functions.xml:407-413 gap> Sg:=Subgroups(GroupReduct(T));; gap> Size(Sg); 8 gap> F:=Filtered(Sg,x->IsCircleSubgroupOfNearRing(T,x)); [ Group([ ]), Group([ f2 ]) ] -# doc/_Chapter_Functions.xml:461-466 +# doc/_Chapter_Functions.xml:427-432 gap> FG:=FactorizedGroupAssociatedWithCircleSubgroupOfNearRing(T,F[2]); gap> IdGroup(FG); [ 25, 2 ] -# doc/_Chapter_Functions.xml:480-487 +# doc/_Chapter_Functions.xml:444-451 gap> H:=LocalNearRing(361,2,342,7,7); ExplicitMultiplicationNearRing ( , multiplication ) @@ -202,12 +202,12 @@ gap> C:=ConstantPartOfNearRing(H);; gap> Size(C); 19 -# doc/_Chapter_Functions.xml:501-505 +# doc/_Chapter_Functions.xml:463-467 gap> ZeroSymmetricPartOfNearRing(H);; gap> Size(last); 19 -# doc/_Chapter_Functions.xml:519-526 +# doc/_Chapter_Functions.xml:480-487 gap> M:=LocalNearRing(27,4,18,3,2); ExplicitMultiplicationNearRing ( , multiplication ) gap> GroupOfUnitsAsGroupOfAutomorphisms(M); @@ -215,7 +215,7 @@ gap> GroupOfUnitsAsGroupOfAutomorphisms(M); gap> Size(last); 18 -# doc/_Chapter_Functions.xml:541-550 +# doc/_Chapter_Functions.xml:500-509 gap> D:=LocalNearRing(49,2,42,6,1); ExplicitMultiplicationNearRing ( , multiplication ) @@ -225,13 +225,13 @@ gap> d:=h[3]; gap> IsDistributiveElementOfNearRing(D,d); true -# doc/_Chapter_Functions.xml:565-570 +# doc/_Chapter_Functions.xml:522-527 gap> N:=LocalNearRing(16,10,8,2,7); ExplicitMultiplicationNearRing ( , multiplication ) gap> IsSemiDistributiveNearRing(N); true -# doc/_Chapter_Functions.xml:585-595 +# doc/_Chapter_Functions.xml:540-550 gap> N:=LocalNearRing(343,5,294,8,2); ExplicitMultiplicationNearRing ( , multiplication ) @@ -242,7 +242,7 @@ gap> Identity(N); gap> IsNearRingWithIdentity(N); true -# doc/_Chapter_Functions.xml:611-627 +# doc/_Chapter_Functions.xml:564-580 gap> T:=LocalNearRing(49,2,42,1,2); ExplicitMultiplicationNearRing ( , multiplication )