% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}

\usepackage[top=37mm,bottom=37mm,left=27mm,right=27mm]{geometry}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{FireBrick}{rgb}{0.5812,0.0074,0.0083}
\definecolor{RoyalBlue}{rgb}{0.0236,0.0894,0.6179}
\definecolor{RoyalGreen}{rgb}{0.0236,0.6179,0.0894}
\definecolor{RoyalRed}{rgb}{0.6179,0.0236,0.0894}
\definecolor{LightBlue}{rgb}{0.8544,0.9511,1.0000}
\definecolor{Black}{rgb}{0.0,0.0,0.0}

\definecolor{linkColor}{rgb}{0.0,0.0,0.554}
\definecolor{citeColor}{rgb}{0.0,0.0,0.554}
\definecolor{fileColor}{rgb}{0.0,0.0,0.554}
\definecolor{urlColor}{rgb}{0.0,0.0,0.554}
\definecolor{promptColor}{rgb}{0.0,0.0,0.589}
\definecolor{brkpromptColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapinputColor}{rgb}{0.589,0.0,0.0}
\definecolor{gapoutputColor}{rgb}{0.0,0.0,0.0}

%%  for a long time these were red and blue by default,
%%  now black, but keep variables to overwrite
\definecolor{FuncColor}{rgb}{0.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,0.0}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}


\usepackage{fancyvrb}

\usepackage{mathptmx,helvet}
\usepackage[T1]{fontenc}
\usepackage{textcomp}


\usepackage[
            pdftex=true,
            bookmarks=true,        
            a4paper=true,
            pdftitle={Written with GAPDoc},
            pdfcreator={LaTeX with hyperref package / GAPDoc},
            colorlinks=true,
            backref=page,
            breaklinks=true,
            linkcolor=linkColor,
            citecolor=citeColor,
            filecolor=fileColor,
            urlcolor=urlColor,
            pdfpagemode={UseNone}, 
           ]{hyperref}

\newcommand{\maintitlesize}{\fontsize{50}{55}\selectfont}

% write page numbers to a .pnr log file for online help
\newwrite\pagenrlog
\immediate\openout\pagenrlog =\jobname.pnr
\immediate\write\pagenrlog{PAGENRS := [}
\newcommand{\logpage}[1]{\protect\write\pagenrlog{#1, \thepage,}}
%% were never documented, give conflicts with some additional packages

\newcommand{\GAP}{\textsf{GAP}}

%% nicer description environments, allows long labels
\usepackage{enumitem}
\setdescription{style=nextline}

%% depth of toc
\setcounter{tocdepth}{1}





%% command for ColorPrompt style examples
\newcommand{\gapprompt}[1]{\color{promptColor}{\bfseries #1}}
\newcommand{\gapbrkprompt}[1]{\color{brkpromptColor}{\bfseries #1}}
\newcommand{\gapinput}[1]{\color{gapinputColor}{#1}}


\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\mbox{}\vfill

\begin{center}{\maintitlesize \textbf{ utils \mbox{}}}\\
\vfill

\hypersetup{pdftitle= utils }
\markright{\scriptsize \mbox{}\hfill  utils  \hfill\mbox{}}
{\Huge \textbf{ Utility functions in \textsf{GAP} \mbox{}}}\\
\vfill

{\Huge  0.93 \mbox{}}\\[1cm]
{ 13 November 2025 \mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{ Thomas Breuer\\
   \mbox{}}}\\
{\Large \textbf{ Sebastian Gutsche\\
   \mbox{}}}\\
{\Large \textbf{ Max Horn\\
   \mbox{}}}\\
{\Large \textbf{ Alexander Hulpke\\
   \mbox{}}}\\
{\Large \textbf{ Pedro Garc{\a'\i}a\texttt{\symbol{45}}S{\a'a}nchez\\
   \mbox{}}}\\
{\Large \textbf{ Christopher Jefferson\\
   \mbox{}}}\\
{\Large \textbf{ Stefan Kohl\\
   \mbox{}}}\\
{\Large \textbf{ Frank L{\"u}beck\\
   \mbox{}}}\\
{\Large \textbf{ Chris Wensley\\
   \mbox{}}}\\
\hypersetup{pdfauthor= Thomas Breuer\\
   ;  Sebastian Gutsche\\
   ;  Max Horn\\
   ;  Alexander Hulpke\\
   ;  Pedro Garc{\a'\i}a\texttt{\symbol{45}}S{\a'a}nchez\\
   ;  Christopher Jefferson\\
   ;  Stefan Kohl\\
   ;  Frank L{\"u}beck\\
   ;  Chris Wensley\\
   }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Thomas Breuer\\
   }  Email: \href{mailto://sam@math.rwth-aachen.de} {\texttt{sam@math.rwth\texttt{\symbol{45}}aachen.de}}\\
  Homepage: \href{https://www.math.rwth-aachen.de/~Thomas.Breuer} {\texttt{https://www.math.rwth\texttt{\symbol{45}}aachen.de/\texttt{\symbol{126}}Thomas.Breuer}}}\\
{\mbox{}\\
\small \noindent \textbf{ Sebastian Gutsche\\
   }  Email: \href{mailto://gutsche@mathematik.uni-siegen.de} {\texttt{gutsche@mathematik.uni\texttt{\symbol{45}}siegen.de}}\\
  Homepage: \href{https://sebasguts.github.io/} {\texttt{https://sebasguts.github.io/}}}\\
{\mbox{}\\
\small \noindent \textbf{ Max Horn\\
   }  Email: \href{mailto://mhorn@rptu.de} {\texttt{mhorn@rptu.de}}\\
  Homepage: \href{https://github.com/mhorn} {\texttt{https://github.com/mhorn}}}\\
{\mbox{}\\
\small \noindent \textbf{ Alexander Hulpke\\
   }  Email: \href{mailto://hulpke@math.colostate.edu} {\texttt{hulpke@math.colostate.edu}}\\
  Homepage: \href{https://www.math.colostate.edu/~hulpke} {\texttt{https://www.math.colostate.edu/\texttt{\symbol{126}}hulpke}}}\\
{\mbox{}\\
\small \noindent \textbf{ Pedro Garc{\a'\i}a\texttt{\symbol{45}}S{\a'a}nchez\\
   }  Email: \href{mailto://pedro@ugr.es} {\texttt{pedro@ugr.es}}\\
  Homepage: \href{http://www.ugr.es/local/pedro} {\texttt{http://www.ugr.es/local/pedro}}}\\
{\mbox{}\\
\small \noindent \textbf{ Christopher Jefferson\\
   }  Email: \href{mailto://caj21@st-andrews.ac.uk} {\texttt{caj21@st\texttt{\symbol{45}}andrews.ac.uk}}\\
  Homepage: \href{https://caj.host.cs.st-andrews.ac.uk/} {\texttt{https://caj.host.cs.st\texttt{\symbol{45}}andrews.ac.uk/}}}\\
{\mbox{}\\
\small \noindent \textbf{ Stefan Kohl\\
   }  Email: \href{mailto://stefan@mcs.st-and.ac.uk} {\texttt{stefan@mcs.st\texttt{\symbol{45}}and.ac.uk}}\\
  Homepage: \href{https://www.gap-system.org/DevelopersPages/StefanKohl/} {\texttt{https://www.gap\texttt{\symbol{45}}system.org/DevelopersPages/StefanKohl/}}}\\
{\mbox{}\\
\small \noindent \textbf{ Frank L{\"u}beck\\
   }  Email: \href{mailto://Frank.Luebeck@Math.RWTH-Aachen.De} {\texttt{Frank.Luebeck@Math.RWTH\texttt{\symbol{45}}Aachen.De}}\\
  Homepage: \href{https://www.math.rwth-aachen.de/~Frank.Luebeck} {\texttt{https://www.math.rwth\texttt{\symbol{45}}aachen.de/\texttt{\symbol{126}}Frank.Luebeck}}}\\
{\mbox{}\\
\small \noindent \textbf{ Chris Wensley\\
   }  Email: \href{mailto://cdwensley.maths@btinternet.com} {\texttt{cdwensley.maths@btinternet.com}}\\
  Homepage: \href{https://github.com/cdwensley} {\texttt{https://github.com/cdwensley}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
 The \textsf{Utils} package provides a space for utility functions in a variety of \textsf{GAP} packages to be collected together into a single package. In this way it is
hoped that they will become more visible to package authors. 

 Any package author who transfers a function to \textsf{Utils} will become an author of \textsf{Utils}. 

 If deemed appropriate, functions may also be transferred from the main
library. 

 Bug reports, suggestions and comments are, of course, welcome. Please contact
the last author at \href{mailto://cdwensley.maths@btinternet.com} {\texttt{cdwensley.maths@btinternet.com}} or submit an issue at the GitHub repository \href{https://github.com/gap-packages/utils/issues/} {\texttt{https://github.com/gap\texttt{\symbol{45}}packages/utils/issues/}}. \mbox{}}\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
 {\copyright} 2015\texttt{\symbol{45}}2025, The GAP Group. 

 The \textsf{Utils} package 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. \mbox{}}\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 3 ]}
 This documentation was prepared using the \textsf{GAPDoc} \cite{GAPDoc} and \textsf{AutoDoc} \cite{AutoDoc} packages.

 The procedure used to produce new releases uses the package \textsf{GitHubPagesForGAP} \cite{GitHubPagesForGAP} and the package \textsf{ReleaseTools}.

 \mbox{}}\\[1cm]
\newpage

\def\contentsname{Contents\logpage{[ 0, 0, 4 ]}}

\tableofcontents
\newpage

         
\chapter{\textcolor{Chapter }{Introduction}}\label{chap-intro}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7DFB63A97E67C0A1}{}
{
  The \textsf{Utils} package provides a space for utility functions from a variety of \textsf{GAP} packages to be collected together into a single package. In this way it is
hoped that they will become more visible to other package authors. This
package was first distributed as part of the \textsf{GAP} 4.8.2 distribution. 

 The package is loaded with the command 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LoadPackage( "utils" ); |
  
\end{Verbatim}
 

 Functions have been transferred from the following packages: 
\begin{itemize}
\item  Conversion of a \textsf{GAP} group to a ${\sf Magma}$ output string, taken from various sources including \texttt{other.gi} in the main library. 
\end{itemize}
 

 Transfer is complete (for now) for functions from the following packages: 
\begin{itemize}
\item  \textsf{AutoDoc} \cite{AutoDoc} (with function names changed); 
\item  \textsf{ResClasses} \cite{ResClasses}; 
\item  \textsf{RCWA} \cite{RCWA}; 
\item  \textsf{XMod} \cite{XMod}. 
\end{itemize}
 

 The package may be obtained either as a compressed \texttt{.tar} file or as a \texttt{.zip} file, \texttt{utils\texttt{\symbol{45}}version{\textunderscore}number.tar.gz}, by ftp from one of the following sites: 
\begin{itemize}
\item  the \textsf{Utils} GitHub release site: \href{https://gap-packages.github.io/utils/} {\texttt{https://gap\texttt{\symbol{45}}packages.github.io/utils/}}. 
\item  any \textsf{GAP} archive, e.g. \href{https://www.gap-system.org/Packages/packages.html} {\texttt{https://www.gap\texttt{\symbol{45}}system.org/Packages/packages.html}}; 
\end{itemize}
 \index{GitHub repository} The package also has a GitHub repository at: \href{https://github.com/gap-packages/utils} {\texttt{https://github.com/gap\texttt{\symbol{45}}packages/utils}}. 

 Once the package is loaded, the manual \texttt{doc/manual.pdf} can be found in the documentation folder. The \texttt{html} versions, with or without ${\sf MathJax}$, may be rebuilt as follows: 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ReadPackage( "utils", "makedoc.g" ); |
  
\end{Verbatim}
 

 It is possible to check that the package has been installed correctly by
running the test files (which terminates the \textsf{GAP} session): 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ReadPackage( "utils", "tst/testall.g" );|
  Architecture: . . . . . 
  testing: . . . . . 
  . . . 
  #I  No errors detected while testing
  
\end{Verbatim}
 

 Note that functions listed in this manual that are currently in the process of
being transferred are only read from the source package \textsf{Home} (say), and so can only be used if \textsf{Home} has already been loaded. There are no such functions in transition at present. 
\section{\textcolor{Chapter }{Information for package authors}}\label{sect-author-info}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X8508AD637B79CEE8}{}
{
  A function (or collection of functions) is suitable for transfer from a
package \textsf{Home} to \textsf{Utils} if the following conditions are satisfied. 
\begin{itemize}
\item  The function is sufficiently non\texttt{\symbol{45}}specialised so that it
might be of use to other authors. 
\item  The function does not depend on the remaining functions in \textsf{Home} 
\item  The function does not do what can already be done with a \textsf{GAP} library function. 
\item  Documentation of the function and test examples are available. 
\item  When there is more than one active author of \textsf{Home}, they should all be aware (and content) that the transfer is taking place. 
\end{itemize}
 

 Authors of packages may be reluctant to let go of their utility functions. The
following principles may help to reassure them. (Suggestions for more items
here are welcome.) 
\begin{itemize}
\item  A function that has been transferred to \textsf{Utils} will not be changed without the approval of the original author. 
\item  The current package maintainer has every intention of continuing to maintain \textsf{Utils}. In the event that this proves impossible, the \textsf{GAP} development team will surely find someone to take over. 
\item  Function names will not be changed unless specifically requested by \textsf{Home}'s author(s) or unless they have the form \texttt{HOME{\textunderscore}FunctionName}. 
\item  In order to speed up the transfer process, only functions from one package
will be in transition at any given time. Hopefully a week or two will suffice
for most packages. 
\item  Any package author who transfers a function to \textsf{Utils} will become an author of \textsf{Utils}. (In truth, \textsf{Utils} does not have \emph{authors}, just a large number of \emph{contributors}.) 
\end{itemize}
 

 The process for transferring utility functions from \textsf{Home} to \textsf{Utils} is described in Chapter \ref{chap-transfer}. }

 }

         
\chapter{\textcolor{Chapter }{Printing Lists and Iterators}}\label{chap-print}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X83686EE47E4D4F66}{}
{
  
\section{\textcolor{Chapter }{Printing selected items}}\label{sec-print-select}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X7F6817927F86240F}{}
{
  The functions described here print lists or objects with an iterator with one
item per line, either the whole list/iterator or certain subsets: 
\begin{itemize}
\item  by giving a list of positions of items to be printed, or 
\item  by specifying a first item and then a regular step. 
\end{itemize}
 

\subsection{\textcolor{Chapter }{PrintSelection (for a list of positions)}}
\logpage{[ 2, 1, 1 ]}\nobreak
\hyperdef{L}{X784638AC84D49870}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrintSelection({\mdseries\slshape obj, list})\index{PrintSelection@\texttt{PrintSelection}!for a list of positions}
\label{PrintSelection:for a list of positions}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrintSelection({\mdseries\slshape obj, first, step[, last]})\index{PrintSelection@\texttt{PrintSelection}!for a first item and a step}
\label{PrintSelection:for a first item and a step}
}\hfill{\scriptsize (function)}}\\


 This function, given three (or four) parameters, calls operations \texttt{PrintSelectionFromList} or \texttt{PrintSelectionFromIterator} which prints the \emph{first} item specified, and then the item at every \emph{step}. The fourth parameter is essential when the object being printed is infinite. 

 Alternatively, given two parameters, with the second parameter a list \texttt{L} of positive integers, only the items at positions in \texttt{L} are printed. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@L := List( [1..20], n -> n^5 );;|
  !gapprompt@gap>| !gapinput@PrintSelection( L, [18..20] );|
  18 : 1889568
  19 : 2476099
  20 : 3200000
  !gapprompt@gap>| !gapinput@PrintSelection( L, 2, 9 );       |
  2 : 32
  11 : 161051
  20 : 3200000
  !gapprompt@gap>| !gapinput@PrintSelection( L, 2, 3, 11 );|
  2 : 32
  5 : 3125
  8 : 32768
  11 : 161051
  !gapprompt@gap>| !gapinput@s5 := SymmetricGroup( 5 );;|
  !gapprompt@gap>| !gapinput@PrintSelection( s5, [30,31,100,101] );|
  30 : (1,5)(3,4)
  31 : (1,5,2)
  100 : (1,4,3)
  101 : (1,4)(3,5)
  !gapprompt@gap>| !gapinput@PrintSelection( s5, 1, 30 );|
  1 : ()
  31 : (1,5,2)
  61 : (1,2,3)
  91 : (1,3,5,2,4)
  !gapprompt@gap>| !gapinput@PrintSelection( s5, 9, 11, 43 );|
  9 : (2,5,3)
  20 : (2,4)
  31 : (1,5,2)
  42 : (1,5,2,3,4)
  
\end{Verbatim}
 }

 }

         
\chapter{\textcolor{Chapter }{Lists, Sets and Strings}}\label{chap-lists}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X7AE6EFC086C0EB3C}{}
{
  
\section{\textcolor{Chapter }{Functions for lists}}\label{sec-lists}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X7C3F1E7D878AAA65}{}
{
  

\subsection{\textcolor{Chapter }{DifferencesList}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X78B7C92681D2F13C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DifferencesList({\mdseries\slshape L})\index{DifferencesList@\texttt{DifferencesList}}
\label{DifferencesList}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{ResClasses}. 

 It takes a list $L$ of length $n$ and outputs the list of length $n-1$ containing all the differences $L[i]-L[i-1]$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List( [1..12], n->n^3 );|
  [ 1, 8, 27, 64, 125, 216, 343, 512, 729, 1000, 1331, 1728 ]
  !gapprompt@gap>| !gapinput@DifferencesList( last );|
  [ 7, 19, 37, 61, 91, 127, 169, 217, 271, 331, 397 ]
  !gapprompt@gap>| !gapinput@DifferencesList( last );|
  [ 12, 18, 24, 30, 36, 42, 48, 54, 60, 66 ]
  !gapprompt@gap>| !gapinput@DifferencesList( last );|
  [ 6, 6, 6, 6, 6, 6, 6, 6, 6 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{QuotientsList}}
\logpage{[ 3, 1, 2 ]}\nobreak
\hyperdef{L}{X7975371E865B89BC}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{QuotientsList({\mdseries\slshape L})\index{QuotientsList@\texttt{QuotientsList}}
\label{QuotientsList}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FloatQuotientsList({\mdseries\slshape L})\index{FloatQuotientsList@\texttt{FloatQuotientsList}}
\label{FloatQuotientsList}
}\hfill{\scriptsize (function)}}\\


 These functions have been transferred from package \textsf{ResClasses}. 

 They take a list $L$ of length $n$ and output the quotients $L[i]/L[i-1]$ of consecutive entries in $L$. An error is returned if an entry is zero. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@List( [0..10], n -> Factorial(n) );|
  [ 1, 1, 2, 6, 24, 120, 720, 5040, 40320, 362880, 3628800 ]
  !gapprompt@gap>| !gapinput@QuotientsList( last );|
  [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
  !gapprompt@gap>| !gapinput@L := [ 1, 3, 5, -1, -3, -5 ];;|
  !gapprompt@gap>| !gapinput@QuotientsList( L );|
  [ 3, 5/3, -1/5, 3, 5/3 ]
  !gapprompt@gap>| !gapinput@FloatQuotientsList( L );|
  [ 3., 1.66667, -0.2, 3., 1.66667 ]
  !gapprompt@gap>| !gapinput@QuotientsList( [ 2, 1, 0, -1, -2 ] );|
  [ 1/2, 0, fail, 2 ]
  !gapprompt@gap>| !gapinput@FloatQuotientsList( [1..10] );|
  [ 2., 1.5, 1.33333, 1.25, 1.2, 1.16667, 1.14286, 1.125, 1.11111 ]
  !gapprompt@gap>| !gapinput@Product( last );|
  10. 
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{SearchCycle}}
\logpage{[ 3, 1, 3 ]}\nobreak
\hyperdef{L}{X86096E73858CFABD}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SearchCycle({\mdseries\slshape L})\index{SearchCycle@\texttt{SearchCycle}}
\label{SearchCycle}
}\hfill{\scriptsize (operation)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 \texttt{SearchCycle} is a tool to find likely cycles in lists. What, precisely, a \emph{cycle} is, is deliberately fuzzy here, and may possibly even change. The idea is that
the beginning of the list may be anything, following that the same pattern
needs to be repeated several times in order to be recognized as a cycle. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@L := [1..20];;  L[1]:=13;;                                              |
  !gapprompt@gap>| !gapinput@for i in [1..19] do                                                     |
  !gapprompt@>| !gapinput@       if IsOddInt(L[i]) then L[i+1]:=3*L[i]+1; else L[i+1]:=L[i]/2; fi;|
  !gapprompt@>| !gapinput@   od;                                                                  |
  !gapprompt@gap>| !gapinput@L;                                                                      |
  [ 13, 40, 20, 10, 5, 16, 8, 4, 2, 1, 4, 2, 1, 4, 2, 1, 4, 2, 1, 4 ]
  !gapprompt@gap>| !gapinput@SearchCycle( L );                                                       |
  [ 1, 4, 2 ]
  !gapprompt@gap>| !gapinput@n := 1;;  L := [n];;|
  !gapprompt@gap>| !gapinput@for i in [1..100] do  n:=(n^2+1) mod 1093;  Add(L,n);  od;|
  !gapprompt@gap>| !gapinput@L; |
  [ 1, 2, 5, 26, 677, 363, 610, 481, 739, 715, 795, 272, 754, 157, 604, 848, 
    1004, 271, 211, 802, 521, 378, 795, 272, 754, 157, 604, 848, 1004, 271, 
    211, 802, 521, 378, 795, 272, 754, 157, 604, 848, 1004, 271, 211, 802, 521, 
    378, 795, 272, 754, 157, 604, 848, 1004, 271, 211, 802, 521, 378, 795, 272, 
    754, 157, 604, 848, 1004, 271, 211, 802, 521, 378, 795, 272, 754, 157, 604, 
    848, 1004, 271, 211, 802, 521, 378, 795, 272, 754, 157, 604, 848, 1004, 
    271, 211, 802, 521, 378, 795, 272, 754, 157, 604, 848, 1004 ]
  !gapprompt@gap>| !gapinput@C := SearchCycle( L );|
  [ 157, 604, 848, 1004, 271, 211, 802, 521, 378, 795, 272, 754 ]
  !gapprompt@gap>| !gapinput@P := Positions( L, 157 );|
  [ 14, 26, 38, 50, 62, 74, 86, 98 ]
  !gapprompt@gap>| !gapinput@Length( C );  DifferencesList( P );|
  12
  [ 12, 12, 12, 12, 12, 12, 12 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{RandomCombination}}
\logpage{[ 3, 1, 4 ]}\nobreak
\hyperdef{L}{X7EF06CAD7F35245D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RandomCombination({\mdseries\slshape S, k})\index{RandomCombination@\texttt{RandomCombination}}
\label{RandomCombination}
}\hfill{\scriptsize (operation)}}\\


 This function has been transferred from package \textsf{ResClasses}. 

 It returns a random unordered $k$\texttt{\symbol{45}}tuple of distinct elements of a set{\nobreakspace}$S$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@## "6 aus 49" is a common lottery in Germany|
  !gapprompt@gap>| !gapinput@RandomCombination( [1..49], 6 ); |
  [ 2, 16, 24, 26, 37, 47 ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Distinct and Common Representatives}}\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X82F443FF84B8FCE3}{}
{
 \index{distinct and common representatives} 

\subsection{\textcolor{Chapter }{DistinctRepresentatives}}
\logpage{[ 3, 2, 1 ]}\nobreak
\hyperdef{L}{X78105CAA847A888C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DistinctRepresentatives({\mdseries\slshape list})\index{DistinctRepresentatives@\texttt{DistinctRepresentatives}}
\label{DistinctRepresentatives}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CommonRepresentatives({\mdseries\slshape list})\index{CommonRepresentatives@\texttt{CommonRepresentatives}}
\label{CommonRepresentatives}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CommonTransversal({\mdseries\slshape grp, subgrp})\index{CommonTransversal@\texttt{CommonTransversal}}
\label{CommonTransversal}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsCommonTransversal({\mdseries\slshape grp, subgrp, list})\index{IsCommonTransversal@\texttt{IsCommonTransversal}}
\label{IsCommonTransversal}
}\hfill{\scriptsize (operation)}}\\


 These operations have been transferred from package \textsf{XMod}. 

 They deal with lists of subsets of $[1 \ldots n]$ and construct systems of distinct and common representatives using simple,
non\texttt{\symbol{45}}recursive, combinatorial algorithms. 

 When $L$ is a set of $n$ subsets of $[1 \ldots n]$ and the Hall condition is satisfied (the union of any $k$ subsets has at least $k$ elements), a set of \texttt{DistinctRepresentatives} exists. 

 When $J,K$ are both lists of $n$ sets, the operation \texttt{CommonRepresentatives} returns two lists: the set of representatives, and a permutation of the
subsets of the second list. 

 The operation \texttt{CommonTransversal} may be used to provide a common transversal for the sets of left and right
cosets of a subgroup $H$ of a group $G$, although a greedy algorithm is usually quicker. }

 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@J := [ [1,2,3], [3,4], [3,4], [1,2,4] ];;|
  !gapprompt@gap>| !gapinput@DistinctRepresentatives( J );|
  [ 1, 3, 4, 2 ]
  !gapprompt@gap>| !gapinput@K := [ [3,4], [1,2], [2,3], [2,3,4] ];;|
  !gapprompt@gap>| !gapinput@CommonRepresentatives( J, K );|
  [ [ 3, 3, 3, 1 ], [ 1, 3, 4, 2 ] ]
  !gapprompt@gap>| !gapinput@d16 := DihedralGroup( IsPermGroup, 16 ); |
  Group([ (1,2,3,4,5,6,7,8), (2,8)(3,7)(4,6) ])
  !gapprompt@gap>| !gapinput@SetName( d16, "d16" );|
  !gapprompt@gap>| !gapinput@c4 := Subgroup( d16, [ d16.1^2 ] ); |
  Group([ (1,3,5,7)(2,4,6,8) ])
  !gapprompt@gap>| !gapinput@SetName( c4, "c4" );|
  !gapprompt@gap>| !gapinput@RightCosets( d16, c4 );|
  [ RightCoset(c4,()), RightCoset(c4,(2,8)(3,7)(4,6)), RightCoset(c4,(1,8,7,6,5,
     4,3,2)), RightCoset(c4,(1,8)(2,7)(3,6)(4,5)) ]
  !gapprompt@gap>| !gapinput@trans := CommonTransversal( d16, c4 );|
  [ (), (2,8)(3,7)(4,6), (1,2,3,4,5,6,7,8), (1,2)(3,8)(4,7)(5,6) ]
  !gapprompt@gap>| !gapinput@IsCommonTransversal( d16, c4, trans );|
  true
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Functions for strings}}\label{sec-strings}
\logpage{[ 3, 3, 0 ]}
\hyperdef{L}{X8033A2FE80FC2F2A}{}
{
  

\subsection{\textcolor{Chapter }{BlankFreeString}}
\logpage{[ 3, 3, 1 ]}\nobreak
\hyperdef{L}{X870C964E7804B266}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{BlankFreeString({\mdseries\slshape obj})\index{BlankFreeString@\texttt{BlankFreeString}}
\label{BlankFreeString}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{ResClasses}. 

 The result of \texttt{BlankFreeString( obj );} is a composite of the functions \texttt{String( obj )} and \texttt{RemoveCharacters( obj, " " );}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@gens := GeneratorsOfGroup( DihedralGroup(12) );|
  [ f1, f2, f3 ]
  !gapprompt@gap>| !gapinput@String( gens );                                |
  "[ f1, f2, f3 ]"
  !gapprompt@gap>| !gapinput@BlankFreeString( gens );                       |
  "[f1,f2,f3]"
  
\end{Verbatim}
 }

 }

         
\chapter{\textcolor{Chapter }{Number\texttt{\symbol{45}}theoretic functions}}\label{chap-number}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X86E71C1687F2D0AD}{}
{
  
\section{\textcolor{Chapter }{Functions for integers}}\label{sec-integers}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X7D33B5B17BF785CA}{}
{
  

\subsection{\textcolor{Chapter }{AllSmoothIntegers (for two integers)}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X8191A031788AC7C0}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllSmoothIntegers({\mdseries\slshape maxp, maxn})\index{AllSmoothIntegers@\texttt{AllSmoothIntegers}!for two integers}
\label{AllSmoothIntegers:for two integers}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllSmoothIntegers({\mdseries\slshape L, maxp})\index{AllSmoothIntegers@\texttt{AllSmoothIntegers}!for a list and an integer}
\label{AllSmoothIntegers:for a list and an integer}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 \index{smooth integer} The function \texttt{AllSmoothIntegers(\mbox{\texttt{\mdseries\slshape maxp}},\mbox{\texttt{\mdseries\slshape maxn}})} returns the list of all positive integers less than or equal to \mbox{\texttt{\mdseries\slshape maxn}} whose prime factors are all in the list $L = \{p ~|~ p \leqslant maxp, p~\mbox{prime} \}$. 

 In the alternative form, when $L$ is a list of primes, the function returns the list of all positive integers
whose prime factors lie in $L$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@AllSmoothIntegers( 3, 1000 );|
  [ 1, 2, 3, 4, 6, 8, 9, 12, 16, 18, 24, 27, 32, 36, 48, 54, 64, 72, 81, 96, 
    108, 128, 144, 162, 192, 216, 243, 256, 288, 324, 384, 432, 486, 512, 576, 
    648, 729, 768, 864, 972 ]
  !gapprompt@gap>| !gapinput@AllSmoothIntegers( [5,11,17], 1000 );|
  [ 1, 5, 11, 17, 25, 55, 85, 121, 125, 187, 275, 289, 425, 605, 625, 935 ]
  !gapprompt@gap>| !gapinput@Length( last );|
  16
  !gapprompt@gap>| !gapinput@List( [3..20], n -> Length( AllSmoothIntegers( [5,11,17], 10^n ) ) );|
  [ 16, 29, 50, 78, 114, 155, 212, 282, 359, 452, 565, 691, 831, 992, 1173, 
    1374, 1595, 1843 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{AllProducts}}
\logpage{[ 4, 1, 2 ]}\nobreak
\hyperdef{L}{X78BE6B8B878D250D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllProducts({\mdseries\slshape L, k})\index{AllProducts@\texttt{AllProducts}}
\label{AllProducts}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 The command \texttt{AllProducts(\mbox{\texttt{\mdseries\slshape L}},\mbox{\texttt{\mdseries\slshape k}})} returns the list of all products of \mbox{\texttt{\mdseries\slshape k}} entries of the list{\nobreakspace}\mbox{\texttt{\mdseries\slshape L}}. Note that every ordering of the entries is used so that, in the commuting
case, there are bound to be repetitions. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@AllProducts([1..4],3); |
  [ 1, 2, 3, 4, 2, 4, 6, 8, 3, 6, 9, 12, 4, 8, 12, 16, 2, 4, 6, 8, 4, 8, 12, 
    16, 6, 12, 18, 24, 8, 16, 24, 32, 3, 6, 9, 12, 6, 12, 18, 24, 9, 18, 27, 
    36, 12, 24, 36, 48, 4, 8, 12, 16, 8, 16, 24, 32, 12, 24, 36, 48, 16, 32, 
    48, 64 ]
  !gapprompt@gap>| !gapinput@Set(last);            |
  [ 1, 2, 3, 4, 6, 8, 9, 12, 16, 18, 24, 27, 32, 36, 48, 64 ]
  !gapprompt@gap>| !gapinput@AllProducts( [(1,2,3),(2,3,4)], 2 );|
  [ (2,4,3), (1,2)(3,4), (1,3)(2,4), (1,3,2) ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{RestrictedPartitionsWithoutRepetitions}}
\logpage{[ 4, 1, 3 ]}\nobreak
\hyperdef{L}{X845F46E579CEA43F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RestrictedPartitionsWithoutRepetitions({\mdseries\slshape n, S})\index{RestrictedPartitionsWithoutRepetitions@\texttt{Restricted}\-\texttt{Partitions}\-\texttt{Without}\-\texttt{Repetitions}}
\label{RestrictedPartitionsWithoutRepetitions}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 For a positive integer \mbox{\texttt{\mdseries\slshape n}} and a set of positive integers \mbox{\texttt{\mdseries\slshape S}}, this function returns the list of partitions of \mbox{\texttt{\mdseries\slshape n}} into distinct elements of \mbox{\texttt{\mdseries\slshape S}}. Unlike \texttt{RestrictedPartitions}, no repetitions are allowed. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@RestrictedPartitions( 20, [4..10] );|
  [ [ 4, 4, 4, 4, 4 ], [ 5, 5, 5, 5 ], [ 6, 5, 5, 4 ], [ 6, 6, 4, 4 ], 
    [ 7, 5, 4, 4 ], [ 7, 7, 6 ], [ 8, 4, 4, 4 ], [ 8, 6, 6 ], [ 8, 7, 5 ], 
    [ 8, 8, 4 ], [ 9, 6, 5 ], [ 9, 7, 4 ], [ 10, 5, 5 ], [ 10, 6, 4 ], 
    [ 10, 10 ] ]
  !gapprompt@gap>| !gapinput@RestrictedPartitionsWithoutRepetitions( 20, [4..10] );|
  [ [ 10, 6, 4 ], [ 9, 7, 4 ], [ 9, 6, 5 ], [ 8, 7, 5 ] ]
  !gapprompt@gap>| !gapinput@RestrictedPartitionsWithoutRepetitions( 10^2, List([1..10], n->n^2 ) );|
  [ [ 100 ], [ 64, 36 ], [ 49, 25, 16, 9, 1 ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{NextProbablyPrimeInt}}
\logpage{[ 4, 1, 4 ]}\nobreak
\hyperdef{L}{X81708BF4858505E8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{NextProbablyPrimeInt({\mdseries\slshape n})\index{NextProbablyPrimeInt@\texttt{NextProbablyPrimeInt}}
\label{NextProbablyPrimeInt}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 The function \texttt{NextProbablyPrimeInt(\mbox{\texttt{\mdseries\slshape n}})} does the same as \texttt{NextPrimeInt(\mbox{\texttt{\mdseries\slshape n}})} except that for reasons of performance it tests numbers only for \texttt{IsProbablyPrimeInt(\mbox{\texttt{\mdseries\slshape n}})} instead of \texttt{IsPrimeInt(\mbox{\texttt{\mdseries\slshape n}})}. For large \mbox{\texttt{\mdseries\slshape n}}, this function is much faster than \texttt{NextPrimeInt(\mbox{\texttt{\mdseries\slshape n}})} 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@n := 2^251;|
  3618502788666131106986593281521497120414687020801267626233049500247285301248
  !gapprompt@gap>| !gapinput@NextProbablyPrimeInt( n );|
  3618502788666131106986593281521497120414687020801267626233049500247285301313
  !gapprompt@gap>| !gapinput@time;                     |
  1
  !gapprompt@gap>| !gapinput@NextPrimeInt( n );        |
  3618502788666131106986593281521497120414687020801267626233049500247285301313
  !gapprompt@gap>| !gapinput@time;             |
  213
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{PrimeNumbersIterator}}
\logpage{[ 4, 1, 5 ]}\nobreak
\hyperdef{L}{X8021EEE5787FCA37}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PrimeNumbersIterator({\mdseries\slshape [chunksize]})\index{PrimeNumbersIterator@\texttt{PrimeNumbersIterator}}
\label{PrimeNumbersIterator}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 This function returns an iterator which runs over the prime numbers n
ascending order; it takes an optional argument \texttt{chunksize} which specifies the length of the interval which is sieved in one go (the
default is $10^7$), and which can be used to balance runtime vs. memory consumption. It is
assumed that \texttt{chunksize} is larger than any gap between two consecutive primes within the range one
intends to run the iterator over. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@iter := PrimeNumbersIterator();;|
  !gapprompt@gap>| !gapinput@for i in [1..100] do  p := NextIterator(iter);  od;|
  !gapprompt@gap>| !gapinput@p;|
  541
  !gapprompt@gap>| !gapinput@sum := 0;;|
  !gapprompt@gap>| !gapinput@## "prime number race" 1 vs. 3 mod 4|
  !gapprompt@gap>| !gapinput@for p in PrimeNumbersIterator() do |
  !gapprompt@>| !gapinput@      if p <> 2 then sum := sum + E(4)^(p-1); fi;|
  !gapprompt@>| !gapinput@      if sum > 0 then break; fi;|
  !gapprompt@>| !gapinput@   od;|
  !gapprompt@gap>| !gapinput@p;|
  26861
  
\end{Verbatim}
 }

 }

         
\chapter{\textcolor{Chapter }{Groups and homomorphisms}}\label{chap-groups}
\logpage{[ 5, 0, 0 ]}
\hyperdef{L}{X8171DAF2833FF728}{}
{
  
\section{\textcolor{Chapter }{Functions for groups}}\label{sec-groups}
\logpage{[ 5, 1, 0 ]}
\hyperdef{L}{X7E21E6D285E6B12C}{}
{
  

\subsection{\textcolor{Chapter }{Comm}}
\logpage{[ 5, 1, 1 ]}\nobreak
\hyperdef{L}{X80761843831B468E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Comm({\mdseries\slshape L})\index{Comm@\texttt{Comm}}
\label{Comm}
}\hfill{\scriptsize (operation)}}\\


 This method has been transferred from package \textsf{ResClasses}. 

 It provides a method for \texttt{Comm} when the argument is a list (enclosed in square brackets), and calls the
function \texttt{LeftNormedComm}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Comm( [ (1,2), (2,3) ] );|
  (1,2,3)
  !gapprompt@gap>| !gapinput@Comm( [(1,2),(2,3),(3,4),(4,5),(5,6)] );|
  (1,5,6)
  !gapprompt@gap>| !gapinput@Comm(Comm(Comm(Comm((1,2),(2,3)),(3,4)),(4,5)),(5,6));  ## the same|
  (1,5,6)
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{IsCommuting}}
\logpage{[ 5, 1, 2 ]}\nobreak
\hyperdef{L}{X803A050C7A183CCC}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsCommuting({\mdseries\slshape a, b})\index{IsCommuting@\texttt{IsCommuting}}
\label{IsCommuting}
}\hfill{\scriptsize (operation)}}\\


 This function has been transferred from package \textsf{ResClasses}. 

 It tests whether two elements in a group commute. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@D12 := DihedralGroup( 12 );|
  <pc group of size 12 with 3 generators>
  !gapprompt@gap>| !gapinput@SetName( D12, "D12" ); |
  !gapprompt@gap>| !gapinput@a := D12.1;;  b := D12.2;;  |
  !gapprompt@gap>| !gapinput@IsCommuting( a, b );|
  false
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{ListOfPowers}}
\logpage{[ 5, 1, 3 ]}\nobreak
\hyperdef{L}{X87A8F01286548037}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ListOfPowers({\mdseries\slshape g, exp})\index{ListOfPowers@\texttt{ListOfPowers}}
\label{ListOfPowers}
}\hfill{\scriptsize (operation)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 The operation \texttt{ListOfPowers(g,exp)} returns the list $[g,g^2,...,g^{exp}]$ of powers of the element $g$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ListOfPowers( 2, 20 );|
  [ 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384,
   32768, 65536, 131072, 262144, 524288, 1048576 ]
  !gapprompt@gap>| !gapinput@ListOfPowers( (1,2,3)(4,5), 12 );|
  [ (1,2,3)(4,5), (1,3,2), (4,5), (1,2,3), (1,3,2)(4,5), (),
   (1,2,3)(4,5), (1,3,2), (4,5), (1,2,3), (1,3,2)(4,5), () ]
  !gapprompt@gap>| !gapinput@ListOfPowers( D12.2, 6 );|
  [ f2, f3, f2*f3, f3^2, f2*f3^2, <identity> of ... ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{GeneratorsAndInverses}}
\logpage{[ 5, 1, 4 ]}\nobreak
\hyperdef{L}{X820B71307E41BEE5}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{GeneratorsAndInverses({\mdseries\slshape G})\index{GeneratorsAndInverses@\texttt{GeneratorsAndInverses}}
\label{GeneratorsAndInverses}
}\hfill{\scriptsize (operation)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 This operation returns a list containing the generators of $G$ followed by the inverses of these generators. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@GeneratorsAndInverses( D12 );|
  [ f1, f2, f3, f1, f2*f3^2, f3^2 ]
  !gapprompt@gap>| !gapinput@GeneratorsAndInverses( SymmetricGroup(5) );     |
  [ (1,2,3,4,5), (1,2), (1,5,4,3,2), (1,2) ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{UpperFittingSeries}}
\logpage{[ 5, 1, 5 ]}\nobreak
\hyperdef{L}{X84CF95227F9D562F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UpperFittingSeries({\mdseries\slshape G})\index{UpperFittingSeries@\texttt{UpperFittingSeries}}
\label{UpperFittingSeries}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LowerFittingSeries({\mdseries\slshape G})\index{LowerFittingSeries@\texttt{LowerFittingSeries}}
\label{LowerFittingSeries}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{FittingLength({\mdseries\slshape G})\index{FittingLength@\texttt{FittingLength}}
\label{FittingLength}
}\hfill{\scriptsize (attribute)}}\\


 These three functions have been transferred from package \textsf{ResClasses}. 

 \index{Fitting series} The upper and lower Fitting series and the Fitting length of a solvable group
are described here: \href{https://en.wikipedia.org/wiki/Fitting_length} {\texttt{https://en.wikipedia.org/wiki/Fitting{\textunderscore}length}}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@UpperFittingSeries( D12 );  LowerFittingSeries( D12 );|
  [ Group([  ]), Group([ f3, f2*f3 ]), Group([ f1, f3, f2*f3 ]) ]
  [ D12, Group([ f3 ]), Group([  ]) ]
  !gapprompt@gap>| !gapinput@FittingLength( D12 );|
  2
  !gapprompt@gap>| !gapinput@S4 := SymmetricGroup( 4 );;|
  !gapprompt@gap>| !gapinput@UpperFittingSeries( S4 );|
  [ Group(()), Group([ (1,2)(3,4), (1,4)(2,3) ]), Group([ (1,2)(3,4), (1,4)
    (2,3), (2,4,3) ]), Group([ (3,4), (2,3,4), (1,2)(3,4) ]) ]
  !gapprompt@gap>| !gapinput@List( last, StructureDescription );|
  [ "1", "C2 x C2", "A4", "S4" ]
  !gapprompt@gap>| !gapinput@LowerFittingSeries( S4 );|
  [ Sym( [ 1 .. 4 ] ), Alt( [ 1 .. 4 ] ), Group([ (1,4)(2,3), (1,3)
   (2,4) ]), Group(()) ]
  !gapprompt@gap>| !gapinput@List( last, StructureDescription );|
  [ "S4", "A4", "C2 x C2", "1" ]
  !gapprompt@gap>| !gapinput@FittingLength( S4);|
  3
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Left Cosets for Groups}}\label{sec-leftcosets}
\logpage{[ 5, 2, 0 ]}
\hyperdef{L}{X7FE4848B7DE6B3FD}{}
{
  

\subsection{\textcolor{Chapter }{LeftCoset}}
\logpage{[ 5, 2, 1 ]}\nobreak
\hyperdef{L}{X8340B4537F17DCD3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LeftCoset({\mdseries\slshape g, U})\index{LeftCoset@\texttt{LeftCoset}}
\label{LeftCoset}
}\hfill{\scriptsize (operation)}}\\


 Since \textsf{GAP} uses right actions by default, the library contains the operation \texttt{RightCoset(U,g)} for constructing the right coset $Ug$ of a subgroup $U \leq G$ and an element $g \in G$. It has been noted in the reference manual that, by inverting all the
elements in $Ug$, the left coset $g^{-1}U$ is obtained. 

 Just for the sake of completeness, from August 2022 this package provides the
operation \texttt{LeftCoset(g,U)} for constructing the left coset $gU$. Users are strongly recommended to continue to use \texttt{RightCoset} for all serious calculations, since left cosets have a much simpler
implementation and do not behave exactly like right cosets. 

 The methods for left cosets which are provided generally work by converting $gU$ to $Ug^{-1}$; applying the equivalent method for right cosets; and, if necessary,
converting back again to left cosets. 

 $G$ acts on left cosets by \texttt{OnLeftInverse}: $(gU)^{g_0} = g_0^{-1}*(gU) = (g_0^{-1}g)U$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@a4 := Group( (1,2,3), (2,3,4) );; SetName( a4, "a4" );|
  !gapprompt@gap>| !gapinput@k4 := Group( (1,2)(3,4), (1,3)(2,4) );; SetName( k4, "k4" );|
  !gapprompt@gap>| !gapinput@rc := RightCosets( a4, k4 );|
  [ RightCoset(k4,()), RightCoset(k4,(2,3,4)), RightCoset(k4,(2,4,3)) ]
  !gapprompt@gap>| !gapinput@lc := LeftCosets( a4, k4 );|
  [ LeftCoset((),k4), LeftCoset((2,4,3),k4), LeftCoset((2,3,4),k4) ]
  !gapprompt@gap>| !gapinput@AsSet( lc[2] );|
  [ (2,4,3), (1,2,3), (1,3,4), (1,4,2) ]
  !gapprompt@gap>| !gapinput@LeftCoset( (1,4,2), k4 ) = lc[2];|
  true
  !gapprompt@gap>| !gapinput@Representative( lc[2] );|
  (2,4,3)
  !gapprompt@gap>| !gapinput@ActingDomain( lc[2] );|
  k4
  !gapprompt@gap>| !gapinput@(1,4,3) in lc[3];|
  true
  !gapprompt@gap>| !gapinput@(1,2,3)*lc[2] = lc[3];|
  true
  !gapprompt@gap>| !gapinput@lc[2]^(1,3,2) = lc[3];|
  true
  
\end{Verbatim}
 
\subsection{\textcolor{Chapter }{Inverse}}\label{subsec-inverse}
\logpage{[ 5, 2, 2 ]}
\hyperdef{L}{X793E48267EF5FD77}{}
{
  The inverse of the left coset $gU$ is the right coset $Ug^{-1}$, and conversely. This is an abuse of the attribute \texttt{Inverse}, since the standard requirement, that $x*x^{-1}$ is an identity, does not hold. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Inverse( rc[3] ) = lc[3];|
  true
  !gapprompt@gap>| !gapinput@Inverse( lc[2] ) = rc[2];|
  true
  
\end{Verbatim}
 }

 }

 
\section{\textcolor{Chapter }{Functions for group homomorphisms}}\label{sec-homomorphisms}
\logpage{[ 5, 3, 0 ]}
\hyperdef{L}{X80A512877F515DE7}{}
{
  

\subsection{\textcolor{Chapter }{EpimorphismByGenerators}}
\logpage{[ 5, 3, 1 ]}\nobreak
\hyperdef{L}{X80C9A0B583FEA7B9}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{EpimorphismByGenerators({\mdseries\slshape G, H})\index{EpimorphismByGenerators@\texttt{EpimorphismByGenerators}}
\label{EpimorphismByGenerators}
}\hfill{\scriptsize (operation)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 It constructs a group homomorphism which maps the generators of $G$ to those of $H$. Its intended use is when $G$ is a free group, and a warning is printed when this is not the case. Note that
anything may happen if the resulting map is not a homomorphism! 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := Group( (1,2,3), (3,4,5), (5,6,7), (7,8,9) );;|
  !gapprompt@gap>| !gapinput@phi := EpimorphismByGenerators( FreeGroup("a","b","c","d"), G );|
  [ a, b, c, d ] -> [ (1,2,3), (3,4,5), (5,6,7), (7,8,9) ]
  !gapprompt@gap>| !gapinput@PreImagesRepresentativeNC( phi, (1,2,3,4,5,6,7,8,9) );|
  d*c*b*a
  !gapprompt@gap>| !gapinput@a := G.1;; b := G.2;; c := G.3;; d := G.4;;|
  !gapprompt@gap>| !gapinput@d*c*b*a;|
  (1,2,3,4,5,6,7,8,9)
  !gapprompt@gap>| !gapinput@## note that it is easy to produce nonsense: |
  !gapprompt@gap>| !gapinput@epi := EpimorphismByGenerators( Group((1,2,3)), Group((8,9)) );|
  Warning: calling GroupHomomorphismByImagesNC without checks
  [ (1,2,3) ] -> [ (8,9) ]
  !gapprompt@gap>| !gapinput@IsGroupHomomorphism( epi );|
  true
  !gapprompt@gap>| !gapinput@Image( epi, (1,2,3) );                                            |
  ()
  !gapprompt@gap>| !gapinput@Image( epi, (1,3,2) );|
  (8,9)
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{Pullback}}
\logpage{[ 5, 3, 2 ]}\nobreak
\hyperdef{L}{X7C705F2A79F8E43C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Pullback({\mdseries\slshape hom1, hom2})\index{Pullback@\texttt{Pullback}}
\label{Pullback}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PullbackInfo({\mdseries\slshape G})\index{PullbackInfo@\texttt{PullbackInfo}}
\label{PullbackInfo}
}\hfill{\scriptsize (attribute)}}\\


 If $\phi_1 : G_1 \to H$ and $\phi_2 : G_2 \to H$ are two group homomorphisms with the same range, then their \emph{pullback} is the subgroup of $G_1 \times G_2$ consisting of those elements $(g_1,g_2)$ such that $\phi_1 g_1 = \phi_2 g_2$. 

 The attribute \texttt{PullbackInfo} of a pullback group \texttt{P} is similar to \texttt{DirectProductInfo} for a direct product of groups. Its value is a record with the following
components: 

 
\begin{description}
\item[{\texttt{directProduct}}]  the direct product $G_1 \times G_2$, and 
\item[{\texttt{projections}}]  a list with the two projections onto $G_1$ and $G_2$. 
\end{description}
 There are no embeddings in this record, but it is possible to use the
embeddings into the direct product, see \texttt{Embedding} (\textbf{Reference: Embedding}). 

 }

 
\begin{Verbatim}[commandchars=@|C,fontsize=\small,frame=single,label=Example]
  
  @gapprompt|gap>C @gapinput|s4 := Group( (1,2),(2,3),(3,4) );;C
  @gapprompt|gap>C @gapinput|s3 := Group( (5,6),(6,7) );;C
  @gapprompt|gap>C @gapinput|c3 := Subgroup( s3, [ (5,6,7) ] );;C
  @gapprompt|gap>C @gapinput|f := GroupHomomorphismByImages( s4, s3, C
  @gapprompt|>C @gapinput|            [(1,2),(2,3),(3,4)], [(5,6),(6,7),(5,6)] );; C
  @gapprompt|gap>C @gapinput|i := GroupHomomorphismByImages( c3, s3, [(5,6,7)], [(5,6,7)] );; C
  @gapprompt|gap>C @gapinput|Pfi := Pullback( f, i );C
  Group([ (2,3,4)(5,7,6), (1,2)(3,4) ])
  @gapprompt|gap>C @gapinput|StructureDescription( Pfi );C
  "A4"
  @gapprompt|gap>C @gapinput|info := PullbackInfo( Pfi );C
  rec( directProduct := Group([ (1,2), (2,3), (3,4), (5,6,7) ]), 
    projections := [ [ (2,3,4)(5,7,6), (1,2)(3,4) ] -> [ (2,3,4), (1,2)(3,4) ], 
        [ (2,3,4)(5,7,6), (1,2)(3,4) ] -> [ (5,7,6), () ] ] )
  @gapprompt|gap>C @gapinput|g := (1,2,3)(5,6,7);; C
  @gapprompt|gap>C @gapinput|ImageElm( info!.projections[1], g );C
  (1,2,3)
  @gapprompt|gap>C @gapinput|ImageElm( info!.projections[2], g );C
  (5,6,7) 
  @gapprompt|gap>C @gapinput|dp := info!.directProduct;; C
  @gapprompt|gap>C @gapinput|a := ImageElm( Embedding( dp, 1 ), (1,4,3) );; C
  @gapprompt|gap>C @gapinput|b := ImageElm( Embedding( dp, 2 ), (5,7,6) );; C
  @gapprompt|gap>C @gapinput|a*b in Pfi;C
  true
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{CentralProduct}}
\logpage{[ 5, 3, 3 ]}\nobreak
\hyperdef{L}{X78DD2C617B992BE2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CentralProduct({\mdseries\slshape G1, G2, Z1, Phi})\index{CentralProduct@\texttt{CentralProduct}}
\label{CentralProduct}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CentralProductInfo({\mdseries\slshape G})\index{CentralProductInfo@\texttt{CentralProductInfo}}
\label{CentralProductInfo}
}\hfill{\scriptsize (attribute)}}\\


 This function was added by Thomas Breuer, following discussions with Hongyi
Zhao (see \href{https://github.com/gap-packages/hap/issues/73} {\texttt{https://github.com/gap\texttt{\symbol{45}}packages/hap/issues/73}}). 

 Let \mbox{\texttt{\mdseries\slshape G1}} and \mbox{\texttt{\mdseries\slshape G2}} be two groups, \mbox{\texttt{\mdseries\slshape Z1}} be a central subgroup of \mbox{\texttt{\mdseries\slshape G1}}, and \mbox{\texttt{\mdseries\slshape Phi}} be an isomorphism from \mbox{\texttt{\mdseries\slshape Z1}} to a central subgroup of \mbox{\texttt{\mdseries\slshape G2}}. The \emph{central product} defined by these arguments is the factor group of the direct product of \mbox{\texttt{\mdseries\slshape G1}} and \mbox{\texttt{\mdseries\slshape G2}} by the central subgroup $\{ (z, (\mbox{\texttt{\mdseries\slshape Phi}}(z))^{-1}) : z \in \mbox{\texttt{\mdseries\slshape Z1}} \}$. 

 The attribute \texttt{CentralProductInfo} of a group $G$ that has been created by \texttt{CentralProduct} is similar to \texttt{PullbackInfo} (\ref{PullbackInfo}) for pullback groups. Its value is a record with the following components. 

 
\begin{description}
\item[{\texttt{projection}}]  the epimorphism from the direct product of \mbox{\texttt{\mdseries\slshape G1}} and \mbox{\texttt{\mdseries\slshape G2}} to $G$, and 
\item[{\texttt{phi}}]  the map \mbox{\texttt{\mdseries\slshape Phi}}. 
\end{description}
 Note that one can access the direct product as the \texttt{Source} (\textbf{Reference: Source}) value of the \texttt{projection} map, and one can access \mbox{\texttt{\mdseries\slshape G1}} and \mbox{\texttt{\mdseries\slshape G2}} as the two embeddings of this direct product, see \texttt{Embedding} (\textbf{Reference: Embedding}). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  !gapprompt@gap>| !gapinput@g1 := DihedralGroup( 8 );|
  <pc group of size 8 with 3 generators>
  !gapprompt@gap>| !gapinput@c1 := Centre( g1 );|
  Group([ f3 ])
  !gapprompt@gap>| !gapinput@cp1 := CentralProduct( g1, g1, c1, IdentityMapping( c1 ) );|
  Group([ f1, f2, f5, f3, f4, f5 ])
  !gapprompt@gap>| !gapinput@IdGroup( cp1 ) = IdGroup( ExtraspecialGroup( 2^5, "+" ) );|
  true
  !gapprompt@gap>| !gapinput@g2 := QuaternionGroup( 8 );|
  <pc group of size 8 with 3 generators>
  !gapprompt@gap>| !gapinput@c2 := Centre( g2 );|
  Group([ y2 ])
  !gapprompt@gap>| !gapinput@cp2 := CentralProduct( g2, g2, c2, IdentityMapping( c2 ) );|
  Group([ f1, f2, f5, f3, f4, f5 ])
  !gapprompt@gap>| !gapinput@IdGroup( cp2 ) = IdGroup( ExtraspecialGroup( 2^5, "+" ) );|
  true
  !gapprompt@gap>| !gapinput@info2 := CentralProductInfo( cp2 );|
  rec( phi := IdentityMapping( Group([ y2 ]) ), 
    projection := [ f1, f2, f3, f4, f5, f6 ] -> [ f1, f2, f5, f3, f4, f5 ] )
  !gapprompt@gap>| !gapinput@Source( Embedding( Source( info2.projection ), 1 ) ) = g2;|
  true
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{IdempotentEndomorphisms}}
\logpage{[ 5, 3, 4 ]}\nobreak
\hyperdef{L}{X801038CB808FC956}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IdempotentEndomorphisms({\mdseries\slshape G})\index{IdempotentEndomorphisms@\texttt{IdempotentEndomorphisms}}
\label{IdempotentEndomorphisms}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IdempotentEndomorphismsData({\mdseries\slshape G})\index{IdempotentEndomorphismsData@\texttt{IdempotentEndomorphismsData}}
\label{IdempotentEndomorphismsData}
}\hfill{\scriptsize (attribute)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IdempotentEndomorphismsWithImage({\mdseries\slshape genG, R})\index{IdempotentEndomorphismsWithImage@\texttt{IdempotentEndomorphismsWithImage}}
\label{IdempotentEndomorphismsWithImage}
}\hfill{\scriptsize (operation)}}\\


 An endomorphism $f : G \to G$ is idempotent if $f^2=f$. It has an image $R \leqslant G$; is the identity map when restricted to $R$; and has a kernel $N$ which has trivial intersection with $R$ and has size $|G|/|R|$. 

 The operation \texttt{IdempotentEndomorphismsWithImage(genG,R)} returns a list of the images of the generating set \texttt{genG} of a group $G$ under the idempotent endomorphisms with image $R$. 

 The attribute \texttt{IdempotentEndomorphismsData(G)} returns a record \texttt{data} with fields \texttt{data.gens}, a fixed generating set for $G$, and \texttt{data.images} a list of the non\texttt{\symbol{45}}empty outputs of \texttt{IdempotentEndomorphismsWithImage(genG,R)} obtained by iterating over all subgroups of $G$. 

 The operation \texttt{IdempotentEndomorphisms(G)} returns the list of these mappings obtained using \texttt{IdempotentEndomorphismsData(G)}. The first of these is the zero map, the second is the identity. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@gens := [ (1,2,3,4), (1,2)(3,4) ];; |
  !gapprompt@gap>| !gapinput@d8 := Group( gens );;|
  !gapprompt@gap>| !gapinput@SetName( d8, "d8" );|
  !gapprompt@gap>| !gapinput@c2 := Subgroup( d8, [ (2,4) ] );;|
  !gapprompt@gap>| !gapinput@IdempotentEndomorphismsWithImage( gens, c2 );|
  [ [ (), (2,4) ], [ (2,4), () ] ]
  !gapprompt@gap>| !gapinput@IdempotentEndomorphismsData( d8 );|
  rec( gens := [ (1,2,3,4), (1,2)(3,4) ], 
    images := [ [ [ (), () ] ], [ [ (), (2,4) ], [ (2,4), () ] ], 
        [ [ (), (1,3) ], [ (1,3), () ] ], 
        [ [ (), (1,2)(3,4) ], [ (1,2)(3,4), (1,2)(3,4) ] ], 
        [ [ (), (1,4)(2,3) ], [ (1,4)(2,3), (1,4)(2,3) ] ], 
        [ [ (1,2,3,4), (1,2)(3,4) ] ] ] )
  !gapprompt@gap>| !gapinput@List( last.images, L -> Length(L) );|
  [ 1, 2, 2, 2, 2, 1 ]
  !gapprompt@gap>| !gapinput@IdempotentEndomorphisms( d8 );               |
  [ [ (1,2,3,4), (1,2)(3,4) ] -> [ (), () ], 
    [ (1,2,3,4), (1,2)(3,4) ] -> [ (), (2,4) ], 
    [ (1,2,3,4), (1,2)(3,4) ] -> [ (2,4), () ], 
    [ (1,2,3,4), (1,2)(3,4) ] -> [ (), (1,3) ], 
    [ (1,2,3,4), (1,2)(3,4) ] -> [ (1,3), () ], 
    [ (1,2,3,4), (1,2)(3,4) ] -> [ (), (1,2)(3,4) ], 
    [ (1,2,3,4), (1,2)(3,4) ] -> [ (1,2)(3,4), (1,2)(3,4) ], 
    [ (1,2,3,4), (1,2)(3,4) ] -> [ (), (1,4)(2,3) ], 
    [ (1,2,3,4), (1,2)(3,4) ] -> [ (1,4)(2,3), (1,4)(2,3) ], 
    [ (1,2,3,4), (1,2)(3,4) ] -> [ (1,2,3,4), (1,2)(3,4) ] ]
  
\end{Verbatim}
 The quaternion group \texttt{q8} is an example of a group with a tail: there is only one subgroup in the
lattice which covers the identity subgroup. The only idempotent isomorphisms
of such groups are the identity mapping and the zero mapping because the only
pairs $N,R$ are the whole group and the identity subgroup. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@q8 := QuaternionGroup( 8 );;|
  !gapprompt@gap>| !gapinput@IdempotentEndomorphisms( q8 );|
  [ [ x, y ] -> [ <identity> of ..., <identity> of ... ], [ x, y ] -> [ x, y ] ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{DirectProductOfFunctions}}
\logpage{[ 5, 3, 5 ]}\nobreak
\hyperdef{L}{X81FA9E6C7F3B9238}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DirectProductOfFunctions({\mdseries\slshape G, H, f1, f2})\index{DirectProductOfFunctions@\texttt{DirectProductOfFunctions}}
\label{DirectProductOfFunctions}
}\hfill{\scriptsize (operation)}}\\


 Given group homomorphisms $f_1 : G_1 \to G_2$ and $f_2 : H_1 \to H_2$, this operation return the product homomorphism $f_1 \times f_2 : G_1 \times G_2 \to H_1 \times H_2$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@c4 := Group( (1,2,3,4) );; |
  !gapprompt@gap>| !gapinput@c2 := Group( (5,6) );; |
  !gapprompt@gap>| !gapinput@f1 := GroupHomomorphismByImages( c4, c2, [(1,2,3,4)], [(5,6)] );;|
  !gapprompt@gap>| !gapinput@c3 := Group( (1,2,3) );; |
  !gapprompt@gap>| !gapinput@c6 := Group( (1,2,3,4,5,6) );; |
  !gapprompt@gap>| !gapinput@f2 := GroupHomomorphismByImages( c3, c6, [(1,2,3)], [(1,3,5)(2,4,6)] );; |
  !gapprompt@gap>| !gapinput@c4c3 := DirectProduct( c4, c3 ); |
  Group([ (1,2,3,4), (5,6,7) ])
  !gapprompt@gap>| !gapinput@c2c6 := DirectProduct( c2, c6 ); |
  Group([ (1,2), (3,4,5,6,7,8) ])
  !gapprompt@gap>| !gapinput@f := DirectProductOfFunctions( c4c3, c2c6, f1, f2 ); |
  [ (1,2,3,4), (5,6,7) ] -> [ (1,2), (3,5,7)(4,6,8) ]
  !gapprompt@gap>| !gapinput@ImageElm( f, (1,4,3,2)(5,7,6) ); |
  (1,2)(3,7,5)(4,8,6)
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{DirectProductOfAutomorphismGroups}}
\logpage{[ 5, 3, 6 ]}\nobreak
\hyperdef{L}{X7CB2D5F27F4182AF}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DirectProductOfAutomorphismGroups({\mdseries\slshape A1, A2})\index{DirectProductOfAutomorphismGroups@\texttt{DirectProductOfAutomorphismGroups}}
\label{DirectProductOfAutomorphismGroups}
}\hfill{\scriptsize (operation)}}\\


 Let $A_1,A_2$ be groups of automorphism of groups $G_1,G_2$ respectively. The output of this function is a group $A_1 \times A_2$ of automorphisms of $G_1 \times G_2$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@c9 := Group( (1,2,3,4,5,6,7,8,9) );; |
  !gapprompt@gap>| !gapinput@ac9 := AutomorphismGroup( c9 );; |
  !gapprompt@gap>| !gapinput@q8 := QuaternionGroup( IsPermGroup, 8 );;|
  !gapprompt@gap>| !gapinput@aq8 := AutomorphismGroup( q8 );;|
  !gapprompt@gap>| !gapinput@A := DirectProductOfAutomorphismGroups( ac9, aq8 );|
  <group with 5 generators>
  !gapprompt@gap>| !gapinput@genA := GeneratorsOfGroup( A );;|
  !gapprompt@gap>| !gapinput@G := Source( genA[1] );|
  Group([ (1,2,3,4,5,6,7,8,9), (10,14,12,16)(11,17,13,15), (10,11,12,13)
  (14,15,16,17) ])
  !gapprompt@gap>| !gapinput@a := genA[1]*genA[5];  |
  [ (1,2,3,4,5,6,7,8,9), (10,14,12,16)(11,17,13,15), (10,11,12,13)(14,15,16,17) 
   ] -> [ (1,3,5,7,9,2,4,6,8), (10,16,12,14)(11,15,13,17), 
    (10,11,12,13)(14,15,16,17) ]
  !gapprompt@gap>| !gapinput@ImageElm( a, (1,9,8,7,6,5,4,3,2)(10,14,12,16)(11,17,13,15) );|
  (1,8,6,4,2,9,7,5,3)(10,16,12,14)(11,15,13,17)
  
\end{Verbatim}
 }

 }

         
\chapter{\textcolor{Chapter }{Matrices}}\label{chap-matrix}
\logpage{[ 6, 0, 0 ]}
\hyperdef{L}{X812CCAB278643A59}{}
{
  
\section{\textcolor{Chapter }{Some operations for matrices}}\label{sec-matrix-ops}
\logpage{[ 6, 1, 0 ]}
\hyperdef{L}{X802118FB7C94D6BA}{}
{
  

\subsection{\textcolor{Chapter }{DirectSumDecompositionMatrices}}
\logpage{[ 6, 1, 1 ]}\nobreak
\hyperdef{L}{X787B89237E1398B6}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DirectSumDecompositionMatrices({\mdseries\slshape M})\index{DirectSumDecompositionMatrices@\texttt{DirectSumDecompositionMatrices}}
\label{DirectSumDecompositionMatrices}
}\hfill{\scriptsize (operation)}}\\


 In June 2023 Hongyi Zhao asked in the Forum for a function to implement matrix
decomposition into blocks. Such a function was then provided by Pedro
Garc{\a'\i}a\texttt{\symbol{45}}S{\a'a}nchez. Hongyi Zhao then requested that
the function be added to \textsf{Utils}. What is provided here is a revised version of the original solution,
returning a list of decompositions. 

 This function is a partial inverse to the undocumented library operation \texttt{DirectSumMat}. So if $L$ is the list of diagonal decompositions of a matrix $M$ then each entry in $L$ is a list of matrices, and the direct sum of each of these lists is equal to
the original $M$. 

 In the following examples, $M_6$ is an obvious direct sum with $3$ blocks. $M_4$ is an example with three decompositions, while $M_8 = M_4 \oplus M_4$ has $16$ decompositions (not listed). 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@M6 := [ [1,2,0,0,0,0], [3,4,0,0,0,0], [5,6,0,0,0,0],                       |
  !gapprompt@>| !gapinput@           [0,0,9,0,0,0], [0,0,0,1,2,3], [0,0,0,4,5,6] ];;|
  !gapprompt@gap>| !gapinput@Display( M6 );|
  [ [  1,  2,  0,  0,  0,  0 ],
    [  3,  4,  0,  0,  0,  0 ],
    [  5,  6,  0,  0,  0,  0 ],
    [  0,  0,  9,  0,  0,  0 ],
    [  0,  0,  0,  1,  2,  3 ],
    [  0,  0,  0,  4,  5,  6 ] ]
  !gapprompt@gap>| !gapinput@L6 := DirectSumDecompositionMatrices( M6 );|
  [ [ [ [ 1, 2 ], [ 3, 4 ], [ 5, 6 ] ], [ [ 9 ] ], [ [ 1, 2, 3 ], [ 4, 5, 6 ] ] 
       ] ]
  
  !gapprompt@gap>| !gapinput@M4 := [ [0,3,0,0], [0,0,0,0], [0,0,0,0], [0,0,4,0] ];;|
  !gapprompt@gap>| !gapinput@Display( M4 );|
  [ [  0,  3,  0,  0 ],
    [  0,  0,  0,  0 ],
    [  0,  0,  0,  0 ],
    [  0,  0,  4,  0 ] ]
  !gapprompt@gap>| !gapinput@L4 := DirectSumDecompositionMatrices( M4 );|
  [ [ [ [ 0, 3 ] ], [ [ 0, 0 ], [ 0, 0 ], [ 4, 0 ] ] ], 
    [ [ [ 0, 3 ], [ 0, 0 ] ], [ [ 0, 0 ], [ 4, 0 ] ] ], 
    [ [ [ 0, 3 ], [ 0, 0 ], [ 0, 0 ] ], [ [ 4, 0 ] ] ] ]
  !gapprompt@gap>| !gapinput@for L in L4 do |
  !gapprompt@>| !gapinput@       A := DirectSumMat( L );; |
  !gapprompt@>| !gapinput@       if ( A = M4 ) then Print( "yes, A = M4\n" ); fi; |
  !gapprompt@>| !gapinput@   od;|
  yes, A = M4
  yes, A = M4
  yes, A = M4
  
  !gapprompt@gap>| !gapinput@M8 := DirectSumMat( M4, M4 );; |
  !gapprompt@gap>| !gapinput@Display( M8 );|
  [ [  0,  3,  0,  0,  0,  0,  0,  0 ],
    [  0,  0,  0,  0,  0,  0,  0,  0 ],
    [  0,  0,  0,  0,  0,  0,  0,  0 ],
    [  0,  0,  4,  0,  0,  0,  0,  0 ],
    [  0,  0,  0,  0,  0,  3,  0,  0 ],
    [  0,  0,  0,  0,  0,  0,  0,  0 ],
    [  0,  0,  0,  0,  0,  0,  0,  0 ],
    [  0,  0,  0,  0,  0,  0,  4,  0 ] ]
  !gapprompt@gap>| !gapinput@L8 := DirectSumDecompositionMatrices( M8 );;|
  !gapprompt@gap>| !gapinput@Length( L8 ); |
  16
  
\end{Verbatim}
 

 The current method does not, however, catch all possible decompositions. In
the following example the matrix $M_5$ has its third row and third column extirely zero, and the only decomposition
found has a $[0]$ factor. There are clearly two $2$\texttt{\symbol{45}}factor decompositions with a $2$\texttt{\symbol{45}}by\texttt{\symbol{45}}$3$ and a $3$\texttt{\symbol{45}}by\texttt{\symbol{45}}$2$ factor, but these are not found at present. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@M5 := [ [1,2,0,0,0], [3,4,0,0,0], [0,0,0,0,0],|
  !gapprompt@>| !gapinput@           [0,0,0,6,7], [0,0,0,8,9] ];;|
  !gapprompt@gap>| !gapinput@Display(M5);|
  [ [  1,  2,  0,  0,  0 ],
    [  3,  4,  0,  0,  0 ],
    [  0,  0,  0,  0,  0 ],
    [  0,  0,  0,  6,  7 ],
    [  0,  0,  0,  8,  9 ] ]
  !gapprompt@gap>| !gapinput@L5 := DirectSumDecompositionMatrices( M5 ); |
  [ [ [ [ 1, 2 ], [ 3, 4 ] ], [ [ 0 ] ], [ [ 6, 7 ], [ 8, 9 ] ] ] ]
  
\end{Verbatim}
 }

 }

         
\chapter{\textcolor{Chapter }{Iterators}}\label{chap-iterator}
\logpage{[ 7, 0, 0 ]}
\hyperdef{L}{X85A3F00985453F95}{}
{
  
\section{\textcolor{Chapter }{Some iterators for groups and their isomorphisms}}\label{sec-group-iters}
\logpage{[ 7, 1, 0 ]}
\hyperdef{L}{X7BB5350081B27D17}{}
{
  \index{Iterators} The motivation for adding these operations is partly to give a simple example
of an iterator for a list that does not yet exist, and need not be created. 

 

\subsection{\textcolor{Chapter }{AllIsomorphismsIterator}}
\logpage{[ 7, 1, 1 ]}\nobreak
\hyperdef{L}{X7F8B54D1806C762D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllIsomorphismsIterator({\mdseries\slshape G, H})\index{AllIsomorphismsIterator@\texttt{AllIsomorphismsIterator}}
\label{AllIsomorphismsIterator}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllIsomorphismsNumber({\mdseries\slshape G, H})\index{AllIsomorphismsNumber@\texttt{AllIsomorphismsNumber}}
\label{AllIsomorphismsNumber}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllIsomorphisms({\mdseries\slshape G, H})\index{AllIsomorphisms@\texttt{AllIsomorphisms}}
\label{AllIsomorphisms}
}\hfill{\scriptsize (operation)}}\\


 The main \textsf{GAP} library contains functions producing complete lists of group homomorphisms
such as \texttt{AllHomomorphisms}; \texttt{AllEndomorphisms} and \texttt{AllAutomorphisms}. Here we add the missing \texttt{AllIsomorphisms(G,H)} for a list of isomorphisms from $G$ to $H$. The method is simple \texttt{\symbol{45}}\texttt{\symbol{45}} find one
isomorphism $G \to H$ and compose this with all the automorphisms of $G$. In all these cases it may not be desirable to construct a list of
homomorphisms, but just implement an iterator, and that is what is done here.
The operation \texttt{AllIsomorphismsNumber} returns the number of isomorphisms iterated over (this is, of course, just the
order of the automorphisms group). The operation \texttt{AllIsomorphisms} produces the list or isomorphisms. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@G := SmallGroup( 6,1);; |
  !gapprompt@gap>| !gapinput@iter := AllIsomorphismsIterator( G, s3 );;|
  !gapprompt@gap>| !gapinput@NextIterator( iter );|
  [ f1, f2 ] -> [ (6,7), (5,6,7) ]
  !gapprompt@gap>| !gapinput@n := AllIsomorphismsNumber( G, s3 );|
  6
  !gapprompt@gap>| !gapinput@AllIsomorphisms( G, s3 );|
  [ [ f1, f2 ] -> [ (6,7), (5,6,7) ], [ f1, f2 ] -> [ (5,7), (5,6,7) ], 
    [ f1, f2 ] -> [ (5,6), (5,7,6) ], [ f1, f2 ] -> [ (6,7), (5,7,6) ], 
    [ f1, f2 ] -> [ (5,7), (5,7,6) ], [ f1, f2 ] -> [ (5,6), (5,6,7) ] ]
  !gapprompt@gap>| !gapinput@iter := AllIsomorphismsIterator( G, s3 );;|
  !gapprompt@gap>| !gapinput@for h in iter do Print( ImageElm( h, G.1 ) = (6,7), ", " ); od;|
  true, false, false, true, false, false,
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{AllSubgroupsIterator}}
\logpage{[ 7, 1, 2 ]}\nobreak
\hyperdef{L}{X831DA5AE8437578F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllSubgroupsIterator({\mdseries\slshape G})\index{AllSubgroupsIterator@\texttt{AllSubgroupsIterator}}
\label{AllSubgroupsIterator}
}\hfill{\scriptsize (operation)}}\\


 The manual entry for the operation \texttt{AllSubgroups} states that it is only intended to be used on small examples in a classroom
situation. Access to all subgroups was required by the \textsf{XMod} package, so this iterator was introduced here. It used the operations \texttt{LatticeSubgroups(G)} and \texttt{ConjugacyClassesSubgroups(lat)}, and then iterates over the entries in these classes. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@c3c3 := Group( (1,2,3), (4,5,6) );; |
  !gapprompt@gap>| !gapinput@iter := AllSubgroupsIterator( c3c3 );|
  <iterator>
  !gapprompt@gap>| !gapinput@while not IsDoneIterator(iter) do Print(NextIterator(iter),"\n"); od;|
  Group( () )
  Group( [ (4,5,6) ] )
  Group( [ (1,2,3) ] )
  Group( [ (1,2,3)(4,5,6) ] )
  Group( [ (1,3,2)(4,5,6) ] )
  Group( [ (4,5,6), (1,2,3) ] )
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Operations on iterators}}\label{sec-iter-ops}
\logpage{[ 7, 2, 0 ]}
\hyperdef{L}{X85413EED812C6497}{}
{
  This section considers ways of producing an iterator from one or more
iterators. It may be that operations equivalent to these are available
elsewhere in the library \texttt{\symbol{45}}\texttt{\symbol{45}} if so, the
ones here can be removed in due course. 

\subsection{\textcolor{Chapter }{CartesianIterator}}
\logpage{[ 7, 2, 1 ]}\nobreak
\hyperdef{L}{X87395A9181A35301}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CartesianIterator({\mdseries\slshape iter1, iter2})\index{CartesianIterator@\texttt{CartesianIterator}}
\label{CartesianIterator}
}\hfill{\scriptsize (operation)}}\\


 This iterator returns all pairs $[x,y]$ where $x$ is the output of a first iterator and $y$ is the output of a second iterator. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@it1 := Iterator( [ 1, 2, 3 ] );;|
  !gapprompt@gap>| !gapinput@it2 := Iterator( [ 4, 5, 6 ] );;|
  !gapprompt@gap>| !gapinput@iter := CartesianIterator( it1, it2 );;|
  !gapprompt@gap>| !gapinput@while not IsDoneIterator(iter) do Print(NextIterator(iter),"\n"); od;|
  [ 1, 4 ]
  [ 1, 5 ]
  [ 1, 6 ]
  [ 2, 4 ]
  [ 2, 5 ]
  [ 2, 6 ]
  [ 3, 4 ]
  [ 3, 5 ]
  [ 3, 6 ]
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{UnorderedPairsIterator}}
\logpage{[ 7, 2, 2 ]}\nobreak
\hyperdef{L}{X7C95E27987A812EA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UnorderedPairsIterator({\mdseries\slshape iter})\index{UnorderedPairsIterator@\texttt{UnorderedPairsIterator}}
\label{UnorderedPairsIterator}
}\hfill{\scriptsize (operation)}}\\


 This operation returns pairs $[x,y]$ where $x,y$ are output from a given iterator \texttt{iter}. Unlike the output from \texttt{CartesianIterator(iter,iter)}, unordered pairs are returned. In the case $L = [1,2,3,\ldots]$ the pairs are ordered as $[1,1],[1,2],[2,2],[1,3],[2,3],[3,3],\ldots$. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@L := [6,7,8,9];;|
  !gapprompt@gap>| !gapinput@iterL := IteratorList( L );; |
  !gapprompt@gap>| !gapinput@pairsL := UnorderedPairsIterator( iterL );;                              |
  !gapprompt@gap>| !gapinput@while not IsDoneIterator(pairsL) do Print(NextIterator(pairsL),"\n"); od;|
  [ 6, 6 ]
  [ 6, 7 ]
  [ 7, 7 ]
  [ 6, 8 ]
  [ 7, 8 ]
  [ 8, 8 ]
  [ 6, 9 ]
  [ 7, 9 ]
  [ 8, 9 ]
  [ 9, 9 ]
  !gapprompt@gap>| !gapinput@iter4 := IteratorList( [ 4 ] );|
  <iterator>
  !gapprompt@gap>| !gapinput@pairs4 := UnorderedPairsIterator(iter4);|
  <iterator>
  !gapprompt@gap>| !gapinput@NextIterator( pairs4 );|
  [ 4, 4 ]
  !gapprompt@gap>| !gapinput@IsDoneIterator( pairs4 );|
  true
  
\end{Verbatim}
 }

 }

         
\chapter{\textcolor{Chapter }{Records}}\label{chap-record}
\logpage{[ 8, 0, 0 ]}
\hyperdef{L}{X7AA1073C7E943DD7}{}
{
  
\section{\textcolor{Chapter }{Functions for records}}\label{sec-records}
\logpage{[ 8, 1, 0 ]}
\hyperdef{L}{X82B3D1D583CDF0E5}{}
{
  

\subsection{\textcolor{Chapter }{AssignGlobals}}
\logpage{[ 8, 1, 1 ]}\nobreak
\hyperdef{L}{X84D82EB579B2ACCD}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AssignGlobals({\mdseries\slshape rec})\index{AssignGlobals@\texttt{AssignGlobals}}
\label{AssignGlobals}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 It assigns the record components of \mbox{\texttt{\mdseries\slshape rec}} to global variables with the same names. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@r := rec( a := 1, b := 2, c := 3 );;                                      |
  !gapprompt@gap>| !gapinput@AssignGlobals( r );|
  The following global variables have been assigned:
  [ "a", "b", "c" ]
  !gapprompt@gap>| !gapinput@[a,b,c];|
  [ 1, 2, 3 ]
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Option records for functions}}\label{sec-options}
\logpage{[ 8, 2, 0 ]}
\hyperdef{L}{X7E6207B47B9AA30C}{}
{
  

\subsection{\textcolor{Chapter }{OptionRecordWithDefaults}}
\logpage{[ 8, 2, 1 ]}\nobreak
\hyperdef{L}{X8322B9377CC590D2}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{OptionRecordWithDefaults({\mdseries\slshape defaults, useroptions})\index{OptionRecordWithDefaults@\texttt{OptionRecordWithDefaults}}
\label{OptionRecordWithDefaults}
}\hfill{\scriptsize (function)}}\\


 This functions has been transferred by Chris Jefferson from other packages. It
simplifies the handling of records which are intended to be used for
expressing configuration options. \mbox{\texttt{\mdseries\slshape defaults}} represents the "default record", and \mbox{\texttt{\mdseries\slshape useroptions}} lets the user give new values for values in \mbox{\texttt{\mdseries\slshape defaults}}. 

 The function returns a record with the same component names as \mbox{\texttt{\mdseries\slshape defaults}} and which has the same values as \mbox{\texttt{\mdseries\slshape defaults}}, except for those component names in \mbox{\texttt{\mdseries\slshape useroptions}}, where the values in \mbox{\texttt{\mdseries\slshape useroptions}} are used instead. An error is given if \mbox{\texttt{\mdseries\slshape useroptions}} contains any component names not in \mbox{\texttt{\mdseries\slshape defaults}}. If \mbox{\texttt{\mdseries\slshape useroptions}} is an empty list it is treated as an empty record, and if \mbox{\texttt{\mdseries\slshape useroptions}} is a list of length $1$ containing a record, this record is used as \mbox{\texttt{\mdseries\slshape useroptions}}. 

 }

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@defaults := rec( a := 1, b := 2, c := 3 );;|
  !gapprompt@gap>| !gapinput@OptionRecordWithDefaults( defaults, rec( a := 6) );|
  rec( a := 6, b := 2, c := 3 )
  !gapprompt@gap>| !gapinput@OptionRecordWithDefaults( defaults, rec( b := 7, c := 8 ) );|
  rec( a := 1, b := 7, c := 8 )
  !gapprompt@gap>| !gapinput@OptionRecordWithDefaults( defaults, [ ] );|
  rec( a := 1, b := 2, c := 3 )
  !gapprompt@gap>| !gapinput@OptionRecordWithDefaults( defaults, [ rec( c := 8 ) ] );|
  rec( a := 1, b := 2, c := 8 )
  !gapprompt@gap>| !gapinput@OptionRecordWithDefaults( defaults, rec( d := 9 ) );|
  Error, Unknown option: d
  !gapprompt@gap>| !gapinput@OptionRecordWithDefaults( defaults, [ rec( b := 7 ), rec( c := 8 ) ] );|
  Error, Too many arguments for function
  !gapprompt@gap>| !gapinput@OptionRecordWithDefaults( defaults, [6,7,8] );|
  Error, Too many arguments for function
  
\end{Verbatim}
 This function is designed to support functions with optional arguments given
as a variable record, of the form \texttt{function(x,y,options...)}. In the following, very contrived, example function, \texttt{PrintDimensions}, the defaults are given by the variable \texttt{order} which takes values \texttt{h}, \texttt{w} and \texttt{d} having default values $1$, $2$ and $3$. If there is a second argument, then \texttt{OptionRecordWithDefaults( order, arg[2] );} is used to cvhange the values. These three values then determine the order in
which the three dimensions are printed using a \texttt{SortParallel} command. 
\begin{Verbatim}[commandchars=@|A,fontsize=\small,frame=single,label=]
  
  PrintDimensions := function( arg ) 
      local nargs, dim, order, V, L, len, K, i; 
      nargs := Length( arg ); 
      dim := [ arg[1]!.height, arg[1]!.width, arg[1]!.depth ]; 
      order := rec( h := 1, w := 2, d := 3 ); 
      V := [ "height", "width", "depth" ]; 
      if ( nargs > 1 ) and IsRecord( arg[2] ) then 
          order := OptionRecordWithDefaults( order, arg[2] ); 
      fi; 
      L := [ order!.h, order!.w, order!.d ]; 
      len := Length( L );
      K := [ 1..len ]; 
      SortParallel( L, K ); 
      Print( "dimensions: " ); 
      Print( V[K[1]], " = ", dim[K[1]], ", " );
      Print( V[K[2]], " = ", dim[K[2]], ", " );
      Print( V[K[3]], " = ", dim[K[3]], "\n" );
  end;;
\end{Verbatim}
 In the example below the first call to \texttt{PrintDimensions} has just one parameter, \texttt{mydim}, so the default order is used. In the second call, alternate values for \texttt{h}, \texttt{w} and \texttt{d} are given, causing the width to be printed first, and then the depth and
height. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@mydim := rec( height := 45, width := 31, depth := 17 ); |
  rec( depth := 17, height := 45, width := 31 )
  !gapprompt@gap>| !gapinput@PrintDimensions( mydim );|
  dimensions: height = 45, width = 31, depth = 17
  !gapprompt@gap>| !gapinput@PrintDimensions( mydim, rec( h:=3, w:=1, d:=2 ) );|
  dimensions: width = 31, depth = 17, height = 45
  
\end{Verbatim}
 }

 }

         
\chapter{\textcolor{Chapter }{Web Downloads}}\label{chap-download}
\logpage{[ 9, 0, 0 ]}
\hyperdef{L}{X815B0C4B7EBE6E1E}{}
{
  The \texttt{Download} operation has been written by Thomas Breuer, incorporating a number of
suggestions from Max Horn, for version 0.77 of \textsf{Utils}. It implements downloading a file from within \textsf{GAP}. It can use the \textsf{IO} or \textsf{curlInterface} packages, or \emph{wget} or \emph{curl}, if installed, and it can be extended with other download methods quite
easily. It is envisaged that, once other packages have started to use it, and
any problems have been addressed, that the functions will be transferred to
the main \textsf{GAP} library. 
\section{\textcolor{Chapter }{Functions for downloading files from the web}}\label{sec-download}
\logpage{[ 9, 1, 0 ]}
\hyperdef{L}{X8758CB7F79EFB6ED}{}
{
  

\subsection{\textcolor{Chapter }{Download}}
\logpage{[ 9, 1, 1 ]}\nobreak
\hyperdef{L}{X7A7438AE8448635E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Download({\mdseries\slshape url[, opt]})\index{Download@\texttt{Download}}
\label{Download}
}\hfill{\scriptsize (function)}}\\


 This function downloads the file with the web address \mbox{\texttt{\mdseries\slshape url}}, which must be a string. 

 The result is a record which has at least the component \texttt{success}, with value \texttt{true} if the download was successful and \texttt{false} otherwise. In the former case, the component \texttt{result} is bound, whose value is a string that contains the contents of the downloaded
file. In the latter case, the component \texttt{error} is bound, whose value is a string that describes the problem. 

 The function calls the methods stored in the global list \texttt{Download{\textunderscore}Methods} until one of them is successful. Currently there are methods based on the \textsf{GAP} functions \texttt{DownloadURL} (\textbf{curl: DownloadURL}) and \texttt{SingleHTTPRequest} (\textbf{IO: SingleHTTPRequest}), and methods based on the external programs \texttt{wget} and \texttt{curl}. 

 An optional record \mbox{\texttt{\mdseries\slshape opt}} can be given. The following components are supported. 

 
\begin{description}
\item[{\texttt{maxTime}}]  If this component is bound then its value must be a nonnegative integer $n$, meaning that the function gives up after $n$ seconds. 

 A zero value of $n$ means that no timeout is set, the method will never give up in this case. 

 The default for $n$ is given by the value of the user preference \texttt{DownloadMaxTime} (see \ref{subsec-DownloadMaxTime}). 
\item[{\texttt{target}}]  If this component is bound then its value must be a string that is a local
filename, and the function writes the downloaded contents to this file; the
returned record does not have a \texttt{result} component in this case. 
\item[{\texttt{verifyCert}}]  If this component is bound and has the value \texttt{false} then those download methods that are based on \texttt{curl} or \texttt{wget} will omit the check of the server's certificate. 

 The same effect is achieved for all \texttt{Download} calls by setting the user preference \texttt{DownloadVerifyCertificate} (see \ref{subsec-DownloadVerifyCertificate}) to \texttt{false} and omitting the \texttt{verifyCert} component from \mbox{\texttt{\mdseries\slshape opt}}. 
\end{description}
 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@url:= "https://www.gap-system.org/index.html";;|
  !gapprompt@gap>| !gapinput@res1:= Download( url );;|
  !gapprompt@gap>| !gapinput@res1.success;|
  true
  !gapprompt@gap>| !gapinput@IsBound( res1.result ) and IsString( res1.result );|
  true
  !gapprompt@gap>| !gapinput@res2:= Download( Concatenation( url, "xxx" ) );;|
  !gapprompt@gap>| !gapinput@res2.success;|
  false
  !gapprompt@gap>| !gapinput@IsBound( res2.error ) and IsString( res2.error );|
  true
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{User preference \texttt{DownloadVerifyCertificate}}}\label{subsec-DownloadVerifyCertificate}
\logpage{[ 9, 1, 2 ]}
\hyperdef{L}{X85182BA486E3C2AA}{}
{
  \index{DownloadVerifyCertificate@\texttt{DownloadVerifyCertificate}} The value \texttt{true} (the default) means that the server's certificate is checked in calls of \texttt{Download} (\ref{Download}), such that nothing gets downloaded if the certificate is invalid. 

 If the value is \texttt{false} then download methods are supposed to omit the check of the server's
certificate (this may not be supported by all download methods). 

 One can set the value of the preference to be \texttt{val} via \texttt{SetUserPreference} (\textbf{Reference: SetUserPreference}), by calling \texttt{SetUserPreference( "utils", "DownloadVerifyCertificate", val )}, and access the current value via \texttt{UserPreference} (\textbf{Reference: UserPreference}), by calling \texttt{UserPreference( "utils", "DownloadVerifyCertificate" )}. 

 We recommend leaving this preference at its default value \texttt{true}. Sometimes it can be necessary to change it, e.g. to work around issues with
old operating systems which may not be able to correctly verify new
certificates. In general it is better to update such a system, but if that is
not an option, then disabling certificate checks may be a good last resort. }

 
\subsection{\textcolor{Chapter }{User preference \texttt{DownloadMaxTime}}}\label{subsec-DownloadMaxTime}
\logpage{[ 9, 1, 3 ]}
\hyperdef{L}{X79E10E5B83EF929F}{}
{
  \index{DownloadMaxTime@\texttt{DownloadMaxTime}} The value \texttt{0} (the default) means that no timeout is set in calls of \texttt{Download} (\ref{Download}). If the value is a positive integer $n$ then those download methods that support a timeout will give up after $n$ seconds. 

 One can set the value of the preference to be \texttt{val} via \texttt{SetUserPreference} (\textbf{Reference: SetUserPreference}), by calling \texttt{SetUserPreference( "utils", "DownloadMaxTime", val )}, and access the current value via \texttt{UserPreference} (\textbf{Reference: UserPreference}), by calling \texttt{UserPreference( "utils", "DownloadMaxTime" )}. }

 }

 }

          
\chapter{\textcolor{Chapter }{Various other functions}}\label{chap-others}
\logpage{[ 10, 0, 0 ]}
\hyperdef{L}{X83EFC3178180D918}{}
{
  
\section{\textcolor{Chapter }{File operations}}\label{sec-log2html}
\logpage{[ 10, 1, 0 ]}
\hyperdef{L}{X81A0A4FF842B039B}{}
{
  

\subsection{\textcolor{Chapter }{Log2HTML}}
\logpage{[ 10, 1, 1 ]}\nobreak
\hyperdef{L}{X7B7ECADF85F748BE}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Log2HTML({\mdseries\slshape filename})\index{Log2HTML@\texttt{Log2HTML}}
\label{Log2HTML}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 This function converts the \textsf{GAP} logfile \texttt{filename} to HTML. It appears that the logfile should be in your current directory. The
extension of the input file must be \texttt{*.log}. The name of the output file is the same as the one of the input file except
that the extension \texttt{*.log} is replaced by \texttt{*.html}. There is a sample CSS file in \texttt{utils/doc/gaplog.css}, which you can adjust to your taste. 

 }

 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LogTo( "triv.log" );|
  !gapprompt@gap>| !gapinput@a := 33^5;|
  39135393
  !gapprompt@gap>| !gapinput@LogTo(); |
  !gapprompt@gap>| !gapinput@Log2HTML( "triv.log" );     |
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{{\LaTeX} strings}}\label{sec-latex}
\logpage{[ 10, 2, 0 ]}
\hyperdef{L}{X84D2922D87EDE9E9}{}
{
  

\subsection{\textcolor{Chapter }{IntOrOnfinityToLaTeX}}
\logpage{[ 10, 2, 1 ]}\nobreak
\hyperdef{L}{X87DEB2B58266F858}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IntOrOnfinityToLaTeX({\mdseries\slshape n})\index{IntOrOnfinityToLaTeX@\texttt{IntOrOnfinityToLaTeX}}
\label{IntOrOnfinityToLaTeX}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{ResClasses}. 

 \texttt{IntOrInfinityToLaTeX(n)} returns the {\LaTeX} string for \mbox{\texttt{\mdseries\slshape n}}. 

 }

 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@IntOrInfinityToLaTeX( 10^3 );|
  "1000"
  !gapprompt@gap>| !gapinput@IntOrInfinityToLaTeX( infinity );|
  "\\infty"
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{LaTeXStringFactorsInt}}
\logpage{[ 10, 2, 2 ]}\nobreak
\hyperdef{L}{X7DC642B97CD02F4E}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LaTeXStringFactorsInt({\mdseries\slshape n})\index{LaTeXStringFactorsInt@\texttt{LaTeXStringFactorsInt}}
\label{LaTeXStringFactorsInt}
}\hfill{\scriptsize (function)}}\\


 This function has been transferred from package \textsf{RCWA}. 

 It returns the prime factorization of the integer $n$ as a string in {\LaTeX} format. 

 }

 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@LaTeXStringFactorsInt( Factorial(12) );|
  "2^{10} \\cdot 3^5 \\cdot 5^2 \\cdot 7 \\cdot 11"
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Conversion to ${\sf Magma}$ strings}}\label{sec-magma}
\logpage{[ 10, 3, 0 ]}
\hyperdef{L}{X79F021B1830B68F6}{}
{
  

\subsection{\textcolor{Chapter }{ConvertToMagmaInputString}}
\logpage{[ 10, 3, 1 ]}\nobreak
\hyperdef{L}{X8768D7707B4CBBD4}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ConvertToMagmaInputString({\mdseries\slshape arg})\index{ConvertToMagmaInputString@\texttt{ConvertToMagmaInputString}}
\label{ConvertToMagmaInputString}
}\hfill{\scriptsize (function)}}\\


 The function \texttt{ConvertToMagmaInputString( obj [, str] )} attempts to output a string \texttt{s} which can be read into ${\sf Magma}$ \cite{MAGMA} so as to produce the same group in that computer algebra system. In the second
form the user specifies the name of the resulting object, so that the output
string has the form \texttt{"str := ..."}. 

 When \texttt{obj} is a permutation group, the operation \texttt{PermGroupToMagmaFormat(obj)} is called. \index{PermGroupToMagmaFormat} This function has been taken from \texttt{other.gi} in the main library where it was called \texttt{MagmaInputString}. 

 When \texttt{obj} is a pc\texttt{\symbol{45}}group, the operation \texttt{PcGroupToMagmaFormat(obj)} is called. \index{PcGroupToMagmaFormat} This function was private code of Max Horn. 

 When \texttt{obj} is a matrix group over a finite field, the operation \texttt{MatrixGroupToMagmaFormat(obj)} is called. \index{MatrixGroupToMagmaFormat} This function is a modification of private code of Frank L{\"u}beck. 

 Hopefully code for other types of group will be added in due course. 

 These functions should be considered \emph{experimental}, and more testing is desirable. 

 }

 

 
\begin{Verbatim}[commandchars=@AB,fontsize=\small,frame=single,label=Example]
  
  @gappromptAgap>B @gapinputA## permutation groupsB
  @gappromptAgap>B @gapinputAConvertToMagmaInputString( Group( (1,2,3,4,5), (3,4,5) ) );B
  "PermutationGroup<5|(1,2,3,4,5),\n(3,4,5)>;\n"
  @gappromptAgap>B @gapinputAConvertToMagmaInputString( Group( (1,2,3,4,5) ), "c5" );        B
  "c5 := PermutationGroup<5|(1,2,3,4,5)>;\n"
  @gappromptAgap>B @gapinputA## pc-groupB
  @gappromptAgap>B @gapinputAConvertToMagmaInputString( DihedralGroup( IsPcGroup, 10 ) );B
  "PolycyclicGroup< f1,f2 |\nf1^2,\nf2^5,\nf2^f1 = f2^4\n>;\n"
  @gappromptAgap>B @gapinputA## fp-groupB
  @gappromptAgap>B @gapinputAF2 := FreeGroup( 2 );;B
  @gappromptAgap>B @gapinputAf := F2.1;;  g := F2.2;;B
  @gappromptAgap>B @gapinputArelq8 := [ f^4, g^4, f*g*f*g^-1, f^2*g^2 ];; B
  @gappromptAgap>B @gapinputAq8 := F2/relq8;; B
  @gappromptAgap>B @gapinputAConvertToMagmaInputString( q8 );B
  no conversion function yet available for fp-groups
  fail
  @gappromptAgap>B @gapinputA## matrix groupB
  @gappromptAgap>B @gapinputAM := GL(2,5);;  Size(M); B
  480
  @gappromptAgap>B @gapinputAs1 := ConvertToMagmaInputString( M );B
  "F := GF(5);\nP := GL(2,F);\ngens := [\nP![2,0,0,1],\nP![4,1,4,0]\n];\nsub<P |\
   gens>;\n"
  @gappromptAgap>B @gapinputAPrint( s1 );B
  F := GF(5);
  P := GL(2,F);
  gens := [
  P![2,0,0,1],
  P![4,1,4,0]
  ];
  sub<P | gens>;
  @gappromptAgap>B @gapinputAn1 := [ [ Z(9)^0, Z(9)^0 ], [ Z(9)^0, Z(9) ] ];;B
  @gappromptAgap>B @gapinputAn2 := [ [ Z(9)^0, Z(9)^3 ], [ Z(9)^4, Z(9)^2 ] ];;B
  @gappromptAgap>B @gapinputAN := Group( n1, n2 );;  Size( N );B
  5760
  @gappromptAgap>B @gapinputAs2 := ConvertToMagmaInputString( N, "gpN" );;B
  @gappromptAgap>B @gapinputAPrint( s2 );B
  F := GF(3^2);
  P := GL(2,F);
  w := PrimitiveElement(F);
  gens := [
  P![ 1, 1, 1,w^1],
  P![ 1,w^3, 2,w^2]
  ];
  gpN := sub<P | gens>;
  
\end{Verbatim}
 }

 }

         
\chapter{\textcolor{Chapter }{Obsolete functions}}\label{chap-obsolete}
\logpage{[ 11, 0, 0 ]}
\hyperdef{L}{X7F561B1D803182FF}{}
{
  
\section{\textcolor{Chapter }{Operations from AutoDoc}}\label{sec-obs-folders}
\logpage{[ 11, 1, 0 ]}
\hyperdef{L}{X7A6BB3D084912F35}{}
{
  The file functions \texttt{FindMatchingFiles} \index{FindMatchingFiles} and \texttt{CreateDirIfMissing} \index{CreateDirIfMissing} were copied from package \textsf{AutoDoc} where they are named \texttt{AutoDoc{\textunderscore}FindMatchingFiles} and \texttt{AutoDoc{\textunderscore}CreateDirIfMissing}. 

 The string function \texttt{StringDotSuffix} \index{StringDotSuffix} was also copied from package \textsf{AutoDoc}, where it is named \texttt{AUTODOC{\textunderscore}GetSuffix}. \index{GetSuffix} 

 The function \texttt{SetIfMissing} \index{SetIfMissing} was also transferred from package \textsf{AutoDoc}, where it is called \texttt{AUTODOC{\textunderscore}SetIfMissing}. It writes into a record provided the position is not yet bound. 

 As from version 0.61, all these functions became obsolete in \textsf{Utils}, but continue to be defined in \textsf{AutoDoc}. }

 
\section{\textcolor{Chapter }{Functions for printing}}\label{sec-obs-print}
\logpage{[ 11, 2, 0 ]}
\hyperdef{L}{X86F322FC7DECE36F}{}
{
  The function \texttt{PrintOneItemPerLine} \index{PrintOneItemPerLine} was used to prints lists vertically, rather than horizontally. Since a very
similar result may be achieved using the \textsf{GAP} library functions \texttt{Perform} and \texttt{Display}, this function became obsolete in version 0.61. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@s3 := SymmetricGroup( 3 );; |
  !gapprompt@gap>| !gapinput@L := KnownPropertiesOfObject( GeneratorsOfGroup( s3 ) );;|
  !gapprompt@gap>| !gapinput@Perform( L, Display );|
  IsFinite
  IsSmallList
  IsGeneratorsOfMagmaWithInverses
  IsGeneratorsOfSemigroup
  IsSubsetLocallyFiniteGroup
  !gapprompt@gap>| !gapinput@Perform( s3, Display ); |
  ()
  (2,3)
  (1,3)
  (1,3,2)
  (1,2,3)
  (1,2)
  
\end{Verbatim}
 }

 
\section{\textcolor{Chapter }{Other obsolete functions}}\label{sec-obs-others}
\logpage{[ 11, 3, 0 ]}
\hyperdef{L}{X84A4F0B281FA0F94}{}
{
  
\subsection{\textcolor{Chapter }{Applicable Methods}}\label{subsec-app-meth}
\logpage{[ 11, 3, 1 ]}
\hyperdef{L}{X78B7D1A982BE9866}{}
{
  The function \index{PrintApplicableMethod} \texttt{PrintApplicableMethod}, which was included in versions from 0.41 to 0.58, has been removed since it
was considered superfluous. The example shows how to print out a function. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ApplicableMethod( IsCyclic, [ Group((1,2,3),(4,5)) ], 1, 1 );|
  #I  Searching Method for IsCyclic with 1 arguments:
  #I  Total: 7 entries
  #I  Method 4: ``IsCyclic'' at /Applications/gap/gap4r9/lib/grp.gi:30 , value: 
  36
  function( G ) ... end
  !gapprompt@gap>| !gapinput@Print( last );|
  function ( G )
      if Length( GeneratorsOfGroup( G ) ) = 1 then
          return true;
      else
          TryNextMethod();
      fi;
      return;
  end
  !gapprompt@gap>| !gapinput@ApplicableMethod( IsCyclic, [ Group((1,2,3),(4,5)) ], 0, 3 );|
  function( <1 unnamed arguments> ) ... end
  !gapprompt@gap>| !gapinput@Print( last );                                               |
  function ( <<arg-1>> )
      <<compiled GAP code from GAPROOT/lib/oper1.g:578>>
  end
  
\end{Verbatim}
 }

 
\subsection{\textcolor{Chapter }{ExponentOfPrime}}\label{subsec-exponent}
\logpage{[ 11, 3, 2 ]}
\hyperdef{L}{X7C1AF2467FB55D79}{}
{
  The function \texttt{ExponentOfPrime} \index{ExponentOfPrime} was originally transferred from package \textsf{RCWA}. The command \texttt{ExponentOfPrime(\mbox{\texttt{\mdseries\slshape n}},\mbox{\texttt{\mdseries\slshape p}})} returned the exponent of the prime \mbox{\texttt{\mdseries\slshape p}} in the prime factorization of \mbox{\texttt{\mdseries\slshape n}}. 

 Since the \textsf{GAP} function \texttt{PValuation} produces the same results, and does so more quickly, this function has been
made obsolete. }

 }

 }

         
\chapter{\textcolor{Chapter }{The transfer procedure}}\label{chap-transfer}
\logpage{[ 12, 0, 0 ]}
\hyperdef{L}{X84AC9613842F014C}{}
{
  We consider here the process for transferring utility functions from a package \textsf{Home} to \textsf{Utils} which has to avoid the potential problem of duplicate declarations of a
function causing loading problems in \textsf{GAP}. 

 If the functions in \textsf{Home} all have names of the form \texttt{HOME{\textunderscore}FunctionName} then, in \textsf{Utils}, these functions are likely to be renamed as \texttt{FunctionName} or something similar. In this case the problem of duplicate declarations does
not arise. This is what has happened with transfers from the \textsf{AutoDoc} package. 

 The case where the function names are unchanged is more complicated. Initially
we tried out a process which allowed repeated declarations and installations
of the functions being transferred. This involved additions to the main
library files \texttt{global.g} and \texttt{oper.g}. Since there were misgivings about interfering in this way with basic
operations such as \texttt{BIND{\textunderscore}GLOBAL}, a simpler (but slightly less convenient) process has been adopted. 

 Using this alternative procedure, the following steps will be followed when
making transfers from \textsf{Home} to \textsf{Utils}. 
\begin{enumerate}
\item  (\textsf{Home}:) Offer functions for inclusion. This may be simply done by emailing a list
of functions. More usefully, email the declaration, implementation, test and
documentation files, e.g.: \texttt{home.gd}, \texttt{home.gi}, \texttt{home.tst} and \texttt{home.xml}. (All active authors should be involved.) 
\item  (\textsf{Home}:) Declare that \textsc{m.n} is the last version of \textsf{Home} to contain these functions, so that \textsc{m.n+1} (or similar) will be the first version of \textsf{Home} to have all these functions removed, and to specify \textsf{Utils} as a required package. 
\item  (\textsf{Utils}:) Add strings \mbox{\texttt{\mdseries\slshape "home"}} and \mbox{\texttt{\mdseries\slshape "m.n"}} to the list \texttt{UtilsPackageVersions} in the file \texttt{utils/lib/start.gd}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  UtilsPackageVersions := 
    [ "autodoc",     "2016.01.31", 
      "resclasses",  "4.2.5", 
      "home",        "m.n",
      ...,           ... 
    ];
  
\end{Verbatim}
 While the transfers are being made, it is essential that any new versions of \textsf{Home} should be tested with the latest version of \textsf{Utils} before they are released, so as to avoid loading failures. 
\item  (\textsf{Utils}:) Include the function declaration and implementation sections in suitable
files, enclosed within a conditional clause of the form: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  if OKtoReadFromUtils( "Home" ) then
  . . . . . . 
   <the code> 
  . . . . . . 
  fi;
  
\end{Verbatim}
 \index{OKtoReadFromUtils} The function \texttt{OKtoReadFromUtils} returns \texttt{true} only if there is an installed version of \textsf{Home} and if this version is greater than \textsc{m.n}. So, at this stage, \emph{the copied code will not be read}, and the transferred functions can only be called if \textsf{Home} has been installed. 
\item  (\textsf{Utils}:) Add the test and documentation material to the appropriate files. The
copied code can be tested by temporarily moving \textsf{Home} away from \textsf{GAP}'s package directory. 
\item  (\textsf{Utils}:) Release a new version of \textsf{Utils} containing all the transferred material. 
\item  (\textsf{Home}:) Edit out the declarations and implementations of all the transferred
functions, and remove references to them in the manual and tests. Possibly add
a note to the manual that these functions have been transferred. Add \textsf{Utils} to the list of \textsf{Home}'s required packages in \texttt{PackageInfo.g}. Release a new version of \textsf{Home}. 
\item  (\textsf{Utils}:) In due course, when the new version(s) of \textsf{Home} are well established, it may be safe to remove the conditional clauses
mentioned in item 4 above. The entry for \textsf{Home} in \texttt{UtilsPackageLists} may then be removed. 
\end{enumerate}
 

 Finally, a note on the procedure for testing these functions. As long as a
function being transferred still exists in the \textsf{Home} package, the code will not be read from \textsf{Utils}. So, when the tests are run, it is necessary to \texttt{LoadPackage("home")} before the function is called. The file \texttt{utils/tst/testall.g} makes sure that all the necessary packages are loaded before the individual
tests are called. }

 \def\bibname{References\logpage{[ "Bib", 0, 0 ]}
\hyperdef{L}{X7A6F98FD85F02BFE}{}
}

\bibliographystyle{alpha}
\bibliography{bib.xml}

\addcontentsline{toc}{chapter}{References}

\def\indexname{Index\logpage{[ "Ind", 0, 0 ]}
\hyperdef{L}{X83A0356F839C696F}{}
}

\cleardoublepage
\phantomsection
\addcontentsline{toc}{chapter}{Index}


\printindex

\immediate\write\pagenrlog{["Ind", 0, 0], \arabic{page},}
\newpage
\immediate\write\pagenrlog{["End"], \arabic{page}];}
\immediate\closeout\pagenrlog
\end{document}