This is VectorFields.info, produced by Macaulay2, version 1.21

VectorFields -- a package for manipulating polynomial vector fields
*******************************************************************

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

VectorFields provides functions to study polynomial vector fields on affine
space, and modules of such vector fields. This package may be of interest to
those studying representations of Lie groups, foliations, or logarithmic vector
fields.

We represent a vector field on affine $n$-space as an element of the module
$R^n$, where $R$ is a polynomial ring in $n$ variables. Concretely, the
ordering of variables given by vars(R) is used to identify each vector field
with a $n\times 1$ See Matrix (Macaulay2Doc), and vice-versa, with
each entry in the matrix storing the coefficient of a derivative with respect
to a particular variable. For instance, on a 3-dimensional space the vector
field $M=2y \partial_y + z \partial_z$ is entered this way:

+-----------------------------+
|i1 : R=QQ[x,y,z];            |
+-----------------------------+
|i2 : vars(R)                 |
|                             |
|o2 = | x y z |               |
|                             |
|             1       3       |
|o2 : Matrix R  <--- R        |
+-----------------------------+
|i3 : M=matrix {{0},{2*y},{z}}|
|                             |
|o3 = | 0  |                  |
|     | 2y |                  |
|     | z  |                  |
|                             |
|             3       1       |
|o3 : Matrix R  <--- R        |
+-----------------------------+

Many functions in this package are designed to accept either a finite
collection of vector fields (in the form of a Matrix (Macaulay2Doc),
where each column represents a vector field), or a module
of vector fields (in the form of a submodule of $R^n$). These different
versions may compute quite different things! For instance, the vector field in
M commutes with itself:

+----------------------+
|i4 : commutator(M)    |
|                      |
|o4 = 0                |
|                      |
|             3        |
|o4 : Matrix R  <--- 0 |
+----------------------+
|i5 : bracket(M,M)     |
|                      |
|o5 = 0                |
|                      |
|             3       1|
|o5 : Matrix R  <--- R |
+----------------------+

but the vector fields in the module generated by M do not:

+------------------------------+
|i6 : commutator(image M)      |
|                              |
|o6 = image | 0 0   0   |      |
|           | 0 4y2 2yz |      |
|           | 0 2yz z2  |      |
|                              |
|                             3|
|o6 : R-module, submodule of R |
+------------------------------+
|i7 : bracket(M,y*M)           |
|                              |
|o7 = | 0   |                  |
|     | 4y2 |                  |
|     | 2yz |                  |
|                              |
|             3       1        |
|o7 : Matrix R  <--- R         |
+------------------------------+

In other cases, the Matrix (Macaulay2Doc), and Module (Macaulay2Doc),
versions of a function compute identical things, perhaps
returning different types. For instance, here we apply vector fields to a
function:

+--------------------------------------+
|i8 : applyVectorField(M,x*y-z^2)      |
|                                      |
|              2                       |
|o8 = 2x*y - 2z                        |
|                                      |
|o8 : R                                |
+--------------------------------------+
|i9 : applyVectorField(image M,x*y-z^2)|
|                                      |
|                    2                 |
|o9 = ideal(2x*y - 2z )                |
|                                      |
|o9 : Ideal of R                       |
+--------------------------------------+

See differences between certain bracketing functions,
for more details.

To show some capabilities of this package, let us use derlog, to
find the vector fields on the ambient space that are tangent to $xy-z^2=0$:

+-------------------------------+
|i10 : D=derlog(ideal (x*y-z^2))|
|                               |
|o10 = image | 2x 0  2z 0  |    |
|            | 0  2y 0  2z |    |
|            | z  z  y  x  |    |
|                               |
|                              3|
|o10 : R-module, submodule of R |
+-------------------------------+

Actually, $M$ is one of these vector fields:

+-------------------------+
|i11 : isSubset(image M,D)|
|                         |
|o11 = true               |
+-------------------------+

We may also check some properties of $D$:

+---------------------------+
|i12 : isVectorField(gens D)|
|                           |
|o12 = true                 |
+---------------------------+
|i13 : isVectorField(D)     |
|                           |
|o13 = true                 |
+---------------------------+
|i14 : isLieAlgebra(D)      |
|                           |
|o14 = true                 |
+---------------------------+

Note that this package has been rewritten since version 1.0. Any users of the
earlier version should upgrade with care, and read the comments inside the
package's source code.

See also
========

  * commutator -- the commutator of a collection of vector
    fields
  * bracket -- compute the Lie bracket of vector fields
  * applyVectorField -- apply a vector field to a
    function or functions
  * derlog -- compute the logarithmic (tangent) vector fields to
    an ideal
  * isVectorField -- test whether a module or matrix can
    be interpreted as a collection of vector fields
  * isLieAlgebra -- check that a module of vector fields
    is closed under the Lie bracket

Author
======

  * Brian Pike (see http://www.brianpike.info/ ) <bapike@gmail.com>

Version
=======

This documentation describes version 1.80 of VectorFields.

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

The source code from which this documentation is derived is in the file
VectorFields.m2 (see common/share/Macaulay2/VectorFields.m2 ).

Exports
=======

  * Types
      * StratificationByRank -- a type to hold a
        rank computation
  * Functions and commands
      * applyVectorField -- apply a vector field to a
        function or functions
      * bracket -- compute the Lie bracket of vector fields
      * commutator -- the commutator of a collection of
        vector fields
      * der -- compute the module of vector fields which send one
        set to another
      * derivedSeries -- compute the derived series of a
        set of vector fields
      * derlog -- compute the logarithmic (tangent) vector
        fields to an ideal
      * "derlogH" -- see derlog, -- compute the logarithmic
        (tangent) vector fields to an ideal
      * homogeneousVectorFieldDegree, --
        check if vector fields are homogeneous, and of what degree
      * isFiniteStratification -- checks if a
        stratification by integral submanifolds is finite
      * isFreeDivisor -- check if the provided
        information is associated with a free divisor
      * isHHolonomic -- test whether a hypersurface is
        H-holonomic
      * isHolonomic -- test whether an algebraic set is
        holonomic
      * isHomogeneousVectorField -- determine
        whether a matrix or module is generated by homogeneous vector fields
      * isLieAlgebra -- check that a module of vector
        fields is closed under the Lie bracket
      * isLogarithmic -- check if the given vector fields
        are logarithmic
      * isVectorField -- test whether a module or matrix
        can be interpreted as a collection of vector fields
      * lowerCentralSeries -- compute the lower
        central series of a set of vector fields
      * stratifyByRank -- compute ideals describing
        where the vector fields have a particular rank
  * Methods
      * "applyVectorField(Matrix,List)" -- see applyVectorField,
        -- apply a vector field to a function or functions
      * "applyVectorField(Matrix,RingElement)" -- see applyVectorField,
        -- apply a vector field to a function or functions
      * "applyVectorField(Module,Ideal)" -- see applyVectorField,
        -- apply a vector field to a function or functions
      * "applyVectorField(Module,RingElement)" -- see applyVectorField,
        -- apply a vector field to a function or functions
      * "applyVectorField(Vector,List)" -- see applyVectorField,
        -- apply a vector field to a function or functions
      * "applyVectorField(Vector,RingElement)" -- see applyVectorField,
        -- apply a vector field to a function or functions
      * "bracket(Matrix,Matrix)" -- see bracket, -- compute the
        Lie bracket of vector fields
      * "bracket(Matrix,Matrix,List)" -- see bracket, -- compute
        the Lie bracket of vector fields
      * "bracket(Module,Module)" -- see bracket, -- compute the
        Lie bracket of vector fields
      * "bracket(Vector,Vector)" -- see bracket, -- compute the
        Lie bracket of vector fields
      * "commutator(Matrix)" -- see commutator, -- the
        commutator of a collection of vector fields
      * "commutator(Module)" -- see commutator, -- the
        commutator of a collection of vector fields
      * "der(Ideal,Ideal)" -- see der, -- compute the module of
        vector fields which send one set to another
      * "der(VisibleList,Ideal)" -- see der, -- compute the module
        of vector fields which send one set to another
      * "derivedSeries(ZZ,Matrix)" -- see derivedSeries,
        -- compute the derived series of a set of vector fields
      * "derivedSeries(ZZ,Module)" -- see derivedSeries,
        -- compute the derived series of a set of vector fields
      * "derlog(Ideal)" -- see derlog, -- compute the logarithmic
        (tangent) vector fields to an ideal
      * "derlog(RingElement)" -- see derlog, -- compute the
        logarithmic (tangent) vector fields to an ideal
      * "derlogH(List)" -- see derlog, -- compute the logarithmic
        (tangent) vector fields to an ideal
      * "derlogH(RingElement)" -- see derlog, -- compute the
        logarithmic (tangent) vector fields to an ideal
      * "homogeneousVectorFieldDegree(Matrix)" -- see
        homogeneousVectorFieldDegree, -- check if
        vector fields are homogeneous, and of what degree
      * "homogeneousVectorFieldDegree(Module)" -- see
        homogeneousVectorFieldDegree, -- check if
        vector fields are homogeneous, and of what degree
      * "isFiniteStratification(StratificationByRank)" -- see
        isFiniteStratification, -- checks if a
        stratification by integral submanifolds is finite
      * "isFreeDivisor(Matrix)" -- see isFreeDivisor, --
        check if the provided information is associated with a free divisor
      * "isFreeDivisor(Module)" -- see isFreeDivisor, --
        check if the provided information is associated with a free divisor
      * "isFreeDivisor(RingElement)" -- see isFreeDivisor,
        -- check if the provided information is associated with a free divisor
      * "isHHolonomic(RingElement)" -- see isHHolonomic, --
        test whether a hypersurface is H-holonomic
      * "isHolonomic(Ideal)" -- see isHolonomic, -- test
        whether an algebraic set is holonomic
      * "isHolonomic(RingElement)" -- see isHolonomic, --
        test whether an algebraic set is holonomic
      * "isHomogeneousVectorField(Matrix)" -- see
        isHomogeneousVectorField, -- determine
        whether a matrix or module is generated by homogeneous vector fields
      * "isHomogeneousVectorField(Matrix,List)" -- see
        isHomogeneousVectorField, -- determine
        whether a matrix or module is generated by homogeneous vector fields
      * "isHomogeneousVectorField(Matrix,Set)" -- see
        isHomogeneousVectorField, -- determine
        whether a matrix or module is generated by homogeneous vector fields
      * "isHomogeneousVectorField(Module)" -- see
        isHomogeneousVectorField, -- determine
        whether a matrix or module is generated by homogeneous vector fields
      * "isHomogeneousVectorField(Module,List)" -- see
        isHomogeneousVectorField, -- determine
        whether a matrix or module is generated by homogeneous vector fields
      * "isHomogeneousVectorField(Module,Set)" -- see
        isHomogeneousVectorField, -- determine
        whether a matrix or module is generated by homogeneous vector fields
      * "isLieAlgebra(Module)" -- see isLieAlgebra, --
        check that a module of vector fields is closed under the Lie bracket
      * "isLogarithmic(Matrix,Ideal)" -- see isLogarithmic,
        -- check if the given vector fields are logarithmic
      * "isLogarithmic(Module,Ideal)" -- see isLogarithmic,
        -- check if the given vector fields are logarithmic
      * "isLogarithmic(Vector,Ideal)" -- see isLogarithmic,
        -- check if the given vector fields are logarithmic
      * "isVectorField(Matrix)" -- see isVectorField, --
        test whether a module or matrix can be interpreted as a collection of
        vector fields
      * "isVectorField(Module)" -- see isVectorField, --
        test whether a module or matrix can be interpreted as a collection of
        vector fields
      * "lowerCentralSeries(ZZ,Matrix)" -- see lowerCentralSeries,
        -- compute the lower central series of a set of
        vector fields
      * "lowerCentralSeries(ZZ,Module)" -- see lowerCentralSeries,
        -- compute the lower central series of a set of
        vector fields
      * "stratifyByRank(Matrix)" -- see stratifyByRank,
        -- compute ideals describing where the vector fields have a particular
        rank
      * "stratifyByRank(Module)" -- see stratifyByRank,
        -- compute ideals describing where the vector fields have a particular
        rank

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

The object VectorFields, is a package (Macaulay2Doc).

applyVectorField -- apply a vector field to a function or functions
*******************************************************************

Synopsis
========

  * Usage:
        g=applyVectorField(M,f)
        g=applyVectorField(V,f)
        L=applyVectorField(M,l)
        L=applyVectorField(V,l)
        J=applyVectorField(m,f)
        J=applyVectorField(m,I)
  * Inputs:
      * M, a matrix (Macaulay2Doc), of vector fields
      * V, a vector (Macaulay2Doc), a column from a matrix of
        vector fields
      * f, a ring element (Macaulay2Doc), to apply the first
        parameter to
      * l, a list (Macaulay2Doc), of RingElements to apply the
        first parameter to
      * m, a module (Macaulay2Doc), of vector fields
      * I, an ideal (Macaulay2Doc), an ideal of functions to apply
        the first parameter to
  * Outputs:
      * g, a ring element (Macaulay2Doc),
      * L, a list (Macaulay2Doc), of RingElements
      * J, an ideal (Macaulay2Doc),

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

Apply the vector field(s) represented by M, V, or m, to the second parameter,
that is, use the vector field(s) as differential operator(s).

When the first parameter is a Matrix (Macaulay2Doc), or a
Vector (Macaulay2Doc), then the return type matches the second
parameter. If that is a RingElement (Macaulay2Doc), then
there must only be 1 column in the matrix. When the second parameter is a
List (Macaulay2Doc), l of RingElement (Macaulay2Doc),s,
then the returned List (Macaulay2Doc), is formed by applying each
vector field in turn to the first entry of l, then each vector field to the
second entry of l, etc.

+--------------------------------------+
|i1 : R=QQ[x,y,z];                     |
+--------------------------------------+
|i2 : A=matrix {{x},{y},{0}};          |
|                                      |
|             3       1                |
|o2 : Matrix R  <--- R                 |
+--------------------------------------+
|i3 : B=matrix {{0},{0},{z}};          |
|                                      |
|             3       1                |
|o3 : Matrix R  <--- R                 |
+--------------------------------------+
|i4 : f=x*y-z^2;                       |
+--------------------------------------+
|i5 : applyVectorField(A,f)            |
|                                      |
|o5 = 2x*y                             |
|                                      |
|o5 : R                                |
+--------------------------------------+
|i6 : applyVectorField(A,{f,x*f})      |
|                                      |
|              2       2               |
|o6 = {2x*y, 3x y - x*z }              |
|                                      |
|o6 : List                             |
+--------------------------------------+
|i7 : applyVectorField(A|B,{f,x*f})    |
|                                      |
|               2    2       2       2 |
|o7 = {2x*y, -2z , 3x y - x*z , -2x*z }|
|                                      |
|o7 : List                             |
+--------------------------------------+

When the first parameter is a Module (Macaulay2Doc), then the
return type is an Ideal (Macaulay2Doc). Applying a Module (Macaulay2Doc),
to a RingElement (Macaulay2Doc), gives
the Ideal (Macaulay2Doc), generated by applying each generator to
the function. Applying a Module (Macaulay2Doc), to an Ideal (Macaulay2Doc),
I produces the Ideal (Macaulay2Doc), generated
by applying every element of the module to every element of I; this is
generated by not only the functions formed by applying each generator of the
module to each generator of I (as might be computed by the (Matrix,List)
version of this function), but also I times the ideal of coefficients of the
generators of the module.

+-------------------------------------------------------------+
|i8 : applyVectorField(image A,f)                             |
|                                                             |
|o8 = ideal(2x*y)                                             |
|                                                             |
|o8 : Ideal of R                                              |
+-------------------------------------------------------------+
|i9 : applyVectorField(image A,ideal (f))                     |
|                                                             |
|                    2     2                                  |
|o9 = ideal (x*y, y*z , x*z )                                 |
|                                                             |
|o9 : Ideal of R                                              |
+-------------------------------------------------------------+
|i10 : trim(ideal(applyVectorField(A,f))+ideal(f)*minors(1,A))|
|                                                             |
|                     2     2                                 |
|o10 = ideal (x*y, y*z , x*z )                                |
|                                                             |
|o10 : Ideal of R                                             |
+-------------------------------------------------------------+

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields
  * derlog -- compute the logarithmic (tangent) vector fields to
    an ideal
  * der -- compute the module of vector fields which send one set
    to another

Ways to use applyVectorField :
==============================

  * "applyVectorField(Matrix,List)"
  * "applyVectorField(Matrix,RingElement)"
  * "applyVectorField(Module,Ideal)"
  * "applyVectorField(Module,RingElement)"
  * "applyVectorField(Vector,List)"
  * "applyVectorField(Vector,RingElement)"

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

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

bracket -- compute the Lie bracket of vector fields
***************************************************

Synopsis
========

  * Usage:
        M=bracket(M1,M2)
        M=bracket(M1,M2,L)
        V=bracket(V1,V2)
        m=bracket(m1,m2)
  * Inputs:
      * M1, a matrix (Macaulay2Doc), of vector fields
      * M2, a matrix (Macaulay2Doc), of vector fields
      * L, a list (Macaulay2Doc), of 2-element lists, giving
        indices of columns of M1 and of M2
      * V1, a vector (Macaulay2Doc), vector from a matrix of
        vector fields
      * V2, a vector (Macaulay2Doc), vector from a matrix of
        vector fields
      * m1, a module (Macaulay2Doc), of vector fields
      * m2, a module (Macaulay2Doc), of vector fields
  * Outputs:
      * M, a matrix (Macaulay2Doc),
      * V, a vector (Macaulay2Doc),
      * m, a module (Macaulay2Doc), where the output type matches
        the input type

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

This computes the Lie bracket of pairs of vector fields from the first and
second parameters. If $D_1$ and $D_2$ are vector fields, then the Lie bracket
of $D_1$ and $D_2$, denoted $[D_1,D_2]$, is the vector field $F$ such that
$F(g)=D_1(D_2(g))-D_2(D_1(g))$ for all $g$, where $V(f)$ denotes the operation
of applying a vector field to a function (see applyVectorField).

When the first two parameters are matrices M1 and M2, this function returns a
Matrix (Macaulay2Doc), of (numColumns(M1))*(numColumns(M2))
columns, consisting of all possible brackets of a column from M1 with a column
from M2. If a specific ordering (or subset) of the brackets is desired, then a
List (Macaulay2Doc), of column index pairs should also be provided.

When the first two parameters are Vector (Macaulay2Doc),s, this
returns the Vector (Macaulay2Doc), formed by the Lie bracket of
the two vector fields.

When the parameters are Module (Macaulay2Doc),s m1 and m2, then we
compute the module generated by $[X,Y]$, for $X$ in m1 and $Y$ in m2. This is a
superset of the module generated by the brackets of the generators! (A
calculation shows that bracket(m1,m2) is generated by image bracket(gens
m1,gens m2), I1*m2, and I2*m1, where I1 is the ideal generated by the
coefficients of the generators of m1, and similarly I2.)

See differences between certain bracketing functions,
for more details on the differences.

+----------------------------------------------------------------+
|i1 : R=QQ[x,y];                                                 |
+----------------------------------------------------------------+
|i2 : A=matrix {{0},{x}};                                        |
|                                                                |
|             2       1                                          |
|o2 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i3 : B=matrix {{x^2},{y}};                                      |
|                                                                |
|             2       1                                          |
|o3 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i4 : C=matrix {{1},{x}};                                        |
|                                                                |
|             2       1                                          |
|o4 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i5 : bracket(A,B)                                               |
|                                                                |
|o5 = | 0     |                                                  |
|     | -x2+x |                                                  |
|                                                                |
|             2       1                                          |
|o5 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i6 : bracket(B,A)==-bracket(A,B)                                |
|                                                                |
|o6 = true                                                       |
+----------------------------------------------------------------+
|i7 : bracket(A,C)                                               |
|                                                                |
|o7 = | 0  |                                                     |
|     | -1 |                                                     |
|                                                                |
|             2       1                                          |
|o7 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i8 : bracket(A_0,C_0)                                           |
|                                                                |
|o8 = |  0 |                                                     |
|     | -1 |                                                     |
|                                                                |
|      2                                                         |
|o8 : R                                                          |
+----------------------------------------------------------------+
|i9 : bracket(A,B|C)                                             |
|                                                                |
|o9 = | 0     0  |                                               |
|     | -x2+x -1 |                                               |
|                                                                |
|             2       2                                          |
|o9 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i10 : bracket(A|C,B|C,{(0,0),(1,1)})===bracket(A,B)|bracket(C,C)|
|                                                                |
|o10 = true                                                      |
+----------------------------------------------------------------+
|i11 : bracket(A|C,B|C,{{0,1}})===bracket(A,C)                   |
|                                                                |
|o11 = true                                                      |
+----------------------------------------------------------------+

Providing Module (Macaulay2Doc),s computes something much
different:

+-------------------------------------+
|i12 : trim bracket(image(A),image(B))|
|                                     |
|o12 = image | 0 0  0    x3 |         |
|            | x xy x2-x 0  |         |
|                                     |
|                              2      |
|o12 : R-module, submodule of R       |
+-------------------------------------+

because, for example,

+-----------------------------------------+
|i13 : (2*x+1)*bracket(A,B)-bracket(x*A,B)|
|                                         |
|o13 = | 0 |                              |
|      | x |                              |
|                                         |
|              2       1                  |
|o13 : Matrix R  <--- R                   |
+-----------------------------------------+

An action of SL_2 on GL_2 differentiates to the following vector fields:

+-----------------------------------+
|i14 : R=QQ[a,b,c,d];               |
+-----------------------------------+
|i15 : e=matrix {{c},{d},{0},{0}};  |
|                                   |
|              4       1            |
|o15 : Matrix R  <--- R             |
+-----------------------------------+
|i16 : f=matrix {{0},{0},{a},{b}};  |
|                                   |
|              4       1            |
|o16 : Matrix R  <--- R             |
+-----------------------------------+
|i17 : h=matrix {{-a},{-b},{c},{d}};|
|                                   |
|              4       1            |
|o17 : Matrix R  <--- R             |
+-----------------------------------+
|i18 : L=e|f|h;                     |
|                                   |
|              4       3            |
|o18 : Matrix R  <--- R             |
+-----------------------------------+

Verify that this is a representation of sl_2, where [e,f]=h, [h,f]=-2f,
[h,e]=2e.

+-------------------------+
|i19 : bracket(e,f)-h==0  |
|                         |
|o19 = true               |
+-------------------------+
|i20 : bracket(h,f)+2*f==0|
|                         |
|o20 = true               |
+-------------------------+
|i21 : bracket(h,e)-2*e==0|
|                         |
|o21 = true               |
+-------------------------+

Of course we should have [L,L]=L:

+-----------------------------------+
|i22 : bracket(L,L)                 |
|                                   |
|o22 = | 0 -a -2c a  0 0  2c 0   0 ||
|      | 0 -b -2d b  0 0  2d 0   0 ||
|      | 0 c  0   -c 0 2a 0  -2a 0 ||
|      | 0 d  0   -d 0 2b 0  -2b 0 ||
|                                   |
|              4       9            |
|o22 : Matrix R  <--- R             |
+-----------------------------------+
|i23 : image bracket(L,L)==image L  |
|                                   |
|o23 = true                         |
+-----------------------------------+

Caveat
======

The Matrix (Macaulay2Doc), and Module (Macaulay2Doc),
versions of this routine compute different things; see differences between certain bracketing functions.

See also
========

  * commutator -- the commutator of a collection of vector
    fields
  * differences between certain bracketing functions
    -- The difference between certain bracketing
    functions
  * VectorFields -- a package for manipulating polynomial vector
    fields

Ways to use bracket :
=====================

  * "bracket(Matrix,Matrix)"
  * "bracket(Matrix,Matrix,List)"
  * "bracket(Module,Module)"
  * "bracket(Vector,Vector)"

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

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

commutator -- the commutator of a collection of vector fields
*************************************************************

Synopsis
========

  * Usage:
        N=commutator(M)
        n=commutator(m)
  * Inputs:
      * M, a matrix (Macaulay2Doc), of vector fields
      * m, a module (Macaulay2Doc), of vector fields
  * Outputs:
      * N, a matrix (Macaulay2Doc), with columns containing the
        brackets of pairs of columns of M
      * n, a module (Macaulay2Doc), the module generated by
        brackets of elements of m

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

When given a Matrix (Macaulay2Doc), this returns a Matrix (Macaulay2Doc),
with columns containing the brackets of pairs of columns
of M.

When given a Module (Macaulay2Doc), this returns the
Module (Macaulay2Doc), generated by $[X,Y]$, for $X$ and $Y$ in the
module m. This is a superset of the module generated by the brackets of
generators of m; see bracket, for more details.

In either case, see commutator, computes much the same thing as
calling bracket, with repeated parameters, but is more efficient
because it takes advantage of skew-symmetry.

See differences between certain bracketing functions,
for more information.

+-----------------------------------------------------------------------------+
|i1 : R=QQ[x,y];                                                              |
+-----------------------------------------------------------------------------+
|i2 : D=derlog(ideal (x*y*(x-y)))                                             |
|                                                                             |
|o2 = image | x 0     |                                                       |
|           | y xy-y2 |                                                       |
|                                                                             |
|                             2                                               |
|o2 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i3 : commutator(gens D)                                                      |
|                                                                             |
|o3 = | 0     |                                                               |
|     | xy-y2 |                                                               |
|                                                                             |
|             2       1                                                       |
|o3 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i4 : bracket(gens D,gens D)                                                  |
|                                                                             |
|o4 = | 0 0     0      0 |                                                    |
|     | 0 xy-y2 -xy+y2 0 |                                                    |
|                                                                             |
|             2       4                                                       |
|o4 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i5 : commutator(D)                                                           |
|                                                                             |
|o5 = image | 0     x2 0       0 0 xy 0      x2y-xy2 0            |           |
|           | xy-y2 xy x2y-xy2 0 0 y2 xy2-y3 xy2-y3  x2y2-2xy3+y4 |           |
|                                                                             |
|                             2                                               |
|o5 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i6 : bracket(D,D)                                                            |
|                                                                             |
|o6 = image | 0 0     0      0 x2 0       0 0 xy 0      x2y-xy2 0             |
|           | 0 xy-y2 -xy+y2 0 xy x2y-xy2 0 0 y2 xy2-y3 xy2-y3  x2y2-2xy3+y4  |
|                                                                             |
|                             2                                               |
|o6 : R-module, submodule of R                                                |
|-----------------------------------------------------------------------------|
|x2 0       0 0 xy 0      x2y-xy2 0            |                              |
|xy x2y-xy2 0 0 y2 xy2-y3 xy2-y3  x2y2-2xy3+y4 |                              |
+-----------------------------------------------------------------------------+

Caveat
======

The Matrix (Macaulay2Doc), and Module (Macaulay2Doc),
versions of this routine compute different things; see differences between certain bracketing functions.

See also
========

  * bracket -- compute the Lie bracket of vector fields
  * differences between certain bracketing functions
    -- The difference between certain bracketing
    functions
  * VectorFields -- a package for manipulating polynomial vector
    fields

Ways to use commutator :
========================

  * "commutator(Matrix)"
  * "commutator(Module)"

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

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

der -- compute the module of vector fields which send one set to another
************************************************************************

Synopsis
========

  * Usage:
        m=der(I,J)
        m=der(L,J)
  * Inputs:
      * J, an ideal (Macaulay2Doc),
      * I, an ideal (Macaulay2Doc), over the same ring as J
      * L, a visible list (Macaulay2Doc), of RingElements in
        the same ring as J
  * Outputs:
      * m, a module (Macaulay2Doc), the module of derivations
        sending I or L to J

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

This computes the module of vector fields that, as derivations, send each
element of I (or L) to an element of J. This can be used to calculate, for
example, the module of vector fields tangent to an algebraic variety (see
derlog).

Note that der(I,J) is always a subset of der(list of generators of I,J), and
frequently a proper subset.

For der(L,J), the computation is done by finding the syzygies between the
partial derivatives of the entries of L and the generators of J. This method of
computation was adapted from Singular's KVequiv.lib, written by Anne
Frühbis-Krüger.

For der(I,J), we intersect der(list of generators of I,J) with the free module
consisting of vector fields with coefficients in J:I; the latter is unnecessary
when I is a subset of J.

For example, consider the following ideals.

+-------------------+
|i1 : R=QQ[x,y];    |
+-------------------+
|i2 : I=ideal (x*y);|
|                   |
|o2 : Ideal of R    |
+-------------------+
|i3 : J=ideal (0_R);|
|                   |
|o3 : Ideal of R    |
+-------------------+
|i4 : K=ideal (x,y);|
|                   |
|o4 : Ideal of R    |
+-------------------+

Every vector field sends the zero ideal to zero:

+-------------------+
|i5 : der(J,I)      |
|                   |
|      2            |
|o5 = R             |
|                   |
|o5 : R-module, free|
+-------------------+
|i6 : der(J,K)      |
|                   |
|      2            |
|o6 = R             |
|                   |
|o6 : R-module, free|
+-------------------+

This finds the vector fields tangent to x*y=0 (see derlog):

+------------------------------+
|i7 : D=der(I,I)               |
|                              |
|o7 = image | x 0 |            |
|           | 0 y |            |
|                              |
|                             2|
|o7 : R-module, submodule of R |
+------------------------------+
|i8 : applyVectorField(D,I)    |
|                              |
|o8 = ideal(x*y)               |
|                              |
|o8 : Ideal of R               |
+------------------------------+

This finds the vector fields annihilating x*y (see derlogH):

+------------------------------+
|i9 : D=der({x*y},J)           |
|                              |
|o9 = image | x  |             |
|           | -y |             |
|                              |
|                             2|
|o9 : R-module, submodule of R |
+------------------------------+

This is different than

+-------------------------------+
|i10 : der(I,J)                 |
|                               |
|o10 = image 0                  |
|                               |
|                              2|
|o10 : R-module, submodule of R |
+-------------------------------+

because, for example, the generator of D does not annihilate x^2*y:

+------------------------------------+
|i11 : applyVectorField(gens D,x^2*y)|
|                                    |
|       2                            |
|o11 = x y                           |
|                                    |
|o11 : R                             |
+------------------------------------+

Another illustration of the difference is:

+-------------------------------+
|i12 : der({x},ideal (y))       |
|                               |
|o12 = image | 0 y |            |
|            | 1 0 |            |
|                               |
|                              2|
|o12 : R-module, submodule of R |
+-------------------------------+
|i13 : der(ideal (x),ideal (y)) |
|                               |
|o13 = image | y 0 |            |
|            | 0 y |            |
|                               |
|                              2|
|o13 : R-module, submodule of R |
+-------------------------------+

This illustrates a basic identity:

+------------------------------------------------------------+
|i14 : intersect(der(ideal (x),K),der(ideal (y),K))==der(K,K)|
|                                                            |
|o14 = true                                                  |
+------------------------------------------------------------+

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields
  * Ideal : Ideal (missing documentation)
  * derlog -- compute the logarithmic (tangent) vector fields to
    an ideal
  * derlogH -- compute the logarithmic (tangent) vector fields
    to an ideal

Ways to use der :
=================

  * "der(Ideal,Ideal)"
  * "der(VisibleList,Ideal)"

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

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

derivedSeries -- compute the derived series of a set of vector fields
*********************************************************************

Synopsis
========

  * Usage:
        L=derivedSeries(k,M)
        L=derivedSeries(k,m)
  * Inputs:
      * k, an integer (Macaulay2Doc), a nonnegative integer
      * M, a matrix (Macaulay2Doc), of vector fields
      * m, a module (Macaulay2Doc), of vector fields
  * Outputs:
      * L, a list (Macaulay2Doc), containing m or M, and the first
        k terms of the derived series. The types of the terms of the list
        agrees with the input type.

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

Compute the first few terms of the derived series of a set of vector fields.
For an object $n$, if we define $n^{(0)}=n$ and
$n^{(i+1)}=bracket(n^{(i)},n^{(i)})$, then $n^{(i)}$ is the $i$th term of the
derived series, and will be in the $i$th index position of the returned list.

As with bracket, this function computes different things,
depending on the type of the parameter. See differences between certain bracketing functions,
for
more information.

The following Lie algebra is generated by a finite-dimensional representation
of gl_2.

+------------------------------+
|i1 : R=QQ[a,b,c];             |
+------------------------------+
|i2 : D=derlog(a*c-b^2)        |
|                              |
|o2 = image | 2b a  0  0  |    |
|           | c  0  b  a  |    |
|           | 0  -c 2c 2b |    |
|                              |
|                             3|
|o2 : R-module, submodule of R |
+------------------------------+

The derived series (when provided with a Matrix (Macaulay2Doc))
stabilizes as a representation of sl_2:

+-----------------------------------------------------------------------------+
|i3 : ds=derivedSeries(3,gens D)                                              |
|                                                                             |
|o3 = {| 2b a  0  0  |, | 2b -2b 0 -2a 0  0   |, | 0 0 0 -4b 4b 0 -2a 2a  0   |
|      | c  0  b  a  |  | c  -c  0 0   a  -a  |  | 0 0 0 -2c 2c 0 0   0   0   |
|      | 0  -c 2c 2b |  | 0  0   0 2c  2b -2b |  | 0 0 0 0   0  0 2c  -2c 0   |
|     ------------------------------------------------------------------------|
|     0   2a  -2a 0 0  0 |, | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 8b -8b 0 0 0|
|     -2a 0   0   0 2a 0 |  | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 4c -4c 0 0 0|
|     -4b -2c 2c  0 4b 0 |  | 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0  0   0 0 0|
|     ------------------------------------------------------------------------|
|     0 -8b 8b 0 0 0 0 0 0 0 0 0 0 0 0 0 -8a 8a  0 0  0   0 0 0 0 -8b 8b 0 0 0|
|     0 -4c 4c 0 0 0 0 0 0 0 0 0 0 0 0 0 0   0   0 4a -4a 0 0 0 0 -4c 4c 0 0 0|
|     0 0   0  0 0 0 0 0 0 0 0 0 0 0 0 0 8c  -8c 0 8b -8b 0 0 0 0 0   0  0 0 0|
|     ------------------------------------------------------------------------|
|     0 0  0 0 0 8b -8b 0 0 0 0 0   0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 8a  -8a 0 |
|     0 4a 0 0 0 4c -4c 0 0 0 0 -4a 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0   0   0 |
|     0 8b 0 0 0 0  0   0 0 0 0 -8b 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 -8c 8c  0 |
|     ------------------------------------------------------------------------|
|     0   0  0 0 0  0   0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 |}                      |
|     -4a 4a 0 0 4a -4a 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 |                       |
|     -8b 8b 0 0 8b -8b 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 |                       |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : apply(ds,f->gens trim image f)                                          |
|                                                                             |
|o4 = {| 2b a  0  0  |, | 2b a  0  |, | 2b a  0  |, | 2b a  0  |}             |
|      | c  0  b  a  |  | c  0  a  |  | c  0  a  |  | c  0  a  |              |
|      | 0  -c 2c 2b |  | 0  -c 2b |  | 0  -c 2b |  | 0  -c 2b |              |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

The derived series (when provided with a Module (Macaulay2Doc))
stabilizes immediately with a linear part isomorphic to sl_2, and a
higher-order part equal to ideal (a,b,c)*D.

+-----------------------------------------------------------------------------+
|i5 : derivedSeries(3,D)                                                      |
|                                                                             |
|o5 = {image | 2b a  0  0  |, image | 2b a  0  0   0   0     |, image | 2b a  |
|            | c  0  b  a  |        | c  0  a  bc  b2  0     |        | c  0  |
|            | 0  -c 2c 2b |        | 0  -c 2b 2c2 2bc b2-ac |        | 0  -c |
|     ------------------------------------------------------------------------|
|     0  0   0   0     |, image | 2b a  0  0   0   0     |}                   |
|     a  bc  b2  0     |        | c  0  a  bc  b2  0     |                    |
|     2b 2c2 2bc b2-ac |        | 0  -c 2b 2c2 2bc b2-ac |                    |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : trim((image commutator(gens D))+(ideal (a,b,c))*D)                      |
|                                                                             |
|o6 = image | 2b a  0  0   0   0     |                                        |
|           | c  0  a  bc  b2  0     |                                        |
|           | 0  -c 2b 2c2 2bc b2-ac |                                        |
|                                                                             |
|                             3                                               |
|o6 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+

This Lie algebra is generated by a finite-dimensional representation of t_2, a
solvable Borel subalgebra of gl_2. Consequently, the linear part disappears:

+-----------------------------------------------------------------------------+
|i7 : D=derlog(a*(a*c-b^2))                                                   |
|                                                                             |
|o7 = image | a  0  0  |                                                      |
|           | 0  b  a  |                                                      |
|           | -c 2c 2b |                                                      |
|                                                                             |
|                             3                                               |
|o7 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i8 : derivedSeries(3,gens D)                                                 |
|                                                                             |
|o8 = {| a  0  0  |, | 0 0  0   |, 0, 0}                                      |
|      | 0  b  a  |  | 0 a  -a  |                                             |
|      | -c 2c 2b |  | 0 2b -2b |                                             |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : derivedSeries(3,D)                                                      |
|                                                                             |
|o9 = {image | a  0  0  |, image | 0  ac  0   ab  0   a2  0     |, image |    |
|            | 0  b  a  |        | a  0   bc  0   b2  0   0     |        |    |
|            | -c 2c 2b |        | 2b -c2 2c2 -bc 2bc -ac b2-ac |        |    |
|     ------------------------------------------------------------------------|
|     2ab  0      a2  0   0     0   2ac2 0    0   |, image | 2ab2+a2c  a2b    |
|     -ac  2b2+ac 0   ab  0     a2  bc2  ac2  bc3 |        | 0         0      |
|     -4bc 6bc    -ac 2ac b2-ac 2ab 0    2bc2 2c4 |        | -4b2c+ac2 -abc   |
|     ------------------------------------------------------------------------|
|     0    0    a3   0    0      0       0    6abc2 0         a2c2 0    0     |
|     a2c  ab2  0    a2b  0      0       a3   ac3   2b2c2-ac3 0    abc2 b3c   |
|     2abc 2abc -a2c 2a2c b3-abc ab2-a2c 2a2b -4bc3 2bc3      -ac3 2ac3 2ac3  |
|     ------------------------------------------------------------------------|
|     0        0     0    2ac5 0   |}                                         |
|     0        b4    ac4  bc5  bc7 |                                          |
|     b2c2-ac3 2abc2 2bc4 0    2c8 |                                          |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * commutator -- the commutator of a collection of vector
    fields
  * lowerCentralSeries -- compute the lower central
    series of a set of vector fields
  * differences between certain bracketing functions
    -- The difference between certain bracketing
    functions
  * VectorFields -- a package for manipulating polynomial vector
    fields

Ways to use derivedSeries :
===========================

  * "derivedSeries(ZZ,Matrix)"
  * "derivedSeries(ZZ,Module)"

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

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

derlog -- compute the logarithmic (tangent) vector fields to an ideal
*********************************************************************

Synopsis
========

  * Usage:
        m=derlog(I)
        m=derlog(f)
        n=derlogH(L)
        n=derlogH(f)
  * Inputs:
      * I, an ideal (Macaulay2Doc),
      * f, a ring element (Macaulay2Doc),
      * L, a list (Macaulay2Doc), nonempty, of RingElements
  * Outputs:
      * m, a module (Macaulay2Doc), the module of logarithmic
        vector fields for I or ideal(f)
      * n, a module (Macaulay2Doc), the module of vector fields
        that annihilates f or the entries of L

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

derlog computes the module of logarithmic vector fields to an affine variety
defined by I or f; these are the ambient vector fields tangent to the variety.

derlogH computes the module of ambient vector fields tangent to all level sets
of f or of the entries of L.

Note that derlog(I)=der(I,I) and derlogH(L)=der(L,0); see der.

+------------------------------+
|i1 : R=QQ[x,y,z];             |
+------------------------------+
|i2 : f=x*y-z^2;               |
+------------------------------+
|i3 : derlog(ideal (f))        |
|                              |
|o3 = image | 2x 0  2z 0  |    |
|           | 0  2y 0  2z |    |
|           | z  z  y  x  |    |
|                              |
|                             3|
|o3 : R-module, submodule of R |
+------------------------------+
|i4 : derlogH(f)               |
|                              |
|o4 = image | x  2z 0  |       |
|           | -y 0  2z |       |
|           | 0  y  x  |       |
|                              |
|                             3|
|o4 : R-module, submodule of R |
+------------------------------+
|i5 : dH=derlogH({f})          |
|                              |
|o5 = image | x  2z 0  |       |
|           | -y 0  2z |       |
|           | 0  y  x  |       |
|                              |
|                             3|
|o5 : R-module, submodule of R |
+------------------------------+

Although every element of dH annihilates f, they do not annihilate the ideal
generated by f:

+------------------------------------------------+
|i6 : applyVectorField(dH,f)                     |
|                                                |
|o6 = ideal (0, 0, 0)                            |
|                                                |
|o6 : Ideal of R                                 |
+------------------------------------------------+
|i7 : applyVectorField(dH,ideal(f))              |
|                                                |
|                     3     2      2   2       2 |
|o7 = ideal (x*y*z - z , x*y  - y*z , x y - x*z )|
|                                                |
|o7 : Ideal of R                                 |
+------------------------------------------------+

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields
  * der -- compute the module of vector fields which send one set
    to another
  * isLogarithmic -- check if the given vector fields are
    logarithmic

Ways to use derlog :
====================

  * "derlog(Ideal)"
  * "derlog(RingElement)"

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

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

differences between certain bracketing functions -- The difference between certain bracketing functions
*******************************************************************************************************

This package contains a variety of functions that calculate or work with
brackets, including bracket, commutator,
derivedSeries, and lowerCentralSeries.
Each function has two variants: those that work on only
the provided vector fields, and those that work on a module of vector fields.
The former type accept a Matrix (Macaulay2Doc), as the parameter,
while the latter type accept a Module (Macaulay2Doc), as the
parameter.

The documentation for each function explains what is calculated, and how.

Here is an example to illustrate the difference.

+-------------------------------+
|i1 : R=QQ[x,y];                |
+-------------------------------+
|i2 : D=gens derlog(ideal (x*y))|
|                               |
|o2 = | x 0 |                   |
|     | 0 y |                   |
|                               |
|             2       2         |
|o2 : Matrix R  <--- R          |
+-------------------------------+
|i3 : bracket(D,D)              |
|                               |
|o3 = 0                         |
|                               |
|             2       4         |
|o3 : Matrix R  <--- R          |
+-------------------------------+
|i4 : commutator(D)             |
|                               |
|o4 = 0                         |
|                               |
|             2       1         |
|o4 : Matrix R  <--- R          |
+-------------------------------+

The generating vector fields of D commute but not all pairs of elements from
the module D are commutative:

+-----------------------------------------------------------------------------+
|i5 : co1=commutator(D|x*D|y*D)                                               |
|                                                                             |
|o5 = | 0 x2 0 0  0 0   0 xy -x2y x2y  0 0  0 0   -xy2 |                      |
|     | 0 0  0 xy 0 x2y 0 0  0    -xy2 0 y2 0 xy2 0    |                      |
|                                                                             |
|             2       15                                                      |
|o5 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i6 : commutator(D|x*D|y*D|x^2*D|x*y*D|y^2*D)                                 |
|                                                                             |
|o6 = | 0 x2 0 0  0 0   0 xy -x2y x2y  0 0  0 0   -xy2 2x3 0 x4 0    2x3y 0   |
|     | 0 0  0 xy 0 x2y 0 0  0    -xy2 0 y2 0 xy2 0    0   0 0  -x3y 0    0   |
|     ------------------------------------------------------------------------|
|     0    0 0    0 -x3y  0     0    x2y x2y 0 x3y   x2y2 x2y2 -x4y x4y    0  |
|     2x2y 0 2x3y 0 2x2y2 -x2y2 2x4y 0   0   0 -x2y2 0    0    0    -2x3y2 xy2|
|     ------------------------------------------------------------------------|
|     0   0    0    -x2y2 0 0    0    -x3y2 0 2xy2 -x2y2 2x2y2 0 2xy3 -2x3y2  |
|     xy2 x2y2 x2y2 xy3   0 x3y2 x3y2 x2y3  0 0    0     -xy3  0 0    0       |
|     ------------------------------------------------------------------------|
|     2x3y2  -x2y3 2x2y3 0 0   0 0    -xy3 0  0 0     -x2y3 0   -2xy4 |       |
|     -2x2y3 0     -xy4  0 2y3 0 2xy3 0    y4 0 2x2y3 0     xy4 0     |       |
|                                                                             |
|             2       66                                                      |
|o6 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+

In this case only the first-order terms are necessary to achieve the results
calculated by the Module (Macaulay2Doc), versions of the
functions:

+--------------------------------------------------------------+
|i7 : bracket(image D,image D)                                 |
|                                                              |
|o7 = image | 0 0 0 0 x2 0  0 0 0 0 xy 0  x2 0  0 0 0 0 xy 0  ||
|           | 0 0 0 0 0  xy 0 0 0 0 0  y2 0  xy 0 0 0 0 0  y2 ||
|                                                              |
|                             2                                |
|o7 : R-module, submodule of R                                 |
+--------------------------------------------------------------+
|i8 : commutator(image D)                                      |
|                                                              |
|o8 = image | 0 x2 0  0 0 0 0 xy 0  |                          |
|           | 0 0  xy 0 0 0 0 0  y2 |                          |
|                                                              |
|                             2                                |
|o8 : R-module, submodule of R                                 |
+--------------------------------------------------------------+
|i9 : bracket(image D,image D)==image co1                      |
|                                                              |
|o9 = true                                                     |
+--------------------------------------------------------------+
|i10 : commutator(image D)==image co1                          |
|                                                              |
|o10 = true                                                    |
+--------------------------------------------------------------+

See also
========

  * bracket -- compute the Lie bracket of vector fields
  * commutator -- the commutator of a collection of vector
    fields
  * derivedSeries -- compute the derived series of a set
    of vector fields
  * lowerCentralSeries -- compute the lower central
    series of a set of vector fields
  * VectorFields -- a package for manipulating polynomial vector
    fields

homogeneousVectorFieldDegree -- check if vector fields are homogeneous, and of what degree
******************************************************************************************

Synopsis
========

  * Usage:
        l=homogeneousVectorFieldDegree(M)
        l=homogeneousVectorFieldDegree(m)
  * Inputs:
      * M, a matrix (Macaulay2Doc), of vector fields
      * m, a module (Macaulay2Doc), of vector fields
  * Outputs:
      * l, a list (Macaulay2Doc), either of degrees or false if a
        vector field is not homogeneous

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

This finds the degree of each vector field. When given a Matrix (Macaulay2Doc),
the function checks the degree of each column. When
given a Module (Macaulay2Doc), the function checks the degree of
each generator.

In a coordinate system $x_1,\ldots,x_n$ with $x_i$ having degree $k_i$, each
$\partial_{x_i}$ has degree $-k_i$. Hence, a non-zero vector field $\sum_i
f_i\partial_{x_i}$ has degree $d$ if and only if for each $i$, $f_i$ is either
$0$ or weighted homogeneous of degree $d+k_i$. The zero vector field has degree
$-\infty$.

+---------------------------------------------------+
|i1 : R=QQ[x,y];                                    |
+---------------------------------------------------+
|i2 : M=matrix {{x^2,1,0,x^2,x*y},{y^2,0,0,y^4,y^2}}|
|                                                   |
|o2 = | x2 1 0 x2 xy |                              |
|     | y2 0 0 y4 y2 |                              |
|                                                   |
|             2       5                             |
|o2 : Matrix R  <--- R                              |
+---------------------------------------------------+
|i3 : homogeneousVectorFieldDegree(M)               |
|                                                   |
|o3 = {{1}, {-1}, -infinity, false, {1}}            |
|                                                   |
|o3 : List                                          |
+---------------------------------------------------+
|i4 : homogeneousVectorFieldDegree(image M)         |
|                                                   |
|o4 = {{1}, {-1}, -infinity, false, {1}}            |
|                                                   |
|o4 : List                                          |
+---------------------------------------------------+

We also handle non-standard degrees:

+---------------------------------------------------+
|i5 : R=QQ[x,y,Degrees=>{{3},{1}}];                 |
+---------------------------------------------------+
|i6 : M=matrix {{x^2,1,0,x^2,x*y},{y^2,0,0,y^4,y^2}}|
|                                                   |
|o6 = | x2 1 0 x2 xy |                              |
|     | y2 0 0 y4 y2 |                              |
|                                                   |
|             2       5                             |
|o6 : Matrix R  <--- R                              |
+---------------------------------------------------+
|i7 : homogeneousVectorFieldDegree(M)               |
|                                                   |
|o7 = {false, {-3}, -infinity, {3}, {1}}            |
|                                                   |
|o7 : List                                          |
+---------------------------------------------------+

and multidegrees:

+---------------------------------------------------+
|i8 : R=QQ[x,y,Degrees=>{{3,1},{1,1}}];             |
+---------------------------------------------------+
|i9 : M=matrix {{x^2,1,0,x^2,x*y},{y^2,0,0,y^4,y^2}}|
|                                                   |
|o9 = | x2 1 0 x2 xy |                              |
|     | y2 0 0 y4 y2 |                              |
|                                                   |
|             2       5                             |
|o9 : Matrix R  <--- R                              |
+---------------------------------------------------+
|i10 : homogeneousVectorFieldDegree(M)              |
|                                                   |
|o10 = {false, {-3, -1}, -infinity, false, {1, 1}}  |
|                                                   |
|o10 : List                                         |
+---------------------------------------------------+

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields
  * isHomogeneousVectorField -- determine
    whether a matrix or module is generated by homogeneous vector fields

Ways to use homogeneousVectorFieldDegree :
==========================================

  * "homogeneousVectorFieldDegree(Matrix)"
  * "homogeneousVectorFieldDegree(Module)"

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

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

isFiniteStratification -- checks if a stratification by integral submanifolds is finite
***************************************************************************************

Synopsis
========

  * Usage:
        b=isFiniteStratification(strat)
  * Inputs:
      * strat, an instance of the type StratificationByRank,
        the output of stratifyByRank,
        applied to a collection of vector fields
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), whether strat is a
        finite stratification

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

Let strat be the output of stratifyByRank, applied to a
module $L$ of vector fields. When $L$ is a Lie algebra, strat contains
information about the integral submanifolds of $L$; under the assumption that
$L$ is a Lie algebra, this function checks whether there are a finite number of
connected integral submanifolds.

The algorithm used, and perhaps even the term integral submanifold, is only
valid in real or complex geometry. This routine checks that, for all $j$, each
component of strat#j has dimension $<j$. It is up to the user to check that the
answers obtained by Macaulay2 (e.g., in QQ[x,y,z]) would not change if the
calculation was done over the real or complex numbers.

The algorithm is motivated by the results of section 4.3 of ``James Damon and
Brian Pike. Solvable groups, free divisors and nonisolated matrix singularities
II: Vanishing topology. Geom. Topol., 18(2):911-962, 2014'', available at
http://dx.doi.org/10.2140/gt.2014.18.911 or http://arxiv.org/abs/1201.1579.

To display progress reports, make debugLevel (Macaulay2Doc),
$>1$.

+---------------------------------+
|i1 : R=QQ[a,b,c];                |
+---------------------------------+
|i2 : f=a*b*(a-b)*(a-c*b)         |
|                                 |
|        2 2       3     3     2 2|
|o2 = - a b c + a*b c + a b - a b |
|                                 |
|o2 : R                           |
+---------------------------------+
|i3 : D=derlog(ideal (f))         |
|                                 |
|o3 = image | a 0    0     |      |
|           | b 0    ab-b2 |      |
|           | 0 bc-a -ac+a |      |
|                                 |
|                             3   |
|o3 : R-module, submodule of R    |
+---------------------------------+
|i4 : S=stratifyByRank(D);        |
+---------------------------------+

Since D has rank 0 on $a=b=0$, that is, the vector fields all vanish:

+-----------------+
|i5 : S#1         |
|                 |
|o5 = ideal (a, b)|
|                 |
|o5 : Ideal of R  |
+-----------------+

the stratification cannot be finite (every point on $a=b=0$ is its own
stratum):

+-----------------------------------------------------------------------------+
|i6 : isFiniteStratification(S)                                               |
|isFiniteStratification: Component ideal(b,a) has dim 1 but should be of dim  |
|                                                                             |
|o6 = false                                                                   |
|-----------------------------------------------------------------------------|
|<1 to have a finite stratification.                                          |
+-----------------------------------------------------------------------------+

This stratification is finite:

+----------------------------------------------+
|i7 : D=derlog(ideal (a*b*c))                  |
|                                              |
|o7 = image | a 0 0 |                          |
|           | 0 b 0 |                          |
|           | 0 0 c |                          |
|                                              |
|                             3                |
|o7 : R-module, submodule of R                 |
+----------------------------------------------+
|i8 : isFiniteStratification(stratifyByRank(D))|
|                                              |
|o8 = true                                     |
+----------------------------------------------+

Caveat
======

The assumption that $L$ is a Lie algebra is not checked.

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields
  * stratifyByRank -- compute ideals describing where
    the vector fields have a particular rank
  * isHolonomic -- test whether an algebraic set is
    holonomic
  * isHHolonomic -- test whether a hypersurface is
    H-holonomic

Ways to use isFiniteStratification :
====================================

  * "isFiniteStratification(StratificationByRank)"

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

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

isFreeDivisor -- check if the provided information is associated with a free divisor
************************************************************************************

Synopsis
========

  * Usage:
        t=isFreeDivisor(M)
        t=isFreeDivisor(m)
        t=isFreeDivisor(f)
  * Inputs:
      * M, a matrix (Macaulay2Doc), of vector fields, usually
        square
      * m, a module (Macaulay2Doc), of vector fields
      * f, a ring element (Macaulay2Doc), a polynomial
        defining a hypersurface
  * Outputs:
      * t, a Boolean value (Macaulay2Doc), whether M or m
        generate the module of vector fields for a free divisor, or whether f=0
        defines a free divisor

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

Determine whether the given object is associated to a free divisor, using a
variety of methods. A free divisor is a hypersurface germ $X$ for which the
associated module of logarithmic vector fields (see derlog) is
free.

When given a RingElement (Macaulay2Doc), f, this tests
whether f=0 is a free divisor by computing derlog(ideal (f)) and then testing
if this is a free module by computing a partial resolution (Macaulay2Doc).
This method may give false negatives if the
resolution computed is not minimal; use with caution.

When given a Matrix (Macaulay2Doc), M, this tests whether the
given vector fields are a free set of generators of the module of logarithmic
vector fields for a free divisor. A criterion of Kyoji Saito is used: if the
number of vector fields provided equals the dimension of the ambient space
(i.e., M is square), the vector fields generate a Lie algebra, and the
determinant of the matrix is reduced (square-free), then the provided vector
fields are a free basis of the free module derlog(ideal det(M)), and det(M)=0
defines a free divisor. This method may give false negatives if redundant
generators are provided.

When given a Module (Macaulay2Doc), this tests whether the module
is the module of logarithmic vector fields of a free divisor. The method
applies the Matrix (Macaulay2Doc), version of the command to the
generators given by gens(m). If the generators provided by generators (Macaulay2Doc),
are not minimal, then this may give false negatives;
use trim (Macaulay2Doc), first.

For example, this is not a free divisor:

+------------------------------+
|i1 : R=QQ[a,b,c];             |
+------------------------------+
|i2 : f=a*c-b^2;               |
+------------------------------+
|i3 : M=derlog(ideal (f))      |
|                              |
|o3 = image | 2b a  0  0  |    |
|           | c  0  b  a  |    |
|           | 0  -c 2c 2b |    |
|                              |
|                             3|
|o3 : R-module, submodule of R |
+------------------------------+
|i4 : isFreeDivisor(gens M)    |
|                              |
|o4 = false                    |
+------------------------------+
|i5 : isFreeDivisor(M)         |
|                              |
|o5 = false                    |
+------------------------------+
|i6 : isFreeDivisor(f)         |
|                              |
|o6 = false                    |
+------------------------------+

This is a free divisor:

+------------------------------+
|i7 : f=a*(a*c-b^2);           |
+------------------------------+
|i8 : M=derlog(ideal (f))      |
|                              |
|o8 = image | a  0  0  |       |
|           | 0  b  a  |       |
|           | -c 2c 2b |       |
|                              |
|                             3|
|o8 : R-module, submodule of R |
+------------------------------+
|i9 : isFreeDivisor(gens M)    |
|                              |
|o9 = true                     |
+------------------------------+
|i10 : isFreeDivisor(M)        |
|                              |
|o10 = true                    |
+------------------------------+
|i11 : isFreeDivisor(f)        |
|                              |
|o11 = true                    |
+------------------------------+

This is a free divisor:

+-------------------------------+
|i12 : f=a;                     |
+-------------------------------+
|i13 : D=derlog(ideal (f))      |
|                               |
|o13 = image | 0 0 a |          |
|            | 1 0 0 |          |
|            | 0 1 0 |          |
|                               |
|                              3|
|o13 : R-module, submodule of R |
+-------------------------------+
|i14 : isFreeDivisor(f)         |
|                               |
|o14 = true                     |
+-------------------------------+
|i15 : isFreeDivisor(D)         |
|                               |
|o15 = true                     |
+-------------------------------+

but the vector fields in M are not a generating set of the logarithmic vector
fields:

+-----------------------------------------+
|i16 : M=matrix {{a,0,0},{0,a,0},{0,0,1}};|
|                                         |
|              3       3                  |
|o16 : Matrix R  <--- R                   |
+-----------------------------------------+
|i17 : isSubset(image M,D)                |
|                                         |
|o17 = true                               |
+-----------------------------------------+
|i18 : isFreeDivisor(M)                   |
|                                         |
|o18 = false                              |
+-----------------------------------------+

False negatives can occur with a set of generators that is not minimal:

+--------------------------------------------+
|i19 : isFreeDivisor((gens D)|M)             |
|                                            |
|o19 = false                                 |
+--------------------------------------------+
|i20 : isFreeDivisor(trim image ((gens D)|M))|
|                                            |
|o20 = true                                  |
+--------------------------------------------+

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields
  * isLieAlgebra -- check that a module of vector fields
    is closed under the Lie bracket
  * derlog -- compute the logarithmic (tangent) vector fields to
    an ideal

Ways to use isFreeDivisor :
===========================

  * "isFreeDivisor(Matrix)"
  * "isFreeDivisor(Module)"
  * "isFreeDivisor(RingElement)"

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

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

isHHolonomic -- test whether a hypersurface is H-holonomic
**********************************************************

Synopsis
========

  * Usage:
        b=isHHolonomic(H)
  * Inputs:
      * H, a ring element (Macaulay2Doc), a nonzero function
        defining a hypersurface
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), whether the
        hypersurface is H-holonomic

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

Test if $X$, the algebraic set defined by H, is H-holonomic. Let $D$ be the
module of vector fields annihilating $H$ (see derlogH), a
submodule of the module of logarithmic vector fields for $H$. Then $X$ is
called H-holonomic if at any point $p$ in $X$, the generators of $D$ evaluated
at $p$ span the tangent space of the stratum containing $p$ of the canonical
Whitney stratification of $X$; equivalently, the collection of maximal integral
submanifolds of $D$ that are contained in $X$ will equal the canonical Whitney
stratification of $X$. The ``H'' in H-holonomic refers to the name of the
function.

The algorithm used essentially checks the dimensions of the components of the
sets given by stratifyByRank(derlog(ideal (H))) (see isHolonomic,
and isFiniteStratification) and
then compares these sets with those given by stratifyByRank(derlogH(H)).
Details may be found in section 4.3 of ``James Damon and Brian Pike. Solvable
groups, free divisors and nonisolated matrix singularities II: Vanishing
topology. Geom. Topol., 18(2):911-962, 2014'', available at
http://dx.doi.org/10.2140/gt.2014.18.911 or http://arxiv.org/abs/1201.1579.

To display progress reports, set debugLevel (Macaulay2Doc),>0.

+-----------------+
|i1 : R=QQ[a,b,c];|
+-----------------+

This hypersurface is not even holonomic, as the logarithmic vector fields have
rank 0 on $a=b=0$:

+-----------------------------------------------------------------------------+
|i2 : f=a*b*(a-b)*(a-c*b);                                                    |
+-----------------------------------------------------------------------------+
|i3 : derlog(ideal (f))                                                       |
|                                                                             |
|o3 = image | a 0    0     |                                                  |
|           | b 0    ab-b2 |                                                  |
|           | 0 bc-a -ac+a |                                                  |
|                                                                             |
|                             3                                               |
|o3 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i4 : derlogH(f)                                                              |
|                                                                             |
|o4 = image | ab      a2          |                                           |
|           | b2      -3ab+4b2    |                                           |
|           | -4bc+4a 4ac-12bc+8a |                                           |
|                                                                             |
|                             3                                               |
|o4 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i5 : isHHolonomic(f)                                                         |
|isFiniteStratification: Component ideal(b,a) has dim 1 but should be of dim  |
|                                                                             |
|o5 = false                                                                   |
|-----------------------------------------------------------------------------|
|<1 to have a finite stratification.                                          |
+-----------------------------------------------------------------------------+
|i6 : isHolonomic(f)                                                          |
|isFiniteStratification: Component ideal(b,a) has dim 1 but should be of dim  |
|                                                                             |
|o6 = false                                                                   |
|-----------------------------------------------------------------------------|
|<1 to have a finite stratification.                                          |
+-----------------------------------------------------------------------------+

This hypersurface is H-Holonomic, although the generators of D are linearly
dependent everywhere:

+------------------------------------------------+
|i7 : f=a*c-b^2;                                 |
+------------------------------------------------+
|i8 : D=gens derlogH(f)                          |
|                                                |
|o8 = | 2b a  0  |                               |
|     | c  0  a  |                               |
|     | 0  -c 2b |                               |
|                                                |
|             3       3                          |
|o8 : Matrix R  <--- R                           |
+------------------------------------------------+
|i9 : det(D)                                     |
|                                                |
|o9 = 0                                          |
|                                                |
|o9 : R                                          |
+------------------------------------------------+
|i10 : isHHolonomic(f)                           |
|                                                |
|o10 = true                                      |
+------------------------------------------------+
|i11 : S=stratifyByRank(D)                       |
|                                                |
|o11 = StratificationByRank{1 => ideal (a, b, c)}|
|                           2 => ideal (a, b, c) |
|                           3 => ideal ()        |
|                                                |
|o11 : StratificationByRank                      |
+------------------------------------------------+
|i12 : S#1                                       |
|                                                |
|o12 = ideal (a, b, c)                           |
|                                                |
|o12 : Ideal of R                                |
+------------------------------------------------+
|i13 : S#2                                       |
|                                                |
|o13 = ideal (a, b, c)                           |
|                                                |
|o13 : Ideal of R                                |
+------------------------------------------------+
|i14 : S#3                                       |
|                                                |
|o14 = ideal ()                                  |
|                                                |
|o14 : Ideal of R                                |
+------------------------------------------------+

The Whitney Umbrella is also H-Holonomic:

+---------------------+
|i15 : f=a^2-b^2*c;   |
+---------------------+
|i16 : isHHolonomic(f)|
|                     |
|o16 = true           |
+---------------------+

Caveat
======

See the warnings in isFiniteStratification.

See also
========

  * isHolonomic -- test whether an algebraic set is
    holonomic
  * isFiniteStratification -- checks if a
    stratification by integral submanifolds is finite
  * derlog -- compute the logarithmic (tangent) vector fields to
    an ideal
  * derlogH -- compute the logarithmic (tangent) vector fields
    to an ideal
  * stratifyByRank -- compute ideals describing where
    the vector fields have a particular rank
  * VectorFields -- a package for manipulating polynomial vector
    fields

Ways to use isHHolonomic :
==========================

  * "isHHolonomic(RingElement)"

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

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

isHolonomic -- test whether an algebraic set is holonomic
*********************************************************

Synopsis
========

  * Usage:
        b=isHolonomic(I)
        b=isHolonomic(f)
  * Inputs:
      * I, an ideal (Macaulay2Doc), defining an algebraic set
      * f, a ring element (Macaulay2Doc), a nonzero function
        defining a hypersurface
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), whether the algebraic
        set is holonomic

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

Test if $X$, the algebraic set defined by I or f, is holonomic. Let $D$ be the
module of logarithmic vector fields for I. Then $X$ is called holonomic if at
any point $p$ in $X$, the generators of $D$ evaluated at $p$ span the tangent
space of the stratum containing $p$ of the canonical Whitney stratification of
$X$; equivalently, the maximal integral submanifolds of $D$ equal the the
canonical Whitney stratification of $X$ (except that the complement of $X$
forms additional integral submanifold(s)).

The algorithm used amounts to computing
isFiniteStratification(stratifyByRank(derlog(I))) (see
isFiniteStratification, stratifyByRank,
see derlog). Details may be found in section 4.3 of
``James Damon and Brian Pike. Solvable groups, free divisors and nonisolated
matrix singularities II: Vanishing topology. Geom. Topol., 18(2):911-962,
2014'', available at http://dx.doi.org/10.2140/gt.2014.18.911 or
http://arxiv.org/abs/1201.1579. The basic idea, however, is present in (3.13)
of ``Kyoji Saito. Theory of logarithmic differential forms and logarithmic
vector fields. J. Fac. Sci. Univ. Tokyo Sect. IA Math., 27: 265-291, 1980''.

+-----------------+
|i1 : R=QQ[a,b,c];|
+-----------------+

This hypersurface is not holonomic, since gens(D) has rank 0 on the
$1$-dimensional space $a=b=0$:

+-----------------------------------------------------------------------------+
|i2 : f=a*b*(a-b)*(a-c*b);                                                    |
+-----------------------------------------------------------------------------+
|i3 : D=derlog(ideal (f))                                                     |
|                                                                             |
|o3 = image | a 0    0     |                                                  |
|           | b 0    ab-b2 |                                                  |
|           | 0 bc-a -ac+a |                                                  |
|                                                                             |
|                             3                                               |
|o3 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+
|i4 : isHolonomic(f)                                                          |
|isFiniteStratification: Component ideal(b,a) has dim 1 but should be of dim  |
|                                                                             |
|o4 = false                                                                   |
|-----------------------------------------------------------------------------|
|<1 to have a finite stratification.                                          |
+-----------------------------------------------------------------------------+

This is holonomic; the stratification consists of the origin, and the rest of
the surface $ac-b^2=0$:

+------------------------------+
|i5 : f=a*c-b^2;               |
+------------------------------+
|i6 : D=derlog(ideal (f))      |
|                              |
|o6 = image | 2b a  0  0  |    |
|           | c  0  b  a  |    |
|           | 0  -c 2c 2b |    |
|                              |
|                             3|
|o6 : R-module, submodule of R |
+------------------------------+
|i7 : isHolonomic(f)           |
|                              |
|o7 = true                     |
+------------------------------+
|i8 : S=stratifyByRank(D);     |
+------------------------------+
|i9 : S#1                      |
|                              |
|o9 = ideal (a, b, c)          |
|                              |
|o9 : Ideal of R               |
+------------------------------+
|i10 : S#2                     |
|                              |
|o10 = ideal (a, b, c)         |
|                              |
|o10 : Ideal of R              |
+------------------------------+
|i11 : S#3                     |
|                              |
|             2                |
|o11 = ideal(b  - a*c)         |
|                              |
|o11 : Ideal of R              |
+------------------------------+

The Whitney Umbrella is also holonomic; the stratification consists of the
origin, the rest of the line $a=b=0$, and the rest of the surface:

+--------------------------+
|i12 : f=a^2-b^2*c;        |
+--------------------------+
|i13 : D=derlog(ideal (f));|
+--------------------------+
|i14 : isHolonomic(f)      |
|                          |
|o14 = true                |
+--------------------------+
|i15 : S=stratifyByRank(D);|
+--------------------------+
|i16 : S#1                 |
|                          |
|o16 = ideal (a, b, c)     |
|                          |
|o16 : Ideal of R          |
+--------------------------+
|i17 : S#2                 |
|                          |
|o17 = ideal (a, b)        |
|                          |
|o17 : Ideal of R          |
+--------------------------+
|i18 : S#3                 |
|                          |
|             2     2      |
|o18 = ideal(b c - a )     |
|                          |
|o18 : Ideal of R          |
+--------------------------+

Caveat
======

See the warnings in isFiniteStratification.

Also, this usage of holonomic originates with Kyoji Saito and may vary from
other meanings of the word, particularly in D-module theory.

See also
========

  * isHHolonomic -- test whether a hypersurface is
    H-holonomic
  * derlog -- compute the logarithmic (tangent) vector fields to
    an ideal
  * stratifyByRank -- compute ideals describing where
    the vector fields have a particular rank
  * isFiniteStratification -- checks if a
    stratification by integral submanifolds is finite
  * VectorFields -- a package for manipulating polynomial vector
    fields

Ways to use isHolonomic :
=========================

  * "isHolonomic(Ideal)"
  * "isHolonomic(RingElement)"

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

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

isHomogeneousVectorField -- determine whether a matrix or module is generated by homogeneous vector fields
**********************************************************************************************************

Synopsis
========

  * Usage:
        b=isHomogeneousVectorField(M)
        b=isHomogeneousVectorField(m)
        b=isHomogeneousVectorField(M,s)
        b=isHomogeneousVectorField(m,s)
  * Inputs:
      * M, a matrix (Macaulay2Doc), of vector fields
      * m, a module (Macaulay2Doc), of vector fields
      * s, a list (Macaulay2Doc), of degrees
      * s, a set (Macaulay2Doc), of degrees
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), whether the vector
        fields are homogeneous, or homogeneous of a type in s

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

Determine whether the matrix or module is generated by homogeneous vector
fields, or homogeneous vector fields of degrees appearing in s. See
homogeneousVectorFieldDegree, for more
information on degrees.

This is not homogeneous because of $1 \partial_x + 2x \partial_y$:

+--------------------------------------+
|i1 : R=QQ[x,y];                       |
+--------------------------------------+
|i2 : M1=derlog(ideal (x^2-y))         |
|                                      |
|o2 = image | x  1  |                  |
|           | 2y 2x |                  |
|                                      |
|                             2        |
|o2 : R-module, submodule of R         |
+--------------------------------------+
|i3 : isHomogeneousVectorField(gens M1)|
|                                      |
|o3 = false                            |
+--------------------------------------+

This is homogeneous, of degree -1 and 0:

+--------------------------------------------+
|i4 : M2=gens derlog(ideal (x))              |
|                                            |
|o4 = | 0 x |                                |
|     | 1 0 |                                |
|                                            |
|             2       2                      |
|o4 : Matrix R  <--- R                       |
+--------------------------------------------+
|i5 : homogeneousVectorFieldDegree(M2)       |
|                                            |
|o5 = {{-1}, {0}}                            |
|                                            |
|o5 : List                                   |
+--------------------------------------------+
|i6 : isHomogeneousVectorField(M2)           |
|                                            |
|o6 = true                                   |
+--------------------------------------------+
|i7 : isHomogeneousVectorField(M2,{{-1},{0}})|
|                                            |
|o7 = true                                   |
+--------------------------------------------+

This is homogeneous, of degrees 0, 1, and -infinity:

+------------------------------------------------------+
|i8 : M3=matrix {{x,0,0},{0,y^2,0}}                    |
|                                                      |
|o8 = | x 0  0 |                                       |
|     | 0 y2 0 |                                       |
|                                                      |
|             2       3                                |
|o8 : Matrix R  <--- R                                 |
+------------------------------------------------------+
|i9 : homogeneousVectorFieldDegree(M3)                 |
|                                                      |
|o9 = {{0}, {1}, -infinity}                            |
|                                                      |
|o9 : List                                             |
+------------------------------------------------------+
|i10 : isHomogeneousVectorField(M3)                    |
|                                                      |
|o10 = true                                            |
+------------------------------------------------------+
|i11 : isHomogeneousVectorField(M3,{{1},{0}})          |
|                                                      |
|o11 = false                                           |
+------------------------------------------------------+
|i12 : isHomogeneousVectorField(M3,{-infinity,{1},{0}})|
|                                                      |
|o12 = true                                            |
+------------------------------------------------------+

If the parameter is a module, then the generators given by generators (Macaulay2Doc),
are studied. Consequently, the routine may return
false even though a module may have a homogeneous basis:

+--------------------------------------------+
|i13 : m=matrix {{0,0},{x,x^3+x}}            |
|                                            |
|o13 = | 0 0    |                            |
|      | x x3+x |                            |
|                                            |
|              2       2                     |
|o13 : Matrix R  <--- R                      |
+--------------------------------------------+
|i14 : isHomogeneousVectorField(image m)     |
|                                            |
|o14 = false                                 |
+--------------------------------------------+
|i15 : isHomogeneousVectorField(trim image m)|
|                                            |
|o15 = true                                  |
+--------------------------------------------+

Caveat
======

Despite the name, the function does not check the number of vector fields
provided.

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields
  * homogeneousVectorFieldDegree -- check
    if vector fields are homogeneous, and of what degree

Ways to use isHomogeneousVectorField :
======================================

  * "isHomogeneousVectorField(Matrix)"
  * "isHomogeneousVectorField(Matrix,List)"
  * "isHomogeneousVectorField(Matrix,Set)"
  * "isHomogeneousVectorField(Module)"
  * "isHomogeneousVectorField(Module,List)"
  * "isHomogeneousVectorField(Module,Set)"

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

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

isLieAlgebra -- check that a module of vector fields is closed under the Lie bracket
************************************************************************************

Synopsis
========

  * Usage:
        b=isLieAlgebra(m)
  * Inputs:
      * m, a module (Macaulay2Doc), of vector fields
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), whether the module is
        a Lie algebra of vector fields

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

Checks whether the module generated by the provided vector fields is closed
under the Lie bracket of vector fields (see bracket) and thus
forms a Lie algebra.

+-------------------+
|i1 : R=QQ[a,b,c,d];|
+-------------------+

An action of SL_2 on GL_2 differentiates to the following vector fields:

+----------------------------------+
|i2 : e=matrix {{c},{d},{0},{0}};  |
|                                  |
|             4       1            |
|o2 : Matrix R  <--- R             |
+----------------------------------+
|i3 : f=matrix {{0},{0},{a},{b}};  |
|                                  |
|             4       1            |
|o3 : Matrix R  <--- R             |
+----------------------------------+
|i4 : h=matrix {{-a},{-b},{c},{d}};|
|                                  |
|             4       1            |
|o4 : Matrix R  <--- R             |
+----------------------------------+

Verify that this is sl_2, where [e,f]=h, [h,f]=-2f, [h,e]=2e.

+------------------------+
|i5 : bracket(e,f)-h==0  |
|                        |
|o5 = true               |
+------------------------+
|i6 : bracket(h,f)+2*f==0|
|                        |
|o6 = true               |
+------------------------+
|i7 : bracket(h,e)-2*e==0|
|                        |
|o7 = true               |
+------------------------+

In particular, the module these generate form a Lie algebra:

+--------------------------------+
|i8 : isLieAlgebra(image (e|f|h))|
|                                |
|o8 = true                       |
+--------------------------------+

Caveat
======

There is no isLieAlgebra(Matrix), yet.

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields

Ways to use isLieAlgebra :
==========================

  * "isLieAlgebra(Module)"

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

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

isLogarithmic -- check if the given vector fields are logarithmic
*****************************************************************

Synopsis
========

  * Usage:
        b=isLogarithmic(M,I)
        b=isLogarithmic(V,I)
        b=isLogarithmic(m,I)
  * Inputs:
      * M, a matrix (Macaulay2Doc), of vector fields
      * V, a vector (Macaulay2Doc), a column from a matrix of
        vector fields
      * m, a module (Macaulay2Doc), of vector fields
      * I, an ideal (Macaulay2Doc), the ideal
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), whether the vector
        fields are in derlog(I)

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

Check if the vector field(s) given are in the module of logarithmic vector
fields of I (see derlog). This function does not compute
derlog(I), but instead applies the vector fields to the generators of I and
checks if the result lies in I.

+--------------------------------------------+
|i1 : R=QQ[x,y,z];                           |
+--------------------------------------------+
|i2 : f=x*y-z^2;                             |
+--------------------------------------------+
|i3 : I=ideal (f);                           |
|                                            |
|o3 : Ideal of R                             |
+--------------------------------------------+
|i4 : M=matrix {{x,2*z,2*z},{y,0,0},{z,y,x}};|
|                                            |
|             3       3                      |
|o4 : Matrix R  <--- R                       |
+--------------------------------------------+
|i5 : applyVectorField(M,{f})                |
|                                            |
|               2                            |
|o5 = {2x*y - 2z , 0, - 2x*z + 2y*z}         |
|                                            |
|o5 : List                                   |
+--------------------------------------------+
|i6 : isLogarithmic(M,I)                     |
|                                            |
|o6 = false                                  |
+--------------------------------------------+
|i7 : isLogarithmic(M_{0,1},I)               |
|                                            |
|o7 = true                                   |
+--------------------------------------------+
|i8 : isLogarithmic(derlog(I),I)             |
|                                            |
|o8 = true                                   |
+--------------------------------------------+

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields
  * derlog -- compute the logarithmic (tangent) vector fields to
    an ideal
  * applyVectorField -- apply a vector field to a
    function or functions

Ways to use isLogarithmic :
===========================

  * "isLogarithmic(Matrix,Ideal)"
  * "isLogarithmic(Module,Ideal)"
  * "isLogarithmic(Vector,Ideal)"

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

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

isVectorField -- test whether a module or matrix can be interpreted as a collection of vector fields
****************************************************************************************************

Synopsis
========

  * Usage:
        b=isVectorField(m)
        b=isVectorField(M)
  * Inputs:
      * m, a module (Macaulay2Doc),
      * M, a matrix (Macaulay2Doc),
  * Outputs:
      * b, a Boolean value (Macaulay2Doc), whether the provided
        module or matrix can be interpreted as a collection of vector fields

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

This determines whether the provided Module (Macaulay2Doc), or
Matrix (Macaulay2Doc), can be interpreted as a collection of
vector fields.

For a Module (Macaulay2Doc), to be interpreted as a module of
vector fields, the module must be presented as a submodule of a free module
whose rank equals the number of variables in the ring.

+------------------------------------------------+
|i1 : R=QQ[x,y];                                 |
+------------------------------------------------+
|i2 : isVectorField(image matrix {{x,y^2}})      |
|                                                |
|o2 = false                                      |
+------------------------------------------------+
|i3 : isVectorField(image matrix {{x,y^2},{0,0}})|
|                                                |
|o3 = true                                       |
+------------------------------------------------+

For a Matrix (Macaulay2Doc), it must have the correct number of
rows.

+------------------------------------------+
|i4 : isVectorField(matrix {{x,y^2}})      |
|                                          |
|o4 = false                                |
+------------------------------------------+
|i5 : isVectorField(matrix {{x,y^2},{0,0}})|
|                                          |
|o5 = true                                 |
+------------------------------------------+

Caveat
======

Despite the name, the function does not check the number of vector fields
provided.

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields

Ways to use isVectorField :
===========================

  * "isVectorField(Matrix)"
  * "isVectorField(Module)"

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

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

lowerCentralSeries -- compute the lower central series of a set of vector fields
********************************************************************************

Synopsis
========

  * Usage:
        L=lowerCentralSeries(k,M)
        L=lowerCentralSeries(k,m)
  * Inputs:
      * k, an integer (Macaulay2Doc), a nonnegative integer
      * M, a matrix (Macaulay2Doc), of vector fields
      * m, a module (Macaulay2Doc), of vector fields
  * Outputs:
      * L, a list (Macaulay2Doc), a list containing m or M and the
        first k terms of the lower central series. The types of the terms of
        the list agrees with the input type.

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

Compute the first few terms of the lower central series of a set of vector
fields. For an object $n$, if we define $n^{(0)}=n$ and
$n^{(i+1)}=bracket(n,n^{(i)})$, then $n^{(i)}$ is the $i$th term of the lower
central series, and will be in the $i$th index position of the returned list.

As with bracket, this function computes different things,
depending on the type of the parameter. See differences between certain bracketing functions,
for
more information.

The following Lie algebra is generated by a finite-dimensional representation
of gl_2.

+------------------------------+
|i1 : R=QQ[a,b,c];             |
+------------------------------+
|i2 : D=derlog(a*c-b^2)        |
|                              |
|o2 = image | 2b a  0  0  |    |
|           | c  0  b  a  |    |
|           | 0  -c 2c 2b |    |
|                              |
|                             3|
|o2 : R-module, submodule of R |
+------------------------------+

The lower central series (when provided with a Matrix (Macaulay2Doc))
stabilizes as a representation of sl_2:

+-----------------------------------------------------------------------------+
|i3 : lcs=lowerCentralSeries(2,gens D)                                        |
|                                                                             |
|o3 = {| 2b a  0  0  |, | 0 2b -2b -2a -2b 0 0 0  2b 0 0 0   2a  0   0  0 |, ||
|      | c  0  b  a  |  | 0 c  -c  0   -c  0 0 a  c  0 0 -a  0   -a  a  0 |  ||
|      | 0  -c 2c 2b |  | 0 0  0   2c  0   0 0 2b 0  0 0 -2b -2c -2b 2b 0 |  ||
|     ------------------------------------------------------------------------|
|     0 0 0 -4b 0 0 0 -2a 0 0 0 2a  4b 2a  -2a 0 0 -2b 2b 0 2b 0 0 0  -2b 0 0 |
|     0 0 0 -2c 0 0 0 0   0 0 0 0   2c 0   0   0 0 -c  c  0 c  0 0 a  -c  0 0 |
|     0 0 0 0   0 0 0 2c  0 0 0 -2c 0  -2c 2c  0 0 0   0  0 0  0 0 2b 0   0 0 |
|     ------------------------------------------------------------------------|
|     0   0 0   0  0 0 2b -2b 0 -2b 0 0 0   2b 0 0 0  0 0  0   0 0 2a  -2a 0  |
|     -a  0 -a  a  0 0 c  -c  0 -c  0 0 -a  c  0 0 a  0 a  -a  0 0 0   0   2a |
|     -2b 0 -2b 2b 0 0 0  0   0 0   0 0 -2b 0  0 0 2b 0 2b -2b 0 0 -2c 2c  4b |
|     ------------------------------------------------------------------------|
|     -2a 0 0 0 2a  0 0 0 0   0 0 0 |}                                        |
|     0   0 0 0 0   0 0 0 -2a 0 0 0 |                                         |
|     2c  0 0 0 -2c 0 0 0 -4b 0 0 0 |                                         |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : apply(lcs,f->gens trim image f)                                         |
|                                                                             |
|o4 = {| 2b a  0  0  |, | 2b a  0  |, | 2b a  0  |}                           |
|      | c  0  b  a  |  | c  0  a  |  | c  0  a  |                            |
|      | 0  -c 2c 2b |  | 0  -c 2b |  | 0  -c 2b |                            |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

The lower central series (when provided with a Module (Macaulay2Doc))
stabilizes with a linear part isomorphic to sl_2, and a
higher-order part equal to ideal (a,b,c)*D.

+-----------------------------------------------------------------------------+
|i5 : lowerCentralSeries(2,D)                                                 |
|                                                                             |
|o5 = {image | 2b a  0  0  |, image | 2b a  0  0   0   0     |, image | 2b a  |
|            | c  0  b  a  |        | c  0  a  bc  b2  0     |        | c  0  |
|            | 0  -c 2c 2b |        | 0  -c 2b 2c2 2bc b2-ac |        | 0  -c |
|     ------------------------------------------------------------------------|
|     0  0   0   0     |}                                                     |
|     a  bc  b2  0     |                                                      |
|     2b 2c2 2bc b2-ac |                                                      |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : trim((image commutator(gens D))+(ideal (a,b,c))*D)                      |
|                                                                             |
|o6 = image | 2b a  0  0   0   0     |                                        |
|           | c  0  a  bc  b2  0     |                                        |
|           | 0  -c 2b 2c2 2bc b2-ac |                                        |
|                                                                             |
|                             3                                               |
|o6 : R-module, submodule of R                                                |
+-----------------------------------------------------------------------------+

In this example, with 1 generator, the difference between the two versions is
particularly stark.

+-----------------------------------------------------------------------------+
|i7 : D=image matrix {{0},{a},{2*b}};                                         |
+-----------------------------------------------------------------------------+
|i8 : lowerCentralSeries(5,gens D)                                            |
|                                                                             |
|o8 = {| 0  |, 0, 0, 0, 0, 0}                                                 |
|      | a  |                                                                 |
|      | 2b |                                                                 |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+
|i9 : lowerCentralSeries(5,D)                                                 |
|                                                                             |
|o9 = {image | 0  |, image | 0   0   |, image | 0   0   |, image | 0    0     |
|            | a  |        | ab  a2  |        | a2  ab2 |        | a2b  a3    |
|            | 2b |        | 2b2 2ab |        | 2ab 2b3 |        | 2ab2 2a2b  |
|     ------------------------------------------------------------------------|
|     0   |, image | 0    0    0   |, image | 0     0    0    0   |}          |
|     ab3 |        | a3   a2b2 ab4 |        | a3b   a4   a2b3 ab5 |           |
|     2b4 |        | 2a2b 2ab3 2b5 |        | 2a2b2 2a3b 2ab4 2b6 |           |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * bracket -- compute the Lie bracket of vector fields
  * derivedSeries -- compute the derived series of a set
    of vector fields
  * differences between certain bracketing functions
    -- The difference between certain bracketing
    functions
  * VectorFields -- a package for manipulating polynomial vector
    fields

Ways to use lowerCentralSeries :
================================

  * "lowerCentralSeries(ZZ,Matrix)"
  * "lowerCentralSeries(ZZ,Module)"

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

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

StratificationByRank -- a type to hold a rank computation
*********************************************************

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

This is a type of HashTable (Macaulay2Doc), with positive
integer keys, used to store the output of stratifyByRank.
If M is a module of vector fields and h=stratifyByRank(M) is
the StratificationByRank object, then h#i is the radical ideal defining the set
of points $p$ such that the generators of $M$ evaluated at $p$ span a subspace
of dimension less than $i$.

These objects are primarily used by isFiniteStratification.

If M is a Lie algebra, then this gives some information about the 'orbits' or
maximal integral submanifolds of the vector fields.

See also
========

  * stratifyByRank -- compute ideals describing where
    the vector fields have a particular rank
  * isFiniteStratification -- checks if a
    stratification by integral submanifolds is finite
  * VectorFields -- a package for manipulating polynomial vector
    fields

Functions and methods returning an object of class StratificationByRank :
=========================================================================

  * stratifyByRank -- compute ideals describing where
    the vector fields have a particular rank

Methods that use an object of class StratificationByRank :
==========================================================

  * "isFiniteStratification(StratificationByRank)" -- see
    isFiniteStratification, -- checks if a
    stratification by integral submanifolds is finite

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

The object StratificationByRank, is a type (Macaulay2Doc),
with ancestor classes HashTable (Macaulay2Doc),
< Thing (Macaulay2Doc).

stratifyByRank -- compute ideals describing where the vector fields have a particular rank
******************************************************************************************

Synopsis
========

  * Usage:
        H=stratifyByRank(M)
        H=stratifyByRank(m)
  * Inputs:
      * M, a matrix (Macaulay2Doc), of vector fields
      * m, a module (Macaulay2Doc), of vector fields
  * Outputs:
      * H, an instance of the type StratificationByRank,
        a type of HashTable (Macaulay2Doc),
        with integer keys: i maps to the radical ideal
        defining the set where the vector fields have rank less than i.

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

Computes ideals describing where the provided vector fields have a particular
rank. For $1\leq i\leq n$, where $n$ is the dimension of the space,
(stratifyByRank(M))#i will be an ideal defining the set of points $p$ such that
the generators of $M$ evaluated at $p$ span a subspace of dimension less than
$i$. If the vector fields generate a Lie algebra, then this gives some
information about their 'orbits' or their maximal integral submanifolds.

For details on the parts of the calculation, make debugLevel (Macaulay2Doc),
positive.

+---------------------------------+
|i1 : R=QQ[a,b,c];                |
+---------------------------------+
|i2 : f=a*b*(a-b)*(a-c*b)         |
|                                 |
|        2 2       3     3     2 2|
|o2 = - a b c + a*b c + a b - a b |
|                                 |
|o2 : R                           |
+---------------------------------+
|i3 : D=derlog(ideal (f))         |
|                                 |
|o3 = image | a 0    0     |      |
|           | b 0    ab-b2 |      |
|           | 0 bc-a -ac+a |      |
|                                 |
|                             3   |
|o3 : R-module, submodule of R    |
+---------------------------------+
|i4 : S=stratifyByRank(D);        |
+---------------------------------+

D has rank 0 on $a=b=0$, that is, the vector fields all vanish there:

+-----------------+
|i5 : S#1         |
|                 |
|o5 = ideal (a, b)|
|                 |
|o5 : Ideal of R  |
+-----------------+

D has rank <3 precisely on the hypersurface $f=0$, and hence rank 3 off the
hypersurface:

+--------------------------------------+
|i6 : S#3                              |
|                                      |
|            2 2       3     3     2 2 |
|o6 = ideal(a b c - a*b c - a b + a b )|
|                                      |
|o6 : Ideal of R                       |
+--------------------------------------+

This submodule of D has rank $<3$ everywhere since it only has 2 generators:

+----------------------------------+
|i7 : Df=derlogH(f)                |
|                                  |
|o7 = image | ab      a2          ||
|           | b2      -3ab+4b2    ||
|           | -4bc+4a 4ac-12bc+8a ||
|                                  |
|                             3    |
|o7 : R-module, submodule of R     |
+----------------------------------+
|i8 : isSubset(Df,D)               |
|                                  |
|o8 = true                         |
+----------------------------------+
|i9 : S=stratifyByRank(Df);        |
+----------------------------------+
|i10 : S#3                         |
|                                  |
|o10 = ideal 0                     |
|                                  |
|o10 : Ideal of R                  |
+----------------------------------+

See also
========

  * VectorFields -- a package for manipulating polynomial vector
    fields
  * StratificationByRank -- a type to hold a rank
    computation
  * isFiniteStratification -- checks if a
    stratification by integral submanifolds is finite

Ways to use stratifyByRank :
============================

  * "stratifyByRank(Matrix)"
  * "stratifyByRank(Module)"

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

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