next | previous | forward | backward | up | top | index | toc | Macaulay2 website
Dmodules :: D-modules tutorial

D-modules tutorial -- Algebraic computations for linear differential equations

D-modules are modules over rings of differential operators over algebraic varieties. This package is mostly concerned with computations in the Weyl algebra, the ring of differential operators over affine space (over a field of characteristic zero). Most algorithms in this package can be found in the book Gr\"obner deformations of Hypergeometric Differential Equations by Saito, Sturmfels and Takayama, hereafter referred to as [SST]. This is also the best place to learn about computational D-module theory. The book Computational Algebraic Geometry with Macaulay2 has a chapter on D-modules and local cohomology. A good introduction to D-module theory is A primer of algebraic D-modules by Coutinho.

The Weyl algebra $D_n$ is the free associative algebra in $2n$ variables $x_1,\dots,x_n$, $\partial_1,\dots,\partial_n$, subject to the following relations: the $x$'s commute with each other; the $\partial$'s commute with each other; $x_i$ commutes with $\partial_j$ if $i\neq j$; and finally, $\partial_i x_i = x_i \partial_i +1$ (the Leibniz rule).

i1 : D1 = QQ[z,dz, WeylAlgebra=>{z=>dz}]

o1 = D1

o1 : PolynomialRing, 1 differential variables

As a reality check, let us confirm that this is not a commutative ring. Here is the Leibniz rule.

i2 : dz*z

o2 = z*dz + 1

o2 : D1

In order to type less, we can use the shortcuts makeWeylAlgebra or makeWA.

i3 : R = QQ[x_1..x_4]

o3 = R

o3 : PolynomialRing
i4 : D4 = makeWA R

o4 = D4

o4 : PolynomialRing, 4 differential variables
i5 : describe D4

o5 = QQ[x ..x , dx ..dx , Degrees => {8:1}, Heft => {1}, MonomialOrder => {MonomialSize => 32}, DegreeRank => 1, WeylAlgebra => {x  => dx , x  => dx , x  => dx , x  => dx }]
         1   4    1    4                                                  {GRevLex => {8:1}  }                                    1      1   2      2   3      3   4      4
                                                                          {Position => Up    }

Elements and ideals are handled in the usual Macaulay2 way. Let us look at the Gauss hypergeometric equation for parameters $a=1, b=2, c=3$.

i6 : use D1

o6 = D1

o6 : PolynomialRing, 1 differential variables
i7 : a = 1, b = 2, c = 3

o7 = (1, 2, 3)

o7 : Sequence
i8 : g = z*(1-z)*dz^2 + (c-(a+b+1)*z)*dz -a*b

        2  2       2
o8 = - z dz  + z*dz  - 4z*dz + 3dz - 2

o8 : D1
i9 : I = ideal g

              2  2       2
o9 = ideal(- z dz  + z*dz  - 4z*dz + 3dz - 2)

o9 : Ideal of D1

The holonomicRank function computes the dimension of the solution space of a linear system of differential equations.

i10 : holonomicRank I

o10 = 2

A-Hypergeometric systems, also known as GKZ systems (see [SST, Chapters 3 and 4]) are implemented.

i11 : use D4

o11 = D4

o11 : PolynomialRing, 4 differential variables
i12 : A = matrix{{1,1,1,1},{0,1,3,4}}

o12 = | 1 1 1 1 |
      | 0 1 3 4 |

               2        4
o12 : Matrix ZZ  <--- ZZ
i13 : b = {1,2}

o13 = {1, 2}

o13 : List
i14 : H = sub(gkz(A,b), vars D4) -- change this when GKZ is modified

                                                                            
o14 = ideal (x dx  + x dx  + x dx  + x dx  - 1, x dx  + 3x dx  + 4x dx  - 2,
              1  1    2  2    3  3    4  4       2  2     3  3     4  4     
      -----------------------------------------------------------------------
          3        2       2     2                            3     2
      - dx  + dx dx , dx dx  - dx dx , - dx dx  + dx dx , - dx  + dx dx )
          3     2  4    1  3     2  4      2  3     1  4      2     1  3

o14 : Ideal of D4

Holonomic D-ideals are analogous to zero-dimensional ideals in polynomial rings (see [SST, Section 1.4]). Let us confirm that our GKZ systems are holonomic.

i15 : isHolonomic H

o15 = true

Once we know our ideal is holonomic, we can compute its holonomic rank. The above is a famous GKZ example because the holonomic rank may change when the parameter vector $b$ is changed.

i16 : holonomicRank H

o16 = 5
i17 : holonomicRank sub(gkz(A,{1,0}), vars D4)

o17 = 4

We can compute the characteristic ideal and singular locus of a D-ideal [SST, Section 1.4]. Note that the output of charIdeal belongs to a commutative ring, the associated graded ring of $D_n$ with respect to the order filtration.

i18 : charIdeal H

                                                                       
o18 = ideal (dx dx  - dx dx , x dx  + 3x dx  + 4x dx , x dx  - 2x dx  -
               2  3     1  4   2  2     3  3     4  4   1  1     3  3  
      -----------------------------------------------------------------------
                3        2       2     2       3     2
      3x dx , dx  - dx dx , dx dx  - dx dx , dx  - dx dx )
        4  4    3     2  4    1  3     2  4    2     1  3

o18 : Ideal of QQ[x ..x , dx ..dx ]
                   1   4    1    4
i19 : singLocus H

                3 3        3 4       2 2 2 2        4 3       3     3  
o19 = ideal(4x x x x  + 27x x x  + 6x x x x  + 27x x x  + 192x x x x  -
              1 2 3 4      1 3 4     1 2 3 4      1 2 4       1 2 3 4  
      -----------------------------------------------------------------------
          4 4
      256x x )
          1 4

o19 : Ideal of D4

The singular locus of a GKZ system is the zero set of a polynomial called the Principal A-determinant, which is a product of discriminants corresponding to faces of the matrix A (see Chapters 8 and 9 of the book Discriminants, Resultants and Multidimensional Determinants by Gelfand, Kapranov and Zelevinsky). Here is how to find the classic cubic discriminant.

i20 : A1 = matrix{{1,1,1,1},{0,1,2,3}}, b1={0,0}

o20 = (| 1 1 1 1 |, {0, 0})
       | 0 1 2 3 |

o20 : Sequence
i21 : H1 = sub(gkz(A1,b1),vars D4)

                                                                         2  
o21 = ideal (x dx  + x dx  + x dx  + x dx , x dx  + 2x dx  + 3x dx , - dx  +
              1  1    2  2    3  3    4  4   2  2     3  3     4  4      3  
      -----------------------------------------------------------------------
                  2
      dx dx , - dx  + dx dx , - dx dx  + dx dx )
        2  4      2     1  3      2  3     1  4

o21 : Ideal of D4
i22 : factor (singLocus H1)_0

                2 2       3     3                     2 2
o22 = (x )(x )(x x  - 4x x  - 4x x  + 18x x x x  - 27x x )
        4   1   2 3     1 3     2 4      1 2 3 4      1 4

o22 : Expression of class Product

See also