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://macaulay2.com/. 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: # optional - macaulay2
sage: macaulay2('3/5 + 7/11')
68
--
55
sage: f = macaulay2('f = i -> i^3')
sage: f
f
sage: f(5)
125

sage: # optional - macaulay2
sage: R = macaulay2('ZZ/5[x,y,z]')
sage: R
ZZ
--[x...z]
 5
sage: x = macaulay2('x')
sage: y = macaulay2('y')
sage: (x+y)^5
 5    5
x  + y
sage: parent((x+y)^5)
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: # optional - macaulay2
sage: R = macaulay2('QQ[x,y,z,w]', 'R')
sage: R
R

sage: # optional - macaulay2
sage: f = macaulay2('x^4 + 2*x*y^3 + x*y^2*w + x*y*z*w + x*y*w^2'
....:               '+ 2*x*z*w^2 + y^4 + y^3*w + 2*y^2*z*w + z^4 + w^4')
sage: f
 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')
sage: print(g.factor())
  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: # optional - macaulay2
sage: macaulay2.eval('compactMatrixForm')
true
sage: macaulay2.eval('compactMatrixForm = false;')
sage: macaulay2.eval('matrix {{1, x^2+y}}')
|     2     |
| 1  x  + y |

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

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: ExtraTabCompletion, 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: # optional - macaulay2
sage: macaulay2.eval('R = QQ[x,y];')
sage: macaulay2.eval('net class R')
PolynomialRing
sage: macaulay2.clear('R')
sage: macaulay2.eval('net class R')
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: # optional - macaulay2
sage: R = macaulay2("QQ[x,y]")
sage: x,y = R.gens()
sage: a = (x+y+1)^20
sage: macaulay2.cputime()       # 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 = Current options for Macaulay2 - after_print: False#

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

version()#

Return the version of Macaulay2 as a tuple.

EXAMPLES:

sage: macaulay2.version() # optional - macaulay2
(1, ...)

class sage.interfaces.macaulay2.Macaulay2Element(parent, value, is_name=False, name=None)#

Bases: ExtraTabCompletion, ExpectElement, Macaulay2Element

Instances of this class represent objects in Macaulay2.

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

_sage_()#

EXAMPLES:

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

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

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

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

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

sage: # optional - macaulay2
sage: macaulay2(GF(7)).sage()
Finite Field of size 7
sage: macaulay2(GF(49, 'a')).sage()
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: # optional - macaulay2
sage: R = macaulay2("QQ[x,y]")
sage: I = macaulay2("ideal (x,y)")
sage: I.sage()
Ideal (x, y) of Multivariate Polynomial Ring in x, y over Rational Field

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

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

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

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

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

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

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

sage: # optional - macaulay2
sage: d = 'digraph ({{1,2},{2,1},{3,1}}, EntryMode => "edges")'
sage: g = macaulay2(d)
sage: g.sage()
Digraph on 3 vertices
sage: g.sage().edges(labels=False)
[(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: # optional - macaulay2
sage: R = macaulay2("ZZ/7[x,y]")
sage: I = macaulay2("ideal (x^3 - y^2)")
sage: (R/I).gens()
{x, y}
sage: (R/I).sage().gens()
(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: # optional - macaulay2
sage: d = macaulay2.new("MutableHashTable")
sage: d["k"] = 4
sage: d.dot("k")
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: # optional - macaulay2
sage: S = macaulay2(QQ['x,y'])
sage: S.name()
'sage...'
sage: R = S.name("R")
sage: R.name()
'R'
sage: R.vars().cokernel().resolution()
 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: # optional - macaulay2
sage: R = macaulay2.ring('QQ','(x,y)')
sage: f = macaulay2('x^3 + 3*y^11 + 5')
sage: print(f)
 3     11
x  + 3y   + 5
sage: f.sage_polystring()
'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: # optional - macaulay2
sage: S = macaulay2('QQ[a..d]')
sage: R = S / macaulay2('a^3 + b^3 + c^3 + d^3')
sage: X = R.Proj().name('X')
sage: X.structure_sheaf()
doctest:...: DeprecationWarning: The function `structure_sheaf` is deprecated. Use `self.sheaf()` instead.
See https://github.com/sagemath/sage/issues/27848 for details.
OO
  X
sage: X.sheaf()
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: # optional - macaulay2
sage: R = macaulay2("QQ[x]")
sage: P = macaulay2("ZZ/7[symbol x]")
sage: x, = R.gens()
sage: a = x^2 + 1
sage: a = a.substitute(P)
sage: a.sage().parent()
Univariate Polynomial Ring in x over Finite Field of size 7

to_sage(*args, **kwds)#: Deprecated: Use sage() instead. See github issue #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: ExpectFunction

class sage.interfaces.macaulay2.Macaulay2FunctionElement(obj, name)#: Bases: FunctionElement

sage.interfaces.macaulay2.is_Macaulay2Element(x)#

Return True if x is a Macaulay2Element

This function is deprecated; use isinstance() (of sage.interfaces.abc.Macaulay2Element) instead.

EXAMPLES:

sage: from sage.interfaces.macaulay2 import is_Macaulay2Element
sage: is_Macaulay2Element(2)              # optional - macaulay2
doctest:...: DeprecationWarning: the function is_Macaulay2Element is deprecated; use isinstance(x, sage.interfaces.abc.Macaulay2Element) instead
See https://github.com/sagemath/sage/issues/34804 for details.
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'