lib: add operation DirectProductFamily

This declares the new operation DirectProductFamily and installs a
method for it. 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>
 

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,42 @@ 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/>
+##  <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");