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,46 @@ 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 a collections family <C>fam</C>
+##  with the following property:
+##  Each collection <C>coll</C> in <C>fam</C> is a direct product
+##  whose <C>i</C>-th factors are collections in <C>args[i]</C>.
+##  This is modelled on the level of the elements by requiring that each
+##  <C>elm</C> of <C>coll</C> must be an <Ref Filt="IsDirectProductElement"/>
+##  object with <C>elm[i]</C> contained in <C>ElementsFamily(args[i])</C>.
+##  <P/>
+##  Note though that not all direct products in &GAP; are created via these
+##  families, see for example <Ref Func="DirectProduct"/> for permutation
+##  groups.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> D8 := DihedralGroup(IsPermGroup, 8);;
+##  gap> fam := FamilyObj(D8);
+##  <Family: "CollectionsFamily(...)">
+##  gap> ElementsFamily(fam);
+##  <Family: "PermutationsFamily">
+##  gap> productFamily := DirectProductFamily([fam, fam]);
+##  <Family: "CollectionsFamily(...)">
+##  gap> elmsOfProductFamily := ElementsFamily(productFamily);
+##  <Family: "DirectProductElementsFamily( <<famlist>> )">
+##  gap> ComponentsOfDirectProductElementsFamily(elmsOfProductFamily);
+##  [ <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");