Add and document new function DirectProductFamily

doc/ref/mapping.xml

@@ -37,10 +37,11 @@ section&nbsp;<Ref Sect="General Mappings"/>.
 
 
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
-<Section Label="sect:IsDirectProductElement">
-<Heading>IsDirectProductElement (Filter)</Heading>
+<Section Label="sect:Direct Products and their Elements">
+<Heading>Direct Products and their Elements</Heading>
 
 <#Include Label="IsDirectProductElement">
+<#Include Label="DirectProductFamily">
 
 </Section>
 

hpcgap/lib/mapping.gi

@@ -1262,12 +1262,11 @@ InstallMethod( UnderlyingRelation,
     true,
     [ IsGeneralMapping ], 0,
     function( map )
-    local rel;
-    rel:= Objectify( NewType( CollectionsFamily(
-          DirectProductElementsFamily( [ ElementsFamily( FamilyObj( Source( map ) ) ),
-                          ElementsFamily( FamilyObj( Range( map  ) ) ) ] ) ),
-                              IsDomain and IsAttributeStoringRep ),
-                     rec() );
+    local type, rel;
+    type:= NewType( DirectProductFamily( [ FamilyObj( Source( map ) ),
+                                           FamilyObj( Range( map ) ) ] ),
+                    IsDomain and IsAttributeStoringRep );
+    rel:= Objectify( type, rec() );
     SetUnderlyingGeneralMapping( rel, map );
     return rel;
     end );

hpcgap/lib/tuples.gi

@@ -512,3 +512,17 @@ InstallOtherMethod( \*,
     fi;
     return DirectProductElement( List( dpelm, entry -> nonlist * entry ) );
     end );
+
+
+#############################################################################
+##
+##
+InstallGlobalFunction( DirectProductFamily,
+    function( args )
+    if not IsDenseList(args) or not ForAll(args, IsCollectionFamily) then
+        ErrorNoReturn("<args> must be a dense list of collection families");
+    fi;
+    return CollectionsFamily(
+        DirectProductElementsFamily( List( args, ElementsFamily ) )
+    );
+    end );

lib/mapping.gi

@@ -1259,12 +1259,11 @@ InstallMethod( UnderlyingRelation,
     true,
     [ IsGeneralMapping ], 0,
     function( map )
-    local rel;
-    rel:= Objectify( NewType( CollectionsFamily(
-          DirectProductElementsFamily( [ ElementsFamily( FamilyObj( Source( map ) ) ),
-                          ElementsFamily( FamilyObj( Range( map  ) ) ) ] ) ),
-                              IsDomain and IsAttributeStoringRep ),
-                     rec() );
+    local type, rel;
+    type:= NewType( DirectProductFamily( [ FamilyObj( Source( map ) ),
+                                           FamilyObj( Range( map ) ) ] ),
+                    IsDomain and IsAttributeStoringRep );
+    rel:= Objectify( type, rec() );
     SetUnderlyingGeneralMapping( rel, map );
     return rel;
     end );

lib/tuples.gd

@@ -178,3 +178,52 @@ direct product elements families" );
 DeclareOperation( "DirectProductElement", [ IsList ]);
 DeclareOperation( "DirectProductElementNC",
     [ IsDirectProductElementFamily, IsList ]);
+
+
+#############################################################################
+##
+##
+##  <#GAPDoc Label="DirectProductFamily">
+##  <ManSection>
+##  <Func Name="DirectProductFamily" Arg='args'/>
+##
+##  <Description>
+##  <A>args</A> must be a dense list of <Ref Attr="CollectionsFamily"/>
+##  families, otherwise the function raises an error.
+##  <P/>
+##  <Ref Func="DirectProductFamily"/> returns <C>fam</C>, a collections
+##  family of <Ref Filt="IsDirectProductElement"/> objects.
+##  <P/>
+##  <C>fam</C> is the <Ref Filt="CollectionsFamily"/> of
+##  <Ref Filt="IsDirectProductElement"/> objects
+##  whose <C>i</C>-th component is in <C>ElementsFamily(args[i])</C>.
+##  <P/>
+##  Note that a collection in <C>fam</C> may not itself be a
+##  direct product; it just is a subcollection of a direct product.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> D8 := DihedralGroup(IsPermGroup, 8);;
+##  gap> FamilyObj(D8) = CollectionsFamily(PermutationsFamily);
+##  true
+##  gap> fam := DirectProductFamily([FamilyObj(D8), FamilyObj(D8)]);;
+##  gap> ComponentsOfDirectProductElementsFamily(ElementsFamily(fam));
+##  [ <Family: "PermutationsFamily">, <Family: "PermutationsFamily"> ]
+##  ]]></Example>
+##  Also note that not all direct products in &GAP; are created via these
+##  families. For example if the arguments to <Ref Func="DirectProduct"/>
+##  are permutation groups, then it returns a permutation group as well, whose
+##  elements are not <Ref Filt="IsDirectProductElement"/> objects.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> fam = FamilyObj(DirectProduct(D8, D8));
+##  false
+##  gap> D4 := DihedralGroup(IsPcGroup, 4);;
+##  gap> fam2 := DirectProductFamily([FamilyObj(D8), FamilyObj(D4)]);;
+##  gap> fam2 = FamilyObj(DirectProduct(D8, D4));
+##  true
+##  ]]></Example>
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+DeclareGlobalFunction( "DirectProductFamily",
+                       "for a dense list of collection families" );

lib/tuples.gi

@@ -506,3 +506,17 @@ InstallOtherMethod( \*,
     fi;
     return DirectProductElement( List( dpelm, entry -> nonlist * entry ) );
     end );
+
+
+#############################################################################
+##
+##
+InstallGlobalFunction( DirectProductFamily,
+    function( args )
+    if not IsDenseList(args) or not ForAll(args, IsCollectionFamily) then
+        ErrorNoReturn("<args> must be a dense list of collection families");
+    fi;
+    return CollectionsFamily(
+        DirectProductElementsFamily( List( args, ElementsFamily ) )
+    );
+    end );

tst/testinstall/tuples.tst

@@ -0,0 +1,13 @@
+gap> START_TEST("tuples.tst");
+gap> D8 := DihedralGroup(IsPermGroup, 8);;
+gap> fam := FamilyObj(D8);
+<Family: "CollectionsFamily(...)">
+gap> ElementsFamily(fam);
+<Family: "PermutationsFamily">
+gap> dpf := DirectProductFamily([fam, fam]);
+<Family: "CollectionsFamily(...)">
+gap> IsDirectProductElementFamily(ElementsFamily(dpf));
+true
+
+#
+gap> STOP_TEST("tuples.tst");