%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%A  design.tex               DESIGN documentation              Leonard Soicher
%
%
%
\def\GRAPE{\sf GRAPE}
\def\DESIGN{\sf DESIGN}
\def\GAPDoc{\sf GAPDoc}
\def\nauty{\it nauty}
\def\Aut{{\rm Aut}\,} 

\Chapter{Design}

This manual describes the {\DESIGN}~1.8.2 package for {\GAP}.
The {\DESIGN} package is for constructing, classifying, partitioning,
and studying block designs.

The {\DESIGN} package is Copyright {\copyright} Leonard H. Soicher
2003--2024.  {\DESIGN} is part of a wider project, which received EPSRC
funding under grant GR/R29659/01, to provide a web-based resource for
design theory; see \URL{http://designtheory.org} and \cite{Dotw}.
The development of {\DESIGN} was also partially supported by EPSRC grant
EP/M022641/1 (CoDiMa: a Collaborative Computational Project in the area
of Computational Discrete Mathematics).

{\DESIGN} is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version. For details, see 
\URL{https://www.gnu.org/licenses/gpl.html}.

Please reference your use of the {\DESIGN} package in a published work
as follows:

L.H.~Soicher, The DESIGN package for GAP, Version 1.8.2, 2024,
\URL{https://gap-packages.github.io/design}.

For questions, remarks, suggestions, and issues, please use the issue
tracker at \URL{https://github.com/gap-packages/design/issues}.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Installing the DESIGN Package}

The {\DESIGN} package is included in the standard {\GAP} distribution. You
only need to download and install {\DESIGN} if you need to install
the package locally or are installing an upgrade of {\DESIGN} to
an existing installation of {\GAP} (see the main {\GAP} reference
section "ref:Installing a GAP Package").  If you do need to download
{\DESIGN}, you can find an archive file for the latest release at
\URL{https://github.com/gap-packages/design/releases}.  This archive
file can then be downloaded and unpacked in the `pkg' subdirectory of
an appropriate {\GAP} root directory (see the main {\GAP} reference section
"ref:GAP Root Directories").

The {\DESIGN} package is written entirely in {\GAP} code, and requires
no further installation.  However, {\DESIGN} makes use of the {\GRAPE}
package \cite{Grape}, which must be fully installed.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Loading DESIGN}

Before using {\DESIGN} you must load the package within {\GAP} by calling 

\begintt
LoadPackage("design");
\endtt

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{The structure of a block design in DESIGN}

A *block design*
\index{block design} 
is an ordered pair $(X,B)$, where
$X$ is a non-empty finite set whose elements are called *points*, and
$B$ is a non-empty finite multiset whose elements are called *blocks*,
such that each block is a non-empty finite multiset of points.

{\DESIGN} deals with arbitrary block designs. However, at present, some
{\DESIGN} functions only work for *binary* block designs
\index{binary block design} 
(i.e. those with no repeated element in any block of
the design), but these functions will check if an input block design
is binary.

In {\DESIGN}, a block design <D> is stored as a record, with mandatory
components `isBlockDesign', `v', and `blocks'.  The points of a block
design <D> are always 1,2,...,`<D>.v', but they may also be given *names*
in the optional component `pointNames', with `<D>.pointNames[<i>]'
the name of point <i>.  The `blocks' component must be a sorted list
of the blocks of <D> (including any repeats), with each block being a
sorted list of points (including any repeats). 

A block design record may also have some optional components which store
information about the design. At present these optional components include
`isSimple', `isBinary', `isConnected', `r', `blockSizes', `blockNumbers',
`resolutions', `autGroup', `autSubgroup', `tSubsetStructure',
`allTDesignLambdas', `efficiency', `id', `statistical_propertiesXML',
and `pointNames'.

A non-expert user should only use functions in the {\DESIGN} package to
create block design records and their components.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Example of the use of DESIGN}

To give you an idea of the capabilities of this package, we now give
an extended example of an application of the {\DESIGN} package, in
which a nearly resolvable non-simple 2-(21,4,3) design is constructed
(for Donald Preece) via a pairwise-balanced design. All the {\DESIGN}
functions used here are described in this manual.

The program first discovers the unique (up to isomorphism)
pairwise-balanced 2-(21,$\{4,5\}$,1) design $D$ invariant under $H=\langle
(1,2,\ldots,20)\rangle$, and then applies the $\*$-construction of
\cite{McSo} to this design $D$ to obtain a non-simple 2-(21,4,3) design
$Dstar$ with automorphism group of order 80. The program then classifies
the near-resolutions of $Dstar$ invariant under the subgroup of order 5
of $H$, and finds exactly two such (up to the action of $\Aut(Dstar)$).
Finally, $Dstar$ is printed.

Further extended examples of the use of the {\DESIGN} package can be
found in \cite{Soi13} and \cite{Soi24}.

\beginexample
gap> H:=CyclicGroup(IsPermGroup,20);
Group([ (1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20) ])
gap> D:=BlockDesigns(rec(v:=21,blockSizes:=[4,5],
>       tSubsetStructure:=rec(t:=2,lambdas:=[1]),
>       requiredAutSubgroup:=H ));;
gap> Length(D);
1
gap> D:=D[1];;
gap> BlockSizes(D);
[ 4, 5 ]
gap> BlockNumbers(D);
[ 20, 9 ]
gap> Size(AutGroupBlockDesign(D));
80
gap> Dstar:=TDesignFromTBD(D,2,4);;
gap> AllTDesignLambdas(Dstar);
[ 105, 20, 3 ]
gap> IsSimpleBlockDesign(Dstar);
false
gap> Size(AutGroupBlockDesign(Dstar));
80
gap> near_resolutions:=PartitionsIntoBlockDesigns(rec(
>    blockDesign:=Dstar,
>    v:=21,blockSizes:=[4],
>    tSubsetStructure:=rec(t:=0,lambdas:=[5]),
>    blockIntersectionNumbers:=[[ [0] ]],
>    requiredAutSubgroup:=SylowSubgroup(H,5) ));;
gap> Length(near_resolutions);
2
gap> List(near_resolutions,x->Size(x.autGroup));
[ 5, 20 ]
gap> Print(Dstar,"\n");
rec(
  isBlockDesign := true,
  v := 21,
  blocks := [ [ 1, 2, 4, 15 ], [ 1, 2, 4, 15 ], [ 1, 2, 4, 15 ], 
      [ 1, 3, 14, 20 ], [ 1, 3, 14, 20 ], [ 1, 3, 14, 20 ], [ 1, 5, 9, 13 ], 
      [ 1, 5, 9, 17 ], [ 1, 5, 13, 17 ], [ 1, 6, 11, 16 ], [ 1, 6, 11, 21 ], 
      [ 1, 6, 16, 21 ], [ 1, 7, 8, 10 ], [ 1, 7, 8, 10 ], [ 1, 7, 8, 10 ], 
      [ 1, 9, 13, 17 ], [ 1, 11, 16, 21 ], [ 1, 12, 18, 19 ], 
      [ 1, 12, 18, 19 ], [ 1, 12, 18, 19 ], [ 2, 3, 5, 16 ], [ 2, 3, 5, 16 ], 
      [ 2, 3, 5, 16 ], [ 2, 6, 10, 14 ], [ 2, 6, 10, 18 ], [ 2, 6, 14, 18 ], 
      [ 2, 7, 12, 17 ], [ 2, 7, 12, 21 ], [ 2, 7, 17, 21 ], [ 2, 8, 9, 11 ], 
      [ 2, 8, 9, 11 ], [ 2, 8, 9, 11 ], [ 2, 10, 14, 18 ], [ 2, 12, 17, 21 ], 
      [ 2, 13, 19, 20 ], [ 2, 13, 19, 20 ], [ 2, 13, 19, 20 ], 
      [ 3, 4, 6, 17 ], [ 3, 4, 6, 17 ], [ 3, 4, 6, 17 ], [ 3, 7, 11, 15 ], 
      [ 3, 7, 11, 19 ], [ 3, 7, 15, 19 ], [ 3, 8, 13, 18 ], [ 3, 8, 13, 21 ], 
      [ 3, 8, 18, 21 ], [ 3, 9, 10, 12 ], [ 3, 9, 10, 12 ], [ 3, 9, 10, 12 ], 
      [ 3, 11, 15, 19 ], [ 3, 13, 18, 21 ], [ 4, 5, 7, 18 ], [ 4, 5, 7, 18 ], 
      [ 4, 5, 7, 18 ], [ 4, 8, 12, 16 ], [ 4, 8, 12, 20 ], [ 4, 8, 16, 20 ], 
      [ 4, 9, 14, 19 ], [ 4, 9, 14, 21 ], [ 4, 9, 19, 21 ], [ 4, 10, 11, 13 ],
      [ 4, 10, 11, 13 ], [ 4, 10, 11, 13 ], [ 4, 12, 16, 20 ], 
      [ 4, 14, 19, 21 ], [ 5, 6, 8, 19 ], [ 5, 6, 8, 19 ], [ 5, 6, 8, 19 ], 
      [ 5, 9, 13, 17 ], [ 5, 10, 15, 20 ], [ 5, 10, 15, 21 ], 
      [ 5, 10, 20, 21 ], [ 5, 11, 12, 14 ], [ 5, 11, 12, 14 ], 
      [ 5, 11, 12, 14 ], [ 5, 15, 20, 21 ], [ 6, 7, 9, 20 ], [ 6, 7, 9, 20 ], 
      [ 6, 7, 9, 20 ], [ 6, 10, 14, 18 ], [ 6, 11, 16, 21 ], 
      [ 6, 12, 13, 15 ], [ 6, 12, 13, 15 ], [ 6, 12, 13, 15 ], 
      [ 7, 11, 15, 19 ], [ 7, 12, 17, 21 ], [ 7, 13, 14, 16 ], 
      [ 7, 13, 14, 16 ], [ 7, 13, 14, 16 ], [ 8, 12, 16, 20 ], 
      [ 8, 13, 18, 21 ], [ 8, 14, 15, 17 ], [ 8, 14, 15, 17 ], 
      [ 8, 14, 15, 17 ], [ 9, 14, 19, 21 ], [ 9, 15, 16, 18 ], 
      [ 9, 15, 16, 18 ], [ 9, 15, 16, 18 ], [ 10, 15, 20, 21 ], 
      [ 10, 16, 17, 19 ], [ 10, 16, 17, 19 ], [ 10, 16, 17, 19 ], 
      [ 11, 17, 18, 20 ], [ 11, 17, 18, 20 ], [ 11, 17, 18, 20 ] ],
  autGroup := Group( [ ( 2,14,10,18)( 3, 7,19,15)( 4,20, 8,12)( 5,13,17, 9), 
      ( 1,17, 5, 9)( 2,10,14, 6)( 4,16,12,20)( 7,15,19,11), 
      ( 1,18,19,12)( 2,11, 8, 9)( 3, 4,17, 6)( 5,10,15,20)( 7,16,13,14) ] ),
  blockSizes := [ 4 ],
  isBinary := true,
  allTDesignLambdas := [ 105, 20, 3 ],
  isSimple := false )
\endexample