This is Dmodules.info, produced by Macaulay2, version 1.26.06

Dmodules -- D-modules package collection
****************************************

Description
===========

To begin, read the D-modules tutorial.

Packages included in this collection

  * WeylAlgebras -- D-modules
  * HolonomicSystems -- Holonomic Systems
  * BernsteinSato -- Bernstein-Sato

Authors
=======

  * Anton Leykin <leykin@math.gatech.edu>
  * Harrison Tsai

Version
=======

This documentation describes version 1.4.1.1 of Dmodules, released February
2023.

Citation
========

If you have used this package in your research, please cite it as follows:

+--------------------------------------------------------------------+
|@misc{DmodulesSource,                                               |
|  title = {{Dmodules: A \emph{Macaulay2} package. Version~1.4.1.1}},|
|  author = {Anton Leykin and Harrison Tsai},                        |
|  howpublished = {A \emph{Macaulay2} package available at           |
|    "http://people.math.gatech.edu/~aleykin3/Dmodules"}             |
|}                                                                   |
|                                                                    |
+--------------------------------------------------------------------+

For the programmer
==================

The object Dmodules, is a package (Macaulay2Doc),
defined in Dmodules.m2.

-------------------------------------------------------------------------------

The source of this document is in Dmodules.m2:142:0.

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öbner deformations of Hypergeometric Differential Equations by Saito,
Sturmfels and Takayama, hereafter referred to as [SST (see
https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf )]. 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 variable(s)|
+-----------------------------------------------+

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 variable(s)                              |
+-----------------------------------------------------------------------------+
|i5 : describe D4                                                             |
|                                                                             |
|o5 = QQ[x ..x , dx ..dx , Degrees => {8:1}, Heft => {1}, WeylAlgebra => {{x ,|
|         1   4    1    4                                                   1 |
|-----------------------------------------------------------------------------|
|dx }, {x , dx }, {x , dx }, {x , dx }}]                                      |
|  1     2    2     3    3     4    4                                         |
+-----------------------------------------------------------------------------+

Elements and ideals are handled in the usual Macaulay2 way. Let us look at the
Gauss hypergeometric equation (see
https://en.wikipedia.org/wiki/Hypergeometric_function#The_hypergeometric_
differential_equation ) for parameters $a=1, b=2, c=3$.

+-----------------------------------------------+
|i6 : use D1                                    |
|                                               |
|o6 = D1                                        |
|                                               |
|o6 : PolynomialRing, 1 differential variable(s)|
+-----------------------------------------------+
|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 (see
https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), Chapters 3 and 4]) are
implemented.

+-----------------------------------------------------------------------------+
|i11 : needsPackage "HolonomicSystems"                                        |
|                                                                             |
|o11 = HolonomicSystems                                                       |
|                                                                             |
|o11 : Package                                                                |
+-----------------------------------------------------------------------------+
|i12 : use D4                                                                 |
|                                                                             |
|o12 = D4                                                                     |
|                                                                             |
|o12 : PolynomialRing, 4 differential variable(s)                             |
+-----------------------------------------------------------------------------+
|i13 : A = matrix{{1,1,1,1},{0,1,3,4}}                                        |
|                                                                             |
|o13 = | 1 1 1 1 |                                                            |
|      | 0 1 3 4 |                                                            |
|                                                                             |
|               2       4                                                     |
|o13 : Matrix ZZ  <-- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i14 : b = {1,2}                                                              |
|                                                                             |
|o14 = {1, 2}                                                                 |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+
|i15 : H = gkz(A,b, D4)                                                       |
|                                                                             |
|                                                                             |
|o15 = 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     |
|                                                                             |
|o15 : Ideal of D4                                                            |
+-----------------------------------------------------------------------------+

Holonomic D-ideals are analogous to zero-dimensional ideals in polynomial rings
(see [SST (see https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), Section
1.4]). Let us confirm that our GKZ systems are holonomic.

+-------------------+
|i16 : isHolonomic H|
|                   |
|o16 = 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.

+----------------------------------------------+
|i17 : holonomicRank H                         |
|                                              |
|o17 = 5                                       |
+----------------------------------------------+
|i18 : holonomicRank sub(gkz(A,{1,0}), vars D4)|
|                                              |
|o18 = 4                                       |
+----------------------------------------------+

We can compute the characteristic ideal and singular locus of a D-ideal [SST
(see https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), 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.

+-----------------------------------------------------------------------------+
|i19 : charIdeal H                                                            |
|                                                                             |
|                                                                             |
|o19 = 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                    |
|                                                                             |
|o19 : Ideal of QQ[x ..x , dx ..dx ]                                          |
|                   1   4    1    4                                           |
+-----------------------------------------------------------------------------+
|i20 : singLocus H                                                            |
|                                                                             |
|                3 3        3 4       2 2 2 2        4 3       3     3        |
|o20 = 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                                                                |
|                                                                             |
|o20 : 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.

+-----------------------------------------------------------------------------+
|i21 : A1 = matrix{{1,1,1,1},{0,1,2,3}}, b1={0,0}                             |
|                                                                             |
|o21 = (| 1 1 1 1 |, {0, 0})                                                  |
|       | 0 1 2 3 |                                                           |
|                                                                             |
|o21 : Sequence                                                               |
+-----------------------------------------------------------------------------+
|i22 : H1 = sub(gkz(A1,b1),vars D4)                                           |
|                                                                             |
|                                                                         2   |
|o22 = 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                              |
|                                                                             |
|o22 : Ideal of D4                                                            |
+-----------------------------------------------------------------------------+
|i23 : factor (singLocus H1)_0                                                |
|                                                                             |
|                2 2       3     3                     2 2                    |
|o23 = (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                    |
|                                                                             |
|o23 : Expression of class Product                                            |
+-----------------------------------------------------------------------------+

See also
========

  * Dmodules -- D-modules
-------------------------------------------------------------------------------

The source of this document is in Dmodules.m2:142:0.