lib: add operation DirectProductFamily

This declares the new operation DirectProductFamily and installs a
method for it. The new method is also added to `hpcgap/lib/tuples.gi`.
Also adds documentation and tests.

In the reference manual, the section "IsDirectProductElement (Filter)"
is renamed into "Direct Products and their Elements" to also accomodate
the documentation of DirectProductFamily and future categories and
operations.

UnderlyingRelation is adapted to use the new method, which makes it
easier to read.

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/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,43 @@ 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> must thus not necessarily be a
+##  direct product.
+##  Also note that not all direct products in &GAP; are created via these
+##  families. For example the elements of a permutation group created via
+##  <Ref Func="DirectProduct"/> are not <Ref Filt="IsDirectProductElement"/>
+##  objects.
+##  <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>
+##  </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");