% generated by GAPDoc2LaTeX from XML source (Frank Luebeck)
\documentclass[a4paper,11pt]{report}
\usepackage{a4wide}
\sloppy
\pagestyle{myheadings}
\usepackage{amssymb}
\usepackage[utf8]{inputenc}
\usepackage{makeidx}
\makeindex
\usepackage{color}
\definecolor{DarkOlive}{rgb}{0.1047,0.2412,0.0064}
\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{FuncColor}{rgb}{1.0,0.0,0.0}
%% strange name because of pdflatex bug:
\definecolor{Chapter }{rgb}{0.0,0.0,1.0}

\usepackage{fancyvrb}

\usepackage{pslatex}

\usepackage[pdftex=true,
        a4paper=true,bookmarks=false,pdftitle={Written with GAPDoc},
        pdfcreator={LaTeX with hyperref package / GAPDoc},
        colorlinks=true,backref=page,breaklinks=true,linkcolor=RoyalBlue,
        citecolor=RoyalGreen,filecolor=RoyalRed,
        urlcolor=RoyalRed,pagecolor=RoyalBlue]{hyperref}

% 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}}

\begin{document}

\logpage{[ 0, 0, 0 ]}
\begin{titlepage}
\begin{center}{\Huge \textbf{\textsf{HomalgToCAS}\mbox{}}}\\[1cm]
\hypersetup{pdftitle=\textsf{HomalgToCAS}}
\markright{\scriptsize \mbox{}\hfill \textsf{HomalgToCAS} \hfill\mbox{}}
{\Large \textbf{A window to the outer world\mbox{}}}\\[1cm]
{Version 2009.11.09 \mbox{}}\\[1cm]
{November 2009\mbox{}}\\[1cm]
\mbox{}\\[2cm]
{\large \textbf{Mohamed Barakat\\
    \mbox{}}}\\
{\large \textbf{Thomas Breuer\\
    \mbox{}}}\\
{\large \textbf{Simon G{\"o}rtzen\\
    \mbox{}}}\\
{\large \textbf{Frank L{\"u}beck\\
    \mbox{}}}\\
\hypersetup{pdfauthor=Mohamed Barakat\\
    ; Thomas Breuer\\
    ; Simon G{\"o}rtzen\\
    ; Frank L{\"u}beck\\
    }
\mbox{}\\[2cm]
\begin{minipage}{12cm}\noindent
(\emph{this manual is still under construction}) \\
\\
 This manual is best viewed as an \textsc{HTML} document. The latest version is available \textsc{online} at: \\
\\
 \href{http://homalg.math.rwth-aachen.de/~barakat/HomalgToCAS/chap0.html} {\texttt{http://homalg.math.rwth-aachen.de/\texttt{\symbol{126}}barakat/HomalgToCAS/chap0.html}} \\
\\
 An \textsc{offline} version should be included in the documentation subfolder of the package. \\
\\
 This package is part of the \textsf{homalg}-project: \\
\\
 \href{http://homalg.math.rwth-aachen.de/index.php/core-packages/homalgtocas} {\texttt{http://homalg.math.rwth-aachen.de/index.php/core-packages/homalgtocas}} \end{minipage}

\end{center}\vfill

\mbox{}\\
{\mbox{}\\
\small \noindent \textbf{Mohamed Barakat\\
    } --- Email: \href{mailto://barakat@mathematik.uni-kl.de} {\texttt{barakat@mathematik.uni-kl.de}}\\
 --- Homepage: \href{http://wwwb.math.rwth-aachen.de/~barakat/} {\texttt{http://wwwb.math.rwth-aachen.de/\texttt{\symbol{126}}barakat/}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Department of Mathematics, \\
 University of Kaiserslautern, \\
 67653 Kaiserslautern, \\
 Germany \end{minipage}
}\\
{\mbox{}\\
\small \noindent \textbf{Thomas Breuer\\
    } --- Email: \href{mailto://sam@math.rwth-aachen.de} {\texttt{sam@math.rwth-aachen.de}}\\
 --- Homepage: \href{http://www.math.rwth-aachen.de/~Thomas.Breuer/} {\texttt{http://www.math.rwth-aachen.de/\texttt{\symbol{126}}Thomas.Breuer/}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Lehrstuhl D f{\"u}r Mathematik, RWTH-Aachen,\\
 Templergraben 64\\
 52062 Aachen\\
 Germany \end{minipage}
}\\
{\mbox{}\\
\small \noindent \textbf{Simon G{\"o}rtzen\\
    } --- Email: \href{mailto://simon.goertzen@rwth-aachen.de} {\texttt{simon.goertzen@rwth-aachen.de}}\\
 --- Homepage: \href{http://wwwb.math.rwth-aachen.de/goertzen/} {\texttt{http://wwwb.math.rwth-aachen.de/goertzen/}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Lehrstuhl B f{\"u}r Mathematik, RWTH-Aachen,\\
 Templergraben 64\\
 52062 Aachen\\
 Germany \end{minipage}
}\\
{\mbox{}\\
\small \noindent \textbf{Frank L{\"u}beck\\
    } --- Email: \href{mailto://frank.luebeck@math.rwth-aachen.de} {\texttt{frank.luebeck@math.rwth-aachen.de}}\\
 --- Homepage: \href{http://www.math.rwth-aachen.de/~Frank.Luebeck/} {\texttt{http://www.math.rwth-aachen.de/\texttt{\symbol{126}}Frank.Luebeck/}}\\
 --- Address: \begin{minipage}[t]{8cm}\noindent
 Lehrstuhl D f{\"u}r Mathematik, RWTH-Aachen,\\
 Templergraben 64\\
 52062 Aachen\\
 Germany \end{minipage}
}\\
\end{titlepage}

\newpage\setcounter{page}{2}
{\small 
\section*{Copyright}
\logpage{[ 0, 0, 1 ]}
 {\copyright} 2007-2009 by Mohamed Barakat, Thomas Breuer, Simon G{\"o}rtzen,
and Frank L{\"u}beck.

 This package may be distributed under the terms and conditions of the GNU
Public License Version 2. \mbox{}}\\[1cm]
{\small 
\section*{Acknowledgements}
\logpage{[ 0, 0, 2 ]}
 We are very much indebted to Max Neunh{\"o}ffer who provided the first piece
of code around which the package \textsf{IO{\textunderscore}ForHomalg} was built. The package \textsf{HomalgToCAS} provides a further abstraction layer preparing the communication. \mbox{}}\\[1cm]
\newpage

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

\tableofcontents
\newpage

 \index{\textsf{HomalgToCAS}}   
\chapter{\textcolor{Chapter }{Introduction}}\label{intro}
\logpage{[ 1, 0, 0 ]}
\hyperdef{L}{X7DFB63A97E67C0A1}{}
{
  \textsf{HomalgToCAS} is one of the core packages of the \textsf{homalg} project \cite{homalg-project}. But as one of the rather technical packages, this manual is probably not of
interest for the average uers. The average user will usually not get in direct
contact with the operations provided by this package. 

 Quoting from the Appendix  (\textbf{homalg: The Core Packages and the Idea behind their Splitting}) of the \textsf{homalg} package manual ($\to$  (\textbf{homalg: HomalgToCAS})): 

 ``The package \textsf{HomalgToCAS} (which needs the \textsf{homalg} package) includes all what is needed to let the black boxes used by \textsf{homalg} reside in external computer algebra systems. So as mentioned above, \textsf{HomalgToCAS} is the right place to declare the three \textsf{GAP} representations external rings, external ring elements, and external matrices.
Still, \textsf{HomalgToCAS} is independent from the external computer algebra system with which \textsf{GAP} will communicate \emph{and} independent of how this communication physically looks like.'' 
\section{\textcolor{Chapter }{\textsf{HomalgToCAS} provides ...}}\label{HomalgToCAS-provides}
\logpage{[ 1, 1, 0 ]}
\hyperdef{L}{X82F5B96B817F7863}{}
{
  
\begin{itemize}
\item Declaration and construction of 
\begin{itemize}
\item external objects (which are pointers to data (rings,ring elements, matrices,
...) residing in external systems)
\item external rings (as a new representation for the \textsf{GAP4}-category of homalg rings)
\item external ring elements (as a new representation for the \textsf{GAP4}-category of homalg ring elements)
\item external matrices (as a new representation for the \textsf{GAP4}-category of homalg matrices)
\end{itemize}
 
\item \texttt{LaunchCAS}: the standard interface used by \textsf{homalg} to launch external systems
\item \texttt{TerminateCAS}: the standard interface used by \textsf{homalg} to terminate external systems
\item \texttt{homalgSendBlocking}: the standard interface used by \textsf{homalg} to send commands to external systems
\item External garbage collection: delete the data in the external systems that
became obsolete for \textsf{homalg}
\item \texttt{homalgIOMode}: decide how much of the communication you want to see
\end{itemize}
 }

 }

   
\chapter{\textcolor{Chapter }{Installation of the \textsf{HomalgToCAS} Package}}\label{install}
\logpage{[ 2, 0, 0 ]}
\hyperdef{L}{X85268DEB879735D2}{}
{
  To install this package just extract the package's archive file to the \textsf{GAP} \texttt{pkg} directory.

 By default the \textsf{HomalgToCAS} package is not automatically loaded by \textsf{GAP} when it is installed. You must load the package with \\
\\
 \texttt{LoadPackage}( "HomalgToCAS" ); \\
\\
 before its functions become available.

 Please, send me an e-mail if you have any questions, remarks, suggestions,
etc. concerning this package. Also, we would be pleased to hear about
applications of this package. \\
\\
\\
 Mohamed Barakat, Thomas Breuer, Simon G{\"o}rtzen, and Frank L{\"u}beck  }

   
\chapter{\textcolor{Chapter }{Watch and Influence the Communication}}\label{Watch}
\logpage{[ 3, 0, 0 ]}
\hyperdef{L}{X83F828CA834F6529}{}
{
  
\section{\textcolor{Chapter }{Functions}}\label{Watch:Functions}
\logpage{[ 3, 1, 0 ]}
\hyperdef{L}{X86FA580F8055B274}{}
{
  

\subsection{\textcolor{Chapter }{homalgIOMode}}
\logpage{[ 3, 1, 1 ]}\nobreak
\hyperdef{L}{X798522BD7B01027E}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{homalgIOMode({\slshape str[, str2[, str3]]})\index{homalgIOMode@\texttt{homalgIOMode}}
\label{homalgIOMode}
}\hfill{\scriptsize (function)}}\\


 This function sets different modes which influence how much of the
communication becomes visible. Handling the string \mbox{\texttt{\slshape str}} is \emph{not} case-sensitive. \texttt{homalgIOMode} invokes the global function \texttt{homalgMode} defined in the \textsf{homalg} package with an ``appropriate'' argument (see code below). Alternatively, if a second or more strings are
given, then \texttt{homalgMode} is invoked with the remaining strings \mbox{\texttt{\slshape str2}}, \mbox{\texttt{\slshape str3}}, ... at the end. In particular, you can use \texttt{homalgIOMode}( \mbox{\texttt{\slshape str}}, "" ) to reset the effect of invoking \texttt{homalgMode}. \begin{center}
\begin{tabular}{l|c|l}\mbox{\texttt{\slshape str}}&
\mbox{\texttt{\slshape str}} (long form)&
mode description\\
\hline
&
&
\\
""&
""&
the default mode, i.e. the communication protocol won't be visible\\
&
&
(\texttt{homalgIOMode}( ) is a short form for \texttt{homalgIOMode}( "" ))\\
&
&
\\
"a"&
"all"&
combine the modes "debug" and "file"\\
&
&
\\
"b"&
"basic"&
the same as "picto" + \texttt{homalgMode}( "basic" )\\
&
&
\\
"d"&
"debug"&
view the complete communication protocol\\
&
&
\\
"f"&
"file"&
dump the communication protocol into a file with the name\\
&
&
\texttt{Concatenation}( "commands{\textunderscore}file{\textunderscore}of{\textunderscore}", CAS,
"{\textunderscore}with{\textunderscore}PID{\textunderscore}", PID )\\
&
&
\\
"p"&
"picto"&
view the abbreviated communication protocol\\
&
&
using the preassigned pictograms\\
&
&
\\
\hline
\end{tabular}\\[2mm]
\end{center}

 All modes other than the "default"-mode only set their specific values and
leave the other values untouched, which allows combining them to some extent.
This also means that in order to get from one mode to a new mode (without the
aim to combine them) one needs to reset to the "default"-mode first. \\
\\
 \emph{Caution}: 
\begin{itemize}
\item In case you choose one of the modes "file" or "all" you might want to set the
global variable \texttt{HOMALG{\textunderscore}IO.DoNotDeleteTemporaryFiles} := \texttt{true}; this is only important if during the computations some matrices get
converted via files (using \texttt{ConvertHomalgMatrixViaFile}), as reading these files will be part of the protocol!
\item It makes sense for the dumped communication protocol to be (re)executed with
the respective external system, only in case the latter is deterministic (i.e.
same-input-same-output).
\end{itemize}
 
\begin{Verbatim}[fontsize=\small,frame=single,label=Code]
  InstallGlobalFunction( homalgIOMode,
    function( arg )
      local nargs, mode, s;
      
      nargs := Length( arg );
      
      if nargs = 0 or ( IsString( arg[1] ) and arg[1] = "" ) then
          mode := "default";
      elif IsString( arg[1] ) then	## now we know, the string is not empty
          s := arg[1];
          if LowercaseString( s{[1]} ) = "a" then
              mode := "all";
          elif LowercaseString( s{[1]} ) = "b" then
              mode := "basic";
          elif LowercaseString( s{[1]} ) = "d" then
              mode := "debug";
          elif LowercaseString( s{[1]} ) = "f" then
              mode := "file";
          elif LowercaseString( s{[1]} ) = "p" then
              mode := "picto";
          else
              mode := "";
          fi;
      else
          Error( "the first argument must be a string\n" );
      fi;
      
      if mode = "default" then
          ## reset to the default values
          HOMALG_IO.color_display := false;
          HOMALG_IO.show_banners := true;
          HOMALG_IO.save_CAS_commands_to_file := false;
          HOMALG_IO.DoNotDeleteTemporaryFiles := false;
          HOMALG_IO.SaveHomalgMaximumBackStream := false;
          HOMALG_IO.InformAboutCASystemsWithoutActiveRings := true;
          SetInfoLevel( InfoHomalgToCAS, 1 );
  	homalgMode( );
      elif mode = "all" then
          homalgIOMode( "debug" );
          homalgIOMode( "file" );
      elif mode = "basic" then
          HOMALG_IO.color_display := true;
          HOMALG_IO.show_banners := true;
          SetInfoLevel( InfoHomalgToCAS, 4 );
          homalgMode( "basic" );	## use homalgIOMode( "basic", "" ) to reset
      elif mode = "debug" then
          HOMALG_IO.color_display := true;
          HOMALG_IO.show_banners := true;
          SetInfoLevel( InfoHomalgToCAS, 8 );
          homalgMode( "debug" );	## use homalgIOMode( "debug", "" ) to reset
      elif mode = "file" then
          HOMALG_IO.save_CAS_commands_to_file := true;
      elif mode = "picto" then
          HOMALG_IO.color_display := true;
          HOMALG_IO.show_banners := true;
          SetInfoLevel( InfoHomalgToCAS, 4 );
  	homalgMode( "logic" );	## use homalgIOMode( "picto", "" ) to reset
      fi;
      
      if nargs > 1 and IsString( arg[2] ) then
          CallFuncList( homalgMode, arg{[ 2 .. nargs ]} );
      fi;
      
  end );
\end{Verbatim}
 

 This is the part of the global function \texttt{homalgSendBlocking} that controls the visibility of the communication. 
\begin{Verbatim}[fontsize=\small,frame=single,label=Code]
  io_info_level := InfoLevel( InfoHomalgToCAS );
  
  if not IsBound( pictogram ) then
      pictogram := "   ";
  elif io_info_level >= 3 then
      ## add colors to the pictograms
      if pictogram = HOMALG_IO.Pictograms.ReducedEchelonForm and
         IsBound( HOMALG.color_BOE ) then
          pictogram := Concatenation( HOMALG.color_BOE, pictogram, "\033[0m" );
      elif pictogram = HOMALG_IO.Pictograms.BasisOfModule and
        IsBound( HOMALG.color_BOB ) then
          pictogram := Concatenation( HOMALG.color_BOB, pictogram, "\033[0m" );
      elif pictogram = HOMALG_IO.Pictograms.DecideZero and
        IsBound( HOMALG.color_BOD ) then
          pictogram := Concatenation( HOMALG.color_BOD, pictogram, "\033[0m" );
      elif pictogram = HOMALG_IO.Pictograms.SyzygiesGenerators and
        IsBound( HOMALG.color_BOH ) then
          pictogram := Concatenation( HOMALG.color_BOH, pictogram, "\033[0m" );
      elif pictogram = HOMALG_IO.Pictograms.BasisCoeff and
        IsBound( HOMALG.color_BOC ) then
          pictogram := Concatenation( HOMALG.color_BOC, pictogram, "\033[0m" );
      elif pictogram = HOMALG_IO.Pictograms.DecideZeroEffectively and
        IsBound( HOMALG.color_BOP ) then
          pictogram := Concatenation( HOMALG.color_BOP, pictogram, "\033[0m" );
      elif need_output or need_display then
          pictogram := Concatenation( HOMALG_IO.Pictograms.color_need_output,
                               pictogram, "\033[0m" );
      else
          pictogram := Concatenation( HOMALG_IO.Pictograms.color_need_command,
                               pictogram, "\033[0m" );
      fi;
  fi;
  
  if io_info_level >= 3 then
      if ( io_info_level >= 7 and not need_display ) or io_info_level >= 8 then
          ## print the pictogram, the prompt of the external system,
          ## and the sent command
          Info( InfoHomalgToCAS, 7, pictogram, " ", stream.prompt,
                L{[ 1 .. Length( L ) - 1 ]} );
      elif io_info_level >= 4 then
          ## print the pictogram and the prompt of the external system
          Info( InfoHomalgToCAS, 4, pictogram, " ", stream.prompt, "..." );
      else
          ## print the pictogram only
          Info( InfoHomalgToCAS, 3, pictogram );
      fi;
  fi;
\end{Verbatim}
 }

 }

  }

   
\chapter{\textcolor{Chapter }{External Rings}}\label{Rings}
\logpage{[ 4, 0, 0 ]}
\hyperdef{L}{X82A8947087082312}{}
{
  
\section{\textcolor{Chapter }{External Rings: Representation}}\label{Rings:Category}
\logpage{[ 4, 1, 0 ]}
\hyperdef{L}{X85D85B6C837F4B05}{}
{
  

\subsection{\textcolor{Chapter }{IsHomalgExternalRingRep}}
\logpage{[ 4, 1, 1 ]}\nobreak
\hyperdef{L}{X7D2FB57D87A6B71A}{}
{\noindent\textcolor{FuncColor}{$\Diamond$\ \texttt{IsHomalgExternalRingRep({\slshape R})\index{IsHomalgExternalRingRep@\texttt{IsHomalgExternalRingRep}}
\label{IsHomalgExternalRingRep}
}\hfill{\scriptsize (Representation)}}\\
\textbf{\indent Returns:\ }
\texttt{true} or \texttt{false}



 The internal representation of \textsf{homalg} rings. 

 (It is a representation of the \textsf{GAP} category \texttt{IsHomalgRing}.) }

 }

 
\section{\textcolor{Chapter }{Rings: Constructors}}\label{Rings:Constructors}
\logpage{[ 4, 2, 0 ]}
\hyperdef{L}{X7C7962B97E6CDFE2}{}
{
  }

 
\section{\textcolor{Chapter }{External Rings: Operations and Functions}}\label{Rings:Operations}
\logpage{[ 4, 3, 0 ]}
\hyperdef{L}{X7B1D4BD485F406CA}{}
{
  }

  }

 

\appendix


\chapter{\textcolor{Chapter }{Overview of the \textsf{homalg} Package Source Code}}\label{FileOverview}
\logpage{[ "A", 0, 0 ]}
\hyperdef{L}{X84555A0687FBAE33}{}
{
  The package \textsf{HomalgToCAS} is split in several files. \begin{center}
\begin{tabular}{l|l}Filename \texttt{.gd}/\texttt{.gi}&
Content\\
\hline
\texttt{HomalgToCAS}&
the global variable \texttt{HOMALG{\textunderscore}IO} and\\
&
the global function \texttt{homalgIOMode}\\
&
\\
\texttt{homalgExternalObject}&
\textsf{homalg} external objects, \texttt{homalgPointer},\\
&
\texttt{homalgExternalCASystem}, \texttt{homalgStream}, ...\\
&
\\
\texttt{HomalgExternalRing}&
\texttt{CreateHomalgExternalRing}, \texttt{HomalgExternalRingElement}\\
&
\\
\texttt{HomalgExternalMatrix}&
\texttt{ConvertHomalgMatrix}, \texttt{ConvertHomalgMatrixViaFile}\\
&
\\
\texttt{homalgSendBlocking}&
\texttt{homalgFlush}, \texttt{homalgSendBlocking}\\
&
\\
\texttt{IO}&
\texttt{LaunchCAS}, \texttt{TerminateCAS}\\
\end{tabular}\\[2mm]
\textbf{Table: }\emph{The \textsf{HomalgToCAS} package files}\end{center}

 }

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

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

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


\printindex

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