% 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{ ResClasses \mbox{}}}\\
\vfill

\hypersetup{pdftitle= ResClasses }
\markright{\scriptsize \mbox{}\hfill  ResClasses  \hfill\mbox{}}
{\Huge \textbf{ Set\texttt{\symbol{45}}Theoretic Computations with Residue Classes \mbox{}}}\\
\vfill

{\Huge  4.7.4 \mbox{}}\\[1cm]
{ 24 September 2025 \mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\Large \textbf{ Stefan Kohl\\
   \mbox{}}}\\
\hypersetup{pdfauthor= Stefan Kohl\\
   }
\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{ Stefan Kohl\\
   }  Email: \href{mailto://sk239@st-andrews.ac.uk} {\texttt{sk239@st\texttt{\symbol{45}}andrews.ac.uk}}\\
  Homepage: \href{https://stefan-kohl.github.io/} {\texttt{https://stefan\texttt{\symbol{45}}kohl.github.io/}}}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Abstract}
\logpage{[ 0, 0, 1 ]}
      \textsf{ResClasses} is a package for \textsf{GAP} 4 which provides a fully\texttt{\symbol{45}}featured and
easy\texttt{\symbol{45}}to\texttt{\symbol{45}}use implementation of
set\texttt{\symbol{45}}theoretic unions of residue classes of the integers and
of a few other rings. 

 The class of sets which \textsf{ResClasses} can deal with includes the open and the closed sets in the topology on the
respective ring which is induced by taking the set of all residue classes as a
basis, as far as the usual restrictions imposed by the finiteness of computing
resources permit this. 

 The package further provides slightly more specialized functionality for
unions of residue classes with distinguished representatives and signed
moduli. 

 The \textsf{ResClasses} package is used in a group theoretical context by the \textsf{RCWA} package{\nobreakspace}\cite{RCWA}.  \mbox{}}\\[1cm]
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 2 ]}
 {\copyright} 2003 \texttt{\symbol{45}} 2017 by Stefan Kohl. 

 \textsf{ResClasses} 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. 

 \textsf{ResClasses} is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details. 

 For a copy of the GNU General Public License, see the file \texttt{GPL} in the \texttt{etc} directory of the \textsf{GAP} distribution or see \href{https://www.gnu.org/licenses/gpl.html} {\texttt{https://www.gnu.org/licenses/gpl.html}}. \mbox{}}\\[1cm]
\newpage

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

\tableofcontents
\newpage

      
\chapter{\textcolor{Chapter }{Set\texttt{\symbol{45}}Theoretic Unions of Residue Classes}}\label{ch:UnionsOfResidueClasses}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X815A3DDE7C0BC44A}{}
{
    
\section{\textcolor{Chapter }{Entering residue classes and set\texttt{\symbol{45}}theoretic unions thereof}}\label{sec:DefiningUnionsOfResidueClasses}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X7E16A64485A7AB79}{}
{
  

\subsection{\textcolor{Chapter }{ResidueClass (by ring, modulus and residue)}}
\logpage{[ 1, 1, 1 ]}\nobreak
\hyperdef{L}{X8753CC098447BE0D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClass({\mdseries\slshape R, m, r})\index{ResidueClass@\texttt{ResidueClass}!by ring, modulus and residue}
\label{ResidueClass:by ring, modulus and residue}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClass({\mdseries\slshape m, r})\index{ResidueClass@\texttt{ResidueClass}!by modulus and residue}
\label{ResidueClass:by modulus and residue}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClass({\mdseries\slshape r, m})\index{ResidueClass@\texttt{ResidueClass}!by residue and modulus}
\label{ResidueClass:by residue and modulus}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 in the three\texttt{\symbol{45}}argument form the residue class \mbox{\texttt{\mdseries\slshape r}}{\nobreakspace}mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}} of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}, and in the two\texttt{\symbol{45}}argument form the residue class \mbox{\texttt{\mdseries\slshape r}}{\nobreakspace}mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}} of the ``default ring'' ($\rightarrow$ \texttt{DefaultRing} in the \textsf{GAP} Reference Manual) of the arguments. 



 In the two\texttt{\symbol{45}}argument case, \mbox{\texttt{\mdseries\slshape m}} is taken to be the larger and \mbox{\texttt{\mdseries\slshape r}} is taken to be the smaller of the arguments. For convenience, it is permitted
to enclose the argument list in list brackets. 

 \index{IsResidueClass@\texttt{IsResidueClass}} \index{Modulus@\texttt{Modulus}!of a residue class} \index{Residue@\texttt{Residue}!of a residue class} Residue classes have the property \texttt{IsResidueClass}. Rings are regarded as residue class 0{\nobreakspace}(mod{\nobreakspace}1),
and therefore have this property. There are operations \texttt{Modulus} and \texttt{Residue} to retrieve the modulus{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}} resp. residue{\nobreakspace}\mbox{\texttt{\mdseries\slshape r}} of a residue class. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ResidueClass(2,3);|
  The residue class 2(3) of Z
  !gapprompt@gap>| !gapinput@ResidueClass(Z_pi([2,5]),2,1);|
  The residue class 1(2) of Z_( 2, 5 )
  !gapprompt@gap>| !gapinput@R := PolynomialRing(GF(2),1);;|
  !gapprompt@gap>| !gapinput@x := Indeterminate(GF(2),1);; SetName(x,"x");|
  !gapprompt@gap>| !gapinput@ResidueClass(R,x+One(R),Zero(R));|
  The residue class 0 ( mod x+1 ) of GF(2)[x]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{ResidueClassUnion (by ring, modulus and residues)}}
\logpage{[ 1, 1, 2 ]}\nobreak
\hyperdef{L}{X85327C777F32DA8F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClassUnion({\mdseries\slshape R, m, r})\index{ResidueClassUnion@\texttt{ResidueClassUnion}!by ring, modulus and residues}
\label{ResidueClassUnion:by ring, modulus and residues}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClassUnion({\mdseries\slshape R, m, r, included, excluded})\index{ResidueClassUnion@\texttt{ResidueClassUnion}!by ring, modulus, residues and included / excluded elements}
\label{ResidueClassUnion:by ring, modulus, residues and included / excluded elements}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClassUnion({\mdseries\slshape R, cls})\index{ResidueClassUnion@\texttt{ResidueClassUnion}!by ring and list of classes}
\label{ResidueClassUnion:by ring and list of classes}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClassUnion({\mdseries\slshape R, cls, included, excluded})\index{ResidueClassUnion@\texttt{ResidueClassUnion}!by ring, list of classes and included / excluded elements}
\label{ResidueClassUnion:by ring, list of classes and included / excluded elements}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 in the first two cases, the union of the residue classes \mbox{\texttt{\mdseries\slshape r}}[$i$]{\nobreakspace}mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}} of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}, plus / minus finite sets \mbox{\texttt{\mdseries\slshape included}} and \mbox{\texttt{\mdseries\slshape excluded}} of elements of{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}. In the last two cases, the union of the residue classes \mbox{\texttt{\mdseries\slshape cls}}[$i$][1]{\nobreakspace}mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape cls}}[$i$][2] of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}={\ensuremath{\mathbb Z}}, plus / minus finite sets \mbox{\texttt{\mdseries\slshape included}} and \mbox{\texttt{\mdseries\slshape excluded}} of integers. 



 For unions of residue classes of the integers, two distinct representations
are implemented: in the first representation, a union of residue classes is
represented by its modulus \mbox{\texttt{\mdseries\slshape m}} and the list of residues \mbox{\texttt{\mdseries\slshape r}}; this is called the ``standard'' representation. In the second (``sparse'') representation, a union of residue classes $r_1(m_1) \cup \dots \cup r_k(m_k)$ is represented by the list \mbox{\texttt{\mdseries\slshape cls}} of the pairs \texttt{[r{\textunderscore}i,m{\textunderscore}i]}. \index{StandardRep@\texttt{StandardRep}!for a residue class union} \index{SparseRep@\texttt{SparseRep}!for a residue class union} One can switch between the two representations by using the operations \texttt{StandardRep} and \texttt{SparseRep}, respectively. The sparse representation allows more efficient computation in
terms of time\texttt{\symbol{45}} and memory requirements when computing with
unions of ``relatively few'' residue classes where the lcm of the moduli is ``large''; otherwise the standard representation is advantageous. For rings other than
{\ensuremath{\mathbb Z}}, presently only the standard representation is
available. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ResidueClassUnion(Integers,5,[1,2],[3,8],[-4,1]);|
  (Union of the residue classes 1(5) and 2(5) of Z) U [ 3, 8 ] \ [ -4, 1 ]
  !gapprompt@gap>| !gapinput@ResidueClassUnion(Integers,[[1,2],[0,40],[2,1200]]);|
  Union of the residue classes 1(2), 0(40) and 2(1200) of Z
  !gapprompt@gap>| !gapinput@ResidueClassUnion(Z_pi([2,3]),8,[3,5]);|
  Union of the residue classes 3(8) and 5(8) of Z_( 2, 3 )
  !gapprompt@gap>| !gapinput@ResidueClassUnion(R,x^2,[One(R),x],[],[One(R)]);|
  <union of 2 residue classes (mod x^2) of GF(2)[x]> \ [ 1 ]
  
\end{Verbatim}
 }

 \index{residue class union@residue class union!definition} When talking about a \emph{residue class union} in this chapter, we always mean an object as it is returned by this function. 

 \index{Modulus@\texttt{Modulus}!of a residue class union} \index{Residues@\texttt{Residues}!of a residue class union} \index{IncludedElements@\texttt{IncludedElements}!of a residue class union} \index{ExcludedElements@\texttt{ExcludedElements}!of a residue class union} There are operations \texttt{Modulus}, \texttt{Residues}, \texttt{IncludedElements} and \texttt{ExcludedElements} to retrieve the components of a residue class union as they have originally
been passed as arguments to \texttt{ResidueClassUnion} (\ref{ResidueClassUnion:by ring, modulus and residues}). 

 \index{ResidueClassUnionViewingFormat@\texttt{ResidueClassUnionViewingFormat}} The user has the choice between a longer and more descriptive and a shorter
and less bulky output format for residue classes and unions thereof: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ResidueClassUnionViewingFormat("short");|
  !gapprompt@gap>| !gapinput@ResidueClassUnion(Integers,12,[0,1,4,7,8]);|
  0(4) U 1(6)
  !gapprompt@gap>| !gapinput@ResidueClassUnionViewingFormat("long");|
  !gapprompt@gap>| !gapinput@ResidueClassUnion(Integers,12,[0,1,4,7,8]);|
  Union of the residue classes 0(4) and 1(6) of Z
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{AllResidueClassesModulo (of a given ring, modulo a given modulus)}}
\logpage{[ 1, 1, 3 ]}\nobreak
\hyperdef{L}{X8326D6F285081E0F}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllResidueClassesModulo({\mdseries\slshape R, m})\index{AllResidueClassesModulo@\texttt{AllResidueClassesModulo}!of a given ring, modulo a given modulus}
\label{AllResidueClassesModulo:of a given ring, modulo a given modulus}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllResidueClassesModulo({\mdseries\slshape m})\index{AllResidueClassesModulo@\texttt{AllResidueClassesModulo}!by modulus, of the default ring of that modulus}
\label{AllResidueClassesModulo:by modulus, of the default ring of that modulus}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a sorted list of all residue classes (mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}}) of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}. 



 If the argument \mbox{\texttt{\mdseries\slshape R}} is omitted it defaults to the default ring of \mbox{\texttt{\mdseries\slshape m}} \texttt{\symbol{45}}\texttt{\symbol{45}} cf. the documentation of \texttt{DefaultRing} in the \textsf{GAP} reference manual. \index{AllResidues@\texttt{AllResidues}!for ring and modulus} \index{NumberOfResidues@\texttt{NumberOfResidues}!for ring and modulus} \index{NrResidues@\texttt{NrResidues}!for ring and modulus} A transversal for the residue classes (mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}}) can be obtained by the operation \texttt{AllResidues(\mbox{\texttt{\mdseries\slshape R}},\mbox{\texttt{\mdseries\slshape m}})}, and their number can be determined by the operation \texttt{NumberOfResidues(\mbox{\texttt{\mdseries\slshape R}},\mbox{\texttt{\mdseries\slshape m}})}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@AllResidueClassesModulo(Integers,2);|
  [ The residue class 0(2) of Z, The residue class 1(2) of Z ]
  !gapprompt@gap>| !gapinput@AllResidueClassesModulo(Z_pi(2),2);|
  [ The residue class 0(2) of Z_( 2 ), The residue class 1(2) of Z_( 2 ) ]
  !gapprompt@gap>| !gapinput@AllResidueClassesModulo(R,x);|
  [ The residue class 0 ( mod x ) of GF(2)[x], 
    The residue class 1 ( mod x ) of GF(2)[x] ]
  !gapprompt@gap>| !gapinput@AllResidues(R,x^3);|
  [ 0, 1, x, x+1, x^2, x^2+1, x^2+x, x^2+x+1 ]
  !gapprompt@gap>| !gapinput@NumberOfResidues(Z_pi([2,3]),360);|
  72
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{Methods for residue class unions}}\label{sec:MethodsForResidueClassUnions}
\logpage{[ 1, 2, 0 ]}
\hyperdef{L}{X7A3FA13187CEADED}{}
{
  \index{Print@\texttt{Print}!for a residue class union} \index{String@\texttt{String}!for a residue class union} \index{Display@\texttt{Display}!for a residue class union} There are methods for \texttt{Print}, \texttt{String} and \texttt{Display} which are applicable to residue class unions. There is a method for \texttt{in} which tests whether some ring element lies in a given residue class union. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Print(ResidueClass(1,2),"\n");|
  ResidueClassUnion( Integers, 2, [ 1 ] )
  !gapprompt@gap>| !gapinput@1 in ResidueClass(1,2);|
  true
  
\end{Verbatim}
 \index{Union@\texttt{Union}!for residue class unions} \index{Intersection@\texttt{Intersection}!for residue class unions} \index{Difference@\texttt{Difference}!for residue class unions} \index{IsSubset@\texttt{IsSubset}!for residue class unions} There are methods for \texttt{Union}, \texttt{Intersection}, \texttt{Difference} and \texttt{IsSubset} available for residue class unions. They also accept finite subsets of the
base ring as arguments. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@S := Union(ResidueClass(0,2),ResidueClass(0,3));|
  Z \ Union of the residue classes 1(6) and 5(6) of Z
  !gapprompt@gap>| !gapinput@Intersection(S,ResidueClass(0,7));|
  Union of the residue classes 0(14) and 21(42) of Z
  !gapprompt@gap>| !gapinput@Difference(S,ResidueClass(2,4));|
  Union of the residue classes 0(4) and 3(6) of Z
  !gapprompt@gap>| !gapinput@IsSubset(ResidueClass(0,2),ResidueClass(4,8));|
  true
  !gapprompt@gap>| !gapinput@Union(S,[1..10]);|
  (Union of the residue classes 0(2) and 3(6) of Z) U [ 1, 5, 7 ]
  !gapprompt@gap>| !gapinput@Intersection(S,[1..6]);|
  [ 2, 3, 4, 6 ]
  !gapprompt@gap>| !gapinput@Difference(S,[1..6]);|
  (Union of the residue classes 0(2) and 3(6) of Z) \ [ 2, 3, 4, 6 ]
  !gapprompt@gap>| !gapinput@Difference(Integers,[1..10]);|
  Z \ <set of cardinality 10>
  !gapprompt@gap>| !gapinput@IsSubset(S,[1..10]);|
  false
  
\end{Verbatim}
 If the underlying ring has a residue class ring of a given
cardinality{\nobreakspace}$t$, then a residue class can be written as a disjoint union of $t$ residue classes with equal moduli: 

\subsection{\textcolor{Chapter }{SplittedClass (for a residue class and a number of parts)}}
\logpage{[ 1, 2, 1 ]}\nobreak
\hyperdef{L}{X854315A2877B69A7}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SplittedClass({\mdseries\slshape cl, t})\index{SplittedClass@\texttt{SplittedClass}!for a residue class and a number of parts}
\label{SplittedClass:for a residue class and a number of parts}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a partition of the residue class \mbox{\texttt{\mdseries\slshape cl}} into \mbox{\texttt{\mdseries\slshape t}} residue classes with equal moduli, provided that such a partition exists.
Otherwise \texttt{fail}. 



 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@SplittedClass(ResidueClass(1,2),2);|
  [ The residue class 1(4) of Z, The residue class 3(4) of Z ]
  !gapprompt@gap>| !gapinput@SplittedClass(ResidueClass(Z_pi(3),3,0),2);|
  fail
  
\end{Verbatim}
 }

 Often one needs a partition of a given residue class union into ``few'' residue classes. The following operation takes care of this: 

\subsection{\textcolor{Chapter }{AsUnionOfFewClasses (for a residue class union)}}
\logpage{[ 1, 2, 2 ]}\nobreak
\hyperdef{L}{X87C166FE7FA17325}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AsUnionOfFewClasses({\mdseries\slshape U})\index{AsUnionOfFewClasses@\texttt{AsUnionOfFewClasses}!for a residue class union}
\label{AsUnionOfFewClasses:for a residue class union}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a set of disjoint residue classes whose union is equal to{\nobreakspace}\mbox{\texttt{\mdseries\slshape U}}, up to the finite sets \texttt{IncludedElements(\mbox{\texttt{\mdseries\slshape U}})} and \texttt{ExcludedElements(\mbox{\texttt{\mdseries\slshape U}})}. 



 As the name of the operation suggests, it is taken care that the number of
residue classes in the returned list is kept ``reasonably small''. It is not guaranteed that it is minimal. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ResidueClassUnionViewingFormat("short");|
  !gapprompt@gap>| !gapinput@AsUnionOfFewClasses(Difference(Integers,ResidueClass(0,30)));|
  [ 1(2), 2(6), 4(6), 6(30), 12(30), 18(30), 24(30) ]
  !gapprompt@gap>| !gapinput@Union(last);|
  Z \ 0(30)
  
\end{Verbatim}
 }

 One can compute the sets of sums, differences, products and quotients of the
elements of a residue class union and an element of the base ring: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ResidueClass(0,2) + 1;|
  1(2)
  !gapprompt@gap>| !gapinput@ResidueClass(0,2) - 2 = ResidueClass(0,2);|
  true
  !gapprompt@gap>| !gapinput@3 * ResidueClass(0,2);|
  0(6)
  !gapprompt@gap>| !gapinput@ResidueClass(0,2)/2;|
  Integers
  
\end{Verbatim}
 

\subsection{\textcolor{Chapter }{PartitionsIntoResidueClasses (of a given ring, of given length)}}
\logpage{[ 1, 2, 3 ]}\nobreak
\hyperdef{L}{X8079E174813646DA}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PartitionsIntoResidueClasses({\mdseries\slshape R, length})\index{PartitionsIntoResidueClasses@\texttt{PartitionsIntoResidueClasses}!of a given ring, of given length}
\label{PartitionsIntoResidueClasses:of a given ring, of given length}
}\hfill{\scriptsize (operation)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{PartitionsIntoResidueClasses({\mdseries\slshape R, length, primes})\index{PartitionsIntoResidueClasses@\texttt{PartitionsIntoResidueClasses}!of a given ring, of given length, with moduli with given factors}
\label{PartitionsIntoResidueClasses:of a given ring, of given length, with moduli with given factors}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 in the 2\texttt{\symbol{45}}argument version a sorted list of all partitions
of the ring \mbox{\texttt{\mdseries\slshape R}} into \mbox{\texttt{\mdseries\slshape length}} residue classes. In the 3\texttt{\symbol{45}}argument version a sorted list of
all partitions of the ring \mbox{\texttt{\mdseries\slshape R}} into \mbox{\texttt{\mdseries\slshape length}} residue classes whose moduli have only prime factors in the list \mbox{\texttt{\mdseries\slshape primes}}. 



 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@PartitionsIntoResidueClasses(Integers,4);|
  [ [ 0(2), 1(4), 3(8), 7(8) ], [ 0(2), 3(4), 1(8), 5(8) ], 
    [ 0(2), 1(6), 3(6), 5(6) ], [ 1(2), 0(4), 2(8), 6(8) ], 
    [ 1(2), 2(4), 0(8), 4(8) ], [ 1(2), 0(6), 2(6), 4(6) ], 
    [ 0(3), 1(3), 2(6), 5(6) ], [ 0(3), 2(3), 1(6), 4(6) ], 
    [ 1(3), 2(3), 0(6), 3(6) ], [ 0(4), 1(4), 2(4), 3(4) ] ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{RandomPartitionIntoResidueClasses (of a given ring, of given length)}}
\logpage{[ 1, 2, 4 ]}\nobreak
\hyperdef{L}{X8653860F7ADA4D38}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RandomPartitionIntoResidueClasses({\mdseries\slshape R, length, primes})\index{RandomPartitionIntoResidueClasses@\texttt{RandomPartitionIntoResidueClasses}!of a given ring, of given length}
\label{RandomPartitionIntoResidueClasses:of a given ring, of given length}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 a ``random'' partition of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}} into \mbox{\texttt{\mdseries\slshape length}} residue classes whose moduli have only prime factors in \mbox{\texttt{\mdseries\slshape primes}}, respectively \texttt{fail} if no such partition exists. 



 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@RandomPartitionIntoResidueClasses(Integers,30,[2,3,5,7]);|
  [ 0(7), 2(7), 5(7), 3(14), 10(14), 1(21), 8(21), 15(21), 18(21), 20(21), 
    6(63), 13(63), 25(63), 27(63), 32(63), 34(63), 46(63), 48(63), 53(63), 
    55(63), 4(126), 67(126), 137(189), 74(567), 200(567), 263(567), 
    389(567), 452(567), 11(1134), 578(1134) ]
  !gapprompt@gap>| !gapinput@Union(last);|
  Integers
  !gapprompt@gap>| !gapinput@Sum(List(last2,Density));|
  1
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{CoverByResidueClasses (of the integers, by residue classes with given moduli)}}
\logpage{[ 1, 2, 5 ]}\nobreak
\hyperdef{L}{X7BAF36BF7A276D46}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CoverByResidueClasses({\mdseries\slshape Integers, moduli})\index{CoverByResidueClasses@\texttt{CoverByResidueClasses}!of the integers, by residue classes with given moduli}
\label{CoverByResidueClasses:of the integers, by residue classes with given moduli}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{CoversByResidueClasses({\mdseries\slshape Integers, moduli})\index{CoversByResidueClasses@\texttt{CoversByResidueClasses}!of the integers, by residue classes with given moduli}
\label{CoversByResidueClasses:of the integers, by residue classes with given moduli}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 in the first form a cover of the integers by residue classes with moduli \mbox{\texttt{\mdseries\slshape moduli}} if such cover exists, and \texttt{fail} otherwise; in the second form a list of all covers of the integers by residue
classes with moduli \mbox{\texttt{\mdseries\slshape moduli}}. 



 Since there are often very many such covers, computing all of them can take a
lot of time and memory. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@CoverByResidueClasses(Integers,[2,3,4,6,8,12]);|
  [ 0(2), 0(3), 1(4), 1(6), 3(8), 11(12) ]
  !gapprompt@gap>| !gapinput@Union(last);|
  Integers
  !gapprompt@gap>| !gapinput@CoversByResidueClasses(Integers,[2,3,3,6]);|
  [ [ 0(2), 0(3), 1(3), 5(6) ], [ 0(2), 0(3), 2(3), 1(6) ], 
    [ 0(2), 1(3), 2(3), 3(6) ], [ 1(2), 0(3), 1(3), 2(6) ], 
    [ 1(2), 0(3), 2(3), 4(6) ], [ 1(2), 1(3), 2(3), 0(6) ] ]
  !gapprompt@gap>| !gapinput@List(last,Union);|
  [ Integers, Integers, Integers, Integers, Integers, Integers ]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Density (of a residue class union)}}
\logpage{[ 1, 2, 6 ]}\nobreak
\hyperdef{L}{X791C16E77BE97FE3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Density({\mdseries\slshape U})\index{Density@\texttt{Density}!of a residue class union}
\label{Density:of a residue class union}
}\hfill{\scriptsize (operation)}}\\
\textbf{\indent Returns:\ }
 the natural density of{\nobreakspace}\mbox{\texttt{\mdseries\slshape U}} as a subset of the underlying ring. 



 The \emph{natural density} of a residue class $r(m)$ of a ring{\nobreakspace}$R$ is defined by $1/|R/mR|$, and the \emph{natural density} of a union{\nobreakspace}$U$ of finitely many residue classes is defined by the sum of the densities of the
elements of a partition of{\nobreakspace}$U$ into finitely many residue classes. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@Density(ResidueClass(0,2));|
  1/2
  !gapprompt@gap>| !gapinput@Density(Difference(Integers,ResidueClass(0,5)));|
  4/5
  
\end{Verbatim}
 }

 \index{Iterator@\texttt{Iterator}!for a residue class union} \index{NextIterator@\texttt{NextIterator}!for an iterator of a residue class union} For looping over residue class unions of the integers, there are methods for
the operations \texttt{Iterator} and \texttt{NextIterator}. }

  
\section{\textcolor{Chapter }{On residue class unions of ${\ensuremath{\mathbb Z}}^2$}}\label{sec:ResidueClassUnionsOfZxZ}
\logpage{[ 1, 3, 0 ]}
\hyperdef{L}{X7921D4368632E15C}{}
{
  Residue class unions of ${\ensuremath{\mathbb Z}}^2$ are treated similar as those of any other ring. Also there is roughly the same
functionality available for them. However there are some differences and a few
additional features, which are described in this section. 

 The elements of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ are represented as lists of length{\nobreakspace}2 with integer entries. The
modulus of a residue class union of ${\ensuremath{\mathbb Z}}^2$ is a lattice. This lattice is stored as a $2 \times 2$ integer matrix of full rank in Hermite normal form, whose rows are the
spanning vectors. Residue classes of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ modulo principal ideals are presently not implemented. Residue class unions
of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ can be multiplied by matrices of full rank from the right. A snippet of a
residue class union of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$ is shown in ``ASCII art'' when one \texttt{Display}'s it with option \texttt{AsGrid}. We give some illustrative examples: 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@R := Integers^2;|
  ( Integers^2 )
  !gapprompt@gap>| !gapinput@5*R+[2,3];|
  (2,3)+(5,0)Z+(0,5)Z
  !gapprompt@gap>| !gapinput@Difference(R,last);|
  Z^2 \ (2,3)+(5,0)Z+(0,5)Z
  !gapprompt@gap>| !gapinput@Density(last);|
  24/25
  !gapprompt@gap>| !gapinput@L1 := [[2,1],[-1,2]];;|
  !gapprompt@gap>| !gapinput@L2 := [[6,2],[0,6]];;|
  !gapprompt@gap>| !gapinput@AllResidueClassesModulo(R,L1); # The modulus is transformed to HNF.|
  [ (0,0)+(1,3)Z+(0,5)Z, (0,1)+(1,3)Z+(0,5)Z, (0,2)+(1,3)Z+(0,5)Z,
    (0,3)+(1,3)Z+(0,5)Z, (0,4)+(1,3)Z+(0,5)Z ]
  !gapprompt@gap>| !gapinput@cl1 := ResidueClass(R,L1,[0,0]);|
  (0,0)+(1,3)Z+(0,5)Z
  !gapprompt@gap>| !gapinput@cl2 := ResidueClass(R,L2,[0,0]);|
  (0,0)+(6,2)Z+(0,6)Z
  !gapprompt@gap>| !gapinput@cl3 := Intersection(cl1,cl2);|
  (0,0)+(6,8)Z+(0,30)Z
  !gapprompt@gap>| !gapinput@S1 := Difference(cl1,cl2);|
  <union of 35 residue classes (mod (6,8)Z+(0,30)Z)>
  !gapprompt@gap>| !gapinput@S2 := Difference(cl2,cl1);|
  <union of 4 residue classes (mod (6,8)Z+(0,30)Z)>
  !gapprompt@gap>| !gapinput@Display(S1); # The set is written as union of "few" residue classes:|
  (0,5)+(1,3)Z+(0,10)Z U (1,3)+(2,6)Z+(0,10)Z U (2,6)+(6,8)Z+(0,10)Z U
  (4,2)+(6,8)Z+(0,10)Z U (0,10)+(6,8)Z+(0,30)Z U (0,20)+(6,8)Z+(0,30)Z
  !gapprompt@gap>| !gapinput@Display(S2);|
  (0,6)+(6,8)Z+(0,30)Z U (0,12)+(6,8)Z+(0,30)Z U (0,18)+(6,8)Z+(0,30)Z
   U (0,24)+(6,8)Z+(0,30)Z
  !gapprompt@gap>| !gapinput@cls := AsUnionOfFewClasses(S1);|
  [ (0,5)+(1,3)Z+(0,10)Z, (1,3)+(2,6)Z+(0,10)Z, (2,6)+(6,8)Z+(0,10)Z,
    (4,2)+(6,8)Z+(0,10)Z, (0,10)+(6,8)Z+(0,30)Z, (0,20)+(6,8)Z+(0,30)Z ]
  !gapprompt@gap>| !gapinput@Union(cls) = S1;|
  true
  !gapprompt@gap>| !gapinput@S3 := S1*[[3,5],[2,4]];|
  <union of 35 residue classes (mod (2,46)Z+(0,180)Z)>
  !gapprompt@gap>| !gapinput@Display(S1:AsGrid);|
      *    *    *    *    *    *    *    *    *    *    *    *    *    *
   *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
     *    *    *    *    *    *    *    *    *    *    *    *    *    *
  *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
    *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
      *    *    *    *         *    *    *    *    *         *    *    *
   *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
     *    *    *    *    *    *    *    *    *    *    *    *    *    *
  *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
    *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
      *    *    *    *    *    *    *    *    *    *    *    *    *    *
   *    *    *         *    *    *    *    *         *    *    *    *    *
     *    *    *    *    *    *    *    *    *    *    *    *    *    *
  *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
    *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
      *    *    *    *    *    *    *    *    *    *    *    *    *    *
   *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
     *         *    *    *    *    *         *    *    *    *    *
  *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
    *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
      *    *    *    *    *    *    *    *    *    *    *    *    *    *
   *    *    *    *    *    *    *    *    *    *    *    *    *    *    *
     *    *    *    *    *    *    *    *    *    *    *    *    *    *
       *    *    *    *    *         *    *    *    *    *         *    *
  
\end{Verbatim}
 Note that in \textsf{GAP} multiplying lists of integers means computing their scalar product as vectors.
The consequence is that technically the free module ${\ensuremath{\mathbb Z}}^2$ is not a ring in \textsf{GAP}. }

  
\section{\textcolor{Chapter }{The categories and families of residue class unions}}\label{sec:CategoriesOfResidueClassUnions}
\logpage{[ 1, 4, 0 ]}
\hyperdef{L}{X7B26BB1C7C8495A5}{}
{
  

\subsection{\textcolor{Chapter }{IsResidueClassUnion}}
\logpage{[ 1, 4, 1 ]}\nobreak
\hyperdef{L}{X7EA29BBD82552352}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsResidueClassUnion({\mdseries\slshape U})\index{IsResidueClassUnion@\texttt{IsResidueClassUnion}}
\label{IsResidueClassUnion}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsResidueClassUnionOfZ({\mdseries\slshape U})\index{IsResidueClassUnionOfZ@\texttt{IsResidueClassUnionOfZ}}
\label{IsResidueClassUnionOfZ}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsResidueClassUnionOfZxZ({\mdseries\slshape U})\index{IsResidueClassUnionOfZxZ@\texttt{IsResidueClassUnionOfZxZ}}
\label{IsResidueClassUnionOfZxZ}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsResidueClassUnionOfZ{\textunderscore}pi({\mdseries\slshape U})\index{IsResidueClassUnionOfZ{\textunderscore}pi@\texttt{IsResidue}\-\texttt{Class}\-\texttt{Union}\-\texttt{Of}\-\texttt{Z{\textunderscore}pi}}
\label{IsResidueClassUnionOfZuScorepi}
}\hfill{\scriptsize (filter)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{IsResidueClassUnionOfGFqx({\mdseries\slshape U})\index{IsResidueClassUnionOfGFqx@\texttt{IsResidueClassUnionOfGFqx}}
\label{IsResidueClassUnionOfGFqx}
}\hfill{\scriptsize (filter)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if \mbox{\texttt{\mdseries\slshape U}} is a residue class union, a residue class union
of{\nobreakspace}{\ensuremath{\mathbb Z}}, a residue class union
of{\nobreakspace}${\ensuremath{\mathbb Z}}^2$, a residue class union of a semilocalization
of{\nobreakspace}{\ensuremath{\mathbb Z}} or a residue class union of a
polynomial ring in one variable over a finite field, respectively, and \texttt{false} otherwise. 



 Often the same methods can be used for residue class unions of the ring of
integers and of its semilocalizations. For this reason, there is a category \texttt{IsResidueClassUnionOfZorZ{\textunderscore}pi} which is the union of \texttt{IsResidueClassUnionOfZ} and \texttt{IsResidueClassUnionOfZ{\textunderscore}pi}. \index{IsResidueClassUnionOfZ_pi@\texttt{IsResidueClassUnionOfZ{\textunderscore}pi}} The internal representation of residue class unions is called \texttt{IsResidueClassUnionResidueListRep}. \index{IsResidueClassUnionResidueListRep@\texttt{IsResidueClassUnionResidueListRep}} There are methods available for \texttt{ExtRepOfObj} and \texttt{ObjByExtRep}. \index{ExtRepOfObj@\texttt{ExtRepOfObj}} \index{ObjByExtRep@\texttt{ObjByExtRep}} }

 

\subsection{\textcolor{Chapter }{ResidueClassUnionsFamily (of a ring)}}
\logpage{[ 1, 4, 2 ]}\nobreak
\hyperdef{L}{X7F9BCB1A797F8F48}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClassUnionsFamily({\mdseries\slshape R})\index{ResidueClassUnionsFamily@\texttt{ResidueClassUnionsFamily}!of a ring}
\label{ResidueClassUnionsFamily:of a ring}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClassUnionsFamily({\mdseries\slshape R, fixedreps})\index{ResidueClassUnionsFamily@\texttt{ResidueClassUnionsFamily}!of a ring, with fixed representatives}
\label{ResidueClassUnionsFamily:of a ring, with fixed representatives}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the family of residue class unions or the family of unions of residue classes
with fixed representatives of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}, depending on whether \mbox{\texttt{\mdseries\slshape fixedreps}} is present and \texttt{true} or not. 



 The ring \mbox{\texttt{\mdseries\slshape R}} can be retrieved as \texttt{UnderlyingRing(ResidueClassUnionsFamily(\mbox{\texttt{\mdseries\slshape R}}))}. \index{residue class union@residue class union!coercion} There is no coercion between residue class unions or unions of residue classes
with fixed representatives which belong to different families. Unions of
residue classes with fixed representatives are described in the next chapter. }

 }

  }

       
\chapter{\textcolor{Chapter }{Unions of Residue Classes with Fixed Representatives}}\label{ch:UnionsOfResidueClassesWithFixedReps}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X87871B5A86254179}{}
{
   \textsf{ResClasses} supports computations with unions of residue classes which are endowed with
distinguished (``fixed'') representatives. These unions of residue classes can be viewed as multisets
of ring elements. The residue classes forming such a union do not need to be
disjoint or even only distinct.  
\section{\textcolor{Chapter }{ Entering unions of residue classes with fixed representatives }}\label{sec:DefiningUnionsOfResidueClassesWithFixedReps}
\logpage{[ 2, 1, 0 ]}
\hyperdef{L}{X78BE0FA38691B1B6}{}
{
  

\subsection{\textcolor{Chapter }{ResidueClassWithFixedRepresentative (by ring, modulus and residue)}}
\logpage{[ 2, 1, 1 ]}\nobreak
\hyperdef{L}{X831C976D876FDAD3}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClassWithFixedRepresentative({\mdseries\slshape R, m, r})\index{ResidueClassWithFixedRepresentative@\texttt{ResidueClassWithFixedRepresentative}!by ring, modulus and residue}
\label{ResidueClassWithFixedRepresentative:by ring, modulus and residue}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResidueClassWithFixedRepresentative({\mdseries\slshape m, r})\index{ResidueClassWithFixedRepresentative@\texttt{ResidueClassWithFixedRepresentative}!of Z, by modulus and residue}
\label{ResidueClassWithFixedRepresentative:of Z, by modulus and residue}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the residue class \mbox{\texttt{\mdseries\slshape r}}{\nobreakspace}mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}} of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}, with the fixed representative{\nobreakspace}\mbox{\texttt{\mdseries\slshape r}}. 



 If the argument \mbox{\texttt{\mdseries\slshape R}} is omitted, it defaults to \texttt{Integers}. \index{IsResidueClassWithFixedRep@\texttt{IsResidueClassWithFixedRep}} Residue classes with fixed representatives have the property \texttt{IsResidueClassWithFixedRepresentative}. The fixed representative{\nobreakspace}\mbox{\texttt{\mdseries\slshape r}} can be retrieved by the operation \texttt{Residue}, and the modulus{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}} can be retrieved by the operation \texttt{Modulus}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@ResidueClassWithFixedRepresentative(Integers,2,1);|
  [1/2]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{UnionOfResidueClassesWithFixedReps (by ring and list of classes)}}
\logpage{[ 2, 1, 2 ]}\nobreak
\hyperdef{L}{X871ED1D17AE52A95}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UnionOfResidueClassesWithFixedReps({\mdseries\slshape R, classes})\index{UnionOfResidueClassesWithFixedReps@\texttt{UnionOfResidueClassesWithFixedReps}!by ring and list of classes}
\label{UnionOfResidueClassesWithFixedReps:by ring and list of classes}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{UnionOfResidueClassesWithFixedReps({\mdseries\slshape classes})\index{UnionOfResidueClassesWithFixedReps@\texttt{UnionOfResidueClassesWithFixedReps}!of Z, by list of classes}
\label{UnionOfResidueClassesWithFixedReps:of Z, by list of classes}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the union of the residue classes \mbox{\texttt{\mdseries\slshape classes}}[$i$][2] mod \mbox{\texttt{\mdseries\slshape classes}}[$i$][1] of the ring \mbox{\texttt{\mdseries\slshape R}}, with fixed representatives \mbox{\texttt{\mdseries\slshape classes}}[$i$][2]. 



 The argument \mbox{\texttt{\mdseries\slshape classes}} must be a list of pairs of elements of the ring \mbox{\texttt{\mdseries\slshape R}}. Their first entries \texttt{\symbol{45}}\texttt{\symbol{45}} the moduli
\texttt{\symbol{45}}\texttt{\symbol{45}} must be nonzero. If the argument \mbox{\texttt{\mdseries\slshape R}} is omitted, it defaults to \texttt{Integers}. \pagebreak[4] 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@UnionOfResidueClassesWithFixedReps(Integers,[[2,4],[3,9]]);|
  [4/2] U [9/3]
  
\end{Verbatim}
 }

 \index{Modulus@\texttt{Modulus}!of a union of residue classes with fixed rep's} \index{Classes@\texttt{Classes}!of a union of residue classes with fixed rep's} \index{AsListOfClasses@\texttt{AsListOfClasses}!for a union of residue classes with fixed rep's} There is a method for the operation \texttt{Modulus} which returns the lcm of the moduli of the residue classes forming such a
union. Further there is an operation \texttt{Classes} for retrieving the list of classes which has been passed as an argument to \texttt{UnionOfResidueClassesWithFixedReps}. The operation \texttt{AsListOfClasses} does the same, except that the returned list contains residue classes instead
of pairs \texttt{[\mbox{\texttt{\mdseries\slshape modulus}},\mbox{\texttt{\mdseries\slshape residue}}]}. There are methods for \texttt{Print}, \texttt{String} and \texttt{Display} available for unions of residue classes with fixed representatives. 

\subsection{\textcolor{Chapter }{AllResidueClassesWithFixedRepsModulo (by ring and modulus)}}
\logpage{[ 2, 1, 3 ]}\nobreak
\hyperdef{L}{X8198386A809A6B17}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllResidueClassesWithFixedRepsModulo({\mdseries\slshape R, m})\index{AllResidueClassesWithFixedRepsModulo@\texttt{All}\-\texttt{Residue}\-\texttt{Classes}\-\texttt{With}\-\texttt{Fixed}\-\texttt{Reps}\-\texttt{Modulo}!by ring and modulus}
\label{AllResidueClassesWithFixedRepsModulo:by ring and modulus}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{AllResidueClassesWithFixedRepsModulo({\mdseries\slshape m})\index{AllResidueClassesWithFixedRepsModulo@\texttt{All}\-\texttt{Residue}\-\texttt{Classes}\-\texttt{With}\-\texttt{Fixed}\-\texttt{Reps}\-\texttt{Modulo}!by modulus, of the default ring of that modulus}
\label{AllResidueClassesWithFixedRepsModulo:by modulus, of the default ring of that modulus}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 a sorted list of all residue classes (mod{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}}) of the ring{\nobreakspace}\mbox{\texttt{\mdseries\slshape R}}, with fixed representatives. 



 If the argument \mbox{\texttt{\mdseries\slshape R}} is omitted it defaults to the default ring of{\nobreakspace}\mbox{\texttt{\mdseries\slshape m}}, cf. the documentation of \texttt{DefaultRing} in the \textsf{GAP} reference manual. The representatives are the same as those chosen by the
operation \texttt{mod}. See also \texttt{AllResidueClassesModulo} (\ref{AllResidueClassesModulo:of a given ring, modulo a given modulus}). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@AllResidueClassesWithFixedRepsModulo(4);|
  [ [0/4], [1/4], [2/4], [3/4] ]
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{ Methods for unions of residue classes with fixed representatives }}\label{sec:MethodsForUnionOfResidueClassesWithFixedReps}
\logpage{[ 2, 2, 0 ]}
\hyperdef{L}{X7C26C7E682C2FD2E}{}
{
  Throughout this chapter, the argument \mbox{\texttt{\mdseries\slshape R}} denotes the underlying ring, and the arguments \mbox{\texttt{\mdseries\slshape U}}, \mbox{\texttt{\mdseries\slshape U1}} and{\nobreakspace}\mbox{\texttt{\mdseries\slshape U2}} denote unions of residue classes of \mbox{\texttt{\mdseries\slshape R}} with fixed representatives. 

 Unions of residue classes with fixed representatives are multisets. Elements
and residue classes can be contained with multiplicities: 

\subsection{\textcolor{Chapter }{Multiplicity (of an element in a union of residue classes with fixed rep's)}}
\logpage{[ 2, 2, 1 ]}\nobreak
\hyperdef{L}{X808442EC7F3F5748}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Multiplicity({\mdseries\slshape x, U})\index{Multiplicity@\texttt{Multiplicity}!of an element in a union of residue classes with fixed rep's}
\label{Multiplicity:of an element in a union of residue classes with fixed rep's}
}\hfill{\scriptsize (method)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Multiplicity({\mdseries\slshape cl, U})\index{Multiplicity@\texttt{Multiplicity}!of a residue class in a union of residue classes with fixed rep's}
\label{Multiplicity:of a residue class in a union of residue classes with fixed rep's}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 the multiplicity of \mbox{\texttt{\mdseries\slshape x}} in{\nobreakspace}\mbox{\texttt{\mdseries\slshape U}} regarded as a multiset of ring elements, resp. the multiplicity of the residue
class \mbox{\texttt{\mdseries\slshape cl}} in{\nobreakspace}\mbox{\texttt{\mdseries\slshape U}} regarded as a multiset of residue classes. 



 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U := UnionOfResidueClassesWithFixedReps(Integers,[[2,0],[3,0]]);|
  [0/2] U [0/3]
  !gapprompt@gap>| !gapinput@List([0..20],n->Multiplicity(n,U));|
  [ 2, 0, 1, 1, 1, 0, 2, 0, 1, 1, 1, 0, 2, 0, 1, 1, 1, 0, 2, 0, 1 ]
  !gapprompt@gap>| !gapinput@Multiplicity(ResidueClassWithFixedRep(2,0),U);|
  1
  
\end{Verbatim}
 }

 \index{Density@\texttt{Density}!of a union of residue classes with fixed rep's} \index{IsOverlappingFree@\texttt{IsOverlappingFree}!for a union of residue classes with fixed rep's} \index{AsOrdinaryUnionOfResidueClasses@\texttt{AsOrdinaryUnionOfResidueClasses}!for a union of residue classes with fixed rep's} Let \texttt{U} be a union of residue classes with fixed representatives. The multiset \texttt{U} can have an attribute \texttt{Density} which denotes its \emph{natural density} as a multiset, i.e. elements with multiplicity{\nobreakspace}$k$ count $k$\texttt{\symbol{45}}fold. The multiset \texttt{U} has the property \texttt{IsOverlappingFree} if it consists of pairwise disjoint residue classes. The
set\texttt{\symbol{45}}theoretic union of the residue classes forming \texttt{U} can be determined by the operation \texttt{AsOrdinaryUnionOfResidueClasses}. The object returned by this operation is an ``ordinary'' residue class union as described in Chapter{\nobreakspace}\ref{ch:UnionsOfResidueClasses}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U := UnionOfResidueClassesWithFixedReps(Integers,[[2,0],[3,0]]);|
  [0/2] U [0/3]
  !gapprompt@gap>| !gapinput@Density(U);|
  5/6
  !gapprompt@gap>| !gapinput@IsOverlappingFree(U);|
  false
  !gapprompt@gap>| !gapinput@AsOrdinaryUnionOfResidueClasses(U);|
  Z \ 1(6) U 5(6)
  !gapprompt@gap>| !gapinput@Density(last);|
  2/3
  
\end{Verbatim}
 In the sequel we abbreviate the term ``the multiset of ring elements endowed with the structure of a union of residue
classes with fixed representatives'' by ``the multiset''. 

 There are methods for \texttt{+} and \texttt{\texttt{\symbol{45}}} available for computing the multiset of sums $u + x$, $u \in U$, the multiset of differences $u - x$ resp. $x - u$, $u \in U$ and the multiset of the additive inverses of the elements of{\nobreakspace}$U$. Further there are methods for \texttt{*} and \texttt{/} available for computing the multiset of products $x \cdot u$, $u \in U$ and the multiset of quotients $u/x$, $u \in U$. The division method requires all elements of{\nobreakspace}\texttt{U} to be divisible by{\nobreakspace}$x$. If the underlying ring is the ring of integers, scalar multiplication and
division leave $\delta$ invariant ($\rightarrow${\nobreakspace}\texttt{Delta} (\ref{Delta:for a union of residue classes with fixed representatives})). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U := UnionOfResidueClassesWithFixedReps(Integers,[[2,0],[3,0]]);|
  [0/2] U [0/3]
  !gapprompt@gap>| !gapinput@U + 7;|
  [7/2] U [7/3]
  !gapprompt@gap>| !gapinput@U - 7; 7 - U; -U;|
  [-7/2] U [-7/3]
  [7/-3] U [7/-2]
  [0/-3] U [0/-2]
  !gapprompt@gap>| !gapinput@V := 2 * U;|
  [0/4] U [0/6]
  !gapprompt@gap>| !gapinput@V/2;|
  [0/2] U [0/3]
  
\end{Verbatim}
 \pagebreak[4] 

\subsection{\textcolor{Chapter }{Union (for unions of residue classes with fixed representatives)}}
\logpage{[ 2, 2, 2 ]}\nobreak
\hyperdef{L}{X8296A97779FE8B72}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Union({\mdseries\slshape U1, U2})\index{Union@\texttt{Union}!for unions of residue classes with fixed representatives}
\label{Union:for unions of residue classes with fixed representatives}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 the union of \mbox{\texttt{\mdseries\slshape U1}} and{\nobreakspace}\mbox{\texttt{\mdseries\slshape U2}}. 



 The multiplicity of any ring element or residue class in the union is the sum
of its multiplicities in the arguments. It holds that \texttt{Delta(Union(\mbox{\texttt{\mdseries\slshape U1}},\mbox{\texttt{\mdseries\slshape U2}})) = Delta(\mbox{\texttt{\mdseries\slshape U1}}) + Delta(\mbox{\texttt{\mdseries\slshape U2}})}. ($\rightarrow${\nobreakspace}\texttt{Delta} (\ref{Delta:for a union of residue classes with fixed representatives})). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U := UnionOfResidueClassesWithFixedReps(Integers,[[2,0],[3,0]]);|
  [0/2] U [0/3]
  !gapprompt@gap>| !gapinput@Union(U,U);                                      |
  [0/2] U [0/2] U [0/3] U [0/3]
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Intersection (for unions of residue classes with fixed representatives)}}
\logpage{[ 2, 2, 3 ]}\nobreak
\hyperdef{L}{X7FC166A57F1F5601}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Intersection({\mdseries\slshape U1, U2})\index{Intersection@\texttt{Intersection}!for unions of residue classes with fixed representatives}
\label{Intersection:for unions of residue classes with fixed representatives}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 the intersection of \mbox{\texttt{\mdseries\slshape U1}} and{\nobreakspace}\mbox{\texttt{\mdseries\slshape U2}}. 



 The multiplicity of any residue class in the intersection is the minimum of
its multiplicities in the arguments. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U := UnionOfResidueClassesWithFixedReps(Integers,[[2,0],[3,0]]);|
  [0/2] U [0/3]
  !gapprompt@gap>| !gapinput@Intersection(U,ResidueClassWithFixedRep(2,0));|
  [0/2]
  !gapprompt@gap>| !gapinput@Intersection(U,ResidueClassWithFixedRep(6,0));|
  []
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{Difference (for unions of residue classes with fixed representatives)}}
\logpage{[ 2, 2, 4 ]}\nobreak
\hyperdef{L}{X82A4EE727E67AB98}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Difference({\mdseries\slshape U1, U2})\index{Difference@\texttt{Difference}!for unions of residue classes with fixed representatives}
\label{Difference:for unions of residue classes with fixed representatives}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 the difference of \mbox{\texttt{\mdseries\slshape U1}} and{\nobreakspace}\mbox{\texttt{\mdseries\slshape U2}}. 



 The multiplicity of any residue class in the difference is its multiplicity
in{\nobreakspace}\mbox{\texttt{\mdseries\slshape U1}} minus its multiplicity in{\nobreakspace}\mbox{\texttt{\mdseries\slshape U2}}, if this value is nonnegative. The difference of the empty residue class
union with fixed representatives and some residue class $[r/m]$ is set equal to $[(m-r)/m]$. It holds that \texttt{Delta(Difference(\mbox{\texttt{\mdseries\slshape U1}},\mbox{\texttt{\mdseries\slshape U2}})) = Delta(\mbox{\texttt{\mdseries\slshape U1}}) \texttt{\symbol{45}} Delta(\mbox{\texttt{\mdseries\slshape U2}})}. ($\rightarrow${\nobreakspace}\texttt{Delta} (\ref{Delta:for a union of residue classes with fixed representatives})). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U := UnionOfResidueClassesWithFixedReps(Integers,[[2,0],[3,0]]);|
  [0/2] U [0/3]
  !gapprompt@gap>| !gapinput@V := UnionOfResidueClassesWithFixedReps(Integers,[[3,0],[5,2]]);|
  [0/3] U [2/5]
  !gapprompt@gap>| !gapinput@Difference(U,V);|
  [0/2] U [3/5]
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{ The invariant Delta }}\label{sec:DeltaAndRho}
\logpage{[ 2, 3, 0 ]}
\hyperdef{L}{X7A1CBA1B7E6B93D0}{}
{
  

\subsection{\textcolor{Chapter }{Delta (for a union of residue classes with fixed representatives)}}
\logpage{[ 2, 3, 1 ]}\nobreak
\hyperdef{L}{X78DCAB2C7C4E37E8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Delta({\mdseries\slshape U})\index{Delta@\texttt{Delta}!for a union of residue classes with fixed representatives}
\label{Delta:for a union of residue classes with fixed representatives}
}\hfill{\scriptsize (attribute)}}\\
\textbf{\indent Returns:\ }
 the value of the invariant $\delta$ of the residue class union{\nobreakspace}\mbox{\texttt{\mdseries\slshape U}}. 



 For a residue class $[r/m]$ with fixed representative we set $\delta([r/m]) := r/m - 1/2$, and extend this definition additively to unions of such residue classes. If
no representatives are fixed, this definition is still unique
(mod{\nobreakspace}1). There is a related invariant{\nobreakspace}$\rho$ which is defined by $e^{\delta(U) \pi i}$. The corresponding attribute is called \texttt{Rho}. \index{Rho@\texttt{Rho}!for a union of residue classes with fixed rep's} 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U := UnionOfResidueClassesWithFixedReps(Integers,[[2,3],[3,4]]);|
  [3/2] U [4/3]
  !gapprompt@gap>| !gapinput@Delta(U) = (3/2-1/2) + (4/3-1/2);|
  true
  !gapprompt@gap>| !gapinput@V := RepresentativeStabilizingRefinement(U,3);|
  [3/6] U [5/6] U [7/6] U [4/9] U [7/9] U [10/9]
  !gapprompt@gap>| !gapinput@Delta(V) = Delta(U);|
  true
  !gapprompt@gap>| !gapinput@Rho(V);|
  E(12)^11
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{RepresentativeStabilizingRefinement (of a union of res.-classes with fixed rep's)}}
\logpage{[ 2, 3, 2 ]}\nobreak
\hyperdef{L}{X7E109A6E81A0465C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{RepresentativeStabilizingRefinement({\mdseries\slshape U, k})\index{RepresentativeStabilizingRefinement@\texttt{RepresentativeStabilizingRefinement}!of a union of res.-classes with fixed rep's}
\label{RepresentativeStabilizingRefinement:of a union of res.-classes with fixed rep's}
}\hfill{\scriptsize (method)}}\\
\textbf{\indent Returns:\ }
 the representative stabilizing refinement of \mbox{\texttt{\mdseries\slshape U}} into \mbox{\texttt{\mdseries\slshape k}}{\nobreakspace}parts. 



 The \emph{representative stabilizing refinement} of a residue class $[r/m]$ of{\nobreakspace}{\ensuremath{\mathbb Z}} into $k$ parts is defined by $[r/km] \cup [(r+m)/km] \cup \dots \cup [(r+(k-1)m)/km]$. This definition is extended in the obvious way to unions of residue classes. 

 If the argument \mbox{\texttt{\mdseries\slshape k}} is zero, the method performs a simplification of \mbox{\texttt{\mdseries\slshape U}} by joining appropriate residue classes, if this is possible. 

 In any case the value of \texttt{Delta(\mbox{\texttt{\mdseries\slshape U}})} is invariant under this operation ($\rightarrow${\nobreakspace}\texttt{Delta} (\ref{Delta:for a union of residue classes with fixed representatives})). 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@U := UnionOfResidueClassesWithFixedReps(Integers,[[2,0],[3,0]]);|
  [0/2] U [0/3]
  !gapprompt@gap>| !gapinput@RepresentativeStabilizingRefinement(U,4);   |
  [0/8] U [2/8] U [4/8] U [6/8] U [0/12] U [3/12] U [6/12] U [9/12]
  !gapprompt@gap>| !gapinput@RepresentativeStabilizingRefinement(last,0);|
  [0/2] U [0/3]
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{ The categories of unions of residue classes with fixed rep's }}\label{sec:CategoriesOfUnionsOfResidueClassesWithFixedReps}
\logpage{[ 2, 4, 0 ]}
\hyperdef{L}{X7BA9DE337DF742E9}{}
{
  The names of the categories of unions of residue classes with fixed
representatives are \texttt{IsUnionOfResidueClassesOf[Z|Z{\textunderscore}pi|ZorZ{\textunderscore}pi|GFqx]WithFixedRepresentatives}. }

  }

       
\chapter{\textcolor{Chapter }{Semilocalizations of the Integers}}\label{ch:Z_pi}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X80CB0518869B1818}{}
{
   This package implements residue class unions of the semilocalizations ${\ensuremath{\mathbb Z}}_{(\pi)}$ of the ring of integers. It also provides the underlying \textsf{GAP} implementation of these rings themselves.  
\section{\textcolor{Chapter }{Entering semilocalizations of the integers}}\label{sec:DefiningZ_pi}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X7B3B22AC7E6247A4}{}
{
  

\subsection{\textcolor{Chapter }{Z{\textunderscore}pi (by set of non-invertible primes)}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X7861432E7F221610}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Z{\textunderscore}pi({\mdseries\slshape pi})\index{Z{\textunderscore}pi@\texttt{Z{\textunderscore}pi}!by set of non-invertible primes}
\label{ZuScorepi:by set of non-invertible primes}
}\hfill{\scriptsize (function)}}\\
\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{Z{\textunderscore}pi({\mdseries\slshape p})\index{Z{\textunderscore}pi@\texttt{Z{\textunderscore}pi}!by non-invertible prime}
\label{ZuScorepi:by non-invertible prime}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the ring ${\ensuremath{\mathbb Z}}_{(\pi)}$ or the ring ${\ensuremath{\mathbb Z}}_{(p)}$, respectively. 



 The returned ring has the property \texttt{IsZ{\textunderscore}pi}. The set \mbox{\texttt{\mdseries\slshape pi}} of non\texttt{\symbol{45}}invertible primes can be retrieved by the operation \texttt{NoninvertiblePrimes}. \index{IsZ_pi@\texttt{IsZ{\textunderscore}pi}} \index{NoninvertiblePrimes@\texttt{NoninvertiblePrimes}!of a semilocalization of Z} 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@R := Z_pi(2);|
  Z_( 2 )
  !gapprompt@gap>| !gapinput@S := Z_pi([2,5,7]);|
  Z_( 2, 5, 7 )
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{Methods for semilocalizations of the integers}}\label{sec:MethodsForZ_pi}
\logpage{[ 3, 2, 0 ]}
\hyperdef{L}{X7E75C4217DCA45D0}{}
{
  \index{StandardAssociate@\texttt{StandardAssociate}!of an element of a semilocalization of Z} \index{Gcd@\texttt{Gcd}!of elements of a semilocalization of Z} \index{Lcm@\texttt{Lcm}!of elements of a semilocalization of Z} \index{Factors@\texttt{Factors}!of an element of a semilocalization of Z} \index{IsUnit@\texttt{IsUnit}!for an element of a semilocalization of Z} There are methods for the operations \texttt{in}, \texttt{Intersection}, \texttt{IsSubset}, \texttt{StandardAssociate}, \texttt{Gcd}, \texttt{Lcm}, \texttt{Factors} and \texttt{IsUnit} available for semilocalizations of the integers. For the documentation of
these operations, see the \textsf{GAP} reference manual. The standard associate of an element of a ring ${\ensuremath{\mathbb Z}}_{(\pi)}$ is defined by the product of the non\texttt{\symbol{45}}invertible prime
factors of its numerator. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@4/7 in R; 3/2 in R;|
  true
  false
  !gapprompt@gap>| !gapinput@Intersection(R,Z_pi([3,11])); IsSubset(R,S);|
  Z_( 2, 3, 11 )
  true
  
\end{Verbatim}
 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@StandardAssociate(R,-6/7);|
  2
  !gapprompt@gap>| !gapinput@Gcd(S,90/3,60/17,120/33);|
  10
  !gapprompt@gap>| !gapinput@Lcm(S,90/3,60/17,120/33);|
  40
  !gapprompt@gap>| !gapinput@Factors(R,840);|
  [ 105, 2, 2, 2 ]
  !gapprompt@gap>| !gapinput@Factors(R,-2/3);|
  [ -1/3, 2 ]
  !gapprompt@gap>| !gapinput@IsUnit(S,3/11);|
  true
  
\end{Verbatim}
  }

  }

       
\chapter{\textcolor{Chapter }{Installation and Auxiliary Functions}}\label{ch:InstallationAndAuxiliaryFunctions}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X859F6BF88754E5CC}{}
{
   
\section{\textcolor{Chapter }{Requirements}}\label{sec:Requirements}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X85A08CF187A6D986}{}
{
  This version of \textsf{ResClasses} needs at least \textsf{GAP}{\nobreakspace}4.9.0, \textsf{Polycyclic}{\nobreakspace}2.11{\nobreakspace}\cite{Polycyclic}, \textsf{GAPDoc}{\nobreakspace}1.5.1{\nobreakspace}\cite{GAPDoc} and \textsf{Utils}{\nobreakspace}0.40{\nobreakspace}\cite{Utils}. It can be used on all platforms for which \textsf{GAP} is available. \textsf{ResClasses} is completely written in the \textsf{GAP} language and does neither contain nor require external binaries. }

  
\section{\textcolor{Chapter }{Installation}}\label{sec:Installation}
\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X8360C04082558A12}{}
{
  Like any other \textsf{GAP} package, \textsf{ResClasses} is usually installed in the \texttt{pkg} subdirectory of the \textsf{GAP} distribution. This is accomplished by extracting the distribution file in this
directory. By default, the package \textsf{ResClasses} is autoloaded. If you have switched autoloading of packages off, you can load \textsf{ResClasses} via \texttt{LoadPackage( "resclasses" );}. }

  
\section{\textcolor{Chapter }{The testing routines}}\label{sec:TheTestingRoutines}
\logpage{[ 4, 3, 0 ]}
\hyperdef{L}{X865D6A49826B92EC}{}
{
  

\subsection{\textcolor{Chapter }{ResClassesTest}}
\logpage{[ 4, 3, 1 ]}\nobreak
\hyperdef{L}{X8733F00082901C2C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResClassesTest({\mdseries\slshape })\index{ResClassesTest@\texttt{ResClassesTest}}
\label{ResClassesTest}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 \texttt{true} if no errors were found, and \texttt{false} otherwise. 



 Performs tests of the \textsf{ResClasses} package. Errors, i.e. differences to the correct results of the test
computations, are reported. The processed test files are in the directory \texttt{pkg/resclasses/tst}. }

 

\subsection{\textcolor{Chapter }{ResClassesTestExamples}}
\logpage{[ 4, 3, 2 ]}\nobreak
\hyperdef{L}{X802034807F5D6C47}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{ResClassesTestExamples({\mdseries\slshape })\index{ResClassesTestExamples@\texttt{ResClassesTestExamples}}
\label{ResClassesTestExamples}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing. 



 Runs all examples in the manual of the \textsf{ResClasses} package, and reports any differences between the actual output and the output
printed in the manual. }

 }

  
\section{\textcolor{Chapter }{Creating timestamped logfiles}}\label{sec:LogToDatedFile}
\logpage{[ 4, 4, 0 ]}
\hyperdef{L}{X7B0129E185088420}{}
{
  

\subsection{\textcolor{Chapter }{LogToDatedFile}}
\logpage{[ 4, 4, 1 ]}\nobreak
\hyperdef{L}{X7B023FD184CC118D}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{LogToDatedFile({\mdseries\slshape directory})\index{LogToDatedFile@\texttt{LogToDatedFile}}
\label{LogToDatedFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the full pathname of the created logfile. 



 This function opens a logfile in the specified directory; the name of the
logfile has the form of a timestamp, i.e. \texttt{year\texttt{\symbol{45}}month\texttt{\symbol{45}}day
hour\texttt{\symbol{45}}minute\texttt{\symbol{45}}second.log.} If \textsf{GAP} is already in logging mode, the old logfile is closed before the new one is
opened. 

 The availability of this function depends on that the package \textsf{IO}{\nobreakspace}\cite{IO} is installed and compiled. }

 }

  
\section{\textcolor{Chapter }{DownloadFile, SendEmail and EmailLogFile}}\label{sec:SendEmailAndEmailLogFile}
\logpage{[ 4, 5, 0 ]}
\hyperdef{L}{X81DD0163859E9EF5}{}
{
  

\subsection{\textcolor{Chapter }{DownloadFile}}
\logpage{[ 4, 5, 1 ]}\nobreak
\hyperdef{L}{X7C1543408472A82B}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DownloadFile({\mdseries\slshape url})\index{DownloadFile@\texttt{DownloadFile}}
\label{DownloadFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 the contents of the file with URL \mbox{\texttt{\mdseries\slshape url}} in the form of a string if that file exists and the download was successful,
and \texttt{fail} otherwise. 



 As most system\texttt{\symbol{45}}related functions, \texttt{DownloadFile} works only under UNIX / Linux. Also the computer must of course be connected
to the Internet. }

 

\subsection{\textcolor{Chapter }{SendEmail}}
\logpage{[ 4, 5, 2 ]}\nobreak
\hyperdef{L}{X7F27919085001EA8}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SendEmail({\mdseries\slshape sendto, copyto, subject, text})\index{SendEmail@\texttt{SendEmail}}
\label{SendEmail}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 zero if everything worked correctly, and a system error number otherwise. 



 Sends an e\texttt{\symbol{45}}mail with subject \mbox{\texttt{\mdseries\slshape subject}} and body \mbox{\texttt{\mdseries\slshape text}} to the addresses in the list \mbox{\texttt{\mdseries\slshape sendto}}, and copies it to those in the list \mbox{\texttt{\mdseries\slshape copyto}}. The first two arguments must be lists of strings, and the latter two must be
strings. 

 As most system\texttt{\symbol{45}}related functions, \texttt{SendEmail} works only under UNIX / Linux. Also the computer must of course be connected
to the Internet. }

 

\subsection{\textcolor{Chapter }{EmailLogFile}}
\logpage{[ 4, 5, 3 ]}\nobreak
\hyperdef{L}{X8000E5CF7DF4339C}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{EmailLogFile({\mdseries\slshape addresses})\index{EmailLogFile@\texttt{EmailLogFile}}
\label{EmailLogFile}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 zero if everything worked correctly, and a system error number otherwise. 



 Sends the current log file by e\texttt{\symbol{45}}mail to \mbox{\texttt{\mdseries\slshape addresses}}, if \textsf{GAP} is in logging mode and one is working under UNIX / Linux, and does nothing
otherwise. The argument \mbox{\texttt{\mdseries\slshape addresses}} must be either a list of e\texttt{\symbol{45}}mail addresses or a single
e\texttt{\symbol{45}}mail address. Long log files are abbreviated, i.e. if the
log file is larger than 64KB, then any output is truncated at 1KB, and if the
log file is still longer than 64KB afterwards, it is truncated
at{\nobreakspace}64KB. }

 }

  
\section{\textcolor{Chapter }{Creating bitmap pictures}}\label{sec:BitmapPictures}
\logpage{[ 4, 6, 0 ]}
\hyperdef{L}{X855F2CE284BFB06B}{}
{
  \textsf{ResClasses} provides functions to generate bitmap picture files from suitable pixel
matrices and vice versa. The author has successfully tested this feature both
under Linux and under Windows, and the generated pictures can be processed
further with many common graphics programs: 

\subsection{\textcolor{Chapter }{SaveAsBitmapPicture (picture, filename)}}
\logpage{[ 4, 6, 1 ]}\nobreak
\hyperdef{L}{X81DE1E838615C214}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{SaveAsBitmapPicture({\mdseries\slshape picture, filename})\index{SaveAsBitmapPicture@\texttt{SaveAsBitmapPicture}!picture, filename}
\label{SaveAsBitmapPicture:picture, filename}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing. 



 Writes the pixel matrix \mbox{\texttt{\mdseries\slshape picture}} to a bitmap\texttt{\symbol{45}} (bmp\texttt{\symbol{45}}) picture file named \mbox{\texttt{\mdseries\slshape filename}}. The filename should include the entire pathname. The argument \mbox{\texttt{\mdseries\slshape picture}} can be a GF(2) matrix, in which case a monochrome picture file is generated.
In this case, zeros stand for black pixels and ones stand for white pixels.
The argument \mbox{\texttt{\mdseries\slshape picture}} can also be an integer matrix, in which case a 24\texttt{\symbol{45}}bit true
color picture file is generated. In this case, the entries of the matrix are
supposed to be integers $n = 65536 \cdot red + 256 \cdot green + blue$ in the range $0, \dots, 2^{24}-1$ specifying the RGB values of the colors of the pixels. 

 \index{LoadBitmapPicture@\texttt{LoadBitmapPicture}!filename} The picture can be read back into \textsf{GAP} by the function \texttt{LoadBitmapPicture(\mbox{\texttt{\mdseries\slshape filename}})}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@color   := n->32*(n mod 8)+256*32*(Int(n/8) mod 8)+65536*32*Int(n/64);;|
  !gapprompt@gap>| !gapinput@picture := List([1..512],y->List([1..512],x->color(Gcd(x,y)-1)));;|
  !gapprompt@gap>| !gapinput@SaveAsBitmapPicture(picture,Filename(DirectoryTemporary(),"gcd.bmp"));|
  
\end{Verbatim}
 }

 

\subsection{\textcolor{Chapter }{DrawLineNC (pic, x1, y1, x2, y2, color, width)}}
\logpage{[ 4, 6, 2 ]}\nobreak
\hyperdef{L}{X83D7129581B8CF21}{}
{\noindent\textcolor{FuncColor}{$\triangleright$\enspace\texttt{DrawLineNC({\mdseries\slshape pic, x1, y1, x2, y2, color, width})\index{DrawLineNC@\texttt{DrawLineNC}!pic, x1, y1, x2, y2, color, width}
\label{DrawLineNC:pic, x1, y1, x2, y2, color, width}
}\hfill{\scriptsize (function)}}\\
\textbf{\indent Returns:\ }
 nothing. 



 Draws a line on picture \mbox{\texttt{\mdseries\slshape pic}} from (\mbox{\texttt{\mdseries\slshape x1}},\mbox{\texttt{\mdseries\slshape y1}}) to (\mbox{\texttt{\mdseries\slshape x2}},\mbox{\texttt{\mdseries\slshape y2}}), with color \mbox{\texttt{\mdseries\slshape color}} and of width \mbox{\texttt{\mdseries\slshape width}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@picture := NullMat(100,100)+2^24-1;;|
  !gapprompt@gap>| !gapinput@DrawLineNC(picture,30,20,70,80,255,8);                 |
  !gapprompt@gap>| !gapinput@SaveAsBitmapPicture(picture,Filename(DirectoryTemporary(),|
  !gapprompt@>| !gapinput@                       "example.bmp"));|
  
\end{Verbatim}
 }

 }

  
\section{\textcolor{Chapter }{Some general utility functions}}\label{sec:UtilityFunctions}
\logpage{[ 4, 7, 0 ]}
\hyperdef{L}{X808A30E37A293D19}{}
{
  \textsf{ResClasses} provides a few small utility functions and \texttt{\symbol{45}}operations
which can be used in a more general context. They are described in this
section. 

 \index{PositionsSublist@\texttt{PositionsSublist}} There is an operation \texttt{PositionsSublist(\mbox{\texttt{\mdseries\slshape list}},\mbox{\texttt{\mdseries\slshape sub}})} which returns the list of positions at which \mbox{\texttt{\mdseries\slshape sub}} occurs as a sublist of \mbox{\texttt{\mdseries\slshape list}}. 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@PositionsSublist([1,2,6,2,7,2,7,2,3,1,6,2,7,2,8],[2,7,2]);|
  [ 4, 6, 12 ]
  !gapprompt@gap>| !gapinput@PositionsSublist([1,2,3,4,3,2,1],[1,3,5]);|
  [  ]
  !gapprompt@gap>| !gapinput@PositionsSublist("This is an example, isn't it?","is");   |
  [ 3, 6, 21 ]
  
\end{Verbatim}
 \index{EquivalenceClasses@\texttt{EquivalenceClasses}!for a list and a function computing a class invariant} \index{EquivalenceClasses@\texttt{EquivalenceClasses}!for a list and a function describing an equivalence relation} Also there are methods \texttt{EquivalenceClasses(\mbox{\texttt{\mdseries\slshape l}},\mbox{\texttt{\mdseries\slshape inv}})} and \texttt{EquivalenceClasses(\mbox{\texttt{\mdseries\slshape l}},\mbox{\texttt{\mdseries\slshape rel}})} which decompose a list{\nobreakspace}\mbox{\texttt{\mdseries\slshape l}} into equivalence classes under an equivalence relation. The equivalence
relation is given either as a function \mbox{\texttt{\mdseries\slshape inv}} computing a class invariant of a given list entry or as a function \mbox{\texttt{\mdseries\slshape rel}} which takes as arguments two list entries and returns either \texttt{true} or \texttt{false} depending on whether the arguments belong to the same equivalence class or
not. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@EquivalenceClasses([2..50],n->Length(Factors(n))); |
  [ [ 2, 3, 5, 7, 11, 13, 17, 19, 23, 29, 31, 37, 41, 43, 47 ], 
    [ 4, 6, 9, 10, 14, 15, 21, 22, 25, 26, 33, 34, 35, 38, 39, 46, 49 ], 
    [ 8, 12, 18, 20, 27, 28, 30, 42, 44, 45, 50 ], [ 16, 24, 36, 40 ], 
    [ 32, 48 ] ]
  !gapprompt@gap>| !gapinput@EquivalenceClasses(AsList(AlternatingGroup(4)),|
  !gapprompt@>| !gapinput@                      function ( g, h )|
  !gapprompt@>| !gapinput@                        return IsConjugate(SymmetricGroup(4),g,h);|
  !gapprompt@>| !gapinput@                      end);|
  [ [ (2,3,4), (2,4,3), (1,2,3), (1,2,4), (1,3,2), (1,3,4), (1,4,2), 
        (1,4,3) ], [ (1,2)(3,4), (1,3)(2,4), (1,4)(2,3) ], [ () ] ]
  
\end{Verbatim}
 \index{GraphClasses@\texttt{GraphClasses}} \index{AllGraphs@\texttt{AllGraphs}} \index{IdGraphNC@\texttt{IdGraphNC}} Further, there is an operation \texttt{GraphClasses(\mbox{\texttt{\mdseries\slshape n}})} which returns a list of isomorphism classes of graphs with vertices $1, 2, \dots, n$, and an operation \texttt{AllGraphs(\mbox{\texttt{\mdseries\slshape n}})} which returns a list of representatives of these classes. The graphs are
represented as lists of edges, where each edge is a list of the two vertices
it connects, and they are ordered by ascending number of edges. Given a graph \mbox{\texttt{\mdseries\slshape graph}} with \mbox{\texttt{\mdseries\slshape n}} vertices, the operation \texttt{IdGraphNC(\mbox{\texttt{\mdseries\slshape graph}},GraphClasses(\mbox{\texttt{\mdseries\slshape n}}))} returns the index \texttt{i} such that \mbox{\texttt{\mdseries\slshape graph}} lies in \texttt{GraphClasses(\mbox{\texttt{\mdseries\slshape n}})[i]}. For reasons of efficiency, \texttt{IdGraphNC} performs no argument checks. 

 
\begin{Verbatim}[commandchars=!@|,fontsize=\small,frame=single,label=Example]
  
  !gapprompt@gap>| !gapinput@GraphClasses(3);|
  [ [ [  ] ], [ [ [ 1, 2 ] ], [ [ 2, 3 ] ], [ [ 1, 3 ] ] ], 
    [ [ [ 1, 2 ], [ 1, 3 ] ], [ [ 1, 2 ], [ 2, 3 ] ], 
        [ [ 1, 3 ], [ 2, 3 ] ] ], [ [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ] ] ]
  !gapprompt@gap>| !gapinput@List(last,Length); # sizes of classes|
  [ 1, 3, 3, 1 ]
  !gapprompt@gap>| !gapinput@AllGraphs(4);|
  [ [  ], [ [ 1, 2 ] ], [ [ 1, 2 ], [ 1, 3 ] ], [ [ 1, 2 ], [ 3, 4 ] ], 
    [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ] ], [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ], 
    [ [ 1, 2 ], [ 1, 3 ], [ 2, 4 ] ], 
    [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ] ], 
    [ [ 1, 2 ], [ 1, 3 ], [ 2, 4 ], [ 3, 4 ] ], 
    [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 2, 4 ] ], 
    [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 2, 4 ], [ 3, 4 ] ] ]
  !gapprompt@gap>| !gapinput@List(last,Length); # numbers of edges|
  [ 0, 1, 2, 2, 3, 3, 3, 4, 4, 5, 6 ]
  !gapprompt@gap>| !gapinput@IdGraphNC([[1,3],[1,8],[3,8]],GraphClasses(4)); # a triangle graph|
  6
  !gapprompt@gap>| !gapinput@AllGraphs(4)[last];|
  [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ]
  
\end{Verbatim}
 }

  }

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

\bibliographystyle{alpha}
\bibliography{resclassesbib.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}
