\chapter{Scripts of Macaulay (by D. Eisenbud, M. Stillman}
\label{ap-scripts}

In this appendix we describe the \Macaulay\ scripts which we provide.
These descriptions are taken directly from each script.

\section{\tt adj\_of\_cat}

\begin{verbatim}
Usage:
    <adj_of_cat p q j
Produces the p by p+q-1 adjoint matrix
of a p by q catalecticant matrix, which is
(for p=3,q=2) a matrix of the form
    a b 0 0
    0 a b 0
    0 0 a b .
Parameters:
            p,q = number of rows, number of variables
Output values:
            j = p x (p+q-1) matrix
The entries of j are from the first q variables of the current ring.
The matrix j is the traditional answer to the problem
of producing a matrix whose pxp minors generate the pth
power of the maximal ideal in q variables.
\end{verbatim}

\section{\tt adjoin\_fractions}

\begin{verbatim}
Usage:
    <adjoin_fractions a J S K
Compute S/K = R[J/a], where R is the base ring of J, a is a nonzero-
divisor of R, and S is a polynomial ring over R supplied by the user.
Parameters:
 a = 1x1 matrix over R
 J = an ideal of R
 S = a polynomial ring over R, whose extra variables y[i] correspond to the
     generators, J[i] of J, and have deg y[i] = deg J[i] - deg a.
Output values:
 K = an ideal of S.
The ideal K = ((ay[i] - J[i], all i) : a*).  This is correct because
upon inverting the element a, the desired ideal is obviously
    (ay[i] - J[i], all i).
The ring R may be a quotient ring.
An alternate method would be to compute the ring R[(J,a)t] using
the script "blowup", and then set a := 1.  In effect this computes
the ring of an affine open set of the blowup.
Caveats:
    The degree of a MUST BE < the degrees of the given generators of J.
\end{verbatim}

\section{\tt adjoint}

\begin{verbatim}
Usage:
    <adjoint f A B g
Given a map f:(A \tensor B) --> C and the identity maps A of A and
B of B,
where A,B,C are free modules, this script sets g to the adjoint
map g:A --> (C \tensor B^*).
Parameters:
            f = c x a*b  matrix
            A = a x a identity matrix
            B = b x b identity matrix
Output values:
            g = b*c x a matrix
It does this by writing g as the composite of
T = (A \tensor t) : A --> (A \tensor B \tensor B^*)
where t is the trace map
t: R --> (B\tensor B^*),
and the map
S = (f \tensor B^*):(A \tensor B \tensor B^*) --> (C \tensor B^*).
\end{verbatim}

\section{\tt annihilator1}

\begin{verbatim}
Usage:
    <annihilator1 X ann_X
computes the annihilator by calling "quotient"
Parameters:
            X = a module
Output values:
            ann_X = its annihilator, as an ideal with standard
            basis.
This script essentially computes the intersection
of the annihilators of all the generators of X.
A different method -- sometimes faster, sometimes
slower -- is used by "<annihilator2
\end{verbatim}

\section{\tt annihilator2}

\begin{verbatim}
Usage:
    <annihilator2 X ann_X
computes the annihilator of X by finding the annihilator of
a "general" element, by the rational normal curve method.
Parameters:
            X = a module
Output values:
            ann_X = its annihilator, as an ideal with standard
            basis.
This script is sometimes dramatically faster than the obvious method
using quotient, (done in annihilator1) sometimes slower.
Caveats:  The script does not necessarily produce a minimal
generating set for the annihilator.
\end{verbatim}

\section{\tt binomial}

\begin{verbatim}
Usage
    <binomial n k b
Parameters:
    n,k = integers
Output values
            b = n choose k.
Sets b to the binomial coefficient n choose k.
This is the combinatorial binomial coefficient, =0 if n<0.
Caveat:  Works up to n = 29, all k, but not for n=30, k=15.
\end{verbatim}

\section{\tt block\_map}

\begin{verbatim}
Usage:
    <block_map lo hi f
Create a ring map (over the current ring) which sends the given range 
of variables to themselves, but sends every other variable to 0.
Parameters:
  lo, hi = two integers specifying the range of variables.  The variables
       are numbered starting at 1.
Output values:
  f = 1xn matrix which is the desired ring map.
Caveats: if lo <= 0, problems can occur.
\end{verbatim}

\section{\tt blowup}

\begin{verbatim}
Usage:
	<blowup J T L
L is set to be the ideal with standard basis defining the Rees 
ring R[tJ] as a quotient ring of a polynomial ring T over the base 
ring R of J.  The variable "t" is the first variable of T.
Parameters:
  J = ideal to blowup.
  T = a polynomial ring over R in variables whose weights are 
  proportional to the degrees of the generators of J.
Output values:
 L = the result ideal in T.
The ring R may be a quotient ring. 
The ideal L defining the blowup ring R[tJ] is
obtained by eliminating "t" from the ideal K produced by the script
"blowup0".  The situation is summarized by the following diagram:
	K ---> S = R[t,y] --->> R[t]   (y[i] |--> tJ[i])
	|        |               |     
L ---> T = R[y]   --->> R[tJ]

where the vertical lines represent inclusions.
It is convenient to form the ring T by making a polynomial ring whose
generators correspond to the generators of J, and then use ring-sum
to tensor this ring with R.
Caveats:
If the ring T has more generators than needed, the correct
initial subset is chosen.

\end{verbatim}

\section{\tt blowup0}

\begin{verbatim}
Usage:
    <blowup0 J K
K is set to be the ideal with a standard basis defining the
ring R[t] as a quotient ring of a polynomial ring 
S = R[t,y[1],...y[ncols(J)]]
under the map sending y[i] to the i th generator of J.
The ring R is the base ring of J.  The variable "t" is the first 
variable of S.
Parameters:
  J = ideal to blow up
Output values:
  K = standard basis of the ideal (y[i]-tJ[i], i=1..ncols(J)), where
  J[i] stands for the i th generator of J, and K is an ideal in the
  the ring S.
The ring S = R'[t, y[1], ..., y[ncols(J)]], where R' is
a copy of R, with variables named x[i], using the reverse 
lexicographic order with three blocks of variables: the first block
consists of the variable "t", the second block contains the y[i], and
the last block contains the variables x[i] corresponding to the
variables of R.
The ring R may be a quotient ring. 
This script is useful for computing blowup rings and associated graded
rings (normal cones).  The ideal L defining the blowup ring R[tJ] is
obtained by eliminating "t" from K.  The normal cone of J can be 
obtained by adding the generators of J to the ideal L 
(see the script "normalcone" for a different method).
\end{verbatim}

\section{\tt cohomology}

\begin{verbatim}
Usage:
    <cohomology i M j H
Computes the cohomology module
H = \sum_{n >= 0} H^i(M(n))
of the module M , regarded as
a coherent sheaf on projective space.
Parameters:
            i>0 the index of the cohomology group
            M a module
            j>0 a sufficiently large integer (see below.)
Output values:
            H = module.
    H is computed as the truncation in degrees >=0
of the module Ext^i(J, M), where J is the ideal
generated by the jth powers of the variables in the
base ring of M.
    For the answer to be guaranteed correct, it is enough
to have:  All the syzygy modules of M are generated
in degrees <= j + numvars - 1.
Caveats:
    Note that the answer returned is
TRUNCATED IN DEGREES >= 0 !  To get all of Ext^i(J, M)
use <cohomology1 i M j H instead.  This is desirable, for
example, when computing H^0, or the first nonzero H^i with
i >= 0, but in general the low degree parts may not mean much.
\end{verbatim}

\section{\tt cohomology1}

\begin{verbatim}
Usage:
    <cohomology1 i M j H
Computes the cohomology module
H = \sum_{n >= 0} H^i(M(n))
of the module M , regarded as
a coherent sheaf on projective space.
The low degree parts of the module computed may
or may not mean much (see below).
Parameters:
            i>0 the index of the cohomology group
            M
            j>0 a sufficiently large integer (see below.)
Output values:
    H = Ext^i(J, M),
where J is the ideal
generated by the jth powers of the variables in the
base ring of M.
    The answer coincides with the cohomology (at least)
in degrees >= d - numvars + 1 - j,
where d is the maximum degree of a generator of a syzygy module of M,
and numvars is the number of variables in the ring.
\end{verbatim}

\section{\tt complement}

\begin{verbatim}
Usage:
    <complement submodule complement
Given a submodule of a free module, the script computes
a minimal summand of the free module such that with the
submodule, the summand generates the free module.
Parameters:
            submodule = matrix whose image is the submodule
Output values:
            complement = matrix of a split mono whose image
                                            is the complement
\end{verbatim}

\section{\tt copyring}

\begin{verbatim}
Usage:
    <copyring var newring

Makes a copy of the current ring with name newring and variable
names var[1], var[2], ... .  Puts all the vars into one reverse
lex block.  Makes new ring the current ring.
Parameters:
    var = a letter, used in the names of the new variables
Returned values:
    newring = a nearly faithful copy of the current ring
This script is useful when two rings need to be tensored and a
conflict of variable names must be avoided.
Caveats and complaints:
    The variables in the newring form a single reverse lex block,
no matter what they were in the old ring.  For this reason, if the
current ring is a quotient ring when this script is called, a new
standard basis for the presenting ideal must be computed.  For
this reason, and because putting all the variables in one block
might sometimes make the degree bound undesirably low, it might be
better to either have a built-in command to do this, which would
copy all the data of the ring, or else (more flexible) make the
"Monomial order" information in the ring accessible and handleable
by the rest of Macaulay.  For example the monomial order might be
specified by a matrix as follows:
    Each row of the matrix would represent what is now a term in
the sequence of specification made in response to the monomial
order prompt in the ring command: a row beginning with a c would
represent the component vector, a row beginning with a w would be
followed by integers and represent a weight vector, a row
beginning with an integer would represent a reverse lex block with
that many variables (as currently).  There would have to be a
utility to generate such matrices.  Alternately, and maybe more
conveniently if less mnemonically, the code for each type of row
could be an integer (instead of c, w or nothing.)
\end{verbatim}

\section{\tt cotan}

\begin{verbatim}
Usage:
    <cotan ideal Omega
This script sets Omega to the graded module
representing the cotangent sheaf of the
variety defined by the given ideal.
Parameters:
            ideal = 1xn matrix
Output values:
            Omega = module over the base ring of ideal
The matrix Omega returned is actually a presentation
over the polynomial ring of the module
coker I/I^2 --> OmegaP,
where I is the given ideal, in the polynomial
ring R, and OmegaP is the module corresponding
to the cotangent sheaf of the ambient projective
space, restricted to the subscheme Z(I).  OmegaP
is computed as the kernel of the map
(R/I)(-1)^(n) --> R/I,
where n is the number of variables of R,
so it is a module of depth 2.
            One would really like to compute the module
\sum H^0( Omega(n) ) directly here.  Of course it can be
obtained from the computed Omega by using
<cohomology 0 Omega j Omega'
but one actually has the desired module already in
some cases:
    If I is a prime then I^2 is primary iff the
map I/I^2 --> OmegaP is a
monomorphism.  If this is satisfied and R/I has
depth >=1, then (sinced OmegaP then has depth >=1) the
computed module will have depth >= 2 if depth I/I^2 >= 3,
and depth >= 1 if depth I/I^2 >= 2.
Thus if I is a complete intersection, and
depth R/I >= 3 (resp 2) then depth Omega >= 2 (resp 1).
Caveats:
This script must be modified to work directly in the
multihomogeneous case (subvariety of Pr x Ps...);
there one computes OmegaP as the
kernel of the direct sum of the the maps corresponding
to the different sets of variables.  See the script
cotan_bihom form the bihomogeneous case
\end{verbatim}

\section{\tt cotan\_bihom}

\begin{verbatim}
Usage:
    <cotan_bihom x[0]..x[r] y[0]..y[s] ideal Omega
This script sets Omega to the graded module
representing the cotangent sheaf of the
variety defined by the given bihomogeneous ideal
in Pr x Ps.
Parameters:
            x[0]..x[r] y[0]..y[s] = variable lists
            ideal = 1xn matrix, bihomoageneous over the base ring
                            which is a poly ring in the 2 sets of vars
                            x[0]..x[r] y[0]..y[s].
Output values:
            Omega = module over the base ring of ideal
The matrix Omega returned is actually a presentation
over the polynomial ring of the module
coker I/I^2 --> OmegaP,
where I is the given ideal, in the polynomial
ring R, and OmegaP is the module corresponding
to the cotangent sheaf of the ambient projective
space, restricted to the subscheme Z(I).  OmegaP
is computed as the kernel of the map
(R/I)(-1)^(n) --> R/I,
where n is the number of variables of R,
so it is a module of depth 2.
            One would really like to compute the module
\sum H^0( Omega(n) ) directly here.  Of course it can be
obtained from the computed Omega by using
<cohomology 0 Omega j Omega'
but one actually has the desired module already in
some cases:
    If I is a prime then I^2 is primary iff the
map I/I^2 --> OmegaP is a
monomorphism.  If this is satisfied and R/I has
depth >=1, then (sinced OmegaP then has depth >=1) the
computed module will have depth >= 2 if depth I/I^2 >= 3,
and depth >= 1 if depth I/I^2 >= 2.
Thus if I is a complete intersection, and
depth R/I >= 3 (resp 2) then depth Omega >= 2 (resp 1).
Caveats:  This script is not as useful as it might be
because Macaulay has no good way of keeping track of the
bigrading, so the bidegrees of the generators of Omega
must be computed by hand from the matrices in the resolution
of vars@. (That is, from the way that the presentation for
OmegaP is computed.)
\end{verbatim}

\section{\tt deg01}

\begin{verbatim}
where
result = 
Usage:
    <deg01 I d result
Given an ideal I in 2 sets of variables (i.e. ring has two blocks), find
a k-basis for the degree (d, 1) part of the quotient ring S/I.
Parameters:
 I 	= ideal, bihomogeneous, where first weight vector is the one used in
  the ring, and the second is: each variable in the first block
  of variables has degree 1, and the rest have degree 0.  It is
  assumed that a STANDARD BASIS of I HAS BEEN COMPUTED.
 d	= integer.
Output values:
 result = the ideal consisting of a set of  monomials of 
      degree (d, 1) which form a basis of S/I in degree (d,1). 
\end{verbatim}

\section{\tt diagonal\_submodule}

\begin{verbatim}
Usage:
    <diagonal_submodule f M h M1
Given any map f: R --> S of rings, (WHERE R IS THE CURRENT RING)
any S-module M presented as
    F -->G --> M -->0,
and any inclusion h: G --> H,
the script computes the S-submodule M1 of M generated by
G \intersect H_R,
where H_R is the R-free R-submodule of H  generated by
the given S-generators.
For example, if f:k[zij] --> k[xi yj] is a Segre map, then given a
bigraded S-module M and a monomorphism h from the free module of
generators of M to a free module generated in degrees n,n (n \in
Z) this script computes the "diagonal" S-module generated by all
elements of M of bidegree n,n (n \in Z).
Parameters:
    f = 1xn matrix over a ring S.  THE VARIABLES OF THE CURRENT
    RING MUST HAVE DEGREES PROPORTIONAL TO THOSE OF THE ENTRIES OF f.
    M = module over S
    h = matrix over S which can be composed with M as hM.
Output values:
    M1 = module over S.
The method is as follows: we use pushforward1 to compute the intersection
    hm1:F1_R --> H_R of
h m F with H_R, since this is the set of relations on the
R-submodule of the cokernel of hm generated by the given
S-generators of H.  Then we use f to tensor up to S, obtaining
hm1: F1 --> H; this will be the S-submodule generated by the
intersection.  We lift this map back to G (we can since its image
is by definition a submodule of the image of G under h) to get the
result M1.
Caveats:
   This really ought to be done by having Macaulay keep track of
bigradings with a facility like "trunc" for the multigraded case.
\end{verbatim}

\section{\tt double\_dual}

\begin{verbatim}
Usage:
    <double_dual M N f
N is set equal to the double dual
Hom(M,Hom (M, R)) of M over whatever ring
M is defined.  f is set to the natural map from
M to N (that is, from the free module giving
the generators of M to the one giving the generators
of N.
Parameters:
            M = module
Output values:
            N =  M^**
    f : M --> N the natural map (given on the generators)
The torsion submodule of M is the kernel of the map f;
it can be computed by a call of the form
    <kernel f M N torsion
    type torsion
See the script "kernel" for an example.
Method: Let m be the dual of a presentation map of M.  2 steps of
the resolution of m are computed.  Writing n.-1 for
the dual of the second, the desired presentation of
N is obtained as n.1 , the 3rd map in the resolution
beginning with n.-1.  The map f is obtained by lifting
the dual of m.2 along n.0.
Caveats:
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
\end{verbatim}

\section{\tt double\_dual1}

\begin{verbatim}
Usage:
    <double_dual1 M A N f
N is set equal to the double dual into A,
Hom(M,Hom (M, A)) of M over whatever ring
M is defined.  f is set to the natural map from
M to N (that is, from the free module giving
the generators of M to the one giving the generators
of N.
Parameters:
            M,A modules
Output values:
            N = Hom(M,Hom (M, A))
            f : M --> N the natural map
The A-torsion submodule of M (=the intersection
of the kernels of all maps from M to A)
is the kernel of the map f;
it can be computed by a call of the form
    <kernel f M N Atorsion
    type Atorsion
In case A is the ring over which M is defined, use
<double_dual instead (note that A does not appear in the
argument list of <double_dual)
Explanation:
(Notation:  Let
    m: GM /to FM          be a presentation of M.
    a: GA /to FA          be a presentation of A.
ma: ** \to FMA   be a presentation of (M,A) -- that is, Hom(M,A)
N = maa: ** \to FMAA be a presentation of ((M,A),A).
f_ma: FMA \to (FM,FA) be the map inducing the natural (M,A) \to (FM,A)
f_maa: FMAA \to (FMA,FA) be the map inducing the natural map
                      ((M,A),A) to (FMA,A)
taut: FM \to ((FM,FA),FA) be the tautological map.)
T the map (f_ma^* \tensor FA)
The desired map f is then the map FM \to FMAA obtained by lifting the
composite s = (T)(taut) along f_maa.
\end{verbatim}

\section{\tt dual\_variety}

\begin{verbatim}
Usage:
    <dual_variety I c J
Given the ideal I of a variety X of codimensions c in projective space,
forms the classical dual variety -- that is, the closure
of the set of hyperplanes containing
tangent planes at smooth points of X.
Parameters:
            I = and ideal
Output values:
            J = an ideal, in the same set of variables as I
\end{verbatim}

\section{\tt ext}

\begin{verbatim}
Usage:
    <ext n a b c
A presentation of the module
Ext^n(a,b) is put into the
variable c.
Parameters:
            n = non-negative integer
            a, b = modules
Output values:
            c = module
A presentation of the module
Ext^n(A,B) is put into the
variable c, where A and B are presented by a and b.
We compute Ext as the homology
of the complex Hom(F*A,B), where F*A is a resolution of A.
If n=0, then Hom is used instead.
\end{verbatim}

\section{\tt ext(-,R)}

\begin{verbatim}
Usage:
    <ext(-,R) n a c
A presentation of the module
Ext^n(a,R) is put into the
variable c, where A is presented by a and R
is the ring over which a is defined.
Parameters:
            n = non-negative integer
            a = module
Output values:
            c = Ext^n(a,R)
We will compute Ext(A,R) as the homology of
               g'             f'
Hom(F(n-1)A,R) --> Hom(FnA,R) --> Hom(F(n+1)A,R)
where
            f       g
    F(n+1)A --> Fna --> F(n-1)A
is a piece of the resolution of A.
\end{verbatim}

\section{\tt extend\_ring}

\begin{verbatim}
Usage:
    <extend_ring J x S
Computes an approximation S to the smallest
subring S' of the total quotient ring of R.
the base ring of J, having
depth J S' >= 2.  In certain cases this is
    \sum_n  H^0( O_X (n) ),
where X is the projective variety defined by the
base ring of j --- see below.
Parameters:
    J = ideal in the ambient ring with respect
                    to which the 0 th local cohom is being
                    computed.
            x = the name of the new variables to use
                    in defining S; MUST NOT CONFLICT WITH
                    THE NAMES OF VARIABLES IN THE BASE RING
                    OF J.
Output values:
S = R[ x[1], x[2], ... ]/K,
where R is the base ring of J and K is an ideal.
The base ring R of J may be a quotient ring.
The natural map f from R to S may be found by using
            <imap f J S
            ;
The ring generated over R by the fractional
ideal Hom(J,R) is computed, under the
assumption that the first generator of
J given is a nonzerodivisor on R
(use NZD to check this.)  S is set
equal to this new ring. S is created for
this purpose, using variables named
x[1]..x[n], where n is the number of
variables in R + the number of generators
computed for Hom(J,R).
If J is primary to the maximal ideal,
then S is a subring of
\sum H^0( O_X (m) ),
where X is the projective variety corresponding
to R -- the part annihilated by J mod R.
If in addition J annihilates
the first local cohomology
of R, and in particular if R (nvars R)-1
+ the degrees of the generators of J
are all >= the largest degree
occurring in the resolution
of R at the (nvars R)-1 th step, then
Hom(J, R) is the whole of this ring.
\end{verbatim}

\section{\tt from\_bigraded}

\begin{verbatim}
Usage:
    <from_bigraded r s m n segre
    If m is a bigraded module over Pr x Ps then n is set to
the singly graded module over P^{rs+r+s} which
represents the same sheaf as m, via the segre embedding.
            It is assumed that the current ring has at least
rs+r+s+1 variables, and the first rs+r+s+1 of these are
used.
Parameters:
  r,s = positive integers
  m = bigraded module over a polynomial ring in
      two sets of variables: the first r+1 and the next
      s+1.  m must be generated by forms of bidgree d,d
      for various d (that is, m must be a diagonal module.)
Output values:
  n = module over the current ring.
  segre = the segre map used
If R = k[zij] is the current ring, and S = k[ xi , yj ] is the
bihomogeneous base ring of m, then the desired module is the
R-submodule of m generated by the given S-generators, via the
segre map sending zij to xi yj.

If m is not generated by "diagonal" elements (bidegrees equal),
but, say by elements of bidegree d,e, then the result will
correspond to the module m, regraded -- that is, twisted by a line
bundel 0(d,e).
\end{verbatim}

\section{\tt from\_div\_powers}

\begin{verbatim}
Usage:
    <from_div_powers1 f g
Write a polynomial f in the divided power algebra in terms of
ordinary powers.
Parameters:
  f = 1x1 matrix.
Output values:
  g = result 1x1 matrix.
The monomials of f are to be interpreted as monomials in the divided
powers.  Thus if f = x2+y3z2 then f is to be interpreted
as x^(2) + y^(3) z^(2), and g = (1/2)x2+(1/12)y3z2.
\end{verbatim}

\section{\tt generic\_mat}

\begin{verbatim}
Usage:
    <generic_mat var numrows numcols A
Create a generic matrix, whose (1,1) entry is "var".
Parameters:
 var = either a ring variable or the integer i to specify the i+1 st
       variable.
 numrows, numcols = size of the result generic matrix.
Output values:
 A   = a generic matrix of the given size, defined over the current ring.
       The row degrees of A are set to 0.
Caveat:
    If the current ring has too few variables, then the matrix is padded
with zeros.
\end{verbatim}

\section{\tt getvars}

\begin{verbatim}
Usage:
    <getvars result
Creates a 1xn matrix containing the variables of the current ring
in order.
\end{verbatim}

\section{\tt hom}

\begin{verbatim}
Usage:
    <hom a b c
The module Hom(a,b) is put into the
variable c.
Parameters:
            a,b = modules
Output values:
            c = Hom(a,b)
We will compute Hom as the kernel of
the map
               f = Hom(a,B)
            Hom(A0,B)  ------------>  Hom(A1,B), where
where b is a presentation of B and
           a
                    A1 --> A0
is a.
    The script returns a standard basis
\end{verbatim}

\section{\tt hom\_and\_map}

\begin{verbatim}
Usage:
    <hom_and_map a b c ff
The module Hom(a,b) is put into the
variable c. ff is set to the map inducing
the natural map Hom(A,b) --> Hom(A0,b),
where
                    a
    A1 --> A0 --> A --> 0
s the given presentation.
Parameters:
            a,b = modules
Output values:
            c = Hom(a,b)
This script is used in the script
double_dual1, where the map
A --> Hom(Hom(A,B),B) is computed.
We will compute Hom as the kernel of
the map
               f = Hom(a,B)
            Hom(A0,B)  ------------>  Hom(A1,B), where
where b is a presentation of B and
        a
            A1 --> A0
is a.
\end{verbatim}

\section{\tt hom\_is\_0}

\begin{verbatim}
Usage:
    <hom_is_0 a b
The output is the null matrix
iff Hom is 0.  Useful for
checking whether an element is a
nonzerodivisor (but the script NZD does it a different way.)
Parameters:
            a,b modules
This version of the script hom is optimized for testing
hom for 0.
Modulo is used in place of the
call to <kernel in the script Hom, and reduce is used
to make the test.  For further description, see hom.
\end{verbatim}

\section{\tt homology}

\begin{verbatim}
Usage:
    <homology b c f g h
(brief description)
Parameters:
            b,c,f,g = modules
Output values:
            h = module
If b,c are maps presenting modules B,C,
and f,g are maps inducing f: A->B and g:B->C,
(for some module A)
then a presentation of the homology is computed
and assigned to h.
\end{verbatim}

\section{\tt ideal}

\begin{verbatim}
Usage:
    <ideal j f1 f2 ... fn
Creates an ideal j over the current ring with generators f1, ..., fn.
Parameters:
  f1, ..., fn = polynomial expressions in the current ring
Output values:
  j = result 1xn matrix with entries f1, ..., fn.
Caveats:
\end{verbatim}

\section{\tt idencoldegs}

\begin{verbatim}
Usage:
    <idencoldegs m I
Sets I equal to an identity matrix
whose size is the number of cols of m and
whose row and column degrees are
equal to the column degrees of m.
Parameters:
            m = matrix
Output values:
    I = identity matrix such that
the composition mI makes sense
\end{verbatim}

\section{\tt idenrowdegs}

\begin{verbatim}
Usage:
    <idenrowdegs m result
Sets result equal to an identity matrix
whose size is the number of rows of m and
whose row and column degrees are
equal to the row degrees of m.
Parameters:
            m = matrix
Output values:
    I = identity matrix such that
the composition Im makes sense
\end{verbatim}

\section{\tt inhomog\_std}

\begin{verbatim}
Usage:
    <inhomog_std I J
Compute a standard basis J of the inhomogeneous submodule I.
Parameters:
  I = axb (inhomogeneous) matrix
Output values:
  J = matrix with a rows, together with a (minimal) standard basis
The method we use is to homogenize the columns of J with a new
variable which is least in the monomial order,
compute a standard basis in this case, and then dehomogenize.
The command "stdpart" is used to find a minimal subset of this 
standard basis.
Caveats:
The standard basis J is minimal, but not usually auto-reduced.
\end{verbatim}

\section{\tt interchange}

\begin{verbatim}
Usage:
    <interchange a b c1 c2
sets c1 and c2 equal to the invertible matrices such that
c2(a0b)c1 = b0a,
where we have written a0b for the tensor
product of the matrices a and b.
Parameters:
            a,b = matrices
Output values:
            c1,c2 = invertible matrices
We first form permutation matrices corresponding to the ci,
using <interchange_permutation, then
set their degrees to match a0b.
\end{verbatim}

\section{\tt interchange\_permutation}

\begin{verbatim}
Usage:
    <interchange_permutation a b c
sets c equal to the
permutation matrix of the permutation taking the set
A x B (where a,b are the cardinalities of A,B) in lex order to the
same set in the order that corresponds to the lex order
on B x A
Parameters:
            a,b = positive integers, the size of the sets A,B
Output values:
            an invertible ab x ab matrix
It might be more efficient to use the contract command
than the lift command as is done here
\end{verbatim}

\section{\tt inverse}

\begin{verbatim}
Usage:
    <inverse u answer
This file computes the inverse of a scalar
matrix u by means of the lift command.
Parameters:
            u = invertible scalar matrix
Output values:
            answer = inverse of u
\end{verbatim}

\section{\tt j\_from\_lambda}

\begin{verbatim}
Usage:
    <j_from_lambda lambda j
computes j = 2^8 (lambda^2-lambda+1)^3 / lambda^2 (lambda-1)^2
Parameters:
            lambda = a number (from the base field)
Output values:
            j = 1x1 matrix containing a number.
This is the function invariant under lambda -->
            lambda, 1/lambda, 1-lambda, 1/(1-lambda)
    lambda/(lambda-1) , (lambda-1)/lambda.
\end{verbatim}

\section{\tt j\_invariant}

\begin{verbatim}
Usage:
    <j_invariant f j
computes the j-invariant of a quartic form f in 4 variables
(that is, the j invariant of its 4 roots.)
Parameters:
    f = 1x1 matrix containing a cubic form in 3 variables
Output values:
            j = 1x2 matrix representing the point of P1 which is
the j-invariant of f.
Uses the equations of the divisors of forms of j-invariant 0 and 1728
\end{verbatim}

\section{\tt kernel}

\begin{verbatim}
Usage:
    <kernel f0 a b c
Given f0, a, b making a commutative diagram
(where the vertical arrows go down):
   C1 --> A1 --> B1
   |      |      |
 c |     a|      | b
   |      |  f0  |
   C0 --> A0 --> B0
   |      |      |
   |      |  f   |
ker f --> A  --> B
we compute a presentation c for the kernel of f
Parameters:
            f0,a,b = matrices
Output values:
            c = matrix
We first compute the relations on the generators
of the image of f0 modulo the image of b,
then a presentation of the kernel is obtained
by computing the relations on this
modulo the image of the map presenting a.
User kernel_and_map to compute the map from the
kernel to A at the same time.
\end{verbatim}

\section{\tt kernel\_and\_map}

\begin{verbatim}
Usage:
    <kernel_and_map f0 a b c g
Given f0, a, b making a commutative diagram
(where the vertical arrows go down):
   C1 --> A1 --> B1
   |      |      |
 c |     a|      | b
   |  g   |  f0  |
   C0 --> A0 --> B0
   |      |      |
   |      |  f   |
ker f --> A  --> B
we compute a presentation c for the kernel of f and
the comparison map g.
Parameters:
            f0,a,b = matrices
Output values:
            c,g = matrices
We first compute the relations on the generators
of the image of f0 modulo the image of b,
then a presentation of the kernel is obtained
by computing the relations on this
modulo the image of the map presenting a.
\end{verbatim}

\section{\tt kosz\_hom1}

\begin{verbatim}
Usage:
    <kosz_hom1 i m
The i-th koszul homology group of "m" is computed up
to degree 0, and displayed.
Thus the answer corresponds to the linear part of
the resolution at step k.
Parameters:
    i = integer >0
    m = module
Displayed value:
    the dimension of the ith koszul homology in degrees <= i
      (if m is generated in degrees >=0, then there is nothing
       of degree <0)
Setting i = 1 gives the vectorspace
of linear relations, etc.
The answer doesn't mean much unless the module is generated 
in degree >=0.
\end{verbatim}

\section{\tt kosz\_hom2}

\begin{verbatim}
Usage:
    <kosz_hom2 i J
The dimension of the degree i+1 part of the
ith Koszul homology group of R/J is displayed.
This corresponds to the 2-linear part of the resolution
at step i, that is, to
    Tor_i (R/J, k)_{i+1}
where R is the ambient polynomial ring and k is the ground
field.
Parameters:
            i = integer >0
    J = ideal CONTAINING NO LINEAR FORMS
Displayed value:
            the dimension of the ith koszul homology in degrees <= I+1
            (if m is generated in degrees >=0, then there is nothing
            of degree <0 . )
This corresponds to the 2-linear part of the resolution
at step i, that is, to
    Tor_i (R/J, k)_{i+1}
where R is the ambient polynomial ring and k is the ground
field. Thus:
             Setting step = 1 gives the number of deg 2 generators of
of the ideal, step = 2 gives the linear relations
on these, etc.
Caveats: J must contain no linear forms for the answer to
be meaningful.  Though this script beats res on the
square of the maximal ideal in many variables if i is large,
res is usually faster!
\end{verbatim}

\section{\tt l\_dual0}

\begin{verbatim}
Usage:
    <l_dual0 d J f
Given an integer d, compute
  J = (x1^d, ..., xn^d), and
  f = x1^(d-1).x2^(d-1)...xn^(d-1)
where the variables in the current ring are x1, ..., xn.
Parameters:
  d = an integer expression.
Output values:
  J = a 1xn matrix 
  f = a 1x1 matrix.
This script is used in "<l_from_dual" and "<l_to_dual".  The current
ring may be a quotient ring.
\end{verbatim}

\section{\tt l\_from\_dual}

\begin{verbatim}
Usage:
    <l_from_dual I' I
Compute the ideal I which is dual to the inverse system I'.
I' is generated by the dual polynomials of the 1xn matrix I'.
Parameters:
   I' = 1xn matrix, over a base ring S.
Output values:
   I  = 1xm matrix, over the same base ring S.

Let R be the localization of S at the homogeneous maximal ideal.
Let E be the R-module generated by {1/x^A}, for all monomials x^A, with
R action defined by x^A.(1/x^B) = 0 (if A-B has a positive component)
                                  1/x^(B-A) otherwise.
E is the injective envelope of the base field k in R.  It is not
finitely generated.  
Given an ideal I of R, its inverse system I' is defined to be
   Hom_R(R/I, E)
which is naturally identified as a submodule of E.
If R/I is Artinian, then I' is finitely generated.  If
I' is finitely generated, then R/I is Artinian.
Similarly, given a submodule I' of E, define an ideal I of R by
   I = {g in R : g.h = 0, for all h in I'} = Ann I'
Caveats:  The base ring S should not be a quotient ring.
\end{verbatim}

\section{\tt l\_homog0}

\begin{verbatim}
Usage:
    <l_homog0 I v J
Homogenize the columns of the matrix "I" using the new variable "v",
producing a matrix "J" over a new ring.  The monomial order for
this new ring is "elimination w.r.t. the variable v", which is
useful for many operations over local rings.
Parameters:
  I = mxn matrix over a ring R
  v = a variable name not occuring in R, such as t[-100].
Output values:
  J = mxn matrix over the ring R[v], whose columns are now homogenious.

This script is used by those scripts which compute over a local ring.
Let R_m be the localization of R at the homogeneous maximal ideal.
The lead terms of a polynomial of R_m are the terms of LOWEST degree.
The elimination order above has the property that the lead term 
of the homogenization of a polynomial f corresponds to the term of lowest
total degree.
Caveats:  the variable v must be distinct from the variables of the
ring R.
\end{verbatim}

\section{\tt l\_minimal}

\begin{verbatim}
Usage:
    <l_minimal I J
Find a minimal generating set J for the submodule I over localization R
at the homogeneous maximal ideal of the base ring of I.
Parameters:
 I = mxn matrix, whose columns are not necessarily homogeneous.
Output values:
 J = mxr matrix, whose columns minimally generate the submodule I over R.

This script uses l_minimal0 to do most of the work.
Caveats:  (1)The resulting minimal generators may not be the simnplest
possible.  For example, if I = (x2+x3), then over R, I = (x2).  This
script will not find such a representation.  Nevertheless, this is an
extremely useful script.
(2) The base ring of I must not include the variable "t[-100]".
\end{verbatim}

\section{\tt l\_minimal0}

\begin{verbatim}
Usage:
    <l_minimal0 I J
Find a minimal geneating set, J1,  for a submodule I1 over the
localization R of a polynomial ring at the origin.
I is a homogeneous submodule over a ring R[t], and I1 is obtained 
from I by setting "t" to one.  J1 is obtained similarly from J.
Parameters:
 I = mxn matrix over a ring whose first variable is the homogenizing
variable "t" (it can, of course, be named anything).
Output values:
 J = matrix with m rows, s.t. after setting "t" to one, the columns
 minimally generate the submodule I1 as above.

J is computed by finding the relations between I, and m I.  It is
possible that using as few generators for I as possible initially
will save alot of computation.
Caveats: This version requires I to be homogeneous.  Use l_minimal
if I has not yet been homogenized.
\end{verbatim}

\section{\tt l\_tangentcone}

\begin{verbatim}
Usage:
    <l_tangentcone I J
Compute the tangent cone, or the associated graded algebra, 
of a ring R/I, where R is the localization of a polynomial ring S at the
origin (ie. the localization at the homogeneous maximal ideal).
Parameters:
 I = 1xn matrix over a polynomial ring S.
Output values:
 J = a standard basis for the ideal defining the tangent cone.
     J is a 1xr matrix whose entries are homogeneous.
By definition, S/J = R/m + m/m^2 + m^2/m^3 + ..., 
where "m" is the homogeneous maximal ideal of R or S.
J is computed by homogenizing w.r.t. a new variable, say "t", 
and computing a standard basis of I using the monomial order which
eliminates "t", refined by graded reverse lexicographic order.

After dehomogenizing each element of this standard basis, a standard
The leading form of lowest degree of each element of this standard
basis, after setting "t" to one, forms a standard basis for the
ideal J.
This standard basis J can be used to determine various information
about the ring R/I:
1. the codimension of I:
<l_tangentcone I J
codim J
2. the multiplicity of R/I:
<l_tangentcone I J
degree J
3. ideal of initial monomials:
<l_tangentcone I J
in J in'I
\end{verbatim}

\section{\tt l\_to\_dual}

\begin{verbatim}
Usage:
    <l_to_dual I d I'
Compute the dual socle of a zero dimensional ideal I over the localization
of the base ring of I at the homogeneous maximal ideal.
Parameters:
  I = 1xn matrix of (inhomogeneous) polynomials
  d = integer such that xi^d is in I, for each variable xi.
Output values:
  I' = 1xr matrix whose entries generate the inverse system (dual socle)
       of I.
See the script "l_from_dual" for definitions and notation.
The inverse system is defined to be
   I' = Hom_R(R/I, E).
Let A = R/(x1^d, ..., xn^d), where x1, ..., xn are the variables of R.
Then I' = Hom_A(A/I, E) = Hom_A(A/I, E1),
where  E1 is the A-submodule of E generated by 1/(x1^(d-1)...xn^(d-1)),
which is isomorphic to A.
We compute the inverse system by first computing 
    Hom_A(A/I, A) = Ann_A(A/I),
and then mapping the answer back into E, by "contracting" with the 
element 1/(x1^(d-1)...xn^(d-1)).
Caveats:  The integer d must be correctly given, otherwise one
may get only a "part" of the inverse system. On the other hand, this
computes a filtration (by "d") of the inverse system, for any ideal I,
not just zero dimensional ideals.
\end{verbatim}

\section{\tt line\_bundle\_image}

\begin{verbatim}
Usage:
    <line_bundle_image m y j
Find the equations, "j", of the image to projective space defined by
the line bundle which is the sheafification of the module "m",
on the projective scheme X = Supp(m).  The variables of this 
new projective space are named y[0], ..., y[r].
Parameters:
   m = a matrix whose sheafification is a line bundle on X.
   y = a letter.  The variables in the base ring of the result are
       y[0], ..., y[r], for some r.
Output values:
   j = the ideal in y[0], ..., y[r] defining the image to P^r
       of the map corresponding to the elements of "m" of degree zero.
See the forthcoming paper by M. Brundu and M. Stillman for a more
detailed description and proof of this method.
Caveats:  If the module "m" is not reflexive (or "S2"), then the 
elements of degree zero in m might not generate the entire vector space
of global sections of the line bundle.  This script will compute the
image using exactly these section.  You might wish to first use
"double_dual" on the module "m".
\end{verbatim}

\section{\tt minpres}

\begin{verbatim}
Usage:
    <minpres j varlist j' f
Find a minimal presentation k[varlist]/j' for a given ring R/j,
and a map f: R --> k[varlist] inducing an isomorphism
   R/j ----> k[varlist]/j'
Parameters:
            j = ideal, possibly containing some minimal forms
            varlist = a variable list suitable for the ring command
Output values:
            j' = an ideal in k[varlist]
            f  = an ideal of linear forms and zeros in k[varlist],
                    representing the projection map from R.
k[varlist] is of course isomorphic, via f, to R/j1, where
j1 is the ideal generated by the linear forms in j.
Caveats:
    If not enough variables are given, the script puts in A[1]...A[100]
\end{verbatim}

\section{\tt monomial\_curve}

\begin{verbatim}
Usage:
    <monomial_curve a1 ... an  i
Sets i = the defining ideal of the projective
curve given parametrically on an affine piece by
t ---> ( t^a1, ... ,t^an ).
The ideal is defined in the current ring, which
MUST HAVE AT LEAST n+1 variables of equal degree at
the beginning of its list of variables.
Parameters:
    a1, ... ,an = nonnegative integers.
We must have n > 0.
Output values:
i = homogeneous ideal of the curve, defined over the
current ring.
The script forms the subring of the polynomial ring
in 2 variables t[1] and t[2] generated by
    (t[1]^m, ... , t[1]^(m-ai) t[2]^ai , ... ),
where m is the maximum of the ai,
and calls pushforward1 to compute the relations on it.
Note that the result will be a degenerate curve if
any of the ai are repeated OR IF ONE OF THE ai=0.
Caveats:
            The setdegs commands produce a spurious
"; warning: module isn't homogeneous" line, which
may be ignored.
\end{verbatim}

\section{\tt nbyn\_commuting}

\begin{verbatim}
Usage:
    <nbyn_commuting n j A B
Create a ring with a generic pair of  n by n commuting matrices, A, B.
Parameters:
 n = size of the matrices
Output values:
 A, B = two n by n matrices with indeterminate entries.
 j = ideal in a new ring containing the entries of the matrix AB-BA.
The new ring has variables a[i,j] and b[i,j].
\end{verbatim}

\section{\tt normal\_cone}

\begin{verbatim}
Usage:
	<normal_conecone J T L
Compute the graded ring T/L = R/J + J/J^2 + J^2/J^3 + ...,
where R is the base ring of J, and T is a polynomial ring over R
supplied by the user.  T/L corresponds to the normal cone of the scheme
defined by J.
Parameters:
 J = an ideal.
 T = a polynomial ring over R in variables whose weights are 
 proportional to the degrees of the generators of J.
Output values:
 L = the result ideal in the ring T.
The ring R may be a quotient ring.
The normal cone is computed by writing R[tJ] = T/L1.  Then the ideal
L = L1 + JT.
\end{verbatim}

\section{\tt normal\_sheaf}

\begin{verbatim}
Usage:
    <normal_sheaf i N [p]

If there are only 2 args, N = (i/i^2)^* , the normal sheaf, as a
module over the ambient ring.  If a third arg p is present, the
result (with std basis computed) is left in the variable p.3, over
the factor ring R/i, where R is the ambient ring and N is not set.
Parameters:
  i = ideal
Output values:
  N = (i/i^2)^* module

This script computes the normal sheaf by finding a presentation of
i, dualizing it, and resolving over the factor ring R/i, where R
is the ambient ring.
For some reason this method is much faster than the
more obvious N = hom (i.2,i), where i.2 is a presentation of i.
-- see the examples section for a comparison.
Caveats:
    A minimal presentation is produced over R/i, but the final
tensor command spoils this, so that the given information is not
minimal.
    Note that if one only wants to compute the dimension of 
H^j N(p) then its probably just as well to remain over the
quotient ring rather than mapping back.  In particular, to compute
just H^0 N(p) for the smallest p making this non-minimal, it is
enough to compute the second syzygy over the factor ring -- more
generally, we get the degrees of the generators of N by
            res @pres @pres 2
    betti @pres.2 ;the last column give the generators.
\end{verbatim}

\section{\tt nzd}

\begin{verbatim}
Usage:
    <nzd x m mbar
Test to see whether the linear form x is a nonzerodivisor
on m and set mbar = m/xm OVER THE CURRENT RING
( if the base ring of m has n variables, the first
n-1 variables of the current ring are used )
Parameters:
            x = 1x1 matrix containing a linear form
            m = module
Output values:
            mbar = m/xm as a module over the current ring
    The program also prints a message telling whether
            x is a nonzerodivisor on m.
The program uses the saturation method for finding whether
x is a nonzerodivisor -- generally cheapest, as it involves only
one standard basis computation, and that in reverse lex order.
The ideal that is printed is actually (0:x*)_m, the set of all
elements of m which are killed by a power of x.
\end{verbatim}

\section{\tt orbit\_equations}

\begin{verbatim}
Usage:
    <orbit_equations g J
computes the ideal J of equations defining the orbit of
a homogeneous polynomial g under the general linear group.
THE CURRENT RING MUST BE A RING WITH AT LEAST AS MANY VARIABLES AS
THE NUMBER OF COEFFICIENTS OF g.
Parameters:
    g = 1x1 matrix containing the polynomial (generally not over
the current ring.)
Output values:
            J = ideal in the current ring of polynomials
vanishing on the closure of the orbit of g.
The script applies a general change of variables to f and computes
the equations satisfied by the new coefficients.
Caveats:
    The polynomial must be homogeneous with all variables of
degree 1.  The script runs quite slowly in all but the smallest
cases.  Thus it is worth making sure that there are no extra
variables in either the ring of f or the current ring, the ring
representing the coefficients of the general form.
\end{verbatim}

\section{\tt permutation}

\begin{verbatim}
Usage:
    <permutation n x[i1]x[i2]..x[in] p
computes the permutation matrix which expresses
    i1..in
as a
permutation of
    1..n.
Parameters:
            n = number of letters permuted
            x[i1]x[i2]..x[in] = the permutation, as a list in order
                                    of the variables x[1]x[2]..x[n]
Output values:
            p = n x n matrix expressing the permutation.
\end{verbatim}

\section{\tt points}

\begin{verbatim}
Usage:
    <points pointsmat result
Computes the ideal of a set of points specified
in the matrix pointsmat.
Example of a pointsmat for 3 points in the line
    0 1 1
    1 1 0
Parameters:
            pointsmat = (r+1) x n matrix of scalars to
                                    specify n points in Pr.
Output values:
            result = ideal of the points
It is assumed that the ring over which pointsmat
is defined has at least r+1 variables.  If
the number of variables is >r+1, the first
r+1 are used.
\end{verbatim}

\section{\tt powers}

\begin{verbatim}
Usage:
    <powers I p Ip
Find the ideal whose generators are the pth powers
of the generators of I.
Parameters:
            I = ideal
            p = positive integer
Output values:
            Ip = ideal whose ith generator is the pth power
                            of the ith generator of I.
\end{verbatim}

\section{\tt project\_from\_product}

\begin{verbatim}
Usage:
    <project_from_product I n J
Finds the defining ideal J of the image of a subscheme
of   A^n x A^m   , minus any component supported on 0 x A^m,
projected to the second factor.  IT IS ASSUMED THAT THE
CURRENT RING has at least m variables, and its first m
variables are treated as the variables of A^m.  FURTHER,
IT IS ASSUMED THAT THE BASE RING OF I HAS AN ELIMINATION ORDER,
SO THAT ELIM WILL ELIMINATE THE FIRST n VARIABLES.
Parameters:
            I = ideal in a ring with n+m variables
            n = the number of variables to eliminate
Output values:
            J = ideal in the current ring.
The usual application is to compute the projection of a subscheme of
P^(n-1) x A^m or P^(n-1) x P(m-1), given by a bihomogeneous
ideal I, to the second factor.
The method is to saturate the given
ideal with respect to the ideal linear forms
in the first n variables, and then eliminate the
first n variables.
\end{verbatim}

\section{\tt prune}

\begin{verbatim}
Usage:
    <prune a b
finds a minimal presentation b for coker a.
Parameters:
            a = matrix
Output values:
            b = minimal matrix with the same cokernel
The script prune_and_map gives in addition
the map from the minimal presentation inducing
the identity on coker a.
\end{verbatim}

\section{\tt prune\_and\_map}

\begin{verbatim}
Usage:
    <prune_and_map a b f
finds a minimal presentation b for coker a and a map
    f: target b --> target a
inducing the identity on the cokernel.
Parameters:
            a = matrix
Output values:
            b = minimal matrix with the same cokernel
            f = matrix so that fb = ag for some g and f induces 1 on
                            1: coker b --> coker a.
\end{verbatim}

\section{\tt pts\_linear}

\begin{verbatim}
Usage:
    <pts_linear I M J
Find a linear subsystem of the polynomials I vanishing at the
points which are the rows of M.
Parameters:
I = ideal of polynomials all of the same degree.
M = m by n matrix with constant entries, such that the i th row 
represents a point in P^{n-1}, where n = number of variables of the 
base ring. 
Output values:
J = ideal consisting of the sub-vector space of I vanishing at every 
point in M.
\end{verbatim}

\section{\tt push\_forward}

\begin{verbatim}
Usage:
    <push_forward f M N
Computes the pushforward N = f_*(M) over the current ring S,
(M regarded as a module via f)
where f is a map from the current ring to the base ring of M.
Parameters:
  f = 1xn matrix over a ring R, whose entries have degrees
      proportional to the degrees of the current ring.
      M = R-module
Output values:
  N = module over the current ring, S.

If M is not finite via S, then the script outputs the codimension
of M/(vars of S)M (this is = dim R iff M is finite) and exits.
The script first checks to see whether M will be a
finitely generated module over the current ring via f.
Assuming that it is, the push forward f_* M is computed.  This is
done by first finding a presentation for M in terms of a set of
elements which generate M as an S-module over the ring R \tensor
S, and then calling push_forward1.
Caveats:
The script returns a set of relations of N that usually isn't
minimal; of course one can then do an std or nres or... to
find a minimal set of relations (the generators returned
are minimal generators of N.)
\end{verbatim}

\section{\tt push\_forward1}

\begin{verbatim}
Usage:
    <push_forward1 f M N
Given a map f from the current ring R to a ring S and a matrix
presenting a module M over S, the script forms a presentation
matrix for the R-submodule of M generated generators given
for M as an S-module.
    It is assumed that the first ncols f variables in R
have degrees proportional to the column degrees of f.
Parameters:
    f = 1xn matrix
    M = matrix over the same base ring as f
Output values:
    N = matrix over the current ring, whose rows correspond to those
of M.
This script performs a very basic set of operations.  It is used
by several others (see them for descriptions):
1. <subring      ;forms a subring given its generators
2. <push_forward ;writes a module as a module over another ring
3. <diagonal_submodule  
                 ;Finds the submodule generated by n,n forms in a
                 ;bigraded module
4. <from_bigraded
                 ;finds the singly graded module associated to a
                 ;bigraded module by the Segre map.
It can be used directly to compute the "pushforward" of
M as long as the given S-generators of M
generate it over the ring R.
Caveats:
1. If R and S do not have the same characteristic there may
be trouble!
2. If R is a quotient ring and the relations satisfied by R are
not satisfied by the elements of f (so that f is not really a map)
then the effect is to impose the additional relations satisfied by
the variables of R; that is, the effect is as if we first factored
out these relations from S and M.
3. The script does its main work over a new ring SR = S \tensor R
which has two blocks of variables, one from S and one from R.  If
the number of variables in one of these blocks is large and/or if
the degrees of the entries of f are large, there could be problems
with the "degree bound exceeded".  In that case one should use the
idea of the script but do the work "by hand", making many blocks
(and eliminating as many as necessary.)
4. The script returns a set of relations that usually isn't
minimal; of course one can then do an std or nres or... to
find a minimal set of relations (the generators returned
are minimal generators.)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
\end{verbatim}

\section{\tt random\_mat}

\begin{verbatim}
Usage:
    <random_mat a b i m
defines an  a x b  matrix m whose entries are random linear
combinations of the entries of the 1xn matrix i.  The rowdegs of m
are all = 0.
Parameters:
            a,b = integers >= 0 (a>0 )
            i = ideal.
Output values:
            m = a x b matrix
Caveat: Unless all the entries of i are of the same degree,
m will not be homogeneous.
he restriction a>0 is necessary till random can take
0s as parameters.
\end{verbatim}

\section{\tt representatives}

\begin{verbatim}
Usage:
<representatives a b result
computes a minimal set of representatives for the
image of a modulo the image of b;
That is, if a and b are regarded as maps to
a free module F, then result is a map to
F whose columns correspond to a minimal set
of generators of (im a)/(im b).
Parameters:
            a, b matrices with the same target (row space).
Output values:
            result = matrix with the same target as a,b.
This script  does not assumes that im a contains im b.
If one does  have this assumption, use
the script representatives1 instead.
\end{verbatim}

\section{\tt representatives1}

\begin{verbatim}
Usage:
<representatives a b result
computes a minimal set of representatives for the
image of a modulo the image of b,IF THE FIRST CONTAINS
THE SECOND.
That is, if a and b are regarded as maps to
a free module F, then result is a map to
F whose columns correspond to a minimal set
of generators of (im a)/(im b).
Parameters:
            a, b matrices with the same target (row space).
Output values:
            result = matrix with the same target as a,b.
This script assumes that im a contains im b.
If one does not have this assumption, use
the script representatives instead.
\end{verbatim}

\section{\tt ring}

\begin{verbatim}
Usage:
    <ring n varlist ringname
creates a ring with n variables, specified by varlist
( eg a-z  or  x[1,1]-x[2,3]st ).
Parameters:
  n >0  number of variables
  varlist = specification of variables acceptable to the ring command
Output values:
  A ring is created named ringname (which then refers to the ideal of
  variables.
    This creates a ring, with default characteristic, weight one
variables, and reverse lex. order,using the given variables.  If
too few variables given, variables A[1]A[2]... are used.
Caveats: 
     One might want the component first, but then when <ring
is used in conjunction with tensor_ring and elimination there
might be trouble.
\end{verbatim}

\section{\tt rmap}

\begin{verbatim}
Usage:
    <rmap vars values f
Create a ring map which sends the ith element of the ideal "vars" 
(which must be a variable) to the ith element of the ideal "values".  
All other variables are sent to zero.
Parameters:
  vars = 1xn matrix of (distinct) variables, with base ring R
  values = 1xn matrix of polynomials over the ring S
Output values:
  f = 1xm matrix over S, where m is the number of variables of R.
This script is useful since the variables don't have to appear "in
order".  It is also useful in scripts where you don't know the names
of variables in advance.
Caveats:  If an entry of "vars" is not a variable, the initial term is
used.  This initial term should be a variable.
\end{verbatim}

\section{\tt sat}

\begin{verbatim}
Usage:
    <sat I J K
This script computes K = (I:J^*)
    by the "rational normal" method.
Parameters:
            I = module (regarded as a submodule of a free module)
            J = ideal
Output values:
            K = (I:J^*), that is \union_N (I:J^N)
    The calls sat1 to compute (I:f^*), where f is a
a combination of the generators of J with coefficients
the powers of a new variable, suitably homogenized.
Caveats:
            One could do the same thing taking f to be a random linear
combination of the generators of J.  This might be faster in
some cases.  However, since one would have to bring all the
generators up to the same degree first, f might be a
very nonsparse polynomial.
;;;;;;;;;;;;;;;;;;;;;;;
\end{verbatim}

\section{\tt sat1}

\begin{verbatim}
Usage:
    <sat1 I f J
J = (I:f*) = {g \in F : gf^N \in I, for N >> 0}, where
I is a submodule of the free module F (typically I is an ideal).
Parameters:
 I = matrix representing a submodule of a free module F
 f = 1x1 matrix, an element of the base ring R of I.
Output values:
 J = matrix with the same number of rows as I.
This script uses the method of Bayer's thesis:
    First set up a ring S with one more variable than
the ring over which I, f are defined.  The new
variable comes last, and reverse lex is used,
so that after computing a standard basis, we can
conveniently "divide by the highest possible power of z."
We apply this division to the module (IS + (f-z)FS).
The ring R may be a quotient ring.
\end{verbatim}

\section{\tt subring}

\begin{verbatim}
Usage:
    <subring f K
defines an ideal K IN THE CURRENT RING R such that
    R/K = subring generated by f in the basering of f.
Parameters:
            f = 1xn matrix over some ring S.  The degrees of the
entries of f must be proportional to the degrees of the first
ncols f variables in the current ring.
Output values:
            K = ideal in the current ring
    This script calls pushforward1 to do set up the ring of the
correspondence defined by f,
R \tensor S modulo (xi-fi), where the xi are the
variables of R, and eliminate the variables of S
R and S may be quotient rings.
\end{verbatim}

\section{\tt symmetric\_algebra}

\begin{verbatim}
Usage:
    <symmalg m n old new
Compute the symmetric algebra, n, of the module presented by
the matrix m.  "old" and "new" are ideals containing the variables
coming from the ring, and the rows of m, respectively.
Parameters:
  m = axb matrix
Output values:
  n = symmetric algebra of m, an ideal over a new ring S.
  old = ideal of the variables of S corresponding to base ring of m.
  new = ideal of the variables of S corresponding to the rows of m.
The symmetric algebra is obtained from m by adding "a" variables to
the base ring of m, one for each row of the matrix m, and then multiplying
the matrix m by the vector of these new variables.
More specifically, the functor S*(-) (symmetric algebra) is right exact:
If R^b ---> R^a ---> M ---> 0 is exact, then
S*(R^b) ---> S*(R^a) ---> S*(M) ---> 0.
This gives us a presentation for S*M, as a factor ring of S*(R^a), which
is precisely the ring S above.  Notice that the equations defining
S*M all have degree one in the "new" variables.
\end{verbatim}

\section{\tt to\_div\_powers}

\begin{verbatim}
Usage:
    <to_div_powers f g
Write a polynomial f in the symmetric algebra in terms of divided powers.
Parameters:
  f = 1x1 matrix.
Output values:
  g = result 1x1 matrix.
The monomials of g are to be interpreted as monomials in the divided
powers.  Thus if f = x2+y3z2, then g = 2x2+12y3z2 is to be interpreted
as 2 x^(2) + 12 y^(3) z^(2).
\end{verbatim}

\section{\tt tor}

\begin{verbatim}
Usage:
    <tor n a b c
Computes c = Tor^n(a,b)
Parameters:
            n >= 0 an integer
            a,b = modules
Output values:
            c = module
Computes Tor as the homology of
the complex
Fn+1 \0 B -> Fn \0 B -> Fn-1 \0 B,
where \0 denotes tensor product, and B is the module
presented by b.  Checks to
see whether n = 0, and treats that case differently.
The module c produced usually is not given with a minimal set of
generators; call
            <prune c c
to get one.
\end{verbatim}

\section{\tt x\_to\_last}

\begin{verbatim}
Usage:
    <x_to_last x f g
If R is the base ring of x and S is the current ring, the
script returns inverse ring maps f: R -->S and g: S-->R.  The
effect of f is to make the linear forms in "x" act as the
last variables.  Thus after
    <x_to_last x s f g
            ev f m m1,
the last variable of S will act on m1 the way the linear
form which is the last entry of x acts on m.
Parameters:
  x = 1 x m matrix of linear forms over a ring with no more
      variables than the current ring.
Output values:
  f = ideal of the current ring with m linear forms, where m
      is the number of variables of the base ring of x
  g = ideal of the base ring of x, again with m variables.
typical usage: To saturate the ideal i (defined over r,
with last variable z and reverse lex order)
with respect to a linear form x we might do
    <x_to_last x f g
    ev f i i1
    std i1 i1
    sat i1 i1 z
    ev g i1 i1
Useful for checking whether x is a nonzerodivisor, using sat.
See NZD.
The idea is to find an nxn scalar invertible matrix G
whose last m columns consist of the coefficients of x in terms
of the variables of R.  The map g is defined by the ideal
(z1, ... zn)G, where the zi are the variables of R.
If we set,
F := G^(-1)
then the map f is defined by the ideal
(y_1,...,y_n)F, where the y_i are the variables of S.
\end{verbatim}

\section{\tt zeromat}

\begin{verbatim}
Usage:
    <zeromat numrows numcols result
Set the result equal to the numrows x numcols matrix consisting of
zeros over the current ring.
Parameters:
  numrows, numcols = integers
Output values:
  result = matrix over the current ring.
Can be used to compute matrices with either zero rows or zero columns.
\end{verbatim}
