Macaulay User Manual

Maureen Stillman  Michael Stillman^{1}  Dave Bayer ^{2}

August 10, 1989

1partially supported by MSI and NSF 2Partially supported by the Alfred P. Sloan Foundation, and by ONR contract

N00014-87-K0214.

\begin{matrix}c \\ ◯ \end{matrix}1989 Maureen Stillman, Michael Stillman and David Bayer. All rights reserved.

This manual may be freely copied and given to others.

Contents

1 Introduction to Macaulay 3 1.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 Summary of New Features . . . . . . . . . . . . . . . . . . . . . . 4 1.3 Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.4 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Getting Started with Macaulay 6

2.1 Using Macaulay on Unix Systems . . . . . . . . . . . . . . . . . . 6 2.1.1 Starting up Macaulay . . . . . . . . . . . . . . . . . . . . 6 2.1.2 Command line editing . . . . . . . . . . . . . . . . . . . . 6 2.1.3 Controlling scrolling of the screen . . . . . . . . . . . . . . 6 2.1.4 Using Emacs, Suntools, or Xwindows . . . . . . . . . . . . 7

3 Input Syntax 8 3.1 How to Input a Command . . . . . . . . . . . . . . . . . . . . . . 8 3.2 Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.3 User Defined Variables (Identifiers) . . . . . . . . . . . . . . . . . 9

3.3.1 Indexed Identifiers . . . . . . . . . . . . . . . . . . . . . . 9 3.4 Naming polynomial ring variables (indeterminants) . . . . . . . . 10 3.5 Integer Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 10 3.6 Polynomial expressions . . . . . . . . . . . . . . . . . . . . . . . . 11 3.7 Integer lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 3.8 Variable lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

4 User Defined Variables 16 4.1 Types of Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 16 4.2 Commands to display and remove variables . . . . . . . . . . . . 16 4.3 Referencing variables . . . . . . . . . . . . . . . . . . . . . . . . . 17 4.4 Reusing Variable Names . . . . . . . . . . . . . . . . . . . . . . . 18 4.5 Integer Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 5 Rings 19

5.1 The “ring” command . . . . . . . . . . . . . . . . . . . . . . . . 19 5.2 Other ring commands . . . . . . . . . . . . . . . . . . . . . . . . 22 5.3 Quotient Rings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5.4 Monomial orders in Macaulay . . . . . . . . . . . . . . . . . . . . 25

5.4.1 Reverse lexicographic order . . . . . . . . . . . . . . . . . 26 5.4.2 Product and elimination orders . . . . . . . . . . . . . . . 26 5.4.3 Monomial orders for free modules . . . . . . . . . . . . . . 29 5.4.4 General monomial orders in Macaulay . . . . . . . . . . . 30

6 Matrices 33 6.1 Matrix creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 6.2 Displaying Matrices . . . . . . . . . . . . . . . . . . . . . . . . . 36 6.3 Operations on matrices . . . . . . . . . . . . . . . . . . . . . . . 38 6.4 Editing Commands . . . . . . . . . . . . . . . . . . . . . . . . . 48 6.5 Graded Matrices and Homogeniety . . . . . . . . . . . . . . . . . 50

7 Standard (Gröbner) Basis Computations 53 7.1 Standard basis and syzygy computations . . . . . . . . . . . . . . 54 7.2 Other computation commands . . . . . . . . . . . . . . . . . . . 57 7.3 Internal format of a computation . . . . . . . . . . . . . . . . . . 61 7.4 Fine control of standard basis computations . . . . . . . . . . . . 62

7.4.1 Interrupting computations . . . . . . . . . . . . . . . . . . 63 7.4.2 Feedback during computations . . . . . . . . . . . . . . . 63 7.4.3 Controlling computation . . . . . . . . . . . . . . . . . . . 63

8 Operations on standard bases 65 8.1 Elimination of variables . . . . . . . . . . . . . . . . . . . . . . . 66 8.2 Ideal or submodule membership . . . . . . . . . . . . . . . . . . . 69 8.3 Treating variables as constants . . . . . . . . . . . . . . . . . . . 71 8.4 Saturation of ideals or submodules . . . . . . . . . . . . . . . . . 76 8.5 Computing numerical information . . . . . . . . . . . . . . . . . 76 8.6 Displaying Information about Resolutions . . . . . . . . . . . . . 79

9 Ring maps 82 9.1 Introduction to ring maps . . . . . . . . . . . . . . . . . . . . . . 82 9.2 Commands for defining and using ring maps . . . . . . . . . . . . 83

10 System commands 88 10.1 Finding help about Macaulay . . . . . . . . . . . . . . . . . . . . 88 10.2 Recording a Macaulay session . . . . . . . . . . . . . . . . . . . . 90 10.3 Macaulay parameters . . . . . . . . . . . . . . . . . . . . . . . . . 91 10.4 Space Utilization . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 10.5 Interrupting Macaulay’s computations . . . . . . . . . . . . . . . 95

10.6 Redirection of input and output . . . . . . . . . . . . . . . . . . . 96

11 Command Files 97 11.1 Running scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 11.2 Creating scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 11.3 Tour mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 11.4 Passing parameters to scripts . . . . . . . . . . . . . . . . . . . . 99 11.5 Silence is sometimes golden . . . . . . . . . . . . . . . . . . . . . 100 11.6 If statements and jumps . . . . . . . . . . . . . . . . . . . . . . . 100 11.7 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

A Examples 102 A.1 The rational quartic in P3 . . . . . . . . . . . . . . . . . . . . . . 102 A.2 An elliptic curve on the Veronese in P^{5} . . . . . . . . . . . . . . 104 A.3 The tangent developable of a rational normal curve . . . . . . . . 106 A.4 Finding an inhomogeneous standard basis . . . . . . . . . . . . . 111 A.5 The ideal of the 3 by 3 commuting matrices . . . . . . . . . . . . 113 A.6 Linkage of curves in P^{3} . . . . . . . . . . . . . . . . . . . . . . . 115

B Macaulay under MPW 118 B.1 Controlling Macaulay from a window . . . . . . . . . . . . . . . . 119 B.2 Customizing the MPW environment . . . . . . . . . . . . . . . . 119 B.3 Some Peculiarities of Macaulay under MPW . . . . . . . . . . . . 120

C Scripts of Macaulay (by D. Eisenbud, M. Stillman 122 C.1 adj of cat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122 C.2 adjoin fractions . . . . . . . . . . . . . . . . . . . . . . . . . . 122 C.3 adjoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 C.4 annihilator1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 C.5 annihilator2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 C.6 binomial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124 C.7 block map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 C.8 blowup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125 C.9 blowup0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 C.10 cohomology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 C.11 cohomology1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 C.12 complement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 C.13 copyring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128 C.14 cotan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129 C.15 cotan bihom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 C.16 deg01 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 C.17 diagonal submodule . . . . . . . . . . . . . . . . . . . . . . . . . 131 C.18 double dual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 C.19 double dual1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 C.20 dual variety . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 C.21 ext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 C.22 ext(-,R) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 C.23 extend ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 C.24 from bigraded . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 C.25 from div powers . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 C.26 generic mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 C.27 getvars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 C.28 hom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 C.29 hom and map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 C.30 hom is 0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 C.31 homology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 C.32 ideal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 C.33 idencoldegs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 C.34 idenrowdegs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 C.35 inhomog std . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 C.36 interchange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141 C.37 interchange permutation . . . . . . . . . . . . . . . . . . . . . 141 C.38 inverse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 C.39 j from lambda . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 C.40 j invariant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 C.41 kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 C.42 kernel and map . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 C.43 kosz hom1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 C.44 kosz hom2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 C.45 l dual0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 C.46 l from dual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 C.47 l homog0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 C.48 l minimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 C.49 l minimal0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 C.50 l tangentcone . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 C.51 l to dual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 C.52 line bundle image . . . . . . . . . . . . . . . . . . . . . . . . . . 149 C.53 minpres . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149 C.54 monomial curve . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 C.55 nbyn commuting . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 C.56 normal cone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 C.57 normal sheaf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 C.58 nzd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 C.59 orbit equations . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 C.60 permutation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 C.61 points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153 C.62 powers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154 C.63 project from product . . . . . . . . . . . . . . . . . . . . . . . 154 C.64 prune . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 C.65 prune and map . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 C.66 pts linear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 C.67 push forward . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 C.68 push forward1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156 C.69 random mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158 C.70 representatives . . . . . . . . . . . . . . . . . . . . . . . . . . 158 C.71 representatives1 . . . . . . . . . . . . . . . . . . . . . . . . . . 158 C.72 ring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 C.73 rmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159 C.74 sat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 C.75 sat1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 C.76 subring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 C.77 symmetric algebra . . . . . . . . . . . . . . . . . . . . . . . . . 161 C.78 to div powers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 C.79 tor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 C.80 x to last . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 C.81 zeromat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

Chapter 1

Introduction to Macaulay

1.1 Background

Macaulay is a system for computing in the fields of algebraic geometry and commutative algebra; it is intended to provide a computational research tool for working mathematicians. The system performs algebraic manipulation on polynomials, matrices, ideals, polynomial rings, modules, maps between rings, and complexes of modules. The possible manipulations include the computation of standard (Gröbner) bases, modules of syzygies, finite free resolutions, Hilbert polynomials and functions. Using these basic operations, a variety of derived operations are possible, such as projections, ideal intersections, and the computation of coherent sheaf cohomology groups.

Macaulay differs in a number of significant ways from other computer algebra systems. The computation of standard bases is its fundamental operation, rather than simplification and factoring. Unlike other systems which provide for the computation of standard bases, submodules of free modules can uniformly be used wherever ideals can be used. Macaulay is written in the language C and its design has been optimized for execution on small systems; Macaulay is available, and reasonably powerful, on a Macintosh microcomputer. Computations in Macaulay are interruptable, with the full power of the system available to study and use partial as well as complete results of computations. Macaulay is command-driven, and is quickly learned by mathematicians having no experience with computers.

Macaulay has been continuously evolving since 1977. Macaulay is currently implemented on the Macintosh and Sun, and has been used by mathematicians in a number of countries, including Canada, France, Germany, Italy, Norway, and the USA.

1.2 Summary of New Features

There are a number of new commands available with version 3.

• Monomial orders are more general in that the user can specify an arbitrary monomial order.

• Parameters can be passed to command files, and a limited form of programming is allowed.

• Integer and polynomial expressions are now allowed on input.

• The standard bases commands are more flexible.

• Quotient rings have been added.

• Computations can be performed modulo a homogeneous ideal.

• A fast codimension and degree algorithm has been added.

• A large set of scripts (command files) are provided. These scripts were designed and implemented by David Eisenbud and Mike Stillman.

1.3 Conventions

Throughout this document the operating system prompt is represented by a “#”. The Macaulaysystem prompt is represented by “%”. All Macaulay dialogs are displayed in a typewriter font.

Some commands require parameters while others have optional parameters. Required parameters are enclosed with angle brackets i.e.

command < required argument1 > … < required argument n >

Optional parameters are enclosed in square brackets i.e.:

command [optional argument1] … [optional argument n]

Commands which have default parameters will use the default value if the user enters a carriage return. We will denote this by <return>. (On the Macintosh, one uses the <enter> key, see Appendix B).

1.4 Acknowledgements

There are two people who have had a large influence on us as well as on Macaulay. Graham Evans first introduced one of us (Mike Stillman) to the wonders of syzygies and finite free resolutions, which led to the ancestor of Macaulay written in the late 1970’s. Without him, this system would not exist. His continual support has been invaluable.

David Eisenbud has also played a large role through the years. His support and suggestions have helped shape the entire project, and have been invaluable. He wrote a large majority of the scripts in Appendix C. This large amount of work has made Macaulay a much more powerful system.

We would also like to thank the Mathematical Sciences Insitute at Cornell, for providing us with the Macintosh MPW license, as well as computer equipment and hospitality.

Getting Started with Macaulay

To use Macaulay on a Macintosh, see Appendix B. The following describes how to start Macaulay from a Unix system, such as the SUN.

2.1 Using Macaulay on Unix Systems

2.1.1 Starting up Macaulay

To start up Macaulaytype:

#Macaulay

Macaulaywill respond with a header which includes the system version number.

2.1.2 Command line editing

A backspace will delete the last character typed. To delete the whole command line type:

   (control)"x"

(i.e. hold down the cntrl key and type x at the same time.)

2.1.3 Controlling scrolling of the screen

Some Macaulaycommands such as pres (print resolution) may print more than one screenful of information. Therefore, we need to be able to stop and restart screen scroll.

• To stop the system from printing on the screen type: (control)"s"

• To resume printing on the screen type: (control)"q" 2.1. USING MACAULAY ON UNIX SYSTEMS 11

2.1.4 Using Emacs, Suntools, or Xwindows

Please see a local expert for using Macaulay under Suntools, or Xwindows.

Input Syntax

This chapter describes Macaulay’s input format for commands, user defined variables, ring indeterminates, integer and polynomial expressions, integer lists and variable lists.

3.1 How to Input a Command

Commands are input with one or more spaces between all parameters. Throughout Macaulay, spaces are always considered separators. This means that any integer or polynomial expression cannot include spaces.

3.2 Special Characters

The following characters have special meaning in Macaulay.

                >, <, <<, >>, #, $, @, &, ?, %, ;

The characters “>, <, <<, >>, #, $, @, &” all have meaning when used with script files. The characters “>, <, <<, >>” redirect either the input or the output of Macaulay, when they appear at the beginning of a line or a parameter. The characters “<, <=, >, >=, =, !=” have their usual meaning as relational operators if they appear in an integer or polynomial expression.

The character “#” is used for arguments to scripts, the character “@” is used to provide some support for local variables, and the character “$” is used to exit a script. This last character, if typed outside of a script, causes Macaulay to exit exactly as if “exit” had been typed, so be careful! See Chapter 11 for more details.

The characters “;”, “?” and “%” are used for comments. Any text appearing after a semicolon is ignored (to the end of the line). Text appearing before a “?” or “%” on an input line is also ignored. This allows the user to place comments either at the beginning or at the end of the line. This was included mainly for use with the Macintosh MPW shell: when one types “<enter>”, the entire current line is sent as input to Macaulay. Macaulay’s prompts for input always end with either a “?” or “%”. Therefore the prompt part of the line is considered a comment by Macaulay! An additional benefit is that a Macaulay session (recorded with monitor for example) can be “played back” as an input file.

3.3 User Defined Variables (Identifiers)

Each mathematical object created by the user is associated with a name selected by the user. Identifiers begin with an alphabetic character (upper or lower case) or one of the following three characters: @, ', _. Subsequent characters of the identifer must be either digits (0,…, 9) or a character from the above list. The length of an identifier is limited to 50 characters. Upper and lower case characters are distinct, thus the identifiers “myMatrix” and “mymatrix” refer to different user variables.

For example, the following are all legal names in Macaulay.

     a'mine
     @veronese
     my_matrix
     m0128
     a'

The character @ is used for local variables inside scripts (command files): Inside of a script, @ is expanded to @nn@, where nn is the “level” of this script. Thus name conflicts will not occur if all local variables in a script contain a @. See Chapter 11 for details.

Wherever an identifier is expected as a paramter to a command, you may enclose it in curly braces. Therefore, the identifiers “a mat” and “{a mat}” represent the same variable. Curly braces are only required in certain instances, to avoid name conflicts. See section 4.3 for a complete list of these instances.

3.3.1 Indexed Identifiers

Some variables which denote computations may be indexed. An indexed identifier is an identifier as above, followed by the character “.”, followed by an integer expression. See section 3.5 for a description of integer expressions. See section 4.3 for more information on indexed variables. For example, if “i” is an integer variable, then the following are legal indexed identifiers.

    a.3,
    a.(2*i+1)

3.4 Naming polynomial ring variables (indeterminants)

Every polynomial and every matrix in Macaulay must be defined over a polynomial ring. The indeterminates of a ring are either single letters or are single letters indexed by one or more integers. More specifically, these indeterminates have the following form.

1. a single letter: a-z, A-Z, where upper and lower case are distinct or

2. a single letter, indexed by a set of integers or integer expressions, separated by commas and enclosed by square brackets.

For example, if “i” is a user defined integer variable, then the following are legal ring indeterminates:

    a
    A
    F[1,2,3]
    z[-1,2*i]

The ring command informs Macaulay which variables you wish to use. These names do not conflict with any user defined variable names (i.e. one can have a matrix named “a”, as well as an indeterminate in the base ring of this matrix, named “a”. The only time a conflict is possible is with polynomial expressions. See Sections 3.6 and 4.3 for more details.

We often call ring indeterminates either “variables” or “ring variables”. These should not be confused with user defined variables which are rings.

3.5 Integer Expressions

The syntax for integer expressions in Macaulay is similar to most computer languages, except that no blank spaces are allowed inside of such an expression, since spaces are used as delimiters in Macaulay.

The legal operators of Macaulay, in order of increasing precedence, are given in the following table.

   • <, <=, >, >=, =, !=
   • +, -

• *, / (integer division), & (remainder)

• +, - unary operators

• ^, ** (both are exponentiation operators)

Parentheses are used to enforce groupings in an expression. User defined variables which are integers may appear in expressions.

The relational operators all return the value one if the condition is true, else they return zero.

For example, using the int command,

%  int i (3+1)/2+(4-1)^2
%  type i
; 11
%  int a (i+3)*(i+2)*(i+1)/6
%  type a
; 364
%  int b i>a
%  type b
; 0
%  int b i<a
%  type b
; 1

3.6 Polynomial expressions

The syntax for polynomial expressions is similar to integer expressions.

The legal operators for polynomials, in order of increasing precedence, are given in the following table.

   • +, -

• *, / (polynomial division), & (polynomial remainder)

• +, - unary operators

• ^, ** (both are exponentiation operators)

The polynomial division and remainder are done using the defined monomial order in the base ring. Parentheses are used to enforce groupings in an expression.

The following remarks describe certain aspects of polynomial expressions.

• Polynomials in Macaulayare output in an abbreviated notation: each polynomial is displayed as a number of monomials separated by “+” or “-”. Each monomial is preceeded by its coefficient and each indeterminate is followed by its degree with no intervening blanks. Rational number coefficients are represented by x/y. A polynomial which extends over a line boundary is displayed by using \ as the continuation character. If you wish to have polynomials output in Mathematica format, use the prmat command.

• User defined matrix variables can appear in polynomial expressions. The variable must be enclosed in curly braces so that Macaulay won’t think that it is a sequence of ring indeterminates. “{M}” refers to the (1, 1) entry of the matrix M.

• A \ at the end of a line, preceded by a space, is the line continuation character. Macaulay computes the polynomial on each continued line, and then adds them all together. Thus, each line must be a well-defined polynomial.

• Certain abbreviations are allowed, mainly in order to allow easier entry of polynomials, and to allow the output polynomials of Macaulay to be legal input. One can suppress the “*” between a number or a ring indeterminate and another ring indeterminate, the “^” between a ring indeterminate and its exponent, and the “*” before a left parenthesis, or after a right parenthesis.

For example,

%  poly f (x[1]+x[2])^2
%  type f
; x[1]2+2x[1]x[2]+x[2]2
%  int i 1
%  poly g (x[i]-x[i+1])^2*{f}
%  type g
; x[1]4-2x[1]2x[2]2+x[2]4
%  poly h ab2+c2d+a(b+c)(b-c)
%  type h
; 2ab2-ac2+c2d

3.7 Integer lists

An integer list in Macaulay is an ordered list of integers. They are used for many purposes including, listing the degrees of the rows or columns of a matrix, weights of the variables in a ring, weight functions for monomial orders, and selecting rows or columns of a matrix to define a submatrix.

An integer list consists of a sequence of items, separated by blanks. Each item is one of the following, where e and f are arbitrary integer expressions.

• an integer expression e

• e..f (range)

• e:f (replication)

• a matrix variable m

Ranges must represent an increasing sequence of integers, for example “a..b”, denotes the sequence a, a + 1,…, b, where a and b are user defined integer variables, and a ≤ b. “a..b” is legal even if a > b, but denotes the empty sequence.

Replications e..f replicate the first integer e the number of times indicated by the second integer f. Thus “2:4” represents the sequence 2, 2, 2, 2. If f ≤ 0, e..f denotes the empty sequence.

A matrix variable m denotes the sequence of row degrees of the matrix m. If a fixed length list is expected (as in the setdegs command), and fewer

items are specified, the last integer is replicated to fill the list. If more items are specified, the extras are simply ignored with no warning.

Using special characters in response to an integer list prompt has the following meaning.

• <return> This gives a default integer list which is dependent upon the command. For example, the default value for row degrees in the setdegs command is 0, and the default for the variable weights in a ring, using the ring command is 1.

• “\” This is the line continuation character. If this is entered, preceded by a blank space, you will be prompted to continue the integer list on the next line (which may also be continued with “\”, etc.)

Integer lists are displayed using replication.

Examples: Suppose that the row degrees of the matrix m are “1,1,2,3” and the row degrees of the matrix n are “-1,-4,5,100,1200”. Then

3:5  3 3 3 3 3
1 2 3..5 0:3  1 2 3 4 5 0 0 0
2 1 -1..4 1:2 2 1 -1 0 1 2 3 4 1 1
1 2 3..5 i..i+3 1 2 3 4 5 i i+1 i+2 i+3
4 1 2  4 1 2
0:5 1  0 0 0 0 0 1
0:d  0 0 0 ... 0 (d zeros)
m 10 n  1 1 2 3 10 -1 -4 5 100 1200

Integer lists are used by the commands: submat, cat, ring, setdegs,setcoldegs.

3.8 Variable lists

A variable list is an unordered subset of the variables of a ring. Variable lists are used by the command jacob to determine which variables to differentiate with respect to, and the commands coef, stdpart, inpart, std-minimal, k-basis, and truncate which divide the variables into the “essential” variables and the “parameters” or “coefficients”.

A variable list consists of items separated by blanks. An item in the variable list is one of the following:

• ring variables, e.g. a, x[i+1], d[i,j].

• < ring variable >..< ring variable > (range).

Duplicates in the list are not counted and ranges are determined by the order of the variables in the ring.

Using special characters in response to a variable list request has the following meaning:

• <return> indicates the default and denotes the variables in the first block.

• ! < list > An exclamation mark at the beginning of a list means complement the set.

• ! Denotes the set of all variables in the ring.

• \ This is the line continuation character. If this is entered, preceded by a blank space, you will be prompted to continue entering the variable list on the next line (which may also be continued with \, etc.)

For example, suppose the ring variables in the current ring, in the order they were given in the ring command, are “xyzabcdef”, where “xyz” are the three variables in the first block, and “abcdef” are the variables in the second block. The following variable lists denote the corresponding sets of variables.

x y z a..d {x,y,z,a,b,c,d}
f z..c  {z,a,b,c,f}
a a y..x  {a}

<return>  {x,y,z}

! a..f  {x,y,z}

Suppose that the variables in the current ring, in the order they were given in the ring command, are “xyzdcbax[1]x[2]x[3]y[2]”. Suppose that “xyz” are the variables in the first block, and that the rest of the variables are in the second block. The following variable lists denote the corresponding sets of variables.

x y x[1]..y[2] x,y,x[1],x[2],x[3],y[2]
x..z d..a  x,y,z,d,c,b,a
a..d  bad variable list
! x..z  d,c,b,a,x[1],x[2],x[3],y[2]

<return>  x,y,z

!  all variables x,y,z,d,c,b,a,x[1],x[2],x[3],y[2]

User Defined Variables

4.1 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 Chapter 5 for details.

In Macaulay, an 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 Chapter 9). Computations include standard (Gröbner) bases, syzygies, and finite free

resolutions (see Chapter 7). 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 Chapter 6).

Variables can be created using the following commands: int creates an integer, ring creates a ring. ideal, mat, sparse, and poly create matrices, rmap, imap create ring maps, and std, nres, res and the rest of the commands of Chapter 7 create computations and standard bases.

4.2 Commands to display and remove variables

listvars [a] [a]

List the names and types of all variables currently defined.

If the user types “listvars a”, then more detailed information will be displayed. If “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 Chapter 5 for more details.

type < user defined variable >

This displays the value associated with the variable. If the type of the variable is a matrix, the matrix is displayed (see section 6.2). If the variable is a ring, its variables are displayed. In order to view the other parameters of a ring, use the 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 putstd command. If the computation is a resolution (from res or nres), then use pres to display the corresponding matrices in the resolution.

kill < variable 1 > … < variable n >

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 “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 section 7.4) it is not advisable to kill variables, especially the interrupted computation. Dire and unpleasant things await those who do not heed this warning!

4.3 Referencing variables

Most variables are referenced simply be typing their names, e.g. “R, myideal, f”. There are two special situations.

First, there are many matrices in the resulting resolution coming from the res and 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 “w.3”, and “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 (quotient, intersect, and modulo) create an auxiliary matrix. This matrix always has index “0”. See section 7.2 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. “a+{f}” adds the ring indeterminate a to the polynomial f.

include them here! This problem occurs in several other places as well. .

4.4 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 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: “add m n m” will add the matrices m and n and store the result in m.

4.5 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.

int < name > < 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,

%  int i 3
%  int i i-1
%  int a (i^2-i+1)^3
%  type a     ; answer should be 27

Rings

Every matrix in Macaulay must have a base ring. This base ring is a polynomial ring in a certain number of variables, over a prime field of characteristic p > 0, for some p. It is possible to work modulo an ideal (see the qring command in section 5.3).

There may be many rings defined at any instant, but one of these rings is defined as the “current ring”. For commands which input polynomials (e.g. poly, ideal, mat, sparse), this current ring is used as the base ring. Most commands set the current ring, such as add (add 2 matrices). You may set it explicitly using the setring command.

If a matrix is used as an argument to a Macaulay command which expects a ring, the base ring of the matrix is used. These commands include pring, setring, ring-sum, and the ring map commands (Chapter 9).

When a ring is created, say with the name “r”, the returned value is actually a 1 by n matrix consisting of all the variables in the new ring.

5.1 The “ring” command

The ring command is the most basic command in Macaulay: a ring must be defined before any matrix can be created. We first describe the simplest uses of this command.

ring < result ring >

Interactively define a ring. You are asked for some obvious information, and then for some more obscure information.

The following information is requested:

1. Characteristic of the ring – a positive prime number less than about 32000 is required. If you want to simulate characteristic zero, simply

type <return>. A large characteristic is then selected.

2. The number of variables – must be positive. There is also an upper limit on the number of variables (100 on Macintosh, 512 on Unix systems).

3. Names of the variables (see section 3.4 for the syntax of ring indeterminates). These should be given without intervening spaces. Sequences of variables may be generated by using “-” between two variables, e.g: “a-f”

     expands to “abcdef”, and “a[1]-b[2]” expands to “a[1]a[2]b[1]b[2]”.

If not enough variables are given, you will be prompted for more. If too many are given, the extras are ignored (with a warning).

4. Weights of the variables. An integer list is expected. The weight of each variable must be a positive integer. If <return> is entered, then the variables are all assigned weight one. If too few weights are given, then the last weight given is assigned to the remaining variables.

5. The monomial order. Typing <return> selects the reverse lexicographic order. Typing in a number (which is less than the number of variables) selects a product order (see section 5.4 for details, and the general form expected for the input).

Very often, one types <return> to requests (1), (4) and (5). The following examples define rings, using these defaults.

%  ; first define a ring with variables {a,b,c,d}:
%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  4
!   4 variables, please               ?  a-d
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ? <return>
;   largest degree of a monomial        : 512
% <return>
; second, define a ring with variables {x,y,z,a[1,1], ..., a[2,2]}
%  ; (7 variables in all)
%  ring S
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  7
!   7 variables, please               ?  xyza[1,1]-a[2,2]
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ? <return>
;   largest degree of a monomial        : 76
% <return>

; display these rings using the "pring" command
%  pring R
; ring R
; characteristic           : 31991
; number of variables      : 4
; variables                : abcd
; weights                  : 1 1 1 1
; monomial order           : 4 c
; top degree of a monomial : 512
%  pring S
; ring S
; characteristic           : 31991
; number of variables      : 7
; variables                : xyza[1,1]a[1,2]a[2,1]a[2,2]
; weights                  : 1 1 1 1 1 1 1
; monomial order           : 7 c
; top degree of a monomial : 76

The standard (Gröbner) basis computations in Macaulay require every ideal to be homogeneous, and each matrix to be graded. The weights of the ring variables can often be set so that an ideal is homogeneous. For example, let I = (x − s^{3}, y − s^{2}t^{4}, z − t^{5}). This ideal is not homogeneous. However, if we set the weight of s, t to one, and the weight of x to 3, y to 6, and z to 5, then each generator of I is homogeneous with respect to these weights. This is often used with elimination of variables.

%  ; define a ring with variables {a,b,c,d,e} having weights 5,3,1,1,1
%  ; notice that the last "1" typed is repeated, so that the variables
%  ; c,d,e all have weight one.
%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  5
!   5 variables, please               ?  a-e
! variable weights (if not all 1)     ?  5 3 1
! monomial order (if not rev. lex.)   ? <return>
;   largest degree of a monomial        : 372
%  pring R
; ring R
; characteristic           : 31991
; number of variables      : 5
; variables                : abcde
; weights                  : 5 3 1 1 1

; monomial order           : 5 c
; top degree of a monomial : 372

See Appendix A for more examples.

Caveat: the weight of each variable must be a positive integer. If any of the elements of the integer list are negative, every weight is increased by the same amount in order for the weights to be all positive.

The format for monomial orders is rather complicated, and a whole section (section 5.4) is devoted to it.

5.2 Other ring commands

Each of the commands in this section expect a ring as a parameter. If instead a matrix is specified, the base ring of the matrix is used. This allows rings to be used “anonymously”.

pring [user defined variable]

Display the name and value of the current ring if no parameters are given. If a ring is specified, display its name and value. If a variable is specified, display the name and value of its base ring. For examples, see the ring command above.

setring < R >

Set the current ring to be the ring < R >. The commands which use the current

ring are cat  fetch ideal  iden is-zero koszul mat  pmap poly  pring random sparse

Most commands which manipulate matrices set the current ring to the base ring of the matrix arguments.

nvars < ring > [result integer]

Set the result integer variable, if given, to the number of variables in the given polynomial ring. If an integer is not specified, display the number of variables.

characteristic < ring > [result integer]

Set the result integer variable, if given, to the characteristic of the given polynomial ring. If an integer is not specified, display the characteristic.

ring-from-rows < matrix > < result ring >

Create a new ring with n variables, where n is the number of rows of the given matrix. The weight of each variable is the degree of the corresponding row. The user is prompted for the names of the variables (which should be given exactly as in the ring command). The number of rows must be positive, otherwise an error message is displayed. If any of the weights are non-positive, the same value is added to every weight so that the least weight is one.

The characteristic of the ring is set to the characteristic of the base ring of the given matrix.

For example,

%  row-degs m
21 26 31 39
%  ring-from-rows m S
!   4 variables, please               ?  x[1]-x[4]
[126k]
%  pring S
; ring S
; characteristic           : 31991
; number of variables      : 4
; variables                : x[1]x[2]x[3]x[4]
; weights                  : 21 26 31 39
; monomial order           : 4 c
; top degree of a monomial : 512

ring-from-cols < matrix > < result ring >

Create a new ring with variables corresponding to the columns of the given matrix. This command is exactly like ring-from-rows, except that the variables correspond to the columns rather than the rows.

ring-sum < ring R_{1} > < ring R_{2} > < result ring >

Create a new ring with the variables from both R_{1} and R_{2}. The monomial order of the result is the product order, where each variable of R_{1} is greater than each variable of R_{2}. If either or both of R_{1} and R_{2} is a quotient ring, then the result will be one as well. For example,

%  ; the ring R has variables a,b,c,d, and S has variables x,y,z.
%  ring-sum R S T
%  pring T

; ring T
; characteristic           : 31991
; number of variables      : 7
;  4 variables for block 0 : abcd
;  3 variables for block 1 : xyz
; weights for block 0      : 1 1 1 1
; weights for block 1      : 1 1 1
; monomial order           : 4 3 c
; top degree of a monomial : 512 512

Caveat: no warning message is given if there is a variable of R_{1} with the same name as a variable of R_{2}. In this case, the new ring is created. The two variables will have the same name, but be internally different. This means that when inputting a matrix, the second variable cannot be named: each occurence of the name refers to the variable corresponding to the ring R_{1}.

5.3 Quotient Rings

qring < standard basis > < result ring >

Given a standard basis of an ideal, create a new ring where all operations in this new ring will be done modulo this ideal. A warning message is given if the first argument is not a standard basis. Creating a quotient ring where the base ring of the standard basis is already a quotient ring is legal.

All operations in Macaulay can be done over a quotient ring, including computing standard bases, syzygies, Hilbert functions, and all matrix arithmetic.

For example,

%  putstd j k
%  type k
; b3-acd ab-cd a2-b2
%  qring j S
%  pring S
; ring S
; characteristic           : 31991
; number of variables      : 4
; variables                : abcd
; weights                  : 1 1 1 1
; monomial order           : 4 c
; top degree of a monomial : 512

; quotient ring by ideal:
; a2-b2
; ab-cd
; b3-acd
%  poly f (a+b)^2
%  ; f is reduced w.r.t. the above standard basis:
%  type f
; 2b2+2cd

Caveat: Using the forcestd command, it is possible to create a quotient ring where the above ideal is not homogeneous. In this case, every computation command (Chapter 7) will most likely compute, and compute, and compute... These commands do not detect this possibility.

present-ring < ring > < result ideal I >

Present a ring as a polynomial ring modulo an ideal I. If the given ring is a quotient ring w.r.t. an ideal J, a copy of this ideal is placed into the result I. If the given ring is not a quotient ring, I is set to be the zero ideal over this ring.

%  ; the ring S is the quotient ring above.
%  present-ring S k
%  type k
; a2-b2 ab-cd b3-acd

5.4 Monomial orders in Macaulay

All polynomials in Macaulay are stored as an ordered list of monomials. The order on monomials is a parameter for standard bases which can be modified. Different applications of standard bases often require different monomial orders. Macaulay is flexible enough to allow the user to define arbitrary monomial orders. This order is defined using the ring command.

The most important monomial orders are the reverse lexicographic order, product orders and elimination orders. Almost every application involving standard (Gröbner) bases uses only these orders. On the first reading, most users should skip the section on general monomial orders.

5.4.1 Reverse lexicographic order

The most important monomial order is the (graded) reverse lexicographic order. This is the default in Macaulay, since it can be shown that, in many cases, it is theoretically the most efficient [BS1].

Definition 1 (Reverse lexicographic order) The graded reverse lexicographic order on the monomials of k[x_{1},…, x_{n}]is defined by x^{A} > x^{B} ⟺ deg(x^{A}) > deg(x^{B}), or deg(x^{A}) = deg(x^{B}), and the last non-zero component of A-B is negative.

Thus, in k[x, y, z],

x^{2} > xy > y^{2} > xz > yz > z^{2} > x > y > z > 1.

There are many reverse lexicographic orders, in fact, there is one for each permutation of the variables.

The user can define the reverse lexicographic order using the ring command. For example, to define a polynomial ring with five variables of weight one, e.g. (a, b, c, d, e) , and using the reverse lexicographic order in this ring, you need to simply input the number of variables and <return> (the default) for the monomial order.

%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  5
!   5 variables, please               ?  abcde
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ? <return>
;   largest degree of a monomial        : 217

As this example illustrates, you don’t have to do anything special to get the reverse lexicographic order. Note that this order is graded: it first orders by degree. For example, in k[x, y, z], if deg(x) = 2, deg(y) = 3, and deg(z) = 4, then the order of monomials in the reverse lexicographic order is

x^{2} > z > y > x > 1,

since deg(x^{2}) = deg(z) = 4 > deg(y).

5.4.2 Product and elimination orders

Although the reverse lexicographic order is the best order to use in many cases, there are applications where one must use other orders. See the examples in the appendix for more information (e.g., computing projections, images of maps to projective spaces, normal cones, computing inhomogeneous standard bases using homogenization, etc.).

The product order and the elimination order are also useful monomial orders. The product order is used when you want one set of variables to always be greater than the second set. The elimination order is used for computing projections (i.e. elimination of a set of variables).

Definition 2 (Product order) Let >_{1} (resp. >_{2}) be a monomial order on the monomials of k[x_{1},…, x_{m}] (resp. k[y_{1},…, y_{n}]). The product order > on the monomials of k[x_{1},…, x_{m}, y_{1},…, y_{n}] is defined by x^{A}y^{B} > x^{C}y^{D} ⟺ x^{A} >_{1} x^{C}, or x^{A} = x^{C}, and y^{B} >_{2} y^{D}.

Similarly, one can define the product order on any number of blocks of variables. The simplest product order is the product order where each >_{i} is the reverse lexicographic order. In this case, we have

x_{1}^{2} > x_{1}x_{2} > x_{1}y_{1}^{100} > y_{1}^{100} > y_{1}y_{2} > 1.

We denote by x_{1},…, x_{m} >> y_{1},…, y_{n}, the product order where we use reverse lexicographic order in each block. This order can be constructed with the ring command in response to the prompt for the monomial order. The user specifies m blocks of variables by inputting m integers. Each of these integers indicates how many variables are in each block. The blocks are determined by the order of the variables input to the ring command. Macaulaydisplays the maximum degrees that are allowed for a monomial. Each number is the maximum total degree of the variables in the corresponding block.

If this number is too small, then break up the variables into more blocks. By default, the maximum degree allowed is 512. This can be changed by using the Macaulay parameter “maxdegree”. This parameter is only a suggestion to Macaulay: it may still be necessary to break the variables into smaller blocks.

For example, to create the product order

x, y, z >> a, b, c, d

in k[x, y, z, a, b, c, d], one responds to the prompts as follows:

%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  7
!   7 variables, please               ?  x-za-d
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ?  3 4
;   largest degree of a monomial        : 512 512

To create the product order

s, t >> x, y, z >> a, b, c

one responds to the prompts as follows:

%  ring S
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  8
!   8 variables, please               ?  stxyzabc
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ?  2 3 3
[189k];   largest degree of a monomial        : 512 512 512

The product order is very versatile, and has many applications. However, the elimination order is in many instances more efficient.

Definition 3 (Elimination order) Let 1 ≤ i ≤ n. The elimination order >_{i} on the monomials of k[x_{1},…, x_{n}] is defined by x^{A} > x^{B} ⟺ deg_{i}(x^{A}) > deg_{i}(x^{B}), or deg_{i}(x^{A}) = deg_{i}(x^{B}), and x^{A} >_{rlex} x^{B}, where deg_{i}(x_{1}^{a_{1}}x_{2}^{a_{2}} … x_{n}^{a_{n}}) := deg x_{1}^{a_{1}} … x_{i}^{a_{i}}.

If the i^{th} variable is named x, we denote this order by >_{x}. We define an elimination order with the ring command in the following way. For example, suppose you want a ring with variables s,t,w,x,y,z, and you want to choose the elimination order >_{t}. When prompted for the monomial order respond with “w”. The “w” stands for “weight vector”. After giving the default weights for the variables by hitting the return key, you are then prompted for a “weight vector”. You respond by typing in the name of the last variable you wish to eliminate, in this case t. For example,

%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  6
!   6 variables, please               ?  stw-z
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ?  w
! weight vector #1                    ?  t
;   largest degree of a monomial        : 117
%  ; now display this ring
%  pring R
; ring R
; characteristic           : 31991

; number of variables      : 6
; variables                : stwxyz
; weights                  : 1 1 1 1 1 1
; weight vector block 0    : 1 1 0 0 0 0
; monomial order           : w 6 c
; top degree of a monomial : 117

5.4.3 Monomial orders for free modules

So far we have only considered orders on the monomials in a polynomial ring. However, if we wish to compute standard bases of submodules of free modules as well as for ideals, we need to define monomial orders on the monomials in a free module. First, what are the monomials in a free module? Let e_{i} = (0,…, 1,…, 0)^{T} be the i^{th} unit (column) vector in the free module k[x_{1},…, x_{n}]^{s}, 1 ≤ i ≤ s. The monomials are just x^{A}e_{i}.

There are two basic ways of extending a monomial order > to free modules.

• x^{A}e_{i} > x^{B}e_{j} ⟺ x^{A} > x^{B}, or x^{A} = x^{B} and i > j.

• x^{A}e_{i} > x^{B}e_{j} ⟺ i > j, or i = j and x^{A} > x^{B}.

The first of these is the default in Macaulay. The second can be obtained using the ring command in the following way. When prompted for the monomial order, respond with the letter “c”. The “c” stands for the “module component number”, or the “row number” of the monomial. The effect of this response is that the higher the component, or row, number, the greater the monomial.

For example,

%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  5
!   5 variables, please               ?  a-e
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ?  c
;   largest degree of a monomial        : 217
%  ; the component number is now considered before the order on the
monomials
%  ; of the ring.
%  pring R
; ring R
; characteristic           : 31991
; number of variables      : 5
; variables                : abcde

; weights                  : 1 1 1 1 1
; monomial order           : c 5
; top degree of a monomial : 217

Important note for computing finite free resolutions: It is often much more efficient, both in space and elapsed time, to use this second order rather than the default. The default has been chosen to make elimination of variables for modules a simpler process.

In fact, if you have several blocks of variables, you can put the “c” before or after any block. The default in Macaulay is to tag the “c” on at the end of what you type (assuming you did not include a “c”). At the end of this section we describe these more general forms.

Usually, when you display a polynomial using type, for example, the monomials are displayed in descending order. For column vectors this is not possible, since the lead monomial can occur in any row. You can see the initial monomial by using the in command.

5.4.4 General monomial orders in Macaulay

The most important monomial orders are those which have been introduced earlier in this section. Occasionally, one needs finer control over the monomial order. Macaulay allows you to construct arbitrary monomials orders.

When you are prompted for the monomial order by the ring command, you are actually specifying the internal representation of monomials for the ring being defined. The representation is a series of 32 bit non-negative integers, one for each specifier given. The specifiers may be

1. “w” for a weight vector. The program prompts later to have the weight vectors input, in order.

2. a number, specifying the number of variables to put into the “next” block of variables to be created. That is, for “3 w 5”, the third specifier refers to the 4th through the 8th variable. Within a given block, Macaulay uses the graded reverse lexicographic order.

3. “c” for the position of the component number. At most one “c” can be used. Except for computing difficult finite free resolutions, this is best omitted: Macaulay will insert it last automatically.

4. “-”: Put this first to suppress the component.

If the representation is “incomplete”, it is completed automatically by Macaulay, which adds one or two fields to the end of the list: any variables not included in a given block of variables are made into a block, and a component field (specified by “c”) is put at the end of the list, unless it is already present or has been inhibited by the presence of a “-” specifier.

Caveat: use the “-” specifier at your own risk. No matrices with more than one row are allowed in such a ring. This is mostly useful for computing a standard basis of an ideal which will use alot of memory.

Weight vectors

Macaulay next prompts for the weight vectors, one for each “w” given above. A weight vector in a ring with variables x_{1},…, x_{n} is a vector (w_{1},…, w_{n}). Macaulay expects an integer list or a ring variable. The 32 bit integer which is placed into the corresponding field is the value of the monomial x_{1}^{a_{1}} … x_{n}^{a_{n}} under this weight vector: ∑ w_{i}a_{i}.

Specifying a ring variable corresponds to using the weight of each variable up to and including the variable given, and zeros afterwards. This is useful for specifying elimination orders.

It is possible to have a name conflict between a user defined integer variable and a ring variable. Therefore, in order to use an integer variable you must enclose it in curly braces.

Weight vectors have integer entries: they can be negative if desired. If so, Macaulay adds a multiple of the variable weights to the weight vector so that each component will be non-negative.

For example,

%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  7
!   7 variables, please               ?  xyza-d
! variable weights (if not all 1)     ?  2 3 4 1 1 2 2
! monomial order (if not rev. lex.)   ?  w w
! weight vector #1                    ?  2:3 0
! weight vector #2                    ?  z
;   largest degree of a monomial        : 146
%  pring R
; ring R
; characteristic           : 31991
; number of variables      : 7
; variables                : xyzabcd
; weights                  : 2 3 4 1 1 2 2
; weight vector block 0    : 2 2 2 0 0 0 0
; weight vector block 1    : 2 3 4 0 0 0 0
; monomial order           : w w 7 c
; top degree of a monomial : 146
%  ; notice the two weight vectors, and that the specifiers "7 c"

%  ; have been added to the end of the monomial specification.

The general monomial order

The monomial order which Macaulay uses is the strict lexicographic order on the 32 bit integers which form the internal representation of a monomial. For example,

%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  7
!   7 variables, please               ?  xyza-d
! variable weights (if not all 1)     ?  1:3 4
! monomial order (if not rev. lex.)   ?  w 3 4
! weight vector #1                    ?  1 0:6
;   largest degree of a monomial        : 512 512
%  pring R
; ring R
; characteristic           : 31991
; number of variables      : 7
;  3 variables for block 1 : xyz
;  4 variables for block 2 : abcd
; weights for block 1      : 1 1 1
; weights for block 2      : 4 4 4 4
; weight vector block 0    : 1 0 0 0 0 0 0
; monomial order           : w 3 4 c
; top degree of a monomial : 512 512
%  poly f x2+xy10a+xy10+a50+a53b
%  type f
; x2+xy10a+xy10+a53b+a50
%  ; The weight vector (1,0,...,0) takes precedence: the monomials
%  ; are ordered first by highest power in "x", then by the (graded)
%  ; reverse lexicographic order in x,y,z (ignoring a,...,d), and finally
%  ; by the reverse lex. order in a,b,c,d.

Matrices

A matrix in Macaulay is a matrix of polynomials over some polynomial ring. In this chapter, we describe the operations available for computing with matrices which don’t require standard bases. These range from matrix input and output, to simple operations such as addition and multiplication of matrices, to relatively esoteric operations such as koszul or contract.

Matrices have several interpretations in Macaulay. Let M be an m by n matrix of polynomials over the ring R. There are two R-modules which we can associate to M. First, the submodule I ⊂ R^{m} is the submodule of R^{m} generated by the columns of the matrix M. This interpretation is used heavily when dealing with standard (Gröbner) bases. We call I the “submodule generated by the columns of the matrix M”. The second module corresponding to M is the module N which is presented by M. That is, The R-module N has m generators, one for each row of M, and the relations between these generators are exactly the columns of the matrix M. This interpretation is used often, although not as much as the first. For example, the hilb command computes the Hilbert series of the module presented by a matrix.

Each matrix in Macaulay must be defined over a specific base ring. This is required so that the standard basis and syzygy computations which are the heart of Macaulay can be highly optimized. Every command in this chapter (indeed, every command of Macaulay) can be used with all rings of Macaulay. In particular, each command works fine over a quotient ring.

Every operation described in this chapter remains valid even if the input matrices are not graded. In fact, the only commands of Macaulay where this is false are the computation commands (see Chapter 7).

Some additional notes valid for all matrix commands:

• Matrices with zero rows or columns (or both) are allowed as parameters (when they make sense, e.g. one can multiply a 3 by 0, and a 0 by 4 matrix to obtain a 3 by 4 matrix. This is useful for writing scripts.

• Result variables can be given the same name as an argument: e.g. the command “add m n m” computes m+n, and then removes the old matrix m, and finally stores the result m + n with the name m.

• As usual thoughout Macaulay, whenever an integer is expected as an argument, or is prompted for, one may use any integer expression.

The following two commands display the number of rows or columns of a given matrix. They are most useful in conjunction with scripts. See also the numinfo and betti commands: they display more information.

nrows < matrix > [result integer]

Set the result integer variable, if given, to the number of rows of the matrix. If an integer is not specified, display the number of rows.

ncols < matrix > [result integer]

Set the result integer variable, if given, to the number of columns of the matrix. If an integer is not specified, display the number of columns.

6.1 Matrix creation

There are four commands for creating matrices interactively: mat, poly, ideal and sparse. These prompt the user for input polynomials. The resulting matrix for each of these commands has the current ring as its base ring.

ideal < result matrix >

In Macaulay, ideals are represented as matrices with a single row. The ideal command is provided to allow you to simply specify the generators for the ideal. First, you are prompted for the number of generators. Subsequently, the system prompts for the generators one at a time creating a 1 by n matrix, where n is the number of generators. The generators are input as polynomials in the current ring. The base ring of the resulting matrix is the current ring.

mat < result matrix > [file name]

Interactively create a matrix over the current ring. You are first prompted for the number of rows, and then columns. Any integer expression is allowed. Macaulay then prompts for each entry of the matrix column by column. Each entry should be a polynomial expression in the base ring.

If a file name is specified, the command uses this file as input, and the system doesn’t display any prompt lines. Thus "mat m file" is the same as "mat m <file", where the input has been redirected to come from “file”, except that no prompts are displayed.

For example, to define a 2 by 3 matrix named m,

%  mat m
! number of rows    ?  2
! number of columns ?  3
! (1,1) ?  a2-b2
! (2,1) ?  (a+b)^2
! (1,2) ?  2c
! (2,2) ?  3d
! (1,3) ?  0
! (2,3) ?  (a+b)(c-d)
%  type m
; a2-b2     2c 0
; a2+2ab+b2 3d ac+bc-ad-bd

The putmat command outputs matrices in a format suitable to be input to the mat command. Thus, one can use putmat to output matrices to a disk, and then read them at another time using mat.

For more information about degrees of rows, columns, and graded matrices, see section 6.5.

poly < result matrix > < polynomial >

Set < result > with the 1 by 1 matrix over the current ring consisting of the given polynomial expression. For example,

%  poly f (a+b)*(a-b)
%  type f
; a2-b2
%  poly f {f}^2
%  type f
; a4-2a2b2+b4

In order to use a previously defined polynomial, its name must be enclosed in curly braces. This prevents name conflicts with ring variables. See section 3.6 for more details.

sparse < result matrix > [file name]

Interactively create a sparse matrix over the current ring. The system first prompts for the number of rows and columns, and then prompts for the index and polynomial value of each non-zero entry.

If a file name is given, the command uses this file as input, and the system doesn’t display any prompt lines. Thus "sparse m file" is the same as "sparse m <file", where the input has been redirected to come from “file”, except that no prompts are displayed.

For example, to create a 5 by 6 matrix named m56,

%  sparse m56
! number of rows    ?  5
! number of columns ?  6
! row column value  ?  1 1 a2+b2+cd
! row column value  ?  3 5 abc
! row column value  ?  5 6 -1
! row column value  ? <return>
%  type m
; a2-b2     2c 0
; a2+2ab+b2 3d ac+bc-ad-bd

The row, column, and polynomial expression are separated by blanks. The row and column can be any integer expressions. To stop the input of entries, simply type <return> on your terminal. The remaining entries are set to zero.

The base ring of the matrix is the current ring.

6.2 Displaying Matrices

type < matrix >

Display the given matrix on the user’s screen. This is the usual method of viewing matrices which are not too large. If an entry of the matrix is large, putmat is sometimes preferable.

putmat < matrix >

Write to standard output the matrix in a format suitable to read by mat. For example, "putmat m >file" writes to the file “file”. One can then use "mat m <file", or "mat m file" to read this matrix in at a later time. Caution: before using this command with a file, make sure you have defined the desired current polynomial ring!

For example,

%  type m
; a b
; c d
%  putmat m
; 2
; 2
; a
; c
; b
; d

The leading semicolons will not appear if a file name is given.

prmat < matrix >

Writes the matrix in a format suitable for input to the Mathematica system.

One word of warning: Certain variable names can cause problems. For example, any indexed variable using “D”: eg. D[1]. In Mathematica, D[1] is the derivative of the function “1”, so D[1] = 0. The letters which are used in Mathematica are: “D”, “E”, “I”, “N”, and “O”. When inputting the matrix to Mathematica, the following problem can occur. If an identifier, say “a” already has a value, then every occurence of “a” in the matrix will be replaced with this value.

%  type m
; a     ab-1/3c -12
; b2-c2 0       a3+a2+a+1
%  prmat m
{
  {a,
    a*b-1/3*c,
    -12},
  {b^2-c^2,
    0,
    a^3+a^2+a+1}
}

6.3 Operations on matrices

add < matrix > < matrix > < result >

Add two m by n matrices having the same base ring and store the result in an m by n matrix.

cat < ring variable or integer > < result matrix >

Create a matrix consisting of indeterminates. The first argument is either a ring indeterminate in the current ring, or an integer. The user is prompted for two integer lists: call them rows, and cols. The result matrix is then the matrix whose (i, j) entry is

v[rows(i) + cols(j)],

where v[k] is the k th ring indeterminate:

1. if the first argument is a ring variable, then v[k] is the k th variable after the given ring variable.

2. if the first argument is an integer, n say, then v[k] is the n + k th variable of the ring.

For example, if the variables of the current ring are abcdefghij, then

%  cat a m
! rows ?  0 3 6
! columns ?  0 1 2
%  type m
; a b c
; d e f
; g h i

Note: if i is an integer variable, then “cat i m” takes the ring indeterminate i. To get the integer i, use “cat {i} m”.

This command is very useful for creating “generic” matrices.

coef < matrix > < result matrix > [variable list]

Find the monomials in the given variable list which occur in < matrix >, and return a 1 by n matrix consisting of these monomials, and another matrix consisting of the coefficients of these monomials.

If < matrix > has just one column, then the result coef matrix has the same number of rows as < matrix > and n columns, one for each monomial.

If < matrix > has several columns, the result is the concatenation of the results for each column done separately.

For example,

%  type m
; abc2+abcd+a2d
; a2e+1
; b2+1
%  coef m monoms coefs a b
%  type monoms
; ab a2 b2 1
%  type coefs
; c2+cd d 0 0
; 0     e 0 1
; 0     0 1 1

Caution: The default variable list, if none is given, is the first block of variables in the base ring of < matrix >. To find the coefficients in all of the variables, use “!”: e.g. coef m monoms coefs !. For more details see section 3.8.

compress < matrix > < result matrix >

Create a new matrix which is the submatrix of < matrix > consisting of those columns which have a non-zero entry. For example,

%  type m
; 0 a 0
; 0 b 0
%  compress m n
%  type n
; a
; b

concat < matrix > < matrix2 > ... < matrix n >

Replace < matrix > with the concatenation of all n matrices. Every matrix should have the same number of rows and the same base ring. The result matrix has the same number of rows, but it has a column for each column of each matrix. These columns are placed into < matrix > in the natural order.

The row degrees of the result matrix are exactly the same as the original < matrix >. The column degrees have likewise been concatenated together. So, if the row degrees of the various matrices are different, then the resulting matrix is probably not graded: use setdegs, or setcoldegs to correct this.

For example,

%  type m
; a2
; b2
%  type m1
; a b
; c d
%  concat m m1
%  type m
; a2 a b
; b2 c d

Caution: this command is “destructive”: the first argument is actually modified. An error is reported if the matrix being modified also appears later in the argument list.

contract < ideal I > < ideal J > < result matrix >

Contract each element of a 1 by n matrix J by each element of the 1 by m matrix I, producing a m by n matrix. Both matrices must have the same base ring.

Contraction is defined on monomials by

x^{A}.x^{B} = \{ \begin{matrix}x^{B−A} & if B − A ≥ 0 \\ 0 & otherwise \end{matrix}

and is extended bilinearly to all polynomials. For example, x^{2}yz.x^{3}y^{2}z = xy.

This is exactly the same as diff, except that contraction is used instead of differentiation. E.g. a^{2}.a^{3} = a, not 6a.

For example,

%  type i
; a2 a2+bc abc

%  type j
; a2-bc abcd
%  contract i j k
%  type k
; 1 0
; 0 ad
; 0 d

copy < existing matrix > < copy of matrix >

Create a copy of the original matrix. If any changes are made to either matrix, the other will not be affected.

diag < matrix > < result >

Takes an m by n matrix and places into < result > the mn by mn diagonal matrix whose diagonal entries are all the entries of < matrix >. The diagonal entries of the result are taken from the first column, then the second, and so on, as in the following example.

%  type m
; a c
; b d
%  diag m n
%  type n
; a 0 0 0
; 0 b 0 0
; 0 0 c 0
; 0 0 0 d

diff < ideal I > < ideal J > < result matrix >

Differentiate each element of a 1 by n matrix J by the differential operator corresponding to each element of the 1 by m matrix I, producing a m by n matrix. Both matrices must have the same base ring.

This is exactly the same as contract, except that differentiation is used instead of contraction. For example, a^{2}.a^{3} = 6a.

For example,

%  type i
; a2 a2+bc abc
%  type j
; a2-bc abcd
%  diff i j k
%  type k
; 2 0
; 1 ad
; 0 d

dsum < matrix > ... < matrix > < result >

Place into < result > the direct sum of the given matrices, i.e. the block diagonal matrix with the i th block being the i th matrix.

For example,

%  type m
; a b
; c d
%  type n
; a2+b2 ab-cd
%  dsum m n n p
%  type p
; a b 0     0     0     0
; c d 0     0     0     0
; 0 0 a2+b2 ab-cd 0     0
; 0 0 0     0     a2+b2 ab-cd

flatten < matrix > < result ideal of entries >

Create the row vector consisting of all the entries of the given m by n matrix. The resulting matrix has size 1 by mn. The elements of < matrix > are taken from the first column, then the second, and so on, as in the following example.

%  type m
; a c e
; b d f

%  flatten m n
%  type n
; a b c d e f

homog < matrix > < homog variable > < result matrix >

Homogenize the columns of < matrix > w.r.t. the homogenizing variable, which must be a ring indeterminate in the base ring of < matrix > having weight one.

For example, if a, b, d all have weight one in the current ring, then

%  type m
; a3  a+3 -a3+ab+1
; a-1 a-2 b5
%  homog m d n
%  type n
; a3     a+3d -a3d2+abd3+d5
; ad2-d3 a-2d b5

iden < size > < result >

Creates a < size > by < size > identity matrix over the current ring. The row and column degrees are all set to 0. Use setdegs to change them, if desired.

jacob < ideal > < resulting jacobian > [variable list]

Compute the Jacobian matrix of a 1 by n matrix, w.r.t. the given set of variables. The resulting matrix has n rows, and m columns, where m is the number of variables given in the variable list. The (i, j) entry is then the derivative of the i th polynomial in < ideal > by the j th variable in the given set of variables.

For example,

%  type j
; a2-bc abcd
%  jacob j k a..d
%  type k
; 2a  -c  -b  0
; bcd acd abd abc

In the first example, if instead of a..d, one used d c b a, the exact same answer would result, since variable lists are unordered.

Caution: The default variable list, if none is given, is the first block of variables in the base ring of < ideal >. To find the derivatives with respect to all of the variables, use “!”: e.g. jacob m Dm !. For more details see section 3.8.

koszul < int n, or matrix > < p > < result matrix >

Create a Koszul matrix. If the first argument is a matrix, it should be a 1 by n matrix, for some n. If an integer is given, the input matrix is set to the 1 by n matrix consisting of the first n variables in the current ring.

The result matrix is the matrix corresponding to the map

⋀^{p} V ⟶ ⋀^{p−1} V,

where V is free of rank n, and the map is induced from the input matrix. The resulting matrix has dimensions \binom{n}{p−1} by \binom{n}{p}.

For example, if the first 4 variables in the current ring are abcd, then

%  koszul 4 2 n
%  type n
; b  c  d  0  0  0
; -a 0  0  c  d  0
; 0  -a 0  -b 0  d
; 0  0  -a 0  -b -c

mult < matrix 1 > < matrix 2 > < result >

Multiply a p by q matrix by a q by r matrix, producing a p by r matrix. Both matrices must have the same base ring.

outer < matrix > < matrix > < result matrix >

Compute the outer (or Kronecker) product of two matrices. If the matrices have sizes a by b and c by d respectively, then the result has size ac by bd.

For example,

%  type m
; a b
; c d

%  type n
; e f g
; h i j
; k l m
%  outer m n p
%  type p
; ae af ag be bf bg
; ah ai aj bh bi bj
; ak al am bk bl bm
; ce cf cg de df dg
; ch ci cj dh di dj
; ck cl cm dk dl dm

pfaff < skew matrix > < result ideal >

Given an n by n skew symmetric matrix, compute the 1 by \binom{n}{4} matrix of all the 4 by 4 Pfaffians of the matrix. Recall that the Pfaffian of a 4 by 4 skew symmetric matrix is the square root of its determinant.

For example,

%  type m
; 0  a  b  c  d
; -a 0  e  f  g
; -b -e 0  h  i
; -c -f -h 0  j
; -d -g -i -j 0
%  pfaff m j
%  type j
; ce-bf+ah de-bg+ai df-cg+aj dh-ci+bj gh-fi+ej

power < matrix > < integer d > < result matrix >

Take a 1 by n matrix and returns a 1 by \binom{n+d−1}{n−1} matrix consisting of all products of these polynomials taken d at a time. The products are constructed in descending lexicographic order.

For example,

%  type m

; a b c d
%  power m 2 m2
%  type m2
; a2 ab ac ad b2 bc bd c2 cd d2

random < integer m > < integer n > < result matrix >

Create a m by n matrix with random constant entries over the current ring. For example,

%  random 2 3 m
%  type m
; -1955 2555 3982
; 3748  1719 8651

smult < matrix > < polynomial > < result >

Multiply each entry of the m by n matrix by the polynomial and store the result in an m by n matrix. The polynomial must be in the base ring of the matrix.

For example,

%  type m
; a b
; c d
%  smult m (d+e)^2 n
%  type n
; ad2+2ade+ae2 bd2+2bde+be2
; cd2+2cde+ce2 d3+2d2e+de2

subtract < matrix 1 > < matrix 2 > < result >

This command subtracts the m by n < matrix 2 > from the m by n < matrix 1 > and stores the result in an m by n matrix.

submat < matrix > < result submatrix >

Put a submatrix of < matrix > into < result submatrix >. The user is prompted for integer lists describing exactly which rows and columns to choose.

In the following example, we choose the first two rows of the matrix m, and the last two columns of m permuted.

%  type m
; a b c d
; e f g h
; i j k l
%  submat m n
! rows ?  3 2
! columns ?  1..3
%  type n
; i j k
; e f g

If <return> is entered for the row (or column) integer list, then every row (or column) is selected. Notice that this command can be used to permute the rows or columns of a matrix.

tensor < matrix M > < matrix N > < result matrix >

Compute the tensor product of the modules presented by the matrices M, N: If M is an a by b matrix, and N is a c by d matrix, then the result is a matrix with ac rows, and bc + ad columns, which is the matrix which presents the tensor product of the two modules.

For example,

%  type m
; a b
; c d
%  type n
; e f g
; h i j
; k l m
%  tensor m n p
%  type p

; e f g 0 0 0 a b 0 0 0 0
; h i j 0 0 0 0 0 a b 0 0
; k l m 0 0 0 0 0 0 0 a b
; 0 0 0 e f g c d 0 0 0 0
; 0 0 0 h i j 0 0 c d 0 0
; 0 0 0 k l m 0 0 0 0 c d

transpose < matrix > < result matrix >

Transpose the m by n matrix and store the result in an n by m matrix. The row and column degrees are interchanged and negated, in order to keep the result matrix graded, assuming the input matrix is also graded.

trace < matrix > < resulting trace >

Sets the 1 by 1 matrix < result > with the sum of the diagonal entries of the m by n < matrix >.

wedge < matrix M > < integer p > < result matrix >

Compute the determinants of all the p by p minors of the given m by n matrix. The resulting matrix ∧^{p}M has size \binom{m}{p} by \binom{n}{p}. The signs are chosen so that if C = A.B, where A and B are matrices, then ∧^{p}C = ∧^{p}A ∧^{p} B.

For example,

%  type m
; a b c
; d e f
; g h i
%  wedge m 2 n
%  type n
; -bd+ae cd-af  -ce+bf
; bg-ah  -cg+ai ch-bi
; -eg+dh fg-di  -fh+ei

Use the flatten command to find the ideal of all of these determinants.

6.4 Editing Commands

The commands in this section all modify a previously defined matrix. They are often useful to simplify a matrix, or to change a single entry of a matrix.

In order to use these commands, you must first use the edit command to tell Macaulay which matrix you wish to edit. This “edit matrix” is kept as the matrix to modify until either you select a different matrix, or the variable is removed.

edit [matrix]

Set the “edit matrix” to be the specified matrix. Subsequently, the commands ac, ar, ce, mc, mr, pc, and pr will act on and modify this matrix.

If no matrix is specified, the “edit matrix” is set to “none”. This also occurs if the “edit matrix” is removed or killed by another command.

edit < skew symmetric matrix > skew

This version of the edit command tells the system that the specified matrix is a skew-symmetric matrix and that every row operation ar, mr, and pr should also be done on columns in order for the result to remain skew symmetric.

ac < col c > < polynomial f > < column to modify d >

Add a polynomial multiple of one column to another column. Modify the d th column of the edit matrix by multiplying the c th column of the edit matrix by f, and adding this to the d th column. c and d are integer expressions, and f is any polynomial expression in the base ring of the edit matrix.

ar < row r > < polynomial f > < row to modify s >

Add a polynomial multiple of one row to another row. This command is the same as ac, but acts on rows rather than columns.

ce < i > < j > < polynomial f >

Change the (i, j) entry of the edit matrix to f. i and j are integer expressions and f is a polynomial expression in the base ring of the edit matrix.

This command does not modify the row or column degrees, so it may be necessary to use either setdegs or setcoldegs to correct the degrees.

mc < column c > < polynomial f >

Multiply the specified column of the edit matrix by the specified polynomial. c is any integer expression, and f is a polynomial expression in the base ring of the edit matrix.

mr < row r > < polynomial f >

Multiply the specified row of the edit matrix by the specified polynomial. r is any integer expression, and f is a polynomial expression in the base ring of the edit matrix.

pc < column i > < column j >

Permute (interchange) the specified columns of the edit matrix. i and j are any integer expressions.

pr < row i > < row j >

Permute (interchange) the specified rows of the edit matrix. i and j are any integer expressions.

6.5 Graded Matrices and Homogeniety

Each matrix in Macaulay is presumed to be graded. i.e. each row and each column is given an integer degree, and the sum of the i th row degree with the degree of the (i, j) entry of the matrix is equal to the j th column degree.

When a matrix is created, its row degrees are all set to zero. The degree of each non-zero column is then computed, and every zero column is given degree zero.

The commands setdegs, setcoldegs, and dshift modify the row and column degrees of a matrix. This is sometimes necessary because certain commands do not usually reset the degrees of the matrix which they modify. These commands include the “edit matrix” commands (section 6.4), concat, and editmap.

Most commands of Macaulay will operate on matrices which are not graded. The only commands which require graded matrices are the commands which compute standard (Groebner) bases. These commands include std, res, nres, syz, intersect, quotient, modulo, and lift-std.

col-degree < matrix > < column > [result integer]

Set the result integer variable, if given, to the degree of the given column of the given matrix. If an integer is not specified, display this degree. The < column > is any integer expression. Zero is returned if < column > is out of range.

col-degs < matrix > [column degrees]

Display the column degrees of a matrix. If a second argument is given, it should be an identifier. In this case, its value is set to an n by 0 matrix whose row degrees are the same as the column degrees of < matrix >.

dshift < matrix > < degree d to shift by >

Add the value of the integer expression ”d” to each row and column degree of < matrix >.

max < matrix > [result maximum row degree]

Set the result integer variable, if given, to the maximum row degree of the given matrix. If a variable is not specified, display the maximum degree. If < matrix > has zero rows, then zero is returned.

min < matrix > [result minimum row degree]

Set the result integer variable, if given, to the minimum row degree of the given matrix. If a variable is not specified, display the minimum degree. If < matrix > has zero rows, then zero is returned.

row-degree < matrix > < row > [result integer]

Set the result integer variable, if given, to the degree of the given row of the given matrix. If a variable is not given, display the degree. The < row > is any integer expression. Zero is returned if the < row > is out of range.

row-degs < matrix > [row degrees]

Display the row degrees of a matrix. If a second argument is given, it should be an identifier. In this case, its value is set to an n by 0 matrix with the same row degrees as < matrix >.

setcoldegs < matrix >

Prompts for the degree of each column. If <return>is typed, the column degree of each non-zero column is computed from the existing row degrees. Each column consisting entirely of zeros has its degree set to zero. If instead an integer list is given, this list is used as the column degrees. See section 3.7 for details on integer lists.

A warning message is displayed if the resulting matrix is not graded.

setdegs < matrix >

Prompts for the row degrees to be assigned to this matrix. If <return>is typed, every row degree is set to zero. Otherwise, an integer list is expected. The system then prompts for the column degrees. If <return>is typed, the column degree of each non-zero column is computed from the above row degrees. Each column consisting entirely of zeros has its degree set to zero. If instead an integer list is given, this list is used as the column degrees. See section 3.7 for details on integer lists.

A warning message is displayed if the resulting matrix is not graded.

Standard (Gröbner) Basis Computations

Computations of standard bases and syzygies are the heart of Macaulay. The command std is the workhorse of Macaulay which computes standard (Gröbner) bases. The commands res and nres are important commands which compute finite free resolutions. These three basic commands are described in section 7.1. The other computations are somewhat more specialized, but still quite useful. These include intersect, lift-std, modulo, quotient and syz. These commands are described in section 7.2.

Each matrix which is input to the commands of this chapter must be graded: see section 6.5 for details. In fact, the commands in this section are the only commands of Macaulay which require that their input parameters be graded. If the matrix is not graded, an error message is issued. In this case, either homogenize the matrix, or use the setdegs or setcoldegs command to make the matrix graded.

The commands in this chapter compute a standard basis and/or syzygy module of a submodule of a free module corresponding to the columns of a matrix. (see the introduction of Chapter 6). For each computation command except res and nres, the result is a matrix together with a standard basis for the corresponding submodule. Both the standard basis and the matrix have the same name, the name given to the < result computation >. The result of the commands nres and res is the set of syzygy matrices and corresponding standard bases. In these cases, the various matrices of the resolution are indexed starting at 1: e.g. w.1, w.2, etc.

In every case except one the result matrix or matrices correspond to minimal generators of the result submodule(s). The exception is with the res command. The first matrix of the result has a standard basis computed, but the matrix is the original matrix. However, the rest of the matrices do correspond to minimal generators of their submodules.

Each of these commands is designed to work in the case where the base ring is a quotient ring.

7.1 Standard basis and syzygy computations

The following three commands are the most used standard basis commands of Macaulay.

std < matrix M > < computation >

Compute a standard (or Groebner) basis of the submodule I ⊂ R^{r} generated by the columns of the matrix M with r rows, where R is the base ring of M. If M has one row, I is the ideal of R generated by the entries of the matrix of M. In this case, the result is the usual standard, or Groebner, basis of this ideal.

To obtain the standard basis as a matrix after the computation has finished, use the putstd command. However, there are many other commands which manipulate standard bases (see Chapter 8).

A minimal set of generators for I is computed, but no change of basis matrix is computed. If one is desired (e.g. for use with the reduce or lift commands), use lift-std instead.

For example,

%  type j
; ab-c2 bc-d2 cd-e2
%  std j w
; 23.4.5.
; computation complete after degree 5
%  type w
; ab-c2 bc-d2 cd-e2
%  putstd w
; 1
; 5
; d3-be2
; cd-e2
; c3-ad2
; bc-d2
; ab-c2

The std command

nres < matrix > < computation > [max depth]

Compute a minimal free resolution of the module M presented by < matrix >. The columns of the i^{th} matrix of the result minimally generate the i^{th} syzygy module of M. A standard basis is computed for each of these syzygy modules.

If a maximum depth, d, is specified, then only the first d matrices of the resolution are computed. The default for d is the number of variables in the base ring of < matrix >. If the base ring is a polynomial ring, and not a quotient ring, then Hilbert’s syzygy theorem says that the length of the resolution is bounded by the number of variables.

For example,

%  type j
; -bc+ad -bc+ad b3-a2c c3-bd2 -ac2+b2d
%  nres j w
; 2.3...4...5...
; computation complete after degree 5
%  pres w
;
; ----------------------------------
; bc-ad b3-a2c c3-bd2 ac2-b2d
;
; ----------------------------------
; ac bd c2 b2
; -d 0  0  -c
; 0  -a -b 0
; -b c  d  -a
;
; ----------------------------------
; -c
; -b
; a
; d
;
; ----------------------------------

The nres command

Note that the columns of w.1 minimally generate the submodule corresponding to < matrix >, the columns of w.2 minimally generate the syzygies on these columns, the columns of w.3 minimally generate the syzygies on w.2, etc.

The computation proceeds degree by (slanted) degree. For more details, see section 7.4.

res < matrix > < computation > [max depth]

Compute a free resolution of the module M presented by < matrix >, such that the first matrix in the resolution is the specified matrix. The columns of the i^{th} matrix of the result minimally generate the i^{th} syzygy module of M for i ≥ 2. A standard basis is computed for each of these syzygy modules.

If a maximum depth, d, is specified, then only the first d matrices of the resolution are computed. The default for d is the number of variables in the base ring of < matrix >. If the base ring is a polynomial ring, and not a quotient ring, then Hilbert’s syzygy theorem says that the length of the resolution is bounded by the number of variables.

This command differs from nres in the following way. The columns of the first matrix of the resolution constructed using nres minimally generate the submodule corresponding to < matrix >. The first matrix of the resolution constructed using res is exactly < matrix >. Thus, res does not necessarily find a minimal resolution of M. Instead, the syzygies of the columns of < matrix > are found.

For example,

%  type j
; -bc+ad -bc+ad b3-a2c c3-bd2 -ac2+b2d
%  res j w
; 1..2..3...4...5...
; computation complete after degree 5
%  pres w
;
; ----------------------------------
; -bc+ad -bc+ad b3-a2c c3-bd2 -ac2+b2d
;
; ----------------------------------
; -1 ac bd c2 b2
; 1  0  0  0  0
; 0  d  0  0  c
; 0  0  a  b  0

; 0  -b c  d  -a
;
; ----------------------------------
; 0
; -c
; -b
; a
; d
;
; ----------------------------------

The res command

7.2 Other computation commands

These commands are more specialized than the commands of section 7.1 but are still extremely useful.

intersect < matrix1 > ... < matrix n > < result computation >

Compute the intersection

I_{1} ∩… ∩ I_{n}

of the submodules I_{j} corresponding to the given matrices. A standard basis and a minimal set of generators of this submodule are also computed.

For example,

%  type j1
; b2-ac c2-bd -bc+ad
%  type j2
; a2 b2 c2 d2
%  intersect j1 j2 w
; 0.1.2.3..4..5..
; computation complete after degree 5
%  type w
; c2d-bd2 bc2-b2d c3-ad2 ab2-a2c b3-a2d b2c-ac2 b2d2-acd2 a2c2-a2bd

%  type w.0  ;; this is the auxiliary matrix.
; 1 b2-ac c2-bd -bc+ad 0  0  0  0
; 1 0     0     0      a2 b2 c2 d2

The intersect command

The intersection is computed by creating an auxiliary matrix (w.0 in the above example) and then using the syz command to find the first component(s) of each syzygy on the columns of this matrix.

Each matrix < matrix i > must be graded, and have the same number of rows. If the resulting auxiliary matrix is not graded, then an error message is given, and < result computation > itself is set to this matrix.

lift-std < matrix > < computation >

Compute a standard basis of the submodule, I, corresponding to < matrix >, keeping enough information to remember how each standard basis element can be expressed in terms of the original columns of < matrix >. This extra information is called the ”change of basis matrix” by Macaulay. It is needed for the reduce and lift commands. The putchange command extracts this matrix from the < computation >. The resulting matrix corresponds to minimal generators of I.

For example,

%  type j
; ab-b2 a2-c2 ab2-c3
%  lift-std j w
; 2.3.4.5.
; computation complete after degree 5
%  type w
; ab-b2 a2-c2 ab2-c3
%  putstd w
; 1
; 5
; bc2-c3
; b3-c3
; ac3-c4
; ab-b2
; a2-c2

%  putchange w wc
%  type wc
; a  -b -a2+ab+ac+c2 1 0
; -b 0  ab-b2-bc     0 1
; 1  1  -a+b+c       0 0

The lift-std command

modulo < matrix > < matrix > < computation >

Compute a presentation for I +J/J, where I is the submodule generated by the columns of the first matrix, and J is the submodule generated by the columns of the second matrix.

If the row degrees for I and J are not the same, or if I or J is not graded, an error message is given.

For example,

%  type f
; a2-b2
%  type g
; a2c2-b2c2 abcd -c2+ad
%  modulo f g w
; 2.3.4..5..6..7..
; computation complete after degree 7
%  type w
; c2-ad ad
%  type w.0
; a2-b2 a2c2-b2c2 abcd -c2+ad

The modulo command

quotient < matrix M > < matrix N > < result computation >

Compute the ideal or submodule quotient (I : J), where I ⊂ R^{r} and J are the submodules generated by the columns of M and N, respectively, and R is the base ring of M and N.

There are two cases, depending on whether J is an ideal or a submodule of R^{r}. If J is an ideal, then (I : J) = {f ∈ R^{r} | fJ ⊂ I} is a submodule of R^{r}. If J ⊂ R^{r}, then (J : I) = {f ∈ R | fJ ⊂ I} is an ideal of R.

For example,

%  type m
; a b c d
; e f g h
%  type n
; 1 0
; 0 1
%  quotient m n w
; 0.1.2..3..
; computation complete after degree 3
%  type w
; de-ah df-bh dg-ch ce-ag cf-bg be-af
%  type w.0
; 1 a b c d 0 0 0 0
; 0 e f g h 0 0 0 0
; 0 0 0 0 0 a b c d
; 1 0 0 0 0 e f g h

The quotient command

The quotient is computed by creating an auxiliary matrix (w.0 in the above example) and then using the syz command to find the first component(s) of each syzygy on the columns of this matrix.

syz < matrix: M > < no. components: d > < computation: N >

Compute the (partial) syzygies on the columns of the matrix M. Recall that a syzygy on a set of column vectors f_{1},…, f_{c}, where f_{i} ∈ R^{r}, is defined to be a vector (g_{1},…, g_{c}) such that ∑ g_{i}f_{i} = 0.

This command computes (a minimal generating set for) the submodule of “partial” syzygies:

{(g_{1},…, g_{d}) ∈ R^{d} | there exists g_{d+1},…, g_{c} ∈ R s.t. ∑ g_{i}f_{i} = 0}.

The integer d is any integer expression. If d = −1, then the entire syzygy module is found. This is equivalent to “res M N 2”. If d = 0, then this command is equivalent to “std M N”.

This command is mostly used by the modulo, intersect and quotient commands, although it is occasionally useful by itself.

For example,

%  type n
; 1 a b c d
; 1 e f g h
%  syz n 1 w
; 0.1.2..
; computation complete after degree 2
%  type w
; de-ah df-bh dg-ch ce-ag cf-bg be-af

The syz command

7.3 Internal format of a computation

When any matrix is defined in Macaulay, its internal format includes the following information.

1. An array of columns, where each column is a vector of polynomials.

2. The degree of each row.

3. The degree of each column.

This information can be obtained by using the type, row-degs, and coldegs commands.

After a computation is performed using one of the computation commands, each matrix which has had a standard basis computed also contains the following information.

1. The standard basis, represented by an array of columns

2. The change of basis matrix, C, represented by an array of columns. The i^{th} column is the representation of the i^{th} standard basis element in terms of the generators of the matrix. Thus, if there are s elements in the standard basis, and r columns of the original matrix M, then C is a r by s matrix.

Not all computation commands compute a change of basis matrix. The commands which do include lift-std, res, and nres. The other computation commands do not compute this matrix. Most commands of Macaulay do not require the change of basis matrix C. The only exceptions are the reduce and lift commands. The commands res and nres compute C since this is used to calculate syzygy modules.

The following two commands either display or create a new matrix consisting of the standard basis or change of basis matrix.

putstd < standard basis > [result matrix]

Create a matrix whose columns are the given standard basis. If no second argument is provided, then display the standard basis using the same format as the putmat command.

If the first argument is a matrix without a computed standard basis, then a warning message is displayed, and the generators of the matrix are used instead.

putchange < standard basis > [result matrix]

Create a matrix corresponding to the change of basis matrix of the given standard basis. If no second argument is provided, then display the standard basis using the same format as the putmat command.

If the first argument is a matrix without a computed standard basis, or if no change of basis matrix has been computed, then create (or display) a matrix having zero columns.

7.4 Fine control of standard basis computations

Each computation command creates an internal graph which describes the operation to be performed. After constructing this graph, the Macaulay parameter “autocalc” (section 10.3) is examined. If the value is negative, the computation is instructed to run to completion. If the value is positive, the computation is instructed to proceed until it has finished the degree d part of the computation, where d is the value of the Macaulay parameter “autodegree”. If the value of “autocalc” is zero, then the computation is not started.

One can use these two parameters “autocalc” and “autodegree” to control how much computation Macaulay should do. Often, one knows that the desired result must occur in a specific degree, but that there may be a large amount of computation after this degree. In this case, this added control can be essential.

After a computation has been completed though degree d, you may continue the computation in higher degrees using the calc command. Also, if the “autocalc” parameter is set to zero, the computation can be started using calc. This command is no longer used very much in Macaulay.

7.4.1 Interrupting computations

Interrupting a calculation is very useful since intermediate results are meaningful. This is particularly important for calculations which take a long time to complete. One might be satisfied with an intermediate result and decide to terminate a computation before it runs to completion.

The interrupt feature allows the user to interrupt a calculation, examine intermediate results and eventually resume the calculation where it left off, or exit Macaulay.

To interrupt Macaulay on a Macintosh, simply click the mouse button. On all other machines, type (CNTRL)-C.

Interrupting any computation command causes the system to interrupt the computation at the next syzygy or standard basis element computed. In most cases, the user will not have to wait very long for this event to occur. After the interrupt occurs, the user receives a prompt for more input. Any legal Macaulay command can be issued here. For example, the user may want to view a resolution, write it to disk, etc. Caution: using the kill command on any variable while a calculation is interrupted is likely to cause Macaulay to crash!

To resume the calculation, use the continue command. To reset the degree at which to stop, use the chcalc command. To terminate the calculation as well as the Macaulay session, use “exit all”.

7.4.2 Feedback during computations

Certain feedback information is displayed during every computation (unless it is suppressed by using the Macaulay parameter “prlevel” (section 10.3)). Each computation proceeds degree by degree. At the start of each degree d, the number d is displayed. Each time a standard basis is started in a degree which has at least 2 elements (1 if using a quotient ring), a “.” is displayed. It is possible for numbers to be run together without any “.” between them.

If the Macaulay parameter “verbose” is set to a positive value, then more information is displayed. Each S-pair computed has one of three letters displayed: “m” means a new standard basis element has been added. “s” means a non-zero syzygy has been constructed (note that it isn’t necessarily minimal). “o” means that a zero syzygy has been constructed.

7.4.3 Controlling computation

The following three commands are used to provide finer control of computations, as described above.

calc < computation > [top degree]

Perform the computation which was constructed while the Macaulay parameter had the value zero, or perform the computation which had previously been stopped because of the value of the “autodegree” parameter.

The computation proceeds degree by degree until the “top degree” has been completed. If the optional integer is not specified, the default is positive infinity.

If you wish to change the top degree, or remove it, simply stop the computation using the interrupt mentioned above, use the chcalc command, and then restart the computation using the continue command.

chcalc < computation > [new top deg]

When issued inside an interrupted computation, this command resets the top degree of the given computation. If no argument is given, the new top degree is set to infinity. Once you continue the computation with continue, the computation will now proceed to this new top degree.

continue

Continue an interruped computation which had been stopped by using either the mouse button (on Macintosh computers) or “(CNTRL)-C” on other computers.

Operations on standard bases

In this chapter we describe various commands which operate on standard bases. These break up naturally into five distinct groups: elimination of variables, ideal (or submodule) membership, manipulations where some of the variables are treated as constants, numeric information, and saturation. At the end of this chapter we describe the commands for displaying information about finite free resolutions.

Many of the commands in this chapter simply choose an appropriate subset of either the standard basis or the leading terms of the standard basis. Others, such as hilb and reduce involve computation. In fact, the computation of the Hilbert function often takes more time than computing the standard basis!

Most of the commands of this chapter assume that their argument is a matrix which has previously had a standard basis constructed for the submodule generated by its columns. If the matrix given is not a standard basis, a warning message is given, and the columns of the matrix are used as if they formed a standard basis. This is quite useful in many cases, if you happen to know that the columns of the matrix already form a standard basis. However, one must exert some care! If these columns do not form a standard basis, the resulting answers might not answer the question which you intended to ask.

For example, if I is a 1 by n matrix whose entries generate an ideal I, then “codim I” will display a warning message, and also display a number which it claims is the codimension of this ideal. Most likely, this number is wrong: it is the codimension of the monomial ideal generated by the lead terms of the n generators of I. Usually, this is not the correct answer.

8.1 Elimination of variables

Let S be a polynomial ring, and let R be the subring generated by a subset of the variables of S. One important construction is to compute generators for I ∩ R, where I is an ideal of S: i.e. eliminate the variables not in the subring R.

Let > be any monomial order which satisfies the following property:

f ∈ R_{n} ⟺ in(f) ∈ R_{n},

where in(f) is the lead monomial of f in this monomial order. We can then compute I ∩ R via the following simple but important fact.

Proposition 4 (Elimination of variables) Let {g_{1},…, g_{r}} be a standard basis of a submodule I ⊂ S^{a} with respect to the monomial order >. Then

{g_{1},…, g_{r}} ∩ R_{n}

is a standard basis of I ∩ R_{n}.

The most important monomial orders which satisfy the above condition are the elimination and product orders defined in section 5.4. For example, let S = k[s, t, a, b, c, d], and let the monomial order > be the product order s, t >> a, b, c, d. The ring command to produce the ring with this order is

%  ring S
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  6
!   6 variables, please               ?  stabcd
! variable weights (if not all 1)     ?  1 1 3
! monomial order (if not rev. lex.)   ?  2 4
;   largest degree of a monomial        : 512 512

Let R = k[a, b, c, d] ⊂ S. We use the above proposition to compute I ∩ R for any ideal I of S. Several examples are given in Appendix A.

Macaulay stores each monomial in the above ring S as a list of three numbers: the part of the monomial in s, t, the part in the variables a, b, c, d, and finally the module component number (see section 5.4 for more details). The ring R is generated by those monomials of S whose “value” on the first “block” of variables is zero, i.e. a, b, c, d. More generally, we can define the subring generated by the variables (equivalently, monomials) whose value on the first n blocks is zero:

Definition 5 Let S be a polynomial ring defined in Macaulay. Let > be the corresponding monomial order, and let n be a positive integer. Define a subring R_{n} of S by

R_{n} = k[{x^{A} | the value of the first nblocks of x^{A} = 0}]

In the above example, R_{1} = k[a, b, c, d], and R_{2} = k. These subrings are always generated by a subset of the variables. If the monomial order has been chosen to be an elimination order or a product order, the subring of most interest is R_{1}, the subring generated by the variables whose value on the first block is zero.

This notation is used in the descriptions below.

elim < standard basis > < result matrix > [integer n]

Find the subset of the standard basis which lies in a subring. If S is the base ring of the standard basis, and R_{n} is the subring of S defined above, create a matrix whose columns are those elements of the standard basis whose lead monomials lie in R_{n}. If an integer n is not specified, the default value for n is 1.

In other words, this command finds the subset of the standard basis corresponding to the above proposition. This command is in general very useful.

For example, suppose that the ring S is the same as above: the variables are ”stabcd”, and the monomial order is the product order ”2 4”. Then

%  putstd j js
%  type js ; the entire standard basis
; c2-bd bc-ad b2-ac t3-d sd-tc sc-tb sb-ta st2-c s2t-b s3-a
%  elim j k
%  type k  ; the subset not involving s,t
; c2-bd bc-ad b2-ac

in < standard basis > [optional result matrix] [n]

Display or create a matrix of lead terms. If no optional parameters are given, display the monomial submodule of lead terms using the same format as the putmat command. If one optional parameter, the name of the resulting matrix, is specified, create the matrix of lead monomials.

If also a second optional parameter, an integer expression n, is given, create the matrix whose columns are in_{n}(g_{j}), where g_{j} is the j^{th} column of the standard basis, and in_{n}(g) is the sum of those terms of g which have the same value as the lead term of g on the first n blocks of the monomial. The default value for n is infinity. In general this is not a monomial submodule.

For example, suppose that the ring S is the same as above: the variables are ”stabcd”, and the monomial order is the product order ”2 4”. Then

in_{1}(s^{3}a + s^{3}b + s^{2}tc + t^{3}d) = s^{3}a + s^{3}b,

since both s^{3}a and s^{3}b have the same value on the first block (both have the value s^{3}). The following example uses this same order.

%  putstd j js
%  type js
; c2-bd bc-ad b2-ac t3-d sd-tc sc-tb sb-ta st2-c s2t-b s3-a
%  in js jin1 1
; warning: no standard basis. Using initial terms of matrix
%  type jin1  ; initial terms with same monomial in s,t.
; c2-bd bc-ad b2-ac t3 sd sc sb st2 s2t s3
%  in js jin2 2
; warning: no standard basis. Using initial terms of matrix
%  type jin2  ; the initial monomials
; c2 bc b2 t3 sd sc sb st2 s2t s3

Possible applications include finding tangent cones and normal cones.

keep < standard basis > < result matrix > [n]

Find the subset of the standard basis which does not lie in a subring. If S is the base ring of the standard basis, and R_{n} is the subring of S defined above, create a matrix whose columns are those elements of the standard basis whose lead monomials do not lie in R_{n}. If an integer n is not specified, the default value for n is 1.

The elements of the standard basis chosen are exactly the complement of those chosen by the elim command. For example, suppose that the ring S is the same as above: the variables are ”stabcd”, and the monomial order is the product order ”2 4”. Then

%  putstd j js
%  type js
; c2-bd bc-ad b2-ac t3-d sd-tc sc-tb sb-ta st2-c s2t-b s3-a
%  keep j k
%  type k  ; exactly the complement of the "elim" command.
; t3-d sd-tc sc-tb sb-ta st2-c s2t-b s3-a

Possible applications include finding the degree of a rational map, and finding the locus where a birational map is not one to one.

8.2 Ideal or submodule membership

The commands lift and reduce are used to determine whether the columns of a given matrix are in the submodule generated by a given standard basis. The result of the lift command is also part of the output of the reduce command. The lift command is included only for convenience.

lift < standard basis > < matrix N to lift > < result L >

Determine if each column of N belongs to the submodule M generated by the standard basis. If so, “lift” N, obtaining a matrix L satisfying N = ML. Otherwise display an error message.

For example,

%  type j
; b2-ac c2-bd -bc+ad
%  lift-std j j
; 2.3.4.
; computation complete after degree 4
%  poly f (a+b+c2)*(b2-ac)-(a3+c4)*(c2-bd)+(a3+b3)*(ad-bc)
%  lift j f f'
%  type f'
; bd+a+b
; -c4-a3+b2-ac
; a3+b3
%  mult j f' g
%  subtract f g h
%  ; f should equal g, i.e. h = 0:
%  type h
; 0

This command returns the same value L as would be returned by the reduce command. The same restrictions and caveats that apply to reduce apply here as well: a standard basis of M and a change of basis matrix from this standard basis to the columns of M must both have been computed. Otherwise either an error is generated or the matrix L will consist entirely of zeros.

reduce < standard basis M > < matrix N to reduce > < result reduced matrix R > [result lifted matrix L]

Reduce each column of N w.r.t. the standard basis M, placing each reduced column into R. Both of these matrices should have the same number of rows and the same base ring. If a matrix L is specified, then L is set to be the m by n lifted matrix where m is the number of columns of M, and n is the number of columns of N, and M, N, R, L satisfy: N = LM + R.

For example,

%  type j
; b2-ac c2-bd -bc+ad
%  lift-std j j
; 2.3.4.
; computation complete after degree 4
%  poly f a6+(a+b+c2)*(b2-ac)-(a3+c4)*(c2-bd)+(a3+b3)*(ad-bc)
%  reduce j f red lift
%  type red
; a6
%  type lift
; bd+a+b
; -c4-a3+b2-ac
; a3+b3
%  ; find g := j.lift + red
%  mult j lift g
%  add g  red g
%  subtract f g h
%  ; f should equal g, i.e. h = 0:
%  type h

Restriction: If a standard basis of M hasn’t been constructed, then an error message is given, and the reduction is not done. In order to use reduce with matrices which are not standard bases, use the forcestd command.

Important note: In order to compute L, it is necessary that a change of basis matrix from the standard basis to generators of the matrix has been computed. The commands lift-std, res, and nres compute this change of basis matrix, but no other computation command does.

forcestd < matrix M > < result standard basis > [matrix C]

Create a matrix with an attached standard basis. This command forces the columns of M to be considered as a standard basis. If a change of basis matrix C is given, it will be placed in the attached standard basis as if it were the change of basis matrix. C should be a matrix having the same base ring and the same number of columns as M. Otherwise an error message is displayed. It is legal for the matrix M to not be graded. See the example below.

Warning: This command is useful if you happen to know that the columns of M form a standard basis, but the amount of computation to verify this is huge. This command makes each column monic, since Macaulay insists that every standard basis element be monic. If a change of basis matrix is given, it is changed accordingly.

The effect of the following example is to set the variables c to be the square root of −1, and d to be the square root of 3.

%  type j
; c2+1 d2-3
%  forcestd j j
%  poly f (ac+bd)^2
%  reduce j f f'
%  type f'
; 2abcd-a2+3b2

8.3 Treating variables as constants

The commands in this section all have essentially the same form. Their input is a standard basis, together with a list of ring variables. This variable list informs Macaulay that these are the actual variables: the other variables are to be treated as if they were in the ground field.

This is mainly useful when the monomial order of the base ring R of the standard basis is a product order. Suppose that

R = k[t_{0},…, t_{m}][x_{0},…, x_{n}]

is a polynomial ring. Let > be the product order x_{0},…, x_{n} >> t_{0},…, t_{m}. The “t” variables are to be “considered as constants”. If f ∈ R is a polynomial, then we can write

f = α_{1}(t)x^{A_{1}} + β_{1}(t)x^{B_{1}} + ⋯

Notice that in the product order each monomial of α_{1}(t)x^{A_{1}} is ordered greater than every other monomial of f.

The commands in this section refer to the following notation. Let the variables in the variable list be called the “x” variables, and the other variables the “t” variables. Let {g_{1},…, g_{r}} be a standard basis for the ideal or submodule I. We can always write this standard basis as:

g_{1} = α_{1}(t)x^{A_{1}} + ⋯
g_{2} = α_{2}(t)x^{A_{2}} + ⋯
⋮
g_{r} = α_{r}(t)x^{A_{r}} + ⋯,

where each monomial of g_{i} in α_{i}(t)x^{A_{i}} occurs before each monomial of g_{i} not shown.

The default variable list, if one is not given, is always the first block of variables. Caveat: the default is not the set of all the variables.

inpart < standard basis > < result matrix > [variable list]

Find the minimally generated monomial ideal or submodule of initial forms of a standard basis, where some of the variables are considered as constants. In terms of the notation above, the result matrix is set with a minimal set of generators for the submodule {x^{A_{1}},…, x^{A_{r}}}. For example,

%  putstd j js
%  type js
; d2-3 c2+1
%  inpart js jin
; warning: no standard basis. Using initial terms of matrix
%  type jin    ; this is "1", since there were elements constant w.r.t.
s,t.

; d2 c2
%  keep js js1
; warning: no standard basis. Using initial terms of matrix
%  type js1
; d2-3 c2+1
%  inpart js1 jin1
; warning: no standard basis. Using initial terms of matrix
%  type jin1
; d2 c2

Possible applications include finding the initial monomial ideal of an ideal or submodule over a quotient field, and finding the initial monomial ideal of an inhomogeneous ideal or submodule via homogenization.

std-minimal < standard basis > < result matrix > [variable list]

Find the subset of the given standard basis whose lead monomials in a subset of the variables are minimal generators. In terms of the notation above, if x^{A_{i}} is a minimal generator of {x^{A_{1}},…, x^{A_{r}}}, then place the i^{th} standard basis element g_{i} into the result matrix. Note that several standard basis elements placed into the result matrix may correspond to the same minimal monomial x^{A}.

For example,

%  keep js js1
; warning: no standard basis. Using initial terms of matrix
%  type js1
; d2-3 c2+1
%  std-minimal js1 jmin
; warning: no standard basis. Using initial terms of matrix
%  type jmin
; d2-3 c2+1

Possible applications include finding the ramification locus of a projection, and finding loci where a projection is not flat.

stdpart < standard basis > < result matrix > [variable list]

Find a subset of a standard basis whose lead monomials in a subset of the variables minimally generate. In terms of the notation above, if x^{A_{i_{1}}} ,…, x^{A_{iq}} minimally generate the submodule {x^{A_{1}},…, x^{A_{r}}}, then the result is the matrix whose columns are g_{i_{1}},…, g_{i_{q}}.

For example,

%  keep js js1
; warning: no standard basis. Using initial terms of matrix
%  type js1
; d2-3 c2+1
%  stdpart js1 jstd
; warning: no standard basis. Using initial terms of matrix
%  type jstd
; d2-3 c2+1

Possible applications include finding a standard basis of an ideal or submodule over the quotient field generated by a set of the variables (this set is the complement of the variable list given as a parameter), and finding a minimal standard basis of an inhomogeneous ideal or submodule via homogenization.

k-basis < standard basis > < result matrix > [variable list]

Create a matrix whose columns form a k-basis for the module M presented by the given standard basis, where each variable not appearing in the variable list is considered to be a constant. You are prompted for two integer expressions, lo and hi. A k-basis for the module in degrees between lo and hi inclusive is placed into the result matrix. These always consist of monomials in the specified variable list. If <return> is entered in response to the lowest degree (resp. the highest degree), the default is negative infinity (resp. positive infinity).

For example, if the variables are “x,y,a,b,c”, the monomial order is the product order x, y >> a, b, c, and j is a standard basis, then

%  std j j
; 23.4.
; computation complete after degree 4
%  putstd j
; 1

; y2-bc
; x2-ab
%  k-basis j jk
! lowest degree (default=no lowest degree)  ? <return>
! highest degree (default=no high degree)   ? <return>
%  type jk
; 1 x xy y

If the module M does not have finite length, and no higest degree is given, a large matrix will be constructed, and an error message displayed.

truncate < standard basis > < result matrix > [variable list]

Create the matrix whose columns generate the submodule of M, M_{≥d} of all elements of M of degree at least d, where M is the module presented by the given standard basis, and d is an integer for which the user is prompted.

The result matrix consists of a k-basis of M in degree d, and the set of column unit vectors corresponding to those rows of degree at least d. Each column of the result matrix is a monomial in the variables specified in the variable list.

For example, if the variables are “abcd”, and the variables are all in one block,

%  type m
; a a2 b4
; b c2 c4
%  std m m
; 12.3.4.5.6.7.8.
; computation complete after degree 8
%  putstd m ms
%  type ms
; b4 a 0         0      0     0
; c4 b b4c2-a2c4 b5-ac4 ab-c2 a3c4-b3c4
%  truncate ms m1
! lowest degree (default=0)  ?  1
; warning: no standard basis. Using initial terms of matrix
%  type m1
; b c d 0 0 0 0

; 0 0 0 a b c d

8.4 Saturation of ideals or submodules

sat < standard basis > < result matrix > < variable > [max power d]

Divide each column of the standard basis by the specified ring variable as many times as possible, or as much as d times, if d is given on the command line. The highest power divided by is then displayed.

This command is most useful in conjunction with the reverse lexicographic order, where the ring variable is the least variable in the order.

For example, if the variables are ”abct”, and the monomial order is the reverse lexicographic order, then

%  putstd j k
%  type k
; b2t-act ab-ct a2-bt
%  sat j jsat t
; largest division was by t
%  type jsat
; b2-ac ab-ct a2-bt

Possible applications include finding ideal quotients using the reverse lex. order with the given ring variable being the least variable in the order.

8.5 Computing numerical information

The commands below take a standard basis, perform some combinatorics on the initial monomial ideal or submodule, and produce numerical information. In each case, it does not matter which monomial order was used to produce the standard basis. What does matter is that the matrix be a standard basis. If no standard basis is present, the generators of the matrix itself are used, and a warning message is displayed. In this case the user must be sure that the matrix forms a standard basis.

hilb < standard basis >

Computes the Hilbert series of the module M presented by the given standard basis. By the theory of standard (Gröbner) bases, the Hilbert series of the module generated by the columns of the standard basis is the same as the Hilbert series of the monomial submodule of lead monomials of each column of the standard basis. Define the Hilbert series of a graded module M by:

Definition 6 (Hilbert series) Let M be a graded module over k[x_{1},…, x_{n}]. The Hilbert series of M is the power series

H_{M}(t) = ∑_{i=−∞}^{∞} dim M_{i} t^{i}.

It turns out that H_{M}(t) can be written in two useful ways: First, H_{M}(t) = Q(t)/(1−t)^{n}, where Q(t) is a polynomial in t, and n is the number of variables in the polynomial ring. Q(t) is intimately linked with the graded betti numbers of the module M. Second, H_{M}(t) = P (t)/(1−t)^{dim(M)}, where P (t) is a polynomial, and deg M = P (1).

The output of hilb is

1. the polynomial Q(t),

2. the polynomial P (t),

3. the codimension of M, i.e. n − dim M,

4. the degree of M, i.e. P (1),

5. the (sectional) genus of M. If dim M = 2, this is the arithmetic genus of M.

Some notes:

1. The ring variables must all have weight 1, or the results mean very little.

2. By using interrupts (see section 7.4), it is possible to stop a Hilbert series computation. It is not possible to then restart it, except at the beginning.

3. If the Macaulay parameter “verbose” is set to true, then some feedback is given. Each time a new generator is considered, a “.” is displayed. Bear in mind that the process is not linear! The worst case is for each new element to take about twice as long as the last one (roughly). Usually, the process works nicely for less than 200 or so standard basis elements, and for more than 1000 generators it almost never works (at least in 30 or 40 variables). If you just need the codimension or degree, use the two commands below, since they work well on any (I think!) number of generators.

For example, for the rational quartic curve, j, in P^{3},

%  putstd j
; 1
; 4
; c3-bd2
; bc-ad
; b3-a2c
; ac2-b2d
%  hilb j
;       1 t  0
;      -1 t  2
;      -3 t  3
;       4 t  4
;      -1 t  5
;       1 t  0
;       2 t  1
;       2 t  2
;      -1 t  3
; codimension = 2
; degree      = 4
; genus       = 0

In this example, Q(t) = 1 − t^{2} − 3t^{3} + 4t^{4} − t^{5}, and P (t) = 1 + 2t + 2t^{2} − t^{3}.

codim < standard basis > [integer result]

Set the result integer, if given, to the codimension of the module M presented by the given standard basis. If an integer is not specified, then display the codimension.

The codimension of M presented by the standard basis is the same as the codimension of the submodule of initial monomials in the standard basis. Given this monomial submodule, the codimension is computed by finding a minimal set of variables which form an associated prime for the submodule.

The weights of the variables can be arbitrary, and the module M doesn’t even need to be graded. This command works well even for very large standard bases (several thousand elements in the standard basis).

For example, if j is the rational quartic curve in P^{3},

%  type j
; bc-ad b3-a2c c3-bd2 ac2-b2d

%  codim j
; codimension : 2

If the Macaulay parameter “verbose” is set to a positive value, then each associated prime having minimal codimension (so far) is displayed as a vector: if the i^{th} value is set to one, the i^{th} variable is in the associated prime.

degree < standard basis > [integer codim] [int degree]

Set the first integer, if given, to the codimension of the graded module M presented by the standard basis. Set the second integer, if given, to the degree of the module M. If either one or both of these integers are not specified, display the corresponding information.

The degree of M is the same as the degree of the submodule of initial monomials in the standard basis. Given this monomial submodule, the degree is computed by finding every set of variables of minimal length which form an associated prime for the submodule, and then finding the degrees of these components.

For example, if j is the rational quartic curve in P^{3},

%  type j
; bc-ad b3-a2c c3-bd2 ac2-b2d
%  degree j
; codimension : 2
; degree      : 4

Restrictions: The weight of each ring variable is assumed to be one.

If the Macaulay parameter “verbose” is set to a positive value, then the running sum of the degrees of each associated prime of minimal codimension is displayed. These eventually sum to the resulting degree.

8.6 Displaying Information about Resolutions

The commands betti, numinfo, and pres display information about a set of matrices. Usually, this is the set of matrices which occur as the result of a res or nres calculation, but one can apply these commands to a single matrix as well.

betti < complex >

Display the graded betti numbers of a set of matrices. The main use is to display the graded betti numbers of a resolution produced via res or nres.

For example, if j is the ideal of the rational quartic curve in P^{3}, then

%  type j
; bc-ad b3-a2c c3-bd2 ac2-b2d
%  nres j jr
; 2.3...4...5...
; computation complete after degree 5
%  betti jr
; total:      1     4     4     1
; --------------------------------
;     0:      1     -     -     -
;     1:      -     1     -     -
;     2:      -     3     4     1

This should be read as follows. From the line starting with “1:”, the ideal has one generator in degree 2, and three generators of degree 3. The degree of an entry is the sum of the degree “d:” and i, where i is the column (starting at 0, from the left). Thus, there are 4 first syzygies, all in degree 4 = 2 + 2, and one 2^{nd} syzygies in degree 5.

Finally, notice that the “regularity” (see [?]) of the module presented by the first matrix is m, where m is the largest index “d:” which occurs. In the above example, the regularity is 2.

numinfo < complex >

Display numeric information about a set of matrices. Usually < complex > is the result of a res or nres command, but it may also be a matrix.

For example, if j is the ideal of the rational quartic curve in P^{3}, then

%  type j
; bc-ad b3-a2c c3-bd2 ac2-b2d
%  nres j jr
; 2.3...4...5...
; computation complete after degree 5
%  numinfo jr
; name    #rows #cols #standard  degrees

; 1       1     4     4          2 3:3
; 2       4     4     9          4:4
; 3       4     1     1          5

For each matrix the following information is displayed: its index, number of rows and columns, number of standard basis elements (if any), and the degree of each column of the matrix.

pres < complex >

Displays each matrix in < complex >. If < complex > is the result of res or nres, then each column of the i^{th} matrix is a syzygy of the columns of the (i − 1)^{st} matrix.

For example, the finite free resolution of the ideal of the rational quartic curve in P^{3} is

%  pres jr
;
; ----------------------------------
; bc-ad b3-a2c c3-bd2 ac2-b2d
;
; ----------------------------------
; ac bd c2 b2
; -d 0  0  -c
; 0  -a -b 0
; -b c  d  -a
;
; ----------------------------------
; -c
; -b
; a
; d
;
; ----------------------------------

Ring maps

Ring maps are used in Macaulay to change or specialize the value of various variables, to change the monomial order used, to add new variables, etc. Ring maps are represented in Macaulay as matrices with one row. One creates a general ring map either with rmap, or by using the various matrix operations. For special types of ring maps, i.e. ring inclusions or projections, one can use imap to define such a ring map, or one can implicitly use such a ring map with the command fetch. The most important command is ev, which performs the evaluation of a matrix with respect to a ring map.

9.1 Introduction to ring maps

A ring map is a map (homomorphism) between two polynomial rings, f : R → S. If the ring R has n variables, then a ring map f is completely determined by the image f_{i} of each variable x_{i} of R. In Macaulay, a ring map from any ring R to a ring S is given as a 1 by n matrix f whose base ring is S. Since ring maps are represented as matrices in Macaulay, any matrix operation can be used to create a ring map. For an example of a ring map, see the rmap command below.

One can also use the commands rmap and imap to create ring maps. rmap is used to create a general ring map, while imap is used to create an “identity” map: map each variable of R to the variable with the same name in S. The command edit-map allows you to modify an existing ring map. The command ev allows you to evaluate the image of a matrix under a specified ring map. The command fetch is used to map a matrix to a new ring using an “identity” map as above. Finally, the pmap command displays a ring map.

Whenever a ring is expected as a parameter and a matrix is given, the ring used is the base ring of the specified matrix. This actually holds more generally thoughout Macaulay: whenever a ring is expected, any user defined variable with the same base ring can be used.

As always in Macaulay, either ring R or S can be a quotient ring (see section 5.3).

This set of commands has many uses, including: dehomogenizing an ideal or matrix, changing to generic coordinates, changing the monomial order and adding new variables.

9.2 Commands for defining and using ring maps

The commands for manipulating ring maps are described in this section. The examples all assume that the following rings R, S, and T, have been defined:

%  pring R
; ring R
; characteristic           : 31991
; number of variables      : 4
; variables                : abcd
; weights                  : 1 1 1 1
; monomial order           : 4 c
; top degree of a monomial : 512
%  pring S
; ring S
; characteristic           : 31991
; number of variables      : 3
; variables                : xyz
; weights                  : 1 1 1
; monomial order           : 3 c
; top degree of a monomial : 512
%  pring T
; ring T
; characteristic           : 31991
; number of variables      : 3
; variables                : abx
; weights                  : 1 1 1
; monomial order           : 3 c
; top degree of a monomial : 512

R has four variables {a, b, c, d}, S has three variables {x, y, z}, and T has variables {a, b, x}.

rmap < result f > < ring R > < ring S >

Interactively define a map of rings f : R → S. A map of rings from R to S is simply a 1 by n matrix with base ring S, where n is the number of variables of R. The i^{th} variable of R is mapped to the polynomial which is the i^{th} column of this matrix. The command ev is used to evaluate a ring map on a matrix.

For example,

%  rmap f R S
! a ---> ?  x5
! b ---> ?  x4y+x3z2
! c ---> ?  y5
! d ---> ?  z5+y3x2
%  type f
; x5 x4y+x3z2 y5 x2y3+z5
%  pmap f R
; map : R ---> S
; a |--> x5
; b |--> x4y+x3z2
; c |--> y5
; d |--> x2y3+z5

Notice that pmap displays the ring map as a map. The result f is a 1 by 4 matrix over the ring S. The main utility of the rmap command is that you are prompted for the value of each variable. Thus, you don’t need to remember the order of the variables of R.

imap < result ring map: f > < ring R > < ring S > [1]

Create a new ring map (i.e. a 1 by n matrix in the ring R) whose effect is to map each variable of R to the variable of the same name in S. If there is no such variable in S, then it is mapped to zero. If a forth argument, “1”, is present, then the variable is mapped to one rather than zero.

You are prompted to change this map by giving “variable, new image” pairs, as in the edit-map command below. Typing <return> means don’t modify the ring map.

In the following example, the variable x is sent to zero under f, since x is not a variable in the ring R (R and T are defined at the beginning of this section).

%  imap f T R
! variable, new image ? <return>

%  type f
; a b 0
%  pmap f T
; map : T ---> R
; a |--> a
; b |--> b
; x |--> 0

edit-map < ideal f > [source ring S]

Modify a 1 by n matrix f representing a ring map from S to the base ring of f. You are prompted for “variable, new image” pairs. The first argument should be a ring indeterminate in the source ring S (the base ring of f is the default if no ring is specified). The second argument should be a polynomial expression in the base ring of f. The corresponding entry of f is changed to the new value.

The two arguments are separated by spaces, and to quit modifying the ring map, type <return>.

For example,

%  pmap f S
; map : S ---> R
; x |--> ab
; y |--> cd
; z |--> a+b+c+d
%  edit-map f S
! variable, new image ?  x (a+b)^3
! variable, new image ? <return>
%  pmap f S
; map : S ---> R
; x |--> a3+3a2b+3ab2+b3
; y |--> cd
; z |--> a+b+c+d

ev < ideal f > < matrix M > < result matrix N >

Find the image of a matrix under a polynomial ring map. Evaluate the matrix M under the ring map corresponding to the 1 by n matrix f from R, the base ring of M, to S, the base ring of f. The i^{th} variable of R is mapped to the i^{th} entry of f.

If f has fewer columns than the number of variables of R, then the remaining variables of R are mapped to zero. If the number of columns is too large, the remaining columns are ignored.

For example,

%  pmap f R   ; the base ring of f is S.
; map : R ---> S
; a |--> x+y
; b |--> x-y
; c |--> y
; d |--> z+1
%  type m     ; the base ring of m is R.
; a   a2
; b+c ab+d2
%  ev f m n
%  type n     ; the base ring of n is S.
; x+y x2+2xy+y2
; x   x2-y2+z2+2z+1

fetch < matrix M > < result matrix N > [1]

Create a new matrix, N over the current ring which is essentially the matrix M: each variable in the base ring of M which also occurs in the current ring is left unchanged, and each variable which doesn’t occur is set to zero by default (or one, if the optional third argument is given).

This command is useful for changing monomial orders, inclusion of one ring in another, or projection of one ring to another.

The following example “fetch”s the matrix m from the ring R to the ring S.

%  type m     ; the base ring of m is R.
; a   a2
; b+c ab+d2
%  ; make sure the current ring is S, which has vars a,b,c
%  setring S
%  fetch m n
%  type n     ; the variable "d" is set to 0.
; a   a2

; b+c ab

pmap < ideal f > [source ring S]

Display the ring map corrresponding to the 1 by n matrix f, from the ring S to the base ring of f. If no source ring is specified, the current ring is used.

For examples, see the various ring map commands above.

System commands

This chapter describes the system support commands available in Macaulay.

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 ”exit all” in order to exit. Use the continue command to continue an interrupted computation.

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.

version

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

%  version
; version 3.0, created 5/18/89 DAB,MES

10.1 Finding help about Macaulay

commands

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

%  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

help

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

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

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.

help < topic >

Display a small description of < topic >.

help-file < file name >

Display some documentation for the script file < 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 Appendix ??.

10.2 Recording a Macaulay session

monitor < file name >

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

endmon

This command turns off the recording which was started with the monitor command. Leaving Macaulay also turns off recording.

10.3 Macaulay parameters

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 set and incr-set commands.

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.

autocalc This integer flag, if not equal to zero, instructs the computation commands (std, lift-std, res, nres, syz, intersect, modulo, and 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.

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.

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.

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.

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.

maxdegree This integer value describes the maximum degree of a monomial in a ring. In the 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.

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

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.

prlevel This integer flag, if larger than zero, instructs the system to suppress all output to the user’s screen. This is very useful for having certain commands work quietly. Beware though, that 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 prlevel and the last line decrements it, using the 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 “set prlevel 1”, or “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.

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

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.

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 Chapter 7), reduce, lift, hilb, codim, degree, wedge, hulb and hull. The exact information displayed is described with the particular command. The default value is 0.

The commands for manipulating these parameters are the following.

set

Display the current setting of all the above Macaulay parameters.

set < variable >

Resets the < variable > to it’s default value.

set < variable > < integer >

Set the < variable > to the value of the given integer expression.

set default

Reset every Macaulay variable to it’s default value.

incr-set < variable > < integer >

Increment the given Macaulay parameter by the specified integer expression.

set-value < variable > < 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.

10.4 Space Utilization

space

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

%  space
  378K  total memory requested by allocator
   19K  of requested memory not yet used

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 space command was done after computing a finite free resolution of the ideal generated by the variables in a polynomial ring with 10 variables.

%  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

The most important information present is the amount of memory allocated by Macaulay. This information is displayed by using “space”. In the above example, this is 378K. Other useful facts that one can determine from the above table:

1. The number of monomials actually being used in the one ring which is defined is 11,272. Each monomial has size exactly 14 bytes.

2. 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.

3. The monomial table stashes are used for fast lookup of monomials during the computation of standard bases.

4. 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.

size < 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,

%  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

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.

spairs < matrix >

This command displays the number of S-pairs yet to be computed in each degree, if a standard basis of < 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.

10.5 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 (CNTRL)-C.

Each of the computation commands (see Chapter 7) can be interrupted and then restarted using the continue command. The commands type, hilb, wedge, reduce and 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.

calc Interrupting this command temporarily pauses the computation, and the user can use all the Macaulay commands desired, before restarting the computation with the continue command (see Chapter 7).

type Interrupting the type command stops displaying the current matrix.

hilb Interrupting hilb simply stops the computation of the Hilbert function. No partial results exist to display.

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. reduce,lift This command when interrupted returns the partially constructed

results. Again, there is no way to continue this computation after the interrupt.

10.6 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” >myfile, where myfile is the name of the file that Macaulay will use. The spacing is important; there cannot be a space after the >. For example,

%  pres j >j.res

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 putmat command. This file can be read by redirecting the input file. This is done in the same way as above, but using “<” instead of “>”. For example,

%  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

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 Chapter ??.

Command Files

11.1 Running scripts

Macaulay is capable of receiving its input from either the keyboard or from a text file, which we shall call a script. When Macaulay starts up, it expects its input from the keyboard. (This is called standard input in Unix circles; you can make Macaulay start instead from a text file named “script” from Unix by typing “Macaulay <script” to start Macaulay, but we shall assume that you have just typed “Macaulay” to start Macaulay.) We call the initial source of Macaulay’s input “voice 0”. Inside a Macaulay session, you can cause Macaulay to switch over to reading from a text file named “file” by entering “<script”. When you do this, Macaulay calls this new input source “voice 1”, and it keeps track of what voice 0 was so it can go back to it after voice 1 ends. A voice ends either when Macaulay encounters a dollar sign $, or when the file itself ends. If voice 0 ends, Macaulay quits.

This process can be iterated many times; you can tell Macaulay to take its input from a file, which later tells Macaulay to take its input from a second file. When voice 2 ends, Macaulay goes back to voice 1 (which may later start another voice 2, etc.), and when voice 1 ends, Macaulay returns to voice 0, the same state in which it started. There is a rather large limit to the number of possible input voices which Macaulay can stack up at any one time; we’d love to hear from you if you bump into it.

If Macaulay is in a voice > 0, you can tell what this current voice is by Macaulay’s prompt characters: type n%, where n is the voice number. When you interrupt a computation, Macaulay creates a new voice to take input from the keyboard (your scripts are still there, waiting for the suspended computation to finish). In this case, the prompt indicates that a previous environment is suspended, and that an inner environment now also exists. For example, the prompt “2% 3%” indicates that a computation initiated by voice 2 is suspended, and that voice 3 now controls Macaulay.

11.2 Creating scripts

This script capability makes it possible to write and run programs written in Macaulay’s command language. In its simplest form, you can save a sequence of Macaulay commands to a script file, and then later call that script file, rather than retyping the commands each time you need them. To this end, Macaulay provides a facility for saving commands to a script file as you enter them, so that you can enter them again later by simply calling the file: To create a script called “script” from within Macaulay, enter “>>script”. This creates a new input voice, with the property that Macaulay is still listening to your keyboard, but everything that you type is both used as input by Macaulay and saved to “script”. To end this process, type a dollar sign $. You will return to your earlier voice, and the file named “script” will now be complete. To use it later, enter “<script” to call the script.

Of course, you can use your favorite text editor to write a script, when you are not running Macaulay, and then use this script later from within Macaulay. This has the disadvantages that you don’t get to see what happens in an example, as you plan the sequence of commands, and that you may have trouble remembering exactly what information Macaulay wants when. Nevertheless, some people prefer this style of writing scripts; it probably reminds them of their childhoods, bringing decks of punched cards over to a mainframe to find the next bug in their program. We recommend that you create scripts from within Macaulay, and then revise them using an editor, until you are an expert user.

11.3 Tour mode

If you want to see a script run slowly, pausing at each line, enter “<<script” rather than “<script”. We call this “tour” mode, because a long time ago the on-line documentation for Macaulay consisted mainly of three meager tours which one ran in this fashion. It is a good way to study someone else’s script, or to debug your own script. What Macaulay does in this mode is act like a player piano: it types each line of input taken from the script, and then waits for you to type <return>(“enter” in MPW) before going on.

If you want to interrupt a script which is running in tour mode, you can. Type an ampersand & before ending the line for Macaulay, and Macaulay will create a new input voice AFTER executing the line that you just ended. In this new input voice, Macaulay takes its input from the keyboard; when you end it by a dollar sign $, Macaulay returns to the script in tour mode.

If you want to complete the script, but turn back off the tour mode, type an exclamation ! to end a line. Macaulay will then continue to read the script, without pausing for you. If instead you want to end the script early, type a dollar sign $. This works to end the voice, as always.

Tour mode is hereditary; if a script which you are playing in tour mode calls another script, that script will also be run in tour mode. If this isn’t your intention, you can type ! to speed through this inner script. When it finishes, you will be back in the previous script, still in tour mode.

The interactions between scripts in tour mode may seem complicated at first, but all follow from the above rules. You should experiment around, thinking of &, $, and ! as your clutch, brakes, and gas pedals, and you will get the hang of it.

11.4 Passing parameters to scripts

It is possible to have a script use different names for Macaulay objects, each time you call it. If you call a script by the sequence “<script aa bbb c”, then Macaulay will substitute the strings “aa”, “bbb”, and “c” anyplace in the text of “script” that it finds the strings #1, #2, and #3. In addition, #0 stands for the number of arguments used when the script is called (in this case, 3). More generally, any valid Macaulay expression that produces an integer can be used in place of #1, #2, #3 (#0 can only be the digit 0). The expression will be read up to the next blank character, to figure out which integer you mean, unless it begins with a digit, or a parenthesis “(“. A leading digit is used by itself, and a parenthesis are read until the matching parenthesis is found. Thus if i has value 3, then in our example, “a#19 b#(i)b” will be translated to “aa9 bcb”. In particular, numbers greater than 9 must always be parenthesized, as in #(19). There is a rather large limit to the number of possible input parameters which Macaulay can handle at any one time; we’d love to hear from you if you bump into it.

Macaulay’s parameter passing scheme is best understood if you realize that the core of the program has no idea that all this stuff is happening; all of the effects described here are handled by a single preprocessing routine that hands lines of input to Macaulay as if you typed them. In particular, all Macaulay variables are accessible at all times; there is no internal concept of local variables, since the inner depths of Macaulay have no idea when the voice changes. This can be a real pain if several of your scripts use the same variable name in conflicting ways.

To avoid this problem, we created a way for scripts to uniquely name their temporary variables: the character @ is translated to @nn@, where “nn” is the current voice level. Thus if a script running as voice 1 uses a temporary name i@, and it calls a script which also uses a variable i@, then the two names will read as i@01@ and i@02@. These variables are not automatically erased, but if later a new script running as voice 2 uses i@, it will write over the old i@02@ (which is OK with us if it’s OK with you).

There are two exceptions to the automatic expansion of @: Macaulay recognizes something that looks like it is already expanded, and doesn’t reexpand it (so i@01@ doesn’t become i@01@01@01@), and when the input voice is from the keyboard, Macaulay assumes that you mean the closest voice associated with a script (so i@ becomes i@01@ in voice 0, and i@02@ in voice 3, for example.) This is handy when debugging.

If a script needs to use a name which isn’t intended to be temporary, it should be passed as a parameter to the script, to avoid name conflicts. If a script needs to use a name which is intended to be temporary, it should kill the variable after it is done with it, in case space usage becomes a problem.

If you want to create scripts interactively which use parameters, then pass parameters to the script as you create it: Enter “>>script dd eee f” to use “dd”, “eee”, and “f” as example names. While recording this script, you must use #1, #2, and #3 to refer to these parameters if you want your commands to change whene the parameters change. If you use “dd”, “eee”, and “f” while writing your script, it will be hard-wired to use these names, even if it is later called via the sequence “<script aa bbb c”.

11.5 Silence is sometimes golden

If you build up a collection of scripts which call scripts which call scripts, you’ll probably get sick of watching every line go by. Moreover, in many cases it actually takes Macaulay longer to get the results up on the screen than to think them up. By the command “incr-set prlevel 1” at the beginning of a sequence of commands, and “incr-set prlevel -1” at the end, you can normally hide from your sight everything that happens in between, and speed up the process to boot. Many people like to do this at the beginning and end of all of their scripts, so that their scripts run almost like built-in Macaulay commands.

Exceptions: Error messages will still be printed. What you have actually done is to increment and decrement a Macaulay set variable which starts out with value 0, and which inhibits output to the screen whenever it is positive. Thus, if you first enter “set prlevel -3” then your first three voices of “silent” scripts will show their output after all, and any higher voice silent scripts will in fact run silently.

11.6 If statements and jumps

Macaulay provides some rudimentary “control flow” for jumping around in scripts. These commands basically tell the preprocessor which handles scripts to start reading the scripts in different places. In other words, Macaulay scripts are interpretted, not compiled. This is not a serious speed disadvantage for two reasons. First, most of the time is spend actually computing things like standard bases and free resolutions, not figuring out what commands mean. Second, it usually takes the host computer’s operating system far longer to find scripts as they are called, than it takes Macaulay to scan an entire script once found. Thus jumps within a script are faster that calls to other scripts, which is itself faster than the actual computations.

Macaulay jumps around in scripts using labels. A label is anything at the beginning of a line (ignoring leading white space) up to a colon “:”. Labels are ignored by Macaulay for all purposes besides if statments and jumps. When Macaulay is directed by an if statement or a jump to continue reading input from a label, it starts scanning the script file from the beginning, until it finds the label. It begins executing statements on the line of the label, or on the next line if the label is on a line of its own.

A jump statement takes the form “jump label”, and sends Macaulay careening off in search of this label. An if statement takes the form “if condition label” or “if condition label label2”. In the first form, Macaulay jumps to “label:” if the condition is true. In the second form, Macaulay jumps instead to “label2:” (rather than just continuing on from where it was) if the condition is false.

11.7 Summary

Together, these facilities allow for a fairly high degree of automation of the process of directing commands to Macaulay’s innards. This ain’t Lisp we’re talking about here (As Popeye says, I yam what I yam), but many novice computer users actually prefer the simplicity of our environment. If you can think of simple additions to the above constructs that would greatly increase the flexibility or power of Macaulay scripts, please suggest them to us.

Appendix A

Examples

A.1 The rational quartic in P3

Let f : P^{r} → P^{n} be a polynomial map. We wish to compute the equations in P^{n} defining the image of this map. Let f(x_{0},…, x_{r}) = (f_{0}(x),…, f_{n}(x)), where x = x_{0},…, x_{r}.

The ideal I of the image of f consists of the polynomial relations on the polynomials f_{0},…, f_{n}, and therefore

I = (y_{0} − f_{0}(x),…, y_{n} − f_{n}(x)) ∩ k[y_{0},…, y_{n}].

We simply need to eliminate the variables x_{0},…, x_{r} from the ideal J = (y_{0} − f_{0}(x),…, y_{n} − f_{n}(x)).

In Macaulay this is accomplished by first defining a ring containing both the “x” and “y” variables, and choosing either the elimination or product order which orders the “x” variables before the “y” variables. After computing a standard basis, we use the elim command to obtain the final answer.

In the example below we apply this technique to determine the ideal of the rational quartic curve in P^{3}. This is defined to be the image of the polynomial map f(s, t) = (s^{4}, s^{3}t, st^{3}, t^{4}) in P^{3}.

The following remarks refer to the Macaulay session below.

1. All polynomials of J must be homogeneous (or quasi-homogeneous). This will be the case if we set the weight of each variable a, b, c, d to be four, and the weight of s and t to be one, by using the ring command. Notice that the last “4” is replicated so that every variable a, b, c, d has weight 4.

2. In this example we have chosen the product order by responding with “2 4” when asked for the monomial order.

3. Before defining the ring S, the matrix k contains the equations of the rational quartic which is the desired result. However, this ring has the extra variables s and t, and the weight of the variables a,…, d is four. We define a “cleaner” ring S and then use the ring map command fetch to put the matrix k in this simpler ring. Next we compute its finite free resolution.

%  ;; Finding the image of the polynomial map (s4, s3t, st3, t4), and
%  ;; its finite free resolution.
%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  6
!   6 variables, please               ?  sta-d
! variable weights (if not all 1)     ?  1 1 4
! monomial order (if not rev. lex.)   ?  2 4
;   largest degree of a monomial        : 512 512
%  ideal j
! number of generators ?  4
! (1,1) ?  a-s4
! (1,2) ?  b-s3t
! (1,3) ?  c-st3
! (1,4) ?  d-t4
%  type j
; -s4+a -s3t+b -st3+c -t4+d
%  std j j
; 45.6.7.8.9.10.11.12.13.14.15.16.
; computation complete after degree 16
%  elim j k
[126k]
%  type k
; c3-bd2 bc-ad b3-a2c ac2-b2d
%  ; put this ideal into a ring with only variables a,b,c,d all
%  ; having weight one.
%  ring S
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  4
!   4 variables, please               ?  a-d
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ? <return>
;   largest degree of a monomial        : 512

%  fetch k k
%  ; at this point the base ring of "k" is "S".
%  ; find the minimal finite free resolution of "k"
%  nres k kres
; 2.3...4...5...
; computation complete after degree 5
%  pres kres  ; and display it
;
; ----------------------------------
; bc-ad c3-bd2 b3-a2c ac2-b2d
;
; ----------------------------------
; ac bd b2 c2
; 0  -a 0  -b
; -d 0  -c 0
; -b c  -a d
;
; ----------------------------------
; -c
; -b
; d
; a
;
; ----------------------------------

A.2 An elliptic curve on the Veronese in P^{5}

Let f : P^{r} → P^{n} be a polynomial map. It is useful to compute the image of a subvariety X ⊂ P^{r}, rather than P^{n}. The technique in the previous example is easily modified to handle this case.

Let I_{X} be the ideal defining the variety X. The ideal defining the image of X in P^{n} is

I = (y_{0} − f_{0}(x),…, y_{n} − f_{n}(x), I_{X}) ∩ k[y_{0},…, y_{n}].

This is computed exactly as in the example above.

A.2. AN ELLIPTIC CURVE ON THE VERONESE IN P^{5} 109

In this example, we find the image of the nonsingular cubic curve y^{2}z = x^{3} −xz^{2} under the Veronese map to P^{5}: (x^{2}, xy, xzy^{2}, yz, z^{2}). After placing the result into a “clean” ring S, we compute its standard basis and find its Hilbert function.

The following remarks refer to the Macaulay session below.

1. As in the previous example, we create a ring with variables x, y, z of weight one, and variables a, b, c, d, e, f of weight two. We choose the product order “3 6” which has the effect of eliminating the variables x, y, z.

2. The Hilbert series of the result is

H_{S/I}(t) = \frac{1 − 9t^{2} + 16t^{3} − 9t^{4} + t^{6}}{(1 − t)^{6}} = \frac{1 + 4t + t^{2}}{(1 − t)^{2}} .

The curve has degree 6 and genus 1, as expected.

%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  9
!   9 variables, please               ?  xyza-f
! variable weights (if not all 1)     ?  1 1 1 2
! monomial order (if not rev. lex.)   ?  3 6
[189k];   largest degree of a monomial        : 512 235
%  ideal J
! number of generators ?  7
! (1,1) ?  a-x2
! (1,2) ?  b-xy
! (1,3) ?  c-xz
! (1,4) ?  d-y2
! (1,5) ?  e-yz
! (1,6) ?  f-z2
! (1,7) ?  y2z-x3-xz2
%  ; now compute a standard basis, and then eliminate
%  std J J
; 23.4.5.6.7.8.
; computation complete after degree 8
%  elim J I
%  type I
; e2-df ce-bf cd-be c2-af bc-ae b2-ad ac+cf-df ab-de+bf a2-be+af

%  ; now move I to a cleaner ring
%  ring S
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  6
!   6 variables, please               ?  a-f
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ? <return>
;   largest degree of a monomial        : 117
%  fetch I I
%  ; the base ring of I is now S.
%  ; Compute a standard basis and the Hilbert series of S/I
%  std I I
; 23.4.
; computation complete after degree 4
%  hilb I
;       1 t  0
;      -9 t  2
;      16 t  3
;      -9 t  4
;       1 t  6
;       1 t  0
;       4 t  1
;       1 t  2
; codimension = 4
; degree      = 6
; genus       = 1

A.3 The tangent developable of a rational normal curve

In this example, we find the equations of the tangent developable to the rational normal curve in P^{6}. Recall that the rational normal curve is given by the image of the polynomial map f(s, t) = (s^{6}, s^{5}t,…, t^{6}), and that the tangent developable is the union of all the tangent lines of the curve.

A.3. THE TANGENT DEVELOPABLE OF A RATIONAL NORMAL CURVE111

The tangent line at the image point f(s_{0}, t_{0}) is given parametrically by

T (s_{0}, t_{0})(x, y) = ∂f/∂s(s_{0}, t_{0})x + ∂f/∂t(s_{0}, t_{0})y.

Thus the tangent developable is given parametrically by

T (s, t, x, y) = ∂f/∂s(s, t)x + ∂f/∂t(s, t)y.

In order to find the equations of the image we just embed using this map. The following remarks refer to the Macaulay example below.

1. The variables of P^{6} used in this example are a, b, c, d, e, f, g. Each polynomial of the map T has degree 6 in the variables x, y, s, t, and so we set the weight of each variable a,…, g to be 6.

2. The next several commands compute the map T without having to write down the equations directly. The cat command provides a handy way to write down matrices of indeterminates.

3. We construct the polynomial map f by using the power command. This is simpler than typing in all the degree 6 monomials directly. More importantly, changing this example to compute the tangent developable in P^{n}, for some other n becomes a much easier task.

4. It turns out that the ideal of the tangent developable is generated by degree 2 polynomials in a,…, g. In the ring R, these polynomials have degree 12. We use the Macaulay parameters “autocalc” and “autodegree” to change the highest degree to which Macaulay will compute. After we are done with the standard basis, we set “autocalc” back to its previous value. Otherwise all subsequent computations will be done only to degree 12!

5. Finally, using the elim command we obtain the ideal of the tangent developable. We then place this ideal into a cleaner ring, and the compute its minimal finite free resolution. The betti command is used to display concisely the graded betti numbers of the resolution.

%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  11
!  11 variables, please               ?  stxya-g
! variable weights (if not all 1)     ?  1:4 6
! monomial order (if not rev. lex.)   ?  4 6
[252k];   largest degree of a monomial        : 512 512 512
%  ; create 3 ideals (s,t), (x,y), and (a,b,c,d,e,f,g).
%  cat s st

112 APPENDIX A. EXAMPLES

! rows ?  0
! columns ?  0 1
%  cat x xy
! rows ?  0
! columns ?  0 1
%  cat a ag
! rows ?  0
! columns ?  0..6
%  ; compute the polynomial map T
%  power st 6 f
%  type f
; s6 s5t s4t2 s3t3 s2t4 st5 t6
%  jacob f Df s t
%  transpose Df Df
%  mult xy Df T
%  type T
; 6s5x 5s4tx+s5y 4s3t2x+2s4ty 3s2t3x+3s3t2y 2st4x+4s2t3y
; t5x+5st4y 6t5y
%  ; compute the ideal, T1, to eliminate.  Compute a standard basis
and
%  ; perform the elimination.
%  subtract ag T T1
%  type T1
; -6s5x+a -5s4tx-s5y+b -4s3t2x-2s4ty+c -3s2t3x-3s3t2y+d
; -2st4x-4s2t3y+e -t5x-5st4y+f -6t5y+g
%  set autocalc 1    ; see above remark
%  set autodegree 12 ; see above remark
%  std T1 T1
; 67.8.9.10.11.12.

%  set autocalc -1
%  elim T1 I
%  type I
; e2-4/3df+1/3cg de-3/2cf+1/2bg d2-9/5bf+4/5ag ce-8/5bf+3/5ag
; cd-3/2be+1/2af c2-4/3bd+1/3ae
%  ; place the result ideal I into a cleaner ring, and then compute
%  ; its resolution.
%  ring S
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  7
!   7 variables, please               ?  a-g
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ? <return>
;   largest degree of a monomial        : 76
%  fetch I I
%  nres I I
; 2..3...4.[315k]...5....6....
; computation complete after degree 6
%  betti I
; total:      1     6    10     6     1
; --------------------------------------
;     0:      1     -     -     -     -
;     1:      -     6     5     -     -
;     2:      -     -     5     6     -
;     3:      -     -     -     -     1
%  pres I
;
; ----------------------------------
; e2-4/3df+1/3cg de-3/2cf+1/2bg d2-9/5bf+4/5ag ce-8/5bf+3/5ag
; cd-3/2be+1/2af c2-4/3bd+1/3ae
;
; ----------------------------------

; 0    a     b     c     d     0                0
; a    0     -2/3c -8/9d -e    ce-8/5bf         de-6/5cf
; -4b  -8/3c 0     8/9e  4/3f  12/5bg           -e2+9/5cg
; 9/2b 3c    0     -e    -3/2f -de+3/2cf-16/5bg 3/2df-12/5cg
; 3c   8/3d  2/3e  0     -1/3g -9/5cg           6/5ef-9/5dg
; -3d  -3e   -f    -1/3g 0     9/5dg            -9/5f2+12/5eg
; 0               0               0
; 0               0               0
; cd-3/2be+1/2af  -ce+8/5bf-3/5ag c2-4/3bd+1/3ae
; 0               d2-9/5bf+4/5ag  0
; -d2+9/5bf-4/5ag 0               0
; 0               0               -d2+9/5bf-4/5ag
;
; ----------------------------------
; 0         -32/81dg 32/45eg          e2-4/3df-9/5cg
; -d2+9/5bf 4/9cg    -32/45dg         -de+3/2cf+27/10bg
; -9/5af    -cf      8/5df            -9/2ce-27/10ag
; 0         bf-4/9ag -de              9/2be-3/2af
; ad        0        ce-8/5bf+32/45ag ae
; 0         -5/9d    e                -3c
; a         5/9c     -8/9d            4b
; -8/3d     0        -8/27g           -8/3e
; 3c        -5/9e    4/3f             0
; 3e        5/27g    0                4f
; -8/9d2+8/5bf 32/45cg
; 0            -16/15bg
; 0            4/3d2+16/15ag
; -ad          -cd
; ac           c2-4/3bd
; a            c
; 0            -4/3b
; -8/3c        8/9e
; 4b           0
; 8/3d         -4/3f
;
; ----------------------------------
; 8/27de-4/9cf+4/27bg
; 8/5cd-12/5be+4/5af
; c2-4/3bd+1/3ae
; -8/27d2+8/15bf-1896ag

; -1/3e2+4/9df-1/9cg
; -ce+8/5bf-3/5ag
;
; ----------------------------------

A.4 Finding an inhomogeneous standard basis

%  ;; Problem: find a minimal standard basis of an inhomogeneous ideal.
%  ;;
%  ;; The technique we use is to homogenize the ideal, compute a standard
%  ;; basis, and then find a minimal standard basis after dehomogenizing.
%  ring R
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  5
!   5 variables, please               ?  a-dt
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ?  4 1
;   largest degree of a monomial        : 512 512
%  ideal j
! number of generators ?  3
! (1,1) ?  a3-bc-1
! (1,2) ?  ab2-cd-a
! (1,3) ?  b3-bc-d+1
%  ; now we homogenize
%  homog j t k
%  type k
; a3-bct-t3 ab2-cdt-at2 b3-bct-dt2+t3
%  ; compute a standard basis of "k"
%  std k k
; 34.5.6.7.8.9.
; computation complete after degree 9
%  ; find a subset of this standard basis which is minimal after
%  ; dehomogenization
%  stdpart k m a..d
%  putmat m

; 1
; 11
; c3d3t2-bc4t3+b2c2t4+3bc3t4-3c3dt4-3bcd2t4-2ac2t5-3bc2t5+c3t5 \
;     +abdt5+2bcdt5+8c2dt5+2ad2t5-abt6-3b2t6+5act6+2bct6-3c2t6 \
;     -4adt6+3bdt6-6cdt6-d2t6-at7-3bt7+3ct7+2dt7
; bcd3t-b2c2t2-ac2dt2-a2d2t2+abd2t2+c2d2t2-ad3t2+a2bt3-a2ct3 \
;     +b2ct3+a2dt3+2acdt3-bcdt3+ad2t3+a2t4+bt5-dt5+t6
; b2cdt-abdt2-c2dt2+abt3-act3+cdt3+at4
; b3-bct-dt2+t3
; ac2d2t2-bc3t3+2bc2t4-abdt4-2c2dt4+abt5+2b2t5-act5-bct5+c2t5 \
;     -bdt5+3cdt5+at6+bt6-2ct6-t7
; ac3dt2-c3d2t2+a2c2t3+b2c2t3-2ac2dt3-bcd2t3-a2bt4-a2ct4-b2ct4 \
;     +a2dt4-abdt4+bcdt4+ad2t4-a2t5-adt5-bt6+dt6-t7
; abct-bcdt-abt2+adt2-at3
; ab2-cdt-at2
; a2cdt-bc2t2-b2t3+bct3-cdt3+ct4+t5
; a2bdt2+ac2dt2-c2d2t2-a2bt3+a2ct3-2acdt3-a2t4
; a3-bct-t3
%  ; finally, dehomogenize
%  imap f m m
! variable, new image ?  t 1
! variable, new image ? <return>
%  ev f m m
%  ; and the final answer is
%  putmat m
; 1
; 11
; c3d3-bc4+b2c2+3bc3-3c3d-3bcd2-2ac2-3bc2+c3+abd+2bcd+8c2d+2ad2 \
;     -ab-3b2+5ac+2bc-3c2-4ad+3bd-6cd-d2-a-3b+3c+2d
; bcd3-b2c2-ac2d-a2d2+abd2+c2d2-ad3+a2b-a2c+b2c+a2d+2acd-bcd+ad2 \
;     +a2+b-d+1
; b2cd-abd-c2d+ab-ac+cd+a
; b3-bc-d+1
; ac2d2-bc3+2bc2-abd-2c2d+ab+2b2-ac-bc+c2-bd+3cd+a+b-2c-1
; ac3d-c3d2+a2c2+b2c2-2ac2d-bcd2-a2b-a2c-b2c+a2d-abd+bcd+ad2-a2 \
;     -ad-b+d-1
; abc-bcd-ab+ad-a
; ab2-cd-a
; a2cd-bc2-b2+bc-cd+c+1
; a2bd+ac2d-c2d2-a2b+a2c-2acd-a2
; a3-bc-1

A.5 The ideal of the 3 by 3 commuting matrices

Given a (homogeneous) ideal I ⊂ S = k[x_{1},…, x_{n}], what is the best way to determine whether the ring S/I is Cohen-Macaulay (C.M.)? One way is to compute a minimal finite free resolution of S/I. S/I is C.M. if and only if the length of the resolution is equal to the codimension of S/I. (see [?] for definitions and the basic properties of Cohen- Macaulay rings and modules).

Unfortunately, this method sometimes fails, since it is often too time consuming to compute the finite free resolution. A much easier approach is to use the following well known proposition.

Proposition 7 (Test for whether a ring is C.M.) Let I ⊂ S be a homogeneous ideal, and let d = dim S/I. Then S/I is Cohen-Macaulay ⟺ deg S/I = deg S/(I, f_{1},…, f_{d}), for some (and hence all) system of parameters {f_{1},…, f_{d}}.

Recall that deg S/(I, f_{1},…, f_{d}) = dim_{k} S/(I, f_{1},…, f_{d}). In Macaulay, this number can be found from a standard basis by the degree command.

One important problem is the following question of Artin and Hochster. Let I ⊂ k[x_{ij}, y_{ij}] be the ideal of the entries of the n by n matrix XY − Y X, where X = (x_{ij}), and Y = (y_{ij}). Is S/I Cohen-Macaulay? If so, this easily implies that S/I is a normal domain. However, the question has still not been answered for n ≥ 4.

In this example, we show that for n = 3, S/I is Cohen-Macaulay. For this example, it is possible but time consuming to compute a finite free resolution, therefore our method of attack is to use the above proposition. The Macaulay session to determine this is given below. The following list of notes refers to this session.

1. The monomial order for the ring S is set to the default: the reverse lexicographic order. This allows the entire computation to take much less time. For example, the session below takes about 30 seconds on either a SUN 3/140 or a Macintosh II.

2. Notice the shorthand “x[1]-y[9]” to specify the 18 variables which we need.

3. The matrices X and Y are created using the useful cat command.

4. The random command is used to generate enough random numbers so that we can construct 12 random linear forms.

5. The method we have chosen is not the fastest. For example, the standard basis computation of “Icut” is done in the original ring S. However, if we simply reduced I with respect to the random linear forms, we would have an ideal in 6 variables. Computing a standard basis here would be much more efficient. In this example however, more efficiency is not needed.

%  ; first create a ring with 18 variables x[i]'s and y[j]'s.
%  ring S
! characteristic (if not 31991)       ? <return>
! number of variables                 ?  18
!  18 variables, please               ?  x[1]-y[9]
! variable weights (if not all 1)     ? <return>
! monomial order (if not rev. lex.)   ? <return>
;   largest degree of a monomial        : 16
%  ; find the ideal I
%  cat x[1] X
! rows ?  0 3 6
! columns ?  0 1 2
%  cat y[1] Y
! rows ?  0 3 6
! columns ?  0 1 2
%  type X
; x[1] x[2] x[3]
; x[4] x[5] x[6]
; x[7] x[8] x[9]
%  type Y
; y[1] y[2] y[3]
; y[4] y[5] y[6]
; y[7] y[8] y[9]
%  mult X Y XY
%  mult Y X YX
%  subtract XY YX XY_YX
%  flatten XY_YX I
%  ; compute a standard basis of I, and its degree.
%  std I I

A.6. LINKAGE OF CURVES IN P^{3} 119

; 23.4.5.6.7.
; computation complete after degree 7
%  degree I
; codimension : 6
; degree      : 31
%  ; now find a system of parameters for I.
%  ; we need 12 linear forms (since dim(S/I) = 12).
%  ; we choose 12 random linear forms.
%  random 18 12 rand
%  mult S rand linears
%  concat linears I
%  ; compute a standard basis of (I, linears), and its degree.
%  std linears Icut
; 12.3.4.5.6.
; computation complete after degree 6
%  degree Icut
; codimension : 18
; degree      : 31
%  ; both have degree 31, therefore S/I is Cohen-Macaulay.

A.6 Linkage of curves in P^{3}

Let C ⊂ P^{3} be a curve. Let I_{C} be its homogeneous defining ideal. Suppose that f, g ∈ I_{C} are two homogeneous polynomials such that {f, g} is a regular sequence. Then X = Z(f, g) ⊂ P^{3} is also a curve, and X = C ∪ D, for some (possibly reducible) curve D. D is called the link of C via the complete intersection X.

Linkages are an important technique in the theory of curves. In this example, we compute the link D of the rational quartic curve via a complete intersection (f, g), where both f and g have degree three. This curve has degree five. After we find the equations of D, we then see whether the result is a nonsingular curve.

The ideal I_{D} defining the curve D is the ideal quotient

((f, g) : I_{C}) = {h ∈ k[a, b, c, d] | hI_{C} ⊂ (f, g)}.

This is accomplished in Macaulay using the quotient command.

We find the singular locus of any variety by using the following proposition (see [?,?]).

Proposition 8 (Test for non-singularity) Let X ⊂ P^{n} be a projective algebraic set of dimension d, with defining ideal I = {f_{1},…, f_{r}}. Let Df = (∂f_{i}/∂x_{j}) be the (n + 1) by r Jacobian matrix. Let J be the ideal consisting of I together with all the n − d by n − d determinants of the matrix Df.

(a) The singular locus of X is exactly the zero locus Z(J).

(b) X is nonsingular ⟺ codim J = n + 1.

The following list of remarks refers to the Macaulay session below.

1. It is necessary to choose f and g sufficiently “generic” in order for the result to be a nonsingular curve. In this example we use polynomial expressions using the generators for the ideal I_{C}.

2. Before determining the codimension of the ideal J, it is essential to concatenate the equations from I_{C} to the equations from the minors of the Jacobian matrix. It is a common mistake to omit this step!

%  type i_C  ; the ideal of the rational quartic
; c3-bd2 bc-ad b3-a2c ac2-b2d
%  ; first we choose two cubics in this ideal
%  ideal i_X
! number of generators ?  2
! (1,1) ?  (c3-bd2)+(a+b-c+d)*(bc-ad)
! (1,2) ?  (b3-a2c)+2*(ac2-b2d)+3d(bc-ad)
%  ; now we compute the ideal "i_D" of D
%  quotient i_X i_C i_D
; 0.[378k]1.2.3..4..
; computation complete after degree 4
%  putmat i_D
; 1
; 5
; a3+a2b+3/2ab2+b3-5/2a2c+3/2b2c+ac2-1/2bc2+2c3-a2d-4abd-1/2b2d \
;     +3/2acd+3/2bcd-1/2ad2-5bd2+9/2d3
; a2b+ab2+abc+2b2c+ac2-2bc2+2c3-4a2d-3abd+b2d+4acd+2bcd-4ad2 \
;     -4bd2+3cd2
; ab2+2b3-a2c-b2c+2ac2+bc2-2abd-3b2d+acd+5bcd-2c2d-3ad2-2bd2+3d3
; abc+b2c-bc2+c3-a2d-abd+acd+bcd-ad2-bd2
; b3-a2c+2ac2-2b2d+3bcd-3ad2

%  ; is this nonsingular?
%  ; first construct the ideal J
%  jacob i_D Df
%  wedge Df 2 J   ; 2 by 2 minors, since 2 = codim C
%  flatten J J
%  concat J i_D   ; don't forget to add the ideal i_D!!
%  ; now compute the codimension of J
%  std J J
; 34.5.
; computation complete after degree 5
%  codim J
; codimension : 4
%  ; the codimension is 4, and therefore this curve is nonsingular.

Appendix B

Macaulay under MPW

Installation of Macaulay on a Macintosh with a hard disk: Drag the folder ”Macaulay” to any convenient location on the hard disk. (The entire contents of the folder, arcane though some may seem, are necessary.) Now you are ready to run Macaulay.

Macaulay was originally designed to run under UNIX. In the Macintosh environment MPW provides the services that would be provided by the Unix operating system, and then some! (MPW = Macintosh Programmer’s Workshop. The version here provided is licensed from Apple for distribution with Macaulay, courtesy of the Mathematical Sciences Institute at Cornell University.) Thus to run Macaulay you must begin by launching the application MPW, which is inside the Macaulay folder.

When you have launched MPW, you will see a window labeled ”Worksheet”, and you will be talking to the MPW interpreter, which acts something like the finder. One peculiarity of MPW which is very important for using Macaulay is that it interprets <return> (produced by pressing the return key) differently from <enter> (produced either by pressing the enter key or by holding down the command key while pressing the return key.) If you are new to MPW, try the following exercise to understand the difference:

• Type the word ”Directory” (without the quotation marks. You can capitalize or not, since capitals don’t matter to MPW). Press <return>. What happens? (Answer: Nothing. MPW acts as an editor, and you have simply moved to the next line, presumably to add more text.)

• Place the cursor anywhere on the line with the word ”Directory” and press <enter>. What happens? (Answer: MPW interprets the word ”Directory” as a command, and executes it, producing the full name of the ”current folder” – that is, the folder whose contents is listed when you select ”open” from the file menu.)

• Select the word ”Directory” using the mouse. Now press <enter>. What happens? (Answer: Again, MPW executes the selected word as a command. This would also work if you selected many commands together, perhaps on many lines.)

• Again select the word ”Directory”. Now press <return>. What happens? (Answer: The selected word simply disappears, and is replaced by a blank line! This replacement of selected text is the standard response of a Macintosh editor.

Don’t forget that you can use either command-<return> or <enter> (but not command-<enter>!) interchangeably.

B.1 Controlling Macaulay from a window

One of the great virtues of the MPW system is that you can type commands to Macaulay in one window, which becomes a log of the session from which any part of it can be reproduced, and have Macaulay type its responses in another window, such as the worksheet. Each window corresponds to a file which can be saved on the disk. This is the normal way of using Macaulay under MPW, and we will now describe it.

For convenience, start by setting the ”current directory” to be the Work folder inside the Macaulay folder. Do this by going to the ”Directory menu” inside MPW and selecting the directory whose name ends with the word ”Work”.

Now open a new window by selecting ”new” from the file menu, naming the new window whatever you like when the dialogue box comes up. Then choose ”tile windows” from the Window menu to make both of the two windows conveniently visible. Try clicking inside each of the two windows in turn, to see that they become active when you click inside them. While the Worksheet window is active, try pressing command-a to select everything, and then press the delete key, to clear that window of the remains of the previous experiment.

To start Macaulay in the Worksheet: Click in the Worksheet to make it active. Then type the word ”Macaulay” (no quotation marks) and press <enter> (or, as usual, command-<return>.) Macaulay will start up in the Worksheet.

Now click on the other window. You are ready to type a command to Macaulay. Try for example typing ”help”, followed by <enter>, to see some of the features that Macaulay has. (Don’t forget that Macaulay does not react to a command unless you type <enter>. In particular, if you type <return> after a command instead by mistake, nothing will happen!).

B.2 Customizing the MPW environment

Many aspects of the MPW environment are controlled by the document called ”UserStartup”, which is in the Macaulay folder. The adventurous user may wish to experiment with modifications of this file. In particular the ”environment variable” MacaulayPath controls which folders are searched to find commands and scripts for Macaulay, and the ”DirectoryMenu” command controls which folders are listed under the directory menu.

For example, if you create a new work folder named ”Fun” inside the ”Macaulay” folder for some particular project, you might want to add its name to the list of names in these lines of the UserStartup file. Thus you might change the lines

        DirectoryMenu "{mpw}" "{mpw}Scripts" "{mpw}Work"
        Set MacaulayPath ":,{mpw}Scripts:"

to

        DirectoryMenu "{mpw}" "{mpw}Scripts" ^
        "{mpw}Work"  "{mpw}Fun"
        Set MacaulayPath ":,{mpw}Scripts:,{mpw}Fun:"

Note that the useful abbreviation mpw stands here for the full name of whatever folder contains the MPW application – in our case the Macaulay folder. Also, the character which is made by pressing option-d, tells MPW to ignore the carriage return immediately following it, so that the files listed above after DirectoryMenu appear to MPW to be on a single line.

Neither of these changes is actually necessary. The change in the first line simply adds the convenience of being able to switch directories to the ”Fun” folder instantly from the Directory menu. (Else you can switch to it using the ”set directory” command from the Directory menu.) The second change enables Macaulay to find scripts that you store inside the Fun folder even when this folder is not the current folder. (When the Fun folder is the current folder, Macaulay can find them because of the initial item ”:” in the MacaulayPath.)

B.3 Some Peculiarities of Macaulay under MPW

• While Macaulay is active, files cannot be saved in the normal way. Instead, one must save a file (corresponding to the contents of a window) by closing that window – just click in the close box at the upper right hand corner. Then select ”Open” from the file menu and reopen the window to go back to work. It is sometimes important to do this, because if Macaulay crashes the contents of windows that have been put there since the last save will be lost. (Note that the Worksheet cannot be closed, and thus it cannot be saved while Macaulay is running.) An option is of course to quit Macaulay (type exit or command-.), save the file in the usual way, and then restart Macaulay in the Worksheet and get back to where you were by selecting all of the window you are working from and typing <enter>.

• Output from Macaulay will appear wherever the cursor is in the Worksheet. Thus to be sure that output appears at the end of the Worksheet, after moving the cursor by clicking elsewhere within the Worksheet, it is necessary to click at the end of the Worksheet.

Appendix C

Scripts of Macaulay (by D. Eisenbud, M. Stillman

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

C.1 adj of cat
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.

C.2 adjoin fractions
Usage:

C.3. ADJOINT  127

    <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.

C.3 adjoint
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^*).

128APPENDIX C. SCRIPTS OF MACAULAY (BY D. EISENBUD, M. STILLMAN

C.4 annihilator1
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

C.5 annihilator2
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.

C.6 binomial
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.

C.7. BLOCK MAP  129

C.7 block map
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.

C.8 blowup
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.

C.9 blowup0
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).

C.10 cohomology
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.

C.11. COHOMOLOGY1  131

    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.

C.11 cohomology1
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.

C.12 complement
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

C.13 copyring
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.)

C.14 cotan
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

C.15 cotan bihom
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.)

C.16 deg01
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).

C.17 diagonal submodule
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.

C.18 double dual
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.

C.19. DOUBLE DUAL1  137

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:
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

C.19 double dual1
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.

C.20 dual variety
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

C.21 ext

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.

C.22 ext(-,R)
Usage:
    <ext(-,R) n a c
A presentation of the module
Ext^n(a,R) is put into the

C.23. EXTEND RING  139

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.

C.23 extend ring
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.

C.24 from bigraded
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

C.25. FROM DIV POWERS  141

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).

C.25 from div powers
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.

C.26 generic mat
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.

C.27 getvars

    <getvars result
Creates a 1xn matrix containing the variables of the current ring
in order.

C.28 hom

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

C.29 hom and map
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.

C.30 hom is 0
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.

C.31 homology
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.

C.32 ideal

    <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:

C.33 idencoldegs
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

C.34 idenrowdegs
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

C.35 inhomog std
Usage:
    <inhomog_std I J
Compute a standard basis J of the inhomogeneous submodule I.
Parameters:

C.36. INTERCHANGE  145

  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.

C.36 interchange
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.

C.37 interchange permutation
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

C.38 inverse
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

C.39 j from lambda
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.

C.40 j invariant
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

C.41 kernel
Usage:
    <kernel f0 a b c
Given f0, a, b making a commutative diagram

C.42. KERNEL AND MAP  147

(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.

C.42 kernel and map
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.

C.43 kosz hom1
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.

C.44 kosz hom2
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!

C.45 l dual0
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.

C.46 l from dual
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.

C.47 l homog0
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.

C.48 l minimal
Usage:
    <l_minimal I J

C.49. L MINIMAL0  151

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]".

C.49 l minimal0
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.

C.50 l tangentcone
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

C.51 l to dual
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.

C.52. LINE BUNDLE IMAGE  153

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.

C.52 line bundle image
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".

C.53 minpres

    <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]

C.54 monomial curve
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.

C.55. NBYN COMMUTING  155

C.55 nbyn commuting
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].

C.56 normal cone
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.

C.57 normal sheaf
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.

C.58 nzd

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.

C.59. ORBIT EQUATIONS  157

C.59 orbit equations
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.

C.60 permutation
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.

C.61 points
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.

C.62 powers
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.

C.63 project from product
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.

C.64 prune
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.

C.65 prune and map
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.

C.66 pts linear
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.

C.67 push forward
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.)

C.68 push forward1
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

C.68. PUSH FORWARD1  161

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.)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

C.69 random mat
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.

C.70 representatives
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.

C.71 representatives1
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.

C.72 ring
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.

C.73 rmap
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.

C.74 sat

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.
;;;;;;;;;;;;;;;;;;;;;;;

C.75 sat1
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.

C.76 subring
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.

C.77 symmetric algebra
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.

C.78 to div powers
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).

C.79 tor

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.

C.80 x to last
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.

C.81 zeromat
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.