-- -*- Mode: M2; mode: auto-fill; coding: utf-8; fill-column: 100 -*-
Key
"BeginningMacaulay2"
Headline
Mathematicians' Introduction to Macaulay2
Description
Text
We assume you've installed {\em Macaulay2} and can type
Code
EXAMPLE { PRE ///M2/// }
Text
on a command line to bring up the program. You should see something like:
Code
EXAMPLE {
PRE ///Macaulay2, version 1.7
with packages: ConwayPolynomials, Elimination, IntegralClosure, LLLBases,
PrimaryDecomposition, ReesAlgebra, TangentCone///}
Text
We suggest you do that now, so that you can experiment while you read
this tutorial!
Code
SUBSECTION "Arithmetic with integers, rings and ideals"
Text
You can immediately do arithmetic with integers:
Example
2+2
107*431
25!
binomial(5,4)
factor 32004
Text
Most {\em Macaulay2} applications involve polynomial rings over fields
and their quotient rings. Fields can be made in various ways:
Example
ZZ/101
QQ
GF 2^5
k = toField (QQ[i]/(i^2+1))
Text
After making {\tt k} we can compute in it:
Example
1/i
Text
Computation is often fastest and needs least
memory when performed over finite prime fields of the form
$\ZZ/p$.
Fortunately, when the characteristic $p$ is not too small,
qualitative questions often have similar answers over
$\ZZ/p$ and over $\QQ$, so we mostly use the former.
In {\em Macaulay2} the prime $p$
can range up to 32749.
We make a polynomial ring in 5 variables over $\ZZ/101$:
Example
kk=ZZ/101
S=kk[x_1..x_5]
Text
Here is another way:
Example
S=kk[a,b,c,d,e]
Text
One can do arithmetic on polynomials:
Example
(3*a^2+1)^5
Text
We make an ideal in $S$:
Example
I=ideal(a^3-b^3, a+b+c+d+e)
Text
Using this ideal, we can make a factor ring:
Example
R=S/I
Text
Another way to make an ideal, with more compact notation (familiar to anyone who used the
classic Macaulay) is:
Example
use S
I=ideal"3(a+b)3, 4c5"
Text
Note the command ``{\tt use S}'', which specifies
that we want to work with the generators of the polynomial ring S again;
otherwise the variables {\tt a}, {\tt b}, and {\tt c}
would still have had values in $R$ instead of in $S$.
Algebraic operations on ideals are available:
Example
I^2
I*I
I+ideal"a2"
Text
In case you forget any of these things, @TO help@ is available! The most
useful way to get it is often to type something like:
Code
EXAMPLE { PRE ///viewHelp ideal/// }
Text
Then a browser window will pop up that contains documentation about the function @ TO
ideal @ that we've been using; links on that page allow one to explore all of the {\em Macaulay2} documentation.
On the other hand, we might have wanted information about the @TO class@ of all ideals.
Not too surprisingly, this class is called @TO Ideal@. We could get information about
what functions create or use ideals by typing:
Code
EXAMPLE { PRE ///viewHelp Ideal/// }
Text
To see the names of classes, you can begin by looking at the output
of commands; the second line output (the one introduced by a colon) often contains the name of the
class of the result.
Here are some basic operations on matrices:
Example
M= matrix{{a,b,c},{b,c,d},{c,d,e}}
M^2
determinant M
trace M
M-transpose M
Text
The function @TO entries@ gives the entries of a matrix:
Example
entries M
Text
The result is a list of lists, one for each row of the matrix $M$.
The function @TO flatten@ can be used to merge the
lists into a single list:
Example
flatten entries M
Text
If you want a particular entry, say the one in the upper left corner,
you can use the underscore operator @TO2 {(symbol _,Matrix,Sequence),"_"}@:
Example
M_(0,0)
Text
Here, as everywhere in {\em Macaulay2}, all indexing starts with 0.
For example:
Example
I_0
Text
is the first generator of I. You can list all the generators with:
Example
I_*
Text
A {\em module} can be defined as a cokernel, kernel, image, or even as a subquotient:
Example
coker M
image M
kernel matrix"a,b,0;0,a,b"
N = matrix{{a,b},{b,c},{c,d}}
(image M)/(image N)
subquotient(M,N)
Text
Note that the matrix $N$ above was defined with an
alternate syntax, parallel to the alternate syntax for @TO ideal@.
Before going on, the reader might want to explore a bit. A good place to
start is the top of the documentation tree, which can be reached, for
example, by typing:
Code
EXAMPLE { PRE "viewHelp Macaulay2Doc" }
Text
Code
SUBSECTION "Properties of ideals and modules",
Text
To compute the Gröbner basis of an ideal
$(x^2y,xy^2+x^3)$ in the polynomial ring in
four variables we proceed as follows.
First we make our favorite field:
Example
kk = ZZ/32003
Text
Then the polynomial ring:
Example
R = kk[x,y,z,w]
Text
And then the ideal:
Example
I = ideal(x^2*y,x*y^2+x^3)
Text
Now the punch line. We compute the Gröbner basis with the @ TO groebnerBasis @ function:
Example
J = groebnerBasis I
Text
Gr\"obner bases are always computed with respect to a particular
monomial order on the ring. In fact, the ring we defined above has
a default monomial order, the graded reverse lex order. For many
other possibilities, see @ TO MonomialOrder @, or type:
Code
EXAMPLE { PRE "viewHelp MonomialOrder" }
Text
The analogue of factorization in the theory of ideals
is primary decomposition.
For example, we can begin by intersecting three ideals:
Example
I= intersect (ideal"x2,y3", ideal"y2,z3", (ideal"x,y,z")^4)
Text
We can almost undo this operation by computing
a primary decomposition:
Example
primaryDecomposition I
Text
Inspecting the output, we see that the first two ideals
are the same as the first two ideals we intersected, but the
third one differs from the corresponding input ideal.
This is because only the primary components corresponding
to minimal primes (here, the first two) are unique. All three of the input ideals
are primary, so they constitute a primary decomposition of $I$
different from the one provided by {\em Macaulay2} on the output line.
For larger examples, primary decomposition is computationally challenging!
Sometimes it is easier to compute just the minimal primes. To do
this we can use @ TO decompose @:
Example
decompose I
Text
Using Gröbner bases we can compute
codimensions, dimensions,
degrees, Hilbert
functions, and Hilbert polynomials.
This will be more fun if we work with a
meaningful example. We will use
the ideal defining the smooth
rational quartic curve in $\PP^3$ given
parametrically (in an affine representation)
by $$t \mapsto{} (t,t^3,t^4).$$
(The reader more interested in algebra than geometry
may simply treat the ideal given below as a
gift from the gods.)
First we make the
polynomial ring in 4 variables, to serve as the
homogeneous coordinate ring of $\PP^3$:
Example
R = kk[a..d]
Text
We introduce the ring map $\phi: R \to kk[s,t]$ defined by
$(a,b,c,d) \mapsto{} (s^4, s^3 t, s t^3, t^4)$:
Example
phi = map(kk[s,t],R,{s^4, s^3*t, s*t^3, t^4})
Text
Here the syntax of the function @ TO2 {(map,Ring,Ring,List),"map"} @ has the target ring first and the source ring second:
maps in {\em Macaulay2} generally go from right to left!
The last input to the command is a
list of the elements to which to send the variables of the source ring.
The ideal we want is the kernel of this map:
Example
I = ker phi
Text
Shortcut notation for this construction is provided by the function @ TO
monomialCurveIdeal @:
Example
I = monomialCurveIdeal(R,{1,3,4})
Text
We can compute the @ TO2 {(dim,Ideal),"dimension"}@, @ TO2{(codim,Ideal), "codimension"}@ (also called the
height) and @ TO2{(degree,Ideal),"degree"} @ of this ideal:
Example
dim I
codim I
degree I
Text
The Hilbert polynomial is obtained with the function @ TO hilbertPolynomial@:
Example
hilbertPolynomial(R/I)
Text
The output above may not be what the user expected:
the term ${\mathbf P}_m$ represents the Hilbert polynomial of
projective $m$-space. Thus the output tells
us that the Hilbert polynomial of $M$ is
$i \mapsto{} -3*1+4*(i+1) = 4i + 1$. Thus the degree
is four, the dimension of the projective variety
that is the support of $M$ is 1 (and so the affine
dimension is 2), and the (arithmetic) genus is 0 (obtained as 1 minus the
constant term of the polynomial.)
The more usual expression for the Hilbert polynomial can
be obtained as follows:
Example
hilbertPolynomial(R/I, Projective => false)
Text
The construction {\tt Projective => false} is our first example of
an {\em option} to a function: we specified that the option
{\tt Projective} was to have the value {\tt false}.
The form we used first could also have been written this way:
Example
hilbertPolynomial(R/I, Projective => true)
Text
The Hilbert series of $M$ (the generating function
for the dimensions of the graded pieces of $M$) is
obtained with:
Example
hilbertSeries (R/I)
Text
This generating function is expressed
as a rational function with denominator equal to (1-T)^n, where
n is the number of variables in R.
Since R/I has dimension 2, it can also be written
with denominator (1-t)^2. To see it in this form, use @ TO reduceHilbert @:
Example
reduceHilbert hilbertSeries (R/I)
Text
It is possible to manipulate the numerator and denominator of this
expression. To learn how to do so, see @ TO hilbertSeries @ or type:
Code
EXAMPLE { PRE "viewHelp hilbertSeries" }
Text
A great deal of subtle information about a module is visible using
free resolutions. For an example, we begin
by turning $R/I$ into a module. Here the code @ TT "R^1" @ produces the free module of
rank 1 over $R$, and @ TO2 {(resolution,Module),"res"} @ computes a free resolution:
Example
M=R^1/I
Mres = res M
Text
To get more precise information about {\tt Mres},
we could compute its Betti table with @ TO2{(betti,GradedModule), "betti"} @:
Example
betti Mres
Text
The display is chosen for compactness. Each column of the
table corresponds
to a free module in the resolution. The column's heading
specifies the {\em homological degree} (the position of the free
module in the resolution).
The entry just below the homological degree
is the rank of the free module, also called the
{\em total betti
number}. The remaining entries in the column
tell us how many generators of each degree this free
module has: the number in the column labelled $j$ and in the row labelled $d$
tells how many generators of degree $j+d$ the $j$-th free module has.
Thus, in our case, the single
generator of the third (and last) free module in the
resolution has degree $3+2=5$.
Commonly computed homological invariants
such as @ TO2 { (pdim,Module), "projective dimension" } @ and @ TO2 {(regularity,Module),
"regularity"} @ are (also) available directly:
Example
pdim M
regularity M
Text
Code
SUBSECTION "Division With Remainder"
Text
A major application of Gröbner bases is
to give the normal form for an element modulo an
ideal, allowing one, for example, to decide whether
the element is in the ideal.
For example, we can decide which power of the trace
of a generic 3x3 matrix is expressible in terms of the entries of the
cube of the matrix with the following code:
Example
R = kk[a..i]
M = genericMatrix(R,a,3,3)
I = ideal M^3
Text
This gives the ideal of entries of the matrix. In the expression
``{\tt M = genericMatrix(R,a,3,3)}'' the arguments ``{\tt R,a,3,3}'' specify the
ring, the first variable to use, and the numbers of rows and columns
desired.
Example
Tr = trace M
for p from 1 to 10 do print (Tr^p % I)
Text
The expression ``@ TT "Tr^p % I"@'' computes the normal form for the p-th power
of the trace {\tt Tr} with respect to the Gröbner basis of I.
The expression ``@ TT "for p from 1 to 10 do" @'' specifies a
{\em for loop} that executes the following expression, ``@ TT "print (Tr^p % I)" @'',
with 10 consecutive values of {\tt p}. For more information on such loops see @ TO "for" @
or type:
Code
EXAMPLE { PRE ///viewHelp "for"/// }
Text
Here we have put quotes around ``for'' because
``for'' is a keyword in the {\em Macaulay2} language. (In general, it's always safe to use
quotes with viewHelp.)
We see from the output of these commands that the 6-th power
of the trace is NOT in the ideal of entries of the cube of M,
but the 7-th power is. We can compute the coefficients in the expression for it
using the division algorithm, denoted in this setting by @ TO2 {(symbol //, RingElement,
Matrix), "//"} @:
Example
Tr^7//(gens I)
Text
Code
SUBSECTION "Elimination Theory"
Text
Consider the problem of projecting the
``twisted cubic'', a curve in $\PP^3$ defined
by the three $2 \times{} 2$ minors of a certain
$2 \times{} 3$ matrix.
We already have the simplest tools for solving
such a problem.
We first clear the earlier meaning of {\tt x}
to allow it to be used as a subscripted variable:
Example
x = symbol x
Text
Since we are going to deal with a curve in $\PP^3$,
we begin with a polynomial ring in four variables:
Example
R = kk[x_0..x_3]
Text
The ideal of the twisted cubic curve is generated by the $2 \times{} 2$
minors of a ``catalecticant" or ``Hankel" matrix, conveniently
defined as follows:
Example
M = map(R^2, 3, (i,j)->x_(i+j))
I = minors(2,M)
Text
As projection center we
take the point with homogeneous coordinates $(1,0,0,-1)$,
which is defined by the ideal:
Example
pideal = ideal(x_0+x_3, x_1, x_2)
Text
The ideal J of the image of the curve under the projection from this point
is the kernel of the ring map $S=kk[u,v,w] \to R/I$
sending the variables
of S to the generators of {\tt pIdeal},
regarded as elements of $R/I$. This is the same as the more usual formulation:
$$J = I \cap{} kk[x_0+x_3, x_1, x_x]$$
To compute this we first substitute {\tt pIdeal} into $R/I$, and then form
the necessary ring map:
Example
Rbar = R/I
pideal = substitute(pideal, Rbar)
S = kk[u,v,w]
J=kernel map (Rbar, S, gens pideal)
Text
The ideal J defines a curve with one singular point.
We can compute the ideal of the singular locus with:
Example
K = ideal singularLocus(J)
Text
This doesn't look like the ideal of a reduced point! But
that's because it isn't yet saturated:
Example
saturate K
Text
We have just seen the @ TO saturate @ function in its most
common use: to saturate with respect to the maximal ideal.
but we can also find the saturation of any ideal with
respect to another:
Example
saturate (ideal"u3w,uv", ideal"u")
Text
We can also take the ``ideal quotient'' I:J of an ideal I with
respect to another, J
defined as the set of elements f such that
f*J is contained in I:
Example
ideal"u3w,uv":ideal"u"
Text
Code
SUBSECTION "Defining functions and loading packages"
Text
It is easy to define your own functions in {\em Macaulay2}, and this
can save a lot of typing. Functions are defined with the
symbol ->. For example, the famous {\em Collatz Conjecture}
(also called the ``hailstone problem'') asks
about the following procedure: given an integer $n$, divide it
by 2 if possible, or else multiply by 3 and add 1.
If we repeat this over and over,
does the process always reach 1? Here is a function that
performs the Hailstone procedure again and again,
producing a list of the intermediate results.
Example
Collatz = n ->
while n != 1 list if n%2 == 0 then n=n//2 else n=3*n+1
Text
For example:
Example
Collatz 27
Text
If you don't understand this code easily, see @ TO Function @ and @ TO "while" @, or try:
Code
EXAMPLE {
PRE "viewHelp Function",
PRE ///viewHelp "while"///
}
Text
In order to understand a process it is often useful to tabulate the
results of applying it many times. One feature of the Collatz process
is how many steps it takes to get to 1. We can tabulate this statistic
for the first 25 values of n with the function @ TO tally @, as follows:
Example
tally for n from 1 to 30 list length Collatz n
Text
A line of the form
Code
EXAMPLE {
PRE " 18 => 3"
}
Text
in the result means that a Collatz sequence of length 18
was seen 3 times.
To see the successive ``record-breakers'',
that is, the numbers with longer Collatz sequences than any
number before them, we might try:
Example
record = length Collatz 1
L = for n from 2 to 1000 list (
l := length Collatz n;
if l > record
then (record = l; (n,l))
else continue)
Text
If you want to see a list of just the successive records,
you can apply the
function @ TO last @ to each element of the list $L$.
A convenient way to do this is with this syntax:
Example
L/last
Text
Note that in
writing functions of more than one expression (usually
there's one expression per line), the expressions must be
separated by semicolons. For example in the ``for'' loop
above, the first expression was ``{\tt l = length Collatz n}''.
After the last expression of an input line or of a function body,
a semicolon suppresses output, useful when the output
would be large.
There are many packages of ready-made functions available for
your use, many written by other users (perhaps you'll contribute one
someday!) A list of ``installed'' packages can be found with:
Code
EXAMPLE { PRE ///viewHelp/// }
Text
For example, there is a package called @TO "EdgeIdeals::EdgeIdeals"@.
To load the package, use:
Example
loadPackage "EdgeIdeals"
Text
After loading it, you can view its documentation with
Code
EXAMPLE { PRE "viewHelp EdgeIdeals" }
Text
or you can call its functions,
such as @TO "EdgeIdeals::randomGraph"@ and @TO "EdgeIdeals::edgeIdeal"@:
Example
R = kk[vars(0..10)]
G=randomGraph (R,20)
K=edgeIdeal G
hilbertSeries K
betti res K
Text
When testing a conjecture one sometimes wants to run a
large number of randomly chosen
examples.
Here's some typical code that one might use to study
a random graph ideal. First we use ``{\tt for ... list ...}'' to construct a list {\tt L}
and suppress its printing by ending the line that creates
it with a ``;''. Each entry of {\tt L} is a triple consisting of the
codimension, degree, and Betti table of a random graph ideal
on 10 vertices having only 4 edges.
Example
R = ZZ/2[vars(0..10)]
L=for j from 1 to 100 list(
I = edgeIdeal randomGraph (R,5);
(codim I, degree I, betti res I));
Text
We can use @ TO tally @ to find out how many examples
were found with each combination of codimension and degree and Betti table.
Example
tally L
Text
We can determine how many distinct patterns were found:
Example
#tally L
Text
Code
SUBSECTION "Ext, Tor, and cohomology"
Text
{\em Macaulay2} can compute the homology of complexes;
for example, let's compute the homology of a
Koszul complex that is not a resolution:
$$ {\mathbf K}(x^2, x y^2):\ \ 0 \rightarrow{} S(-5) \rightarrow{} S(-2)\oplus S(-3) \rightarrow{} S \rightarrow 0 $$
The free module $S(-2) \oplus{} S(-3)$ can be defined with this
syntax:
Example
S^{-2,-3}
Text
Here is how we can define the maps in the Koszul complex:
Example
S = kk[x,y]
phi1 = map(S^1, S^{-2,-3}, matrix"x2,xy2")
phi2 = map(S^{-2,-3}, S^{-5}, matrix"xy2;-x2")
Text
Let's check that this is will really make a complex:
Example
phi1*phi2
Text
To get the homology we can, for example compute:
Example
(ker phi1)/(image phi2)
Text
We could also use the data type @TO ChainComplex@
and use a built-in facility to take homology (in our case $H_1$):
Example
FF = chainComplex(phi1,phi2)
FF.dd
homology FF
presentation (homology FF)_1
Text
Either way, the first homology is $((x^2):(xy^2)) / (x^2) \cong{} S/(x)$, in accord
with general theory.
There are other ways to construct Koszul complexes. One way is as the tensor product of
chain complexes of length 1:
Example
FF = chainComplex matrix {{x^2}} ** chainComplex matrix {{x*y^2}}
FF.dd
Text
Another way is by using the function @ TO koszul @, designed for that purpose:
Example
FF = koszul matrix {{x^2, x*y^2}}
FF.dd
Text
Since {\em Macaulay2} can compute resolutions and homology, it can
compute things such as $Ext$, $Tor$ and sheaf cohomology, as in the
following examples. The first uses Serre's formula to compute
the multiplicity with which a 2-plane meets the union
of two 2-planes in 4-space (this is the first case in which
the length of the intersection scheme is NOT the right answer.)
The notation ``{\tt M**N}'' denotes the tensor product of the modules $M$ and $N$.
We use the syntactical forms
``{\tt for j from 0 to 4 list ...}'' to list some results and
``{\tt sum(0..4, j -> ...)}'' to sum some results.
Example
S=kk[a,b,c,d]
IX = intersect(ideal(a,b), ideal(c,d))
IY = ideal(a-c, b-d)
degree ((S^1/IX) ** (S^1/IY))
for j from 0 to 4 list degree Tor_j(S^1/IX, S^1/IY)
sum(0..4, j-> (-1)^j * degree Tor_j(S^1/IX, S^1/IY))
Text
Similarly, we can compute Hom and Ext:
Example
Hom(IX, S^1/IX)
Ext^1(IX, S^1/IX)
Text
or the cohomology of the sheaf associated to a module.
Here is how to compute
the first cohomology of the structure
sheaf twisted by $-2$ of the curve $Proj(S/IX)$, which
in this case is the disjoint union of two
lines in $\PP^3$:
Example
HH^1 (sheaf (S^{-2}**(S^1/IX)))
-- Local Variables:
-- compile-command: "make -C /Users/de/src/M2/Macaulay2/packages PACKAGES=BeginningMacaulay2 RemakeAllDocumentation=true IgnoreExampleErrors=false"
-- End: