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

NumericalAlgebraicGeometry -- Numerical Algebraic Geometry
**********************************************************

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

The package NumericalAlgebraicGeometry, also known as NAG4M2
(Numerical Algebraic Geometry for Macaulay2), implements methods of polynomial
homotopy continuation to solve systems of polynomial equations,
+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i2 : F = {x^2+y^2+z^2-1, y-x^2, z-x^3};                                      |
+-----------------------------------------------------------------------------+
|i3 : s = solveSystem F                                                       |
|                                                                             |
|o3 = {{.540536+1.03152*ii, -.771845+1.11514*ii, -1.5675-.193395*ii},         |
|     ------------------------------------------------------------------------|
|     {-.737353, .543689, -.400891}, {-.540536-1.03152*ii,                    |
|     ------------------------------------------------------------------------|
|     -.771845+1.11514*ii, 1.5675+.193395*ii}, {-.540536+1.03152*ii,          |
|     ------------------------------------------------------------------------|
|     -.771845-1.11514*ii, 1.5675-.193395*ii}, {.737353, .543689, .400891},   |
|     ------------------------------------------------------------------------|
|     {.540536-1.03152*ii, -.771845-1.11514*ii, -1.5675+.193395*ii}}          |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : realPoints s                                                            |
|                                                                             |
|o4 = {{-.737353, .543689, -.400891}, {.737353, .543689, .400891}}            |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
and describe positive-dimensional complex algebraic varieties,
+---------------------------------------------+
|i5 : R = CC[x,y,z];                          |
+---------------------------------------------+
|i6 : sph = x^2+y^2+z^2-1;                    |
+---------------------------------------------+
|i7 : I = ideal {x*sph*(y-x^2), sph*(z-x^3)}; |
|                                             |
|o7 : Ideal of R                              |
+---------------------------------------------+
|i8 : numericalIrreducibleDecomposition I     |
|                                             |
|o8 = a "numerical variety" with components in|
|     dim 1:  (dim=1,deg=1) (dim=1,deg=3)     |
|     dim 2:  (dim=2,deg=2)                   |
|                                             |
|o8 : NumericalVariety                        |
+---------------------------------------------+

Basic types (such as Point (NAGtypes), and
WitnessSet (NAGtypes)) are defined in the package NAGtypes.

Basic functions:
----------------

  * track -- track a linear segment
    homotopy given start and target system
  * solveSystem -- solve a system of polynomial
    equations
  * refine -- refine numerical solutions to a
    system of polynomial equations
  * totalDegreeStartSystem, --
    construct a start system for the total degree homotopy
  * numericalIrreducibleDecomposition
    -- constructs a numerical
    variety defined by the given ideal
  * sample -- sample a point on a component
  * isSubset(NumericalVariety,NumericalVariety) (missing documentation)
Optionally, the user may outsource some basic routines to Bertini,
and PHCpack, (look for Software,
option).

Service functions:
------------------

  * Many service functions (such as areEqual (NAGtypes), and
    sortSolutions (NAGtypes)) are defined in the
    package NAGtypes.
  * setDefault -- set/get the default parameters for
    continuation algorithms
  * getDefault -- set/get the default parameters for
    continuation algorithms
  * NAGtrace -- set the trace level in
    NumericalAlgebraicGeometry package
  * newton -- Newton-Raphson method
  * isOn -- determines if a point belongs to a variety
  * union -- union of
    numerical varieties
  * removeRedundantComponents
    -- remove redundant
    components

Functions related to Certified, tracking:
----------------------------------------------------------

  * randomInitialPair -- a random initial pair
  * goodInitialPair -- make an initial pair
    conjectured to be good by Shub and Smale
  * randomSd -- a random homogeneous system of
    polynomial equations

References:
-----------

  * A.J. Sommese, J. Verschelde, and C.W. Wampler, "Introduction to numerical
    algebraic geometry", in "Solving polynomial equations" (2005), 301--338
  * A.J. Sommese and C.W. Wampler, "The numerical solution of systems of
    polynomials", World Scientific Publishing (2005)
  * C. Beltran and A. Leykin, "Certified numerical homotopy tracking",
    Experimental Mathematics 21(1): 69-83 (2012)
  * R. Krone and A. Leykin, "Numerical algorithms for detecting embedded
    components.", arXiv:1405.7871

Authors
=======

  * Anton Leykin (see https://people.math.gatech.edu/~aleykin3 )
    <leykin@math.gatech.edu>
  * Robert Krone <krone@math.gatech.edu>

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

Version 1.4 of this package was accepted for publication in volume 3 (see
http://j-sag.org/Volume3/ ) of The Journal of Software for Algebra and
Geometry: Macaulay2 (see http://j-sag.org/ ) on 2011-05-20, in the article
Numerical Algebraic Geometry (see http://j-sag.org/Volume3/jsag-2-2011.pdf ).
That version can be obtained from the journal (see
http://j-sag.org/Volume3/NumericalAlgebraicGeometry.tar ) or from the Macaulay2
source code repository (see
https://github.com/Macaulay2/M2/blob/c3a7ec33ee30195c2a8a15eef3456b2f27d73bf3/
M2/Macaulay2/packages/NumericalAlgebraicGeometry.m2 ).

Version
=======

This documentation describes version 1.21 of NumericalAlgebraicGeometry.

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

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

Exports
=======

  * Types
      * "GateHomotopy" -- see
        gateHomotopy(GateMatrix,GateMatrix,InputGate),
        -- homotopy
        implemented via straight line programs
      * GateParameterHomotopy -- a homotopy that
        involves parameters and is implemented via straight line programs
      * GateSystem -- a system of functions evaluated via a
        straightline program
  * Functions and commands
      * deflate -- first-order deflation
      * "deflateAndStoreDeflationSequence" -- see deflate, --
        first-order deflation
      * "liftPointToDeflation" -- see deflate, -- first-order
        deflation
      * endGameCauchy -- Cauchy end game for getting a
        better approximation of a singular solution
      * "gateHomotopy" -- see
        gateHomotopy(GateMatrix,GateMatrix,InputGate),
        -- homotopy
        implemented via straight line programs
      * gateSystem -- a constructor for GateSystem
      * "goodInitialPair" -- see goodInitialPair(List),
        -- make an initial pair conjectured to be
        good by Shub and Smale
      * isOn -- determines if a point belongs to a variety
      * "isSolution" -- see isSolution(AbstractPoint,PolySystem),
        -- check if a point
        satisfies a polynomial system approximately
      * "NAGtrace" -- see NAGtrace(ZZ), -- set the
        trace level in NumericalAlgebraicGeometry package
      * newton -- Newton-Raphson method
      * "hypersurfaceSection" -- see numericalIntersection,
        -- intersection of numerical varieties
      * numericalIntersection -- intersection of
        numerical varieties
      * "numericalIrreducibleDecomposition" -- see
        numericalIrreducibleDecomposition(Ideal),
        -- constructs a numerical
        variety defined by the given ideal
      * "parameterHomotopy" -- see parameterHomotopy(List,List,List),
        -- solve a parametric system
        of equations
      * parametricSegmentHomotopy -- creates
        an ansatz for a segment homotopy
      * randomInitialPair -- a random initial pair
      * "randomSd" -- see randomSd(List), -- a random
        homogeneous system of polynomial equations
      * "refine" -- see refine(List,List), --
        refine numerical solutions to a system of polynomial equations
      * "regeneration" -- see regeneration(List),
        -- solve a system of polynomial equations with regeneration method
      * "removeRedundantComponents" -- see
        removeRedundantComponents(NumericalVariety),
        -- remove redundant
        components
      * "sample" -- see sample(WitnessSet), --
        sample a point on a component
      * segmentHomotopy -- a segment homotopy
      * "getDefault" -- see setDefault, -- set/get the
        default parameters for continuation algorithms
      * setDefault -- set/get the default parameters for
        continuation algorithms
      * "solveGenericSystemInTorus" -- see
        solveGenericSystemInTorus(List),
        -- solve a generic system of sparse polynomial equations in the torus
      * "solveSystem" -- see solveSystem(List), --
        solve a system of polynomial equations
      * squareUp -- square up a polynomial system
      * "totalDegreeStartSystem" -- see totalDegreeStartSystem(List),
        -- construct a start system for the
        total degree homotopy
      * "track" -- see track(List,List,List),
        -- track a linear segment homotopy given
        start and target system
      * "trackHomotopy" -- see trackHomotopy(Homotopy,List),
        -- follow points along a homotopy
      * "union" -- see union(NumericalVariety,NumericalVariety),
        -- union of numerical
        varieties
  * Methods
      * decompose(WitnessSet) -- decompose a
        witness set into irreducibles
      * "deflate(Ideal)" -- see deflate, -- first-order
        deflation
      * "deflate(PolySystem,AbstractPoint)" -- see deflate, --
        first-order deflation
      * "deflate(PolySystem,List)" -- see deflate, --
        first-order deflation
      * "deflate(PolySystem,Matrix)" -- see deflate, --
        first-order deflation
      * "deflate(PolySystem,Sequence)" -- see deflate, --
        first-order deflation
      * "deflate(PolySystem,ZZ)" -- see deflate, -- first-order
        deflation
      * "deflateAndStoreDeflationSequence(AbstractPoint,PolySystem)" -- see
        deflate, -- first-order deflation
      * "liftPointToDeflation(AbstractPoint,PolySystem,ZZ)" -- see
        deflate, -- first-order deflation
      * "endGameCauchy(GateHomotopy,Number,AbstractPoint)" -- see
        endGameCauchy, -- Cauchy end game for getting a better
        approximation of a singular solution
      * "endGameCauchy(GateHomotopy,Number,MutableMatrix)" -- see
        endGameCauchy, -- Cauchy end game for getting a better
        approximation of a singular solution
      * evaluateH(GateHomotopy,Matrix,Number)
        -- evaluate gate
        homotopy and its derivatives
      * "evaluateHt(GateHomotopy,Matrix,Number)" -- see
        evaluateH(GateHomotopy,Matrix,Number),
        -- evaluate gate
        homotopy and its derivatives
      * "evaluateHx(GateHomotopy,Matrix,Number)" -- see
        evaluateH(GateHomotopy,Matrix,Number),
        -- evaluate gate
        homotopy and its derivatives
      * evaluateH(GateParameterHomotopy,Matrix,Matrix,Number),
        --
        evaluate (gate) parameter homotopy and its derivatives
      * "evaluateHt(GateParameterHomotopy,Matrix,Matrix,Number)" -- see
        evaluateH(GateParameterHomotopy,Matrix,Matrix,Number),
        --
        evaluate (gate) parameter homotopy and its derivatives
      * "evaluateHx(GateParameterHomotopy,Matrix,Matrix,Number)" -- see
        evaluateH(GateParameterHomotopy,Matrix,Matrix,Number),
        --
        evaluate (gate) parameter homotopy and its derivatives
      * gateHomotopy(GateMatrix,GateMatrix,InputGate)
        -- homotopy
        implemented via straight line programs
      * "numVariables(GateHomotopy)" -- see
        gateHomotopy(GateMatrix,GateMatrix,InputGate),
        -- homotopy
        implemented via straight line programs
      * gateMatrix(GateSystem) -- evaluation
        circuit used for the system
      * "evaluate(GateSystem,Matrix,Matrix)" -- see GateSystem,
        -- a system of functions evaluated via a straightline
        program
      * "net(GateSystem)" -- see GateSystem, -- a system of
        functions evaluated via a straightline program
      * "numFunctions(GateSystem)" -- see GateSystem, -- a
        system of functions evaluated via a straightline program
      * "numParameters(GateSystem)" -- see GateSystem, -- a
        system of functions evaluated via a straightline program
      * "numVariables(GateSystem)" -- see GateSystem, -- a
        system of functions evaluated via a straightline program
      * "gateSystem(GateMatrix,GateMatrix)" -- see gateSystem,
        -- a constructor for GateSystem
      * "gateSystem(GateMatrix,GateMatrix,GateMatrix)" -- see gateSystem,
        -- a constructor for GateSystem
      * "gateSystem(Matrix)" -- see gateSystem, -- a
        constructor for GateSystem
      * "gateSystem(PolySystem)" -- see gateSystem, -- a
        constructor for GateSystem
      * "gateSystem(PolySystem,List)" -- see gateSystem, -- a
        constructor for GateSystem
      * goodInitialPair(List) -- make an
        initial pair conjectured to be good by Shub and Smale
      * "isOn(AbstractPoint,Ideal)" -- see isOn, -- determines if a
        point belongs to a variety
      * "isOn(AbstractPoint,NumericalVariety)" -- see isOn, --
        determines if a point belongs to a variety
      * "isOn(AbstractPoint,RingElement)" -- see isOn, --
        determines if a point belongs to a variety
      * "isOn(AbstractPoint,WitnessSet)" -- see isOn, -- determines
        if a point belongs to a variety
      * "isOn(AbstractPoint,WitnessSet,ZZ)" -- see isOn, --
        determines if a point belongs to a variety
      * isSolution(AbstractPoint,PolySystem)
        -- check if a point
        satisfies a polynomial system approximately
      * isSubset(NumericalVariety,NumericalVariety)
        -- check containment
      * "isSubset(WitnessSet,WitnessSet)" -- see
        isSubset(NumericalVariety,NumericalVariety),
        -- check containment
      * jacobian(GateSystem) -- jacobian of a
        (gate) system
      * "jacobian(List,GateSystem)" -- see jacobian(GateSystem),
        -- jacobian of a (gate) system
      * NAGtrace(ZZ) -- set the trace level in
        NumericalAlgebraicGeometry package
      * "newton(PolySystem,AbstractPoint)" -- see newton, --
        Newton-Raphson method
      * "newton(PolySystem,Matrix)" -- see newton, --
        Newton-Raphson method
      * "hypersurfaceSection(NumericalVariety,RingElement)" -- see
        numericalIntersection, -- intersection of
        numerical varieties
      * "numericalIntersection(NumericalVariety,Ideal)" -- see
        numericalIntersection, -- intersection of
        numerical varieties
      * "numericalIntersection(NumericalVariety,NumericalVariety)" -- see
        numericalIntersection, -- intersection of
        numerical varieties
      * "numericalIntersection(WitnessSet,WitnessSet)" -- see
        numericalIntersection, -- intersection of
        numerical varieties
      * numericalIrreducibleDecomposition(Ideal)
        -- constructs a numerical
        variety defined by the given ideal
      * parameterHomotopy(List,List,List)
        -- solve a parametric system
        of equations
      * parameters(GateSystem) -- the
        parameter gates in the evaluation circuit used for the system
      * "parametricSegmentHomotopy(GateSystem)" -- see
        parametricSegmentHomotopy, -- creates an
        ansatz for a segment homotopy
      * "parametricSegmentHomotopy(PolySystem)" -- see
        parametricSegmentHomotopy, -- creates an
        ansatz for a segment homotopy
      * "randomInitialPair(List)" -- see randomInitialPair,
        -- a random initial pair
      * randomSd(List) -- a random homogeneous
        system of polynomial equations
      * "refine(AbstractPoint)" -- see refine(List,List),
        -- refine numerical solutions to a system of
        polynomial equations
      * refine(List,List) -- refine numerical
        solutions to a system of polynomial equations
      * "refine(PolySystem,AbstractPoint)" -- see refine(List,List),
        -- refine numerical solutions to a system of
        polynomial equations
      * "refine(PolySystem,List)" -- see refine(List,List),
        -- refine numerical solutions to a system of
        polynomial equations
      * regeneration(List) -- solve a system of
        polynomial equations with regeneration method
      * removeRedundantComponents(NumericalVariety)
        -- remove redundant
        components
      * sample(WitnessSet) -- sample a point on
        a component
      * "segmentHomotopy(GateSystem,GateSystem)" -- see segmentHomotopy,
        -- a segment homotopy
      * "segmentHomotopy(List,List)" -- see segmentHomotopy,
        -- a segment homotopy
      * "segmentHomotopy(PolySystem,PolySystem)" -- see segmentHomotopy,
        -- a segment homotopy
      * "getDefault(Symbol)" -- see setDefault, -- set/get
        the default parameters for continuation algorithms
      * solveGenericSystemInTorus(List)
        -- solve a generic system of
        sparse polynomial equations in the torus
      * "solveGenericSystemInTorus(PolySystem)" -- see
        solveGenericSystemInTorus(List),
        -- solve a generic system of sparse polynomial equations in the torus
      * solveSystem(List) -- solve a system of
        polynomial equations
      * "solveSystem(PolySystem)" -- see solveSystem(List),
        -- solve a system of polynomial equations
      * specialize(GateParameterHomotopy,MutableMatrix)
        -- specialize
        parameters in a (gate) parameter homotopy
      * "squareUp(PolySystem)" -- see squareUp, -- square up a
        polynomial system
      * "squareUp(PolySystem,Matrix)" -- see squareUp, --
        square up a polynomial system
      * "squareUp(PolySystem,ZZ)" -- see squareUp, -- square up
        a polynomial system
      * totalDegreeStartSystem(List),
        -- construct a start system for the total degree homotopy
      * track(List,List,List) -- track a
        linear segment homotopy given start and target system
      * "track(PolySystem,PolySystem,List)" -- see track(List,List,List),
        -- track a linear segment homotopy given
        start and target system
      * trackHomotopy(Homotopy,List),
        -- follow points along a homotopy
      * "trackHomotopy(Matrix,List)" -- see trackHomotopy(Homotopy,List),
        -- follow points along a homotopy
      * "trackHomotopy(Sequence,List)" -- see
        trackHomotopy(Homotopy,List), --
        follow points along a homotopy
      * union(NumericalVariety,NumericalVariety)
        -- union of numerical
        varieties
      * vars(GateSystem) -- the variable gates in
        the evaluation circuit used for the system
  * Symbols
      * AffinePatches -- reserved for developers
      * "CompiledHornerForm" -- see AffinePatches, --
        reserved for developers
      * "DynamicPatch" -- see AffinePatches, -- reserved
        for developers
      * "HornerForm" -- see AffinePatches, -- reserved for
        developers
      * "SLP" -- see AffinePatches, -- reserved for
        developers
      * "SLPcorrector" -- see AffinePatches, -- reserved
        for developers
      * "SLPpredictor" -- see AffinePatches, -- reserved
        for developers
      * BERTINI -- use Bertini for homotopy continuation
      * Certified -- a value for the option Predictor that
        triggers certified tracking
      * "Deflation" -- see deflate, -- first-order deflation
      * "DeflationRandomMatrix" -- see deflate, -- first-order
        deflation
      * "DeflationSequence" -- see deflate, -- first-order
        deflation
      * "DeflationSequenceMatrices" -- see deflate, --
        first-order deflation
      * "LiftedPoint" -- see deflate, -- first-order deflation
      * "LiftedSystem" -- see deflate, -- first-order deflation
      * "SolutionSystem" -- see deflate, -- first-order
        deflation
      * "SquareUp" -- see deflate, -- first-order deflation
      * "GeneralPosition" -- see goodInitialPair(List),
        -- make an initial pair conjectured to be
        good by Shub and Smale
      * HOM4PS2 -- use HOM4PS for homotopy continuation
      * "Bits" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "CorrectorTolerance" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "EndZoneFactor" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "ErrorTolerance" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "Euler" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "gamma" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "InfinityThreshold" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "Iterations" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "maxCorrSteps" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "Multistep" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "MultistepDegree" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "NoOutput" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "numberSuccessesBeforeIncrease" -- see numerical homotopy tracking options,
        -- options for
        core functions of Numerical Algebraic Geometry
      * "Predictor" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "Projectivize" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "ResidualTolerance" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "RungeKutta4" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "Secant" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "stepIncreaseFactor" -- see numerical homotopy tracking options,
        -- options for core functions of
        Numerical Algebraic Geometry
      * "Tangent" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "tDegree" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "tStep" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * "tStepMin" -- see numerical homotopy tracking options,
        -- options for core functions of Numerical
        Algebraic Geometry
      * PHCPACK -- use PHCpack for homotopy continuation
      * "Output" -- see regeneration(List), --
        solve a system of polynomial equations with regeneration method
      * "Attempts" -- see setDefault, -- set/get the default
        parameters for continuation algorithms
      * "SingularConditionNumber" -- see setDefault, --
        set/get the default parameters for continuation algorithms
      * "M2" -- see Software, -- specify internal or external
        software
      * "M2engine" -- see Software, -- specify internal or
        external software
      * "M2enginePrecookedSLPs" -- see Software, -- specify
        internal or external software
      * Software -- specify internal or external software
      * "PostProcess" -- see solveSystem(...,PostProcess=>...),
        -- specifies
        whether to postprocess the solutions
      * "SquaredUpSystem" -- see squareUp, -- square up a
        polynomial system
      * "SquareUpMatrix" -- see squareUp, -- square up a
        polynomial system
      * "Field" -- see trackHomotopy(Homotopy,List),
        -- follow points along a homotopy
  * Other things
      * DoublePrecision -- a constant equal to 53 (the
        number of bits of precision)

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

The object NumericalAlgebraicGeometry, is a package (Macaulay2Doc).

AffinePatches -- reserved for developers
****************************************

Functions with optional argument named AffinePatches :
======================================================

  * "setDefault(...,AffinePatches=>...)"
  * "track(...,AffinePatches=>...)"

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

The object AffinePatches, is a symbol (Macaulay2Doc).

BERTINI -- use Bertini for homotopy continuation
************************************************

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

Available at http://www.nd.edu/~sommese/bertini/

See also
========

  * Software -- specify internal or external software

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

The object BERTINI, is a symbol (Macaulay2Doc).

Certified -- a value for the option Predictor that triggers certified tracking
******************************************************************************

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

Tells basic functions, e.g., see track, to
use soft certification described in

C. Beltran and A. Leykin, "Certified numerical homotopy tracking", Experimental
Mathematics 21(1): 69-83 (2012)

The code for robust certification is not incorporated in this package at the
moment; the location of this stand-alone code is in the references of

C. Beltran and A. Leykin, "Robust certified numerical homotopy tracking",
Foundations of Computational Mathematics 13(2): 253-295 (2013)

The functions related to this paper are:

  * randomInitialPair -- a random initial pair
  * goodInitialPair -- make an initial pair
    conjectured to be good by Shub and Smale
  * randomSd -- a random homogeneous system of
    polynomial equations
+-----------------------------------------------------------------------+
|i1 : R = CC[x,y,z];                                                    |
+-----------------------------------------------------------------------+
|i2 : S = {x^2-z^2,y^2-z^2};                                            |
+-----------------------------------------------------------------------+
|i3 : T = {x^2+y^2-z^2, x*y};                                           |
+-----------------------------------------------------------------------+
|i4 : solsS = {(1,-1,1),(1,1,1)};                                       |
+-----------------------------------------------------------------------+
|i5 : track(S,T,solsS,Predictor=>Certified,Normalize=>true)             |
|                                                                       |
|o5 = {{.00000107266, -.70712, .70712}, {.707125, -1.48993e-7, .707107}}|
|                                                                       |
|o5 : List                                                              |
+-----------------------------------------------------------------------+

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

The object Certified, is a symbol (Macaulay2Doc).

decompose(WitnessSet) -- decompose a witness set into irreducibles
******************************************************************

Synopsis
========

  * Function: decompose (Macaulay2Doc),
  * Usage:
        Ws = decompose W
  * Inputs:
      * W, a witness set (NAGtypes), represents an
        equidimensional component of a variety
  * Outputs:
      * Ws, contains irreducible witness sets witness sets (NAGtypes),
        the union of which is W

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

Monodromy driven decomposition is followed by the linear trace test.
+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y]                                                             |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : F = {x^2+y^2-1, x*y};                                                   |
+-----------------------------------------------------------------------------+
|i3 : W = first components regeneration F                                     |
|                                                                             |
|o3 = W                                                                       |
|                                                                             |
|o3 : WitnessSet                                                              |
+-----------------------------------------------------------------------------+
|i4 : decompose W                                                             |
|                                                                             |
|o4 = {(dim=0,deg=1), (dim=0,deg=1), (dim=0,deg=1), (dim=0,deg=1)}            |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : R = CC[x,y,z]                                                           |
|                                                                             |
|o5 = R                                                                       |
|                                                                             |
|o5 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i6 : sph = (x^2+y^2+z^2-1);                                                  |
+-----------------------------------------------------------------------------+
|i7 : decompose \ components regeneration {sph*(x-1)*(y-x^2), sph*(y-2)*(z-x^3|
|                                                                             |
|o7 = {{(dim=1,deg=1), (dim=1,deg=1), (dim=1,deg=1), (dim=1,deg=1),           |
|     ------------------------------------------------------------------------|
|     (dim=1,deg=3)}, {(dim=2,deg=2)}}                                        |
|                                                                             |
|o7 : List                                                                    |
|-----------------------------------------------------------------------------|
|)}                                                                           |
+-----------------------------------------------------------------------------+

Caveat
======

This function is under development. It can not decompose nonreduced components
at the moment. If monodromy breakup algorithm fails to classify some points,
the unnclassified points appear as one witness set (that is not marked as
irreducible).

See also
========

  * regeneration -- solve a system of polynomial
    equations with regeneration method

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

  * decompose(WitnessSet) -- decompose a
    witness set into irreducibles

deflate -- first-order deflation
********************************

Synopsis
========

  * Usage:
        r = deflate(F,P); r = deflate(F,r); r = deflate(F,B), ...
  * Inputs:
      * P, an instance of the type Point (NAGtypes),
      * F, a polynomial system (NAGtypes),
      * r, an integer (Macaulay2Doc),
      * B, a matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Variable => ..., default value null
  * Outputs:
      * r, an integer (Macaulay2Doc), the rank used in the (last)
        deflation
  * Consequences:
      * Attaches the keys Deflation, and
        DeflationRandomMatrix, which are MutableHashTables that (for
        rank r, a potential rank of the jacobian J of F) store  the deflated
        system DF and a matrix B used to obtain it.  Here B is a random matrix
        of size n x (r+1), where n is the number of variables and DF is
        obtained by appending to F the matrix equation J*B*[L_1,...,L_r,1]^T =
        0. The polynomials of DF use the original variables and augmented
        variables L_1,...,L_r.

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

The purpose of deflation is to restore quadratic convergence of Newton's method
in a neighborhood of a singular isolated solution P. This is done by
constructing an augmented polynomial system with a solution of strictly lower
multiplicity projecting to P.

Apart from P, an instance of the type Point (NAGtypes),
one can pass various things as the second argument.

  * an integer (Macaulay2Doc), r specifies the rank of the Jacobian dF
    (that may be known to the user)
  * a matrix (Macaulay2Doc), B specifies a fixed (r+1)-by-n matrix
    to use in the deflation construction.
  * a pair of matrices (B,M) specifies additionally a matrix that is used to
    squareUp.
  * a list{(B1,M1),(B2,M2),...} prompts a chain of successive deflations using
    the provided pairs of matrices.
The option Variable specifies the base name for the augmented variables.
+--------------------------------------------------------------------+
|i1 : CC[x,y,z]                                                      |
|                                                                    |
|o1 = CC  [x..z]                                                     |
|       53                                                           |
|                                                                    |
|o1 : PolynomialRing                                                 |
+--------------------------------------------------------------------+
|i2 : F = polySystem {x^3,y^3,x^2*y,z^2}                             |
|                                                                    |
|o2 = F                                                              |
|                                                                    |
|o2 : PolySystem                                                     |
+--------------------------------------------------------------------+
|i3 : P0 = point matrix{{0.000001, 0.000001*ii,0.000001-0.000001*ii}}|
|                                                                    |
|o3 = P0                                                             |
|                                                                    |
|o3 : Point                                                          |
+--------------------------------------------------------------------+
|i4 : isFullNumericalRank evaluate(jacobian F,P0)                    |
|                                                                    |
|o4 = false                                                          |
+--------------------------------------------------------------------+
|i5 : r1 = deflate (F,P0)                                            |
|                                                                    |
|o5 = 0                                                              |
+--------------------------------------------------------------------+
|i6 : P1' = liftPointToDeflation(P0,F,r1)                            |
|                                                                    |
|o6 = P0                                                             |
|                                                                    |
|o6 : Point                                                          |
+--------------------------------------------------------------------+
|i7 : F1 = F.Deflation#r1                                            |
|                                                                    |
|o7 = F1                                                             |
|                                                                    |
|o7 : PolySystem                                                     |
+--------------------------------------------------------------------+
|i8 : P1 = newton(F1,P1')                                            |
|                                                                    |
|o8 = P1                                                             |
|                                                                    |
|o8 : Point                                                          |
+--------------------------------------------------------------------+
|i9 : isFullNumericalRank evaluate(jacobian F1,P1)                   |
|                                                                    |
|o9 = false                                                          |
+--------------------------------------------------------------------+
|i10 : r2 = deflate (F1,P1)                                          |
|                                                                    |
|o10 = 1                                                             |
+--------------------------------------------------------------------+
|i11 : P2' = liftPointToDeflation(P1,F1,r2)                          |
|                                                                    |
|o11 = P2'                                                           |
|                                                                    |
|o11 : Point                                                         |
+--------------------------------------------------------------------+
|i12 : F2 = F1.Deflation#r2                                          |
|                                                                    |
|o12 = F2                                                            |
|                                                                    |
|o12 : PolySystem                                                    |
+--------------------------------------------------------------------+
|i13 : P2 = newton(F2,P2')                                           |
|                                                                    |
|o13 = P2                                                            |
|                                                                    |
|o13 : Point                                                         |
+--------------------------------------------------------------------+
|i14 : isFullNumericalRank evaluate(jacobian F2,P2)                  |
|                                                                    |
|o14 = true                                                          |
+--------------------------------------------------------------------+
|i15 : P = point {take(coordinates P2, F.NumberOfVariables)}         |
|                                                                    |
|o15 = P                                                             |
|                                                                    |
|o15 : Point                                                         |
+--------------------------------------------------------------------+
|i16 : assert(residual(F,P) < 1e-50)                                 |
+--------------------------------------------------------------------+

Caveat
======

Needs more documentation!!!

See also
========

  * PolySystem (NAGtypes) -- a polynomial system
  * newton -- Newton-Raphson method

Ways to use deflate :
=====================

  * "deflate(Ideal)"
  * "deflate(PolySystem,AbstractPoint)"
  * "deflate(PolySystem,List)"
  * "deflate(PolySystem,Matrix)"
  * "deflate(PolySystem,Sequence)"
  * "deflate(PolySystem,ZZ)"

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

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

DoublePrecision -- a constant equal to 53 (the number of bits of precision)
***************************************************************************

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

The object DoublePrecision, is an integer (Macaulay2Doc).

endGameCauchy -- Cauchy end game for getting a better approximation of a singular solution
******************************************************************************************

Synopsis
========

  * Usage:
        endGameCauchy(H,t'end,p0)
        endGameCauchy(H,t'end,points)
  * Inputs:
      * H, an instance of the type GateHomotopy,
      * t'end, a number (Macaulay2Doc),
      * p0, a point (NAGtypes),
      * points, a mutable matrix (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * backtrack factor
      * CorrectorTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * EndZoneFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * InfinityThreshold, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * maxCorrSteps, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * number of vertices
      * numberSuccessesBeforeIncrease,
        => ..., default value null, options for core functions of
        Numerical Algebraic Geometry
      * stepIncreaseFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * tStep, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * tStepMin, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry

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

Refines an approximation of a (singular) solution to a polynomial system which
was obtained via homotopy continuation. This method is used for posprocessing
in the blackbox solver implemented in solveSystem.

+------------------------------------------------------------------+
|i1 : CC[x,y]                                                      |
|                                                                  |
|o1 = CC  [x..y]                                                   |
|       53                                                         |
|                                                                  |
|o1 : PolynomialRing                                               |
+------------------------------------------------------------------+
|i2 : T = {(x-2)^3,y-x+x^2-x^3}                                    |
|                                                                  |
|       3     2               3    2                               |
|o2 = {x  - 6x  + 12x - 8, - x  + x  - x + y}                      |
|                                                                  |
|o2 : List                                                         |
+------------------------------------------------------------------+
|i3 : sols = solveSystem(T,PostProcess=>false);                    |
+------------------------------------------------------------------+
|i4 : p0 = first sols;                                             |
+------------------------------------------------------------------+
|i5 : peek p0                                                      |
|                                                                  |
|o5 = Point{cache => CacheTable{...5...}                          }|
|           Coordinates => {2.01079-.011783*ii, 434.14+1247.66*ii} |
+------------------------------------------------------------------+
|i6 : t'end = 1                                                    |
|                                                                  |
|o6 = 1                                                            |
+------------------------------------------------------------------+
|i7 : p = endGameCauchy(p0.cache#"H",t'end,p0)                     |
|                                                                  |
|o7 = p                                                            |
|                                                                  |
|o7 : Point                                                        |
+------------------------------------------------------------------+

See also
========

  * refine -- refine numerical solutions to a
    system of polynomial equations

Ways to use endGameCauchy :
===========================

  * "endGameCauchy(GateHomotopy,Number,AbstractPoint)"
  * "endGameCauchy(GateHomotopy,Number,MutableMatrix)"

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

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

evaluateH(GateHomotopy,Matrix,Number) -- evaluate gate homotopy and its derivatives
***********************************************************************************

Synopsis
========

  * Function: evaluateH (missing documentation)

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

  * evaluateH(GateHomotopy,Matrix,Number)
    -- evaluate gate homotopy
    and its derivatives

evaluateH(GateParameterHomotopy,Matrix,Matrix,Number) -- evaluate (gate) parameter homotopy and its derivatives
***************************************************************************************************************

Synopsis
========

  * Function: evaluateH (missing documentation)

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

  * evaluateH(GateParameterHomotopy,Matrix,Matrix,Number),
    --
    evaluate (gate) parameter homotopy and its derivatives

gateHomotopy(...,Parameters=>...) -- specifies parameter names
**************************************************************

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

  * Default value: null
  * Function: gateHomotopy,
    -- homotopy
    implemented via straight line programs
  * Option key: Parameters (NAGtypes), -- a collection of
    parameters

Functions with optional argument named Parameters :
===================================================

  * gateHomotopy(...,Parameters=>...)
    -- specifies parameter
    names

gateHomotopy(...,Software=>...) -- specifies where evaluation should be done (M2=top level, M2engine=core)
**********************************************************************************************************

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

  * Default value: null
  * Function: gateHomotopy,
    -- homotopy
    implemented via straight line programs
  * Option key: Software, -- specify internal or external
    software

Functions with optional argument named Software :
=================================================

  * gateHomotopy(...,Software=>...)
    -- specifies where
    evaluation should be done (M2=top level, M2engine=core)
  * "trackHomotopy(...,Software=>...)" -- see numerical homotopy tracking options,
    -- options for core functions
    of Numerical Algebraic Geometry
  * "hypersurfaceSection(...,Software=>...)" -- see Software,
    -- specify internal or external software
  * "isOn(...,Software=>...)" -- see Software, -- specify
    internal or external software
  * "numericalIrreducibleDecomposition(...,Software=>...)" -- see
    Software, -- specify internal or external software
  * "parameterHomotopy(...,Software=>...)" -- see Software, --
    specify internal or external software
  * "refine(...,Software=>...)" -- see Software, -- specify
    internal or external software
  * "regeneration(...,Software=>...)" -- see Software, --
    specify internal or external software
  * "setDefault(...,Software=>...)" -- see Software, -- specify
    internal or external software
  * "solveSystem(...,Software=>...)" -- see Software, --
    specify internal or external software
  * "track(...,Software=>...)" -- see Software, -- specify
    internal or external software

gateHomotopy(...,Strategy=>...) -- strategy is either to "compress" or not (any other value)
********************************************************************************************

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

  * Default value: compress (Macaulay2Doc),
  * Function: gateHomotopy,
    -- homotopy
    implemented via straight line programs
  * Option key: Strategy (Macaulay2Doc), -- an optional argument

Functions with optional argument named Strategy :
=================================================

  * "addHook(...,Strategy=>...)" -- see addHook (Macaulay2Doc),
    -- add a hook function to an object for later processing
  * "annihilator(...,Strategy=>...)" -- see annihilator (Saturation),
    -- the annihilator ideal
  * "associatedPrimes(...,Strategy=>...)" -- see associatedPrimes (PrimaryDecomposition),
    -- find associated primes
  * "basis(...,Strategy=>...)" -- see basis (Macaulay2Doc), --
    basis or generating set of all or part of a ring, ideal or module
  * "mingens(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * "trim(...,Strategy=>...)" -- see Complement (Macaulay2Doc),
    -- a Strategy option value
  * determinant(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "dual(MonomialIdeal,List,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * "dual(MonomialIdeal,RingElement,Strategy=>...)" -- see
    dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc),
  * dual(MonomialIdeal,Strategy=>...) (Macaulay2Doc)
  * exteriorPower(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * gateHomotopy(...,Strategy=>...)
    -- strategy is either to
    "compress" or not (any other value)
  * "gb(...,Strategy=>...)" -- see gb (Macaulay2Doc), -- compute a
    Gröbner basis
  * gcdLLL(...,Strategy=>...) (missing documentation)
  * "GF(...,Strategy=>...)" -- see GF (Macaulay2Doc), -- make a finite
    field
  * "groebnerBasis(...,Strategy=>...)" -- see groebnerBasis (Macaulay2Doc),
    -- Gröbner basis, as a matrix
  * hermite(...,Strategy=>...) (missing documentation)
  * "hooks(...,Strategy=>...)" -- see hooks (Macaulay2Doc), -- list
    hooks attached to a key
  * "idealizer(...,Strategy=>...)" -- see idealizer (IntegralClosure),
    -- compute Hom(I,I) as a quotient ring
  * integralClosure(...,Strategy=>...) (IntegralClosure),
    --
    control the algorithm used
  * "intersect(Ideal,Ideal,Strategy=>...)" -- see intersect(Ideal,Ideal) (Macaulay2Doc),
    -- compute an intersection of a
    sequence of ideals or modules
  * "intersect(Module,Module,Strategy=>...)" -- see
    intersect(Ideal,Ideal) (Macaulay2Doc), --
    compute an intersection of a sequence of ideals or modules
  * "intersectInP(...,Strategy=>...)" -- see
    intersectInP(...,BasisElementLimit=>...) (ReesAlgebra),
    --
    Option for intersectInP
  * "isPrimary(...,Strategy=>...)" -- see isPrimary (PrimaryDecomposition),
    -- determine whether a submodule is
    primary
  * "isPrime(Ideal,Strategy=>...)" -- see isPrime(Ideal) (MinimalPrimes),
    -- whether an ideal is prime
  * LLL(...,Strategy=>...) (LLLBases)
    -- choose among
    different algorithms
  * "localize(...,Strategy=>...)" -- see localize (PrimaryDecomposition),
    -- localize an ideal at a prime ideal
  * "match(...,Strategy=>...)" -- see match (Macaulay2Doc), --
    regular expression matching
  * "decompose(Ideal,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * "minimalPrimes(...,Strategy=>...)" -- see minimalPrimes (MinimalPrimes),
    -- minimal primes of an ideal
  * minors(...,Strategy=>...) (Macaulay2Doc)
    -- choose
    between Bareiss, Cofactor and Dynamic algorithms
  * "primaryComponent(...,Strategy=>...)" -- see primaryComponent (PrimaryDecomposition),
    -- find a primary component
    corresponding to an associated prime
  * pushForward(...,Strategy=>...) (missing documentation)
  * quotient(...,Strategy=>...) (Saturation)
  * "radical(...,Strategy=>...)" -- see radical (MinimalPrimes),
    -- the radical of an ideal
  * "radicalContainment(...,Strategy=>...)" -- see radicalContainment (MinimalPrimes),
    -- whether an element is contained in
    the radical of an ideal
  * "analyticSpread(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "distinguished(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isLinearType(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "isReduction(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "minimalReduction(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "multiplicity(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "normalCone(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "reesAlgebra(...,Strategy=>...)" -- see reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * reesIdeal(...,Strategy=>...) (ReesAlgebra)
    -- Choose a
    strategy for the saturation step
  * "specialFiber(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "specialFiberIdeal(...,Strategy=>...)" -- see
    reesIdeal(...,Strategy=>...) (ReesAlgebra),
    -- Choose a
    strategy for the saturation step
  * "regSeqInIdeal(...,Strategy=>...)" -- see regSeqInIdeal (PrimaryDecomposition),
    -- a regular sequence contained in an
    ideal
  * resolution(...,Strategy=>...) (Macaulay2Doc)
  * saturate(...,Strategy=>...) (Saturation)
  * "primaryDecomposition(...,Strategy=>...)" -- see strategies for computing primary decomposition (PrimaryDecomposition),
  * "syz(...,Strategy=>...)" -- see syz(Matrix) (Macaulay2Doc),
    -- compute the syzygy matrix
  * "tangentCone(...,Strategy=>...)" -- see tangentCone(Ideal) (TangentCone),

gateHomotopy(GateMatrix,GateMatrix,InputGate) -- homotopy implemented via straight line programs
************************************************************************************************

Synopsis
========

  * Function: gateHomotopy,
  * Usage:
        HS = gateHomotopy(H,X,T)
  * Inputs:
      * H, an instance of the type GateMatrix (SLPexpressions),
        a family of systems (given by a column
        vector)
      * X, an instance of the type GateMatrix (SLPexpressions),
        (a row vector of) variables
      * T, an instance of the type InputGate (SLPexpressions),
        homotopy (continuation) parameter
  * Optional inputs (Macaulay2Doc),:
      * Parameters,
        => ..., default value null, specifies parameter names
      * Software, =>
        ..., default value null, specifies where evaluation should be done
        (M2=top level, M2engine=core)
      * Strategy, =>
        ..., default value compress, strategy is either to "compress" or not
        (any other value)
  * Outputs:
      * HS
      * an instance of the type GateHomotopy,
        or an instance
        of the type GateParameterHomotopy, a
        homotopy that can be used with some routines of
        NumericalAlgebraicGeometry,

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

Optional arguments:
  * Software,-- specifies how the homotopy is evaluated:
    (M2,M2engine)
+-----------------------------------------------------------------------------+
|i1 : X = inputGate symbol X                                                  |
|                                                                             |
|o1 = X                                                                       |
|                                                                             |
|o1 : InputGate                                                               |
+-----------------------------------------------------------------------------+
|i2 : Y = inputGate symbol Y                                                  |
|                                                                             |
|o2 = Y                                                                       |
|                                                                             |
|o2 : InputGate                                                               |
+-----------------------------------------------------------------------------+
|i3 : T = inputGate symbol T                                                  |
|                                                                             |
|o3 = T                                                                       |
|                                                                             |
|o3 : InputGate                                                               |
+-----------------------------------------------------------------------------+
|i4 : F = {X*X-1, Y*Y*Y-1}                                                    |
|                                                                             |
|o4 = {((X * X) + -1), (((Y * Y) * Y) + -1)}                                  |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : G = {X*X+Y*Y-1, X*X*X+Y*Y*Y-1}                                          |
|                                                                             |
|o5 = {(((X * X) + (Y * Y)) + -1), ((((X * X) * X) + ((Y * Y) * Y)) + -1)}    |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+
|i6 : H = (1 - T) * F + T * G                                                 |
|                                                                             |
|o6 = {(((1 + (-1 * T)) * ((X * X) + -1)) + (T * (((X * X) + (Y * Y)) + -1))),|
|     ------------------------------------------------------------------------|
|     (((1 + (-1 * T)) * (((Y * Y) * Y) + -1)) + (T * ((((X * X) * X) + ((Y * |
|     ------------------------------------------------------------------------|
|     Y) * Y)) + -1)))}                                                       |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : HS = gateHomotopy(transpose matrix {H},matrix{{X,Y}},T)                 |
|                                                                             |
|o7 = GateHomotopy{...11...}                                                  |
|                                                                             |
|o7 : GateHomotopy                                                            |
+-----------------------------------------------------------------------------+

Caveat
======

The order of inputs for unexported internal evaluation functions (evaluateH,
etc.) is fixed as follows: Parameters, X, T.

See also
========

  * GateHomotopy,
    -- homotopy implemented via straight line programs
  * GateParameterHomotopy -- a homotopy that
    involves parameters and is implemented via straight line programs
  * specialize (missing documentation)

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

  * gateHomotopy(GateMatrix,GateMatrix,InputGate)
    -- homotopy
    implemented via straight line programs

gateMatrix(GateSystem) -- evaluation circuit used for the system
****************************************************************

Synopsis
========

  * Function: gateMatrix (SLPexpressions),

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

This method returns the GateMatrix (SLPexpressions), used to
evaluate the system.

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

  * gateMatrix(GateSystem) -- evaluation
    circuit used for the system

GateParameterHomotopy -- a homotopy that involves parameters and is implemented via straight line programs
**********************************************************************************************************

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

An object of this type specializes to a Homotopy (NAGtypes),
given values of the parameters. It is related to GateHomotopy.

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

  * evaluateH(GateParameterHomotopy,Matrix,Matrix,Number),
    --
    evaluate (gate) parameter homotopy and its derivatives
  * "evaluateHt(GateParameterHomotopy,Matrix,Matrix,Number)" -- see
    evaluateH(GateParameterHomotopy,Matrix,Matrix,Number),
    --
    evaluate (gate) parameter homotopy and its derivatives
  * "evaluateHx(GateParameterHomotopy,Matrix,Matrix,Number)" -- see
    evaluateH(GateParameterHomotopy,Matrix,Matrix,Number),
    --
    evaluate (gate) parameter homotopy and its derivatives
  * specialize(GateParameterHomotopy,MutableMatrix)
    -- specialize
    parameters in a (gate) parameter homotopy

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

The object GateParameterHomotopy, is a type (Macaulay2Doc),
with ancestor classes ParameterHomotopy (NAGtypes),
< MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

GateSystem -- a system of functions evaluated via a straightline program
************************************************************************

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

An object of this type is a system of functions evaluated via an SLP that is
constructed using the tools of package SLPexpressions.

An object of this type (constructed with gateSystem) is a
System (NAGtypes), of functions represented via a
GateMatrix (SLPexpressions). In particular, polynomial systems and
systems of rational functions can be represented this way.

Unlike PolySystem (NAGtypes), the functions of a
GateSystem, do not belong to a ring and can be evaluated on
Number (Macaulay2Doc),s and RingElement (Macaulay2Doc),
s as long as the constants in the evaluation circuits
can be promoted to the corresponding Ring (Macaulay2Doc),s.

See also
========

  * gateSystem -- a constructor for GateSystem
  * gateMatrix(GateSystem) -- evaluation
    circuit used for the system
  * vars(GateSystem) -- the variable gates in the
    evaluation circuit used for the system
  * parameters(GateSystem) -- the parameter
    gates in the evaluation circuit used for the system
  * System (NAGtypes) -- a system of functions
  * PolySystem (NAGtypes) -- a polynomial system

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

  * "gateSystem(Matrix)" -- see gateSystem, -- a constructor
    for GateSystem
  * "gateSystem(PolySystem)" -- see gateSystem, -- a
    constructor for GateSystem

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

  * gateMatrix(GateSystem) -- evaluation
    circuit used for the system
  * "evaluate(GateSystem,Matrix,Matrix)"
  * "net(GateSystem)"
  * "numFunctions(GateSystem)"
  * "numParameters(GateSystem)"
  * "numVariables(GateSystem)"
  * jacobian(GateSystem) -- jacobian of a
    (gate) system
  * "jacobian(List,GateSystem)" -- see jacobian(GateSystem),
    -- jacobian of a (gate) system
  * parameters(GateSystem) -- the parameter
    gates in the evaluation circuit used for the system
  * "parametricSegmentHomotopy(GateSystem)" -- see
    parametricSegmentHomotopy, -- creates an ansatz
    for a segment homotopy
  * "segmentHomotopy(GateSystem,GateSystem)" -- see segmentHomotopy,
    -- a segment homotopy
  * vars(GateSystem) -- the variable gates in the
    evaluation circuit used for the system

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

The object GateSystem, is a type (Macaulay2Doc),
with ancestor classes System (NAGtypes), < MutableHashTable (Macaulay2Doc)
< HashTable (Macaulay2Doc) <
Thing (Macaulay2Doc).

gateSystem -- a constructor for GateSystem
******************************************

Synopsis
========

  * Usage:
        gateSystem(params,variables,M)
        gateSystem(variables,M)
  * Inputs:
      * M, an instance of the type GateMatrix (SLPexpressions),
      * parameters, an instance of the type GateMatrix (SLPexpressions),
      * variables, an instance of the type GateMatrix (SLPexpressions),

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

See GateMatrix (SLPexpressions), M is expected to have 1 column.
Matrices params and variables are expected to have 1 row.

+-------------------------------------------------------------------+
|i1 : variables = declareVariable \ {x,y}                           |
|                                                                   |
|o1 = {x, y}                                                        |
|                                                                   |
|o1 : List                                                          |
+-------------------------------------------------------------------+
|i2 : F = gateSystem(matrix{variables}, matrix{{x*y-1},{x^3+y^2-2}})|
|                                                                   |
|o2 = gate system: 2 ---> 2                                         |
|                                                                   |
|o2 : GateSystem                                                    |
+-------------------------------------------------------------------+
|i3 : evaluate(F,point{{0.1,0.2+ii}})                               |
|                                                                   |
|o3 = | -.98+.1ii -2.959+.4ii |                                     |
|                                                                   |
|                1          2                                       |
|o3 : Matrix CC    <--- CC                                          |
|              53         53                                        |
+-------------------------------------------------------------------+
|i4 : evaluate(F,point{{1/2,1/3}})                                  |
|                                                                   |
|o4 = | -5/6 -127/72 |                                              |
|                                                                   |
|              1        2                                           |
|o4 : Matrix QQ  <--- QQ                                            |
+-------------------------------------------------------------------+
|i5 : evaluate(F,point{{2_(ZZ/101),3}})                             |
|                                                                   |
|o5 = | 5 15 |                                                      |
|                                                                   |
|              ZZ 1        ZZ 2                                     |
|o5 : Matrix (---)  <--- (---)                                      |
|             101         101                                       |
+-------------------------------------------------------------------+

Systems with parameters are allowed.

+-----------------------------------------------------------------------------+
|i6 : params = declareVariable \ {a,b}                                        |
|                                                                             |
|o6 = {a, b}                                                                  |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+
|i7 : Fab = gateSystem(matrix{params}, matrix{variables},                     |
|                                                                             |
|o7 = gate system: 2 ---> 2                                                   |
|     (#parameters = 2)                                                       |
|                                                                             |
|o7 : GateSystem                                                              |
|-----------------------------------------------------------------------------|
|matrix{{a*x*y-1},{x^3+y^2-b}})                                               |
+-----------------------------------------------------------------------------+
|i8 : evaluate(Fab,point{{1,2}},point{{0.1,0.2+ii}})                          |
|                                                                             |
|o8 = | -.98+.1ii -2.959+.4ii |                                               |
|                                                                             |
|                1          2                                                 |
|o8 : Matrix CC    <--- CC                                                    |
|              53         53                                                  |
+-----------------------------------------------------------------------------+

Caveat
======

Note for developers: there is a version of the constructor that builds
GateSystem, from PolySystem (NAGtypes). Its
variant that takes the list of variables to treat as parameters is likely to
disappear.

See also
========

  * System (NAGtypes) -- a system of functions
  * PolySystem (NAGtypes) -- a polynomial system
  * GateSystem -- a system of functions evaluated via a
    straightline program

Ways to use gateSystem :
========================

  * "gateSystem(GateMatrix,GateMatrix)"
  * "gateSystem(GateMatrix,GateMatrix,GateMatrix)"
  * "gateSystem(Matrix)"
  * "gateSystem(PolySystem)"
  * "gateSystem(PolySystem,List)"

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

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

goodInitialPair(List) -- make an initial pair conjectured to be good by Shub and Smale
**************************************************************************************

Synopsis
========

  * Function: goodInitialPair,
  * Usage:
        (S,sol) = goodInitialPair T
  * Inputs:
      * T, a list (Macaulay2Doc), contains homogeneous polynomials
  * Optional inputs (Macaulay2Doc),:
      * GeneralPosition => ..., default value false, make a random unitary
        change of coordinates
  * Outputs:
      * S, contains homogeneous polynomials
      * sol, contains one solution of S

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

Generates a start system S that is conjectured to have good complexity when
used in linear homotopy with target system T leading to one solution. For more
details see: C. Beltran and A. Leykin, "Certified numerical homotopy tracking",
Experimental Mathematics 21(1): 69-83 (2012)

+--------------------------------------------------------------------+
|i1 : T = randomSd {2,3};                                            |
+--------------------------------------------------------------------+
|i2 : (S,solsS) = goodInitialPair T                                  |
|                                                                    |
|                                 2                                  |
|o2 = ({1.41421x1*x3, 1.73205x2*x3 }, {{0, 0, 1}})                   |
|                                                                    |
|o2 : Sequence                                                       |
+--------------------------------------------------------------------+
|i3 : M = track(S,T,solsS,gamma=>0.6+0.8*ii,Software=>M2)            |
|                                                                    |
|o3 = {{.751732+.463283*ii, .284351-.0717164*ii, .348144-.114302*ii}}|
|                                                                    |
|o3 : List                                                           |
+--------------------------------------------------------------------+

See also
========

  * Certified -- a value for the option Predictor that
    triggers certified tracking
  * track -- track a linear segment
    homotopy given start and target system

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

  * goodInitialPair(List) -- make an initial
    pair conjectured to be good by Shub and Smale

HOM4PS2 -- use HOM4PS for homotopy continuation
***********************************************

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

Available at http://hom4ps.math.msu.edu/HOM4PS_soft.htm

See also
========

  * Software -- specify internal or external software

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

The object HOM4PS2, is a symbol (Macaulay2Doc).

isOn -- determines if a point belongs to a variety
**************************************************

Synopsis
========

  * Usage:
        B = isOn(P,V)
  * Inputs:
      * P, a point (NAGtypes),
      * V, a numerical variety (NAGtypes), a
        witness set (NAGtypes), an ideal (Macaulay2Doc),
        or a ring element (Macaulay2Doc),
  * Optional inputs (Macaulay2Doc),:
      * Software, => ..., default value null, specify internal
        or external software
      * Tolerance => ..., default value null
  * Outputs:
      * B, a Boolean value (Macaulay2Doc),

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

Determines whether the given point is (approximately) on the given variety,
which is either represented numerically or defines by polynomials.
+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y]                                                             |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal((x^2+y^2+2)*x,(x^2+y^2+2)*y);                                 |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : e = 0.0000001                                                           |
|                                                                             |
|o3 = 1e-7                                                                    |
|                                                                             |
|o3 : RR (of precision 53)                                                    |
+-----------------------------------------------------------------------------+
|i4 : W = witnessSet(ideal I_0 , ideal(x-y), {point {{                        |
|                                                                             |
|o4 = W                                                                       |
|                                                                             |
|o4 : WitnessSet                                                              |
|-----------------------------------------------------------------------------|
|(1-e)*ii,(1-e)*ii}},point {{ -(1+e)*ii,-(1+e)*ii}}})                         |
+-----------------------------------------------------------------------------+
|i5 : isOn(point {{sqrt 5*ii,sqrt 3}},W)                                      |
|                                                                             |
|o5 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * Point (NAGtypes) -- a type used to store a point in
    complex space
  * NumericalVariety (NAGtypes) -- a numerical variety

Ways to use isOn :
==================

  * "isOn(AbstractPoint,Ideal)"
  * "isOn(AbstractPoint,NumericalVariety)"
  * "isOn(AbstractPoint,RingElement)"
  * "isOn(AbstractPoint,WitnessSet)"
  * "isOn(AbstractPoint,WitnessSet,ZZ)"

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

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

isSolution(AbstractPoint,PolySystem) -- check if a point satisfies a polynomial system approximately
****************************************************************************************************

Synopsis
========

  * Function: isSolution,
  * Optional inputs (Macaulay2Doc),:
      * Tolerance => ..., default value null

Caveat
======

Either rewrite or phase out!!!

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

  * isSolution(AbstractPoint,PolySystem)
    -- check if a point satisfies a
    polynomial system approximately

isSubset(NumericalVariety,NumericalVariety) -- check containment
****************************************************************

Synopsis
========

  * Function: isSubset (Macaulay2Doc),
  * Usage:
        B = isSubset(V,W)
  * Inputs:
      * V, a numerical variety (NAGtypes),  or a
        witness set (NAGtypes),
      * W, a numerical variety (NAGtypes),  or a
        witness set (NAGtypes),
  * Outputs:
      * B, a Boolean value (Macaulay2Doc),

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

Checks containment of one variety represented numerically in the other.

Caveat
======

Does not work for singular components.

See also
========

  * WitnessSet (NAGtypes) -- a witness set
  * isOn -- determines if a point belongs to a variety

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

  * isSubset(NumericalVariety,NumericalVariety)
    -- check containment
  * "isSubset(WitnessSet,WitnessSet)"

jacobian(GateSystem) -- jacobian of a (gate) system
***************************************************

Synopsis
========

  * Function: jacobian (Macaulay2Doc),

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

  * jacobian(GateSystem) -- jacobian of a
    (gate) system
  * "jacobian(List,GateSystem)"

NAGtrace(ZZ) -- set the trace level in NumericalAlgebraicGeometry package
*************************************************************************

Synopsis
========

  * Function: NAGtrace,
  * Usage:
        a = NAGtrace b
  * Inputs:
      * an integer (Macaulay2Doc), b, the new level
  * Outputs:
      * a, the old level

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

Determines how talkative the procedures of NumericalAlgebraicGeometry are. The
most meaningful values are:
  * 0 -- silent
  * 1 -- progress and timings
  * 2 -- more messages than 1
The progress is displayed as follows:
  * . = regular solution found
  * S = singular solution (or encountered a singular point on the path)
  * I = a homotopy path diverged to infinity
  * M = minimum step bound reached
+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : S = {x^2-1,y^2-1};                                                      |
+-----------------------------------------------------------------------------+
|i3 : T = {x^2+y^2-1, x+y};                                                   |
+-----------------------------------------------------------------------------+
|i4 : NAGtrace 1                                                              |
|                                                                             |
|o4 = 0                                                                       |
+-----------------------------------------------------------------------------+
|i5 : track(S,T,{(1,1),(1,-1),(-1,1),(-1,-1)})                                |
|                                                                             |
|.M.MSetup time: 0                                                            |
|Computing time:0                                                             |
|                                                                             |
|o5 = {{.707107, -.707107}, [M,t=.465282], {-.707107, .707107}, [M,t=.465282]}|
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

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

  * NAGtrace(ZZ) -- set the trace level in
    NumericalAlgebraicGeometry package

newton -- Newton-Raphson method
*******************************

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

Performs one step of the Newton-Raphson method.

Caveat
======

Works for a regular square or overdetermined system.

Ways to use newton :
====================

  * "newton(PolySystem,AbstractPoint)"
  * "newton(PolySystem,Matrix)"

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

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

numerical homotopy tracking options -- options for core functions of Numerical Algebraic Geometry
*************************************************************************************************

  * [gamma]:  (default gamma = 1). A parameter in the homotopy:
    H(t)=(1-t)^{tDegree} S + \gamma t^{tDegree} T.
  * [tDegree]:  (default tDegree = 1). A parameter in the homotopy:
    H(t)=(1-t)^{tDegree} S + \gamma t^{tDegree} T.
  * [tStep]:  (default tStep = .05). Initial step size.
  * [tStepMin]:  (default tStepMin = .000001). Minimal step size.
  * [stepIncreaseFactor]:  (default stepIncreaseFactor = 2). Determines how the
    step size is adjusted.
  * [numberSuccessesBeforeIncrease]:  (default numberSuccessesBeforeIncrease =
    4). Determines how the step size is adjusted.
  * [Predictor]:  (default Predictor = RungeKutta4). A method to predict the
    next point on the homotopy path: choose between RungeKutta4,
    see Tangent,
    see Euler,
    Secant, Multistep,
    see Certified. The option
    Certified, provides certified tracking.
  * [MultistepDegree]:  (default MultistepDegree = 3). Degree of the Multistep
    predictor.
  * [maxCorrSteps]:  (default maxCorrSteps = 3). Max number of steps corrector
    takes before a failure is declared.
  * [CorrectorTolerance]:  (default CorrectorTolerance = .000001). Corrector
    succeeds if the relative error does not exceed this tolerance.
  * [EndZoneFactor]:  (default EndZoneFactor = .05). Determines the size of the
    "end zone", the interval at the end of the path where
    CorrectorTolerance, is tighter.
  * [InfinityThreshold]:  (default InfinityThreshold = 1e9). Paths are
    truncated if the norm of the approximation exceeds the threshold.
  * [Projectivize]:  (default Projectivize = false). If true then the system is
    homogenized and the projective tracker is executed.
  * [Normalize]:  (default Normalize = false). Normalize the start and target
    systems w.r.t. the Bombieri-Weyl norm.
  * [NoOutput]:  (default NoOutput = false). If true, no output is produced
    (used by developers).
  * [Iterations]:  (default Iterations = 30). Number of refining iterations of
    Newton's method.
  * [Bits]:  (default Bits = infinity). Number of bits of precision.
  * [ErrorTolerance]:  (default ErrorTolerance = 1e-8). A bound on the desired
    estimated error.
  * [ResidualTolerance]:  (default ResidualTolerance = .0001). A bound on
    desired residual.
  * [Precision]:  (default Precision = 53). Precision of the floating-point
    numbers used in computation. If set to infinity (Macaulay2Doc),
    (EXPERIMENTAL!) the precision in homotopy
    continuation adapts according to numerical conditioning. The default
    setting, DoublePrecision, forces fast arithmetic and linear algebra in
    standard precision. (Other settings invoke MPFR library.)

numericalIntersection -- intersection of numerical varieties
************************************************************

Caveat
======

Under construction!!!

Ways to use numericalIntersection :
===================================

  * "numericalIntersection(NumericalVariety,Ideal)"
  * "numericalIntersection(NumericalVariety,NumericalVariety)"
  * "numericalIntersection(WitnessSet,WitnessSet)"

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

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

numericalIrreducibleDecomposition(Ideal) -- constructs a numerical variety defined by the given ideal
*****************************************************************************************************

Synopsis
========

  * Function: numericalIrreducibleDecomposition,
  * Usage:
        V = numericalIrreducibleDecomposition I
  * Inputs:
      * I, an ideal (Macaulay2Doc), contained in the ring of
        polynomials with complex coefficients
  * Optional inputs (Macaulay2Doc),:
      * Software, => ..., default value null, specify internal
        or external software
  * Outputs:
      * V

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

The witness sets (NAGtypes), of the numerical variety (NAGtypes),
V are in one-to-one correspondence with irreducible
components of the variety defined by I.
+---------------------------------------------+
|i1 : R = CC[x,y,z]                           |
|                                             |
|o1 = R                                       |
|                                             |
|o1 : PolynomialRing                          |
+---------------------------------------------+
|i2 : sph = (x^2+y^2+z^2-1);                  |
+---------------------------------------------+
|i3 : I = ideal {sph*(y-x^2), sph*(z-x^3)};   |
|                                             |
|o3 : Ideal of R                              |
+---------------------------------------------+
|i4 : numericalIrreducibleDecomposition I     |
|                                             |
|o4 = a "numerical variety" with components in|
|     dim 1:  (dim=1,deg=3)                   |
|     dim 2:  (dim=2,deg=2)                   |
|                                             |
|o4 : NumericalVariety                        |
+---------------------------------------------+

Caveat
======

This function is under development. It may not work well if the input
represents a nonreduced scheme.

See also
========

  * decompose(WitnessSet) (missing documentation)

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

  * numericalIrreducibleDecomposition(Ideal)
    -- constructs a numerical
    variety defined by the given ideal

parameterHomotopy(List,List,List) -- solve a parametric system of equations
***************************************************************************

Synopsis
========

  * Function: parameterHomotopy,
  * Usage:
        sols = parameterHomotopy(F,varsP,valuesP)
  * Inputs:
      * F, a list (Macaulay2Doc),  contains the polynomials in the
        system
      * varsP, a list (Macaulay2Doc),  names of the parameters
      * valuesP, a list (Macaulay2Doc),  contains (possibly several
        sets of) values of the parameters
  * Optional inputs (Macaulay2Doc),:
      * Software, => ..., default value null, specify internal
        or external software
  * Outputs:
      * sols, a list (Macaulay2Doc),  lists of lists of solutions
        for each set of the parameters

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

Solves a parameteric polynomial system for several values of parameters.
+-----------------------------------------------------------------------------+
|i1 : R = CC[u1,u2,u3,x,y]                                                    |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : f1 = u1*(y-1)+u2*(y-2)+u3*(y-3)                                         |
|                                                                             |
|o2 = u1*y + u2*y + u3*y - u1 - 2u2 - 3u3                                     |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : f2 = (x-11)*(x-12)*(x-13)                                               |
|                                                                             |
|      3      2                                                               |
|o3 = x  - 36x  + 431x - 1716                                                 |
|                                                                             |
|o3 : R                                                                       |
+-----------------------------------------------------------------------------+
|i4 : try parameterHomotopy({f1,f2},{u1,u2,u3},{{1,0,0},{0,1+2*ii,0}},        |
|sh: 1: bertini: not found                                                    |
|true                                                                         |
|                                                                             |
|                                                                             |
|o4 = need to install Bertini to run these lines                              |
|-----------------------------------------------------------------------------|
|Software=>BERTINI) else "need to install Bertini to run these lines"         |
+-----------------------------------------------------------------------------+

Caveat
======

Available only with Software=>BERTINI at the moment...

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

  * parameterHomotopy(List,List,List)
    -- solve a parametric system of
    equations

parameters(GateSystem) -- the parameter gates in the evaluation circuit used for the system
*******************************************************************************************

Synopsis
========

  * Function: parameters (NAGtypes),

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

This method returns the 1-row GateMatrix (SLPexpressions),
that contains InputGate (SLPexpressions),s that are considered
parameters for the evaluation circuit.

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

  * parameters(GateSystem) -- the parameter
    gates in the evaluation circuit used for the system

parametricSegmentHomotopy -- creates an ansatz for a segment homotopy
*********************************************************************

Synopsis
========

  * Usage:
        PH = parametricSegmentHomotopy F
  * Inputs:
      * F, an instance of the type System (NAGtypes), either a
        GateSystem, or a PolySystem (NAGtypes),
  * Outputs:
      * PH, an instance of the type GateParameterHomotopy,

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

This method returns a homotopy that after specialization of parameters is akin
to the output of segmentHomotopy. There are 2 m
parameters inPH where m is the number of parameters in F. The first m
parameters correspond to the starting point A in the parameter space. The last
m parameters correspond to the end point B in the parameter space.

Ways to use parametricSegmentHomotopy :
=======================================

  * "parametricSegmentHomotopy(GateSystem)"
  * "parametricSegmentHomotopy(PolySystem)"

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

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

PHCPACK -- use PHCpack for homotopy continuation
************************************************

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

Available at http://www.math.uic.edu/~jan/download.html

PHCpack interface provided via the PHCpack, package.

See also
========

  * Software -- specify internal or external software

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

The object PHCPACK, is a symbol (Macaulay2Doc).

randomInitialPair -- a random initial pair
******************************************

Synopsis
========

  * Usage:
        (S,sol) = randomInitialPair T
  * Inputs:
      * T, contains homogeneous polynomials
  * Outputs:
      * S, contains homogeneous polynomials
      * sol, contains one solution of S

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

Generates a start system S that has an equal chance of reaching any of the
solutions of the target system T. For more details see: C. Beltran and A.
Leykin, "Certified numerical homotopy tracking", Experimental Mathematics
21(1): 69-83 (2012)

+-----------------------------------------------------------------------------+
|i1 : T = randomSd {2,3};                                                     |
+-----------------------------------------------------------------------------+
|i2 : (S,solsS) = randomInitialPair T                                         |
|                                                                             |
|                               2                                             |
|o2 = ({(.244218 - .220355*ii)x1  + (.539808 + .144395*ii)x1*x2 + (- .221394 -|
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     .0613168*ii)x2  + (- .259397 - .00345748*ii)x1*x3 + (- .178951 -        |
|     ------------------------------------------------------------------------|
|                                                   2                         |
|     .107379*ii)x2*x3 + (- .0128909 - .144621*ii)x3 , (.359958 -             |
|     ------------------------------------------------------------------------|
|                   3                           2                             |
|     .0342736*ii)x1  + (.221311 + .556399*ii)x1 x2 + (- .133948 +            |
|     ------------------------------------------------------------------------|
|                     2                              3                        |
|     .240825*ii)x1*x2  + (- .299729 - .0133971*ii)x2  + (- .119922 -         |
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     .0166779*ii)x1 x3 + (.132036 + .509053*ii)x1*x2*x3 + (- .0926582 +      |
|     ------------------------------------------------------------------------|
|                   2                                  2                      |
|     .0968547*ii)x2 x3 + (- .710775 + .256295*ii)x1*x3  + (- .104174 +       |
|     ------------------------------------------------------------------------|
|                     2                          3                            |
|     .202058*ii)x2*x3  + (.170022 - .20222*ii)x3 }, {{-.710384+.284524*ii,   |
|     ------------------------------------------------------------------------|
|     .183054-.427437*ii, .40779-.178596*ii}})                                |
|                                                                             |
|o2 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i3 : M = track(S,T,solsS,gamma=>0.6+0.8*ii,Software=>M2)                     |
|                                                                             |
|o3 = {{-.526105-.010808*ii, -.10453-.322525*ii, .60848-.487749*ii}}          |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * Certified -- a value for the option Predictor that
    triggers certified tracking

Ways to use randomInitialPair :
===============================

  * "randomInitialPair(List)"

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

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

randomSd(List) -- a random homogeneous system of polynomial equations
*********************************************************************

Synopsis
========

  * Function: randomSd,
  * Usage:
        T = randomSd d
  * Inputs:
      * d, a list (Macaulay2Doc), contains the degrees
  * Outputs:
      * T, contains polynomials

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

Generates a system of homogeneous polynomials T_i such that deg(T_i) = d_i. The
system is normalized, so that it is on the unit sphere in the Bombieri-Weyl
norm.

+-----------------------------------------------------------------------------+
|i1 : T = randomSd {2,3}                                                      |
|                                                                             |
|                              2                                              |
|o1 = {(.125583 - .231255*ii)x1  + (- .0106283 + .495511*ii)x1*x2 + (.140689 -|
|     ------------------------------------------------------------------------|
|                   2                                                         |
|     .0470904*ii)x2  + (- .395888 - .177428*ii)x1*x3 + (- .3032 -            |
|     ------------------------------------------------------------------------|
|                                                  2                          |
|     .259731*ii)x2*x3 + (.00470858 - .244829*ii)x3 , (- .130206 -            |
|     ------------------------------------------------------------------------|
|                  3                            2                             |
|     .186531*ii)x1  + (- .17129 + .368432*ii)x1 x2 + (- .246583 +            |
|     ------------------------------------------------------------------------|
|                     2                             3                         |
|     .719498*ii)x1*x2  + (- .143827 + .153796*ii)x2  + (- .157571 -          |
|     ------------------------------------------------------------------------|
|                2                                                            |
|     .1962*ii)x1 x3 + (- .0910157 + .825927*ii)x1*x2*x3 + (.0624194 -        |
|     ------------------------------------------------------------------------|
|                  2                                   2                      |
|     .242607*ii)x2 x3 + (- .234055 - .0910887*ii)x1*x3  + (- .0833408 +      |
|     ------------------------------------------------------------------------|
|                     2                            3                          |
|     .155138*ii)x2*x3  + (.134672 + .0401753*ii)x3 }                         |
|                                                                             |
|o1 : List                                                                    |
+-----------------------------------------------------------------------------+
|i2 : (S,solsS) = goodInitialPair T;                                          |
+-----------------------------------------------------------------------------+
|i3 : M = track(S,T,solsS,gamma=>0.6+0.8*ii,Software=>M2)                     |
|                                                                             |
|o3 = {{.751732+.463283*ii, .284351-.0717164*ii, .348144-.114302*ii}}         |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * Certified -- a value for the option Predictor that
    triggers certified tracking
  * track -- track a linear segment
    homotopy given start and target system

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

  * randomSd(List) -- a random homogeneous system of
    polynomial equations

refine(List,List) -- refine numerical solutions to a system of polynomial equations
***********************************************************************************

Synopsis
========

  * Function: refine,
  * Usage:
        solsR = refine(T,sols)
  * Inputs:
      * T, a list (Macaulay2Doc), contains the polynomials of the
        system (may be of type PolySystem (NAGtypes))
      * sols, a list (Macaulay2Doc), contains (a) solution(s)
        (see points (NAGtypes), or lists of coordinates of
        points)
  * Optional inputs (Macaulay2Doc),:
      * Bits, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * ErrorTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * Iterations, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * ResidualTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * SingularConditionNumber, => ..., default value null,
        set/get the default parameters for continuation algorithms
      * Software, => ..., default value null, specify internal
        or external software
  * Outputs:
      * solsR, a list (Macaulay2Doc), contains refined solutions
        (as points (NAGtypes))

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

Uses Newton's method to correct the given solutions so that the resulting
approximation has its estimated relative error bounded by min(see
ErrorTolerance,2^(-see Bits)).
The number of iterations made is at most
Iterations.

+-----------------------------------------------------------------------------+
|i1 : R = CC[x];                                                              |
+-----------------------------------------------------------------------------+
|i2 : F = polySystem {x^2-2};                                                 |
+-----------------------------------------------------------------------------+
|i3 : P := refine(F, point{{1.5+0.001*ii}}, Bits=>1000)                       |
|                                                                             |
|o3 = {1.41421}                                                               |
|                                                                             |
|o3 : Point                                                                   |
+-----------------------------------------------------------------------------+
|i4 : first coordinates P                                                     |
|                                                                             |
|o4 = 1.4142135623730950488016887242096980785696718753769480731766797379907324|
|     784621070388503875343276415727350138462309122970249248360558507372126441|
|     214970999358314132226659275055927557999505011527820605714701095599716059|
|     702745345968620147285174186408891986095523292304843087143214508397626036|
|     2799525140799                                                           |
|                                                                             |
|o4 : CC (of precision 1002)                                                  |
+-----------------------------------------------------------------------------+
|i5 : R = CC[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i6 : T = {x^2+y^2-1, x*y};                                                   |
+-----------------------------------------------------------------------------+
|i7 : sols = { {1.1,-0.1}, {0.1,1.2} };                                       |
+-----------------------------------------------------------------------------+
|i8 : refine(T, sols, Software=>M2, ErrorTolerance=>.001, Iterations=>10)     |
|                                                                             |
|o8 = {{1, -2.17629e-17}, {7.01931e-15, 1}}                                   |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

In case of a singular (multiplicity>1) solution, while solveSystem,
and track, return
the end of the homotopy paths marked as a 'failure', it is possible to improve
the quality of approximation with refine. The
resulting point will be marked as singular:

+------------------------------------------------+
|i9 : R = CC[x,y];                               |
+------------------------------------------------+
|i10 : S = {x^2-1,y^2-1};                        |
+------------------------------------------------+
|i11 : T = {x^2+y^2-1, (x-y)^2};                 |
+------------------------------------------------+
|i12 : solsS = {(1,1),(-1,-1)};                  |
+------------------------------------------------+
|i13 : solsT = track(S,T,solsS)                  |
|                                                |
|o13 = {[M,t=.999998], [M,t=.999998]}            |
|                                                |
|o13 : List                                      |
+------------------------------------------------+
|i14 : solsT / coordinates                       |
|                                                |
|o14 = {{.70667, .707543}, {-.70667, -.707543}}  |
|                                                |
|o14 : List                                      |
+------------------------------------------------+
|i15 : refSols = refine(T, solsT)                |
|                                                |
|o15 = {(.707107, .707107), (-.707107, -.707107)}|
|                                                |
|o15 : List                                      |
+------------------------------------------------+
|i16 : refSols / status                          |
|                                                |
|o16 = {Singular, Singular}                      |
|                                                |
|o16 : List                                      |
+------------------------------------------------+

The failure to complete the refinement procedure is indicated by warning
messages and the resulting point is displayed as [R].

+----------------------------------------------------------------------+
|i17 : R = CC[x];                                                      |
+----------------------------------------------------------------------+
|i18 : F = polySystem {x^2-2};                                         |
+----------------------------------------------------------------------+
|i19 : Q := refine(F, point{{1.5+0.001*ii}}, Bits=>1000, Iterations=>2)|
|                                                                      |
|o19 = [RF]                                                            |
|                                                                      |
|o19 : Point                                                           |
+----------------------------------------------------------------------+
|i20 : peek Q                                                          |
|                                                                      |
|o20 = Point{cache => CacheTable{...4...}}                             |
|            Coordinates => {1.41422}                                  |
+----------------------------------------------------------------------+

Caveat
======

There are 2 'safety' bits in the computation. If the condition of the system at
the refined point is poor the number of correct bits may be much smaller than
requested.

See also
========

  * solveSystem -- solve a system of polynomial
    equations
  * track -- track a linear segment
    homotopy given start and target system

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

  * "refine(AbstractPoint)"
  * refine(List,List) -- refine numerical
    solutions to a system of polynomial equations
  * "refine(PolySystem,AbstractPoint)"
  * "refine(PolySystem,List)"

regeneration(List) -- solve a system of polynomial equations with regeneration method
*************************************************************************************

Synopsis
========

  * Function: regeneration,
  * Usage:
        Ws = regeneration F
  * Inputs:
      * F, a list (Macaulay2Doc), contains polynomials with complex
        coefficients
  * Optional inputs (Macaulay2Doc),:
      * Output => ..., default value Singular
      * Software, => ..., default value null, specify internal
        or external software
  * Outputs:
      * Ws, a list (Macaulay2Doc), contains witness sets (NAGtypes),
        for equidimensional components of the variety
        {x|F(x)=0}

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

Regeneration is a blackbox method that obtains a numerical description of an
algebraic variety. Note that Ws are not necessarily irreducible witness sets;
use decompose(WitnessSet), to decompose into
irreducibles.
+--------------------------------------------------------+
|i1 : R = CC[x,y]                                        |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : F = {x^2+y^2-1, x*y};                              |
+--------------------------------------------------------+
|i3 : regeneration F                                     |
|                                                        |
|o3 = a "numerical variety" with components in           |
|     dim 0:  [dim=0,deg=4]-*may be reducible*-          |
|                                                        |
|o3 : NumericalVariety                                   |
+--------------------------------------------------------+
|i4 : R = CC[x,y,z]                                      |
|                                                        |
|o4 = R                                                  |
|                                                        |
|o4 : PolynomialRing                                     |
+--------------------------------------------------------+
|i5 : sph = (x^2+y^2+z^2-1);                             |
+--------------------------------------------------------+
|i6 : regeneration {sph*(x-1)*(y-x^2), sph*(y-2)*(z-x^3)}|
|                                                        |
|o6 = a "numerical variety" with components in           |
|     dim 1:  [dim=1,deg=7]-*may be reducible*-          |
|     dim 2:  [dim=2,deg=2]-*may be reducible*-          |
|                                                        |
|o6 : NumericalVariety                                   |
+--------------------------------------------------------+

Caveat
======

This function is under development. It may not work well if the input
represents a nonreduced scheme.The (temporary) option Output,
can take two values: Regular (NAGtypes),
(default) and Singular (NAGtypes).
It specifies whether the algorithm attempts to keep
singular points.

See also
========

  * decompose(WitnessSet) (missing documentation)

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

  * regeneration(List) -- solve a system of
    polynomial equations with regeneration method

removeRedundantComponents(NumericalVariety) -- remove redundant components
**************************************************************************

Synopsis
========

  * Function: removeRedundantComponents,
  * Usage:
        removeRedundantComponents V
  * Inputs:
      * V, a numerical variety (NAGtypes),
  * Optional inputs (Macaulay2Doc),:
      * Tolerance => ..., default value null

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

Removes components contained in other components of the variety. (This is done
"in place".)

See also
========

  * isSubset(WitnessSet,WitnessSet) (missing documentation)

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

  * removeRedundantComponents(NumericalVariety)
    -- remove redundant
    components

sample(WitnessSet) -- sample a point on a component
***************************************************

Synopsis
========

  * Function: sample,
  * Usage:
        P = sample W
  * Inputs:
      * W, a witness set (NAGtypes),
  * Optional inputs (Macaulay2Doc),:
      * Tolerance => ..., default value .000001
  * Outputs:
      * P, an instance of the type Point (NAGtypes),

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

Gets a random point on a component represented numerically.
+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y,z]                                                           |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : W = witnessSet(ideal {x^2+y^2+z^2-1, z^2}, matrix "1,0,0,0",            |
|                                                                             |
|o2 = W                                                                       |
|                                                                             |
|o2 : WitnessSet                                                              |
|-----------------------------------------------------------------------------|
|{{{0,1,0_CC}},{{0,-1,0_CC}}}/point )                                         |
+-----------------------------------------------------------------------------+
|i3 : P := sample(W, Tolerance=>1e-15)                                        |
|                                                                             |
|o3 = (-1.08328-.110311*ii, -.252017+.474162*ii, -2.0883e-26-4.5498e-25*ii)   |
|                                                                             |
|o3 : Point                                                                   |
+-----------------------------------------------------------------------------+
|i4 : isOn(P,W)                                                               |
|                                                                             |
|o4 = true                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

not yet working for singular components

See also
========

  * WitnessSet (NAGtypes) -- a witness set
  * isOn -- determines if a point belongs to a variety

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

  * sample(WitnessSet) -- sample a point on a
    component

segmentHomotopy -- a segment homotopy
*************************************

Synopsis
========

  * Usage:
        H = segmentHomotopy(S,T)
  * Inputs:
      * S, an instance of the type System (NAGtypes), start
        system (could be GateSystem, PolySystem, or list of polynomials)
      * T, an instance of the type System (NAGtypes), target
        system  (could be GateSystem, PolySystem, or list of polynomials)
  * Optional inputs (Macaulay2Doc),:
      * gamma, => ..., default value
        1, options for core functions of Numerical Algebraic Geometry
  * Outputs:
      * H, an instance of the type GateHomotopy,

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

This method produces a Homotopy (NAGtypes), (1-t) S+ t \gamma T,
t\in[0,1].

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y]                                                             |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : T = {random(3,R)-1, random(2,R)-2}                                      |
|                                                                             |
|      9 3   1 2    9   2   1 3       2   3      3 2                          |
|o2 = {-x  + -x y + -x*y  + -y  - 1, x  + -x*y + -y  - 2}                     |
|      2     2      4       2             4      2                            |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : (S,solsS) = totalDegreeStartSystem T                                    |
|                                                                             |
|        3       2                                                            |
|o3 = ({x  - 1, y  - 1}, {{1, -1}, {-.5-.866025*ii, -1}, {-.5+.866025*ii, -1},|
|     ------------------------------------------------------------------------|
|     {-.5-.866025*ii, 1}, {1, 1}, {-.5+.866025*ii, 1}})                      |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i4 : H = segmentHomotopy(S,T,gamma=>1+ii)                                    |
|                                                                             |
|o4 = GateHomotopy{...11...}                                                  |
|                                                                             |
|o4 : GateHomotopy                                                            |
+-----------------------------------------------------------------------------+
|i5 : evaluateH(H,transpose matrix first solsS,0)                             |
|                                                                             |
|o5 = | 0              |                                                      |
|     | -2.44929e-16ii |                                                      |
|                                                                             |
|                2          1                                                 |
|o5 : Matrix CC    <--- CC                                                    |
|              53         53                                                  |
+-----------------------------------------------------------------------------+

Ways to use segmentHomotopy :
=============================

  * "segmentHomotopy(GateSystem,GateSystem)"
  * "segmentHomotopy(List,List)"
  * "segmentHomotopy(PolySystem,PolySystem)"

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

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

setDefault -- set/get the default parameters for continuation algorithms
************************************************************************

Synopsis
========

  * Usage:
        setDefault(p1=>v1, p2=>v2, ...), v = getDefault p
  * Inputs:
      * p, p1, p2, see Symbol (Macaulay2Doc),(s), the name(s) of
        parameter(s)
  * Optional inputs (Macaulay2Doc),:
      * Attempts => ..., default value null,  (meaning Attempts = 5). The
        maximal number of attempts (e.g., to make a random regular homotopy).
      * SingularConditionNumber => ..., default value null,  (meaning
        SingularConditionNumber = 100000). Matrix is considered to be singular
        if its condition number is greater than this value.
      * Precision => ..., default value null,  (meaning bits of precision)
      * AffinePatches, => ..., default value null,
        reserved for developers
      * Bits, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * CorrectorTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * EndZoneFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * ErrorTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * gamma, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * InfinityThreshold, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * Iterations, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * maxCorrSteps, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * MultistepDegree, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * NoOutput, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * Normalize, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * numberSuccessesBeforeIncrease,
        => ..., default value null, options for core functions of
        Numerical Algebraic Geometry
      * Predictor, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * Projectivize, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * ResidualTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * SLP, => ..., default value null, reserved for
        developers
      * SLPcorrector, => ..., default value null, reserved
        for developers
      * SLPpredictor, => ..., default value null, reserved
        for developers
      * Software, => ..., default value null, specify internal
        or external software
      * stepIncreaseFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * tDegree, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * Tolerance, =>
        ..., default value null, specifies the tolerance of a numerical
        computation
      * tStep, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * tStepMin, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
  * Outputs:
      * setDefault returns null (Macaulay2Doc).
      * getDefault returns v, the value of the specified parameter p.

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

To see a detailed description of an option click on its name.

These functions set/get values of optional parameters used in the functions
track, solveSystem,
see refine, as well as
higher-level functions (that are under construction).

+------------------------------------------------------------+
|i1 : getDefault Predictor                                   |
|                                                            |
|o1 = RungeKutta4                                            |
|                                                            |
|o1 : Symbol                                                 |
+------------------------------------------------------------+
|i2 : setDefault(Predictor=>Euler, CorrectorTolerance=>1e-10)|
+------------------------------------------------------------+
|i3 : getDefault Predictor                                   |
|                                                            |
|o3 = Euler                                                  |
|                                                            |
|o3 : Symbol                                                 |
+------------------------------------------------------------+

See also
========

  * track -- track a linear segment
    homotopy given start and target system
  * solveSystem -- solve a system of polynomial
    equations
  * refine -- refine numerical solutions to a
    system of polynomial equations
  * areEqual (NAGtypes) -- determine if solutions are equal

Ways to use setDefault :
========================

  * "setDefault()"

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

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

setDefault(...,Tolerance=>...) -- specifies the tolerance of a numerical computation
************************************************************************************

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

  * Default value: null
  * Function: setDefault, -- set/get the default parameters
    for continuation algorithms
  * Option key: Tolerance (NumericalLinearAlgebra), -- the
    tolerance of a numerical computation

Functions with optional argument named Tolerance :
==================================================

  * "addition(...,Tolerance=>...)" -- see addition (NAGtypes),
    -- Union of polynomial spaces
  * "intersection(PolySpace,PolySpace,Tolerance=>...)" -- see
    intersection(PolySpace,PolySpace) (NAGtypes),
    -- Intersection of
    polynomial spaces
  * "isContained(...,Tolerance=>...)" -- see isContained (NAGtypes),
    -- Is one space contained in the other
  * "isOn(...,Tolerance=>...)" -- see isOn, -- determines if a
    point belongs to a variety
  * "isSolution(...,Tolerance=>...)" -- see
    isSolution(AbstractPoint,PolySystem),
    -- check if a point satisfies a
    polynomial system approximately
  * "removeRedundantComponents(...,Tolerance=>...)" -- see
    removeRedundantComponents(NumericalVariety),
    -- remove redundant
    components
  * "sample(...,Tolerance=>...)" -- see sample(WitnessSet),
    -- sample a point on a component
  * setDefault(...,Tolerance=>...)
    -- specifies the
    tolerance of a numerical computation
  * "areEqual(...,Tolerance=>...)" -- see
    sortSolutions(...,Tolerance=>...) (NAGtypes),
    -- the
    tolerance of a numerical computation
  * "differencePointSet(...,Tolerance=>...)" -- see
    sortSolutions(...,Tolerance=>...) (NAGtypes),
    -- the
    tolerance of a numerical computation
  * "isGEQ(...,Tolerance=>...)" -- see sortSolutions(...,Tolerance=>...) (NAGtypes),
    -- the
    tolerance of a numerical computation
  * "isRealPoint(...,Tolerance=>...)" -- see
    sortSolutions(...,Tolerance=>...) (NAGtypes),
    -- the
    tolerance of a numerical computation
  * "realPoints(...,Tolerance=>...)" -- see
    sortSolutions(...,Tolerance=>...) (NAGtypes),
    -- the
    tolerance of a numerical computation
  * "reduceSpace(...,Tolerance=>...)" -- see
    sortSolutions(...,Tolerance=>...) (NAGtypes),
    -- the
    tolerance of a numerical computation
  * "solutionsWithMultiplicity(...,Tolerance=>...)" -- see
    sortSolutions(...,Tolerance=>...) (NAGtypes),
    -- the
    tolerance of a numerical computation
  * sortSolutions(...,Tolerance=>...) (NAGtypes)
    -- the
    tolerance of a numerical computation
  * "unionPointSet(...,Tolerance=>...)" -- see
    sortSolutions(...,Tolerance=>...) (NAGtypes),
    -- the
    tolerance of a numerical computation
  * "colReduce(...,Tolerance=>...)" -- see
    Tolerance(NumericalLinearAlgebra) (NumericalLinearAlgebra),
    -- the
    tolerance of a numerical computation
  * "numericalImage(...,Tolerance=>...)" -- see
    Tolerance(NumericalLinearAlgebra) (NumericalLinearAlgebra),
    -- the
    tolerance of a numerical computation
  * "numericalKernel(...,Tolerance=>...)" -- see
    Tolerance(NumericalLinearAlgebra) (NumericalLinearAlgebra),
    -- the
    tolerance of a numerical computation

Software -- specify internal or external software
*************************************************

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

One may specify which software is used in homotopy continuation. Possible
values for internal software are:
  * M2 -- use top-level Macaulay2 homotopy continuation routines
  * M2engine -- use subroutines implemented in Macaulay2 engine (DEFAULT)
  * M2enginePrecookedSLPs -- (reserved for developers)
An external program may be used to replace a part of functionality of the
package provide the corresponding software is installed:
  * PHCPACK -- use PHCpack for homotopy continuation
  * BERTINI -- use Bertini for homotopy continuation
  * HOM4PS2 -- use HOM4PS for homotopy continuation

Functions with optional argument named Software :
=================================================

  * gateHomotopy(...,Software=>...)
    -- specifies where
    evaluation should be done (M2=top level, M2engine=core)
  * "trackHomotopy(...,Software=>...)" -- see numerical homotopy tracking options,
    -- options for core functions
    of Numerical Algebraic Geometry
  * "hypersurfaceSection(...,Software=>...)"
  * "isOn(...,Software=>...)"
  * "numericalIrreducibleDecomposition(...,Software=>...)"
  * "parameterHomotopy(...,Software=>...)"
  * "refine(...,Software=>...)"
  * "regeneration(...,Software=>...)"
  * "setDefault(...,Software=>...)"
  * "solveSystem(...,Software=>...)"
  * "track(...,Software=>...)"

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

The object Software, is a symbol (Macaulay2Doc).

solveGenericSystemInTorus(List) -- solve a generic system of sparse polynomial equations in the torus
*****************************************************************************************************

Synopsis
========

  * Function: solveGenericSystemInTorus,
  * Usage:
        s = solveGenericSystemInTorus F
  * Inputs:
      * F, a list (Macaulay2Doc), contains polynomials with complex
        coefficients
  * Outputs:
      * s, contains all complex solutions in the torus (i.e., with no zero
        coordinates) to G=0, where G is a generic system with the same monomial
        support as F

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

Polyhedral homotopy approach is used to compute the solutions in the torus. The
number of the solutions equals the mixed volume of the Newton polytopes of
polynomials in F.

Caveat
======

PHCpack needs to be installed.

See also
========

  * PHCPACK -- use PHCpack for homotopy continuation
  * PHCpack -- a package for Polynomial Homotopy
    Continuation
  * solveSystem -- solve a system of polynomial
    equations

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

  * solveGenericSystemInTorus(List),
    -- solve a generic system of sparse polynomial equations in the torus
  * "solveGenericSystemInTorus(PolySystem)"

solveSystem(...,PostProcess=>...) -- specifies whether to postprocess the solutions
***********************************************************************************

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

Postprocessing includes refinement and clustering the solutions.

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

  * Default value: true (Macaulay2Doc),
  * Function: solveSystem, -- solve a system of
    polynomial equations
  * Option key: PostProcess,
    -- specifies whether
    to postprocess the solutions

Caveat
======

Postprocessing is coded in top-level M2 language and can be much slower than
the homotopy continuation done without postprocessing.

See also
========

  * refine -- refine numerical solutions to a
    system of polynomial equations

Functions with optional argument named PostProcess :
====================================================

  * solveSystem(...,PostProcess=>...)
    -- specifies whether
    to postprocess the solutions

solveSystem(List) -- solve a system of polynomial equations
***********************************************************

Synopsis
========

  * Function: solveSystem,
  * Usage:
        s = solveSystem F
  * Inputs:
      * F, a list (Macaulay2Doc), contains polynomials with complex
        coefficients
  * Optional inputs (Macaulay2Doc),:
      * CorrectorTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * EndZoneFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * gamma, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * InfinityThreshold, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * maxCorrSteps, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * Normalize, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * numberSuccessesBeforeIncrease,
        => ..., default value null, options for core functions of
        Numerical Algebraic Geometry
      * PostProcess,
        => ..., default value true, specifies whether to postprocess the
        solutions
      * Precision, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * Predictor, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * Projectivize, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * ResidualTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * SingularConditionNumber, =>
        ..., default value null, options for core functions of Numerical
        Algebraic Geometry
      * Software, => ..., default value null, specify internal
        or external software
      * stepIncreaseFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * tDegree, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * tStep, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * tStepMin, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
  * Outputs:
      * s, a list (Macaulay2Doc), contains all complex solutions to
        the system F=0

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

Solve a system of polynomial equations using homotopy continuation methods.

+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : F = {x^2+y^2-1, x*y};                                                   |
+-----------------------------------------------------------------------------+
|i3 : solveSystem F                                                           |
|                                                                             |
|o3 = {{3.02251e-20+2.05294e-20*ii, -1}, {-3.02251e-20-2.05294e-20*ii, 1}, {1,|
|     ------------------------------------------------------------------------|
|     8.30314e-21+4.44918e-20*ii}, {-1, -8.30314e-21-4.44918e-20*ii}}         |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
+------------------------------------------------------------------------+
|i4 : R = CC[x,y];                                                       |
+------------------------------------------------------------------------+
|i5 : F = {x^2+y^2-1, x*y, x*(y+1)};                                     |
+------------------------------------------------------------------------+
|i6 : solveSystem F                                                      |
|                                                                        |
|o6 = {{-6.73915e-17-4.6016e-18*ii, -1}, {4.27328e-17+5.26917e-17*ii, 1}}|
|                                                                        |
|o6 : List                                                               |
+------------------------------------------------------------------------+

The system is assumed to have finitely many solutions. If it is not square
(number of equations = number of variables), see squareUp, is
applied and solutions to the original system are then picked out from the
resulting (larger) set of solutions.

The output (produced by track, with
default options) contains all points (NAGtypes), obtained
at the end of homotopy paths when tracking starting at the
totalDegreeStartSystem. In particular, this
means that solving a system that has fewer than Bezout bound many solutions
will produce points that are not marked as regular. See track,
for detailed examples.

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

  * solveSystem(List) -- solve a system of
    polynomial equations
  * "solveSystem(PolySystem)"

specialize(GateParameterHomotopy,MutableMatrix) -- specialize parameters in a (gate) parameter homotopy
*******************************************************************************************************

Synopsis
========

  * Function: specialize (missing documentation)

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

  * specialize(GateParameterHomotopy,MutableMatrix)
    -- specialize
    parameters in a (gate) parameter homotopy

squareUp -- square up a polynomial system
*****************************************

Synopsis
========

  * Usage:
        G = squareUp F\nG = squareUp(F,M)\nsquareUp(F,n)
  * Inputs:
      * F, a polynomial system (NAGtypes),
      * M, a matrix (Macaulay2Doc),  the matrix used to square up
        the system (by default a random matrix is picked)
      * n, an integer (Macaulay2Doc),  the number of polynomials to
        be formed (by default, this equals the number of variables)
  * Outputs:
      * G, a polynomial system (NAGtypes),

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

Squares up an overdetermined polynomial system. Attaches keys
SquareUpMatrix, and SquaredUpSystem, to F.
+-----------------------------------------------------------------------------+
|i1 : CC[x,y]; F = polySystem {x^2+y^2,x^3+y^3,x^4+y^4}                       |
|                                                                             |
|o2 = F                                                                       |
|                                                                             |
|o2 : PolySystem                                                              |
+-----------------------------------------------------------------------------+
|i3 : G := squareUp F                                                         |
|                                                                             |
|o3 = | (.296025-.479811ii)x4+(.296025-.479811ii)y4+(-.605892-.324075ii)x3    |
|     | (-.085187-.0688326ii)x4+(-.085187-.0688326ii)y4+(.54886+.147995ii)    |
|                                                                             |
|o3 : PolySystem                                                              |
|-----------------------------------------------------------------------------|
|+(-.605892-.324075ii)y3+(.448215+.0955171ii)x2+(.448215+.0955171ii)y2 |      |
|x3+(.54886+.147995ii)y3+(.80766+.111983ii)x2+(.80766+.111983ii)y2     |      |
+-----------------------------------------------------------------------------+
|i4 : peek F                                                                  |
|                                                                             |
|o4 = PolySystem{NumberOfPolys => 3                                           |
|                NumberOfVariables =>                                         |
|                PolyMap => {-2} | x2                                         |
|                           {-3} | x3                                         |
|                           {-4} | x4                                         |
|                SquaredUpSystem => |                                         |
|                                   |                                         |
|                SquareUpMatrix => |                                          |
|                                  |                                          |
|-----------------------------------------------------------------------------|
|                                                                             |
| 2                                                                           |
|+y2 |                                                                        |
|+y3 |                                                                        |
|+y4 |                                                                        |
| (.296025-.479811ii)x4+(.296025-.479811ii)y4+(-.605892-.324075ii)x3+(-.605892|
| (-.085187-.0688326ii)x4+(-.085187-.0688326ii)y4+(.54886+.147995ii)x3+(.54886|
|.448215+.0955171ii -.605892-.324075ii .296025-.479811ii   |                  |
|.80766+.111983ii   .54886+.147995ii   -.085187-.0688326ii |                  |
|-----------------------------------------------------------------------------|
|                                                             }               |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|-.324075ii)y3+(.448215+.0955171ii)x2+(.448215+.0955171ii)y2 |                |
|+.147995ii)y3+(.80766+.111983ii)x2+(.80766+.111983ii)y2     |                |
+-----------------------------------------------------------------------------+

See also
========

  * PolySystem (NAGtypes) -- a polynomial system

Ways to use squareUp :
======================

  * "squareUp(PolySystem)"
  * "squareUp(PolySystem,Matrix)"
  * "squareUp(PolySystem,ZZ)"

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

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

totalDegreeStartSystem(List) -- construct a start system for the total degree homotopy
**************************************************************************************

Synopsis
========

  * Function: totalDegreeStartSystem,
  * Usage:
        (S,solsS) = totalDegreeStartSystem T
  * Inputs:
      * T, a list (Macaulay2Doc), polynomials of the target system
  * Outputs:
      * a sequence (Macaulay2Doc), where S is the list of
        polynomials in the start system and solsS is the list of start
        solutions

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

Given a square target system, constructs a start system for a total degree
homotopy together with the total degree (Bezout bound) many start solutions.

For details see: A.J. Sommese, J. Verschelde, and C.W. Wampler, "Introduction
to numerical algebraic geometry", in "Solving polynomial equations" (2005),
301--338

+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i2 : T = {x^2+y^2-1, x*y^2, x^5+y*z+3};                                      |
+-----------------------------------------------------------------------------+
|i3 : totalDegreeStartSystem T                                                |
|                                                                             |
|        2       3       5                                                    |
|o3 = ({x  - 1, y  - 1, z  - 1}, {{-1, -.5+.866025*ii, -.809017-.587785*ii},  |
|     ------------------------------------------------------------------------|
|     {-1, -.5-.866025*ii, -.809017+.587785*ii}, {-1, -.5-.866025*ii, 1}, {-1,|
|     ------------------------------------------------------------------------|
|     1, -.809017-.587785*ii}, {1, -.5-.866025*ii, -.809017-.587785*ii}, {-1, |
|     ------------------------------------------------------------------------|
|     -.5+.866025*ii, -.809017+.587785*ii}, {-1, -.5-.866025*ii,              |
|     ------------------------------------------------------------------------|
|     .309017-.951057*ii}, {-1, -.5+.866025*ii, 1}, {1, -.5+.866025*ii,       |
|     ------------------------------------------------------------------------|
|     -.809017-.587785*ii}, {-1, 1, -.809017+.587785*ii}, {1, -.5-.866025*ii, |
|     ------------------------------------------------------------------------|
|     -.809017+.587785*ii}, {-1, -.5+.866025*ii, .309017-.951057*ii}, {-1,    |
|     ------------------------------------------------------------------------|
|     -.5-.866025*ii, .309017+.951057*ii}, {-1, 1, 1}, {1, -.5-.866025*ii, 1},|
|     ------------------------------------------------------------------------|
|     {1, 1, -.809017-.587785*ii}, {1, -.5+.866025*ii, -.809017+.587785*ii},  |
|     ------------------------------------------------------------------------|
|     {-1, 1, .309017-.951057*ii}, {1, -.5-.866025*ii, .309017-.951057*ii},   |
|     ------------------------------------------------------------------------|
|     {-1, -.5+.866025*ii, .309017+.951057*ii}, {1, -.5+.866025*ii, 1}, {1, 1,|
|     ------------------------------------------------------------------------|
|     -.809017+.587785*ii}, {1, -.5+.866025*ii, .309017-.951057*ii}, {-1, 1,  |
|     ------------------------------------------------------------------------|
|     .309017+.951057*ii}, {1, -.5-.866025*ii, .309017+.951057*ii}, {1, 1, 1},|
|     ------------------------------------------------------------------------|
|     {1, 1, .309017-.951057*ii}, {1, -.5+.866025*ii, .309017+.951057*ii},    |
|     ------------------------------------------------------------------------|
|     {-1, -.5-.866025*ii, -.809017-.587785*ii}, {1, 1, .309017+.951057*ii}}) |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * track -- track a linear segment
    homotopy given start and target system
  * solveSystem -- solve a system of polynomial
    equations

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

  * totalDegreeStartSystem(List), --
    construct a start system for the total degree homotopy

track(List,List,List) -- track a linear segment homotopy given start and target system
**************************************************************************************

Synopsis
========

  * Function: track,
  * Usage:
        solsT = track(S,T,solsS)
  * Inputs:
      * S, a list (Macaulay2Doc),  contains the polynomials in the
        start system
      * T, a list (Macaulay2Doc),  contains the polynomials in the
        target system
      * solsS, a list (Macaulay2Doc),  contains start solutions
  * Optional inputs (Macaulay2Doc),:
      * AffinePatches, => ..., default value null,
        reserved for developers
      * CorrectorTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * EndZoneFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * gamma, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * InfinityThreshold, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * maxCorrSteps, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * MultistepDegree, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * NoOutput, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * Normalize, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * numberSuccessesBeforeIncrease,
        => ..., default value null, options for core functions of
        Numerical Algebraic Geometry
      * Predictor, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * Projectivize, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * SingularConditionNumber, => ..., default value null,
        set/get the default parameters for continuation algorithms
      * SLP, => ..., default value null, reserved for
        developers
      * SLPcorrector, => ..., default value null, reserved
        for developers
      * SLPpredictor, => ..., default value null, reserved
        for developers
      * Software, => ..., default value null, specify internal
        or external software
      * stepIncreaseFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * tDegree, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * tStep, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * tStepMin, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
  * Outputs:
      * a list (Macaulay2Doc), solsT is a list of points (NAGtypes),
        that are solutions of T=0 obtained by
        continuing solsS of S=0

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

Polynomial homotopy continuation techniques are used to obtain solutions of the
target system given a start system. For an introduction to the subject see
  * A.J. Sommese, J. Verschelde, and C.W. Wampler, "Introduction to numerical
    algebraic geometry", in "Solving polynomial equations" (2005), 301--338
  * A.J. Sommese and C.W. Wampler, "The numerical solution of systems of
    polynomials", World Scientific Publishing (2005)
The package implements a most commonly used homotopy:

H(t) = \gamma t^d T + (1-t)^d S

where S and T are square systems (number of equations = number of variables) of
polynomials over CC (Macaulay2Doc), t is in the interval [0,1] and d
= See tDegree.

Here is an example with regular solutions at the ends of all homotopy paths:

+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : S = {x^2-1,y^2-1};                                                      |
+-----------------------------------------------------------------------------+
|i3 : T = {x^2+y^2-1, x*y};                                                   |
+-----------------------------------------------------------------------------+
|i4 : solsS = {(1,-1),(1,1),(-1,1),(-1,-1)};                                  |
+-----------------------------------------------------------------------------+
|i5 : track(S,T,solsS)                                                        |
|                                                                             |
|o5 = {{-4.40616e-16, -1}, {1, 1.22819e-15}, {4.40616e-16, 1}, {-1,           |
|     ------------------------------------------------------------------------|
|     -1.22819e-15}}                                                          |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

Another outcome of tracking a path is divergence (established heuristically).
In that case the divergent paths are marked with an I (see status (NAGtypes),
is set to Infinity (NAGtypes)).

+-----------------------------------------------------------------------------+
|i6 : R = CC[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i7 : S = {x^2-1,y^2-1};                                                      |
+-----------------------------------------------------------------------------+
|i8 : T = {x^2+y^2-1, x-y};                                                   |
+-----------------------------------------------------------------------------+
|i9 : solsS = {(1,-1),(1,1),(-1,1),(-1,-1)};                                  |
+-----------------------------------------------------------------------------+
|i10 : track(S,T,solsS,gamma=>0.6+0.8*ii)                                     |
|                                                                             |
|o10 = {[M,t=.999998], {.707107, .707107}, [M,t=.999998], {-.707107,          |
|      -----------------------------------------------------------------------|
|      -.707107}}                                                             |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+

Some divergent paths as well as most of the paths ending in singular
(multiplicity>1) or near-singular (clustered) solutions are marked with an M
(see status (NAGtypes), is set to MinStepFailure (NAGtypes)).

+------------------------------------------------------------------+
|i11 : R = CC[x,y];                                                |
+------------------------------------------------------------------+
|i12 : S = {x^2-1,y^2-1};                                          |
+------------------------------------------------------------------+
|i13 : T = {x^2+y^2-1, (x-y)^2};                                   |
+------------------------------------------------------------------+
|i14 : solsS = {(1,-1),(1,1),(-1,1),(-1,-1)};                      |
+------------------------------------------------------------------+
|i15 : track(S,T,solsS)                                            |
|                                                                  |
|o15 = {[M,t=.999998], [M,t=.999998], [M,t=.999998], [M,t=.999998]}|
|                                                                  |
|o15 : List                                                        |
+------------------------------------------------------------------+

Tracking in the projective space uses the homotopy corresponding to an arc of a
great circle on  a unit sphere in the space of homogeneous polynomial systems
of a fixed degree. In particular, this is done for certified homotopy tracking
(see C. Beltran and A. Leykin, "Certified numerical homotopy tracking",
Experimental Mathematics 21(1): 69-83 (2012)):

+-----------------------------------------------------------------------------+
|i16 : R = CC[x,y,z];                                                         |
+-----------------------------------------------------------------------------+
|i17 : S = {x^2-z^2,y^2-z^2};                                                 |
+-----------------------------------------------------------------------------+
|i18 : T = {x^2+y^2-z^2, x*y};                                                |
+-----------------------------------------------------------------------------+
|i19 : solsS = {(1,-1,1),(1,1,1),(-1,1,1),(-1,-1,1)};                         |
+-----------------------------------------------------------------------------+
|i20 : track(S,T,solsS,Predictor=>Certified,Normalize=>true)                  |
|                                                                             |
|o20 = {{.00000107266, -.70712, .70712}, {.707125, -1.48993e-7, .707107},     |
|      -----------------------------------------------------------------------|
|      {-.00000107266, .70712, .70712}, {-.707125, 1.48993e-7, .707107}}      |
|                                                                             |
|o20 : List                                                                   |
+-----------------------------------------------------------------------------+

Note that the projective tracker is invoked either if the target system is a
homogeneous system or if Projectivize,
=>true is specified.

Caveat
======

Predictor=>Certified works only with (Software=>M2 or Software=>M2engine) and
Normalize=>true.

Unspecified optional arguments (with default values null (Macaulay2Doc))
have their actual values taken from a local hashtable of
defaults controlled by the functions getDefault, and
setDefault.

See also
========

  * solveSystem -- solve a system of polynomial
    equations
  * setDefault -- set/get the default parameters for
    continuation algorithms
  * Point (NAGtypes) -- a type used to store a point in
    complex space

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

  * track(List,List,List) -- track a
    linear segment homotopy given start and target system
  * "track(PolySystem,PolySystem,List)"

trackHomotopy(Homotopy,List) -- follow points along a homotopy
**************************************************************

Synopsis
========

  * Function: trackHomotopy,
  * Usage:
        trackHomotopy(H,S)
  * Inputs:
      * H, an instance of the type Homotopy (NAGtypes),
      * S, a list (Macaulay2Doc), start solutions
  * Optional inputs (Macaulay2Doc),:
      * CorrectorTolerance, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * EndZoneFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * Field => ..., default value null
      * InfinityThreshold, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * maxCorrSteps, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * NoOutput, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * numberSuccessesBeforeIncrease,
        => ..., default value null, options for core functions of
        Numerical Algebraic Geometry
      * Precision, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * Predictor, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * Software, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
      * stepIncreaseFactor, => ...,
        default value null, options for core functions of Numerical Algebraic
        Geometry
      * tStep, => ..., default value
        null, options for core functions of Numerical Algebraic Geometry
      * tStepMin, => ..., default
        value null, options for core functions of Numerical Algebraic Geometry
  * Outputs:
      * a list (Macaulay2Doc),

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

This method implements homotopy continuation: it follows a given list S of
start solutions along a Homotopy (NAGtypes), H.

Option Field, is unique to this
method (the default is CC (Macaulay2Doc), but one can imagine using
RR (Macaulay2Doc)). It specifies which InexactFieldFamily (Macaulay2Doc),
to use when adaptive precision is requested
via Precision=>infinity. The rest are a subset of numerical homotopy tracking options.

Caveat
======

Note for developers: the old implementation track,
eventually will be replaced by a call to
trackHomotopy. Alternative ways for
calling (H could be a Sequence (a preSLP), Matrix, etc.) are deprecated and are
for debugging purposes only.

See also
========

  * GateHomotopy,
    -- homotopy implemented via straight line programs
  * segmentHomotopy -- a segment homotopy
  * AbstractPoint (NAGtypes) -- a type used to store a
    point in complex space

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

  * trackHomotopy(Homotopy,List), --
    follow points along a homotopy
  * "trackHomotopy(Matrix,List)"
  * "trackHomotopy(Sequence,List)"

union(NumericalVariety,NumericalVariety) -- union of numerical varieties
************************************************************************

Synopsis
========

  * Function: union,
  * Usage:
        VW=union(V,W)
  * Inputs:
      * V, a numerical variety (NAGtypes),
      * W, a numerical variety (NAGtypes),
  * Outputs:
      * VW, a numerical variety (NAGtypes),

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

Constructs the union of numerical varieties

Caveat
======

The resulting numerical variety may have redundant components.

See also
========

  * removeRedundantComponents
    -- remove redundant
    components

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

  * union(NumericalVariety,NumericalVariety)
    -- union of numerical
    varieties

vars(GateSystem) -- the variable gates in the evaluation circuit used for the system
************************************************************************************

Synopsis
========

  * Function: vars (Macaulay2Doc),

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

This method returns the 1-row GateMatrix (SLPexpressions),
that contains InputGate (SLPexpressions),s that are considered
variables for the evaluation circuit.

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

  * vars(GateSystem) -- the variable gates in the
    evaluation circuit used for the system