Connection Matrices in Macaulay2

This page contains the code and a minimal documentation for our new Macaulay2 package \({\tt ConnectionMatrices}\). Since M2 release 1.25.05 it is part
of the official M2 code base.
Paul Görlach, Joris Koefler, Anna-Laura Sattelberger, Mahrud Sayrafi, Hendrik Schroeder, Nicolas Weiss, and Francesca Zaffalon: “Connection Matrices in Macaulay2”
ARXIV: https://arxiv.org/abs/2504.01362 M2-PAGE: ConnectionMatrices

1. Introduction

Systems of homogeneous, linear partial differential equations (PDEs) with polynomial coefficients are encoded by left ideals in the Weyl algebra, denoted

\[D_n=\mathbb{C}[x_1,\ldots,x_n]\langle \partial_1,\ldots,\partial_n \rangle.\]

Such systems can be systematically written as a first-order matrix system, i.e., in “connection form” \(\operatorname{d} - A\wedge \,\), by utilizing Gröbner bases in the Weyl algebra. In the case of a single ordinary differential equation (ODE), the respective matrix is known under the name of “companion matrix”.

The systematic computation of connection matrices in software requires Gröbner bases in the rational Weyl algebra

\[R_n=\mathbb{C}(x_1,\ldots,x_n)\langle \partial_1,\ldots,\partial_n \rangle.\]

These, however, are by now not available in the \(D\)-module packages in standard open-source computer algebra software. Our new Macaulay2 package \({\tt ConnectionMatrices}\) is intended to fill this gap.

An accompanying article which provides the theoretical background will be available on the arxiv. The implemented functionalities include the computation of \({\tt connectionMatrices}\) of \(D\)-ideals for elimination term orders on the Weyl algebra with respect to positive weight vectors. In particular, this required the implementation of the \({\tt normalForm}\) algorithm over the rational Weyl algebra. We also implemented the \({\tt gaugeTransformation}\) for carrying out changes of basis over the field of rational functions. We also allow for the dependence on parameters, such as a “small parameter” \(\varepsilon\), as is commonly used for the dimensional regularization of Feynman integrals in particle physics.

2. Installation

Our package has been added to Macaulay2 in release 1.25.05. So all you need to do is to update your M2 installation and you can directly start using the package as described in the minimal example below.

2.1. (Old) Installation (before M2 version 1.25.05)

If for some reason, you cannot update to M2 release 1.25.05., you can download a snapshot of our package (as of April 2025) below.

In order to install the package, start an M2 session in the folder containing \({\tt ConnectionMatrices.m2}\) and execute

i1 : installPackage "ConnectionMatrices"

You should see M2 building the examples in the documentation which should look something like

 -- making example results for "normalForm"            -- .557581s elapsed
 -- making example results for "connectionMatrices"    -- .573788s elapsed
 -- making example results for "gaugeTransform"        -- .578373s elapsed

o1 = ConnectionMatrices

o1 : Package

2.2 Minimal Example

Now you should be able to use the \({\tt ConnectionMatrices}\) package to compute connection matrices for your favorite \({D}\)-ideals.

i2 : needsPackage "ConnectionMatrices";

i3 : D = makeWA(QQ[x]);

i4 : I = ideal (dx + x*dx*dx);

o4 : Ideal of D

i5 : (connectionMatrices I) # 0

o5 = | 0 1      |
     | 0 (-1)/x |

                          2                  2
o5 : Matrix (frac(QQ[x]))  <-- (frac(QQ[x]))

For more interesting examples and details on all implemented functionalities please refer to the documentation section below.

3. Documentation

The official documentation to our package \({\tt ConnectionMatrices}\) is now available at the following link.

It is also possible to view the documentation locally within M2. Make sure you have installed the package / have the current M2 version and run:

viewHelp "ConnectionMatrices"

3.1 Implemented Methods

The below links will send you to the official M2 website:

Working with the rational Weyl algebra

  • normalForm – computes the normal form within the rational Weyl algebra

  • standardMonomials – computes the standard monomials for a \(D_n\)-ideal

  • baseFractionField – extracts the fraction field of the base polynomial ring of a Weyl algebra

Computing and displaying \(D\)-ideals in connection form

Changing basis of a system of connection matrices

  • gaugeMatrix – computes the base change over the field of rational functions

  • gaugeTransform – computes the gauge transform of a system of connection matrices

  • isEpsilonFactorized – checks whether a system of connection matrices is in \(\epsilon\)-factorized form

Testing integrability of a list of matrices

  • isIntegrable – checks whether a list of matrices fulfills the integrability conditions

Examples

Project page created: 05/04/2025

Project contributors: Paul Görlach (paul.goerlach@ovgu.de), Joris Koefler (joris.koefler@mis.mpg.de), Anna-Laura Sattelberger (anna-laura.sattelberger@mis.mpg.de), Mahrud Sayrafi (mahrud@fields.utoronto.ca), Hendrik Schroeder (h.schroeder@tu-berlin.de), Nicolas Weiss (nicolas.weiss@mis.mpg.de), and Francesca Zaffalon (francesca.zaffalon@mis.mpg.de)

Corresponding author of this page: Nicolas Weiss, nicolas.weiss@mis.mpg.de

Software used: Macaulay2 (Version 1.24.11)

System setup used: MacBook Air with macOS 15.3.2, Processor Apple M3, Memory 24 GB

License for code of this project page: MIT License (https://spdx.org/licenses/MIT.html)

License for all other content of this project page: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

Last updated 26/05/2025.