%%
%% ch4.tex
%%

\chapter{User Defined Variables}
	
\section{Types of Variables}

Each user defined variable has a type. The possible types of variables are:
integer, ring, matrix (defined over a given ring), standard basis, and 
computation.

Rings are a basic concept of \Macaulay.  The major type of data which
\Macaulay\ manipulates are matrices with polynomial entries.  In order
to optimize calculations every matrix must be defined over a base
ring.  A ring contains necessary information such as the number of
variables, their names, and the monomial order being used.  The system
uses this information to compact the monomials into as small a space
as possible.  See \chapref{ch-rings} for details.

In \Macaulay, an {\em ideal} is simply a matrix with exactly one row.
This means that even if the entries of two different matrices $M$, $N$
with one row generate the same ideal, $M$ and $N$ are considered different.

A ring map is also represented as a matrix with one row 
(see \chapref{ch-rmaps}).

Computations include standard (\Grobner) bases, syzygies, and finite free
resolutions (see \chapref{ch-comps}).  A computation is made up of one or
more standard bases.  A standard basis is a matrix, together with 
a standard basis of the submodule generated by the columns of the matrix
(see \chapref{ch-matrices}).  

Variables can be created using the following commands:
\icmd {int} creates an integer, \icmd {ring} creates a ring. \icmd {ideal},
\icmd{mat}, \icmd{sparse}, and \icmd{poly} create matrices, \icmd{rmap},
\icmd{imap} create ring maps, and \icmd{std}, \icmd{nres}, \icmd{res} 
and the rest of the commands of \chapref{ch-comps}
create computations and standard bases.
    
\section{Commands to display and remove variables}

\cmd {listvars} {\optparm {a} \optparm {a}}			
\label{c-listvars} % listvars   List names and types of user variables

List the names and types of all variables currently defined.  

If the user types \type{listvars a}, then more detailed information
will be displayed.  If \type{listvars a a} is typed, then even more
detail is provided.  This extra detail describes the makeup of a computation,
the base ring of each variable, and whether a variable has been ``marked
for destruction''.  

If ``R'' is a user defined variable which is a ring, its type is displayed
as a ``matrix''.  This is because when a ring is created, it is created with
an ``anonymous'' name, and the value returned is actually an ideal (remember,
this means a matrix with one row) consisting of the variables in the ring.
See \chapref{ch-rings} for more details.

\cmd {type} {\parm {user defined variable}}	
\label{c-type} % type  Display an integer or matrix

This displays the value associated with the variable.  If the type of the
variable is a matrix, the matrix is displayed (see \secref{sec-moutput}).
If the variable is a ring, its variables are displayed.  In order to
view the other parameters of a ring, use the \icmd{pring} command.  If
the variable is a computation, this displays the matrix corresponding to the
standard basis which is the result of the computation.  To see the standard
basis itself, use the \icmd{putstd} command.  If the computation is a
resolution (from \icmd{res} or \icmd{nres}), then use \icmd{pres} to
display the corresponding matrices in the resolution.


\cmd {kill} {\parm {variable 1} \ldots \parm {variable n}}
\label{c-kill} % kill  Remove user variables

This removes the variables indicated and these variables can no longer
be referenced.  If no other variable is using that object, then the
space associated with it is removed.

For example, if ``R'' is a ring, then \type{kill R} will only remove
the space associated to ``R'' if there are no variables whose base ring
is ``R''.  In any case, the name ``R'' is removed and can be used again.  

Caveat: inside an interrupted computation (see \secref{sec-cfine}) it
is not advisable to kill variables, {\em especially} the interrupted
computation.  Dire and unpleasant things await those who do not heed this
warning!

\section{Referencing variables}
\label{sec-vref}

Most variables are referenced simply be typing their names, e.g. 
\type{R, myideal, f}.  There are two special situations.

First, there are many matrices in the resulting resolution coming from
the \icmd{res} and \icmd{nres} commands.  In order to use a specific
matrix in the resolution, you can use indexing to refer to the $i^{th}$
matrix.  For example, if the name of the resolution computation is ``w'',
then \type{w.3}, and \type{w.(2+1)} both refer to the third matrix of ``w''.
Arbitrary integer expressions are allowed as the index.  If the value of
the index is out of range, then a matrix with zero rows and columns is
returned.  This is useful when writing scripts.  

Indexing starts at one.  Some computations which have a single result
standard basis (\icmd{quotient}, \icmd{intersect}, and \icmd{modulo}) 
create an auxiliary matrix.  This matrix always has index ``0''.  See
\secref{sec-ccomps} for more details.

The second special situation occurs when entering a polynomial expression.
There are possible name conflicts between names of matrices and the names
of the ring indeterminates.  This is resolved by requiring that each
(1 by 1) matrix $f$ occuring in a polynomial expression be surrounded by
curly braces, e.g. \type{a+\{f\}} adds the ring indeterminate $a$ to the
polynomial $f$.

This problem occurs in several other places as well. \hey{include them here!}.
	
\section{Reusing Variable Names}

If a variable name exists, and another variable is made with the same
name, the first variable is ``killed''.  Therefore, it is not
necessary to \icmd {kill} a variable before reusing its name.  A name
can be reused if an operation is performed and the result of that
operation is stored in one of the operands.  For example: \type{add m
n m} will add the matrices m and n and store the result in m.

\section{Integer Variables}

The creation of integer variables is very simple.  All of the other
variables are much more complex and have separate chapters devoted to
them.

\cmd {int} {\parm {name} \parm {value}}
\label{c-int} % int  Create an integer variable with a given value

Creates an integer variable with the indicated value.  The value can be any
integer expression.  If the variable already has a value, it will be replaced
by the new value.  For example,

\begin{verbatim}
%  int i 3

%  int i i-1

%  int a (i^2-i+1)^3

%  type a     ; answer should be 27
; 27

\end{verbatim}


