%%
%% ch9.tex
%%

\chapter{System commands}

This chapter describes the system support commands available in \Macaulay.

\cmd{exit}{}

Exit \Macaulay.  All work not saved is lost! So be careful.  If you
are in the middle of an interupted computation, you must type "{\tt
exit all}" in order to exit.  Use the \icmd{continue} command to
continue an interrupted computation.

\cmd{reset}{}

Reset \Macaulay.  Again, all work is lost.  All variables are freed
and memory is reinitialized.  In almost all respects, you start with
a clean slate.  The only exception is in monitoring a \Macaulay\ session:
This command doesn't affect monitoring.


\cmd{version}{}

Displays the current \Macaulay\ version number, and the date the system
was created.  For instance, this manual was written for the following
version.

\begin{verbatim}
%  version
; version 3.0, created 5/18/89 DAB,MES

\end{verbatim}

\section{Finding help about \Macaulay}

\cmd{commands}{}

Display a list of every command of \Macaulay.  For example,

\begin{verbatim}
%  commands

; ac             fetch          min            ring-from-cols 
; add            flatten        modulo         ring-from-rows 
; ar             forcestd       monitor        ring-sum       
; betti          help           mr             rmap           
; calc           help-file      mult           row-degree     
; cat            hilb           ncols          row-degs       
; ce             homog          nres           sat            
; characteristic hulb           nrows          set            
; chcalc         hull           numinfo        set-value      
; codim          ideal          nvars          setcoldegs     
; coef           iden           outer          setdegs        
; col-degree     if             pc             setring        
; col-degs       imap           pfaff          shout          
; commands       in             pmap           size           
; compress       incr-set       poly           smult          
; concat         inpart         power          space          
; continue       int            pr             spairs         
; contract       intersect      pres           sparse         
; copy           is-zero        present-ring   std            
; degree         jacob          pring          std-minimal    
; diag           jump           prmat          stdpart        
; diff           k-basis        putchange      submat         
; dshift         keep           putmat         subtract       
; dsum           kill           putstd         syz            
; echo           koszul         qring          tensor         
; edit           lift           quotient       trace          
; edit-map       lift-std       random         transpose      
; elim           listvars       reduce         truncate       
; endmon         mat            res            type           
; ev             max            reset          version        
; exit           mc             ring           wedge          

\end{verbatim}

\cmd{help}{}

List the headings for which there is on-line help.  For example,

\begin{verbatim}
%  help
; (1) Syntax formats for arguments to commands.
; (2) System commands
; (3) command files
; (4) user defined variables
; (5) set variables
; (6) Integers
; (7) matrices
; (8) matrix manipulation commands
; (9) matrix edit commands
; (10) degrees of matrices
; (11) computations
; (12) ring map commands
; (13) resolution commands
; 
! which item (give it's number, <return> to leave help) ? <return>

\end{verbatim}

Choosing a number will display the list of topics under that heading.  
You then choose a topic number to find more information about the topic.

The ``help file'' is generated automatically from this manual, so their
structures are very similar.

\cmd{help}{\parm{topic}}

Display a small description of \parm{topic}.

\cmd{help-file}{\parm{file name}}

Display some documentation for the script file \parm{file name}.  Every line
in this file beginning with three semicolons is displayed.  Usually, this
information describes the parameters and function of a given script.
An error message is given if no file with this name can be found.  For
examples of such documentation, see \appref{app-scripts}.

\section{Recording a \Macaulay\ session}

\cmd{monitor}{\parm{file name}}

This command starts recording all interactions between the user and
\Macaulay, in the file \parm{file name}.  The user can examine or
print this file at a later time.

\cmd{endmon}{}

This command turns off the recording which was started with the
\icmd{monitor} command.  Leaving \Macaulay\ also turns off
recording.

\section{\Macaulay\ parameters}
\label{sec-sysparam}

\Macaulay\ has a set of parameters which are used to control
display or computing.  The values of these parameters can be viewed or
set using the \icmd{set} and \icmd{incr-set} commands.

\begin{description}

  \item[auto] This integer flag, if greater than zero, instructs the
system to not perform auto-reduction on the elements of a standard
basis.  If this variable is set to a positive number, the calculations
will slow down very dramatically.  Thus, it is perhaps crazy to even
think about changing the value of this variable.  The default is 0.

  \item[autocalc] This integer flag, if not equal to zero,
instructs the computation commands (\icmd{std}, \icmd{lift-std},
\icmd{res}, \icmd{nres}, \icmd{syz}, \icmd{intersect}, \icmd{modulo}, 
and \icmd{quotient}) to automatically start their computations.  If the
value of this flag is negative, the above computations are performed
to completion.  If the value is positive, the commands compute their
results through degree $d$, where $d$ is the value of the ``autodegree'' 
set variable below.  The default value is -1.

  \item[autodegree] This integer value describes the highest degree to which
to compute during computations.  This flag is only active if the ``autocalc''
flag is set to a positive value.  The default value is 0.

  \item[char0] This integer flag, if zero, instructs \Macaulay\ to
attempt to lift all numbers mod p to rational numbers.  This lifting
is done for display only: no change in the internal representation of
numbers ever occurs.  If this flag is positive, then each coefficient
of each polynomial is displayed without lifting.  The default value is
0.

  \item[echo] This integer flag, if greater than zero, instructs
\Macaulay\ to echo onto the screen everything which the user types.
This is useful when the input is coming from somewhere other than the
users keyboard.  For example, when using MPW and command files on a
Macintosh, or when using emacs on Unix systems.  The default value is
0.

  \item[linesize] The maximum width (in number of characters) of a
displayed matrix. This should be set to the width of the screen.  The
default value is 79.

  \item[maxdegree]  This integer value describes the maximum degree of
a monomial in a ring.  In the \icmd{ring} command, this maximum degree is used
to determine internal monomial tables.  Depending on the monomial order
chosen, the actual maximum degree may be much smaller than this value.
For example, if a ring has one block of 100 variables, then the maximum
degree is 6.  However, if a block of variables has only several variables, 
then ``maxdegree'' is used.  For example, if a ring has a block with one
variable, and ``maxdegree'' is set to 1000, then the maximum degree of this
variable in any monomial is 1000.  Currently, the limit on ``maxdegree'' is
about 12000.  The default value is 512.

  \item[nlines] The number of blank lines which \Macaulay\ displays
between commands.  The default value is 1.

  \item[prcomment] This integer flag, if positive, instructs
\Macaulay\ to display a leading semicolon in front of any displayed
values.  This is useful in conjunction with monitoring a \Macaulay\
session: the resulting log file can then be used as input to
\Macaulay.  The default value is 1.

  \item[prlevel] This integer flag, if larger than zero, instructs the
system to suppress {\it all} output to the user's screen.  This is
very useful for having certain commands work quietly.  Beware though,
that {\it all} output is silenced: this includes the \Macaulay\
prompt, making it hard to tell what is going on.  For this reason,
this is used mainly in command files: the first line of the command
file increments \icmd{prlevel} and the last line decrements it, using
the \icmd{incr-set} command.

Note that in a command file, \Macaulay\ usually echos to the screen the
commands in the file.  However, \Macaulay\ does a special check to see
if the command is ``{\tt set prlevel 1}'', or ``{\tt incr-set prlevel
1}''.  If so, this line is not echoed.  Thus, in a command file,
these lines are never displayed, allowing the file to act silently.

  \item[showmem] This integer flag, if positive, instructs \Macaulay\ to
display memory usage at every increase (currently about every 64 Kbytes).
Default value is 1.

  \item[timer] This integer flag, if larger than zero, tells
\Macaulay\ to display the amount of time used for each command.  If
the amount of time is less than one second, nothing is displayed.  On
multi-user systems, this time records the amount of time the system
used for \Macaulay, not the time it used to process everyone.  The
default value is 0.

  \item[verbose] This integer flag, if larger than zero, displays
extra feedback information during certain computations.  The commands
which display extra information are the computation commands (see
\chapref{ch-comps}),
\icmd{reduce}, \icmd{lift}, \icmd{hilb}, \icmd{codim}, \icmd{degree}, 
\icmd{wedge}, \icmd{hulb} and \icmd{hull}.  The exact information 
displayed is described with the particular command.  The default value is 0.

\end{description}

The commands for manipulating these parameters are the following.

\cmd{set}{}

Display the current setting of all the above \Macaulay\ parameters.

\cmd{set}{\parm{variable}}

Resets the \parm{variable} to it's default value.

\cmd{set}{\parm{variable} \parm{integer}}

Set the \parm{variable} to the value of the given integer expression.

\cmd{set}{default}

Reset every \Macaulay\ variable to it's default value.

\cmd{incr-set}{\parm{variable} \parm{integer}}

Increment the given \Macaulay\ parameter by the specified integer expression.

\cmd{set-value}{\parm{variable} \parm{result integer}}

Place the value of the given \Macaulay\ parameter into the specified integer
variable.  This is useful to save values inside of scripts which need to
be restored at the end of the script.

\section{Space Utilization}

\cmd{space}{}

Display the amount of memory which \Macaulay\ is currently using.
For example,

\begin{verbatim}
%  space
  378K  total memory requested by allocator
   19K  of requested memory not yet used

\end{verbatim}

\cmd{space}{all}

This displays internal space utilization of \Macaulay. Internally,
\Macaulay\ stores most objects in ``stash''s which consist of a set of
objects, called ``slugs'' in the output of this command.  The
following example illustrates this command.  This \icmd{space} command
was done after computing a finite free resolution of the ideal
generated by the variables in a polynomial ring with 10 variables.

\begin{verbatim}
%  space all
       #blocks  #slugs   #used    size   % used
    5K       1     122       9      36      8%   storage allocator
    5K       1      44      12     100     28%   modules
   18K       4    1256    1023      14     82%   std bases
    5K       1       1       1    4400    100%   small memory
   44K      10      70      67     604     96%   arrays
    5K       1     366       0      12      0%   monomial syzygies
  155K      36   11304   11272      14    100%   polys in ring
   56K      13     520     512     110     99%   mon tables: monom heads
   56K      13    1053    1023      54     98%   mon tables: monomials
   13K       3     732     510      18     70%   mon tables: parens
  357K      83  blocks under control of storage allocator
  357K      83  blocks in use    ( 100%  of allocated blocks )
  355K  allocated into slugs     ( 100%  yield               )
  332K  slugs in actual use      (  94%  of allocated slugs  )
  378K  total memory requested by allocator
   19K  of requested memory not yet used

\end{verbatim}

The most important information present is the amount of memory
allocated by \Macaulay.  This information is displayed by using ``{\tt
space}''.  In the above example, this is 378K.  Other useful facts
that one can determine from the above table:
\begin{enumerate}
  \item The number of monomials actually being used in the one ring
which is defined is 11,272.  Each monomial has size exactly 14 bytes.
  \item The number of monomial syzygies (i.e. S-pairs) which still need to be
computed (totaled over all active computations) is the number of
``used slugs'' in the ``monomial syzygy'' stash. In this case, there
are none left to be computed.
  \item The monomial table stashes are used for fast lookup of
monomials during the computation of standard bases.
  \item Each ring creates a special table for encoding and decoding
its monomials.  This table is usually about 12Kbytes in size. This
space is not shown above, except in the ``total memory requested'' number.
\end{enumerate}

\cmd{size}{\parm{matrix}}

Display the number of generators (i.e. columns) of the
matrix, the number of standard basis elements, and the number of
monomials actually being used to represent these polynomials.  This
information is given degree by degree along with the total values.
For example, 

\begin{verbatim}
%  size rw.5    ; the fifth matrix in the koszul complex on 10 variables
; degree   #gens    #standard    #monoms in gens    #monoms in std
;      5     252          252               1260              1260
; total      252          252               1260              1260

\end{verbatim}

This information is useful when starting to compute a very large problem.
Often, one monomial order will be much better than others (for example, 
permuting the variables might give a much more ``efficient'' order).  One
tries ``heuristically'' to find a good order.  This command can be useful 
for this step.

\cmd{spairs}{\parm{matrix}}

This command displays the number of S-pairs yet to be computed in each
degree, if a standard basis of \parm{matrix} is currently being
constructed.  It does not keep track of how many S-pairs have already
been done.  Also, it is not always a good indication of how much time a
computation will need, since as S-pairs are done, more S-pairs might
be queued for reduction.  Nevertheless, it sometimes gives one an idea
how difficult a computation will be.

\section{Interrupting \Macaulay's computations}

Certain operations in \Macaulay\ can be stopped before their
completion.  Some of these can then be continued.  On the Macintosh,
\Macaulay\ can be interrupted by clicking the mouse button.  On all
other systems, \Macaulay\ can be interrupted by typing {\tt (CNTRL)-C}.

Each of the computation commands (see \chapref{ch-comps}) can be interrupted
and then restarted using the \icmd{continue} command.  The commands
\icmd{type}, \icmd{hilb}, \icmd{wedge}, \icmd{reduce} and \icmd{lift} can
be cancelled.  They cannot be continued or restarted, short of
re-issuing the original command.

The exact actions taken when you interrupt a computation are described
in the following list.

\begin{description}

  \item[calc] Interrupting this command temporarily pauses the
computation, and the user can use all the \Macaulay\ commands desired,
before restarting the computation with the \icmd{continue} command
(see \chapref{ch-comps}).  

  \item[type] Interrupting the \icmd{type} command stops displaying the 
current matrix.  

  \item[hilb] Interrupting \icmd{hilb} simply stops the computation of 
the Hilbert function.  No partial results exist to display.

  \item[wedge] Interrupting this command stops the computation of the
determinants, and the result matrix contains those determinants
already computed.  Short of restarting the whole computation, there is
no way to continue the command.

  \item[reduce,lift] This command when interrupted returns the
partially constructed results.  Again, there is no way to continue
this computation after the interrupt.

\end{description}

\section{Redirection of input and output}

Many commands display their results onto the screen.  You
may want to put the results into a file for further editing or
viewing.  \Macaulay\ supports Unix-like redirection of input and output.  
To put the output from a command into a file, instead of the screen, add to the
command line the ``argument'' {\tt >myfile}, where {\tt myfile} is the
name of the file that \Macaulay\ will use.  The spacing is important;
there cannot be a space after the {\tt >}.  For example,

\begin{verbatim}
%  pres j >j.res

\end{verbatim}

This puts the displayed version of the resolution into the file
``j.res'', instead of typing it to the screen.

Another important use of redirection is to write a matrix to a file, using 
the \icmd{putmat} command.  This file can be read by redirecting the input
file.  This is done in the same way as above, but using ``{\tt <}'' 
instead of ``{\tt >}''.  For example,

\begin{verbatim}
%  type j
; a2+b2+c2 

%  putmat j >j.mat

%  mat k j.mat      ; same as "mat k <j.mat" except no prompting is done

%  type k
; a2+b2+c2 

\end{verbatim}

It is also possible to use redirection of the input file to run
``script'' files.  These are files which contain commands for
\Macaulay\ to execute.  Such script files may have parameters, and
some facilities exist for rudimentary programming.  For more
information on this, see \chapref{app-scripts}.
