This is VersalDeformations.info, produced by Macaulay2, version 1.24.11

VersalDeformations -- calculating versal deformations and local Hilbert schemes
*******************************************************************************

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

This package provides tools for calculating tangent and obstruction spaces as
well as power series solutions for deformation problems involving isolated
singularities and projective schemes, as well as deformations of modules.

A basic description of the package's approach to deformation problems can be
found at the documentation node for versalDeformation.
For details and mathematical background see
  * [DG89] Vincenzo Di Gennaro, A note on deformations of coherent sheaves,
    Boll. Un. Mat. Ital. B (7) 3 1989.
  * [Si01] Arvid Siqveland, The Method of Computing Formal Moduli, Journal of
    Algebra 241, 2001.
  * [St94] Jan Stevens, Computing Versal Deformations, Experimental Mathematics
    Vol. 4 No. 2, 1994.

The numerous examples presented in the documentation nodes for
versalDeformation, and localHilbertScheme,
are classical deformation problems, considered in the
following articles:

  * [Al97] Klaus Altmann, The versal deformation of an isolated Gorenstein
    singularity, Inventiones Mathematicae Vol. 128 No. 3, 443-479 1997.
  * [CS10] Dustin Cartwright and Bernd Sturmfels, The Hilbert scheme of the
    diagonal in a product of projective spaces, International Mathematics
    Research Notices Vol. 2010 No. 9, 1741-1771.
  * [PS85] Ragni Piene and Michael Schlessinger, On the Hilbert scheme
    compactification of the space of twisted cubic curves, American Journal of
    Mathematics, Vol. 107 No. 4, 761-774, 1985.
  * [Pi74] Henry Pinkham, Deformations of algebraic varieties with G_m action,
    Asterisque 20, 1974.
  * [Si01] Arvid Siqveland, The Method of Computing Formal Moduli, Journal of
    Algebra 241, 2001.

The author thanks Jan Christophersen for helpful hints, especially regarding
the computation of $T^2$.

Author
======

  * Nathan Ilten (see http://www.sfu.ca/~nilten/ ) <nilten@sfu.ca>

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

Version 1.0 of this package was accepted for publication in volume 4 (see
https://msp.org/jsag/2012/4-1/ ) of The Journal of Software for Algebra and
Geometry: Macaulay2 (see https://msp.org/jsag/ ) on 2012-06-05, in the article
Versal deformations and local Hilbert schemes (see
https://msp.org/jsag/2012/4-1/p03.xhtml ) (DOI: 10.2140/jsag.2012.4.12 (see
https://doi.org/10.2140/jsag.2012.4.12 )). That version can be obtained from
the journal (see https://msp.org/jsag/2012/4-1/jsag-v4-n1-x03-code.zip ) or
from the Macaulay2 source code repository (see
https://github.com/Macaulay2/M2/blob/ff4ff53a9177b4ff3f8995bbb41b194b92a69ca2/
M2/Macaulay2/packages/VersalDeformations.m2 ).

Version
=======

This documentation describes version 3.0 of VersalDeformations.

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

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

Exports
=======

  * Functions and commands
      * checkComparisonTheorem -- checks if the
        Piene-Schlessinger or Di Dennaro comparison theorem holds
      * checkTangentSpace -- checks if dimension of
        space of sections of the normal bundle agrees with that calculated
        using normalMatrix
      * correctDeformation -- correct lifting to
        avoid obstructions at next order
      * correctionMatrix -- calculate how first order
        deformations perturb obstruction vector
      * cotangentCohomology1 -- calculate first
        cotangent cohomology
      * cotangentCohomology2 -- calculate second
        cotangent cohomology
      * extMatrix -- calculate obstruction space for modules
      * firstOrderDeformations -- use tangent
        space to create first order perturbations and find relations
      * liftDeformation -- lift a solution of the
        deformation equation to the next order
      * localHilbertScheme -- computes a power
        series representation of the local Hilbert scheme
      * normalMatrix -- calculate normal module
      * versalDeformation -- computes a power series
        representation of a versal deformation
  * Methods
      * "checkComparisonTheorem(Ideal)" -- see checkComparisonTheorem,
        -- checks if the Piene-Schlessinger or Di
        Dennaro comparison theorem holds
      * "checkComparisonTheorem(Matrix)" -- see checkComparisonTheorem,
        -- checks if the Piene-Schlessinger or Di
        Dennaro comparison theorem holds
      * "checkTangentSpace(Ideal)" -- see checkTangentSpace,
        -- checks if dimension of space of sections of the
        normal bundle agrees with that calculated using normalMatrix
      * "checkTangentSpace(Ideal,Matrix)" -- see checkTangentSpace,
        -- checks if dimension of space of sections of the
        normal bundle agrees with that calculated using normalMatrix
      * "checkTangentSpace(Matrix)" -- see checkTangentSpace,
        -- checks if dimension of space of sections of the
        normal bundle agrees with that calculated using normalMatrix
      * "checkTangentSpace(Matrix,Matrix)" -- see checkTangentSpace,
        -- checks if dimension of space of sections of the
        normal bundle agrees with that calculated using normalMatrix
      * "correctDeformation(List,List,List,List)" -- see
        correctDeformation, -- correct lifting to avoid
        obstructions at next order
      * "correctDeformation(Sequence,Matrix,List)" -- see
        correctDeformation, -- correct lifting to avoid
        obstructions at next order
      * "correctionMatrix(Matrix,Matrix)" -- see correctionMatrix,
        -- calculate how first order deformations perturb
        obstruction vector
      * "cotangentCohomology1(Ideal)" -- see cotangentCohomology1,
        -- calculate first cotangent cohomology
      * "cotangentCohomology1(InfiniteNumber,ZZ,Ideal)" -- see
        cotangentCohomology1, -- calculate first
        cotangent cohomology
      * "cotangentCohomology1(InfiniteNumber,ZZ,Matrix)" -- see
        cotangentCohomology1, -- calculate first
        cotangent cohomology
      * "cotangentCohomology1(List,Ideal)" -- see cotangentCohomology1,
        -- calculate first cotangent cohomology
      * "cotangentCohomology1(List,Matrix)" -- see cotangentCohomology1,
        -- calculate first cotangent cohomology
      * "cotangentCohomology1(Matrix)" -- see cotangentCohomology1,
        -- calculate first cotangent cohomology
      * "cotangentCohomology1(ZZ,Ideal)" -- see cotangentCohomology1,
        -- calculate first cotangent cohomology
      * "cotangentCohomology1(ZZ,InfiniteNumber,Ideal)" -- see
        cotangentCohomology1, -- calculate first
        cotangent cohomology
      * "cotangentCohomology1(ZZ,InfiniteNumber,Matrix)" -- see
        cotangentCohomology1, -- calculate first
        cotangent cohomology
      * "cotangentCohomology1(ZZ,Matrix)" -- see cotangentCohomology1,
        -- calculate first cotangent cohomology
      * "cotangentCohomology1(ZZ,ZZ,Ideal)" -- see cotangentCohomology1,
        -- calculate first cotangent cohomology
      * "cotangentCohomology1(ZZ,ZZ,Matrix)" -- see cotangentCohomology1,
        -- calculate first cotangent cohomology
      * "cotangentCohomology2(Ideal)" -- see cotangentCohomology2,
        -- calculate second cotangent cohomology
      * "cotangentCohomology2(InfiniteNumber,ZZ,Ideal)" -- see
        cotangentCohomology2, -- calculate second
        cotangent cohomology
      * "cotangentCohomology2(InfiniteNumber,ZZ,Matrix)" -- see
        cotangentCohomology2, -- calculate second
        cotangent cohomology
      * "cotangentCohomology2(List,Ideal)" -- see cotangentCohomology2,
        -- calculate second cotangent cohomology
      * "cotangentCohomology2(List,Matrix)" -- see cotangentCohomology2,
        -- calculate second cotangent cohomology
      * "cotangentCohomology2(Matrix)" -- see cotangentCohomology2,
        -- calculate second cotangent cohomology
      * "cotangentCohomology2(ZZ,Ideal)" -- see cotangentCohomology2,
        -- calculate second cotangent cohomology
      * "cotangentCohomology2(ZZ,InfiniteNumber,Ideal)" -- see
        cotangentCohomology2, -- calculate second
        cotangent cohomology
      * "cotangentCohomology2(ZZ,InfiniteNumber,Matrix)" -- see
        cotangentCohomology2, -- calculate second
        cotangent cohomology
      * "cotangentCohomology2(ZZ,Matrix)" -- see cotangentCohomology2,
        -- calculate second cotangent cohomology
      * "cotangentCohomology2(ZZ,ZZ,Ideal)" -- see cotangentCohomology2,
        -- calculate second cotangent cohomology
      * "cotangentCohomology2(ZZ,ZZ,Matrix)" -- see cotangentCohomology2,
        -- calculate second cotangent cohomology
      * "extMatrix(InfiniteNumber,ZZ,Matrix)" -- see extMatrix,
        -- calculate obstruction space for modules
      * "extMatrix(List,Matrix)" -- see extMatrix, --
        calculate obstruction space for modules
      * "extMatrix(Matrix)" -- see extMatrix, -- calculate
        obstruction space for modules
      * "extMatrix(ZZ,InfiniteNumber,Matrix)" -- see extMatrix,
        -- calculate obstruction space for modules
      * "extMatrix(ZZ,Matrix)" -- see extMatrix, -- calculate
        obstruction space for modules
      * "extMatrix(ZZ,ZZ,Matrix)" -- see extMatrix, --
        calculate obstruction space for modules
      * "firstOrderDeformations(Matrix,Matrix,Matrix)" -- see
        firstOrderDeformations, -- use tangent space to
        create first order perturbations and find relations
      * "liftDeformation(List,List,List,List)" -- see liftDeformation,
        -- lift a solution of the deformation equation to the
        next order
      * "localHilbertScheme(Matrix)" -- see localHilbertScheme,
        -- computes a power series representation of the
        local Hilbert scheme
      * "normalMatrix(Ideal)" -- see normalMatrix, --
        calculate normal module
      * "normalMatrix(InfiniteNumber,ZZ,Ideal)" -- see normalMatrix,
        -- calculate normal module
      * "normalMatrix(InfiniteNumber,ZZ,Matrix)" -- see normalMatrix,
        -- calculate normal module
      * "normalMatrix(List,Ideal)" -- see normalMatrix, --
        calculate normal module
      * "normalMatrix(List,Matrix)" -- see normalMatrix, --
        calculate normal module
      * "normalMatrix(Matrix)" -- see normalMatrix, --
        calculate normal module
      * "normalMatrix(ZZ,Ideal)" -- see normalMatrix, --
        calculate normal module
      * "normalMatrix(ZZ,InfiniteNumber,Ideal)" -- see normalMatrix,
        -- calculate normal module
      * "normalMatrix(ZZ,InfiniteNumber,Matrix)" -- see normalMatrix,
        -- calculate normal module
      * "normalMatrix(ZZ,Matrix)" -- see normalMatrix, --
        calculate normal module
      * "normalMatrix(ZZ,ZZ,Ideal)" -- see normalMatrix, --
        calculate normal module
      * "normalMatrix(ZZ,ZZ,Matrix)" -- see normalMatrix,
        -- calculate normal module
      * versalDeformation(List,List,List,List)
        -- continues
        calculation of  a versal deformation
      * versalDeformation(Matrix), --
        computes a power series representation of a versal deformation
      * versalDeformation(Matrix,Matrix,Matrix)
        -- computes a power
        series representation of a versal deformation
  * Symbols
      * CacheName -- determines hash table in which to cache
        solutions to the deformation equation
      * CorrectionMatrix -- determines the first order
        deformations used in correcting liftings
      * "ModuleDeformation" -- see cotangentCohomology1,
        -- calculate first cotangent cohomology
      * DefParam -- deformation parameter
      * DegreeBound -- determines the degree limit used to
        compute the tangent cone of obstruction equations
      * HighestOrder -- sets the order to which we compute
      * PolynomialCheck -- checks if power series
        solution terminates
      * SanityCheck -- checks if lifting solves deformation
        equation
      * SmartLift -- chooses lifting to avoid obstructions at
        next order
      * VersalDeformationResults -- hash table
        key for cached solutions to the deformation equation
  * Other things
      * CT -- cotangent cohomology

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

The object VersalDeformations, is a package (Macaulay2Doc).

CacheName -- determines hash table in which to cache solutions to the deformation equation
******************************************************************************************

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

CacheName is the name of an optional argument, whose value is either a
mutable hash table (Macaulay2Doc), or null (Macaulay2Doc).
After each stage of lifting, the methods
versalDeformation, and localHilbertScheme,
will store the solution to the deformation equation in
CacheName#VersalDeformationResults. If the value of CacheName is null (Macaulay2Doc),
as is the default, then the solution is stored in the hash
table described in the documentation of versalDeformation,
and localHilbertScheme.

Functions with optional argument named CacheName:
=================================================

  * "localHilbertScheme(...,CacheName=>...)" -- see localHilbertScheme,
    -- computes a power series representation of the local
    Hilbert scheme
  * "versalDeformation(...,CacheName=>...)" -- see
    versalDeformation(Matrix), -- computes a
    power series representation of a versal deformation

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

The object CacheName, is a symbol (Macaulay2Doc).

checkComparisonTheorem -- checks if the Piene-Schlessinger or Di Dennaro comparison theorem holds
*************************************************************************************************

Synopsis
========

  * Usage:
        B = checkComparisonTheorem(F)

  * Inputs:
      * F, a Matrix (Macaulay2Doc), or an Ideal (Macaulay2Doc),
  * Outputs:
      * B, a Boolean value (Macaulay2Doc),

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

 Let $S$ be a polynomial ring in $n$ variables, and $F$ be a matrix
representing a map of graded free modules over $S$. Let $E$ be the target of
$F$, $M$ the cokernel, and $K$ the image. Denote by $\bar E,\bar{M},\bar{K}$
the corresponding sheaves. We are interested in comparing the degree zero local
Quot functor parametrizing quotients of the module $E$ specializing to $M$,
with the local Quot functor parametrizing quotients of the locally free sheaf
$\bar E$ specializing to $\bar M$. In the special case that $E=S$, this means
that we are comparing degree zero embedded deformations of the affine cone of
$X=V(K)\subset \mathbb{P}^n$ with embedded deformations of $X$.

 Let $d_1,\ldots,d_m$ be the degrees of the generators of the source of $F$.
The comparison theorem of Piene and Schlessinger states that in the case $E=S$
and $K$ saturated, the above-mentioned functors are isomorphic if the natural
maps $M_{d_i}\to H^0(\mathbb{P}^n,\bar{M}(d_i))$ are isomorphisms. This is
equivalent to requiring that $H^1((\mathbb{P}^n,\bar{K}(d_i))=0$ for each $i$.
More generally, the theorem of Di Gennaro may be used. Consider arbitrary $E$
as above, and suppose that $K$ is a truncation of a saturated submodule. Again,
the above-mentioned functors are isomorphic if
$H^1((\mathbb{P}^n,\bar{K}(d_i))=0$ for each $i$.  See [PS85] and [DG89].

This method tests if the above hypotheses of Di Gennaro's comparison test are
fulfilled.  Inputing an ideal has the same effect as inputing gens F. In the
following example, the comparison theorem does not hold for the ideal I, but
does for the partial truncation J.

+-------------------------------------------------------------------------+
|i1 : S = QQ[a..d];                                                       |
+-------------------------------------------------------------------------+
|i2 : I = ideal(a,b^3*c,b^4);                                             |
|                                                                         |
|o2 : Ideal of S                                                          |
+-------------------------------------------------------------------------+
|i3 : J=ideal b^4+ideal (ambient basis(3,I))                              |
|                                                                         |
|             4   3   2    2    2      2                   2            2 |
|o3 = ideal (b , a , a b, a c, a d, a*b , a*b*c, a*b*d, a*c , a*c*d, a*d )|
|                                                                         |
|o3 : Ideal of S                                                          |
+-------------------------------------------------------------------------+
|i4 : checkComparisonTheorem I                                            |
|                                                                         |
|o4 = false                                                               |
+-------------------------------------------------------------------------+
|i5 : checkComparisonTheorem J                                            |
|                                                                         |
|o5 = true                                                                |
+-------------------------------------------------------------------------+

Ways to use checkComparisonTheorem:
===================================

  * "checkComparisonTheorem(Ideal)"
  * "checkComparisonTheorem(Matrix)"

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

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

checkTangentSpace -- checks if dimension of space of sections of the normal bundle agrees with that calculated using normalMatrix
*********************************************************************************************************************************

Synopsis
========

  * Usage:
        B = checkTangentSpace(F)
        B = checkTangentSpace(F,N)

  * Inputs:
      * F, a Matrix (Macaulay2Doc), or an Ideal (Macaulay2Doc),
      * N, a Matrix (Macaulay2Doc),
  * Outputs:
      * B, a Boolean value (Macaulay2Doc),

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

The matrix F must have a single row.  Inputing an ideal instead has the same
effect as inputing gens F. checkTangentSpace tests if the number of columns of
the matrix N is equal to the dimension of the space of global sections of the
normal bundle for the subscheme with ideal generated by F. If no matrix N is
supplied, normalMatrix(0,F) is used. In the following example, the desired
equality does not hold for the ideal I, but does for the partial truncation J.

+-------------------------------------------------------------------------+
|i1 : S = QQ[a..d];                                                       |
+-------------------------------------------------------------------------+
|i2 : I = ideal(a,b^3*c,b^4);                                             |
|                                                                         |
|o2 : Ideal of S                                                          |
+-------------------------------------------------------------------------+
|i3 : J=ideal b^4+ideal (ambient basis(3,I))                              |
|                                                                         |
|             4   3   2    2    2      2                   2            2 |
|o3 = ideal (b , a , a b, a c, a d, a*b , a*b*c, a*b*d, a*c , a*c*d, a*d )|
|                                                                         |
|o3 : Ideal of S                                                          |
+-------------------------------------------------------------------------+
|i4 : checkTangentSpace I                                                 |
|                                                                         |
|o4 = false                                                               |
+-------------------------------------------------------------------------+
|i5 : checkTangentSpace J                                                 |
|                                                                         |
|o5 = true                                                                |
+-------------------------------------------------------------------------+

Even if checkTangentSpace returns the value true, it may occur that the map
from the deformation space computed by localHilbertScheme,
to the local Hilbert scheme is not an isomorphism on
tangent spaces, since the rank of the map is not computed.

Ways to use checkTangentSpace:
==============================

  * "checkTangentSpace(Ideal)"
  * "checkTangentSpace(Ideal,Matrix)"
  * "checkTangentSpace(Matrix)"
  * "checkTangentSpace(Matrix,Matrix)"

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

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

correctDeformation -- correct lifting to avoid obstructions at next order
*************************************************************************

Synopsis
========

  * Usage:
        (F,R) = correctDeformation(f,r,g,c)
        (F,R) = correctDeformation(S,M,L)
  * Inputs:
      * f, a list (Macaulay2Doc),
      * r, a list (Macaulay2Doc),
      * g, a list (Macaulay2Doc),
      * c, a list (Macaulay2Doc),
      * (f,r,g,c), a sequence (Macaulay2Doc),
      * M, a matrix (Macaulay2Doc),
      * L, a list (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * SanityCheck => ..., default value true
      * Verbose, =>
        ..., default value 0, control the verbosity of output
  * Outputs:
      * F, a list (Macaulay2Doc), of matrices
      * R, a list (Macaulay2Doc), of matrices

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

Each element of the sequence (F,R) is a list of matrices in increasing powers
of the deformation parameter. (f,r,g,c) should be as in the output of
liftDeformation, and (M,L)should be as in the output of
correctionMatrix. If the latter are omitted, they are
replaced by (M,L)=correctionMatrix(f_1,r_1).

correctDeformation perturbs the last entries of f and r such that if possible,
the next invocation of liftDeformation, will introduce
no new terms in the obstruction equations.  If SanityCheck,
is set to true (Macaulay2Doc), as is the default, then the
algorithm will check that the corrected perturbation really does solve the
deformation equation, and terminate with an error if this is not the case.

For example, consider a degenerate twisted cubic curve, see [PS85],:

+-----------------------------------------------------------------------------+
|i1 : S=QQ[x,y,z,w];                                                          |
+-----------------------------------------------------------------------------+
|i2 : F0=matrix {{x*z,y*z,z^2,x^3}};                                          |
|                                                                             |
|             1      4                                                        |
|o2 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i3 : (f,r,g,c)=localHilbertScheme(F0,Verbose=>0,HighestOrder=>2,SmartLift=>  |
|Warning: calculation terminated since HighestOrder has been reached.         |
|-----------------------------------------------------------------------------|
|false);                                                                      |
+-----------------------------------------------------------------------------+
|i4 : (liftDeformation(f,r,g,c))_2                                            |
|                                                                             |
|o4 = {| t_1t_16             |, | 0                                     |}    |
|      | t_9t_16             |  | -2t_6t_10t_16+3t_10^2t_16-t_8t_11t_16 |     |
|      | -t_4t_16            |  | t_8t_10t_16+2t_3t_11t_16              |     |
|      | -2t_14t_16+t_15t_16 |  | 4t_10t_12t_16+2t_11t_13t_16-t_8t_16^2 |     |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : (F,R)=correctDeformation(f,r,g,c);                                      |
+-----------------------------------------------------------------------------+
|i6 : (liftDeformation(F,R,g,c))_2                                            |
|                                                                             |
|o6 = {| t_1t_16             |, 0}                                            |
|      | t_9t_16             |                                                |
|      | -t_4t_16            |                                                |
|      | -2t_14t_16+t_15t_16 |                                                |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

If the obstruction space is zero, this will generate an error.

Ways to use correctDeformation:
===============================

  * "correctDeformation(List,List,List,List)"
  * "correctDeformation(Sequence,Matrix,List)"

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

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

CorrectionMatrix -- determines the first order deformations used in correcting liftings
***************************************************************************************

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

CorrectionMatrix is the name of an optional argument, whose value is either a
string (Macaulay2Doc), with value auto or a sequence (Macaulay2Doc),
of the form output by correctionMatrix.
The second term in the sequence is a list of two matrices
which give some parameter-free first-order deformations and the corresponding
lifted relations, respectively. The first term in the sequence is a
matrix (Macaulay2Doc), which describes the action on liftings of
equations by the specified first-order deformations.  If set to auto, see
correctionMatrix, is used to calculate the relevant sequence.
The default value of CorrectionMatrix is auto.

Functions with optional argument named CorrectionMatrix:
========================================================

  * "localHilbertScheme(...,CorrectionMatrix=>...)" -- see
    localHilbertScheme, -- computes a power series
    representation of the local Hilbert scheme
  * "versalDeformation(...,CorrectionMatrix=>...)" -- see
    versalDeformation(Matrix), -- computes a
    power series representation of a versal deformation

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

The object CorrectionMatrix, is a symbol (Macaulay2Doc).

correctionMatrix -- calculate how first order deformations perturb obstruction vector
*************************************************************************************

Synopsis
========

  * Usage:
        (M,L) = correctionMatrix(F1,R1)
  * Inputs:
      * F1, a matrix (Macaulay2Doc),
      * R1, a matrix (Macaulay2Doc),
  * Outputs:
      * (M,L), a sequence (Macaulay2Doc),

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

F1 should be some first order perturbations of a matrix with R1 a lift of the
corresponding relations, as in the output of firstOrderDeformations.
M is a matrix representing the effect of these
perturbations one order higher, and L gives a parameter-free version of the
perturbations and lifted relations.

Ways to use correctionMatrix:
=============================

  * "correctionMatrix(Matrix,Matrix)"

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

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

cotangentCohomology1 -- calculate first cotangent cohomology
************************************************************

Synopsis
========

  * Usage:
        T1 = cotangentCohomology1(F)
        T1 = cotangentCohomology1(deg,F)
        T1 = cotangentCohomology1(lo,hi,F)
  * Inputs:
      * F, a Matrix (Macaulay2Doc), or an Ideal (Macaulay2Doc),
      * deg, a list (Macaulay2Doc), or integer (Macaulay2Doc),
      * lo, an integer (Macaulay2Doc), or -see infinity (Macaulay2Doc),
      * hi, an integer (Macaulay2Doc), or infinity (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * ModuleDeformation => ..., default value false
      * SourceRing => ..., default value null
  * Outputs:
      * T1, a matrix (Macaulay2Doc),

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

Inputing an ideal instead has the same effect as inputing gens F.  The output
T1 is a matrix over the same ring as F. If F has a single row and
ModuleDeformation is false, the output is a matrix whose columns form a basis
for (a graded piece of) the first cotangent cohomology module of S/I, where S
is the ring of F and I is ideal generated by the columns of F. If F has
multiple rows or ModuleDeformation is true, the output is a matrix whose
columns form a basis for (a graded piece of) the first extension module
Ext^1(coker F,coker F).

Selection of graded pieces is done in the same manner as with basis (Macaulay2Doc).
If the selected pieces are infinite dimensional, an error
occurs. The optional argument SourceRing (Macaulay2Doc), may
be used in the same fashion as with basis (Macaulay2Doc).

This is a method function (Macaulay2Doc), which may also
be accessed via the ScriptedFunctor (Macaulay2Doc),
CT.

For example, consider the cone over the rational normal curve of degree four,
see [Pi74],:

+--------------------------------------------------------------+
|i1 : S=QQ[x_0..x_4];                                          |
+--------------------------------------------------------------+
|i2 : I=minors(2,matrix {{x_0,x_1,x_2,x_3},{x_1,x_2,x_3,x_4}});|
|                                                              |
|o2 : Ideal of S                                               |
+--------------------------------------------------------------+
|i3 : T1=cotangentCohomology1(I)                               |
|                                                              |
|o3 = {-2} | x_1  x_0  0   0    |                              |
|     {-2} | 0    0    0   x_0  |                              |
|     {-2} | -x_3 -x_2 0   x_1  |                              |
|     {-2} | 0    0    x_2 0    |                              |
|     {-2} | -x_4 -x_3 x_3 0    |                              |
|     {-2} | 0    0    x_4 -x_3 |                              |
|                                                              |
|             6      4                                         |
|o3 : Matrix S  <-- S                                          |
+--------------------------------------------------------------+

The first cotangent cohomology module, and thus the tangent space of the versal
deformation, is four dimensional.

Ways to use cotangentCohomology1:
=================================

  * "cotangentCohomology1(Ideal)"
  * "cotangentCohomology1(InfiniteNumber,ZZ,Ideal)"
  * "cotangentCohomology1(InfiniteNumber,ZZ,Matrix)"
  * "cotangentCohomology1(List,Ideal)"
  * "cotangentCohomology1(List,Matrix)"
  * "cotangentCohomology1(Matrix)"
  * "cotangentCohomology1(ZZ,Ideal)"
  * "cotangentCohomology1(ZZ,InfiniteNumber,Ideal)"
  * "cotangentCohomology1(ZZ,InfiniteNumber,Matrix)"
  * "cotangentCohomology1(ZZ,Matrix)"
  * "cotangentCohomology1(ZZ,ZZ,Ideal)"
  * "cotangentCohomology1(ZZ,ZZ,Matrix)"

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

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

cotangentCohomology2 -- calculate second cotangent cohomology
*************************************************************

Synopsis
========

  * Usage:
        T2 = cotangentCohomology2(F)
        T2 = cotangentCohomology2(deg,F)
        T2 = cotangentCohomology2(lo,hi,F)
  * Inputs:
      * F, a Matrix (Macaulay2Doc), or an Ideal (Macaulay2Doc),
      * deg, a list (Macaulay2Doc), or integer (Macaulay2Doc),
      * lo, an integer (Macaulay2Doc), or -see infinity (Macaulay2Doc),
      * hi, an integer (Macaulay2Doc), or infinity (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * SourceRing => ..., default value null
  * Outputs:
      * T2, a matrix (Macaulay2Doc),

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

The matrix F must have a single row.  Inputing an ideal instead has the same
effect as inputing gens F.  The output T2 is a matrix over the same ring as F
whose columns form a basis for (a graded piece of) the second cotangent
cohomology module of S/I, where S is the ring of F and I is ideal generated by
the columns of F. Selection of graded pieces is done in the same manner as with
basis (Macaulay2Doc). If the selected pieces are infinite
dimensional, an error occurs. The optional argument SourceRing (Macaulay2Doc),
may be used in the same fashion as with basis (Macaulay2Doc).

This is a method function (Macaulay2Doc), which may also
be accessed via the ScriptedFunctor (Macaulay2Doc),
CT.

For example, consider the cone over the rational normal curve of degree four,
see [Pi74],:

+--------------------------------------------------------------+
|i1 : S=QQ[x_0..x_4];                                          |
+--------------------------------------------------------------+
|i2 : I=minors(2,matrix {{x_0,x_1,x_2,x_3},{x_1,x_2,x_3,x_4}});|
|                                                              |
|o2 : Ideal of S                                               |
+--------------------------------------------------------------+
|i3 : T2=cotangentCohomology2(I)                               |
|                                                              |
|o3 = {-3} | 0    0   0   |                                    |
|     {-3} | 0    0   0   |                                    |
|     {-3} | x_3  x_4 0   |                                    |
|     {-3} | x_2  x_3 0   |                                    |
|     {-3} | x_1  x_2 0   |                                    |
|     {-3} | -x_4 0   x_3 |                                    |
|     {-3} | 0    x_4 x_2 |                                    |
|     {-3} | 0    x_3 x_1 |                                    |
|                                                              |
|             8      3                                         |
|o3 : Matrix S  <-- S                                          |
+--------------------------------------------------------------+

The second cotangent cohomology module is three dimensional. Thus, the base
space of the versal deformation is cut out by (at most) three equations.

We also consider the graded example of a degenerate twisted cubic curve, see
[PS85],:

+---------------------------------+
|i4 : S=QQ[x,y,z,w];              |
+---------------------------------+
|i5 : F=matrix {{x*z,y*z,z^2,x^3}}|
|                                 |
|o5 = | xz yz z2 x3 |             |
|                                 |
|             1      4            |
|o5 : Matrix S  <-- S             |
+---------------------------------+
|i6 : T2=cotangentCohomology2(0,F)|
|                                 |
|o6 = {-3} | zw2 xw2 0   0   |    |
|     {-3} | 0   0   0   x2w |    |
|     {-3} | 0   0   zw2 0   |    |
|     {-4} | 0   0   0   0   |    |
|                                 |
|             4      4            |
|o6 : Matrix S  <-- S             |
+---------------------------------+

The degree zero component of the second cotangent cohomology module is four
dimensional. Thus the Hilbert scheme is (locally analytically) cut out by (at
most) four equations.

Ways to use cotangentCohomology2:
=================================

  * "cotangentCohomology2(Ideal)"
  * "cotangentCohomology2(InfiniteNumber,ZZ,Ideal)"
  * "cotangentCohomology2(InfiniteNumber,ZZ,Matrix)"
  * "cotangentCohomology2(List,Ideal)"
  * "cotangentCohomology2(List,Matrix)"
  * "cotangentCohomology2(Matrix)"
  * "cotangentCohomology2(ZZ,Ideal)"
  * "cotangentCohomology2(ZZ,InfiniteNumber,Ideal)"
  * "cotangentCohomology2(ZZ,InfiniteNumber,Matrix)"
  * "cotangentCohomology2(ZZ,Matrix)"
  * "cotangentCohomology2(ZZ,ZZ,Ideal)"
  * "cotangentCohomology2(ZZ,ZZ,Matrix)"

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

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

CT -- cotangent cohomology
**************************

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

CT is a scripted functor (Macaulay2Doc), providing an
interface for cotangent cohomology calculations. CT^1 is equivalent to
cotangentCohomology1, and CT^2 is equivalent to
cotangentCohomology2.

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

The object CT, is a scripted functor (Macaulay2Doc).

DefParam -- deformation parameter
*********************************

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

DefParam is the name of an optional argument. Its value is a symbol (Macaulay2Doc),
which specifies the name of the deformation parameter.
Its default value is determined by the loadtime configuration Option (Macaulay2Doc),
DefaultDefParam, which has default value t.

For example, we may use the deformation parameter s:

+-----------------------------------------------------------------------------+
|i1 : S=QQ[x_0..x_4];                                                         |
+-----------------------------------------------------------------------------+
|i2 : I=minors(2,matrix {{x_0,x_1,x_2,x_3},{x_1,x_2,x_3,x_4}});               |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : F0=gens I                                                               |
|                                                                             |
|o3 = | -x_1^2+x_0x_2 -x_1x_2+x_0x_3 -x_2^2+x_1x_3 -x_1x_3+x_0x_4             |
|     ------------------------------------------------------------------------|
|     -x_2x_3+x_1x_4 -x_3^2+x_2x_4 |                                          |
|                                                                             |
|             1      6                                                        |
|o3 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i4 : (F,R,G,C)=versalDeformation(F0,DefParam=>s);                            |
+-----------------------------------------------------------------------------+
|i5 : sum F                                                                   |
|                                                                             |
|o5 = | x_1s_1+x_0s_2-x_1^2+x_0x_2 -s_1s_3+x_0s_4-x_1x_2+x_0x_3               |
|     ------------------------------------------------------------------------|
|     -s_2s_3+s_3^2-s_1s_4-x_3s_1-x_2s_2+x_1s_4-x_2^2+x_1x_3                  |
|     ------------------------------------------------------------------------|
|     s_2s_3-s_3^2+x_2s_3-x_1x_3+x_0x_4 -x_4s_1-x_3s_2+x_3s_3-x_2x_3+x_1x_4   |
|     ------------------------------------------------------------------------|
|     x_4s_3-x_3s_4-x_3^2+x_2x_4 |                                            |
|                                                                             |
|                       1                6                                    |
|o5 : Matrix (S[s ..s ])  <-- (S[s ..s ])                                     |
|                1   4            1   4                                       |
+-----------------------------------------------------------------------------+

See also
========

  * firstOrderDeformations -- use tangent space
    to create first order perturbations and find relations
  * versalDeformation -- computes a power series
    representation of a versal deformation
  * localHilbertScheme -- computes a power series
    representation of the local Hilbert scheme

Functions with optional argument named DefParam:
================================================

  * "firstOrderDeformations(...,DefParam=>...)" -- see
    firstOrderDeformations, -- use tangent space to
    create first order perturbations and find relations
  * "localHilbertScheme(...,DefParam=>...)" -- see localHilbertScheme,
    -- computes a power series representation of the local
    Hilbert scheme
  * "versalDeformation(...,DefParam=>...)" -- see
    versalDeformation(Matrix), -- computes a
    power series representation of a versal deformation

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

The object DefParam, is a symbol (Macaulay2Doc).

DegreeBound -- determines the degree limit used to compute the tangent cone of obstruction equations
****************************************************************************************************

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

DegreeBound is the name of an optional argument. Its value is an integer (Macaulay2Doc),
or infinity. When lifting a deformation, the tangent cone for
the obstruction equations is computed using a local term order. The computation
uses the command gb (Macaulay2Doc), with the option DegreeLimit (Macaulay2Doc),
set to the order to which the deformation has been
lifted, plus DegreeBound. Default value is 0. If SanityCheck,
is set to true and results in an error being returned, this can be
corrected by re-running the computation using a higher value of DegreeBound.

Functions with optional argument named DegreeBound:
===================================================

  * "liftDeformation(...,DegreeBound=>...)"
  * "localHilbertScheme(...,DegreeBound=>...)"
  * "versalDeformation(...,DegreeBound=>...)"

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

The object DegreeBound, is a symbol (Macaulay2Doc).

extMatrix -- calculate obstruction space for modules
****************************************************

Synopsis
========

  * Usage:
        N = extMatrix(F)
        N = extMatrix(deg,F)
        N = extMatrix(lo,hi,F)
  * Inputs:
      * F, a Matrix (Macaulay2Doc),
      * deg, a list (Macaulay2Doc), or integer (Macaulay2Doc),
      * lo, an integer (Macaulay2Doc), or -see infinity (Macaulay2Doc),
      * hi, an integer (Macaulay2Doc), or infinity (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * SourceRing => ..., default value null
  * Outputs:
      * N, a matrix (Macaulay2Doc),

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

The output N is a matrix over the same ring as F whose columns form a basis for
(a graded piece of) the first extension module Ext^1(image F,coker F).
Selection of graded pieces is done in the same manner as with basis (Macaulay2Doc).
If the selected pieces are infinite dimensional, an error
occurs. The optional argument SourceRing (Macaulay2Doc), may
be used in the same fashing as with basis (Macaulay2Doc).

For example, consider the module M4 over an E6 singularity, see [Si01],:

+----------------------------------------------+
|i1 : S=QQ[x,y]/ideal {x^4+y^3};               |
+----------------------------------------------+
|i2 : F= matrix {{y,-x^2,0},{x,0,-y},{0,-y,-x}}|
|                                              |
|o2 = | y -x2 0  |                             |
|     | x 0   -y |                             |
|     | 0 -y  -x |                             |
|                                              |
|             3      3                         |
|o2 : Matrix S  <-- S                          |
+----------------------------------------------+
|i3 : N=extMatrix(F)                           |
|                                              |
|o3 = {-4} | 0 0 -x 0 0  -y |                  |
|     {-4} | 1 y 0  0 0  0  |                  |
|     {-4} | 0 0 0  1 y  0  |                  |
|     {-4} | 1 y 0  0 0  x  |                  |
|     {-4} | 0 0 0  1 y  0  |                  |
|     {-4} | 0 0 -1 0 0  0  |                  |
|     {-4} | 0 0 y  x xy 0  |                  |
|     {-4} | 0 0 0  0 0  -y |                  |
|     {-4} | 1 y 0  0 0  0  |                  |
|                                              |
|             9      6                         |
|o3 : Matrix S  <-- S                          |
+----------------------------------------------+

There are six obstructions to deforming this module.

Ways to use extMatrix:
======================

  * "extMatrix(InfiniteNumber,ZZ,Matrix)"
  * "extMatrix(List,Matrix)"
  * "extMatrix(Matrix)"
  * "extMatrix(ZZ,InfiniteNumber,Matrix)"
  * "extMatrix(ZZ,Matrix)"
  * "extMatrix(ZZ,ZZ,Matrix)"

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

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

firstOrderDeformations -- use tangent space to create first order perturbations and find relations
**************************************************************************************************

Synopsis
========

  * Usage:
        (F,R) = firstOrderDeformations(F0,R0,T1)
  * Inputs:
      * F0, a matrix (Macaulay2Doc),
      * R0, a matrix (Macaulay2Doc),
      * T1, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * DefParam => ..., default value "t"
      * SanityCheck => ..., default value true
  * Outputs:
      * F, a list (Macaulay2Doc), of matrices
      * R, a list (Macaulay2Doc), of matrices

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

F0, R0, and T1 should all be matrices over some common ring. R0 should be the
first syzygy matrix of F0 and T1 should have the same number rows as the
product of the number of rows and columns of F0.

F is a list of length two with F_0=F0 and F_1 the first order perturbations
corresponding to T1. R is a list of length two with R_0=R0 and R_1 such that
F_0*R_1+F_1*R_0==0. If SanityCheck, is set to true (Macaulay2Doc),
as is the default, then the algorithm will check that this
equation is satisfied, and terminate with an error if this is not the case.

The parameters used in the perturbations may be specified by the option
DefParam.

For example, consider the cone over the rational normal curve of degree four,
see [Pi74],:

+-----------------------------------------------------------------------------+
|i1 : S=QQ[x_0..x_4];                                                         |
+-----------------------------------------------------------------------------+
|i2 : I=minors(2,matrix {{x_0,x_1,x_2,x_3},{x_1,x_2,x_3,x_4}});               |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : F0=gens I                                                               |
|                                                                             |
|o3 = | -x_1^2+x_0x_2 -x_1x_2+x_0x_3 -x_2^2+x_1x_3 -x_1x_3+x_0x_4             |
|     ------------------------------------------------------------------------|
|     -x_2x_3+x_1x_4 -x_3^2+x_2x_4 |                                          |
|                                                                             |
|             1      6                                                        |
|o3 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i4 : T1=cotangentCohomology1(F0);                                            |
|                                                                             |
|             6      4                                                        |
|o4 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i5 : R0=gens ker F0;                                                         |
|                                                                             |
|             6      8                                                        |
|o5 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i6 : (F,R)=firstOrderDeformations(F0,R0,T1)                                  |
|                                                                             |
|o6 = ({| -x_1^2+x_0x_2 -x_1x_2+x_0x_3 -x_2^2+x_1x_3 -x_1x_3+x_0x_4           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|     ------------------------------------------------------------------------|
|     -x_2x_3+x_1x_4 -x_3^2+x_2x_4 |, | x_1t_1+x_0t_2 x_0t_4                  |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|     ------------------------------------------------------------------------|
|     -x_3t_1-x_2t_2+x_1t_4 x_2t_3 -x_4t_1-x_3t_2+x_3t_3 x_4t_3-x_3t_4 |},    |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|     ------------------------------------------------------------------------|
|     {{2} | x_3  x_2  0    x_4  x_3  0    0    0    |, {2} | t_4  0   0      |
|      {2} | -x_2 -x_1 x_4  0    0    0    x_4  x_3  |  {2} | -t_2 t_1 0      |
|      {2} | x_1  x_0  -x_3 0    0    x_4  0    0    |  {2} | 0    0   0      |
|      {2} | 0    0    -x_3 -x_2 -x_1 0    -x_3 -x_2 |  {2} | 0    0   -t_4   |
|      {2} | 0    0    x_2  x_1  x_0  -x_3 0    0    |  {2} | 0    0   0      |
|      {2} | 0    0    0    0    0    x_2  x_1  x_0  |  {2} | 0    0   t_1    |
|     ------------------------------------------------------------------------|
|     0    0    0       0    0    |})                                         |
|     0    -t_3 0       0    0    |                                           |
|     -t_3 0    0       0    -t_3 |                                           |
|     -t_2 t_1  0       -t_4 -t_3 |                                           |
|     0    0    -t_4    -t_3 0    |                                           |
|     0    0    t_2-t_3 0    0    |                                           |
|                                                                             |
|o6 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Ways to use firstOrderDeformations:
===================================

  * "firstOrderDeformations(Matrix,Matrix,Matrix)"

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

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

HighestOrder -- sets the order to which we compute
**************************************************

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

HighestOrder is the name of an optional argument. Its value is an
integer (Macaulay2Doc), which gives an upper bound on to what order a
solution of the deformation equation is lifted. Default value is 20.

Functions with optional argument named HighestOrder:
====================================================

  * "localHilbertScheme(...,HighestOrder=>...)" -- see
    localHilbertScheme, -- computes a power series
    representation of the local Hilbert scheme
  * "versalDeformation(...,HighestOrder=>...)" -- see
    versalDeformation(Matrix), -- computes a
    power series representation of a versal deformation

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

The object HighestOrder, is a symbol (Macaulay2Doc).

liftDeformation -- lift a solution of the deformation equation to the next order
********************************************************************************

Synopsis
========

  * Usage:
        (F,R,G,C) = liftDeformation(f,r,g,c)
  * Inputs:
      * f, a list (Macaulay2Doc),
      * r, a list (Macaulay2Doc),
      * g, a list (Macaulay2Doc),
      * c, a list (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * DegreeBound, => ..., default value 0, determines the
        degree limit used to compute the tangent cone of obstruction equations
      * SanityCheck => ..., default value true
      * Verbose, =>
        ..., default value 0, control the verbosity of output
  * Outputs:
      * F, a list (Macaulay2Doc), of matrices
      * R, a list (Macaulay2Doc), of matrices
      * G, a list (Macaulay2Doc), of matrices
      * C, a list (Macaulay2Doc), of matrices

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

Each element of the sequence (f,r,g,c) is a list of matrices in increasing
powers of some deformation parameter. Their sums satisfy the deformation
equation transpose flatten ( (sum f)*(sum r))+(sum c)*sum(g)==0 up to powers of
the deformation parameter equal to the length of f.

Each element of the output sequence (F,R,G,C) is a list of matrices in
increasing powers of the deformation parameter. The first three matrices of the
sequence are gotten from (f,r,g) by appending one matrix to each list in the
sequence, and furthermore the columns of C_0 are multiples of those of c_0. The
other matrices are chosen to satisfy the deformation equation transpose ((sum
F)*(sum R))+(sum C)*(sum G)==0 up to powers of the deformation parameter equal
to the length of F, provided that there is such a solution. If
SanityCheck, is set to true (Macaulay2Doc), as is the
default, then the algorithm will check that the lifted solution really does
solve the deformation equation, and terminate with an error if this is not the
case.

For example, consider the cone over the rational normal curve of degree four,
see [Pi74],:

+-----------------------------------------------------------------------------+
|i1 : S=QQ[x_0..x_4];                                                         |
+-----------------------------------------------------------------------------+
|i2 : I=minors(2,matrix {{x_0,x_1,x_2,x_3},{x_1,x_2,x_3,x_4}});               |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : F0=gens I                                                               |
|                                                                             |
|o3 = | -x_1^2+x_0x_2 -x_1x_2+x_0x_3 -x_2^2+x_1x_3 -x_1x_3+x_0x_4             |
|     ------------------------------------------------------------------------|
|     -x_2x_3+x_1x_4 -x_3^2+x_2x_4 |                                          |
|                                                                             |
|             1      6                                                        |
|o3 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i4 : T1=cotangentCohomology1(F0);                                            |
|                                                                             |
|             6      4                                                        |
|o4 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i5 : R0=gens ker F0;                                                         |
|                                                                             |
|             6      8                                                        |
|o5 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i6 : (f,r)=firstOrderDeformations(F0,R0,T1);                                 |
+-----------------------------------------------------------------------------+

We now lift the first order deformations to second order:

+-----------------------------------------------------------------------------+
|i7 : A:=(ring f_0)/(image f_0);                                              |
+-----------------------------------------------------------------------------+
|i8 : T2=cotangentCohomology2(F0);                                            |
|                                                                             |
|             8      3                                                        |
|o8 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i9 : NT2:=lift(sub(T2,A)%sub(transpose r_0,A),ring f_0);                     |
|                                                                             |
|                       8                3                                    |
|o9 : Matrix (S[t ..t ])  <-- (S[t ..t ])                                     |
|                1   4            1   4                                       |
+-----------------------------------------------------------------------------+
|i10 : c={NT2};                                                               |
+-----------------------------------------------------------------------------+
|i11 : g={};                                                                  |
+-----------------------------------------------------------------------------+
|i12 : (F,R,G,C)=liftDeformation(f,r,g,c);                                    |
+-----------------------------------------------------------------------------+
|i13 : T=ring first F;                                                        |
+-----------------------------------------------------------------------------+
|i14 : sum F -- equations for family                                          |
|                                                                             |
|o14 = | x_1t_1+x_0t_2-x_1^2+x_0x_2 -t_1t_3+x_0t_4-x_1x_2+x_0x_3              |
|      -----------------------------------------------------------------------|
|      -t_2t_3+t_3^2-t_1t_4-x_3t_1-x_2t_2+x_1t_4-x_2^2+x_1x_3                 |
|      -----------------------------------------------------------------------|
|      t_2t_3-t_3^2+x_2t_3-x_1x_3+x_0x_4 -x_4t_1-x_3t_2+x_3t_3-x_2x_3+x_1x_4  |
|      -----------------------------------------------------------------------|
|      x_4t_3-x_3t_4-x_3^2+x_2x_4 |                                           |
|                                                                             |
|              1      6                                                       |
|o14 : Matrix T  <-- T                                                        |
+-----------------------------------------------------------------------------+
|i15 : sum G -- base equations                                                |
|                                                                             |
|o15 = | t_2t_3-t_3^2 |                                                       |
|      | -t_1t_3      |                                                       |
|      | t_3t_4       |                                                       |
|                                                                             |
|              3      1                                                       |
|o15 : Matrix T  <-- T                                                        |
+-----------------------------------------------------------------------------+

Ways to use liftDeformation:
============================

  * "liftDeformation(List,List,List,List)"

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

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

liftDeformation(...,Verbose=>...) -- control the verbosity of output
********************************************************************

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

Verbose is the name of an optional argument. Its value is an integer, which
specifies how verbose output of the above commands should be. Default value is
0 which gives the tersest possible output. Highest verbosity is attained with
the value 4.

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

  * Default value: 0
  * Function: liftDeformation, -- lift a solution of the
    deformation equation to the next order
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

Functions with optional argument named Verbose:
===============================================

  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * "correctDeformation(...,Verbose=>...)"
  * liftDeformation(...,Verbose=>...)
    -- control the
    verbosity of output
  * "localHilbertScheme(...,Verbose=>...)"
  * "versalDeformation(...,Verbose=>...)"
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree

localHilbertScheme -- computes a power series representation of the local Hilbert scheme
****************************************************************************************

Synopsis
========

  * Usage:
        (F,R,G,C) = localHilbertScheme(F0)
  * Inputs:
      * F0, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CacheName => ..., default value null
      * CorrectionMatrix => ..., default value "auto"
      * DefParam => ..., default value "t"
      * DegreeBound, => ..., default value 0, determines the
        degree limit used to compute the tangent cone of obstruction equations
      * HighestOrder => ..., default value 20
      * PolynomialCheck => ..., default value true
      * SanityCheck => ..., default value true
      * SmartLift => ..., default value true
      * Verbose, =>
        ..., default value 0, control the verbosity of output
  * Outputs:
      * F, a list (Macaulay2Doc), of matrices
      * R, a list (Macaulay2Doc), of matrices
      * G, a list (Macaulay2Doc), of matrices
      * C, a list (Macaulay2Doc), of matrices

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

F0 should  be a matrix with homogeneous entries over some polynomial ring with
one row.

Each element of the sequence (F,R,G,C) is a list of matrices in increasing
powers of the deformation parameter specified by DefParam.
Their sums satisfy the deformation equation transpose ((sum F)*(sum R))+(sum
C)*(sum G)==0 up to powers of the deformation parameter equal to the length of
F. Furthermore, F_0=F0, R_0=gens ker F0, C_0=T^2(0,F_0) and F_1 consists of
first order perturbations corresponding to normalMatrix(0,F0). Thus, F and G
represent a universal family and local analytic equations for the Hilbert
scheme.

Several options are available to control the termination of the calculation.
The calculation will terminate at the very latest after reaching order equal to
the option HighestOrder, which has default value 20. If
this order is reached, a warning message is generated. If
PolynomialCheck, is set to true (Macaulay2Doc), as
is the default, then the algorithm will check if the present solution lifts to
infinite order and terminate if this is the case. If SanityCheck,
is set to true (Macaulay2Doc), as is the default, then
the algorithm will check that the present solution really does solve the
deformation equation, and terminate with an error if this is not the case.

The option Verbose (Macaulay2Doc), may be used to control the
verbosity of the output. Its value should be an integer, with higher values
corresponding to more verbose output. Default value is 0.

The option SmartLift, is also available, which controls
whether the algorithm spends extra time trying to find liftings which introduce
no new obstructions at the next highest order. By default, this option is
enabled. The option CorrectionMatrix, may be used to
control which liftings are considered.

After each step of lifting, the solution (F,R,G,C) to the deformation equation
is cached. By default, it is stored in F0.cache#VersalDeformationResults but
may stored elsewhere by setting the option CacheName, to
something other than null (Macaulay2Doc).

For example, consider a degenerate twisted cubic curve, see [PS85],:

+----------------------------------------------------------+
|i1 : S=QQ[x,y,z,w];                                       |
+----------------------------------------------------------+
|i2 : F0=matrix {{x*z,y*z,z^2,x^3}}                        |
|                                                          |
|o2 = | xz yz z2 x3 |                                      |
|                                                          |
|             1      4                                     |
|o2 : Matrix S  <-- S                                      |
+----------------------------------------------------------+
|i3 : (F,R,G,C)=localHilbertScheme(F0,Verbose=>2);         |
|Calculating first order deformations and obstruction space|
|Calculating first order relations                         |
|Calculating standard expressions for obstructions         |
|Starting lifting                                          |
|Order 2                                                   |
|Order 3                                                   |
|Order 4                                                   |
|Order 5                                                   |
|Order 6                                                   |
|Order 7                                                   |
|Solution is polynomial                                    |
+----------------------------------------------------------+

Local equations for the Hilbert scheme are thus given by

+----------------------------+
|i4 : T=ring first G;        |
+----------------------------+
|i5 : sum G                  |
|                            |
|o5 = | t_1t_16             ||
|     | t_9t_16             ||
|     | -t_4t_16            ||
|     | -2t_14t_16+t_15t_16 ||
|                            |
|             4      1       |
|o5 : Matrix T  <-- T        |
+----------------------------+

Caveat
======

The output may not be the local Hilbert scheme if standard comparison theorems
do not hold for the ideal generated by FO. This may be tested using
checkComparisonTheorem, or checkTangentSpace.

Ways to use localHilbertScheme:
===============================

  * "localHilbertScheme(Matrix)"

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

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

normalMatrix -- calculate normal module
***************************************

Synopsis
========

  * Usage:
        N = normalMatrix(F)
        N = normalMatrix(deg,F)
        N = normalMatrix(lo,hi,F)
  * Inputs:
      * F, a Matrix (Macaulay2Doc), or an Ideal (Macaulay2Doc),
      * deg, a list (Macaulay2Doc), or integer (Macaulay2Doc),
      * lo, an integer (Macaulay2Doc), or -see infinity (Macaulay2Doc),
      * hi, an integer (Macaulay2Doc), or infinity (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * SourceRing => ..., default value null
  * Outputs:
      * N, a matrix (Macaulay2Doc),

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

Inputing an ideal instead has the same effect as inputing gens F.  The output N
is a matrix over the same ring as F whose columns form a basis for (a graded
piece of) the normal module Hom(image F,coker F). Selection of graded pieces is
done in the same manner as with basis (Macaulay2Doc). If the
selected pieces are infinite dimensional, an error occurs. The optional
argument SourceRing (Macaulay2Doc), may be used in the same
fashing as with basis (Macaulay2Doc).

For example, consider a degenerate twisted cubic curve, see [PS85],:

+---------------------------------------------------------------------+
|i1 : S=QQ[x,y,z,w];                                                  |
+---------------------------------------------------------------------+
|i2 : F=matrix {{x*z,y*z,z^2,x^3}}                                    |
|                                                                     |
|o2 = | xz yz z2 x3 |                                                 |
|                                                                     |
|             1      4                                                |
|o2 : Matrix S  <-- S                                                 |
+---------------------------------------------------------------------+
|i3 : N=normalMatrix(0,F)                                             |
|                                                                     |
|o3 = {-2} | 0   0  0   0   0   0   0   0   0   zw 0  x2 xy xw 0  0  ||
|     {-2} | 0   0  0   0   0   0   0   0   0   0  zw xy y2 yw 0  x2 ||
|     {-2} | 0   0  0   0   0   0   0   0   0   0  0  0  0  0  zw 0  ||
|     {-3} | zw2 y3 y2w yw2 x2y x2w xy2 xyw xw2 0  0  0  0  0  0  0  ||
|                                                                     |
|             4      16                                               |
|o3 : Matrix S  <-- S                                                 |
+---------------------------------------------------------------------+

The degree zero component of the normal module, and thus the tangent space of
the Hilbert scheme, is sixteen dimensional.

Ways to use normalMatrix:
=========================

  * "normalMatrix(Ideal)"
  * "normalMatrix(InfiniteNumber,ZZ,Ideal)"
  * "normalMatrix(InfiniteNumber,ZZ,Matrix)"
  * "normalMatrix(List,Ideal)"
  * "normalMatrix(List,Matrix)"
  * "normalMatrix(Matrix)"
  * "normalMatrix(ZZ,Ideal)"
  * "normalMatrix(ZZ,InfiniteNumber,Ideal)"
  * "normalMatrix(ZZ,InfiniteNumber,Matrix)"
  * "normalMatrix(ZZ,Matrix)"
  * "normalMatrix(ZZ,ZZ,Ideal)"
  * "normalMatrix(ZZ,ZZ,Matrix)"

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

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

PolynomialCheck -- checks if power series solution terminates
*************************************************************

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

PolynomialCheck is the name of an optional argument. Its value is a
Boolean value (Macaulay2Doc), which determines whether or not to check
if a solution of the deformation equation lifts trivially to arbitrary order.
Default value is true (Macaulay2Doc),

Functions with optional argument named PolynomialCheck:
=======================================================

  * "localHilbertScheme(...,PolynomialCheck=>...)" -- see
    localHilbertScheme, -- computes a power series
    representation of the local Hilbert scheme
  * "versalDeformation(...,PolynomialCheck=>...)" -- see
    versalDeformation(Matrix), -- computes a
    power series representation of a versal deformation

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

The object PolynomialCheck, is a symbol (Macaulay2Doc).

SanityCheck -- checks if lifting solves deformation equation
************************************************************

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

SanityCheck is the name of an optional argument. Its value is a Boolean value (Macaulay2Doc),
which determines whether or not to check if a
supposed solution of the deformation equation actually satisfies it. Default
value is true (Macaulay2Doc).

Functions with optional argument named SanityCheck:
===================================================

  * "correctDeformation(...,SanityCheck=>...)" -- see correctDeformation,
    -- correct lifting to avoid obstructions at next order
  * "firstOrderDeformations(...,SanityCheck=>...)" -- see
    firstOrderDeformations, -- use tangent space to
    create first order perturbations and find relations
  * "liftDeformation(...,SanityCheck=>...)" -- see liftDeformation,
    -- lift a solution of the deformation equation to the next
    order
  * "localHilbertScheme(...,SanityCheck=>...)" -- see localHilbertScheme,
    -- computes a power series representation of the local
    Hilbert scheme
  * "versalDeformation(...,SanityCheck=>...)" -- see
    versalDeformation(Matrix), -- computes a
    power series representation of a versal deformation

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

The object SanityCheck, is a symbol (Macaulay2Doc).

SmartLift -- chooses lifting to avoid obstructions at next order
****************************************************************

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

SmartLift is the name of an optional argument whose value is a Boolean value (Macaulay2Doc).
If set to true (Macaulay2Doc),
versalDeformation, or localHilbertScheme,
will utilize the function correctDeformation,
in order to choose liftings of the deformation equation at
each step which, if possible, introduce no higher order terms to the
obstruction equations. This may increase the time of calculation, but will
hopefully result in nicer equations for the base space. Default value is
true (Macaulay2Doc),

For example, consider a degenerate twisted cubic curve, see[PS85],:

+----------------------------------+
|i1 : S=QQ[x,y,z,w];               |
+----------------------------------+
|i2 : F0=matrix {{x*z,y*z,z^2,x^3}}|
|                                  |
|o2 = | xz yz z2 x3 |              |
|                                  |
|             1      4             |
|o2 : Matrix S  <-- S              |
+----------------------------------+

With the default setting SmartLift=>true we get very nice equations for the
base space:

+-----------------------------------------------------+
|i3 : time (F,R,G,C)=localHilbertScheme(F0);          |
| -- used 0.811306s (cpu); 0.593121s (thread); 0s (gc)|
+-----------------------------------------------------+
|i4 : T=ring first G;                                 |
+-----------------------------------------------------+
|i5 : sum G                                           |
|                                                     |
|o5 = | t_1t_16             |                         |
|     | t_9t_16             |                         |
|     | -t_4t_16            |                         |
|     | -2t_14t_16+t_15t_16 |                         |
|                                                     |
|             4      1                                |
|o5 : Matrix T  <-- T                                 |
+-----------------------------------------------------+

With the setting SmartLift=>false the calculation is faster, but the equations
are no longer homogeneous:

+-----------------------------------------------------------------------------+
|i6 : time (F,R,G,C)=localHilbertScheme(F0,SmartLift=>false);                 |
| -- used 0.526479s (cpu); 0.380361s (thread); 0s (gc)                        |
+-----------------------------------------------------------------------------+
|i7 : sum G                                                                   |
|                                                                             |
|o7 = | t_1t_16                                                               |
|     | 2t_5t_10t_11t_16+t_7t_11^2t_16-2t_6t_10t_16+3t_10^2t_16-t_8t_11t_16+  |
|     | -t_5t_10^2t_16-2t_7t_10t_11t_16-3t_2t_11^2t_16+t_8t_10t_16+2t_3t_11t  |
|     | 2t_5t_10t_16^2+2t_7t_11t_16^2+4t_10t_12t_16+2t_11t_13t_16-t_8t_16^2-  |
|     ------------------------------------------------------------------------|
|                        |                                                    |
|     t_9t_16            |                                                    |
|     _16-t_4t_16        |                                                    |
|     2t_14t_16+t_15t_16 |                                                    |
|                                                                             |
|                        4                 1                                  |
|o7 : Matrix (S[t ..t  ])  <-- (S[t ..t  ])                                   |
|                1   16            1   16                                     |
+-----------------------------------------------------------------------------+

Functions with optional argument named SmartLift:
=================================================

  * "localHilbertScheme(...,SmartLift=>...)" -- see localHilbertScheme,
    -- computes a power series representation of the local
    Hilbert scheme
  * "versalDeformation(...,SmartLift=>...)" -- see
    versalDeformation(Matrix), -- computes a
    power series representation of a versal deformation

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

The object SmartLift, is a symbol (Macaulay2Doc).

versalDeformation -- computes a power series representation of a versal deformation
***********************************************************************************

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

Here we provide an overview of our approach to solving deformation problems.
For details on using the command versalDeformation, please see the
documentation links below. The most basic use of the method is via
versalDeformation(Matrix), which computes the
versal deformation of an isolated singularity. We give a brief overview of this
case:

First we fix some notation. Let $S$ be a polynomial ring over some field $k$,
and let $I$ be an ideal of $S$ defining a scheme $X=$Spec $S/I$ with isolated
singularities. Consider a free resolution of $S/I$: $$ \ldots \to  S^l \to S^m
\to S \to S/I\to 0 $$ with differentials $R^0:S^l\to S^m$ and $F^0:S^m\to S$.
Let $\phi_i\in$Hom$(S^m/ $Im$ R^0,S)$ for $i=1,\ldots,n$ represent a basis of
$T^1(S/I)\cong$Hom$(S^m/ $Im$ R^0,S)/ $Jac$ F^0$. We introduce deformation
parameters $t_1,\ldots,t_n$ with the ring $T=S[t_1,\ldots,t_n]$ and consider
the map $F^1: T^m\to T$ defined as $F^1=F^0+\sum t_i\phi_i.$ Let $a$ be the
ideal generated by $t_1,\ldots,t_n$. It follows that there is a map $R^1:
T^l\to T^m$ with $R^1= R^0$ mod $a$ satisfying the first order deformation
equation $F^1R^1= 0$ mod $a^2$.

Our goal is to lift this equation to higher order, that is, for each $i>0$, to
find $F^i: T^m\to T$ with $F^i=F^{i-1}$ mod $a^{i}$ and $R^i: T^l\to T^m$ with
$R^i= R^{i-1}$ mod $a^i$ satisfying $F^iR^i= 0$ mod $a^{i+1}$. In general,
there are obstructions to doing this, governed by the $d$-dimensional $k$
vector space $T^2(S/I)$. Thus, we instead aim to solve $$
(F^iR^i)^{tr}+C^{i-2}G^{i-2}= 0 $$ mod $a^{i+1}$. Here, $G^{i-2}: k[t]\to
k[t]^d$ and $C^{i-2}: T^d\to T^l$ are congruent modulo $a^i$ to $G^{i-3}$ and
$C^{i-3}$, respectively. Furthermore, we require that $G^i$ and $C^i$ vanish
for $i<0$, and $C^0$ is of the form $V D$, where $V\in$Hom$(S^d,S^l)$ gives
representatives of a basis for $T^2(S/I)$ and $D\in$Hom$(S^d,S^d)$ is a
diagonal matrix. The $G^i$ now give equations for the miniversal base space of
$X$.

Our implementation solves the above equation step by step. Given a solution
$(F^i,R^i,G^{i-2},C^{i-2})$ modulo $a^{i+1}$, the package uses Macaulay2's
built in matrix quotients to first solve for $F^{i+1}$ and $G^{i-1}$ (by
working over the ring $T/I+$ Im $(G^{i-2})^{tr} +a^{i+2}$) and then solve for
$R^{i+1}$ and $C^{i-1}$. For the actual computation, we avoid working over
quotient rings involving high powers of $a$ by representing the
$(F^i,R^i,G^{i-2},C^{i-2})$ as lists of matrices which keep track of the orders
of the $t_j$ involved.

Our approach to deformations of modules is similar. For a ring $S$, let $M$ be
an $S$-module. Consider a free resolution of $M$: $$ \ldots \to  S^l \to S^m
\to S^r \to M\to 0 $$ with differentials $R^0:S^l\to S^m$ and $F^0:S^m\to S^r$.
Similar to above, we iteratively solve a deformation equation $$ (transpose
flatten (F^iR^i))+C^{i-2}G^{i-2}= 0 $$ where $T^1(S/I)$ and $T^2(S/I)$ from
above have been replaced by appropriate tangent and obstruction spaces.

See  versalDeformation(Matrix,Matrix,Matrix),
for an example.

Ways to use versalDeformation:
==============================

  * versalDeformation(List,List,List,List)
    -- continues calculation
    of  a versal deformation
  * versalDeformation(Matrix) -- computes
    a power series representation of a versal deformation
  * versalDeformation(Matrix,Matrix,Matrix)
    -- computes a power series
    representation of a versal deformation

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

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

versalDeformation(List,List,List,List) -- continues calculation of  a versal deformation
****************************************************************************************

Synopsis
========

  * Function: versalDeformation,
  * Usage:
        (F,R,G,C) = versalDeformation(F0)
        (F,R,G,C) = versalDeformation(F0,T1,T2)
  * Inputs:
      * f, a list (Macaulay2Doc),
      * r, a list (Macaulay2Doc),
      * g, a list (Macaulay2Doc),
      * c, a list (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CacheName, => ..., default value
        null, computes a power series representation of a versal deformation
      * CorrectionMatrix, => ..., default
        value "auto", computes a power series representation of a versal
        deformation
      * DefParam, => ..., default value
        "t", computes a power series representation of a versal deformation
      * DegreeBound, => ..., default value 0, determines the
        degree limit used to compute the tangent cone of obstruction equations
      * HighestOrder, => ..., default
        value 20, computes a power series representation of a versal
        deformation
      * PolynomialCheck, => ..., default
        value true, computes a power series representation of a versal
        deformation
      * SanityCheck, => ..., default value
        true, computes a power series representation of a versal deformation
      * SmartLift, => ..., default value
        true, computes a power series representation of a versal deformation
      * Verbose, =>
        ..., default value 0, control the verbosity of output
  * Outputs:
      * F, a list (Macaulay2Doc), of matrices
      * R, a list (Macaulay2Doc), of matrices
      * G, a list (Macaulay2Doc), of matrices
      * C, a list (Macaulay2Doc), of matrices

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

Each element of the sequence (F,R,G,C) is a list of matrices in increasing
powers of the deformation parameter. The input (f,r,g,c) should be a valid
solution to the deformation equation output in the form done by
versalDeformation(Matrix,Matrix,Matrix).
This function continues
lifting this solution to higher order. All options described for
versalDeformation(Matrix), may be used to the
same effect.

After each step of lifting, the solution (F,R,G,C) to the deformation equation
is cached. By default, it is stored in (f_0).cache#VersalDeformationResults but
may stored elsewhere by setting the option CacheName, to
something other than null (Macaulay2Doc).

This function is especially useful for finding one-parameter families when the
versal family is too complicated to calculate.

We may consider the example of the versal deformation of a degree 12 toric Fano
threefold:

+-----------------------------------------------------------------------------+
|i1 : S=QQ[x1,x2,x3,x4,x5,x6,y1,y2,z];                                        |
+-----------------------------------------------------------------------------+
|i2 : I=ideal {x1*x4-z^2,x2*x5-z^2,x3*x6-z^2,x1*x3-z*x2,x2*x4-z*x3,x3*x5-z*x4,|
|                                                                             |
|o2 : Ideal of S                                                              |
|-----------------------------------------------------------------------------|
|x4*x6-z*x5,x5*x1-z*x6,x6*x2-z*x1,y1*y2-z^2};                                 |
+-----------------------------------------------------------------------------+
|i3 : F0=gens I;                                                              |
|                                                                             |
|             1      10                                                       |
|o3 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i4 : (F,R,G,C)=versalDeformation(F0,CT^1(0,F0),CT^2(0,F0),HighestOrder=>2);  |
|Warning: calculation terminated since HighestOrder has been reached.         |
+-----------------------------------------------------------------------------+

We stop the calculation at order 2, since in this case, the solution to the
deformation equation calculated by the lifting algorithm will not be
polynomial. Equations for the tangent cone at the origin of a versal base space
are

+------------------------+
|i5 : T=ring first G;    |
+------------------------+
|i6 : G_0                |
|                        |
|o6 = | t_19t_22        ||
|     | t_20t_23        ||
|     | t_15t_22-t_22^2 ||
|     | t_16t_23-t_23^2 ||
|                        |
|             4      1   |
|o6 : Matrix T  <-- T    |
+------------------------+

This decomposes into four components:

+-----------------------------------------------------------------------------+
|i7 : decompose ideal G_0                                                     |
|                                                                             |
|o7 = {ideal (t  , t  ), ideal (t  , t  , t   - t  ), ideal (t  , t  , t   -  |
|              23   22           23   19   15    22           22   20   16    |
|     ------------------------------------------------------------------------|
|     t  ), ideal (t  , t  , t   - t  , t   - t  )}                           |
|      23           20   19   16    23   15    22                             |
|                                                                             |
|o7 : List                                                                    |
+-----------------------------------------------------------------------------+

We now find a one-parameter deformation onto the component of highest
dimension:

+-----------------------------------------------------------------------------+
|i8 : A=(coefficientRing ring F_0)[s];                                        |
+-----------------------------------------------------------------------------+
|i9 : sublist=apply(gens T,v->(if v==t_19 or v==t_20  then return v=>s;v=>0));|
+-----------------------------------------------------------------------------+
|i10 : f=apply(F,i->sub(i,sublist));                                          |
+-----------------------------------------------------------------------------+
|i11 : r=apply(R,i->sub(i,sublist));                                          |
+-----------------------------------------------------------------------------+
|i12 : g=apply(G,i->sub(i,sublist));                                          |
+-----------------------------------------------------------------------------+
|i13 : c=apply(C,i->sub(i,sublist));                                          |
+-----------------------------------------------------------------------------+
|i14 : (F,R,G,C)=versalDeformation(f,r,g,c);                                  |
+-----------------------------------------------------------------------------+
|i15 : sum F                                                                  |
|                                                                             |
|o15 = | (y1z+y2z)s+x1x4-z2 (y1z+y2z)s+x2x5-z2 x3x6-z2 x1x3-x2z               |
|      -----------------------------------------------------------------------|
|      (x3y1+x3y2)s+x2x4-x3z x3x5-x4z x4x6-x5z (x6y1+x6y2)s+x1x5-x6z x2x6-x1z |
|      -----------------------------------------------------------------------|
|      y1y2-z2 |                                                              |
|                                                                             |
|              1      10                                                      |
|o15 : Matrix A  <-- A                                                        |
+-----------------------------------------------------------------------------+

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

  * versalDeformation(List,List,List,List)
    -- continues calculation
    of  a versal deformation

versalDeformation(Matrix) -- computes a power series representation of a versal deformation
*******************************************************************************************

Synopsis
========

  * Function: versalDeformation,
  * Usage:
        (F,R,G,C) = versalDeformation(F0)
  * Inputs:
      * F0, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CacheName => ..., default value null
      * CorrectionMatrix => ..., default value "auto"
      * DefParam => ..., default value "t"
      * DegreeBound, => ..., default value 0, determines the
        degree limit used to compute the tangent cone of obstruction equations
      * HighestOrder => ..., default value 20
      * PolynomialCheck => ..., default value true
      * SanityCheck => ..., default value true
      * SmartLift => ..., default value true
      * Verbose, =>
        ..., default value 0, control the verbosity of output
  * Outputs:
      * F, a list (Macaulay2Doc), of matrices
      * R, a list (Macaulay2Doc), of matrices
      * G, a list (Macaulay2Doc), of matrices
      * C, a list (Macaulay2Doc), of matrices

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

Each element of the sequence (F,R,G,C) is a list of matrices in increasing
powers of the deformation parameter specified by DefParam.
Their sums satisfy the deformation equation transpose flatten ((sum F)*(sum
R))+(sum C)*(sum G)==0 up to powers of the deformation parameter equal to the
length of F. Furthermore, F_0=F0 and R_0=gens ker F0. The columns of C_0 are
multiples of the those of cotangentCohomology2,(F0)
if F0 has a single row, and extMatrix,(F0) otherwise. F_1
consists of first order perturbations corresponding to the basis of
cotangentCohomology1,(F0). Thus, F and G represent a
versal family and equations for a versal base space, either for the scheme cut
out by the columns of F0 (when F0 has a single row), or the module coker F0.

Several options are available to control the termination of the calculation.
The calculation will terminate at the very latest after reaching order equal to
the option HighestOrder, which has default value 20. If
this order is reached, a warning message is generated. If
PolynomialCheck, is set to true (Macaulay2Doc), as
is the default, then the algorithm will check if the present solution lifts to
infinite order and terminate if this is the case. If SanityCheck,
is set to true (Macaulay2Doc), as is the default, then
the algorithm will check that the present solution really does solve the
deformation equation, and terminate with an error if this is not the case.

The option Verbose (Macaulay2Doc), may be used to control the
verbosity of the output. Its value should be an integer, with higher values
corresponding to more verbose output. Default value is 0.

The option SmartLift, is also available, which controls
whether the algorithm spends extra time trying to find liftings which introduce
no new obstructions at the next highest order. By default, this option is
enabled. The option CorrectionMatrix, may be used to
control which liftings are considered.

After each step of lifting, the solution (F,R,G,C) to the deformation equation
is cached. By default, it is stored in F0.cache#VersalDeformationResults but
may stored elsewhere by setting the option CacheName, to
something other than null (Macaulay2Doc).

For example, consider the cone over the rational normal curve of degree four,
see [Pi74],:

+-----------------------------------------------------------------------------+
|i1 : S=QQ[x_0..x_4];                                                         |
+-----------------------------------------------------------------------------+
|i2 : I=minors(2,matrix {{x_0,x_1,x_2,x_3},{x_1,x_2,x_3,x_4}});               |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : F0=gens I                                                               |
|                                                                             |
|o3 = | -x_1^2+x_0x_2 -x_1x_2+x_0x_3 -x_2^2+x_1x_3 -x_1x_3+x_0x_4             |
|     ------------------------------------------------------------------------|
|     -x_2x_3+x_1x_4 -x_3^2+x_2x_4 |                                          |
|                                                                             |
|             1      6                                                        |
|o3 : Matrix S  <-- S                                                         |
+-----------------------------------------------------------------------------+
|i4 : (F,R,G,C)=versalDeformation(F0,Verbose=>2);                             |
|Calculating first order deformations and obstruction space                   |
|Calculating first order relations                                            |
|Calculating standard expressions for obstructions                            |
|Starting lifting                                                             |
|Order 2                                                                      |
|Order 3                                                                      |
|Solution is polynomial                                                       |
+-----------------------------------------------------------------------------+

Equations for a versal base space are

+---------------------+
|i5 : T=ring first G; |
+---------------------+
|i6 : sum G           |
|                     |
|o6 = | t_2t_3-t_3^2 ||
|     | -t_1t_3      ||
|     | t_3t_4       ||
|                     |
|             3      1|
|o6 : Matrix T  <-- T |
+---------------------+

The versal family is given by

+-----------------------------------------------------------------------------+
|i7 : sum F                                                                   |
|                                                                             |
|o7 = | x_1t_1+x_0t_2-x_1^2+x_0x_2 -t_1t_3+x_0t_4-x_1x_2+x_0x_3               |
|     ------------------------------------------------------------------------|
|     -t_2t_3+t_3^2-t_1t_4-x_3t_1-x_2t_2+x_1t_4-x_2^2+x_1x_3                  |
|     ------------------------------------------------------------------------|
|     t_2t_3-t_3^2+x_2t_3-x_1x_3+x_0x_4 -x_4t_1-x_3t_2+x_3t_3-x_2x_3+x_1x_4   |
|     ------------------------------------------------------------------------|
|     x_4t_3-x_3t_4-x_3^2+x_2x_4 |                                            |
|                                                                             |
|             1      6                                                        |
|o7 : Matrix T  <-- T                                                         |
+-----------------------------------------------------------------------------+

We may also consider the example of the cone over the del Pezzo surface of
degree six, see [Al97],:

+-----------------------------------------------------------------------------+
|i8 : S=QQ[x1,x2,x3,x4,x5,x6,z];                                              |
+-----------------------------------------------------------------------------+
|i9 : I=ideal {x1*x4-z^2,x2*x5-z^2,x3*x6-z^2,x1*x3-z*x2,x2*x4-z*x3,x3*x5-z*x4,|
|                                                                             |
|o9 : Ideal of S                                                              |
|-----------------------------------------------------------------------------|
|x4*x6-z*x5,x5*x1-z*x6,x6*x2-z*x1};                                           |
+-----------------------------------------------------------------------------+
|i10 : F0=gens I;                                                             |
|                                                                             |
|              1      9                                                       |
|o10 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i11 : (F,R,G,C)=versalDeformation(F0,Verbose=>2);                            |
|Calculating first order deformations and obstruction space                   |
|Calculating first order relations                                            |
|Calculating standard expressions for obstructions                            |
|Starting lifting                                                             |
|Order 2                                                                      |
|Order 3                                                                      |
|Solution is polynomial                                                       |
+-----------------------------------------------------------------------------+

Equations for a versal base space are

+----------------------+
|i12 : T=ring first G; |
+----------------------+
|i13 : sum G           |
|                      |
|o13 = | t_2t_3       ||
|      | t_1t_3-t_3^2 ||
|                      |
|              2      1|
|o13 : Matrix T  <-- T |
+----------------------+

The versal family is given by

+-----------------------------------------------------------------------------+
|i14 : sum F                                                                  |
|                                                                             |
|o14 = | -t_1t_2+zt_1+zt_2+x1x4-z2 zt_2+zt_3+x2x5-z2 zt_1+x3x6-z2             |
|      -----------------------------------------------------------------------|
|      x2t_1+x1x3-x2z x3t_2+x2x4-x3z x4t_3+x3x5-x4z x5t_1-x5t_3+x4x6-x5z      |
|      -----------------------------------------------------------------------|
|      x6t_2+x6t_3+x1x5-x6z x2x6-x1z |                                        |
|                                                                             |
|              1      9                                                       |
|o14 : Matrix T  <-- T                                                        |
+-----------------------------------------------------------------------------+

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

  * versalDeformation(Matrix) -- computes
    a power series representation of a versal deformation

versalDeformation(Matrix,Matrix,Matrix) -- computes a power series representation of a versal deformation
*********************************************************************************************************

Synopsis
========

  * Function: versalDeformation,
  * Usage:
        (F,R,G,C) = versalDeformation(F0)
        (F,R,G,C) = versalDeformation(F0,T1,T2)
  * Inputs:
      * F0, a matrix (Macaulay2Doc),
      * T1, a matrix (Macaulay2Doc),
      * T2, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * CacheName, => ..., default value
        null, computes a power series representation of a versal deformation
      * CorrectionMatrix, => ..., default
        value "auto", computes a power series representation of a versal
        deformation
      * DefParam, => ..., default value
        "t", computes a power series representation of a versal deformation
      * DegreeBound, => ..., default value 0, determines the
        degree limit used to compute the tangent cone of obstruction equations
      * HighestOrder, => ..., default
        value 20, computes a power series representation of a versal
        deformation
      * PolynomialCheck, => ..., default
        value true, computes a power series representation of a versal
        deformation
      * SanityCheck, => ..., default value
        true, computes a power series representation of a versal deformation
      * SmartLift, => ..., default value
        true, computes a power series representation of a versal deformation
      * Verbose, =>
        ..., default value 0, control the verbosity of output
  * Outputs:
      * F, a list (Macaulay2Doc), of matrices
      * R, a list (Macaulay2Doc), of matrices
      * G, a list (Macaulay2Doc), of matrices
      * C, a list (Macaulay2Doc), of matrices

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

F0, T1, and T2 should all be matrices over some common polynomial ring.

Each element of the sequence (F,R,G,C) is a list of matrices in increasing
powers of the deformation parameter specified by DefParam.
Their sums satisfy the deformation equation transpose flatten ((sum F)*(sum
R))+(sum C)*(sum G)==0 up to powers of the deformation parameter equal to the
length of F. Furthermore, F_0=F0, R_0=gens ker F0, the columns of C_0 are
multiples of those of T2 and F_1 consists of first order perturbations
corresponding to T1. Thus, if T1 and T2 are tangent and obstruction spaces for
some deformation functor, then F and G represent a versal family and equations
for a versal base space.

Several options are available to control the termination of the calculation.
The calculation will terminate at the very latest after reaching order equal to
the option HighestOrder, which has default value 20. If
this order is reached, a warning message is generated. If
PolynomialCheck, is set to true (Macaulay2Doc), as
is the default, then the algorithm will check if the present solution lifts to
infinite order and terminate if this is the case. If SanityCheck,
is set to true (Macaulay2Doc), as is the default, then
the algorithm will check that the present solution really does solve the
deformation equation, and terminate with an error if this is not the case.

The option Verbose (Macaulay2Doc), may be used to control the
verbosity of the output. Its value should be an integer, with higher values
corresponding to more verbose output. Default value is 0.

The option SmartLift, is also available, which controls
whether the algorithm spends extra time trying to find liftings which introduce
no new obstructions at the next highest order. By default, this option is
enabled. The option CorrectionMatrix, may be used to
control which liftings are considered.

After each step of lifting, the solution (F,R,G,C) to the deformation equation
is cached. By default, it is stored in F0.cache#VersalDeformationResults but
may stored elsewhere by setting the option CacheName, to
something other than null (Macaulay2Doc).

We may use this method to compute local multigraded Hilbert schemes. Here, we
consider the Borel fixed ideal for the multigraded Hilbert scheme of the
diagonal in a product of three projective planes, see [CS10],:

+-----------------------------------------------------------------------------+
|i1 : S=QQ[x1,x2,x3,y1,y2,y3,z1,z2,z3,Degrees=>                               |
|          {{1,0,0},{1,0,0},{1,0,0},{0,1,0},{0,1,0},{0,1,0},{0,0,1},{0,0,1},{0|
|-----------------------------------------------------------------------------|
|,0,1}}];                                                                     |
+-----------------------------------------------------------------------------+
|i2 : I=ideal {y1*z2, x1*z2, y2*z1, y1*z1, x2*z1, x1*z1, x1*y2, x2*y1,        |
|           x1*y1, x2*y2*z2};                                                 |
|                                                                             |
|o2 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i3 : (F,R,G,C)=versalDeformation(gens I,normalMatrix({0,0,0},gens I),        |
|          CT^2({0,0,0},gens I),Verbose=>2);                                  |
|Calculating first order relations                                            |
|Calculating standard expressions for obstructions                            |
|Starting lifting                                                             |
|Order 2                                                                      |
|Order 3                                                                      |
|Order 4                                                                      |
|Order 5                                                                      |
|Order 6                                                                      |
|Solution is polynomial                                                       |
+-----------------------------------------------------------------------------+

Local equations for the multigraded Hilbert scheme  are

+-----------------------------------------------------------------------------+
|i4 : T=ring first G;                                                         |
+-----------------------------------------------------------------------------+
|i5 : sum G                                                                   |
|                                                                             |
|o5 = | -t_2t_3t_4+t_2t_4t_7+t_1t_3t_8-t_1t_7t_8-t_1t_3t_13+t_2t_3t_13+t_1t_7t|
|     | t_1t_3t_4-t_2t_3t_4-t_1t_7t_8+t_2t_7t_8-t_1t_3t_13+t_2t_3t_13+t_1t_7t_|
|     | -t_1t_3t_16+t_2t_7t_16+t_1t_14t_16-t_2t_14t_16+t_3t_15t_16-t_7t_15t_16|
|     | -t_1t_3t_18+t_2t_7t_18+t_1t_14t_18-t_2t_14t_18+t_3t_15t_18-t_7t_15t_18|
|     | -t_2t_4t_17+t_1t_8t_17-t_1t_13t_17+t_2t_13t_17+t_4t_15t_17-t_8t_15t_17|
|     | t_2t_4t_18-t_1t_8t_18+t_1t_13t_18-t_2t_13t_18-t_4t_15t_18+t_8t_15t_18 |
|     | -t_3t_4t_17+t_7t_8t_17+t_3t_13t_17-t_7t_13t_17+t_4t_14t_17-t_8t_14t_17|
|     | -t_3t_4t_16+t_7t_8t_16+t_3t_13t_16-t_7t_13t_16+t_4t_14t_16-t_8t_14t_16|
|     ------------------------------------------------------------------------|
|     _13-t_2t_7t_13+t_3t_4t_15-t_4t_7t_15-t_3t_8t_15+t_7t_8t_15 |            |
|     13-t_2t_7t_13-t_1t_4t_14+t_2t_4t_14+t_1t_8t_14-t_2t_8t_14  |            |
|                                                                |            |
|                                                                |            |
|                                                                |            |
|                                                                |            |
|                                                                |            |
|                                                                |            |
|                                                                             |
|             8      1                                                        |
|o5 : Matrix T  <-- T                                                         |
+-----------------------------------------------------------------------------+

At this point, the multigraded Hilbert scheme has 7 irreducible components:

+---------------------------------------+
|i6 : # primaryDecomposition ideal sum G|
|                                       |
|o6 = 7                                 |
+---------------------------------------+

We may use this method to compute versal deformations of modules. Here, we
consider versal deformations for a torsion free rank one module of an E6
singularity, see [Si01],:

+--------------------------------------------------------------------+
|i7 : S=QQ[x,y]/ideal {x^4+y^3};                                     |
+--------------------------------------------------------------------+
|i8 : f= matrix {{x,-y^2},{y,x^3}};                                  |
|                                                                    |
|             2      2                                               |
|o8 : Matrix S  <-- S                                                |
+--------------------------------------------------------------------+
|i9 : (F,R,G,C)=versalDeformation(f,CT^1(f),extMatrix(f),Verbose=>2);|
|Calculating first order relations                                   |
|Calculating standard expressions for obstructions                   |
|Starting lifting                                                    |
|Order 2                                                             |
|Order 3                                                             |
|Order 4                                                             |
|Order 5                                                             |
|Solution is polynomial                                              |
+--------------------------------------------------------------------+

The cokernel of f is the module M1. Its versal deformation has a singular curve
as its base space:

+------------------------+
|i10 : T=ring first G;   |
+------------------------+
|i11 : ideal sum G       |
|                        |
|              4    3    |
|o11 = ideal (t  - t , 0)|
|              2    1    |
|                        |
|o11 : Ideal of T        |
+------------------------+

We may also compute local Quot schemes for modules with zero-dimensional
support:

+-----------------------------------------------------------------------------+
|i12 : S = QQ[a, b];                                                          |
+-----------------------------------------------------------------------------+
|i13 : f =  matrix{{a, b, 0, 0}, {0, 0, a, b}};                               |
|                                                                             |
|              2      4                                                       |
|o13 : Matrix S  <-- S                                                        |
+-----------------------------------------------------------------------------+
|i14 : (F,R,G,C)=versalDeformation(f,normalMatrix(f),extMatrix(f),Verbose=>2);|
|Calculating first order relations                                            |
|Calculating standard expressions for obstructions                            |
|Starting lifting                                                             |
|Order 2                                                                      |
|Order 3                                                                      |
|Solution is polynomial                                                       |
+-----------------------------------------------------------------------------+

We are considering the local Quot scheme for the surjection of S^4 to coker f.
Equations for the base space are:

+-----------------------------------------------------------------------------+
|i15 : T=ring first G;                                                        |
+-----------------------------------------------------------------------------+
|i16 : ideal sum G                                                            |
|                                                                             |
|o16 = ideal (t t  - t t , t t  - t t  + t t  - t t , - t t  + t t  - t t  +  |
|              4 5    2 7   2 3    1 4    4 6    2 8     3 5    1 7    6 7    |
|      -----------------------------------------------------------------------|
|      t t , - t t  + t t )                                                   |
|       5 8     4 5    2 7                                                    |
|                                                                             |
|o16 : Ideal of T                                                             |
+-----------------------------------------------------------------------------+

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

  * versalDeformation(Matrix,Matrix,Matrix)
    -- computes a power series
    representation of a versal deformation

VersalDeformationResults -- hash table key for cached solutions to the deformation equation
*******************************************************************************************

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

VersalDeformationResults is the name of a symbol (Macaulay2Doc),
used as a key for caching the output of versalDeformation,
and localHilbertScheme. See
CacheName, for more information.

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

The object VersalDeformationResults, is a
symbol (Macaulay2Doc).