Interface to Macaulay2

Note

You must have Macaulay2 installed on your computer for this interface to work. Macaulay2 is not included with Sage, but you can obtain it from https://faculty.math.illinois.edu/Macaulay2/. No additional optional Sage packages are required.

Sage provides an interface to the Macaulay2 computational algebra system. This system provides extensive functionality for commutative algebra. You do not have to install any optional packages.

The Macaulay2 interface offers three pieces of functionality:

  • macaulay2_console() – A function that dumps you into an interactive command-line Macaulay2 session.
  • macaulay2.eval(expr) – Evaluation of arbitrary Macaulay2 expressions, with the result returned as a string.
  • macaulay2(expr) – Creation of a Sage object that wraps a Macaulay2 object. This provides a Pythonic interface to Macaulay2. For example, if f = macaulay2(10), then f.gcd(25) returns the GCD of \(10\) and \(25\) computed using Macaulay2.

EXAMPLES:

sage: macaulay2('3/5 + 7/11')       # optional - macaulay2
68
--
55
sage: f = macaulay2('f = i -> i^3') # optional - macaulay2
sage: f                             # optional - macaulay2
f
sage: f(5)                          # optional - macaulay2
125

sage: R = macaulay2('ZZ/5[x,y,z]')  # optional - macaulay2
sage: R                             # optional - macaulay2
ZZ
--[x, y, z]
 5
sage: x = macaulay2('x')            # optional - macaulay2
sage: y = macaulay2('y')            # optional - macaulay2
sage: (x+y)^5                       # optional - macaulay2
 5    5
x  + y
sage: parent((x+y)^5)               # optional - macaulay2
Macaulay2

The name of the variable to which a Macaulay2 element is assigned internally can be passed as an argument. This is useful for types like polynomial rings which acquire that name in Macaulay2:

sage: R = macaulay2('QQ[x,y,z,w]', 'R')  # optional - macaulay2
sage: R                                  # optional - macaulay2
R

sage: f = macaulay2('x^4 + 2*x*y^3 + x*y^2*w + x*y*z*w + x*y*w^2'    # optional - macaulay2
....:               '+ 2*x*z*w^2 + y^4 + y^3*w + 2*y^2*z*w + z^4 + w^4')
sage: f                             # optional - macaulay2
 4       3    4    4      2     3                2           2         2    4
x  + 2x*y  + y  + z  + x*y w + y w + x*y*z*w + 2y z*w + x*y*w  + 2x*z*w  + w
sage: g = f * macaulay2('x+y^5')    # optional - macaulay2
sage: print(g.factor())             # optional - macaulay2
  4       3    4    4      2     3                2           2         2    4   5
(x  + 2x*y  + y  + z  + x*y w + y w + x*y*z*w + 2y z*w + x*y*w  + 2x*z*w  + w )(y  + x)

Use eval() for explicit control over what is sent to the interpreter. The argument is evaluated in Macaulay2 as is:

sage: macaulay2.eval('compactMatrixForm')           # optional - macaulay2
true
sage: macaulay2.eval('compactMatrixForm = false;')  # optional - macaulay2
sage: macaulay2.eval('matrix {{1, x^2+y}}')         # optional - macaulay2
|     2     |
| 1  x  + y |

        1       2
Matrix R  <--- R
sage: macaulay2.eval('compactMatrixForm = true;')   # optional - macaulay2

AUTHORS:

  • Kiran Kedlaya and David Roe (2006-02-05, during Sage coding sprint)
  • William Stein (2006-02-09): inclusion in Sage; prompt uses regexp, calling of Macaulay2 functions via __call__.
  • William Stein (2006-02-09): fixed bug in reading from file and improved output cleaning.
  • Kiran Kedlaya (2006-02-12): added ring and ideal constructors, list delimiters, is_Macaulay2Element, sage_polystring, __floordiv__, __mod__, __iter__, __len__; stripped extra leading space and trailing newline from output.

Todo

Get rid of all numbers in output, e.g., in ideal function below.

class sage.interfaces.macaulay2.Macaulay2(maxread=None, script_subdirectory=None, logfile=None, server=None, server_tmpdir=None, command=None)

Bases: sage.interfaces.tab_completion.ExtraTabCompletion, sage.interfaces.expect.Expect

Interface to the Macaulay2 interpreter.

clear(var)

Clear the variable named var.

The interface automatically clears Macaulay2 elements when they fall out of use, so calling this method is usually not necessary.

EXAMPLES:

sage: macaulay2.eval('R = QQ[x,y];')  # optional - macaulay2
sage: macaulay2.eval('net class R')   # optional - macaulay2
PolynomialRing
sage: macaulay2.clear('R')            # optional - macaulay2
sage: macaulay2.eval('net class R')   # optional - macaulay2
Symbol
console()

Spawn a new M2 command-line session.

EXAMPLES:

sage: macaulay2.console()                    # not tested
Macaulay 2, version 1.1
with packages: Classic, Core, Elimination, IntegralClosure, LLLBases, Parsing, PrimaryDecomposition, SchurRings, TangentCone
...
cputime(t=None)

EXAMPLES:

sage: R = macaulay2("QQ[x,y]")  # optional - macaulay2
sage: x,y = R.gens()            # optional - macaulay2
sage: a = (x+y+1)^20            # optional - macaulay2
sage: macaulay2.cputime()       # optional - macaulay2; random
0.48393700000000001
eval(code, strip=True, **kwds)

Send the code x to the Macaulay2 interpreter and return the output as a string suitable for input back into Macaulay2, if possible.

INPUT:

  • code – str
  • strip – ignored

EXAMPLES:

sage: macaulay2.eval("2+2") # optional - macaulay2
4
get(var)

Get the value of the variable var.

INPUT:

  • var - string; the name of the variable in Macaulay2

OUTPUT: a string of the textual representation of the variable in Macaulay2

EXAMPLES:

sage: macaulay2.set("a", "2") # optional - macaulay2
sage: macaulay2.get("a")      # optional - macaulay2
2

Note that the following syntax is used to obtain a Macaulay2Element instead:

sage: a = macaulay2('2'); a   # optional - macaulay2
2
sage: type(a)                 # optional - macaulay2
<class 'sage.interfaces.macaulay2.Macaulay2Element'>
help(s)

EXAMPLES:

sage: macaulay2.help("load")  # optional - macaulay2 - 1st call might be chatty...
...
sage: macaulay2.help("load")  # optional - macaulay2
load...
****...
...
  * "input" -- read Macaulay2 commands and echo
  * "notify" -- whether to notify the user when a file is loaded
ideal(*gens)

Return the ideal generated by gens.

INPUT:

  • gens – list or tuple of Macaulay2 objects (or objects that can be made into Macaulay2 objects via evaluation)

OUTPUT:

the Macaulay2 ideal generated by the given list of gens

EXAMPLES:

sage: R2 = macaulay2.ring('QQ', '[x, y]'); R2            # optional - macaulay2
QQ[x, y]
sage: I = macaulay2.ideal( ('y^2 - x^3', 'x - y') ); I   # optional - macaulay2
          3    2
ideal (- x  + y , x - y)
sage: J = I^3; J.gb().gens().transpose()                 # optional - macaulay2
{-9} | y9-3y8+3y7-y6             |
{-7} | xy6-2xy5+xy4-y7+2y6-y5    |
{-5} | x2y3-x2y2-2xy4+2xy3+y5-y4 |
{-3} | x3-3x2y+3xy2-y3           |
new_from(type, value)

Return a new Macaulay2Element of type type constructed from value.

EXAMPLES:

sage: l = macaulay2.new_from("MutableList", [1,2,3]) # optional - macaulay2
sage: l                                              # optional - macaulay2
MutableList{...3...}
sage: list(l)                                        # optional - macaulay2
[1, 2, 3]
options(*get_value, **set_value)

Global options for Macaulay2 elements.

OPTIONS:

  • after_print – (default: False) append AfterPrint type information to textual representations

EXAMPLES:

sage: macaulay2.options.after_print = True  # optional - macaulay2
sage: A = macaulay2(matrix([[1, 2], [3, 6]])); A  # optional - macaulay2
| 1 2 |
| 3 6 |

         2        2
Matrix ZZ  <--- ZZ
sage: A.kernel()  # optional - macaulay2
image | 2  |
      | -1 |

                          2
ZZ-module, submodule of ZZ
sage: macaulay2.options.after_print = False  # optional - macaulay2

See GlobalOptions for more features of these options.

restart()

Restart Macaulay2 interpreter.

ring(base_ring='ZZ', vars='[x]', order='Lex')

Create a Macaulay2 polynomial ring.

INPUT:

  • base_ring – base ring (see examples below)
  • vars – a tuple or string that defines the variable names
  • order – string (default: ‘Lex’); the monomial order

OUTPUT: a Macaulay2 ring

EXAMPLES:

This is a ring in variables named a through d over the finite field of order 7, with graded reverse lex ordering:

sage: R1 = macaulay2.ring('ZZ/7', '[a..d]', 'GRevLex')  # optional - macaulay2
sage: R1.describe()  # optional - macaulay2
ZZ
--[a..d, Degrees => {4:1}, Heft => {1}, MonomialOrder => {MonomialSize => 16},
 7                                                       {GRevLex => {4:1}  }
                                                         {Position => Up    }
--------------------------------------------------------------------------------
DegreeRank => 1]
sage: R1.char()  # optional - macaulay2
7

This is a polynomial ring over the rational numbers:

sage: R2 = macaulay2.ring('QQ', '[x, y]')  # optional - macaulay2
sage: R2.describe()  # optional - macaulay2
QQ[x..y, Degrees => {2:1}, Heft => {1}, MonomialOrder => {MonomialSize => 16},
                                                         {Lex => 2          }
                                                         {Position => Up    }
--------------------------------------------------------------------------------
DegreeRank => 1]
set(var, value)

Set the variable var to the given value.

INPUT:

  • var - string; the name of the variable in Macaulay2
  • value - a string to evaluate

EXAMPLES:

sage: macaulay2.set("a", "1+1")  # optional - macaulay2
sage: macaulay2.get("a")         # optional - macaulay2
2
set_seed(seed=None)

Set the seed for Macaulay2 interpreter.

INPUT:

  • seed – number (default: None). If None, it is set to a random number.

OUTPUT: the new seed

EXAMPLES:

sage: m = Macaulay2()                     # optional - macaulay2
sage: m.set_seed(123456)                  # optional - macaulay2
123456
sage: [m.random(100) for _ in range(11)]  # optional - macaulay2
[8, 29, 5, 22, 4, 32, 35, 57, 3, 95, 36]
use(R)

Use the Macaulay2 ring R.

EXAMPLES:

sage: R = macaulay2("QQ[x,y]")                  # optional - macaulay2
sage: P = macaulay2("ZZ/7[symbol x, symbol y]") # optional - macaulay2
sage: macaulay2("x").cls()._operator('===', P)  # optional - macaulay2
true
sage: macaulay2.use(R)                          # optional - macaulay2
sage: macaulay2("x").cls()._operator('===', R)  # optional - macaulay2
true
version()

Returns the version of Macaulay2.

EXAMPLES:

sage: macaulay2.version() # optional - macaulay2
(1, 1...
class sage.interfaces.macaulay2.Macaulay2Element(parent, value, is_name=False, name=None)

Bases: sage.interfaces.tab_completion.ExtraTabCompletion, sage.interfaces.expect.ExpectElement

Instances of this class represent objects in Macaulay2.

Using the method sage() we can translate some of them to SageMath objects:

_sage_()

EXAMPLES:

sage: macaulay2(ZZ).sage()         # optional - macaulay2, indirect doctest
Integer Ring
sage: macaulay2(QQ).sage()         # optional - macaulay2
Rational Field

sage: macaulay2(2).sage()          # optional - macaulay2
2
sage: macaulay2(1/2).sage()        # optional - macaulay2
1/2
sage: macaulay2(2/1).sage()        # optional - macaulay2
2
sage: _.parent()                   # optional - macaulay2
Rational Field
sage: macaulay2([1,2,3]).sage()    # optional - macaulay2
[1, 2, 3]

sage: m = matrix([[1,2],[3,4]])
sage: macaulay2(m).sage()          # optional - macaulay2
[1 2]
[3 4]

sage: D = macaulay2('hashTable {4 => 1, 2 => 3}')  # optional - macaulay2
sage: D.pairs()                    # optional - macaulay2
{(4, 1), (2, 3)}
sage: D.sage() == {4: 1, 2: 3}    # optional - macaulay2
True

sage: macaulay2(QQ['x,y']).sage()       # optional - macaulay2
Multivariate Polynomial Ring in x, y over Rational Field
sage: macaulay2(QQ['x']).sage()         # optional - macaulay2
Univariate Polynomial Ring in x over Rational Field
sage: macaulay2(GF(7)['x,y']).sage()    # optional - macaulay2
Multivariate Polynomial Ring in x, y over Finite Field of size 7

sage: macaulay2(GF(7)).sage()          # optional - macaulay2
Finite Field of size 7
sage: macaulay2(GF(49, 'a')).sage()    # optional - macaulay2
Finite Field in a of size 7^2

sage: R.<x,y> = QQ[]
sage: macaulay2(x^2+y^2+1).sage()      # optional - macaulay2
x^2 + y^2 + 1

sage: R = macaulay2("QQ[x,y]")         # optional - macaulay2
sage: I = macaulay2("ideal (x,y)")     # optional - macaulay2
sage: I.sage()                         # optional - macaulay2
Ideal (x, y) of Multivariate Polynomial Ring in x, y over Rational Field

sage: macaulay2("x = symbol x")           # optional - macaulay2
x
sage: macaulay2("QQ[x_0..x_25]").sage()    # optional - macaulay2
Multivariate Polynomial Ring in x_0, x_1,..., x_25 over Rational Field

sage: S = ZZ['x,y'].quotient('x^2-y')
sage: macaulay2(S).sage() == S         # optional - macaulay2
True
sage: S = GF(101)['x,y'].quotient('x^2-y')
sage: macaulay2(S).sage() == S         # optional - macaulay2
True

sage: R = GF(13)['a,b']['c,d']
sage: macaulay2(R).sage() == R  # optional - macaulay2
True
sage: macaulay2('a^2 + c').sage() == R('a^2 + c')  # optional - macaulay2
True
sage: macaulay2.substitute('a', R).sage().parent() is R  # optional - macaulay2
True

sage: R = macaulay2("QQ^2")  # optional - macaulay2
sage: R.sage()               # optional - macaulay2
Vector space of dimension 2 over Rational Field

sage: macaulay2("vector {4_QQ, 2}").sage()  # optional - macaulay2
(4, 2)
sage: _.parent()                            # optional - macaulay2
Vector space of dimension 2 over Rational Field

sage: m = macaulay2('"hello"')  # optional - macaulay2
sage: m.sage()                  # optional - macaulay2
'hello'

sage: gg = macaulay2.needsPackage('"Graphs"') # optional - macaulay2
sage: g = macaulay2.barbellGraph(3)         # optional - macaulay2
sage: g.sage()                              # optional - macaulay2
Graph on 6 vertices
sage: g.sage().edges(labels=False)          # optional - macaulay2
[(0, 1), (0, 2), (1, 2), (2, 3), (3, 4), (3, 5), (4, 5)]

sage: d = 'digraph ({{1,2},{2,1},{3,1}}, EntryMode => "edges")'
sage: g = macaulay2(d)                      # optional - macaulay2
sage: g.sage()                              # optional - macaulay2
Digraph on 3 vertices
sage: g.sage().edges(labels=False)          # optional - macaulay2
[(1, 2), (2, 1), (3, 1)]

Chain complexes and maps of chain complexes can be converted:

sage: R = ZZ['a,b,c']
sage: C = macaulay2(ideal(R.gens())).resolution()  # optional - macaulay2
sage: ascii_art(C.sage())                          # optional - macaulay2
                          [-b  0 -c]       [ c]
                          [ a -c  0]       [ a]
            [a b c]       [ 0  b  a]       [-b]
 0 <-- C_0 <-------- C_1 <----------- C_2 <----- C_3 <-- 0
sage: F = C.dot('dd')  # optional - macaulay2
sage: G = F.sage()     # optional - macaulay2
sage: G.in_degree(2)   # optional - macaulay2
[-b  0 -c]
[ a -c  0]
[ 0  b  a]
sage: F.underscore(2).sage() == G.in_degree(2)  # optional - macaulay2
True
sage: (F^2).sage()     # optional - macaulay2
Chain complex morphism:
  From: Chain complex with at most 4 nonzero terms over Multivariate Polynomial Ring in a, b, c over Integer Ring
  To:   Chain complex with at most 4 nonzero terms over Multivariate Polynomial Ring in a, b, c over Integer Ring

Quotient rings in Macaulay2 inherit variable names from the ambient ring, so we mimic this behaviour in Sage:

sage: R = macaulay2("ZZ/7[x,y]")            # optional - macaulay2
sage: I = macaulay2("ideal (x^3 - y^2)")    # optional - macaulay2
sage: (R/I).gens()                          # optional - macaulay2
{x, y}
sage: (R/I).sage().gens()                   # optional - macaulay2
(x, y)

Elements of quotient rings:

sage: x, y = (R/I).gens()                   # optional - macaulay2
sage: f = ((x^3 + 2*y^2*x)^7).sage(); f     # optional - macaulay2
2*x*y^18 + y^14
sage: f.parent()                            # optional - macaulay2
Quotient of Multivariate Polynomial Ring in x, y over Finite Field of size 7 by the ideal (x^3 - y^2)
after_print_text()

Obtain type information for this Macaulay2 element.

This is the text that is displayed using AfterPrint in a Macaulay2 interpreter.

Macaulay2 by default includes this information in the output. In Sage, this behavior can optionally be enabled by setting the option after_print in Macaulay2.options.

EXAMPLES:

sage: B = macaulay2(matrix([[1, 2], [3, 6]])).kernel(); B  # optional - macaulay2
image | 2  |
      | -1 |
sage: B.after_print_text()  # optional - macaulay2
                          2
ZZ-module, submodule of ZZ
cls()

Since class is a keyword in Python, we have to use cls to call Macaulay2’s class. In Macaulay2, class corresponds to Sage’s notion of parent.

EXAMPLES:

sage: macaulay2(ZZ).cls()  # optional - macaulay2
Ring
dot(x)

EXAMPLES:

sage: d = macaulay2.new("MutableHashTable") # optional - macaulay2
sage: d["k"] = 4                            # optional - macaulay2
sage: d.dot("k")                            # optional - macaulay2
4
external_string()

EXAMPLES:

sage: R = macaulay2("QQ[symbol x, symbol y]")  # optional - macaulay2
sage: R.external_string()                      # optional - macaulay2
'QQ(monoid[x..y, Degrees => {2:1}, Heft => {1}, MonomialOrder => VerticalList{MonomialSize => 32, GRevLex => {2:1}, Position => Up}, DegreeRank => 1])'
name(new_name=None)

Get or change the name of this Macaulay2 element.

INPUT:

  • new_name – string (default: None). If None, return the name of this element; else return a new object identical to self whose name is new_name.

Note that this can overwrite existing variables in the system.

EXAMPLES:

sage: S = macaulay2(QQ['x,y'])          # optional - macaulay2
sage: S.name()                          # optional - macaulay2
'sage...'
sage: R = S.name("R")                   # optional - macaulay2
sage: R.name()                          # optional - macaulay2
'R'
sage: R.vars().cokernel().resolution()  # optional - macaulay2
 1      2      1
R  <-- R  <-- R  <-- 0

0      1      2      3

The name can also be given at definition:

sage: A = macaulay2(ZZ['x,y,z'], name='A')  # optional - macaulay2
sage: A.name()                              # optional - macaulay2
'A'
sage: A^1                                   # optional - macaulay2
 1
A
sage_polystring()

If this Macaulay2 element is a polynomial, return a string representation of this polynomial that is suitable for evaluation in Python. Thus * is used for multiplication and ** for exponentiation. This function is primarily used internally.

EXAMPLES:

sage: R = macaulay2.ring('QQ','(x,y)')               # optional - macaulay2
sage: f = macaulay2('x^3 + 3*y^11 + 5')              # optional - macaulay2
sage: print(f)                                       # optional - macaulay2
 3     11
x  + 3y   + 5
sage: f.sage_polystring()                            # optional - macaulay2
'x**3+3*y**11+5'
sharp(x)

EXAMPLES:

sage: a = macaulay2([1,2,3]) # optional - macaulay2
sage: a.sharp(0)             # optional - macaulay2
1
starstar(x)

The binary operator ** in Macaulay2 is usually used for tensor or Cartesian power.

EXAMPLES:

sage: a = macaulay2([1,2]).set()  # optional - macaulay2
sage: a.starstar(a)               # optional - macaulay2
set {(1, 1), (1, 2), (2, 1), (2, 2)}
structure_sheaf()

EXAMPLES:

sage: S = macaulay2('QQ[a..d]')                     # optional - macaulay2
sage: R = S / macaulay2('a^3 + b^3 + c^3 + d^3')    # optional - macaulay2
sage: X = R.Proj().name('X')                        # optional - macaulay2
sage: X.structure_sheaf()                           # optional - macaulay2
doctest:...: DeprecationWarning: The function `structure_sheaf` is deprecated. Use `self.sheaf()` instead.
See https://trac.sagemath.org/27848 for details.
OO
  X
sage: X.sheaf()                                     # optional - macaulay2
OO
  X
subs(*args, **kwds)

Note that we have to override the substitute method so that we get the default one from Macaulay2 instead of the one provided by Element.

EXAMPLES:

sage: R = macaulay2("QQ[x]")            # optional - macaulay2
sage: P = macaulay2("ZZ/7[symbol x]")   # optional - macaulay2
sage: x, = R.gens()                     # optional - macaulay2
sage: a = x^2 + 1                       # optional - macaulay2
sage: a = a.substitute(P)               # optional - macaulay2
sage: a.sage().parent()                 # optional - macaulay2
Univariate Polynomial Ring in x over Finite Field of size 7
substitute(*args, **kwds)

Note that we have to override the substitute method so that we get the default one from Macaulay2 instead of the one provided by Element.

EXAMPLES:

sage: R = macaulay2("QQ[x]")            # optional - macaulay2
sage: P = macaulay2("ZZ/7[symbol x]")   # optional - macaulay2
sage: x, = R.gens()                     # optional - macaulay2
sage: a = x^2 + 1                       # optional - macaulay2
sage: a = a.substitute(P)               # optional - macaulay2
sage: a.sage().parent()                 # optional - macaulay2
Univariate Polynomial Ring in x over Finite Field of size 7
to_sage(*args, **kwds)

Deprecated: Use sage() instead. See trac ticket #27848 for details.

underscore(x)

EXAMPLES:

sage: a = macaulay2([1,2,3])  # optional - macaulay2
sage: a.underscore(0)         # optional - macaulay2
1
class sage.interfaces.macaulay2.Macaulay2Function(parent, name)

Bases: sage.interfaces.expect.ExpectFunction

class sage.interfaces.macaulay2.Macaulay2FunctionElement(obj, name)

Bases: sage.interfaces.expect.FunctionElement

sage.interfaces.macaulay2.is_Macaulay2Element(x)

EXAMPLES:

sage: from sage.interfaces.macaulay2 import is_Macaulay2Element
sage: is_Macaulay2Element(2)              # optional - macaulay2
False
sage: is_Macaulay2Element(macaulay2(2))   # optional - macaulay2
True
sage.interfaces.macaulay2.macaulay2_console()

Spawn a new M2 command-line session.

EXAMPLES:

sage: macaulay2_console()                    # not tested
Macaulay 2, version 1.1
with packages: Classic, Core, Elimination, IntegralClosure, LLLBases, Parsing, PrimaryDecomposition, SchurRings, TangentCone
...
sage.interfaces.macaulay2.reduce_load_macaulay2()

Used for reconstructing a copy of the Macaulay2 interpreter from a pickle.

EXAMPLES:

sage: from sage.interfaces.macaulay2 import reduce_load_macaulay2
sage: reduce_load_macaulay2()
Macaulay2
sage.interfaces.macaulay2.remove_output_labels(s)

Remove output labels of Macaulay2 from a string.

  • s: output of Macaulay2
  • s: string

Returns: the input string with \(n\) symbols removed from the beginning of each line, where \(n\) is the minimal number of spaces or symbols of Macaulay2 output labels (looking like ‘o39 = ‘) present on every non-empty line.

Return type: string

Note

If s consists of several outputs and their labels have different width, it is possible that some strings will have leading spaces (or maybe even pieces of output labels). However, this function will try not cut any messages.

EXAMPLES:

sage: from sage.interfaces.macaulay2 import remove_output_labels
sage: output = 'o1 = QQ [x, y]\n\no1 : PolynomialRing\n'
sage: remove_output_labels(output)
'QQ [x, y]\n\nPolynomialRing\n'