This is HolonomicSystems.info, produced by Macaulay2, version 1.22

HolonomicSystems -- Examples of Holonomic D-modules
***************************************************

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

Some examples of D-modules
--------------------------

  * gkz -- create the A-hypergeometric system of Gelfand, Kapranov
    and Zelevinsky (GKZ)
  * eulerOperators -- Euler Operators
  * toricIdealPartials -- create the toric ideal of
    an integer matrix
  * AppellF1 -- Appell F1 system of PDE's

See Canonical Series Tutorial, -- Computing series solutions to regular holonomic systems
----------------------------------------------------------------------------------------------------------------------

  * distraction -- the image in the thetaRing of a
    torus-fixed element or ideal in a Weyl algebra
  * cssExpts -- the exponents of the canonical series
    solutions of I in the direction of a weight vector
  * cssExptsMult -- the exponents and multiplicities of
    the canonical series solutions
  * isTorusFixed -- checks if an ideal in a Weyl algebra
    is torus-fixed
  * solveFrobeniusIdeal -- solving Frobenius ideals

Differential Operators
----------------------

  * diffOps -- differential operators of up to the given order
    for a quotient polynomial ring

Authors
=======

  * Mahrud Sayrafi (see https://math.umn.edu/~mahrud ) <mahrud@umn.edu>
  * Christine Berkesch (see https://math.umn.edu/~cberkesc ) <cberkesc@umn.edu>
  * Anton Leykin <leykin@math.gatech.edu>
  * Harrison Tsai

Version
=======

This documentation describes version 1.0 of HolonomicSystems.

Source code
===========

The source code from which this documentation is derived is in the file
HolonomicSystems.m2 (see common/share/Macaulay2/HolonomicSystems.m2 ). The
auxiliary files accompanying it are in the directory HolonomicSystems/ (see
common/share/Macaulay2/HolonomicSystems/ ).

Exports
=======

  * Functions and commands
      * AppellF1 -- Appell F1 system of PDE's
      * createThetaRing (missing documentation)
      * cssExpts -- the exponents of the canonical series
        solutions of I in the direction of a weight vector
      * cssExptsMult -- the exponents and multiplicities
        of the canonical series solutions
      * cssLeadTerm -- lead term of the canonical series
        solutions of I
      * diffOps -- differential operators of up to the given
        order for a quotient polynomial ring
      * distraction -- the image in the thetaRing of a
        torus-fixed element or ideal in a Weyl algebra
      * eulerOperators -- Euler Operators
      * gkz -- create the A-hypergeometric system of Gelfand,
        Kapranov and Zelevinsky (GKZ)
      * indicialIdeal -- the image in the thetaRing of an
        indicial ideal in a Weyl algebra
      * isTorusFixed -- checks if an ideal in a Weyl
        algebra is torus-fixed
      * nilssonSupport (missing documentation)
      * putWeylAlgebra -- transforms output of diffOps
        into elements of Weyl algebra
      * solveFrobeniusIdeal -- solving Frobenius
        ideals
      * toricIdealPartials -- create the toric ideal
        of an integer matrix
      * truncatedCanonicalSeries (missing documentation)
  * Methods
      * "AppellF1(List)" -- see AppellF1, -- Appell F1 system
        of PDE's
      * "cssExpts(Ideal,List)" -- see cssExpts, -- the
        exponents of the canonical series solutions of I in the direction of a
        weight vector
      * "cssExptsMult(Ideal,List)" -- see cssExptsMult, --
        the exponents and multiplicities of the canonical series solutions
      * "cssLeadTerm(Ideal,List)" -- see cssLeadTerm, --
        lead term of the canonical series solutions of I
      * "diffOps(Ideal,ZZ)" -- see diffOps, -- differential
        operators of up to the given order for a quotient polynomial ring
      * "diffOps(RingElement,ZZ)" -- see diffOps, --
        differential operators of up to the given order for a quotient
        polynomial ring
      * "distraction(Ideal,Ring)" -- see distraction, -- the
        image in the thetaRing of a torus-fixed element or ideal in a Weyl
        algebra
      * "distraction(RingElement,Ring)" -- see distraction,
        -- the image in the thetaRing of a torus-fixed element or ideal in a
        Weyl algebra
      * "eulerOperators(Matrix,List,PolynomialRing)" -- see
        eulerOperators, -- Euler Operators
      * "eulerOperators(Matrix,PolynomialRing)" -- see eulerOperators,
        -- Euler Operators
      * "gkz(Matrix,List)" -- see gkz, -- create the
        A-hypergeometric system of Gelfand, Kapranov and Zelevinsky (GKZ)
      * "gkz(Matrix,List,PolynomialRing)" -- see gkz, -- create the
        A-hypergeometric system of Gelfand, Kapranov and Zelevinsky (GKZ)
      * "indicialIdeal(Ideal,List)" -- see indicialIdeal,
        -- the image in the thetaRing of an indicial ideal in a Weyl algebra
      * "isTorusFixed(Ideal)" -- see isTorusFixed, --
        checks if an ideal in a Weyl algebra is torus-fixed
      * "putWeylAlgebra(HashTable)" -- see putWeylAlgebra,
        -- transforms output of diffOps into elements of Weyl
        algebra
      * "solveFrobeniusIdeal(Ideal)" -- see solveFrobeniusIdeal,
        -- solving Frobenius ideals
      * "solveFrobeniusIdeal(Ideal,Ring)" -- see solveFrobeniusIdeal,
        -- solving Frobenius ideals
      * "toricIdealPartials(Matrix,PolynomialRing)" -- see
        toricIdealPartials, -- create the toric ideal of an
        integer matrix
  * Symbols
      * "Vars" -- see AppellF1, -- Appell F1 system of PDE's
      * "BasisElts" -- see diffOps, -- differential operators of
        up to the given order for a quotient polynomial ring
      * "PolyGens" -- see diffOps, -- differential operators of
        up to the given order for a quotient polynomial ring
      * ThetaRing (missing documentation)
      * WtoT (missing documentation)

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

The object HolonomicSystems, is a package (Macaulay2Doc).

gkz -- create the A-hypergeometric system of Gelfand, Kapranov and Zelevinsky (GKZ)
***********************************************************************************

Synopsis
========

  * Usage:
        gkz(A,b)
        gkz(A,b,D)
  * Inputs:
      * A, a matrix (Macaulay2Doc),
      * b, a list (Macaulay2Doc), parameter vector;
      * D, a polynomial ring (Macaulay2Doc), a Weyl
        algebra;
  * Outputs:
      * an ideal (Macaulay2Doc), the GKZ hypergeometric system
        associated to the matrix $A$ and the parameter vector $b$ in the Weyl
        algebra $D$

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

The GKZ hypergeometric system of PDE's associated to a $d \times n$ integer
matrix A is an ideal in the Weyl algebra $D_n$ over $\mathbb{C}$ with
generators $x_1,\dots,x_n$ and $\partial_1,\dots,\partial_n$. It consists of
the toric ideal $I_A$ in the polynomial subring
$\mathbb{C}[\partial_1,...,\partial_n]$ and Euler relations given by the
entries of the vector (A $\theta$ - b), where $\theta$ is the vector
$(\theta_1,...,\theta_n)^t$, and $\theta_i = x_i \partial_i$. A field of
characteristic zero may be used instead of  $\mathbb{C}$. For more details, see
[SST (see https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), Chapters 3
and 4].

+-----------------------------------------------------------------------------+
|i1 : A = matrix{{1,1,1},{0,1,2}}                                             |
|                                                                             |
|o1 = | 1 1 1 |                                                               |
|     | 0 1 2 |                                                               |
|                                                                             |
|              2        3                                                     |
|o1 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i2 : b = {3,4}                                                               |
|                                                                             |
|o2 = {3, 4}                                                                  |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : I = gkz (A,b)                                                           |
|                                                                             |
|                                                         2                   |
|o3 = ideal (x D  + x D  + x D  - 3, x D  + 2x D  - 4, - D  + D D )           |
|             1 1    2 2    3 3       2 2     3 3         2    1 3            |
|                                                                             |
|o3 : Ideal of QQ[x ..x , D ..D ]                                             |
|                  1   3   1   3                                              |
+-----------------------------------------------------------------------------+
|i4 : describe ring I                                                         |
|                                                                             |
|o4 = QQ[x ..x , D ..D , Degrees => {6:1}, Heft => {1}, WeylAlgebra => {{x ,  |
|         1   3   1   3                                                   1   |
|-----------------------------------------------------------------------------|
|D }, {x , D }, {x , D }}]                                                    |
| 1     2   2     3   3                                                       |
+-----------------------------------------------------------------------------+

The ambient Weyl algebra can be determined as an input.

+--------------------------------------------------------------------------+
|i5 : D = makeWA(QQ[x_1..x_3])                                             |
|                                                                          |
|o5 = D                                                                    |
|                                                                          |
|o5 : PolynomialRing, 3 differential variable(s)                           |
+--------------------------------------------------------------------------+
|i6 : gkz(A,b,D)                                                           |
|                                                                          |
|                                                               2          |
|o6 = ideal (x dx  + x dx  + x dx  - 3, x dx  + 2x dx  - 4, - dx  + dx dx )|
|             1  1    2  2    3  3       2  2     3  3          2     1  3 |
|                                                                          |
|o6 : Ideal of D                                                           |
+--------------------------------------------------------------------------+

One may separately produce the toric ideal and the Euler operators.

+----------------------------------------------------+
|i7 : toricIdealPartials(A,D)                        |
|                                                    |
|               2                                    |
|o7 = ideal(- dx  + dx dx )                          |
|               2     1  3                           |
|                                                    |
|o7 : Ideal of QQ[dx ..dx ]                          |
|                   1    3                           |
+----------------------------------------------------+
|i8 : eulerOperators(A,b,D)                          |
|                                                    |
|o8 = {x dx  + x dx  + x dx  - 3, x dx  + 2x dx  - 4}|
|       1  1    2  2    3  3       2  2     3  3     |
|                                                    |
|o8 : List                                           |
+----------------------------------------------------+

Caveat
======

gkz(A,b) always returns a different ring and will use variables x_1,...,x_n,
D_1,...D_n.

See also
========

  * AppellF1 -- Appell F1 system of PDE's

Ways to use gkz :
=================

  * "gkz(Matrix,List)"
  * "gkz(Matrix,List,PolynomialRing)"

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

The object gkz, is a method function (Macaulay2Doc).

eulerOperators -- Euler Operators
*********************************

Synopsis
========

  * Usage:
        eulerOperators(A, D)
        eulerOperators(A, b, D)
  * Inputs:
      * A, a matrix (Macaulay2Doc),
      * b, a list (Macaulay2Doc),
      * D, a polynomial ring (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc), of Euler operators

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

Given a $d \times n$ integer matrix $A = (a_{ij})$ and a Weyl algebra in $n$
variables, produce the $d$ corresponding Euler operators $E_i = \sum_{j=1}^n
a_{ij}x_jdj$. An optional list $b$ imposes a multigrading so that one can look
for solutions to the Euler operatros of multidegree $b$.

+-----------------------------------------------------------+
|i1 : D = makeWeylAlgebra(QQ[x,y,z])                        |
|                                                           |
|o1 = D                                                     |
|                                                           |
|o1 : PolynomialRing, 3 differential variable(s)            |
+-----------------------------------------------------------+
|i2 : A = matrix{{2,-7,5},{14,8,-1}}                        |
|                                                           |
|o2 = | 2  -7 5  |                                          |
|     | 14 8  -1 |                                          |
|                                                           |
|              2        3                                   |
|o2 : Matrix ZZ  <--- ZZ                                    |
+-----------------------------------------------------------+
|i3 : L = eulerOperators(A,D)                               |
|                                                           |
|o3 = {2x*dx - 7y*dy + 5z*dz, 14x*dx + 8y*dy - z*dz}        |
|                                                           |
|o3 : List                                                  |
+-----------------------------------------------------------+
|i4 : Example                                               |
|                                                           |
|o4 = Example                                               |
|                                                           |
|o4 : Symbol                                                |
+-----------------------------------------------------------+
|i5 : D = makeWeylAlgebra(QQ[x,y,z])                        |
|                                                           |
|o5 = D                                                     |
|                                                           |
|o5 : PolynomialRing, 3 differential variable(s)            |
+-----------------------------------------------------------+
|i6 : A = matrix{{2,-7,5},{14,8,-1}}                        |
|                                                           |
|o6 = | 2  -7 5  |                                          |
|     | 14 8  -1 |                                          |
|                                                           |
|              2        3                                   |
|o6 : Matrix ZZ  <--- ZZ                                    |
+-----------------------------------------------------------+
|i7 : b = {2,-3}                                            |
|                                                           |
|o7 = {2, -3}                                               |
|                                                           |
|o7 : List                                                  |
+-----------------------------------------------------------+
|i8 : L = eulerOperators(A,b,D)                             |
|                                                           |
|o8 = {2x*dx - 7y*dy + 5z*dz - 2, 14x*dx + 8y*dy - z*dz + 3}|
|                                                           |
|o8 : List                                                  |
+-----------------------------------------------------------+

Caveat
======

Ring input should be a Weyl algebra. Matrix input should have as many columns
as variables of the Weyl algebra. List should have as many entries as there are
rows of matrix.

See also
========

  * gkz -- create the A-hypergeometric system of Gelfand, Kapranov
    and Zelevinsky (GKZ)

Ways to use eulerOperators :
============================

  * "eulerOperators(Matrix,List,PolynomialRing)"
  * "eulerOperators(Matrix,PolynomialRing)"

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

The object eulerOperators, is a method function (Macaulay2Doc).

toricIdealPartials -- create the toric ideal of an integer matrix
*****************************************************************

Synopsis
========

  * Usage:
        toricIdealPartials(A,D)
  * Inputs:
      * A, a matrix (Macaulay2Doc),
      * D, a polynomial ring (Macaulay2Doc),
  * Outputs:
      * an ideal (Macaulay2Doc), the toric ideal of the matrix $A$
        in the polynomial ring of the partials inside of the Weyl algerba $D$.

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

A $d \times n$ integer matrix $A$ determines a GKZ hypergeometric system of
PDEs in the Weyl algebra $D_n$ over $\mathbb{C}$.  The matrix $A$ is associated
to the toric ideal $I_A$ in the polynomial subring
$\mathbb{C}[\partial_1,...,\partial_n]$ of $D$.  A field of characteristic zero
may be used instead of  $\mathbb{C}$. For more details, see [SST (see
https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), Chapters 3 and 4].

+------------------------------------------------+
|i1 : A = matrix{{1,2,0},{-1,1,3}}               |
|                                                |
|o1 = | 1  2 0 |                                 |
|     | -1 1 3 |                                 |
|                                                |
|              2        3                        |
|o1 : Matrix ZZ  <--- ZZ                         |
+------------------------------------------------+
|i2 : D = makeWA(QQ[x_1..x_3])                   |
|                                                |
|o2 = D                                          |
|                                                |
|o2 : PolynomialRing, 3 differential variable(s) |
+------------------------------------------------+
|i3 : I = toricIdealPartials(A,D)                |
|                                                |
|             2                                  |
|o3 = ideal(dx dx  - dx )                        |
|             1  3     2                         |
|                                                |
|o3 : Ideal of QQ[dx ..dx ]                      |
|                   1    3                       |
+------------------------------------------------+
|i4 : describe ring I                            |
|                                                |
|o4 = QQ[dx ..dx , Degrees => {3:1}, Heft => {1}]|
|          1    3                                |
+------------------------------------------------+

Ways to use toricIdealPartials :
================================

  * "toricIdealPartials(Matrix,PolynomialRing)"

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

The object toricIdealPartials, is a method function (Macaulay2Doc).

AppellF1 -- Appell F1 system of PDE's
*************************************

Synopsis
========

  * Usage:
        AppellF1 {a0,a1,a2,a3}
  * Inputs:
      * a list (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Vars => ..., default value Global
  * Outputs:
      * an ideal (Macaulay2Doc), which represents Appell F1 (see
        https://en.wikipedia.org/wiki/Appell_series#Derivatives_and_
        differential_equations ) system of PDE's associated to the parameters
        a0, a1, a2, and a3.

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

+-----------------------------------------------------------------------------+
|i1 : w = {1,4/5,-2,3/2}                                                      |
|                                                                             |
|         4      3                                                            |
|o1 = {1, -, -2, -}                                                           |
|         5      2                                                            |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : I = AppellF1 w                                                          |
|                                                                             |
|               3  2    2           2  2               14 2     4             |
|o2 = ideal (- x Dx  - x y*Dx*Dy + x Dx  + x*y*Dx*Dy - --x Dx - -x*y*Dy +     |
|                                                       5       5             |
|     ------------------------------------------------------------------------|
|     3       4        2         3  2                2  2             3       |
|     -x*Dx - -x, - x*y Dx*Dy - y Dy  + x*y*Dx*Dy + y Dy  + 2x*y*Dx + -y*Dy + |
|     2       5                                                       2       |
|     ------------------------------------------------------------------------|
|                                   4                                         |
|     2y, x*Dx*Dy - y*Dx*Dy + 2Dx + -Dy)                                      |
|                                   5                                         |
|                                                                             |
|o2 : Ideal of QQ[x, y, Dx, Dy]                                               |
+-----------------------------------------------------------------------------+

Caveat
======

AppellF1 always returns a different ring and will use variables x and y. Input
should be a List of 4 numbers.

See also
========

  * gkz -- create the A-hypergeometric system of Gelfand, Kapranov
    and Zelevinsky (GKZ)

Ways to use AppellF1 :
======================

  * "AppellF1(List)"

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

The object AppellF1, is a method function with options (Macaulay2Doc).

Canonical Series Tutorial -- Computing series solutions to regular holonomic systems
************************************************************************************

If D/I is a regular holonomic D-module, the solutions of the system of
differential equations I can be written as Nilsson series (Puiseux series with
logarithms). The constructive version of this result is the canonical series
method [SST, Sections 2.5, 2.6 (see
https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf )]. In this tutorial, we
illustrate an implementation of this method.

If the input ideal I is not regular, this method is not guaranteed to produce
convergent series, or even holonomicRank(I) formal power series solutions of I.
There currently exists no computational method to verify whether D/I is a
regular holonomic D-module. In the case of GKZ systems, regularity has been
characterized in terms of the input matrix.

Contains the following functions:

Currently, this contains the computation of exponents with respect to a weight
vector. Completing the canonical series computation is in the future. To
compute the exponents for a D-ideal I with respect to w, do as follows. Compute
the initial ideal of I with respect to w. Introduce the subring of D consisting
of polynomials in $\theta_1 = x_1 \partial_1, ... , \theta_n= x_n \partial_n$.
This is a commutative polynomial subring of D, referred to here as thetaRing.
The indicial ideal of I with respect to w is produced by extending the initial
ideal to the ring of differential operators with rational function
coefficients, and contract to thetaRing. The exponents of I with respect to w
are the roots of the indicial ideal, counted with multiplicities.

+-----------------------------------------------------------------------------+
|i1 : needsPackage "Dmodules"                                                 |
|                                                                             |
|o1 = Dmodules                                                                |
|                                                                             |
|o1 : Package                                                                 |
+-----------------------------------------------------------------------------+
|i2 : R1 = QQ[z]                                                              |
|                                                                             |
|o2 = R1                                                                      |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i3 : W1 = makeWA R1                                                          |
|                                                                             |
|o3 = W1                                                                      |
|                                                                             |
|o3 : PolynomialRing, 1 differential variable(s)                              |
+-----------------------------------------------------------------------------+
|i4 : a=1/2                                                                   |
|                                                                             |
|     1                                                                       |
|o4 = -                                                                       |
|     2                                                                       |
|                                                                             |
|o4 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i5 : b=3                                                                     |
|                                                                             |
|o5 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i6 : c=5/3                                                                   |
|                                                                             |
|     5                                                                       |
|o6 = -                                                                       |
|     3                                                                       |
|                                                                             |
|o6 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i7 : J = ideal(z*(1-z)*dz^2+(c-(a+b+1)*z)*dz-a*b) -- the Gauss hypergeometric|
|                                                                             |
|              2  2       2   9       5     3                                 |
|o7 = ideal(- z dz  + z*dz  - -z*dz + -dz - -)                                |
|                             2       3     2                                 |
|                                                                             |
|o7 : Ideal of W1                                                             |
|-----------------------------------------------------------------------------|
|equation, exponents 0, 1-c                                                   |
+-----------------------------------------------------------------------------+
|i8 : cssExpts(J,{1})                                                         |
|                                                                             |
|              2                                                              |
|o8 = {{0}, {- -}}                                                            |
|              3                                                              |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : inw(J,{-1,1})                                                           |
|                                                                             |
|                2                                                            |
|o9 = ideal(6z*dz  + 10dz)                                                    |
|                                                                             |
|o9 : Ideal of W1                                                             |
+-----------------------------------------------------------------------------+
|i10 : distraction(oo,QQ[s])                                                  |
|                                                                             |
|              2                                                              |
|o10 = ideal(6s  + 4s)                                                        |
|                                                                             |
|o10 : Ideal of QQ[s]                                                         |
+-----------------------------------------------------------------------------+
|i11 : factor oo_0                                                            |
|                                                                             |
|o11 = (s)(3s + 2)(2)                                                         |
|                                                                             |
|o11 : Expression of class Product                                            |
+-----------------------------------------------------------------------------+
|i12 : c=1  -- Now we have a single exponent of multiplicity 2                |
|                                                                             |
|o12 = 1                                                                      |
+-----------------------------------------------------------------------------+
|i13 : J = ideal(z*(1-z)*dz^2+(c-(a+b+1)*z)*dz-a*b)                           |
|                                                                             |
|               2  2       2   9            3                                 |
|o13 = ideal(- z dz  + z*dz  - -z*dz + dz - -)                                |
|                              2            2                                 |
|                                                                             |
|o13 : Ideal of W1                                                            |
+-----------------------------------------------------------------------------+
|i14 : cssExpts(J,{1})                                                        |
|                                                                             |
|o14 = {{0}}                                                                  |
|                                                                             |
|o14 : List                                                                   |
+-----------------------------------------------------------------------------+
|i15 : cssExptsMult(J,{1})                                                    |
|                                                                             |
|o15 = {{2, {0}}}                                                             |
|                                                                             |
|o15 : List                                                                   |
+-----------------------------------------------------------------------------+

The first step is to rewrite elements of the initial ideal in a terms of the
thetaRing, in a way that will allow us to easily extend and contract see [SST]

+-----------------------------------------------------------------------------+
|i16 : R2 = QQ[x_1..x_3]                                                      |
|                                                                             |
|o16 = R2                                                                     |
|                                                                             |
|o16 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i17 : W2 = makeWA R2                                                         |
|                                                                             |
|o17 = W2                                                                     |
|                                                                             |
|o17 : PolynomialRing, 3 differential variable(s)                             |
+-----------------------------------------------------------------------------+
|i18 : gens W2                                                                |
|                                                                             |
|o18 = {x , x , x , dx , dx , dx }                                            |
|        1   2   3    1    2    3                                             |
|                                                                             |
|o18 : List                                                                   |
+-----------------------------------------------------------------------------+
|i19 : thetaRing = QQ[t_1,t_2,t_3] -- sets variable names t_i = x_i\dx_i      |
|                                                                             |
|o19 = thetaRing                                                              |
|                                                                             |
|o19 : PolynomialRing                                                         |
+-----------------------------------------------------------------------------+
|i20 : f1= x_1*dx_1 -- this element already belongs to thetaRing              |
|                                                                             |
|o20 = x dx                                                                   |
|       1  1                                                                  |
|                                                                             |
|o20 : W2                                                                     |
+-----------------------------------------------------------------------------+
|i21 : distraction(f1,thetaRing)  -- checks out                               |
|                                                                             |
|o21 = t                                                                      |
|       1                                                                     |
|                                                                             |
|o21 : thetaRing                                                              |
+-----------------------------------------------------------------------------+
|i22 : f2 = x_1^3*dx_1^3 -- this is a descending factorial in the theta       |
|                                                                             |
|       3  3                                                                  |
|o22 = x dx                                                                   |
|       1  1                                                                  |
|                                                                             |
|o22 : W2                                                                     |
|-----------------------------------------------------------------------------|
|variables                                                                    |
+-----------------------------------------------------------------------------+
|i23 : distraction(f2,thetaRing)                                              |
|                                                                             |
|       3     2                                                               |
|o23 = t  - 3t  + 2t                                                          |
|       1     1     1                                                         |
|                                                                             |
|o23 : thetaRing                                                              |
+-----------------------------------------------------------------------------+
|i24 : factor oo   -- now it looks like a descending factorial                |
|                                                                             |
|o24 = (t )(t  - 2)(t  - 1)                                                   |
|        1   1       1                                                        |
|                                                                             |
|o24 : Expression of class Product                                            |
+-----------------------------------------------------------------------------+
|i25 : f = x_1^2*x_2^2*x_3*dx_1*dx_2^2*dx_3^2                                 |
|                                                                             |
|       2 2       2  2                                                        |
|o25 = x x x dx dx dx                                                         |
|       1 2 3  1  2  3                                                        |
|                                                                             |
|o25 : W2                                                                     |
+-----------------------------------------------------------------------------+
|i26 : distraction(f,thetaRing)                                               |
|                                                                             |
|         2 2      2          2                                               |
|o26 = t t t  - t t t  - t t t  + t t t                                       |
|       1 2 3    1 2 3    1 2 3    1 2 3                                      |
|                                                                             |
|o26 : thetaRing                                                              |
+-----------------------------------------------------------------------------+

Here is an example that can be continued when more functions are implemented.
This is worked out as [page 138, ex 3.5.3, SST].

+--------------------------------------------------------------------+
|i27 : A = matrix{{1,1,1},{0,1,2}}                                   |
|                                                                    |
|o27 = | 1 1 1 |                                                     |
|      | 0 1 2 |                                                     |
|                                                                    |
|               2        3                                           |
|o27 : Matrix ZZ  <--- ZZ                                            |
+--------------------------------------------------------------------+
|i28 : I = gkz(A,{10,8})                                             |
|                                                                    |
|                                                           2        |
|o28 = ideal (x D  + x D  + x D  - 10, x D  + 2x D  - 8, - D  + D D )|
|              1 1    2 2    3 3        2 2     3 3         2    1 3 |
|                                                                    |
|o28 : Ideal of QQ[x ..x , D ..D ]                                   |
|                   1   3   1   3                                    |
+--------------------------------------------------------------------+
|i29 : holonomicRank(I)                                              |
|                                                                    |
|o29 = 2                                                             |
+--------------------------------------------------------------------+
|i30 : cssExpts(I,{1,0,0})                                           |
|                                                                    |
|o30 = {{2, 8, 0}, {0, 12, -2}}                                      |
|                                                                    |
|o30 : List                                                          |
+--------------------------------------------------------------------+

In this case, the series corresponding to the exponent (2,8,0) is
logarithm-free (actually, this is a hypergeometric polynomial), while the
series corresponding to (0,12,-2) has logarithms. [SST, page 138] has the
polynomial, and four terms of the logarithmic series.

cssExpts -- the exponents of the canonical series solutions of I in the direction of a weight vector
****************************************************************************************************

Synopsis
========

  * Usage:
        cssExpts(I,w)
  * Inputs:
      * I, an ideal (Macaulay2Doc), (regular) holonomic ideal in
        the Weyl algebra
      * w, a list (Macaulay2Doc), (generic) weights for $I$, of
        length half the number of variables in the Weyl algebra
  * Outputs:
      * a list (Macaulay2Doc), of exponents of the exponents of the
        canonical series solutions of I in the direction of (-w,w), as in [SST
        (see https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), Theorem
        2.3.11].

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

There are examples in the tutorial that can be moved here. Code Pre

+-----------------------------------------------------------------------------+
|i1 : R1 = QQ[z]                                                              |
|                                                                             |
|o1 = R1                                                                      |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : W1 = makeWA R1                                                          |
|                                                                             |
|o2 = W1                                                                      |
|                                                                             |
|o2 : PolynomialRing, 1 differential variable(s)                              |
+-----------------------------------------------------------------------------+
|i3 : a=1/2                                                                   |
|                                                                             |
|     1                                                                       |
|o3 = -                                                                       |
|     2                                                                       |
|                                                                             |
|o3 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i4 : b=3                                                                     |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : c=5/3                                                                   |
|                                                                             |
|     5                                                                       |
|o5 = -                                                                       |
|     3                                                                       |
|                                                                             |
|o5 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i6 : J = ideal(z*(1-z)*dz^2+(c-(a+b+1)*z)*dz-a*b) -- the Gauss hypergeometric|
|                                                                             |
|              2  2       2   9       5     3                                 |
|o6 = ideal(- z dz  + z*dz  - -z*dz + -dz - -)                                |
|                             2       3     2                                 |
|                                                                             |
|o6 : Ideal of W1                                                             |
|-----------------------------------------------------------------------------|
|equation, exponents 0, 1-c                                                   |
+-----------------------------------------------------------------------------+
|i7 : cssExpts(J,{1})                                                         |
|                                                                             |
|              2                                                              |
|o7 = {{0}, {- -}}                                                            |
|              3                                                              |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use cssExpts :
======================

  * "cssExpts(Ideal,List)"

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

The object cssExpts, is a method function (Macaulay2Doc).

cssExptsMult -- the exponents and multiplicities of the canonical series solutions
**********************************************************************************

Synopsis
========

  * Usage:
        cssExptsMult(I,w)
  * Inputs:
      * I, an ideal (Macaulay2Doc), (regular) holonomic ideal in
        the Weyl algebra
      * w, a list (Macaulay2Doc), (generic) weights for $I$, of
        length half the number of variables in the Weyl algebra
  * Outputs:
      * a list (Macaulay2Doc), of exponents of the starting
        exponents of the canonical series solutions of I in the direction of
        (-w,w), as in [SST (see
        https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), Theorem
        2.3.11], together with their multiplicities.

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

There are examples in the tutorial that can be moved here.

+-----------------------------------------------------------------------------+
|i1 : R1 = QQ[z]                                                              |
|                                                                             |
|o1 = R1                                                                      |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : W1 = makeWA R1                                                          |
|                                                                             |
|o2 = W1                                                                      |
|                                                                             |
|o2 : PolynomialRing, 1 differential variable(s)                              |
+-----------------------------------------------------------------------------+
|i3 : a=1/2                                                                   |
|                                                                             |
|     1                                                                       |
|o3 = -                                                                       |
|     2                                                                       |
|                                                                             |
|o3 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i4 : b=3                                                                     |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : c=5/3                                                                   |
|                                                                             |
|     5                                                                       |
|o5 = -                                                                       |
|     3                                                                       |
|                                                                             |
|o5 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i6 : J = ideal(z*(1-z)*dz^2+(c-(a+b+1)*z)*dz-a*b) -- the Gauss hypergeometric|
|                                                                             |
|              2  2       2   9       5     3                                 |
|o6 = ideal(- z dz  + z*dz  - -z*dz + -dz - -)                                |
|                             2       3     2                                 |
|                                                                             |
|o6 : Ideal of W1                                                             |
|-----------------------------------------------------------------------------|
|equation, exponents 0, 1-c                                                   |
+-----------------------------------------------------------------------------+
|i7 : cssExpts(J,{1})                                                         |
|                                                                             |
|              2                                                              |
|o7 = {{0}, {- -}}                                                            |
|              3                                                              |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : c=1  -- Now we have a single exponent of multiplicity 2                 |
|                                                                             |
|o8 = 1                                                                       |
+-----------------------------------------------------------------------------+
|i9 : J = ideal(z*(1-z)*dz^2+(c-(a+b+1)*z)*dz-a*b)                            |
|                                                                             |
|              2  2       2   9            3                                  |
|o9 = ideal(- z dz  + z*dz  - -z*dz + dz - -)                                 |
|                             2            2                                  |
|                                                                             |
|o9 : Ideal of W1                                                             |
+-----------------------------------------------------------------------------+
|i10 : cssExpts(J,{1})                                                        |
|                                                                             |
|o10 = {{0}}                                                                  |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+
|i11 : cssExptsMult(J,{1})                                                    |
|                                                                             |
|o11 = {{2, {0}}}                                                             |
|                                                                             |
|o11 : List                                                                   |
+-----------------------------------------------------------------------------+

Ways to use cssExptsMult :
==========================

  * "cssExptsMult(Ideal,List)"

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

The object cssExptsMult, is a method function (Macaulay2Doc).

cssLeadTerm -- lead term of the canonical series solutions of I
***************************************************************

Synopsis
========

  * Usage:
        cssLeadTerm(I, w)
  * Inputs:
      * I, an ideal (Macaulay2Doc), (regular) holonomic ideal in
        the Weyl algebra
      * w, a list (Macaulay2Doc), (generic) weights for $I$, of
        length half the number of variables in the Weyl algebra
  * Outputs:
      * a list (Macaulay2Doc), containing monomials times
        logarithms in the variables

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

This routine returns the lead terms of the canonical series solutions of $I$
with respect to the weight vector $w$. See [SST (see
https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), Algorithm 2.3.14 and
Lemma 2.5.10].

Here is [SST (see https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ),
Example 2.3.16]:

+-----------------------------------------------------------------------------+
|i1 : needsPackage "FourTiTwo"                                                |
|                                                                             |
|o1 = FourTiTwo                                                               |
|                                                                             |
|o1 : Package                                                                 |
+-----------------------------------------------------------------------------+
|i2 : A = matrix{{1,1,1,1,1,1},{-2,0,0,0,0,1},{0,1,0,1,0,0},{1,1,2,0,0,1}}    |
|                                                                             |
|o2 = | 1  1 1 1 1 1 |                                                        |
|     | -2 0 0 0 0 1 |                                                        |
|     | 0  1 0 1 0 0 |                                                        |
|     | 1  1 2 0 0 1 |                                                        |
|                                                                             |
|              4        6                                                     |
|o2 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i3 : beta = {2,1,0,2}                                                        |
|                                                                             |
|o3 = {2, 1, 0, 2}                                                            |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : Hbeta = gkz(A,beta)                                                     |
|                                                                             |
|                                                                             |
|o4 = ideal (x D  + x D  + x D  + x D  + x D  + x D  - 2, - 2x D  + x D  - 1, |
|             1 1    2 2    3 3    4 4    5 5    6 6          1 1    6 6      |
|     ------------------------------------------------------------------------|
|                                                       2    2           2    |
|     x D  + x D , x D  + x D  + 2x D  + x D  - 2, - D D  + D D , - D D D  +  |
|      2 2    4 4   1 1    2 2     3 3    6 6         3 4    2 5     2 3 5    |
|     ------------------------------------------------------------------------|
|          2     2            2     3 3    2 4                                |
|     D D D , - D D D  + D D D , - D D  + D D )                               |
|      1 4 6     3 4 5    1 2 6     3 5    1 6                                |
|                                                                             |
|o4 : Ideal of QQ[x ..x , D ..D ]                                             |
|                  1   6   1   6                                              |
+-----------------------------------------------------------------------------+
|i5 : w = {9,1,99999, 9999999, 3, 999}                                        |
|                                                                             |
|o5 = {9, 1, 99999, 9999999, 3, 999}                                          |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : netList cssLeadTerm(Hbeta, w)                                           |
| -- 2.849e-6 seconds elapsed                                                 |
| -- 3.078e-6 seconds elapsed                                                 |
| -- 4.399e-6 seconds elapsed                                                 |
| -- 4.301e-6 seconds elapsed                                                 |
| -- 3.164e-6 seconds elapsed                                                 |
|Warning:  Parallel F4 Algorithm not available over current coefficient ring. |
|Converting to Naive algorithm.                                               |
|                                                                             |
|     +----------------------------------------------------+                  |
|     |   1 5   5 5                                        |                  |
|     | - - - - - -                                        |                  |
|     |   2 2   2 2                                        |                  |
|o6 = |x   x x   x                                         |                  |
|     | 1   2 4   5                                        |                  |
|     +----------------------------------------------------+                  |
|     | -1                                                 |                  |
|     |x  x x x 1                                          |                  |
|     | 2  3 4 6                                           |                  |
|     +----------------------------------------------------+                  |
|     | -1       1        3        3                       |                  |
|     |x  x x x (-logX  - -logX  - -logX  + logX )         |                  |
|     | 2  3 4 6 2    0   4    2   4    4       5          |                  |
|     +----------------------------------------------------+                  |
|     |   -1                                               |                  |
|     |x x  x x 1                                          |                  |
|     | 2 4  5 6                                           |                  |
|     +----------------------------------------------------+                  |
|     |   -1     1        3        3        3              |                  |
|     |x x  x x (-logX  - -logX  + -logX  - -logX  + logX )|                  |
|     | 2 4  5 6 2    0   2    1   2    3   2    4       5 |                  |
|     +----------------------------------------------------+                  |
|     | -1 2 2 -1                                          |                  |
|     |x  x x x  1                                         |                  |
|     | 1  3 5 6                                           |                  |
|     +----------------------------------------------------+                  |
|     | -1 2 2 -1 1        3        3                      |                  |
|     |x  x x x  (-logX  - -logX  - -logX  + logX )        |                  |
|     | 1  3 5 6  2    0   4    2   4    4       5         |                  |
|     +----------------------------------------------------+                  |
|     | 1 5                                                |                  |
|     | - -                                                |                  |
|     | 3 3                                                |                  |
|     |x x 1                                               |                  |
|     | 1 6                                                |                  |
|     +----------------------------------------------------+                  |
|     | 1 5                                                |                  |
|     | - -                                                |                  |
|     | 3 3 1        3        3                            |                  |
|     |x x (-logX  - -logX  - -logX  + logX )              |                  |
|     | 1 6 2    0   4    2   4    4       5               |                  |
|     +----------------------------------------------------+                  |
|     |   1     1                                          |                  |
|     | - -     -                                          |                  |
|     |   3     3                                          |                  |
|     |x   x x x 1                                         |                  |
|     | 1   3 5 6                                          |                  |
|     +----------------------------------------------------+                  |
|     |   1     1                                          |                  |
|     | - -     -                                          |                  |
|     |   3     3 1        3        3                      |                  |
|     |x   x x x (-logX  - -logX  - -logX  + logX )        |                  |
|     | 1   3 5 6 2    0   4    2   4    4       5         |                  |
|     +----------------------------------------------------+                  |
+-----------------------------------------------------------------------------+

Ways to use cssLeadTerm :
=========================

  * "cssLeadTerm(Ideal,List)"

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

The object cssLeadTerm, is a method function (Macaulay2Doc).

distraction -- the image in the thetaRing of a torus-fixed element or ideal in a Weyl algebra
*********************************************************************************************

Synopsis
========

  * Usage:
        distraction(I,thetaRing)
        distraction(f,thetaRing)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc),
      * thetaRing, a polynomial ring (Macaulay2Doc), a
        stand in for the subring $k[\theta]$ generated by theta = x*dx
  * Outputs:
      * an ideal (Macaulay2Doc), or a ring element (Macaulay2Doc),
        that results from intersecting with the
        thetaRing of D, as in [SST (see
        https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), Lemma 2.3.1]
        to I.

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

Given a monomial $x^u \partial^v$, this function rewrites it as a product $x^a
p(\theta) \partial^b$, where $\theta_i = x_i \partial_i$ for $i = 1,\dots, n$.
This is a step in a procedure for checking that D-ideal is torus-fixed, and is
used in the isTorusFixed, routine.

Given a torus fixed $D$-ideal, this function computes the distraction as in
[SST, Corollary 2.3.5]. This is necessary to compute indicial ideals [SST,
Theorem 2.3.9, Corollary 2.3.5]; the roots of the indicial ideals are the
exponents of the starting terms of canonical series solutions of regular
holonomic D-ideals.

+-----------------------------------------------------------------------------+
|i1 : R1 = QQ[z]                                                              |
|                                                                             |
|o1 = R1                                                                      |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : W1 = makeWA R1                                                          |
|                                                                             |
|o2 = W1                                                                      |
|                                                                             |
|o2 : PolynomialRing, 1 differential variable(s)                              |
+-----------------------------------------------------------------------------+
|i3 : a=1/2                                                                   |
|                                                                             |
|     1                                                                       |
|o3 = -                                                                       |
|     2                                                                       |
|                                                                             |
|o3 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i4 : b=3                                                                     |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : c=5/3                                                                   |
|                                                                             |
|     5                                                                       |
|o5 = -                                                                       |
|     3                                                                       |
|                                                                             |
|o5 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i6 : J = ideal(z*(1-z)*dz^2+(c-(a+b+1)*z)*dz-a*b) -- the Gauss hypergeometric|
|                                                                             |
|              2  2       2   9       5     3                                 |
|o6 = ideal(- z dz  + z*dz  - -z*dz + -dz - -)                                |
|                             2       3     2                                 |
|                                                                             |
|o6 : Ideal of W1                                                             |
|-----------------------------------------------------------------------------|
|equation, exponents 0, 1-c                                                   |
+-----------------------------------------------------------------------------+
|i7 : cssExpts(J,{1})                                                         |
|                                                                             |
|              2                                                              |
|o7 = {{0}, {- -}}                                                            |
|              3                                                              |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : K = inw(J,{-1,1})                                                       |
|                                                                             |
|                2                                                            |
|o8 = ideal(6z*dz  + 10dz)                                                    |
|                                                                             |
|o8 : Ideal of W1                                                             |
+-----------------------------------------------------------------------------+
|i9 : distraction(K,QQ[s])                                                    |
|                                                                             |
|             2                                                               |
|o9 = ideal(6s  + 4s)                                                         |
|                                                                             |
|o9 : Ideal of QQ[s]                                                          |
+-----------------------------------------------------------------------------+

Ways to use distraction :
=========================

  * "distraction(Ideal,Ring)"
  * "distraction(RingElement,Ring)"

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

The object distraction, is a method function (Macaulay2Doc).

indicialIdeal -- the image in the thetaRing of an indicial ideal in a Weyl algebra
**********************************************************************************

Synopsis
========

  * Usage:
        indicialIdeal(I,w)
  * Inputs:
      * I, an ideal (Macaulay2Doc), in a WeylAlgebra that is
        torus-fixed
      * w, a list (Macaulay2Doc), (generic) weights for $I$, of
        length half the number of variables in the Weyl algebra
  * Outputs:
      * an ideal (Macaulay2Doc), that results from intersecting
        with the thetaRing of D with the result of extending the ideal
        in_(-w,w)(I) with the rational function field in the Weyl algebra
        variables, as in [SST (see
        https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ), Theorem 2.3.9]
        to I.

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

This computes the distraction of a torus fixed D-ideal [SST, Corollary 2.3.5].
This is necessary to compute indicial ideals [SST, Theorem 2.3.9, Corollary
2.3.5]; the roots of the indicial ideals are the exponents of the starting
terms of canonical series solutions of regular holonomic D-ideals.

+-----------------------------------------------------------------------------+
|i1 : R1 = QQ[z]                                                              |
|                                                                             |
|o1 = R1                                                                      |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : W1 = makeWA R1                                                          |
|                                                                             |
|o2 = W1                                                                      |
|                                                                             |
|o2 : PolynomialRing, 1 differential variable(s)                              |
+-----------------------------------------------------------------------------+
|i3 : a=1/2                                                                   |
|                                                                             |
|     1                                                                       |
|o3 = -                                                                       |
|     2                                                                       |
|                                                                             |
|o3 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i4 : b=3                                                                     |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : c=5/3                                                                   |
|                                                                             |
|     5                                                                       |
|o5 = -                                                                       |
|     3                                                                       |
|                                                                             |
|o5 : QQ                                                                      |
+-----------------------------------------------------------------------------+
|i6 : J = ideal(z*(1-z)*dz^2+(c-(a+b+1)*z)*dz-a*b) -- the Gauss hypergeometric|
|                                                                             |
|              2  2       2   9       5     3                                 |
|o6 = ideal(- z dz  + z*dz  - -z*dz + -dz - -)                                |
|                             2       3     2                                 |
|                                                                             |
|o6 : Ideal of W1                                                             |
|-----------------------------------------------------------------------------|
|equation, exponents 0, 1-c                                                   |
+-----------------------------------------------------------------------------+
|i7 : cssExpts(J,{1})                                                         |
|                                                                             |
|              2                                                              |
|o7 = {{0}, {- -}}                                                            |
|              3                                                              |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : K = inw(J,{-1,1})                                                       |
|                                                                             |
|                2                                                            |
|o8 = ideal(6z*dz  + 10dz)                                                    |
|                                                                             |
|o8 : Ideal of W1                                                             |
+-----------------------------------------------------------------------------+
|i9 : distraction(K,QQ[s])                                                    |
|                                                                             |
|             2                                                               |
|o9 = ideal(6s  + 4s)                                                         |
|                                                                             |
|o9 : Ideal of QQ[s]                                                          |
+-----------------------------------------------------------------------------+

Ways to use indicialIdeal :
===========================

  * "indicialIdeal(Ideal,List)"

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

The object indicialIdeal, is a method function (Macaulay2Doc).

isTorusFixed -- checks if an ideal in a Weyl algebra is torus-fixed
*******************************************************************

Synopsis
========

  * Usage:
        isTorusFixed I
  * Inputs:
      * I, an ideal (Macaulay2Doc), in a WeylAlgebra
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if I is
        torus-fixed, false if not

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

There is a natural action of the n-dimensional algebraic torus on $D$ where $t
\in (\mathbb{C}^*)^n$ acts on $\partial_i$ as $t_i\partial_i$ and on $x_i$ as
$t_i^{-1}x_i$. The function isTorusFixed verifies whether a D-ideal is
invariant under this action.

See [SST (see https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf )], just
before Lemma 2.3.1.

+-----------------------------------------------------------------------------+
|i1 : W = makeWA(QQ[x_1,x_2])                                                 |
|                                                                             |
|o1 = W                                                                       |
|                                                                             |
|o1 : PolynomialRing, 2 differential variable(s)                              |
+-----------------------------------------------------------------------------+
|i2 : b = 2                                                                   |
|                                                                             |
|o2 = 2                                                                       |
+-----------------------------------------------------------------------------+
|i3 : I = ideal(x_1*dx_1*(x_1*dx_1+b), x_1*dx_1*(x_2*dx_2+b),                 |
|         x_2*dx_2*(x_1*dx_1+b), x_2*dx_2*(x_2*dx_2+b))                       |
|                                                                             |
|             2  2                                                      2  2  |
|o3 = ideal (x dx  + 3x dx , x x dx dx  + 2x dx , x x dx dx  + 2x dx , x dx  +|
|             1  1     1  1   1 2  1  2     1  1   1 2  1  2     2  2   2  2  |
|     ------------------------------------------------------------------------|
|     3x dx )                                                                 |
|       2  2                                                                  |
|                                                                             |
|o3 : Ideal of W                                                              |
+-----------------------------------------------------------------------------+
|i4 : isTorusFixed I                                                          |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

Ways to use isTorusFixed :
==========================

  * "isTorusFixed(Ideal)"

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

The object isTorusFixed, is a method function (Macaulay2Doc).

solveFrobeniusIdeal -- solving Frobenius ideals
***********************************************

Synopsis
========

  * Usage:
        solveFrobeniusIdeal I
        solveFrobeniusIdeal(I, W)
  * Inputs:
      * I, an ideal (Macaulay2Doc), a Frobenius ideal which is
        m-primary
  * Outputs:
      * a list (Macaulay2Doc), containing monomials times
        logarithms of the variables

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

See [SST (see https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ),
Algorithm 2.3.14].

Here is [SST (see https://mathscinet.ams.org/mathscinet/pdf/1734566.pdf ),
Example 2.3.16]:

+-----------------------------------------------------------------------------+
|i1 : R = QQ[t_1..t_5];                                                       |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(t_1+t_2+t_3+t_4+t_5, t_1+t_2-t_4, t_2+t_3-t_4, t_1*t_3,       |
|                                                                             |
|o2 : Ideal of R                                                              |
|-----------------------------------------------------------------------------|
|t_2*t_4);                                                                    |
+-----------------------------------------------------------------------------+
|i3 : solveFrobeniusIdeal I                                                   |
| -- 2.667e-6 seconds elapsed                                                 |
|Warning:  Parallel F4 Algorithm not available over current coefficient ring. |
|Converting to Naive algorithm.                                               |
|                                                                             |
|                                                                             |
|o3 = {1, - 2logX  + 3logX  - 2logX  + logX , - logX  + logX  - logX  + logX ,|
|                0        1        2       3        0       1       2       4 |
|     ------------------------------------------------------------------------|
|     1             1    2   1             1             1             1    2 |
|     -logX logX  - -logX  + -logX logX  + -logX logX  + -logX logX  + -logX  |
|     4    1    0   8    1   4    2    1   4    3    0   4    3    2   8    3 |
|     ------------------------------------------------------------------------|
|       1             1             1             3                 2         |
|     - -logX logX  - -logX logX  - -logX logX  - -logX logX  + logX }        |
|       2    4    0   4    4    1   2    4    2   4    4    3       4         |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i4 : W = makeWeylAlgebra(QQ[x_1..x_5]);                                      |
+-----------------------------------------------------------------------------+
|i5 : solveFrobeniusIdeal(I, W)                                               |
| -- 2.2e-6 seconds elapsed                                                   |
|Warning:  Parallel F4 Algorithm not available over current coefficient ring. |
|Converting to Naive algorithm.                                               |
|                                                                             |
|                                                                             |
|o5 = {1, - 2logX  + 3logX  - 2logX  + logX , - logX  + logX  - logX  + logX ,|
|                0        1        2       3        0       1       2       4 |
|     ------------------------------------------------------------------------|
|     1             1    2   1             1             1             1    2 |
|     -logX logX  - -logX  + -logX logX  + -logX logX  + -logX logX  + -logX  |
|     4    1    0   8    1   4    2    1   4    3    0   4    3    2   8    3 |
|     ------------------------------------------------------------------------|
|       1             1             1             3                 2         |
|     - -logX logX  - -logX logX  - -logX logX  - -logX logX  + logX }        |
|       2    4    0   4    4    1   2    4    2   4    4    3       4         |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

Ways to use solveFrobeniusIdeal :
=================================

  * "solveFrobeniusIdeal(Ideal)"
  * "solveFrobeniusIdeal(Ideal,Ring)"

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

The object solveFrobeniusIdeal, is a method function (Macaulay2Doc).

diffOps -- differential operators of up to the given order for a quotient polynomial ring
*****************************************************************************************

Synopsis
========

  * Usage:
        diffOps (I, k)
        diffOps (f, k)
  * Inputs:
      * I, an ideal (Macaulay2Doc), contained in a polynomial ring
        R
      * f, a ring element (Macaulay2Doc), an element of a
        polynomial ring R
      * k, an integer (Macaulay2Doc), which is nonnegative
  * Outputs:
      * a hash table (Macaulay2Doc), the differential
        operators of order at most k of the quotient ring R/I (or R/(f))

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

Given an ideal $I$ of a polynomial ring $R$ the set of differential operators
of the quotient ring $R/I$ having order less than or equal to $k$ forms a
finitely generated module over $R/I$. This routine returns its generating set.

The output is in the form of a hash table. The key BasisElts is a row vector of
basic differential operators. The key PolyGens is a matrix over R whose column
vectors represent differential operators of R/I in the following way.  For each
column vector, consider its image in R/I then take its dot product with the
BasisElts. This gives a differential operator, and the set of these operators
generates the differential operators of R/I of order k or less as an
(R/I)-module.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                                           |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(x^2-y*z)                                                      |
|                                                                             |
|            2                                                                |
|o2 = ideal(x  - y*z)                                                         |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : D = diffOps(I, 3)                                                       |
|                                                                             |
|o3 = HashTable{BasisElts => | dx^3 dx^2dy dx^2dz dxdy^2 dxdydz dxdz^2 dy^3   |
|               PolyGens => {-3} | 0  0  0  0  0   -2xz  0    2xy  yz  y2     |
|                           {-3} | 0  0  0  0  0   -6yz  0    0    2xy 0      |
|                           {-3} | 0  0  0  0  0   -6z2  0    12yz 4xz 6xy    |
|                           {-3} | 0  0  0  0  0   0     0    0    0   0      |
|                           {-3} | 0  0  0  0  0   -24xz 0    0    8yz 0      |
|                           {-3} | 0  0  0  0  0   0     0    24xz 4z2 12yz   |
|                           {-3} | 0  0  0  0  0   8y2   0    0    0   0      |
|                           {-3} | 0  0  0  0  0   -24yz 0    0    0   0      |
|                           {-3} | 0  0  0  0  0   0     0    0    8xz 0      |
|                           {-3} | 0  0  0  0  0   0     0    16z2 0   8xz    |
|                           {-2} | 0  z  y  x  0   -3z   0    -3y  x   0      |
|                           {-2} | 0  4x 0  2y 0   0     0    0    -2y 0      |
|                           {-2} | 0  0  4x 2z 0   0     0    0    4z  6y     |
|                           {-2} | 0  4y 0  0  0   24y   y2   0    0   0      |
|                           {-2} | 0  0  0  4x 0   -12z  -2yz 0    0   0      |
|                           {-2} | 0  0  4z 0  0   0     z2   12z  0   12x    |
|                           {-1} | 0  0  0  1  yz  0     0    0    -1  0      |
|                           {-1} | y  2  0  0  0   6     0    0    0   0      |
|                           {-1} | -z 0  2  0  2xz 0     2z   -6   0   0      |
|                                                                             |
|o3 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|dy^2dz dydz^2 dz^3 dx^2 dxdy dxdz dy^2 dydz dz^2 dx dy dz |}                 |
|2xz  0    z2   -yz   0   0   2x2z-2yz2   |                                   |
|8yz  y2   6xz  0     0   0   0           |                                   |
|4z2  -yz  0    -6xz  0   0   0           |                                   |
|8xy  0    12yz 4y2   0   0   0           |                                   |
|16xz 4xy  0    -8yz  0   0   24x2z-24yz2 |                                   |
|0    -4xz 0    -8z2  0   0   0           |                                   |
|0    0    8xy  0     0   0   0           |                                   |
|16yz 0    0    8xy   0   0   0           |                                   |
|0    4yz  0    -16xz 0   0   0           |                                   |
|0    -4z2 0    0     0   0   0           |                                   |
|z    y    0    -x    xy  xz  0           |                                   |
|0    0    6z   8y    0   4yz 0           |                                   |
|0    0    0    -10z  4yz 0   0           |                                   |
|-12y 0    12x  0     0   4xy 0           |                                   |
|8z   2y   0    0     0   0   0           |                                   |
|0    -6z  0    0     4xz 0   0           |                                   |
|0    0    0    1     -y  -z  -3z         |                                   |
|-6   0    0    0     0   0   -6x         |                                   |
|0    0    0    0     0   0   0           |                                   |
+-----------------------------------------------------------------------------+
|i4 : D.BasisElts                                                             |
|                                                                             |
|o4 = | dx^3 dx^2dy dx^2dz dxdy^2 dxdydz dxdz^2 dy^3 dy^2dz dydz^2 dz^3 dx^2  |
|     ------------------------------------------------------------------------|
|     dxdy dxdz dy^2 dydz dz^2 dx dy dz |                                     |
|                                                                             |
|                                  1                            19            |
|o4 : Matrix (QQ[x..z, dx, dy, dz])  <--- (QQ[x..z, dx, dy, dz])              |
+-----------------------------------------------------------------------------+
|i5 : D.PolyGens                                                              |
|                                                                             |
|o5 = {-3} | 0  0  0  0  0   -2xz  0    2xy  yz  y2   2xz  0    z2   -yz   0  |
|     {-3} | 0  0  0  0  0   -6yz  0    0    2xy 0    8yz  y2   6xz  0     0  |
|     {-3} | 0  0  0  0  0   -6z2  0    12yz 4xz 6xy  4z2  -yz  0    -6xz  0  |
|     {-3} | 0  0  0  0  0   0     0    0    0   0    8xy  0    12yz 4y2   0  |
|     {-3} | 0  0  0  0  0   -24xz 0    0    8yz 0    16xz 4xy  0    -8yz  0  |
|     {-3} | 0  0  0  0  0   0     0    24xz 4z2 12yz 0    -4xz 0    -8z2  0  |
|     {-3} | 0  0  0  0  0   8y2   0    0    0   0    0    0    8xy  0     0  |
|     {-3} | 0  0  0  0  0   -24yz 0    0    0   0    16yz 0    0    8xy   0  |
|     {-3} | 0  0  0  0  0   0     0    0    8xz 0    0    4yz  0    -16xz 0  |
|     {-3} | 0  0  0  0  0   0     0    16z2 0   8xz  0    -4z2 0    0     0  |
|     {-2} | 0  z  y  x  0   -3z   0    -3y  x   0    z    y    0    -x    xy |
|     {-2} | 0  4x 0  2y 0   0     0    0    -2y 0    0    0    6z   8y    0  |
|     {-2} | 0  0  4x 2z 0   0     0    0    4z  6y   0    0    0    -10z  4yz|
|     {-2} | 0  4y 0  0  0   24y   y2   0    0   0    -12y 0    12x  0     0  |
|     {-2} | 0  0  0  4x 0   -12z  -2yz 0    0   0    8z   2y   0    0     0  |
|     {-2} | 0  0  4z 0  0   0     z2   12z  0   12x  0    -6z  0    0     4xz|
|     {-1} | 0  0  0  1  yz  0     0    0    -1  0    0    0    0    1     -y |
|     {-1} | y  2  0  0  0   6     0    0    0   0    -6   0    0    0     0  |
|     {-1} | -z 0  2  0  2xz 0     2z   -6   0   0    0    0    0    0     0  |
|     ------------------------------------------------------------------------|
|     0   2x2z-2yz2   |                                                       |
|     0   0           |                                                       |
|     0   0           |                                                       |
|     0   0           |                                                       |
|     0   24x2z-24yz2 |                                                       |
|     0   0           |                                                       |
|     0   0           |                                                       |
|     0   0           |                                                       |
|     0   0           |                                                       |
|     0   0           |                                                       |
|     xz  0           |                                                       |
|     4yz 0           |                                                       |
|     0   0           |                                                       |
|     4xy 0           |                                                       |
|     0   0           |                                                       |
|     0   0           |                                                       |
|     -z  -3z         |                                                       |
|     0   -6x         |                                                       |
|     0   0           |                                                       |
|                                                                             |
|             19       17                                                     |
|o5 : Matrix R   <--- R                                                       |
+-----------------------------------------------------------------------------+

Ways to use diffOps :
=====================

  * "diffOps(Ideal,ZZ)"
  * "diffOps(RingElement,ZZ)"

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

The object diffOps, is a method function (Macaulay2Doc).

putWeylAlgebra -- transforms output of diffOps into elements of Weyl algebra
****************************************************************************

Synopsis
========

  * Usage:
        putWeylAlgebra m
  * Inputs:
      * the output of diffOps
  * Outputs:
      * the differential operators as elements of the Weyl algebra

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

If I is an ideal of the polynomial ring R and m is the output of diffOps(I, k)
then this routine returns elements of the Weyl algebra W corresponding to R
whose images in W/IW are an R/I-generating set for the differential operators
of order at most k.
+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z]                                                           |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(x^2-y*z)                                                      |
|                                                                             |
|            2                                                                |
|o2 = ideal(x  - y*z)                                                         |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : m = diffOps(I, 3)                                                       |
|                                                                             |
|o3 = HashTable{BasisElts => | dx^3 dx^2dy dx^2dz dxdy^2 dxdydz dxdz^2 dy^3   |
|               PolyGens => {-3} | 0  0  0  0  0   -2xz  0    2xy  yz  y2     |
|                           {-3} | 0  0  0  0  0   -6yz  0    0    2xy 0      |
|                           {-3} | 0  0  0  0  0   -6z2  0    12yz 4xz 6xy    |
|                           {-3} | 0  0  0  0  0   0     0    0    0   0      |
|                           {-3} | 0  0  0  0  0   -24xz 0    0    8yz 0      |
|                           {-3} | 0  0  0  0  0   0     0    24xz 4z2 12yz   |
|                           {-3} | 0  0  0  0  0   8y2   0    0    0   0      |
|                           {-3} | 0  0  0  0  0   -24yz 0    0    0   0      |
|                           {-3} | 0  0  0  0  0   0     0    0    8xz 0      |
|                           {-3} | 0  0  0  0  0   0     0    16z2 0   8xz    |
|                           {-2} | 0  z  y  x  0   -3z   0    -3y  x   0      |
|                           {-2} | 0  4x 0  2y 0   0     0    0    -2y 0      |
|                           {-2} | 0  0  4x 2z 0   0     0    0    4z  6y     |
|                           {-2} | 0  4y 0  0  0   24y   y2   0    0   0      |
|                           {-2} | 0  0  0  4x 0   -12z  -2yz 0    0   0      |
|                           {-2} | 0  0  4z 0  0   0     z2   12z  0   12x    |
|                           {-1} | 0  0  0  1  yz  0     0    0    -1  0      |
|                           {-1} | y  2  0  0  0   6     0    0    0   0      |
|                           {-1} | -z 0  2  0  2xz 0     2z   -6   0   0      |
|                                                                             |
|o3 : HashTable                                                               |
|-----------------------------------------------------------------------------|
|dy^2dz dydz^2 dz^3 dx^2 dxdy dxdz dy^2 dydz dz^2 dx dy dz |}                 |
|2xz  0    z2   -yz   0   0   2x2z-2yz2   |                                   |
|8yz  y2   6xz  0     0   0   0           |                                   |
|4z2  -yz  0    -6xz  0   0   0           |                                   |
|8xy  0    12yz 4y2   0   0   0           |                                   |
|16xz 4xy  0    -8yz  0   0   24x2z-24yz2 |                                   |
|0    -4xz 0    -8z2  0   0   0           |                                   |
|0    0    8xy  0     0   0   0           |                                   |
|16yz 0    0    8xy   0   0   0           |                                   |
|0    4yz  0    -16xz 0   0   0           |                                   |
|0    -4z2 0    0     0   0   0           |                                   |
|z    y    0    -x    xy  xz  0           |                                   |
|0    0    6z   8y    0   4yz 0           |                                   |
|0    0    0    -10z  4yz 0   0           |                                   |
|-12y 0    12x  0     0   4xy 0           |                                   |
|8z   2y   0    0     0   0   0           |                                   |
|0    -6z  0    0     4xz 0   0           |                                   |
|0    0    0    1     -y  -z  -3z         |                                   |
|-6   0    0    0     0   0   -6x         |                                   |
|0    0    0    0     0   0   0           |                                   |
+-----------------------------------------------------------------------------+
|i4 : putWeylAlgebra m                                                        |
|                                                                             |
|o4 = | ydy-zdz zdx^2+4xdxdy+4ydy^2+2dy ydx^2+4xdxdz+4zdz^2+2dz               |
|     ------------------------------------------------------------------------|
|     xdx^2+2ydxdy+2zdxdz+4xdydz+dx yzdx+2xzdz                                |
|     ------------------------------------------------------------------------|
|     -2xzdx^3-6yzdx^2dy+8y2dy^3-6z2dx^2dz-24xzdxdydz-24yzdy^2dz-3zdx^2+24ydy^|
|     ------------------------------------------------------------------------|
|     2-12zdydz+6dy y2dy^2-2yzdydz+z2dz^2+2zdz                                |
|     ------------------------------------------------------------------------|
|     2xydx^3+12yzdx^2dz+24xzdxdz^2+16z2dz^3-3ydx^2+12zdz^2-6dz               |
|     ------------------------------------------------------------------------|
|     yzdx^3+2xydx^2dy+4xzdx^2dz+8yzdxdydz+4z2dxdz^2+8xzdydz^2+xdx^2-2ydxdy+  |
|     ------------------------------------------------------------------------|
|     4zdxdz-dx y2dx^3+6xydx^2dz+12yzdxdz^2+8xzdz^3+6ydxdz+12xdz^2            |
|     ------------------------------------------------------------------------|
|     2xzdx^3+8yzdx^2dy+8xydxdy^2+4z2dx^2dz+16xzdxdydz+16yzdy^2dz+zdx^2-12ydy^|
|     ------------------------------------------------------------------------|
|     2+8zdydz-6dy y2dx^2dy-yzdx^2dz+4xydxdydz-4xzdxdz^2+4yzdydz^2-4z2dz^3+ydx|
|     ------------------------------------------------------------------------|
|     ^2+2ydydz-6zdz^2 z2dx^3+6xzdx^2dy+12yzdxdy^2+8xydy^3+6zdxdy+12xdy^2     |
|     ------------------------------------------------------------------------|
|     -yzdx^3+4y2dxdy^2-6xzdx^2dz-8yzdxdydz+8xydy^2dz-8z2dxdz^2-16xzdydz^2-xdx|
|     ------------------------------------------------------------------------|
|     ^2+8ydxdy-10zdxdz+dx xydx^2+4yzdxdz+4xzdz^2-ydx                         |
|     ------------------------------------------------------------------------|
|     xzdx^2+4yzdxdy+4xydy^2-zdx                                              |
|     ------------------------------------------------------------------------|
|     2x2zdx^3-2yz2dx^3+24x2zdxdydz-24yz2dxdydz-3zdx-6xdy |                   |
|                                                                             |
|                                  1                            17            |
|o4 : Matrix (QQ[x..z, dx, dy, dz])  <--- (QQ[x..z, dx, dy, dz])              |
+-----------------------------------------------------------------------------+

See also
========

  * diffOps -- differential operators of up to the given order
    for a quotient polynomial ring

Ways to use putWeylAlgebra :
============================

  * "putWeylAlgebra(HashTable)"

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

The object putWeylAlgebra, is a method function (Macaulay2Doc).

createThetaRing
***************

Ways to use createThetaRing :
=============================

  * createThetaRing(PolynomialRing) (missing documentation)

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

The object createThetaRing (missing documentation) is a method function (Macaulay2Doc).

nilssonSupport
**************

Ways to use nilssonSupport :
============================

  * nilssonSupport(Ideal,List) (missing documentation)
  * nilssonSupport(Ideal,List,ZZ) (missing documentation)

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

The object nilssonSupport (missing documentation) is a method function (Macaulay2Doc).

ThetaRing
*********

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

The object ThetaRing (missing documentation) is a symbol (Macaulay2Doc).

truncatedCanonicalSeries
************************

Ways to use truncatedCanonicalSeries :
======================================

  * truncatedCanonicalSeries(Ideal,List,ZZ) (missing documentation)

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

The object truncatedCanonicalSeries (missing documentation) is a method function (Macaulay2Doc).

WtoT
****

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

The object WtoT (missing documentation) is a symbol (Macaulay2Doc).