This is DiffAlg.info, produced by Macaulay2, version 1.20

DiffAlg -- differential algebra
*******************************

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

See DiffAlg, is a differential algebra package. It can compute the usual
operations with polynomial differential forms and vector fields. Its main
purpose is to associate algebraic objects to differential operators in the
exterior algebra of differential forms.

The simplest way to load the package is with the command:

loadPackage "DiffAlg"

Then, one can define a linear differential 1-form, w, and the radial vector
field, R, in  3-dimensional space as:

+-----------------------------------------------------------------------------+
|i1 : w = newForm(2,1,1,"a")                                                  |
|                                                                             |
|o1 = (a x  + a x  + a x )dx  + (a x  + a x  + a x )dx  + (a x  + a x  +      |
|       0 0    3 1    6 2   0     1 0    4 1    7 2   1     2 0    5 1        |
|     ------------------------------------------------------------------------|
|     a x )dx                                                                 |
|      8 2   2                                                                |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : R = radial 2                                                            |
|                                                                             |
|o2 = x ax  + x ax  + x ax                                                    |
|      0  0    1  1    2  2                                                   |
|                                                                             |
|o2 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i3 : ring w                                                                  |
|                                                                             |
|      QQ[i]                                                                  |
|o3 = ------[][a ..a ][x ..x ][dx ..dx ]                                      |
|      2        0   8   0   2    0    2                                       |
|     i  + 1                                                                  |
|                                                                             |
|o3 : PolynomialRing, 3 skew commutative variables                            |
+-----------------------------------------------------------------------------+
|i4 : ring R                                                                  |
|                                                                             |
|      QQ[i]                                                                  |
|o4 = ------[][x ..x ][ax ..ax ]                                              |
|      2        0   2    0    2                                               |
|     i  + 1                                                                  |
|                                                                             |
|o4 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+

All possible options to call the package can be given with the command:

loadPackage ("DiffAlg",Configuration => {"BaseRing" => aRing, "VariableName" =>
varSymbol, "DiffName" => difSymbol, "FieldName" => derSymbol})

where:

  * aRing, a Ring (Macaulay2Doc), the base ring. Default QQ[i]
  * varSymbol, a String (Macaulay2Doc), the name of the affine
    coordinates. Default x
  * difSymbol, a String (Macaulay2Doc), the symbol to denote the
    differential of a coordinate. Default d
  * derSymbol, a String (Macaulay2Doc), the symbol to denote the
    partial derivative of a coordinate. Default a

Caveat
======

It is recommended to operate in low degrees and dimensions because of the
computational time needed to handle the number of variables generated in every
degree.

See also
========

  * newForm -- constructor of a differential form
  * newField -- constructor of a vector field

Authors
=======

  * Manuel Dubinsky (see  ) <manudubinsky@gmail.com>
  * Cesar Massri (see  ) <cmassri@caece.edu.ar>
  * Ariel Molinuevo (see  ) <amoli@dm.uba.ar>
  * Federico Quallbrunn (see  ) <fquallb@dm.uba.ar>

Certification a gold star
=========================

Version 1.5 of this package was accepted for publication in volume 9 (see
https://msp.org/jsag/2019/9-1/ ) of The Journal of Software for Algebra and
Geometry (see http://j-sag.org/ ) on 19 November 2018, in the article DiffAlg:
a Differential algebra package (see https://msp.org/jsag/2019/9-1/p02.xhtml ).
That version can be obtained from the journal (see
https://msp.org/jsag/2019/9-1/jsag-v9-n1-x02-DiffAlg.m2 ) or from the Macaulay2
source code repository (see
http://github.com/Macaulay2/M2/blob/fb0887a15f6ff5ec7f940f60ad46f738412924cd/M2
/Macaulay2/packages/DiffAlg.m2 ).

Version
=======

This documentation describes version 1.5 of DiffAlg.

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

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

Exports
=======

  * Types
      * DiffAlgDistribution -- the class of
        distributions of vector fields
      * DiffAlgElement -- the class of all differential
        forms and vector fields
      * DiffAlgField -- the class of all vector fields
      * DiffAlgForm -- the class of all differential forms
  * Functions and commands
      * dist -- produces a DiffAlgDistribution from a list
      * genIm -- a basis of the image of a linear expression
      * genKer -- basis of the kernel of a linear expression
      * isInvolutive -- tests if a distribution is
        involutive
      * linearComb -- generic linear combination of elements
      * logarithmicForm -- creates a logarithmic form
      * moduliIdeal -- ideal generated by the coefficients
        of a differential form or vector field
      * newField -- constructor of a vector field
      * newForm -- constructor of a differential form
      * projectivize -- projectivize a differential form
        or vector field
      * radial -- defines the radial vector field
      * singularIdeal -- ideal generated by the
        polynomial coefficients of a differential form or vector field
  * Methods
      * - DiffAlgElement -- negation of a differential
        form or vector field
      * degree(DiffAlgElement) -- degree of
        a differential form or a vector field
      * diff(DiffAlgForm) -- exterior
        differential
      * "DiffAlgElement * QQ" -- see DiffAlgElement * RingElement,
        -- scalar multiplication
      * DiffAlgElement * RingElement, --
        scalar multiplication
      * "DiffAlgElement * ZZ" -- see DiffAlgElement * RingElement,
        -- scalar multiplication
      * "QQ * DiffAlgElement" -- see DiffAlgElement * RingElement,
        -- scalar multiplication
      * "RingElement * DiffAlgElement" -- see DiffAlgElement * RingElement,
        -- scalar multiplication
      * "ZZ * DiffAlgElement" -- see DiffAlgElement * RingElement,
        -- scalar multiplication
      * DiffAlgElement + DiffAlgElement,
        -- addition
      * DiffAlgElement - DiffAlgElement,
        -- subtraction
      * "DiffAlgElement / QQ" -- see DiffAlgElement / RingElement,
        -- scalar division
      * DiffAlgElement / RingElement, --
        scalar division
      * "DiffAlgElement / ZZ" -- see DiffAlgElement / RingElement,
        -- scalar division
      * DiffAlgElement | String -- concatenate
        a string with a differential form or vector field
      * "String | DiffAlgElement" -- see DiffAlgElement | String,
        -- concatenate a string with a differential
        form or vector field
      * DiffAlgField _ DiffAlgForm, --
        contraction of a differential form with respect to a vector field
      * "DiffAlgForm _ DiffAlgField" -- see DiffAlgField _ DiffAlgForm,
        -- contraction of a differential form
        with respect to a vector field
      * DiffAlgField | DiffAlgField -- Lie
        bracket
      * "DiffAlgForm * DiffAlgForm" -- see DiffAlgForm ^ DiffAlgForm,
        -- exterior product
      * DiffAlgForm ^ DiffAlgForm -- exterior
        product
      * "dist(List)" -- see dist, -- produces a DiffAlgDistribution
        from a list
      * "genIm(DiffAlgElement,DiffAlgElement)" -- see genIm, -- a
        basis of the image of a linear expression
      * "genKer(DiffAlgElement,DiffAlgElement)" -- see genKer, --
        basis of the kernel of a linear expression
      * homogenize(DiffAlgElement), --
        homogenize a differential form or vector field
      * isHomogeneous(DiffAlgElement),
        -- tests if a form (or field) is homogeneous
      * "isInvolutive(DiffAlgDistribution)" -- see isInvolutive,
        -- tests if a distribution is involutive
      * "linearComb(List,String)" -- see linearComb, --
        generic linear combination of elements
      * List * DiffAlgForm -- pull-back of a
        differential form by a rational map
      * "logarithmicForm(ZZ,List,String)" -- see logarithmicForm,
        -- creates a logarithmic form
      * "moduliIdeal(DiffAlgElement)" -- see moduliIdeal, --
        ideal generated by the coefficients of a differential form or vector
        field
      * "newField(ZZ,ZZ,String)" -- see newField, --
        constructor of a vector field
      * newField(String) -- constructor of a
        vector field
      * "newForm(ZZ,ZZ,ZZ,String)" -- see newForm, --
        constructor of a differential form
      * newForm(String) -- constructor of a
        differential form
      * "projectivize(DiffAlgElement)" -- see projectivize,
        -- projectivize a differential form or vector field
      * "radial(ZZ)" -- see radial, -- defines the radial vector
        field
      * "random(DiffAlgElement)" -- see random(DiffAlgElement,Ring),
        -- replaces the variables of the
        coefficient ring of a differential form or a vector field with random
        values
      * random(DiffAlgElement,Ring),
        -- replaces the variables of the coefficient ring of a differential
        form or a vector field with random values
      * rank(DiffAlgDistribution) -- rank
        of the given distribution
      * ring(DiffAlgElement) -- ring of the
        differential form or vector field
      * "singularIdeal(DiffAlgElement)" -- see singularIdeal,
        -- ideal generated by the polynomial coefficients of a
        differential form or vector field
      * substitute(DiffAlgElement,Ring)
        -- gets the RingElement of a
        differential form or vector field in a ring

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

The object DiffAlg, is a package (Macaulay2Doc).

- DiffAlgElement -- negation of a differential form or vector field
*******************************************************************

Synopsis
========

  * Operator: - (Macaulay2Doc),
  * Usage:
        - e
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or a vector field
  * Outputs:
      * an instance of the type DiffAlgElement, the
        negation of e

Ways to use this method:
========================

  * - DiffAlgElement -- negation of a differential
    form or vector field

degree(DiffAlgElement) -- degree of a differential form or a vector field
*************************************************************************

Synopsis
========

  * Function: degree (Macaulay2Doc),
  * Usage:
        degree e
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or vector field
  * Outputs:
      * a list (Macaulay2Doc), If e is a vector field it returns
        {n,d}; if e is a differential form it returns {n,r,d}.

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

This function returns the degree of a homogeneous differential form or vector
field.

  * n, an integer (Macaulay2Doc), is the number of variables minus
    one
  * r, an integer (Macaulay2Doc), is the degree of the differential
    form or empty if e is a vector field
  * d, an integer (Macaulay2Doc), is the degree of the polynomial
    coefficients

In the following example we compute the degree of a differential form and a
vector field.

+-----------------------------------------------------------------------------+
|i1 : w = newForm(2,1,3,"a")                                                  |
|                                                                             |
|         3      2          2       3      2                     2           2|
|o1 = (a x  + a x x  + a x x  + a  x  + a x x  + a  x x x  + a  x x  + a  x x |
|       0 0    3 0 1    9 0 1    18 1    6 0 2    12 0 1 2    21 1 2    15 0 2|
|     ------------------------------------------------------------------------|
|             2       3           3      2           2       3      2         |
|     + a  x x  + a  x )dx  + (a x  + a x x  + a  x x  + a  x  + a x x  +     |
|        24 1 2    27 2   0     1 0    4 0 1    10 0 1    19 1    7 0 2       |
|     ------------------------------------------------------------------------|
|                     2           2         2       3           3      2      |
|     a  x x x  + a  x x  + a  x x  + a  x x  + a  x )dx  + (a x  + a x x  +  |
|      13 0 1 2    22 1 2    16 0 2    25 1 2    28 2   1     2 0    5 0 1    |
|     ------------------------------------------------------------------------|
|           2       3      2                     2           2         2      |
|     a  x x  + a  x  + a x x  + a  x x x  + a  x x  + a  x x  + a  x x  +    |
|      11 0 1    20 1    8 0 2    14 0 1 2    23 1 2    17 0 2    26 1 2      |
|     ------------------------------------------------------------------------|
|         3                                                                   |
|     a  x )dx                                                                |
|      29 2   2                                                               |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : degree(w)                                                               |
|                                                                             |
|o2 = {2, 1, 3}                                                               |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : X = newField(2,2,"b")                                                   |
|                                                                             |
|         2               2                          2           2            |
|o3 = (b x  + b x x  + b x  + b x x  + b  x x  + b  x )ax  + (b x  + b x x  + |
|       0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0     1 0    4 0 1   |
|     ------------------------------------------------------------------------|
|         2                          2           2                2           |
|     b  x  + b x x  + b  x x  + b  x )ax  + (b x  + b x x  + b  x  + b x x  +|
|      10 1    7 0 2    13 1 2    16 2   1     2 0    5 0 1    11 1    8 0 2  |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     b  x x  + b  x )ax                                                      |
|      14 1 2    17 2   2                                                     |
|                                                                             |
|o3 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i4 : degree X                                                                |
|                                                                             |
|o4 = {2, 2}                                                                  |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

If the DiffAlgElement, is non-homogeneous the function
returns the highest degrees {n,r,d} of each homogeneous component in the given
expression. For example, if the degree of w is {2,1,3}, then degree(w + (diff
w)) returns, {2,2,3}

Ways to use this method:
========================

  * degree(DiffAlgElement) -- degree of a
    differential form or a vector field

diff(DiffAlgForm) -- exterior differential
******************************************

Synopsis
========

  * Function: diff (Macaulay2Doc),
  * Usage:
        diff w
  * Inputs:
      * w, an instance of the type DiffAlgForm, a form
  * Outputs:
      * an instance of the type DiffAlgForm, the exterior
        differential of w

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

This function computes the exterior differential of a given differential form.

+-----------------------------------------------------------------------------+
|i1 : w = newForm(2,1,2,"a")                                                  |
|                                                                             |
|         2               2                          2           2            |
|o1 = (a x  + a x x  + a x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + |
|       0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0     1 0    4 0 1   |
|     ------------------------------------------------------------------------|
|         2                          2           2                2           |
|     a  x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + a  x  + a x x  +|
|      10 1    7 0 2    13 1 2    16 2   1     2 0    5 0 1    11 1    8 0 2  |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     a  x x  + a  x )dx                                                      |
|      14 1 2    17 2   2                                                     |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : diff w                                                                  |
|                                                                             |
|o2 = ((2a  - a )x  + (a  - 2a )x  + (a  - a  )x )dx dx  + ((2a  - a )x  + (a |
|         1    3  0     4     9  1     7    12  2   0  1       2    6  0     5|
|     ------------------------------------------------------------------------|
|     - a  )x  + (a  - 2a  )x )dx dx  + ((a  - a )x  + (2a   - a  )x  + (a   -|
|        12  1     8     15  2   0  2      5    7  0      11    13  1     14  |
|     ------------------------------------------------------------------------|
|     2a  )x )dx dx                                                           |
|       16  2   1  2                                                          |
|                                                                             |
|o2 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * diff(DiffAlgForm) -- exterior differential

DiffAlgDistribution -- the class of distributions of vector fields
******************************************************************

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

  * "dist(List)" -- see dist, -- produces a DiffAlgDistribution
    from a list

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

  * "isInvolutive(DiffAlgDistribution)" -- see isInvolutive,
    -- tests if a distribution is involutive
  * rank(DiffAlgDistribution) -- rank of
    the given distribution

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

The object DiffAlgDistribution, is a type (Macaulay2Doc),
with ancestor classes List (Macaulay2Doc), <
VisibleList (Macaulay2Doc) < BasicList (Macaulay2Doc)
< Thing (Macaulay2Doc).

DiffAlgElement -- the class of all differential forms and vector fields
***********************************************************************

Types of DiffAlgElement :
=========================

  * DiffAlgField -- the class of all vector fields
  * DiffAlgForm -- the class of all differential forms

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

  * - DiffAlgElement -- negation of a differential
    form or vector field
  * "DiffAlgElement * QQ" -- see DiffAlgElement * RingElement,
    -- scalar multiplication
  * DiffAlgElement * RingElement, --
    scalar multiplication
  * "DiffAlgElement * ZZ" -- see DiffAlgElement * RingElement,
    -- scalar multiplication
  * "QQ * DiffAlgElement" -- see DiffAlgElement * RingElement,
    -- scalar multiplication
  * "RingElement * DiffAlgElement" -- see DiffAlgElement * RingElement,
    -- scalar multiplication
  * "ZZ * DiffAlgElement" -- see DiffAlgElement * RingElement,
    -- scalar multiplication
  * DiffAlgElement + DiffAlgElement, --
    addition
  * DiffAlgElement - DiffAlgElement, --
    subtraction
  * "DiffAlgElement / QQ" -- see DiffAlgElement / RingElement,
    -- scalar division
  * DiffAlgElement / RingElement -- scalar
    division
  * "DiffAlgElement / ZZ" -- see DiffAlgElement / RingElement,
    -- scalar division
  * homogenize(DiffAlgElement), --
    homogenize a differential form or vector field
  * "linearComb(List,String)" -- see linearComb, -- generic
    linear combination of elements
  * "projectivize(DiffAlgElement)" -- see projectivize, --
    projectivize a differential form or vector field
  * "random(DiffAlgElement)" -- see random(DiffAlgElement,Ring),
    -- replaces the variables of the
    coefficient ring of a differential form or a vector field with random
    values
  * random(DiffAlgElement,Ring), --
    replaces the variables of the coefficient ring of a differential form or a
    vector field with random values

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

  * degree(DiffAlgElement) -- degree of a
    differential form or a vector field
  * DiffAlgElement | String -- concatenate a
    string with a differential form or vector field
  * "String | DiffAlgElement" -- see DiffAlgElement | String,
    -- concatenate a string with a differential form
    or vector field
  * "genIm(DiffAlgElement,DiffAlgElement)" -- see genIm, -- a
    basis of the image of a linear expression
  * "genKer(DiffAlgElement,DiffAlgElement)" -- see genKer, --
    basis of the kernel of a linear expression
  * isHomogeneous(DiffAlgElement), --
    tests if a form (or field) is homogeneous
  * "moduliIdeal(DiffAlgElement)" -- see moduliIdeal, --
    ideal generated by the coefficients of a differential form or vector field
  * ring(DiffAlgElement) -- ring of the
    differential form or vector field
  * "singularIdeal(DiffAlgElement)" -- see singularIdeal,
    -- ideal generated by the polynomial coefficients of a differential form or
    vector field
  * substitute(DiffAlgElement,Ring)
    -- gets the RingElement of a
    differential form or vector field in a ring

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

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

DiffAlgElement * RingElement -- scalar multiplication
*****************************************************

Synopsis
========

  * Operator: * (Macaulay2Doc),
  * Usage:
        e * n
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or a vector field
      * n, a ring element (Macaulay2Doc), scalar
  * Outputs:
      * an instance of the type DiffAlgElement, the
        product of e and n

Ways to use this method:
========================

  * "DiffAlgElement * QQ"
  * DiffAlgElement * RingElement, --
    scalar multiplication
  * "DiffAlgElement * ZZ"
  * "QQ * DiffAlgElement"
  * "RingElement * DiffAlgElement"
  * "ZZ * DiffAlgElement"

DiffAlgElement + DiffAlgElement -- addition
*******************************************

Synopsis
========

  * Operator: + (Macaulay2Doc),
  * Usage:
        w + h
  * Inputs:
      * w, an instance of the type DiffAlgElement, a
        differential form or vector field
      * h, an instance of the type DiffAlgElement, a
        differential form or vector field
  * Outputs:
      * an instance of the type DiffAlgElement, the
        addition of w and h

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

+-----------------------------------------------------------------------------+
|i1 : h = radial 2                                                            |
|                                                                             |
|o1 = x ax  + x ax  + x ax                                                    |
|      0  0    1  1    2  2                                                   |
|                                                                             |
|o1 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i2 : w = random newField(3,1,"a")                                            |
|                                                                             |
|o2 = (2x  + 2x  + 2x  + 2x )ax  + (- 2x  - 6x  - x  + 5x )ax  + (- 3x  -     |
|        0     1     2     3   0        0     1    2     3   1        0       |
|     ------------------------------------------------------------------------|
|     x )ax  + (- x  + 5x  - 3x )ax                                           |
|      2   2       0     2     3   3                                          |
|                                                                             |
|o2 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i3 : w + h                                                                   |
|                                                                             |
|o3 = (3x  + 2x  + 2x  + 2x )ax  + (- 2x  - 5x  - x  + 5x )ax  - 3x ax  + (-  |
|        0     1     2     3   0        0     1    2     3   1     0  2       |
|     ------------------------------------------------------------------------|
|     x  + 5x  - 3x )ax                                                       |
|      0     2     3   3                                                      |
|                                                                             |
|o3 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * DiffAlgElement + DiffAlgElement, --
    addition

DiffAlgElement - DiffAlgElement -- subtraction
**********************************************

Synopsis
========

  * Operator: - (Macaulay2Doc),
  * Usage:
        w - h
  * Inputs:
      * w, an instance of the type DiffAlgElement, a
        differential form or vector field
      * h, an instance of the type DiffAlgElement, a
        differential form or vector field
  * Outputs:
      * an instance of the type DiffAlgElement, the
        subtraction of w and h

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

+-----------------------------------------------------------------------------+
|i1 : w = newForm(2,1,1,"a")                                                  |
|                                                                             |
|o1 = (a x  + a x  + a x )dx  + (a x  + a x  + a x )dx  + (a x  + a x  +      |
|       0 0    3 1    6 2   0     1 0    4 1    7 2   1     2 0    5 1        |
|     ------------------------------------------------------------------------|
|     a x )dx                                                                 |
|      8 2   2                                                                |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : h = newForm(3,2,1,"b")                                                  |
|                                                                             |
|o2 = (b x  + b x  + b  x  + b  x )dx dx  + (b x  + b x  + b  x  +            |
|       0 0    6 1    12 2    18 3   0  1     1 0    7 1    13 2              |
|     ------------------------------------------------------------------------|
|     b  x )dx dx  + (b x  + b x  + b  x  + b  x )dx dx  + (b x  + b x  +     |
|      19 3   0  2     3 0    9 1    15 2    21 3   1  2     2 0    8 1       |
|     ------------------------------------------------------------------------|
|     b  x  + b  x )dx dx  + (b x  + b  x  + b  x  + b  x )dx dx  + (b x  +   |
|      14 2    20 3   0  3     4 0    10 1    16 2    22 3   1  3     5 0     |
|     ------------------------------------------------------------------------|
|     b  x  + b  x  + b  x )dx dx                                             |
|      11 1    17 2    23 3   2  3                                            |
|                                                                             |
|o2 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i3 : w - h                                                                   |
|                                                                             |
|o3 = (- b x  - b x  - b  x  - b  x )dx dx  + (- b x  - b x  - b  x  -        |
|         0 0    6 1    12 2    18 3   0  1       1 0    7 1    13 2          |
|     ------------------------------------------------------------------------|
|     b  x )dx dx  + (- b x  - b x  - b  x  - b  x )dx dx  + (- b x  - b x  - |
|      19 3   0  2       3 0    9 1    15 2    21 3   1  2       2 0    8 1   |
|     ------------------------------------------------------------------------|
|     b  x  - b  x )dx dx  + (- b x  - b  x  - b  x  - b  x )dx dx  + (- b x  |
|      14 2    20 3   0  3       4 0    10 1    16 2    22 3   1  3       5 0 |
|     ------------------------------------------------------------------------|
|     - b  x  - b  x  - b  x )dx dx  + (a x  + a x  + a x )dx  + (a x  + a x  |
|        11 1    17 2    23 3   2  3     0 0    3 1    6 2   0     1 0    4 1 |
|     ------------------------------------------------------------------------|
|     + a x )dx  + (a x  + a x  + a x )dx                                     |
|        7 2   1     2 0    5 1    8 2   2                                    |
|                                                                             |
|o3 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * DiffAlgElement - DiffAlgElement, --
    subtraction

DiffAlgElement / RingElement -- scalar division
***********************************************

Synopsis
========

  * Operator: / (Macaulay2Doc),
  * Usage:
        e / n
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or a vector field
      * n, a ring element (Macaulay2Doc), scalar
  * Outputs:
      * an instance of the type DiffAlgElement, the
        quotient of e by n

Ways to use this method:
========================

  * "DiffAlgElement / QQ"
  * DiffAlgElement / RingElement -- scalar
    division
  * "DiffAlgElement / ZZ"

DiffAlgElement | String -- concatenate a string with a differential form or vector field
****************************************************************************************

Synopsis
========

  * Operator: | (Macaulay2Doc),
  * Usage:
        e | text
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or a vector field
      * text, a string (Macaulay2Doc), a string to be
        concatenated
  * Outputs:
      * a string (Macaulay2Doc), concatenation of text with the
        string representation of e

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

+-----------------------------------------------------------------------------+
|i1 : w=newForm(2,1,2,"a")                                                    |
|                                                                             |
|         2               2                          2           2            |
|o1 = (a x  + a x x  + a x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + |
|       0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0     1 0    4 0 1   |
|     ------------------------------------------------------------------------|
|         2                          2           2                2           |
|     a  x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + a  x  + a x x  +|
|      10 1    7 0 2    13 1 2    16 2   1     2 0    5 0 1    11 1    8 0 2  |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     a  x x  + a  x )dx                                                      |
|      14 1 2    17 2   2                                                     |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : newForm ("b*4-"|w|"+4*dx_3")                                            |
|                                                                             |
|           2               2                          2             2        |
|o2 = (- a x  - a x x  - a x  - a x x  - a  x x  - a  x )dx  + (- a x  -      |
|         0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0       1 0        |
|     ------------------------------------------------------------------------|
|                  2                          2             2                2|
|     a x x  - a  x  - a x x  - a  x x  - a  x )dx  + (- a x  - a x x  - a  x |
|      4 0 1    10 1    7 0 2    13 1 2    16 2   1       2 0    5 0 1    11 1|
|     ------------------------------------------------------------------------|
|                              2                                              |
|     - a x x  - a  x x  - a  x )dx  + 4dx  + 4b                              |
|        8 0 2    14 1 2    17 2   2      3                                   |
|                                                                             |
|o2 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * DiffAlgElement | String -- concatenate a
    string with a differential form or vector field
  * "String | DiffAlgElement"

DiffAlgField -- the class of all vector fields
**********************************************

See also
========

  * DiffAlgForm -- the class of all differential forms

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

  * DiffAlgField | DiffAlgField -- Lie
    bracket
  * "newField(ZZ,ZZ,String)" -- see newField, -- constructor of
    a vector field
  * newField(String) -- constructor of a vector
    field
  * "radial(ZZ)" -- see radial, -- defines the radial vector
    field

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

  * DiffAlgField _ DiffAlgForm, --
    contraction of a differential form with respect to a vector field
  * "DiffAlgForm _ DiffAlgField" -- see DiffAlgField _ DiffAlgForm,
    -- contraction of a differential form with
    respect to a vector field

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

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

DiffAlgField _ DiffAlgForm -- contraction of a differential form with respect to a vector field
***********************************************************************************************

Synopsis
========

  * Operator: _ (Macaulay2Doc),
  * Usage:
        X _ w
  * Inputs:
      * X, an instance of the type DiffAlgField, a vector
        field
      * w, an instance of the type DiffAlgForm, a
        differential form
  * Outputs:
      * an instance of the type DiffAlgForm, the
        contraction of w with respect to X

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

Given a vector field X and a differential form w, this function returns the
contraction of w with respect to X. The function can be called as X _ w  or as
w _ X.

In this example we compute the contraction of a simple differential form and a
vector field.

+-------------------------------+
|i1 : w = newForm("dx_0 * dx_1")|
|                               |
|o1 = dx dx                     |
|       0  1                    |
|                               |
|o1 : DiffAlgForm               |
+-------------------------------+
|i2 : Y = newField("ax_0")      |
|                               |
|o2 = ax                        |
|       0                       |
|                               |
|o2 : DiffAlgField              |
+-------------------------------+
|i3 : Y _ w                     |
|                               |
|o3 = dx                        |
|       1                       |
|                               |
|o3 : DiffAlgForm               |
+-------------------------------+

Ways to use this method:
========================

  * DiffAlgField _ DiffAlgForm, --
    contraction of a differential form with respect to a vector field
  * "DiffAlgForm _ DiffAlgField"

DiffAlgField | DiffAlgField -- Lie bracket
******************************************

Synopsis
========

  * Operator: | (Macaulay2Doc),
  * Usage:
        X | Y
  * Inputs:
      * X, an instance of the type DiffAlgField, a vector
        field
      * Y, an instance of the type DiffAlgField, a vector
        field
  * Outputs:
      * an instance of the type DiffAlgField, the Lie
        bracket of X and Y

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

This function computes the Lie bracket of two vector fields.

+---------------------------------------------------------------------------+
|i1 : X = random newField(2,1,"a")                                          |
|                                                                           |
|o1 = - x ax  + (- 4x  + 3x  + x )ax  + (- 4x  + x  + 5x )ax                |
|        1  0        0     1    2   1        0    1     2   2               |
|                                                                           |
|o1 : DiffAlgField                                                          |
+---------------------------------------------------------------------------+
|i2 : Y = random newField(2,1,"b")                                          |
|                                                                           |
|o2 = (4x  + 7x  + 3x )ax  + (2x  - 3x  + 4x )ax  + (6x  - 2x )ax           |
|        0     1     2   0      0     1     2   1      0     1   2          |
|                                                                           |
|o2 : DiffAlgField                                                          |
+---------------------------------------------------------------------------+
|i3 : X | Y                                                                 |
|                                                                           |
|o3 = (- 38x  + 17x  + 26x )ax  + (32x  + 17x )ax  + (- 8x  + 29x  + 6x )ax |
|           0      1      2   0       1      2   1        0      1     2   2|
|                                                                           |
|o3 : DiffAlgField                                                          |
+---------------------------------------------------------------------------+

See also
========

  * isInvolutive -- tests if a distribution is involutive

Ways to use this method:
========================

  * DiffAlgField | DiffAlgField -- Lie
    bracket

DiffAlgForm -- the class of all differential forms
**************************************************

See also
========

  * DiffAlgField -- the class of all vector fields

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

  * diff(DiffAlgForm) -- exterior differential
  * DiffAlgField _ DiffAlgForm, --
    contraction of a differential form with respect to a vector field
  * "DiffAlgForm _ DiffAlgField" -- see DiffAlgField _ DiffAlgForm,
    -- contraction of a differential form with
    respect to a vector field
  * "DiffAlgForm * DiffAlgForm" -- see DiffAlgForm ^ DiffAlgForm,
    -- exterior product
  * DiffAlgForm ^ DiffAlgForm -- exterior
    product
  * List * DiffAlgForm -- pull-back of a
    differential form by a rational map
  * "logarithmicForm(ZZ,List,String)" -- see logarithmicForm,
    -- creates a logarithmic form
  * "newForm(ZZ,ZZ,ZZ,String)" -- see newForm, -- constructor of
    a differential form
  * newForm(String) -- constructor of a
    differential form

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

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

DiffAlgForm ^ DiffAlgForm -- exterior product
*********************************************

Synopsis
========

  * Operator: ^ (Macaulay2Doc),
  * Usage:
        w ^ h
  * Inputs:
      * w, an instance of the type DiffAlgForm, a
        differential form
      * h, an instance of the type DiffAlgForm, a
        differential form
  * Outputs:
      * an instance of the type DiffAlgForm, the exterior
        product of w and h

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

This function computes the exterior product of two differential forms.

+-----------------------------------------------------------------------------+
|i1 : w = newForm(2,1,2,"a")                                                  |
|                                                                             |
|         2               2                          2           2            |
|o1 = (a x  + a x x  + a x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + |
|       0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0     1 0    4 0 1   |
|     ------------------------------------------------------------------------|
|         2                          2           2                2           |
|     a  x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + a  x  + a x x  +|
|      10 1    7 0 2    13 1 2    16 2   1     2 0    5 0 1    11 1    8 0 2  |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     a  x x  + a  x )dx                                                      |
|      14 1 2    17 2   2                                                     |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : h = newForm(2,1,1,"b")                                                  |
|                                                                             |
|o2 = (b x  + b x  + b x )dx  + (b x  + b x  + b x )dx  + (b x  + b x  +      |
|       0 0    3 1    6 2   0     1 0    4 1    7 2   1     2 0    5 1        |
|     ------------------------------------------------------------------------|
|     b x )dx                                                                 |
|      8 2   2                                                                |
|                                                                             |
|o2 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i3 : w ^ h                                                                   |
|                                                                             |
|                      3                                 2                    |
|o3 = ((- a b  + a b )x  + (- a b  + a b  - a b  + a b )x x  + (- a  b  + a b |
|          1 0    0 1  0       4 0    3 1    1 3    0 4  0 1       10 0    9 1|
|     ------------------------------------------------------------------------|
|                      2                    3                                 |
|     - a b  + a b )x x  + (- a  b  + a b )x  + (- a b  + a b  - a b  +       |
|        4 3    3 4  0 1       10 3    9 4  1       7 0    6 1    1 6         |
|     ------------------------------------------------------------------------|
|           2                                                                 |
|     a b )x x  + (- a  b  + a  b  - a b  + a b  - a b  + a b )x x x  + (-    |
|      0 7  0 2       13 0    12 1    7 3    6 4    4 6    3 7  0 1 2         |
|     ------------------------------------------------------------------------|
|                                   2                                       2 |
|     a  b  + a  b  - a  b  + a b )x x  + (- a  b  + a  b  - a b  + a b )x x  |
|      13 3    12 4    10 6    9 7  1 2       16 0    15 1    7 6    6 7  0 2 |
|     ------------------------------------------------------------------------|
|                                           2                     3           |
|     + (- a  b  + a  b  - a  b  + a  b )x x  + (- a  b  + a  b )x )dx dx  +  |
|           16 3    15 4    13 6    12 7  1 2       16 6    15 7  2   0  1    |
|     ------------------------------------------------------------------------|
|                      3                                 2                    |
|     ((- a b  + a b )x  + (- a b  + a b  - a b  + a b )x x  + (- a  b  + a b |
|          2 0    0 2  0       5 0    3 2    2 3    0 5  0 1       11 0    9 2|
|     ------------------------------------------------------------------------|
|                      2                    3                                 |
|     - a b  + a b )x x  + (- a  b  + a b )x  + (- a b  + a b  - a b  +       |
|        5 3    3 5  0 1       11 3    9 5  1       8 0    6 2    2 6         |
|     ------------------------------------------------------------------------|
|           2                                                                 |
|     a b )x x  + (- a  b  + a  b  - a b  + a b  - a b  + a b )x x x  + (-    |
|      0 8  0 2       14 0    12 2    8 3    6 5    5 6    3 8  0 1 2         |
|     ------------------------------------------------------------------------|
|                                   2                                       2 |
|     a  b  + a  b  - a  b  + a b )x x  + (- a  b  + a  b  - a b  + a b )x x  |
|      14 3    12 5    11 6    9 8  1 2       17 0    15 2    8 6    6 8  0 2 |
|     ------------------------------------------------------------------------|
|                                           2                     3           |
|     + (- a  b  + a  b  - a  b  + a  b )x x  + (- a  b  + a  b )x )dx dx  +  |
|           17 3    15 5    14 6    12 8  1 2       17 6    15 8  2   0  2    |
|     ------------------------------------------------------------------------|
|                      3                                 2                    |
|     ((- a b  + a b )x  + (- a b  + a b  - a b  + a b )x x  + (- a  b  +     |
|          2 1    1 2  0       5 1    4 2    2 4    1 5  0 1       11 1       |
|     ------------------------------------------------------------------------|
|                            2                     3                          |
|     a  b  - a b  + a b )x x  + (- a  b  + a  b )x  + (- a b  + a b  - a b  +|
|      10 2    5 4    4 5  0 1       11 4    10 5  1       8 1    7 2    2 7  |
|     ------------------------------------------------------------------------|
|           2                                                                 |
|     a b )x x  + (- a  b  + a  b  - a b  + a b  - a b  + a b )x x x  + (-    |
|      1 8  0 2       14 1    13 2    8 4    7 5    5 7    4 8  0 1 2         |
|     ------------------------------------------------------------------------|
|                                    2                                       2|
|     a  b  + a  b  - a  b  + a  b )x x  + (- a  b  + a  b  - a b  + a b )x x |
|      14 4    13 5    11 7    10 8  1 2       17 1    16 2    8 7    7 8  0 2|
|     ------------------------------------------------------------------------|
|                                           2                     3           |
|     + (- a  b  + a  b  - a  b  + a  b )x x  + (- a  b  + a  b )x )dx dx     |
|           17 4    16 5    14 7    13 8  1 2       17 7    16 8  2   1  2    |
|                                                                             |
|o3 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * DiffAlgForm ^ DiffAlgForm -- exterior
    product

dist -- produces a DiffAlgDistribution from a list
**************************************************

Synopsis
========

  * Usage:
        dist(L)
  * Inputs:
      * L, a list (Macaulay2Doc), list of vector fields, see
        DiffAlgField,
  * Outputs:
      * an instance of the type DiffAlgDistribution,
        generated by the vector fields in the given list.

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

This command checks that all the elements in the list are vector fields.

+----------------------------------------------------+
|i1 : X = newField("3*x_0*ax_0+x_1*ax_1")            |
|                                                    |
|o1 = 3x ax  + x ax                                  |
|       0  0    1  1                                 |
|                                                    |
|o1 : DiffAlgField                                   |
+----------------------------------------------------+
|i2 : Y = radial 3                                   |
|                                                    |
|o2 = x ax  + x ax  + x ax  + x ax                   |
|      0  0    1  1    2  2    3  3                  |
|                                                    |
|o2 : DiffAlgField                                   |
+----------------------------------------------------+
|i3 : dist {X,Y}                                     |
|                                                    |
|o3 = {3x ax  + x ax , x ax  + x ax  + x ax  + x ax }|
|        0  0    1  1   0  0    1  1    2  2    3  3 |
|                                                    |
|o3 : DiffAlgDistribution                            |
+----------------------------------------------------+

See also
========

  * newField -- constructor of a vector field
  * radial -- defines the radial vector field
  * rank(DiffAlgDistribution) -- rank of
    the given distribution
  * isInvolutive -- tests if a distribution is involutive

Ways to use dist :
==================

  * "dist(List)"

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

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

genIm -- a basis of the image of a linear expression
****************************************************

Synopsis
========

  * Usage:
        genIm(expr,var)
  * Inputs:
      * expr, an instance of the type DiffAlgElement, an
        expression linear in the variable var
      * var, an instance of the type DiffAlgElement,
        this is the variable of the linear expression, it must have free and
        linear scalar coefficients
  * Outputs:
      * a list (Macaulay2Doc), a basis of the image of the linear
        expression

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

This routine returns a basis of the image of expr, an homogeneous expression
linear in var.

In this example we compute a basis of the image of the derivative of a
projective differential 1-forms.

+-----------------------------------------------------------------------------+
|i1 : h = newForm(2,1,2,"a")                                                  |
|                                                                             |
|         2               2                          2           2            |
|o1 = (a x  + a x x  + a x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + |
|       0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0     1 0    4 0 1   |
|     ------------------------------------------------------------------------|
|         2                          2           2                2           |
|     a  x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + a  x  + a x x  +|
|      10 1    7 0 2    13 1 2    16 2   1     2 0    5 0 1    11 1    8 0 2  |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     a  x x  + a  x )dx                                                      |
|      14 1 2    17 2   2                                                     |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : R = radial 2                                                            |
|                                                                             |
|o2 = x ax  + x ax  + x ax                                                    |
|      0  0    1  1    2  2                                                   |
|                                                                             |
|o2 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i3 : H = linearComb(genKer(R _ h, h),"a")                                    |
|                                                                             |
|                  2                        2             2                   |
|o3 = (a x x  + a x  + a x x  + a x x  + a x )dx  + (- a x  - a x x  + a x x  |
|       0 0 1    3 1    1 0 2    4 1 2    6 2   0       0 0    3 0 1    2 0 2 |
|     ------------------------------------------------------------------------|
|                   2             2                        2                  |
|     + a x x  + a x )dx  + (- a x  + (- a  - a )x x  - a x  - a x x  -       |
|        5 1 2    7 2   1       1 0       2    4  0 1    5 1    6 0 2         |
|     ------------------------------------------------------------------------|
|     a x x )dx                                                               |
|      7 1 2   2                                                              |
|                                                                             |
|o3 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i4 : genIm(diff H,H)                                                         |
|                                                                             |
|o4 = {-3x dx dx , -3x dx dx , x dx dx  - x dx dx  - 2x dx dx , -3x dx dx , - |
|         0  0  1     0  0  2   2  0  1    1  0  2     0  1  2     1  0  1    |
|     ------------------------------------------------------------------------|
|     x dx dx  - 2x dx dx  - x dx dx , -3x dx dx , -3x dx dx , -3x dx dx }    |
|      2  0  1     1  0  2    0  1  2     1  1  2     2  0  2     2  1  2     |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

It is possible to get a linearly independent set of elements using this
routine:

+-----------------------------------------------------------------------------+
|i5 : w1=random newForm(2,1,2,"a");                                           |
+-----------------------------------------------------------------------------+
|i6 : w2=random newForm(2,1,2,"a");                                           |
+-----------------------------------------------------------------------------+
|i7 : w3=w1+w2;                                                               |
+-----------------------------------------------------------------------------+
|i8 : u=linearComb({w1,w2,w3},"a");                                           |
+-----------------------------------------------------------------------------+
|i9 : genIm(u,u)                                                              |
|                                                                             |
|         2             2                            2            2           |
|o9 = {(2x  - 2x x  + 6x  - 3x x  + 6x x )dx  + (- 7x  + 5x x  - x  - 2x x  - |
|         0     0 1     1     0 2     1 2   0        0     0 1    1     0 2   |
|      -----------------------------------------------------------------------|
|              2            2             2                     2             |
|      x x  + x )dx  + (- 3x  - 4x x  + 7x  + 2x x  - 7x x  - 3x )dx          |
|       1 2    2   1        0     0 1     1     0 2     1 2     2   2         |
|     ------------------------------------------------------------------------|
|          2             2                    2           2     2             |
|      , (x  + 7x x  + 3x  + 2x x  + x x  + 8x )dx  + (- x  - 4x  - 7x x  - x |
|          0     0 1     1     0 2    1 2     2   0       0     1     0 2    1|
|     -  ---------------------------------------------------------------------|
|           2          2             2            2                           |
|        - x )dx  + (3x  - 4x x  + 7x  - 5x x  + x )dx                        |
|           2   1      0     0 1     1     0 2    2   2                       |
|     ------------------------------------------------------------------------|
|                                                                             |
|     x  }                                                                    |
|      2                                                                      |
|     ---                                                                     |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : #oo                                                                    |
|                                                                             |
|o10 = 2                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * genKer -- basis of the kernel of a linear expression

Ways to use genIm :
===================

  * "genIm(DiffAlgElement,DiffAlgElement)"

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

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

genKer -- basis of the kernel of a linear expression
****************************************************

Synopsis
========

  * Usage:
        gerKer(expr,var)
  * Inputs:
      * expr, an instance of the type DiffAlgElement, an
        expression linear in the variable var
      * var, an instance of the type DiffAlgElement,
        this is the variable of the linear expression, it must have free and
        linear scalar coefficients
  * Outputs:
      * a list (Macaulay2Doc), basis of the kernel of the linear
        expression

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

This routine returns a basis of the kernel of expr, an homogeneous expression
linear in var.

In the case of a non-homogeneous linear expression, this routine returns a pair
having in the first coordinate a basis of the kernel of the associated
homogeneous linear expression and in the second coordinate a particular
solution.

In the first example, we compute a basis of projective differential 1-forms in
projective 3-space with polynomial coefficients of degree 1. Then, we define a
random rational differential form of type (1,1) and compute its tangent
directions using the generic projective form defined before.

In the second example, we compute a particular solution of a non-homogeneous
linear expression.

+-----------------------------------------------------------------------------+
|i1 : h = newForm(4,1,1,"a")                                                  |
|                                                                             |
|o1 = (a x  + a x  + a  x  + a  x  + a  x )dx  + (a x  + a x  + a  x  + a  x  |
|       0 0    5 1    10 2    15 3    20 4   0     1 0    6 1    11 2    16 3 |
|     ------------------------------------------------------------------------|
|     + a  x )dx  + (a x  + a x  + a  x  + a  x  + a  x )dx  + (a x  + a x  + |
|        21 4   1     2 0    7 1    12 2    17 3    22 4   2     3 0    8 1   |
|     ------------------------------------------------------------------------|
|     a  x  + a  x  + a  x )dx  + (a x  + a x  + a  x  + a  x  + a  x )dx     |
|      13 2    18 3    23 4   3     4 0    9 1    14 2    19 3    24 4   4    |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : R = radial 4                                                            |
|                                                                             |
|o2 = x ax  + x ax  + x ax  + x ax  + x ax                                    |
|      0  0    1  1    2  2    3  3    4  4                                   |
|                                                                             |
|o2 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i3 : T = genKer(R _ h,h)                                                     |
|                                                                             |
|o3 = {x dx  - x dx , x dx  - x dx , x dx  - x dx , x dx  - x dx , x dx  -    |
|       1  0    0  1   2  0    0  2   2  1    1  2   3  0    0  3   3  1      |
|     ------------------------------------------------------------------------|
|     x dx , x dx  - x dx , x dx  - x dx , x dx  - x dx , x dx  - x dx , x dx |
|      1  3   3  2    2  3   4  0    0  4   4  1    1  4   4  2    2  4   4  3|
|     ------------------------------------------------------------------------|
|     - x dx }                                                                |
|        3  4                                                                 |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : H = linearComb(T,"a")                                                   |
|                                                                             |
|o4 = (a x  + a x  + a x  + a x )dx  + (- a x  + a x  + a x  + a x )dx  + (-  |
|       0 1    1 2    3 3    6 4   0       0 0    2 2    4 3    7 4   1       |
|     ------------------------------------------------------------------------|
|     a x  - a x  + a x  + a x )dx  + (- a x  - a x  - a x  + a x )dx  + (-   |
|      1 0    2 1    5 3    8 4   2       3 0    4 1    5 2    9 4   3        |
|     ------------------------------------------------------------------------|
|     a x  - a x  - a x  - a x )dx                                            |
|      6 0    7 1    8 2    9 3   4                                           |
|                                                                             |
|o4 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i5 : w = random logarithmicForm(4,{1,1},"a", Projective => true)             |
|                                                                             |
|o5 = (49x  + 77x  + 14x  - 28x )dx  + (- 49x  + 140x  + 70x  - 140x )dx  + (-|
|         1      2      3      4   0         0       2      3       4   1     |
|     ------------------------------------------------------------------------|
|     77x  - 140x  + 70x  - 140x )dx  + (- 14x  - 70x  - 70x )dx  + (28x  +   |
|        0       1      3       4   2         0      1      2   3       0     |
|     ------------------------------------------------------------------------|
|     140x  + 140x )dx                                                        |
|         1       2   4                                                       |
|                                                                             |
|o5 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i6 : genKer(w ^ (diff H) + (diff w) ^ H,H)                                   |
|                                                                             |
|                                      1         1                     1      |
|o6 = {(x  + x )dx  - x dx  - x dx , - -x dx  + (-x  + x )dx  - x dx , -x dx  |
|        1    2   0    0  1    0  2    5 1  0    5 0    2   1    1  2  5 3  0 |
|     ------------------------------------------------------------------------|
|                          1                        1                         |
|     + x dx  + x dx  + (- -x  - x  - x )dx , (x  - -x  + x )dx  - x dx  +    |
|        3  1    3  2      5 0    1    2   3    1   2 3    4   0    0  1      |
|     ------------------------------------------------------------------------|
|     1                 11         11     1              1                 7  |
|     -x dx  - x dx , - --x dx  + (--x  - -x  + x )dx  + -x dx  - x dx , (--x |
|     2 0  3    0  4    20 1  0    20 0   2 3    4   1   2 1  3    1  4   20 1|
|     ------------------------------------------------------------------------|
|        1             7     1                     1     1                    |
|     + --x )dx  + (- --x  + -x )dx  + x dx  + (- --x  - -x )dx  - x dx , -   |
|       10 3   0      20 0   2 3   1    4  2      10 0   2 1   3    2  4      |
|     ------------------------------------------------------------------------|
|     11                 11                                                   |
|     --x dx  - x dx  + (--x  + x  + x )dx  - x dx }                          |
|     20 3  0    3  1    20 0    1    4   3    3  4                           |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
+-----------------------------------------------------------------------------+
|i7 : w1 = random newForm(4,1,1,"a");                                         |
+-----------------------------------------------------------------------------+
|i8 : w2 = random newForm(4,1,1,"a");                                         |
+-----------------------------------------------------------------------------+
|i9 : w3 = w1 ^ w2;                                                           |
+-----------------------------------------------------------------------------+
|i10 : h = newForm(4,1,1,"a");                                                |
+-----------------------------------------------------------------------------+
|i11 : last genKer(w1 ^ h - w3,h)                                             |
|                                                                             |
|         7          9          5          15           13     3     5        |
|o11 = (- -x  - x  - -x  + x  + -x )dx  + (--x  - 5x  - --x  - -x  + -x )dx  +|
|         4 0    1   4 2    3   4 4   0     2 0     1    2 2   4 3   2 4   1  |
|      -----------------------------------------------------------------------|
|         25     7     5     3     11          1           3                  |
|      (- --x  - -x  - -x  + -x  - --x )dx  + (-x  - 4x  - -x  - 4x  - 2x )dx |
|          4 0   2 1   4 2   2 3    4 4   2    4 0     1   4 2     3     4   3|
|      -----------------------------------------------------------------------|
|         11     3                                                            |
|      + (--x  - -x  - 2x  + 2x )dx                                           |
|          4 0   2 1     2     3   4                                          |
|                                                                             |
|o11 : DiffAlgForm                                                            |
+-----------------------------------------------------------------------------+

See also
========

  * genIm -- a basis of the image of a linear expression

Ways to use genKer :
====================

  * "genKer(DiffAlgElement,DiffAlgElement)"

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

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

homogenize(DiffAlgElement) -- homogenize a differential form or vector field
****************************************************************************

Synopsis
========

  * Function: homogenize (Macaulay2Doc),
  * Usage:
        homogenize e
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        form or a vector field
  * Outputs:
      * an instance of the type DiffAlgElement, the
        homogenization of e with respect to a new variable. The resulting form
        or vector field is homogeneous.

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

+-----------------------------------------+
|i1 : w = newForm("2*x_0*dx_0+x_1^2*dx_1")|
|                                         |
|               2                         |
|o1 = 2x dx  + x dx                       |
|       0  0    1  1                      |
|                                         |
|o1 : DiffAlgForm                         |
+-----------------------------------------+
|i2 : homogenize w                        |
|                                         |
|                 2                       |
|o2 = 2x x dx  + x dx                     |
|       0 2  0    1  1                    |
|                                         |
|o2 : DiffAlgForm                         |
+-----------------------------------------+
+---------------------------------------------------+
|i3 : homogenize newField ("ax_0+x_1*ax_2+a*ax_1")  |
|                                                   |
|o3 = x ax  + a*x ax  + x ax                        |
|      3  0      3  1    1  2                       |
|                                                   |
|o3 : DiffAlgField                                  |
+---------------------------------------------------+

Caveat
======

The homogenization process of a form adds one variable to the given element.

See also
========

  * projectivize -- projectivize a differential form or
    vector field
  * isHomogeneous (Macaulay2Doc) -- whether something is
    homogeneous (graded)

Ways to use this method:
========================

  * homogenize(DiffAlgElement), --
    homogenize a differential form or vector field

isHomogeneous(DiffAlgElement) -- tests if a form (or field) is homogeneous
**************************************************************************

Synopsis
========

  * Function: isHomogeneous (Macaulay2Doc),
  * Usage:
        isHomogeneous(e)
  * Inputs:
      * e, an instance of the type DiffAlgElement,
        representing a form or a field
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if the form (or
        field) is homogeneous

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

In this example we test if a vector field is homogeneous,

+------------------------------------+
|i1 : X = newField("3*ax_0+x_1*ax_1")|
|                                    |
|o1 = 3ax  + x ax                    |
|        0    1  1                   |
|                                    |
|o1 : DiffAlgField                   |
+------------------------------------+
|i2 : isHomogeneous X                |
|                                    |
|o2 = false                          |
+------------------------------------+

In this example we test if a projective logarithmic differential 1-form is
homogeneous,

+-----------------------------------------------------------------------------+
|i3 : w = random logarithmicForm(2,{1,2},"a",Projective => true)              |
|                                                                             |
|                    2                           2              2             |
|o3 = (120x x  + 144x  + 306x x  + 108x x  + 108x )dx  + (- 120x  - 144x x  - |
|          0 1       1       0 2       1 2       2   0          0       0 1   |
|     ------------------------------------------------------------------------|
|                            2              2       2                         |
|     108x x  - 264x x  - 72x )dx  + (- 306x  + 264x  - 108x x  + 72x x )dx   |
|         0 2       1 2      2   1          0       1       0 2      1 2   2  |
|                                                                             |
|o3 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i4 : isHomogeneous w                                                         |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * homogenize (Macaulay2Doc) -- homogenize with respect to a
    variable

Ways to use this method:
========================

  * isHomogeneous(DiffAlgElement), --
    tests if a form (or field) is homogeneous

isInvolutive -- tests if a distribution is involutive
*****************************************************

Synopsis
========

  * Usage:
        isInvolutive(L)
  * Inputs:
      * L, an instance of the type DiffAlgDistribution,
        as given by the output of dist,
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if the distribution
        L is involutive

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

If L is a list of vector fields, this routine tests the involutivity of L.

In this example we test the involutivity of two vector fields.

+----------------------------------------+
|i1 : X = newField("3*x_0*ax_0+x_1*ax_1")|
|                                        |
|o1 = 3x ax  + x ax                      |
|       0  0    1  1                     |
|                                        |
|o1 : DiffAlgField                       |
+----------------------------------------+
|i2 : Y = radial 3                       |
|                                        |
|o2 = x ax  + x ax  + x ax  + x ax       |
|      0  0    1  1    2  2    3  3      |
|                                        |
|o2 : DiffAlgField                       |
+----------------------------------------+
|i3 : isInvolutive dist {X,Y}            |
|                                        |
|o3 = true                               |
+----------------------------------------+

In this example we compute a basis of the annihilator of a random projective
logarithmic differential 1-form. Then we verify that it is an involutive
distribution.

+-----------------------------------------------------------------------------+
|i4 : w = random logarithmicForm(2,{1,2},"a",Projective => true)              |
|                                                                             |
|                    2                           2              2             |
|o4 = (120x x  + 144x  + 306x x  + 108x x  + 108x )dx  + (- 120x  - 144x x  - |
|          0 1       1       0 2       1 2       2   0          0       0 1   |
|     ------------------------------------------------------------------------|
|                            2              2       2                         |
|     108x x  - 264x x  - 72x )dx  + (- 306x  + 264x  - 108x x  + 72x x )dx   |
|         0 2       1 2      2   1          0       1       0 2      1 2   2  |
|                                                                             |
|o4 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i5 : X = newField(2,2,"a")                                                   |
|                                                                             |
|         2               2                          2           2            |
|o5 = (a x  + a x x  + a x  + a x x  + a  x x  + a  x )ax  + (a x  + a x x  + |
|       0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0     1 0    4 0 1   |
|     ------------------------------------------------------------------------|
|         2                          2           2                2           |
|     a  x  + a x x  + a  x x  + a  x )ax  + (a x  + a x x  + a  x  + a x x  +|
|      10 1    7 0 2    13 1 2    16 2   1     2 0    5 0 1    11 1    8 0 2  |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     a  x x  + a  x )ax                                                      |
|      14 1 2    17 2   2                                                     |
|                                                                             |
|o5 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i6 : D = genKer(X_w,X);                                                      |
+-----------------------------------------------------------------------------+
|i7 : #D                                                                      |
|                                                                             |
|o7 = 6                                                                       |
+-----------------------------------------------------------------------------+
|i8 : isInvolutive dist D                                                     |
|                                                                             |
|o8 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * newField -- constructor of a vector field
  * radial -- defines the radial vector field
  * rank(DiffAlgDistribution) -- rank of
    the given distribution

Ways to use isInvolutive :
==========================

  * "isInvolutive(DiffAlgDistribution)"

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

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

linearComb -- generic linear combination of elements
****************************************************

Synopsis
========

  * Usage:
        linearComb(L,varName)
  * Inputs:
      * L, a list (Macaulay2Doc), list of vector fields or
        differential forms, see DiffAlgField, or
        DiffAlgForm,
      * varName, a string (Macaulay2Doc), name of the generic
        coefficient
  * Outputs:
      * an instance of the type DiffAlgElement, generic
        linear combination of the list L

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

This routine produce a generic linear combination of the elements in L. It can
be used together with genKer, or genIm, to solve a
system of homogeneous linear equations.

In this example we compute a generic and a particular linear combination of two
particular differential 2-forms.

+-----------------------------------------------------------------------------+
|i1 : w = random newForm(2,1,2,"a")                                           |
|                                                                             |
|        2             2                            2            2            |
|o1 = (2x  - 2x x  + 6x  - 3x x  + 6x x )dx  + (- 7x  + 5x x  - x  - 2x x  -  |
|        0     0 1     1     0 2     1 2   0        0     0 1    1     0 2    |
|     ------------------------------------------------------------------------|
|             2            2             2                     2              |
|     x x  + x )dx  + (- 3x  - 4x x  + 7x  + 2x x  - 7x x  - 3x )dx           |
|      1 2    2   1        0     0 1     1     0 2     1 2     2   2          |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : h = random newForm(2,1,2,"a")                                           |
|                                                                             |
|       2             2                    2           2     2                |
|o2 = (x  + 7x x  + 3x  + 2x x  + x x  + 8x )dx  + (- x  - 4x  - 7x x  - x x  |
|       0     0 1     1     0 2    1 2     2   0       0     1     0 2    1 2 |
|     ------------------------------------------------------------------------|
|        2          2             2            2                              |
|     - x )dx  + (3x  - 4x x  + 7x  - 5x x  + x )dx                           |
|        2   1      0     0 1     1     0 2    2   2                          |
|                                                                             |
|o2 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i3 : linearComb({w,h},"a")                                                   |
|                                                                             |
|                 2                                   2                       |
|o3 = ((2a  + a )x  + (- 2a  + 7a )x x  + (6a  + 3a )x  + (- 3a  + 2a )x x  + |
|         0    1  0        0     1  0 1      0     1  1        0     1  0 2   |
|     ------------------------------------------------------------------------|
|                          2                     2                          2 |
|     (6a  + a )x x  + 8a x )dx  + ((- 7a  - a )x  + 5a x x  + (- a  - 4a )x  |
|        0    1  1 2     1 2   0         0    1  0     0 0 1       0     1  1 |
|     ------------------------------------------------------------------------|
|                                                       2                     |
|     + (- 2a  - 7a )x x  + (- a  - a )x x  + (a  - a )x )dx  + ((- 3a  +     |
|            0     1  0 2       0    1  1 2     0    1  2   1         0       |
|     ------------------------------------------------------------------------|
|          2                                   2                              |
|     3a )x  + (- 4a  - 4a )x x  + (7a  + 7a )x  + (2a  - 5a )x x  - 7a x x  +|
|       1  0        0     1  0 1      0     1  1      0     1  0 2     0 1 2  |
|     ------------------------------------------------------------------------|
|                  2                                                          |
|     (- 3a  + a )x )dx                                                       |
|          0    1  2   2                                                      |
|                                                                             |
|o3 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i4 : random oo                                                               |
|                                                                             |
|        2               2                       2             2              |
|o4 = (6x  + 10x x  + 18x  - 2x x  + 14x x  + 16x )dx  + (- 16x  + 10x x  -   |
|        0      0 1      1     0 2      1 2      2   0         0      0 1     |
|     ------------------------------------------------------------------------|
|        2                                       2                      2     |
|     10x  - 18x x  - 4x x )dx  + (- 16x x  + 28x  - 6x x  - 14x x  - 4x )dx  |
|        1      0 2     1 2   1         0 1      1     0 2      1 2     2   2 |
|                                                                             |
|o4 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

In this example we compute a generic differential 1-form that descends to the
projective plane. Then, we impose another linear condition.

+-----------------------------------------------------------------------------+
|i5 : w = newForm(2,1,2,"a");                                                 |
+-----------------------------------------------------------------------------+
|i6 : h = random newForm(2,2,1,"a");                                          |
+-----------------------------------------------------------------------------+
|i7 : L = genKer( (radial 2) _ w,w)                                           |
|                                                                             |
|                 2                2                         2                |
|o7 = {x x dx  - x dx , x x dx  - x dx , x x dx  - x x dx , x dx  - x x dx ,  |
|       0 1  0    0  1   0 2  0    0  2   0 2  1    0 1  2   1  0    0 1  1   |
|     ------------------------------------------------------------------------|
|                                   2      2                2                 |
|     x x dx  - x x dx , x x dx  - x dx , x dx  - x x dx , x dx  - x x dx }   |
|      1 2  0    0 1  2   1 2  1    1  2   2  0    0 2  2   2  1    1 2  2    |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+
|i8 : wr = linearComb(L,"a")                                                  |
|                                                                             |
|                  2                        2             2                   |
|o8 = (a x x  + a x  + a x x  + a x x  + a x )dx  + (- a x  - a x x  + a x x  |
|       0 0 1    3 1    1 0 2    4 1 2    6 2   0       0 0    3 0 1    2 0 2 |
|     ------------------------------------------------------------------------|
|                   2             2                        2                  |
|     + a x x  + a x )dx  + (- a x  + (- a  - a )x x  - a x  - a x x  -       |
|        5 1 2    7 2   1       1 0       2    4  0 1    5 1    6 0 2         |
|     ------------------------------------------------------------------------|
|     a x x )dx                                                               |
|      7 1 2   2                                                              |
|                                                                             |
|o8 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i9 : genKer(h ^ wr, wr)                                                      |
|                                                                             |
|       5 2   5       3       3 2          5       3       2        2         |
|o9 = {(-x  + -x x  + -x x  + -x )dx  + (- -x x  + -x x  + -x x  + x )dx  + (-|
|       7 1   7 0 2   7 1 2   7 2   0      7 0 1   7 0 2   7 1 2    2   1     |
|      -----------------------------------------------------------------------|
|      5 2   6       2 2   3                                                  |
|      -x  - -x x  - -x  - -x x  - x x )dx                                    |
|      7 0   7 0 1   7 1   7 0 2    1 2   2                                   |
|     ------------------------------------------------------------------------|
|      }                                                                      |
|                                                                             |
|     -                                                                       |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * newField -- constructor of a vector field
  * newForm -- constructor of a differential form
  * random (Macaulay2Doc) -- get a random element
  * genKer -- basis of the kernel of a linear expression
  * genIm -- a basis of the image of a linear expression

Ways to use linearComb :
========================

  * "linearComb(List,String)"

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

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

List * DiffAlgForm -- pull-back of a differential form by a rational map
************************************************************************

Synopsis
========

  * Operator: * (Macaulay2Doc),
  * Usage:
        L * w
  * Inputs:
      * L, a list (Macaulay2Doc), the rational map represented by a
        list of polynomials as 0-forms, see DiffAlgForm,
      * w, an instance of the type DiffAlgForm, a
        differential form
  * Outputs:
      * an instance of the type DiffAlgForm, the pull-back
        of w via L

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

Given a list of polynomials F = (F_0,...,F_n) and a differential form w on  n+1
variables, the pull-back F*w is defined as the composition w(F).

In this example we compute the pull-back of the 1-differential form w with
respect to the mapping F = (F_0,F_1,F_2).

+-----------------------------------------------------------------------------+
|i1 : F_0 = random newForm(1,0,1,"a");                                        |
+-----------------------------------------------------------------------------+
|i2 : F_1 = random newForm(1,0,2,"a");                                        |
+-----------------------------------------------------------------------------+
|i3 : F_2 = random newForm(1,0,1,"a");                                        |
+-----------------------------------------------------------------------------+
|i4 : w = random newForm(2,2,1,"a")                                           |
|                                                                             |
|o4 = (- 5x  - 3x  + 6x )dx dx  + (- 3x  + 4x  + 7x )dx dx  + (- 3x  + 2x  -  |
|          0     1     2   0  1        0     1     2   0  2        0     1    |
|     ------------------------------------------------------------------------|
|     3x )dx dx                                                               |
|       2   1  2                                                              |
|                                                                             |
|o4 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i5 : {F_0,F_1,F_2}*w                                                         |
|                                                                             |
|         3      2           2       3       2                   2            |
|o5 = (17x  + 75x x  - 885x x  - 800x  + 593x  + 3162x x  - 3680x  + 288x  -  |
|         0      0 1       0 1       1       0        0 1        1       0    |
|     ------------------------------------------------------------------------|
|     256x )dx dx                                                             |
|         1   0  1                                                            |
|                                                                             |
|o5 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * List * DiffAlgForm -- pull-back of a
    differential form by a rational map

logarithmicForm -- creates a logarithmic form
*********************************************

Synopsis
========

  * Usage:
        logarithmicForm(n,L,varName)
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables minus one
      * L, a list (Macaulay2Doc), list of degrees
      * varName, a string (Macaulay2Doc), name of the
        coefficients
  * Optional inputs (Macaulay2Doc),:
      * Projective,
        => a Boolean value (Macaulay2Doc), default value
        false, whether to create a logarithmic form that descends to projective
        space
  * Outputs:
      * an instance of the type DiffAlgForm, a generic
        logarithmic form

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

A logarithmic form of type (d_0,...,d_n) is a differential 1-form w that can be
written as w=(prod f_i)sum df_i/f_i, where f_i is a polynomial of degree d_i.
This routine creates such a logarithmic form using homogeneous polynomials.
When using a list L of length two, the differential form is called rational.

In this example we generate a random logarithmic form in affine 3-dimensional
space with degrees (1,1,2).

+-----------------------------------------------------------------------------+
|i1 : random logarithmicForm(2,{1,1,2},"a")                                   |
|                                                                             |
|           2          2      3       2                     2           2     |
|o1 = (- 30x x  + 20x x  + 10x  + 600x x  - 395x x x  - 220x x  - 100x x  +   |
|           0 1      0 1      1       0 2       0 1 2       1 2       0 2     |
|     ------------------------------------------------------------------------|
|           2       3           3      2          2      2                    |
|     405x x  - 100x )dx  + (30x  - 20x x  - 10x x  - 95x x  + 80x x x  +     |
|         1 2       2   0       0      0 1      0 1      0 2      0 1 2       |
|     ------------------------------------------------------------------------|
|        2          2        2      3              3       2           2      |
|     30x x  + 10x x  - 60x x  + 15x )dx  + (- 600x  + 490x x  + 140x x  -    |
|        1 2      0 2      1 2      2   1          0       0 1       0 1      |
|     ------------------------------------------------------------------------|
|        3       2                    2           2        2                  |
|     30x  + 100x x  - 415x x x  + 60x x  + 100x x  - 15x x )dx               |
|        1       0 2       0 1 2      1 2       0 2      1 2   2              |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

In this example we generate a generic rational form in the projective plane of
type (1,1).

+-----------------------------------------------------------------------------+
|i2 : logarithmicForm(2,{1,1},"a",Projective => true)                         |
|                                                                             |
|o2 = ((a0 a2 a1  - a1 a0 a2 )x  + (a0 a2 a1  - a1 a0 a2 )x )dx  + ((-        |
|         1  0  1     0  1  1  1      1  0  2     0  1  2  2   0              |
|     ------------------------------------------------------------------------|
|     a0 a2 a1  + a1 a0 a2 )x  + (a0 a1 a2  - a0 a1 a2 )x )dx  + ((- a0 a2 a1 |
|       1  0  1     0  1  1  0      1  2  1     1  1  2  2   1         1  0  2|
|     ------------------------------------------------------------------------|
|     + a1 a0 a2 )x  + (- a0 a1 a2  + a0 a1 a2 )x )dx                         |
|         0  1  2  0        1  2  1     1  1  2  1   2                        |
|                                                                             |
|o2 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

In the following example, we produce a logarithmic form that descends to
projective space.

+---------------------------------------------------------------+
|i3 : l = random logarithmicForm(2,{1,1},"a",Projective => true)|
|                                                               |
|o3 = (9x  - 11x )dx  + (- 9x  - 19x )dx  + (11x  + 19x )dx     |
|        1      2   0        0      2   1       0      1   2    |
|                                                               |
|o3 : DiffAlgForm                                               |
+---------------------------------------------------------------+
|i4 : (radial 2)_l                                              |
|                                                               |
|o4 = 0                                                         |
|                                                               |
|o4 : DiffAlgForm                                               |
+---------------------------------------------------------------+

Ways to use logarithmicForm :
=============================

  * "logarithmicForm(ZZ,List,String)"

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

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

logarithmicForm(...,Projective=>...) -- a boolean option to produce a projective logarithmic form
*************************************************************************************************

Synopsis
========

  * Usage:
        logarithmicForm(..., Projective => b)
  * Inputs:
      * b, a Boolean value (Macaulay2Doc), if true, it return a
        generic projective logarithmic form

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

+-----------------------------------------------------------------------------+
|i1 : l = logarithmicForm(2,{1,1},"a",Projective => true)                     |
|                                                                             |
|o1 = ((a0 a2 a1  - a1 a0 a2 )x  + (a0 a2 a1  - a1 a0 a2 )x )dx  + ((-        |
|         1  0  1     0  1  1  1      1  0  2     0  1  2  2   0              |
|     ------------------------------------------------------------------------|
|     a0 a2 a1  + a1 a0 a2 )x  + (a0 a1 a2  - a0 a1 a2 )x )dx  + ((- a0 a2 a1 |
|       1  0  1     0  1  1  0      1  2  1     1  1  2  2   1         1  0  2|
|     ------------------------------------------------------------------------|
|     + a1 a0 a2 )x  + (- a0 a1 a2  + a0 a1 a2 )x )dx                         |
|         0  1  2  0        1  2  1     1  1  2  1   2                        |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : (radial 2)_l                                                            |
|                                                                             |
|o2 = 0                                                                       |
|                                                                             |
|o2 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

Further information
===================

  * Default value: false (Macaulay2Doc),
  * Function: logarithmicForm, -- creates a logarithmic
    form
  * Option key: Projective (Macaulay2Doc), -- whether to
    produce a projective Hilbert polynomial

Functions with optional argument named Projective :
===================================================

  * hilbertPolynomial(...,Projective=>...) (Macaulay2Doc),
    --
    choose how to display the Hilbert polynomial
  * logarithmicForm(...,Projective=>...)
    -- a boolean option
    to produce a projective logarithmic form

moduliIdeal -- ideal generated by the coefficients of a differential form or vector field
*****************************************************************************************

Synopsis
========

  * Usage:
        moduliIdeal(e)
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or vector field
  * Outputs:
      * an ideal (Macaulay2Doc), the ideal generated by the scalar
        coefficients of e

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

Given a differential form or vector field, this routine returns the ideal
generated by the scalar coefficients of such element.

In this example we compute the equations that the scalar coefficients of a
closed differential 1-form must satisfy.

+-----------------------------------------------------------------------------+
|i1 : w = newForm(2,1,2,"a")                                                  |
|                                                                             |
|         2               2                          2           2            |
|o1 = (a x  + a x x  + a x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + |
|       0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0     1 0    4 0 1   |
|     ------------------------------------------------------------------------|
|         2                          2           2                2           |
|     a  x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + a  x  + a x x  +|
|      10 1    7 0 2    13 1 2    16 2   1     2 0    5 0 1    11 1    8 0 2  |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     a  x x  + a  x )dx                                                      |
|      14 1 2    17 2   2                                                     |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : diff w                                                                  |
|                                                                             |
|o2 = ((2a  - a )x  + (a  - 2a )x  + (a  - a  )x )dx dx  + ((2a  - a )x  + (a |
|         1    3  0     4     9  1     7    12  2   0  1       2    6  0     5|
|     ------------------------------------------------------------------------|
|     - a  )x  + (a  - 2a  )x )dx dx  + ((a  - a )x  + (2a   - a  )x  + (a   -|
|        12  1     8     15  2   0  2      5    7  0      11    13  1     14  |
|     ------------------------------------------------------------------------|
|     2a  )x )dx dx                                                           |
|       16  2   1  2                                                          |
|                                                                             |
|o2 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i3 : moduliIdeal(diff w)                                                     |
|                                                                             |
|o3 = ideal (2a  - a , a  - 2a , a  - a  , 2a  - a , a  - a  , a  - 2a  , a  -|
|              1    3   4     9   7    12    2    6   5    12   8     15   5  |
|     ------------------------------------------------------------------------|
|     a , 2a   - a  , a   - 2a  )                                             |
|      7    11    13   14     16                                              |
|                                                                             |
|               QQ[i]                                                         |
|o3 : Ideal of ------[][a ..a  ]                                              |
|               2        0   17                                               |
|              i  + 1                                                         |
+-----------------------------------------------------------------------------+

See also
========

  * singularIdeal -- ideal generated by the polynomial
    coefficients of a differential form or vector field

Ways to use moduliIdeal :
=========================

  * "moduliIdeal(DiffAlgElement)"

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

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

newField -- constructor of a vector field
*****************************************

Synopsis
========

  * Usage:
        newField(n,d,varName)
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables minus one
      * d, an integer (Macaulay2Doc), degree of the homogeneous
        polynomial coefficients
      * varName, name of the generic scalar coefficients
  * Outputs:
      * an instance of the type DiffAlgField, a
        homogeneous vector field in (n+1)-dimensional affine space with generic
        scalar coefficients

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

This function defines homogeneous vector fields with generic scalar
coefficients. By default, the affine coordinates will be x_0,...,x_n and the
partial derivatives are denoted as ax_0,...,ax_n, respectively.

In this example we define a homogeneous vector field with linear polynomial
coefficients in 3 variables. The scalar coefficients are chosen to be defined
with the variable a. The index of the scalar coefficients will always start
with 0.

+-----------------------------------------------------------------------------+
|i1 : X = newField(2,2,"a")                                                   |
|                                                                             |
|         2               2                          2           2            |
|o1 = (a x  + a x x  + a x  + a x x  + a  x x  + a  x )ax  + (a x  + a x x  + |
|       0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0     1 0    4 0 1   |
|     ------------------------------------------------------------------------|
|         2                          2           2                2           |
|     a  x  + a x x  + a  x x  + a  x )ax  + (a x  + a x x  + a  x  + a x x  +|
|      10 1    7 0 2    13 1 2    16 2   1     2 0    5 0 1    11 1    8 0 2  |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     a  x x  + a  x )ax                                                      |
|      14 1 2    17 2   2                                                     |
|                                                                             |
|o1 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i2 : ring X                                                                  |
|                                                                             |
|      QQ[i]                                                                  |
|o2 = ------[][a ..a  ][x ..x ][ax ..ax ]                                     |
|      2        0   17   0   2    0    2                                      |
|     i  + 1                                                                  |
|                                                                             |
|o2 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+

Caveat
======

The coefficient i is the imaginary unit.

See also
========

  * newField(String) -- constructor of a vector
    field
  * newForm -- constructor of a differential form

Ways to use newField :
======================

  * "newField(ZZ,ZZ,String)"
  * newField(String) -- constructor of a vector
    field

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

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

newField(String) -- constructor of a vector field
*************************************************

Synopsis
========

  * Function: newField,
  * Usage:
        newField(expression)
  * Inputs:
      * expression, a string (Macaulay2Doc), the expression to be
        evaluated
  * Outputs:
      * an instance of the type DiffAlgField, the vector
        field written in expression

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

This function defines the particular vector field written in the given
expression as elements of type DiffAlgField. If any
parameters are founded in the given expression, they are automatically included
in the ring of scalar coefficients.

In the following example we define two particular vector fields, X and Y, and
compute the addition X+Y. Notice that in the definition of X we are introducing
a scalar parameter named a, also the variable x_2 is missing from the ring of
X. When computing X+Y, the rings of both vector fields are automatically
merged.

+----------------------------------+
|i1 : X = newField("2*a*x_0*ax_1") |
|                                  |
|o1 = 2a*x ax                      |
|         0  1                     |
|                                  |
|o1 : DiffAlgField                 |
+----------------------------------+
|i2 : ring X                       |
|                                  |
|      QQ[i]                       |
|o2 = ------[][a][x ..x ][ax ..ax ]|
|      2           0   1    0    1 |
|     i  + 1                       |
|                                  |
|o2 : PolynomialRing               |
+----------------------------------+
|i3 : Y = newField("x_0*ax_2")     |
|                                  |
|o3 = x ax                         |
|      0  2                        |
|                                  |
|o3 : DiffAlgField                 |
+----------------------------------+
|i4 : ring Y                       |
|                                  |
|      QQ[i]                       |
|o4 = ------[][x ..x ][ax ..ax ]   |
|      2        0   2    0    2    |
|     i  + 1                       |
|                                  |
|o4 : PolynomialRing               |
+----------------------------------+
|i5 : X+Y                          |
|                                  |
|o5 = 2a*x ax  + x ax              |
|         0  1    0  2             |
|                                  |
|o5 : DiffAlgField                 |
+----------------------------------+
|i6 : ring (X+Y)                   |
|                                  |
|      QQ[i]                       |
|o6 = ------[][a][x ..x ][ax ..ax ]|
|      2           0   2    0    2 |
|     i  + 1                       |
|                                  |
|o6 : PolynomialRing               |
+----------------------------------+

In this example we show that the variables will always start from the index 0
and go up to the highest index encountered in the expression defining the
vector field.

+-------------------------------+
|i7 : Z = newField("ax_5")      |
|                               |
|o7 = ax                        |
|       5                       |
|                               |
|o7 : DiffAlgField              |
+-------------------------------+
|i8 : ring Z                    |
|                               |
|      QQ[i]                    |
|o8 = ------[][x ..x ][ax ..ax ]|
|      2        0   5    0    5 |
|     i  + 1                    |
|                               |
|o8 : PolynomialRing            |
+-------------------------------+

Caveat
======

By default, the affine coordinates will be x_0,...,x_n and the partial
derivatives are denoted as ax_0,...ax_n, respectively. The coefficient i is the
imaginary unit.

See also
========

  * newField(ZZ,ZZ,String) -- constructor of a vector field
  * newForm -- constructor of a differential form

Ways to use this method:
========================

  * newField(String) -- constructor of a vector
    field

newForm -- constructor of a differential form
*********************************************

Synopsis
========

  * Usage:
        newForm(n,r,d,varName)
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables minus one
      * r, an integer (Macaulay2Doc), degree of the differential form
      * d, an integer (Macaulay2Doc), degree of the polynomial
        coefficients of the differential form
      * varName, a string (Macaulay2Doc), name of the generic
        scalar coefficients of the differential form
  * Outputs:
      * an instance of the type DiffAlgForm, a homogeneous
        differential r-form in (n+1)-dimensional  affine space with polynomial
        coefficients of degree d

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

This function defines homogeneous differential forms with generic scalar
coefficients. By default, the affine coordinates will be x_0,...,x_n and their
exterior derivatives are denoted as dx_0,...,dx_n, respectively.

In this example we define a homogeneous differential 1-form with linear
polynomial coefficients in 3 variables. The scalar coefficients are chosen to
be defined with the variable a. The index of the scalar coefficients will
always start with 0.

+-----------------------------------------------------------------------------+
|i1 : w = newForm(2,1,1,"a")                                                  |
|                                                                             |
|o1 = (a x  + a x  + a x )dx  + (a x  + a x  + a x )dx  + (a x  + a x  +      |
|       0 0    3 1    6 2   0     1 0    4 1    7 2   1     2 0    5 1        |
|     ------------------------------------------------------------------------|
|     a x )dx                                                                 |
|      8 2   2                                                                |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : ring w                                                                  |
|                                                                             |
|      QQ[i]                                                                  |
|o2 = ------[][a ..a ][x ..x ][dx ..dx ]                                      |
|      2        0   8   0   2    0    2                                       |
|     i  + 1                                                                  |
|                                                                             |
|o2 : PolynomialRing, 3 skew commutative variables                            |
+-----------------------------------------------------------------------------+

Caveat
======

The coefficient i is the imaginary unit.

See also
========

  * newForm(String) -- constructor of a
    differential form
  * newField -- constructor of a vector field

Ways to use newForm :
=====================

  * "newForm(ZZ,ZZ,ZZ,String)"
  * newForm(String) -- constructor of a
    differential form

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

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

newForm(String) -- constructor of a differential form
*****************************************************

Synopsis
========

  * Function: newForm,
  * Usage:
        newForm(expression)
  * Inputs:
      * expression, a string (Macaulay2Doc), the expression to be
        evaluated
  * Outputs:
      * an instance of the type DiffAlgForm, the
        differential form written in expression

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

This function defines the particular differential form written in the given
expression as elements of type DiffAlgForm. Notice that the
exterior product must be written as the ordinary product of variables *. If any
parameters are founded in the given expression, they are automatically included
in the ring of scalar coefficients.

In the following example we define two particular differential forms, w and z,
and compute the exterior product w^z, see DiffAlgForm ^ DiffAlgForm.
In the definition of w we are introducing a scalar
parameter named a. Notice that the variable x_2 is missing from the ring of w.
But when computing w^z, the rings of both vector fields are automatically
merged.

+-------------------------------------------------+
|i1 : w = newForm("a * x_1 * dx_0 * dx_1")        |
|                                                 |
|o1 = a*x dx dx                                   |
|        1  0  1                                  |
|                                                 |
|o1 : DiffAlgForm                                 |
+-------------------------------------------------+
|i2 : ring w                                      |
|                                                 |
|      QQ[i]                                      |
|o2 = ------[][a][x ..x ][dx ..dx ]               |
|      2           0   1    0    1                |
|     i  + 1                                      |
|                                                 |
|o2 : PolynomialRing, 2 skew commutative variables|
+-------------------------------------------------+
|i3 : z = newForm("x_0^2 * dx_2 - x_2^2 * dx_0")  |
|                                                 |
|        2       2                                |
|o3 = - x dx  + x dx                              |
|        2  0    0  2                             |
|                                                 |
|o3 : DiffAlgForm                                 |
+-------------------------------------------------+
|i4 : ring z                                      |
|                                                 |
|      QQ[i]                                      |
|o4 = ------[][x ..x ][dx ..dx ]                  |
|      2        0   2    0    2                   |
|     i  + 1                                      |
|                                                 |
|o4 : PolynomialRing, 3 skew commutative variables|
+-------------------------------------------------+
|i5 : w ^ z                                       |
|                                                 |
|        2                                        |
|o5 = a*x x dx dx dx                              |
|        0 1  0  1  2                             |
|                                                 |
|o5 : DiffAlgForm                                 |
+-------------------------------------------------+
|i6 : ring (w+z)                                  |
|                                                 |
|      QQ[i]                                      |
|o6 = ------[][a][x ..x ][dx ..dx ]               |
|      2           0   2    0    2                |
|     i  + 1                                      |
|                                                 |
|o6 : PolynomialRing, 3 skew commutative variables|
+-------------------------------------------------+

In this example we show that the variables will always start from the index 0
and go up to the highest index encountered in the expression defining the
differential form.

+-------------------------------------------------+
|i7 : v = newForm("dx_5")                         |
|                                                 |
|o7 = dx                                          |
|       5                                         |
|                                                 |
|o7 : DiffAlgForm                                 |
+-------------------------------------------------+
|i8 : ring v                                      |
|                                                 |
|      QQ[i]                                      |
|o8 = ------[][x ..x ][dx ..dx ]                  |
|      2        0   5    0    5                   |
|     i  + 1                                      |
|                                                 |
|o8 : PolynomialRing, 6 skew commutative variables|
+-------------------------------------------------+

Caveat
======

By default, the affine coordinates will be x_0,...,x_n and the differentials
are denoted as dx_0,...,dx_n, respectively. The coefficient i is the imaginary
unit.

See also
========

  * newField -- constructor of a vector field
  * newForm(ZZ,ZZ,ZZ,String) -- constructor of a differential
    form

Ways to use this method:
========================

  * newForm(String) -- constructor of a
    differential form

projectivize -- projectivize a differential form or vector field
****************************************************************

Synopsis
========

  * Usage:
        projectivize e
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        form or a vector field
  * Outputs:
      * an instance of the type DiffAlgElement, the
        projectivization of e with respect to a new variable. The resulting
        form or vector field descends to projective space.

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

This returns the unique differential form that extends the given one from
affine space to projective space.

+-------------------------------------------+
|i1 : w = newForm("2*x_0*dx_0+x_1^2*dx_1")  |
|                                           |
|               2                           |
|o1 = 2x dx  + x dx                         |
|       0  0    1  1                        |
|                                           |
|o1 : DiffAlgForm                           |
+-------------------------------------------+
|i2 : r = radial 2                          |
|                                           |
|o2 = x ax  + x ax  + x ax                  |
|      0  0    1  1    2  2                 |
|                                           |
|o2 : DiffAlgField                          |
+-------------------------------------------+
|i3 : projectivize w                        |
|                                           |
|         2       2            3     2      |
|o3 = 2x x dx  + x x dx  + (- x  - 2x x )dx |
|       0 2  0    1 2  1       1     0 2   2|
|                                           |
|o3 : DiffAlgForm                           |
+-------------------------------------------+
|i4 : r_oo                                  |
|                                           |
|o4 = 0                                     |
|                                           |
|o4 : DiffAlgForm                           |
+-------------------------------------------+
+-----------------------------------------------------+
|i5 : projectivize newField ("ax_0+x_1*ax_2+a*ax_1")  |
|                                                     |
|o5 = x ax  + a*x ax  + x ax                          |
|      3  0      3  1    1  2                         |
|                                                     |
|o5 : DiffAlgField                                    |
+-----------------------------------------------------+

Caveat
======

The projectivization process of a form increases the polynomial degree by one
if the original element did not descend to projective space.

See also
========

  * homogenize (Macaulay2Doc) -- homogenize with respect to a
    variable
  * isHomogeneous (Macaulay2Doc) -- whether something is
    homogeneous (graded)

Ways to use projectivize :
==========================

  * "projectivize(DiffAlgElement)"

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

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

radial -- defines the radial vector field
*****************************************

Synopsis
========

  * Usage:
        radial n
  * Inputs:
      * n, an integer (Macaulay2Doc), number of variables minus one
  * Outputs:
      * an instance of the type DiffAlgField, the radial
        vector field in the n-dimensional projective space

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

This function defines the radial field vector field in (n+1)-variables.

+--------------------------+
|i1 : radial 2             |
|                          |
|o1 = x ax  + x ax  + x ax |
|      0  0    1  1    2  2|
|                          |
|o1 : DiffAlgField         |
+--------------------------+

Ways to use radial :
====================

  * "radial(ZZ)"

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

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

random(DiffAlgElement,Ring) -- replaces the variables of the coefficient ring of a differential form or a vector field with random values
*****************************************************************************************************************************************

Synopsis
========

  * Function: random (Macaulay2Doc),
  * Usage:
        random(e,R)
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or vector field with generic coefficients
      * R, a ring (Macaulay2Doc), the ring where the random values
        are taken from. Default value is an integer (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Density (Macaulay2Doc), => ...,
        default value 1, null
      * Height (Macaulay2Doc), => ..., default value 10,
        null
      * MaximalRank (Macaulay2Doc), => ...,
        default value false, null
      * UpperTriangular (Macaulay2Doc), =>
        ..., default value false, null
  * Outputs:
      * an instance of the type DiffAlgElement, the
        differential form or vector field e whose variables of the coefficient
        ring were evaluated at random values

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

+-----------------------------------------------------------------------------+
|i1 : random newForm(2,2,1,"a")                                               |
|                                                                             |
|o1 = - x dx dx  + (- 4x  + 3x  + x )dx dx  + (- 4x  + x  + 5x )dx dx         |
|        1  0  1        0     1    2   0  2        0    1     2   1  2        |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : random(newField(2,2,"a"),QQ)                                            |
|                                                                             |
|      22 2   1        5 2   18       28       23 2          43 2   23        |
|o2 = (--x  + -x x  - --x  - --x x  + --x x  + --x )ax  + (- --x  - --x x  +  |
|      63 0   5 0 1   24 1    7 0 2    5 1 2    5 2   0      10 0    3 0 1    |
|     ------------------------------------------------------------------------|
|     1 2           5        9 2          11 2             2   10       59    |
|     -x  + x x  - --x x  - --x )ax  + (- --x  + 4x x  - 3x  - --x x  - --x x |
|     6 1    0 2   12 1 2   10 2   1      18 0     0 1     1   21 0 2   18 1 2|
|     ------------------------------------------------------------------------|
|       1 2                                                                   |
|     - -x )ax                                                                |
|       4 2   2                                                               |
|                                                                             |
|o2 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+

Options Density and Height are implemented

+-----------------------------------------------------------------------------+
|i3 : random(newForm(2,2,1,"a"),Density => .2)                                |
|                                                                             |
|o3 = (- 4x  - 8x )dx dx  + (- 6x  + 4x )dx dx                                |
|          1     2   0  1        0     2   0  2                               |
|                                                                             |
|o3 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i4 : random(newForm(2,2,1,"a"),Height => 100)                                |
|                                                                             |
|o4 = (58x  + 73x  - 54x )dx dx  + (- 56x  + 31x  + 48x )dx dx  + (32x  + 38x |
|         0      1      2   0  1         0      1      2   0  2       0      1|
|     ------------------------------------------------------------------------|
|     - 4x )dx dx                                                             |
|         2   1  2                                                            |
|                                                                             |
|o4 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+

Caveat
======

This routine depends on the Macaulay2 method random (Macaulay2Doc),
which is not implemented in some rings. The option
random(...,Density=>...) (Macaulay2Doc), applied to
a non-generic form (such us 2a logarithmic form) may return a form equal to 0

Ways to use this method:
========================

  * "random(DiffAlgElement)"
  * random(DiffAlgElement,Ring), --
    replaces the variables of the coefficient ring of a differential form or a
    vector field with random values

rank(DiffAlgDistribution) -- rank of the given distribution
***********************************************************

Synopsis
========

  * Function: rank (Macaulay2Doc),
  * Usage:
        rank(L)
  * Inputs:
      * L, an instance of the type DiffAlgDistribution,
        list of vector fields, see dist,
  * Outputs:
      * an integer (Macaulay2Doc), the rank of the distribution
        generated by L

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

This routine returns the rank of the distribution L.

In this example we generate two random vector fields in three variables with
polynomial coefficients of degree 2. Then we compute the rank of some
distributions generated with them.

+-----------------------------------------------------------------------------+
|i1 : X = random newField(2,2,"a")                                            |
|                                                                             |
|        2             2                            2            2            |
|o1 = (2x  - 2x x  + 6x  - 3x x  + 6x x )ax  + (- 7x  + 5x x  - x  - 2x x  -  |
|        0     0 1     1     0 2     1 2   0        0     0 1    1     0 2    |
|     ------------------------------------------------------------------------|
|             2            2             2                     2              |
|     x x  + x )ax  + (- 3x  - 4x x  + 7x  + 2x x  - 7x x  - 3x )ax           |
|      1 2    2   1        0     0 1     1     0 2     1 2     2   2          |
|                                                                             |
|o1 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i2 : Y = random newField(2,2,"a")                                            |
|                                                                             |
|       2             2                    2           2     2                |
|o2 = (x  + 7x x  + 3x  + 2x x  + x x  + 8x )ax  + (- x  - 4x  - 7x x  - x x  |
|       0     0 1     1     0 2    1 2     2   0       0     1     0 2    1 2 |
|     ------------------------------------------------------------------------|
|        2          2             2            2                              |
|     - x )ax  + (3x  - 4x x  + 7x  - 5x x  + x )ax                           |
|        2   1      0     0 1     1     0 2    2   2                          |
|                                                                             |
|o2 : DiffAlgField                                                            |
+-----------------------------------------------------------------------------+
|i3 : rank dist {X,Y}                                                         |
|                                                                             |
|o3 = 2                                                                       |
+-----------------------------------------------------------------------------+
|i4 : rank dist {X,Y,X+Y,X-Y}                                                 |
|                                                                             |
|o4 = 2                                                                       |
+-----------------------------------------------------------------------------+
|i5 : rank dist {X,Y,X|Y}                                                     |
|                                                                             |
|o5 = 3                                                                       |
+-----------------------------------------------------------------------------+

See also
========

  * newField -- constructor of a vector field
  * radial -- defines the radial vector field
  * isInvolutive -- tests if a distribution is involutive

Ways to use this method:
========================

  * rank(DiffAlgDistribution) -- rank of
    the given distribution

ring(DiffAlgElement) -- ring of the differential form or vector field
*********************************************************************

Synopsis
========

  * Function: ring (Macaulay2Doc),
  * Usage:
        ring e
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or vector field
  * Outputs:
      * a ring (Macaulay2Doc), the ring of e

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

This function returns the ring where the given differential form of vector
field is defined.

+-----------------------------------------------------------------------------+
|i1 : w = newForm(2,1,2,"a")                                                  |
|                                                                             |
|         2               2                          2           2            |
|o1 = (a x  + a x x  + a x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + |
|       0 0    3 0 1    9 1    6 0 2    12 1 2    15 2   0     1 0    4 0 1   |
|     ------------------------------------------------------------------------|
|         2                          2           2                2           |
|     a  x  + a x x  + a  x x  + a  x )dx  + (a x  + a x x  + a  x  + a x x  +|
|      10 1    7 0 2    13 1 2    16 2   1     2 0    5 0 1    11 1    8 0 2  |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     a  x x  + a  x )dx                                                      |
|      14 1 2    17 2   2                                                     |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : ring w                                                                  |
|                                                                             |
|      QQ[i]                                                                  |
|o2 = ------[][a ..a  ][x ..x ][dx ..dx ]                                     |
|      2        0   17   0   2    0    2                                      |
|     i  + 1                                                                  |
|                                                                             |
|o2 : PolynomialRing, 3 skew commutative variables                            |
+-----------------------------------------------------------------------------+

Ways to use this method:
========================

  * ring(DiffAlgElement) -- ring of the
    differential form or vector field

singularIdeal -- ideal generated by the polynomial coefficients of a differential form or vector field
******************************************************************************************************

Synopsis
========

  * Usage:
        singularIdeal(e)
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or vector field
  * Outputs:
      * an ideal (Macaulay2Doc), the ideal generated by the
        polynomial coefficients of e

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

Given a differential form or vector field, this routine returns the ideal
generated by the polynomial coefficients of such element.

In this example we compute the singular locus of a differential form w.

+-----------------------------------------------------------------------------+
|i1 : w = random newForm(2,1,2,"a")                                           |
|                                                                             |
|        2             2                            2            2            |
|o1 = (2x  - 2x x  + 6x  - 3x x  + 6x x )dx  + (- 7x  + 5x x  - x  - 2x x  -  |
|        0     0 1     1     0 2     1 2   0        0     0 1    1     0 2    |
|     ------------------------------------------------------------------------|
|             2            2             2                     2              |
|     x x  + x )dx  + (- 3x  - 4x x  + 7x  + 2x x  - 7x x  - 3x )dx           |
|      1 2    2   1        0     0 1     1     0 2     1 2     2   2          |
|                                                                             |
|o1 : DiffAlgForm                                                             |
+-----------------------------------------------------------------------------+
|i2 : singularIdeal(w)                                                        |
|                                                                             |
|              2             2                      2            2            |
|o2 = ideal (2x  - 2x x  + 6x  - 3x x  + 6x x , - 7x  + 5x x  - x  - 2x x  -  |
|              0     0 1     1     0 2     1 2      0     0 1    1     0 2    |
|     ------------------------------------------------------------------------|
|             2      2             2                     2                    |
|     x x  + x , - 3x  - 4x x  + 7x  + 2x x  - 7x x  - 3x )                   |
|      1 2    2      0     0 1     1     0 2     1 2     2                    |
|                                                                             |
|               QQ[i]                                                         |
|o2 : Ideal of ------[][x ..x ]                                               |
|               2        0   2                                                |
|              i  + 1                                                         |
+-----------------------------------------------------------------------------+

This routine is useful to obtain the RingElement (Macaulay2Doc),
representing a 0-form

+----------------------------------------------------------------------------+
|i3 : w = random newForm(2,1,2,"a");                                         |
+----------------------------------------------------------------------------+
|i4 : r = radial 2;                                                          |
+----------------------------------------------------------------------------+
|i5 : F = r_w                                                                |
|                                                                            |
|      3     2         2     3     2                  2         2      2    3|
|o5 = x  + 6x x  + 3x x  - 4x  + 5x x  - 10x x x  + 6x x  + 3x x  - x x  + x |
|      0     0 1     0 1     1     0 2      0 1 2     1 2     0 2    1 2    2|
|                                                                            |
|o5 : DiffAlgForm                                                            |
+----------------------------------------------------------------------------+
|i6 : degree F                                                               |
|                                                                            |
|o6 = {2, 0, 3}                                                              |
|                                                                            |
|o6 : List                                                                   |
+----------------------------------------------------------------------------+
|i7 : (gens singularIdeal F)_0_0                                             |
|                                                                            |
|      3     2         2     3     2                  2         2      2    3|
|o7 = x  + 6x x  + 3x x  - 4x  + 5x x  - 10x x x  + 6x x  + 3x x  - x x  + x |
|      0     0 1     0 1     1     0 2      0 1 2     1 2     0 2    1 2    2|
|                                                                            |
|      QQ[i]                                                                 |
|o7 : ------[][x ..x ]                                                       |
|      2        0   2                                                        |
|     i  + 1                                                                 |
+----------------------------------------------------------------------------+

See also
========

  * moduliIdeal -- ideal generated by the coefficients of a
    differential form or vector field

Ways to use singularIdeal :
===========================

  * "singularIdeal(DiffAlgElement)"

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

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

substitute(DiffAlgElement,Ring) -- gets the RingElement of a differential form or vector field in a ring
********************************************************************************************************

Synopsis
========

  * Function: substitute (Macaulay2Doc),
  * Usage:
        sub(e,R)
  * Inputs:
      * e, an instance of the type DiffAlgElement, a
        differential form or vector field
      * R, a ring (Macaulay2Doc), the target ring
  * Outputs:
      * a ring element (Macaulay2Doc), an element of R
        representing e

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

By its nature, the package DiffAlg, is constantly changing the rings
where its differential forms and vector fields are defined. This function is
useful to get information of DiffAlg, out to some common polynomial
rings and work with the rest of Macaulay2 packages.

In this example we get the singular locus of a logarithmic form and compute its
Hilbert polynomial.

+---------------------------------------------------------------+
|i1 : w = random logarithmicForm(2,{1,1},"a",Projective => true)|
|                                                               |
|o1 = (35x  + 21x )dx  + (- 35x  + 7x )dx  + (- 21x  - 7x )dx   |
|         1      2   0         0     2   1         0     1   2  |
|                                                               |
|o1 : DiffAlgForm                                               |
+---------------------------------------------------------------+
|i2 : I = singularIdeal w                                       |
|                                                               |
|o2 = ideal (35x  + 21x , - 35x  + 7x , - 21x  - 7x )           |
|               1      2       0     2       0     1            |
|                                                               |
|               QQ[i]                                           |
|o2 : Ideal of ------[][x ..x ]                                 |
|               2        0   2                                  |
|              i  + 1                                           |
+---------------------------------------------------------------+
|i3 : S = QQ[gens ring I]                                       |
|                                                               |
|o3 = S                                                         |
|                                                               |
|o3 : PolynomialRing                                            |
+---------------------------------------------------------------+
|i4 : hilbertPolynomial (sub(I,S))                              |
|                                                               |
|o4 = P                                                         |
|      0                                                        |
|                                                               |
|o4 : ProjectiveHilbertPolynomial                               |
+---------------------------------------------------------------+

Ways to use this method:
========================

  * substitute(DiffAlgElement,Ring)
    -- gets the RingElement of a
    differential form or vector field in a ring