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

PHCpack -- a package for Polynomial Homotopy Continuation
*********************************************************

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

This package provides an interface to the software PHCpack, a general-purpose
polynomial system solver that uses homotopy continuation. The main method is a
numerical blackbox solver, implemented for Laurent systems.  The package also
provides a fast mixed volume computation, the ability to filter solutions,
extract real solutions, or track solution paths defined by a polynomial
homotopy. For positive dimensional solution sets, we can compute a numerical
irreducible decomposition.

The software PHCpack itself is available at
http://www.math.uic.edu/~jan/download.html. This site provides source code and
its executable version phc. To use the methods from this package, the user must
have the executable program phc available, preferably in the execution path.
The functions in this package call the phc executable, behind the scenes, with
appropriate input options, and save intermediate output to temporary files. For
convenience, the file names are displayed, and the commands that are invoked
are documented under "Consequences" for each function.

Below is a simple example using the most popular function, the numerical
blackbox solver.

+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y,z]                                                           |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : system = {y-x^2,z-x^3,x+y+z-1}                                          |
|                                                                             |
|         2         3                                                         |
|o2 = {- x  + y, - x  + z, x + y + z - 1}                                     |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : solns = solveSystem(system)                                             |
|                                                                             |
|o3 = {{-.771845-1.11514*ii, -.647799+1.72143*ii, 2.41964-.606291*ii},        |
|     ------------------------------------------------------------------------|
|     {.543689, .295598, .160713}, {-.771845+1.11514*ii, -.647799-1.72143*ii, |
|     ------------------------------------------------------------------------|
|     2.41964+.606291*ii}}                                                    |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+
|i4 : numSolns = #solns                                                       |
|                                                                             |
|o4 = 3                                                                       |
+-----------------------------------------------------------------------------+
|i5 : solns/print                                                             |
|{-.771845-1.11514*ii, -.647799+1.72143*ii, 2.41964-.606291*ii}               |
|{.543689, .295598, .160713}                                                  |
|{-.771845+1.11514*ii, -.647799-1.72143*ii, 2.41964+.606291*ii}               |
|                                                                             |
|o5 = {, , }                                                                  |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

We see that there are three solutions to the above system. Each solution is of
type Point (NAGtypes), and contains diagnostic information
about the quality of the solution.

+-----------------------------------------------------------------------------+
|i6 : oneSoln = solns_0                                                       |
|                                                                             |
|o6 = oneSoln                                                                 |
|                                                                             |
|o6 : Point                                                                   |
+-----------------------------------------------------------------------------+
|i7 : peek oneSoln                                                            |
|                                                                             |
|o7 = Point{cache => CacheTable{...3...}                                      |
|           Coordinates => {-.771845-1.11514*ii, -.647799+1.72143*ii,         |
|     ------------------------------------------------------------------------|
|                        }                                                    |
|     2.41964-.606291*ii}                                                     |
+-----------------------------------------------------------------------------+

The value of LastT is the end value of the continuation parameter: if it equals
1, then the solver reached the end of the path properly.

Contributors
============

  * Anton Leykin (see http://www.math.gatech.edu/~leykin )
  * Jeff Sommars (see http://www.math.uic.edu/~sommars )
  * Taylor Brysiewicz (see http://www.math.tamu.edu/~tbrysiewicz/ )
  * Corey Harris (see http://www.coreyharris.name/ )
  * Diego Cifuentes (see http://www.mit.edu/~diegcif/ )
  * Kaie Kubjas (see http://www.kaiekubjas.com/ )
  * Anna Seigal (see https://math.berkeley.edu/~seigal/ )

Caveat
======

1. If you are having trouble installing the package, check whether the path to
your PHCpack executable was set correctly. You can check this by typing the
following command:

options PHCpack

If it is wrong, you can update it by putting the absolute path into the
init-PHCpack.m2 file, For example, if the executable phc is located in
C:/cygwin/PHC, then the line inside the init-PHCpack.m2 file will look like
this:

"path" => "C:/cygwin/PHC/" .

Alternately, the path could be set when loading the package using the following
command:

loadPackage ("PHCpack", Configuration=>{"path"=>"C:/cygwin/PHC/","PHCexe"=>"./
phc"})

2. The current version 1.8 of PHCpack.m2 was developed with version 1.9 of
Macaulay2 and with version 2.4.17 of phc.

Authors
=======

  * Elizabeth Gross (see http://www.math.uic.edu/~lizgross ) <egross7@uic.edu>
  * Sonja Petrovic (see http://mypages.iit.edu/~spetrov1/ )
    <Sonja.Petrovic@iit.edu>
  * Jan Verschelde (see http://www.math.uic.edu/~jan ) <jan@math.uic.edu>

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

Version 1.6 of this package was accepted for publication in volume 5 (see
https://msp.org/jsag/2013/5-1/ ) of The Journal of Software for Algebra and
Geometry (see https://msp.org/jsag/ ) on 2013-07-11, in the article Interfacing
with PHCpack (see https://msp.org/jsag/2013/5-1/p04.xhtml ) (DOI:
10.2140/jsag.2013.5.20 (see https://doi.org/10.2140/jsag.2013.5.20 )). That
version can be obtained from the journal (see
https://msp.org/jsag/2013/5-1/jsag-v5-n1-x04-code.zip ) or from the Macaulay2
source code repository (see
https://github.com/Macaulay2/M2/blob/48d32ceffeeb807b23eee20a5c9c243ce085b3ef/
M2/Macaulay2/packages/PHCpack.m2 ).

Version
=======

This documentation describes version 1.8 of PHCpack.

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

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

Exports
=======

  * Functions and commands
      * cascade -- runs a cascade of homotopies to get witness
        sets for the variety
      * constructEmbedding -- constructs an
        embedding of a polynomial system
      * factorWitnessSet -- applies monodromy to
        factor a witness set into irreducible components
      * intersectSlice -- intersects a witness set by a
        slice
      * isCoordinateZero -- checks if coordinate has
        absolute value less than a given tolerance
      * isWitnessSetMember -- tests whether a point
        belongs to a solution set
      * mixedVolume -- computes mixed volume of a
        polynomial system
      * nonZeroFilter -- returns solutions with
        coordinate larger than given tolerance
      * numericalIrreducibleDecomposition
        -- finds the irreducible components
        of the zero set of a system of polynomials
      * realSlice1D -- computes a real slice for a one
        dimensional witness set
      * realSlice2D -- computes a real slice for a two
        dimensional witness set
      * refineSolutions -- refines solutions of a
        system by increasing working precision
      * solveRationalSystem -- approximates
        solutions to a rational system of equations
      * solveSystem -- a numerical blackbox solver
      * toLaurentPolynomial -- converts a list of
        rational polynomials into Laurent polynomials
      * topWitnessSet -- returns a witness set and
        nonsolutions for the top dimensional solution set
      * trackPaths -- tracks paths defined by a typical
        homotopy between start and end systems
      * versionNumber -- returns the version number and
        release date of phc
      * zeroFilter -- returns solutions with k-th coordinate
        less than the given tolerance
  * Methods
      * "cascade(List)" -- see cascade, -- runs a cascade of
        homotopies to get witness sets for the variety
      * "constructEmbedding(List,ZZ)" -- see constructEmbedding,
        -- constructs an embedding of a polynomial system
      * "factorWitnessSet(WitnessSet)" -- see factorWitnessSet,
        -- applies monodromy to factor a witness set into
        irreducible components
      * "intersectSlice(WitnessSet,List)" -- see intersectSlice,
        -- intersects a witness set by a slice
      * "isCoordinateZero(AbstractPoint,ZZ,RR)" -- see isCoordinateZero,
        -- checks if coordinate has absolute value less than
        a given tolerance
      * "isWitnessSetMember(WitnessSet,AbstractPoint)" -- see
        isWitnessSetMember, -- tests whether a point
        belongs to a solution set
      * "nonZeroFilter(List,ZZ,RR)" -- see nonZeroFilter,
        -- returns solutions with coordinate larger than given tolerance
      * "numericalIrreducibleDecomposition(List)" -- see
        numericalIrreducibleDecomposition,
        -- finds the irreducible components of the zero set of a system of
        polynomials
      * "realSlice1D(WitnessSet)" -- see realSlice1D, --
        computes a real slice for a one dimensional witness set
      * "realSlice2D(WitnessSet)" -- see realSlice2D, --
        computes a real slice for a two dimensional witness set
      * "refineSolutions(List,List,ZZ)" -- see refineSolutions,
        -- refines solutions of a system by increasing working
        precision
      * "solveRationalSystem(List)" -- see solveRationalSystem,
        -- approximates solutions to a rational system of
        equations
      * "solveSystem(List)" -- see solveSystem, -- a
        numerical blackbox solver
      * "toLaurentPolynomial(List,Symbol)" -- see toLaurentPolynomial,
        -- converts a list of rational polynomials into
        Laurent polynomials
      * "topWitnessSet(List,ZZ)" -- see topWitnessSet, --
        returns a witness set and nonsolutions for the top dimensional solution
        set
      * "trackPaths(List,List,List)" -- see trackPaths, --
        tracks paths defined by a typical homotopy between start and end
        systems
      * "versionNumber(Nothing)" -- see versionNumber, --
        returns the version number and release date of phc
      * "zeroFilter(List,ZZ,RR)" -- see zeroFilter, --
        returns solutions with k-th coordinate less than the given tolerance
  * Symbols
      * computingPrecision -- flag to switch to
        double double or quad double precision
      * gamma -- the constant in the gamma trick, optional input
        for trackPaths
      * interactive -- flag to run phc -p or phc -m in
        interactive mode
      * intermediateSolutions -- option of
        trackPaths to get all intermediate solutions on a path
      * loadSettingsPath -- option of trackPaths to
        load the settings for a reproducible rerun
      * numThreads -- the number of threads in the path
        tracker
      * randomSeed -- seed for the random number generators
      * saveSettingsPath -- option of trackPaths to
        save the settings for a reproducible rerun
      * searchDelta -- option of realSlice1D
      * searchNpoints -- option of realSlice1D
      * searchTolerance -- option of realSlice1D
      * seeProgress -- flag to monitor the progress of the
        multithreaded path tracker
      * StableMixedVolume -- optional input for
        computation of the stable mixed volume
      * StartDimension -- optional input for cascade and
        numericalIrreducibleDecomposition
      * StartSystem -- optional input to construct and
        solve a random coefficient system
      * tDegree -- the degree of the continuation parameter

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

The object PHCpack, is a package (Macaulay2Doc).

cascade -- runs a cascade of homotopies to get witness sets for the variety
***************************************************************************

Synopsis
========

  * Usage:
        cascade L
  * Inputs:
      * L, a list (Macaulay2Doc), of polynomials
  * Optional inputs (Macaulay2Doc),:
      * StartDimension,
        => ..., default value -1, Option to specify the dimension to begin
        searching for positive dimensional components
      * Verbose, => ...,
        default value false, option to specify whether additional output is
        wanted
  * Outputs:
      * a numerical variety (NAGtypes), containing the
        witness sets for each pure-dimensional variety contained in zero set of
        L.
  * Consequences:
      * Writes the system to temporary file
      * Invokes the command phc -c (with option 0)
      * Stores output of phc in temporary file
      * Parses and outputs the solutions.

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

Given a list of generators of an ideal I, this function creates an embedding
and then runs a cascade of homotopies. The output is a NumericalVariety (NAGtypes),
that contains a WitnessSet (NAGtypes),
for each pure dimensional variety contained in V(I).

+------------------------------+
|i1 : R = CC[x,y,z];           |
+------------------------------+
|i2 : L = { z*(x+y), z*(x-y) };|
+------------------------------+
|i3 : WitSets = cascade(L)     |
|                              |
|o3 = WitSets                  |
|                              |
|o3 : NumericalVariety         |
+------------------------------+
|i4 : W=first WitSets#2        |
|                              |
|o4 = W                        |
|                              |
|o4 : WitnessSet               |
+------------------------------+

The function cascade extends the ring of the inputted system with slack
variables beginning with zz.  Each witness set in contains the equations,
points, and slices of the embedded system.

+-----------------------------------------------------------------------------+
|i5 : W#Equations                                                             |
|                                                                             |
|o5 = {-2} | (-.380139+.924929ii)zz1+(.547606+.836736ii)zz2-xz-yz |           |
|     {-2} | (.45571-.890128ii)zz1+(-.663772-.747935ii)zz2-xz+yz  |           |
|     {-1} | -zz1+(.537862+.843033ii)zz2                          |           |
|                                                                             |
|o5 : PolySystem                                                              |
+-----------------------------------------------------------------------------+
|i6 : W#Points                                                                |
|                                                                             |
|o6 = {{.148619-.161802*ii, .45886-1.03272*ii, 3.21921e-32+7.65273e-33*ii,    |
|                                                                             |
|o6 : VerticalList                                                            |
|-----------------------------------------------------------------------------|
|-2.28184e-32-4.87389e-33*ii, -1.6382e-32+1.66152e-32*ii}}                    |
+-----------------------------------------------------------------------------+
|i7 : W#Slice                                                                 |
|                                                                             |
|o7 = | .205377+.978683ii  .673112+.739541ii .943327-.331864ii                |
|     | -.759495+.650513ii -.89022-.45553ii  -.972487+.232959ii               |
|     ------------------------------------------------------------------------|
|     -.911067-.412259ii .497812+.867285ii  -.883724+.468009ii |              |
|     -.595572-.803302ii -.236638-.971598ii .871298-.490754ii  |              |
|                                                                             |
|                2         6                                                  |
|o7 : Matrix CC    <-- CC                                                     |
|              53        53                                                   |
+-----------------------------------------------------------------------------+

Caveat
======

Coefficient ring of the polynomial system must be of type ComplexField (Macaulay2Doc).

See also
========

  * constructEmbedding -- constructs an embedding of
    a polynomial system
  * numericalIrreducibleDecomposition,
    -- finds the irreducible components of the zero set of a system of
    polynomials

Ways to use cascade:
====================

  * "cascade(List)"

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

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

cascade(...,StartDimension=>...) -- Option to specify the dimension to begin searching for positive dimensional components
**************************************************************************************************************************

Synopsis
========

  * Usage:
        cascade(...,StartDimension=>ZZ)

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

  * Default value: -1
  * Function: cascade, -- runs a cascade of homotopies to get
    witness sets for the variety
  * Option key: StartDimension, -- optional input for
    cascade and numericalIrreducibleDecomposition

Functions with optional argument named StartDimension:
======================================================

  * cascade(...,StartDimension=>...)
    -- Option to specify
    the dimension to begin searching for positive dimensional components
  * numericalIrreducibleDecomposition(...,StartDimension=>...)
    -- Option to specify the dimension to begin searching for positive
    dimensional components

cascade(...,Verbose=>...) -- option to specify whether additional output is wanted
**********************************************************************************

Synopsis
========

  * Usage:
        cascade(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output which includes the input and solution
file names used by phc -c.

The output file of phc contains timings for the stages in the cascade of
homotopies.

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

  * Default value: false (Macaulay2Doc),
  * Function: cascade, -- runs a cascade of homotopies to get
    witness sets for the variety
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

computingPrecision -- flag to switch to double double or quad double precision
******************************************************************************

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

By default, all computations occur in hardware double precision. While this
precision could be large enough to obtain accurate results, for larger
problems, one may need to increase the precision to double double or to quad
double precision.

Setting the value of computingPrecision to 2 changes the precision in the path
trackers to double double.

Setting the value of computingPrecision to 4 changes the precision in the path
trackers to quad double.

To compensate for the cost overhead of the higher precision, it is useful to
run the multithreaded versions of the path trackers, see the option numThreads.

Functions with optional argument named computingPrecision:
==========================================================

  * solveSystem(...,computingPrecision=>...)
    -- option to
    specify the working precision

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

The object computingPrecision, is a symbol (Macaulay2Doc).

constructEmbedding -- constructs an embedding of a polynomial system
********************************************************************

Synopsis
========

  * Usage:
        constructEmbedding(f,k)
  * Inputs:
      * f, a list (Macaulay2Doc), of polynomials
      * k, an integer (Macaulay2Doc), the expected (top) dimension of
        the solution set of f
  * Optional inputs (Macaulay2Doc),:
      * Verbose,
        => ..., default value false, option to specify whether additional
        output is wanted
  * Outputs:
      * a list (Macaulay2Doc), entries are polynomials containing
        the original system with k random linear polynomials and k slack
        variables
  * Consequences:
      * Writes the system to temporary files
      * Extends the ring with slack variables
      * Uses surplus variables when the initial system is overconstrained
      * Invokes the command phc -c (with option 1).
      * Stores output of phc in temporary file
      * Parses and outputs the solutions.

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

To compute generic points of a k-dimensional solution set of a polynomial
system, we add k random linear equations to the system.

+--------------------------------------------------------------------------+
|i1 : R = CC[x,y,z];                                                       |
+--------------------------------------------------------------------------+
|i2 : f = { x^2 - y, x^3 - z };                                            |
+--------------------------------------------------------------------------+
|i3 : fe1 = constructEmbedding(f,1);                                       |
+--------------------------------------------------------------------------+
|i4 : toString fe1                                                         |
|                                                                          |
|o4 = {x^2-y+(.380139-.924929*ii)*zz1, x^3-z+(-.45571+.890128*ii)*zz1, zz1,|
|     (-.205377-.978683*ii)*x+(.943327-.331864*ii)*y+(.673112+.739541*ii)*z|
|     +(-.911067-.412259*ii)*zz1-.883724+.468009*ii}                       |
+--------------------------------------------------------------------------+

Note that the ring of the original system is extended with k slack variables.
Solutions of the embedded system with zero values for the slack variables are
candidate generic points.

If the input system is overdetermined (there are more equations than unknowns),
then as many surplus variables are introduced as the difference between the
number of equations and the number of variables.  Surplus variables start with
ss.

+----------------------------------------------------------------------------+
|i5 : R = CC[x,y,z];                                                         |
+----------------------------------------------------------------------------+
|i6 : f = { x^2-y, x^3-z, x*y-z, x*z-y^2 };                                  |
+----------------------------------------------------------------------------+
|i7 : fe1 = constructEmbedding(f,1);                                         |
+----------------------------------------------------------------------------+
|i8 : toString fe1                                                           |
|                                                                            |
|o8 = {x^2-y+(-.97755+.210704*ii)*ss1+(.380139-.924929*ii)*zz1,              |
|     x^3-z+(-.688326-.725402*ii)*ss1+(-.45571+.890128*ii)*zz1,              |
|     x*y-z+(-.997759-.0669093*ii)*ss1+(-.930099+.36731*ii)*zz1,             |
|     -y^2+x*z+(-.767756-.640743*ii)*ss1+(-.883724+.468009*ii)*zz1,          |
|     (.943327-.331864*ii)*x+(.673112+.739541*ii)*y+(-.911067-.412259*ii)*z  |
|     +(.547606+.836736*ii)*ss1+(-.663772-.747935*ii)*zz1-.205377-.978683*ii}|
+----------------------------------------------------------------------------+

In the example above, the system f has four equations in three unknowns,
constructEmbedding adds one surplus variable and one slack variable. Only
solutions with zero values for the surplus variable are relevant.

Ways to use constructEmbedding:
===============================

  * "constructEmbedding(List,ZZ)"

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

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

constructEmbedding(...,Verbose=>...) -- option to specify whether additional output is wanted
*********************************************************************************************

Synopsis
========

  * Usage:
        constructEmbedding(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output which includes the input and solution
file names used by phc -c.

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

  * Default value: false (Macaulay2Doc),
  * Function: constructEmbedding, -- constructs an
    embedding of a polynomial system
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

factorWitnessSet -- applies monodromy to factor a witness set into irreducible components
*****************************************************************************************

Synopsis
========

  * Usage:
        factorWitnessSet(w)
  * Inputs:
      * w, a witness set (NAGtypes), properly embedded with
        slack variables
  * Optional inputs (Macaulay2Doc),:
      * Verbose, =>
        ..., default value false, option to specify whether additional output
        is wanted
  * Outputs:
      * a list (Macaulay2Doc), a list of witness sets, every
        element of the list is irreducible
  * Consequences:
      * writes the system to temporary files,
      * invokes the command phc -f (with option 2),
      * uses monodromy to factor,
      * uses default settings of path trackers ,
      * stores output of phc in temporary file,
      * parses and outputs the solutions.

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

A witness set is irreducible if there exists a path between any two of its
generic points that does not pass through a singularity.

We illustrate the factorization via the twisted cubic and a line.

+-------------------------------------------------+
|i1 : R = CC[x,y,z]; f = {(x^2-y)*(x-1), x^3 - z};|
+-------------------------------------------------+
|i3 : (w,ns) = topWitnessSet(f,1);                |
+-------------------------------------------------+
|i4 : w                                           |
|                                                 |
|o4 = w                                           |
|                                                 |
|o4 : WitnessSet                                  |
+-------------------------------------------------+
|i5 : L = factorWitnessSet(w)                     |
|found 2 irreducible factors                      |
|                                                 |
|o5 = L                                           |
|                                                 |
|o5 : NumericalVariety                            |
+-------------------------------------------------+

See also
========

  * numericalIrreducibleDecomposition,
    -- finds the irreducible components of the zero set of a system of
    polynomials

Ways to use factorWitnessSet:
=============================

  * "factorWitnessSet(WitnessSet)"

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

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

factorWitnessSet(...,Verbose=>...) -- option to specify whether additional output is wanted
*******************************************************************************************

Synopsis
========

  * Usage:
        factorWitnessSet(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output which includes the input and solution
file names used by phc -f.

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

  * Default value: false (Macaulay2Doc),
  * Function: factorWitnessSet, -- applies monodromy to
    factor a witness set into irreducible components
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

gamma -- the constant in the gamma trick, optional input for trackPaths
***********************************************************************

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

The `gamma trick' refers to the following idea:

If the solutions of the start system are regular, then we avoid singular
solutions along the paths by multiplying the start system in the homotopy with
a random complex constant gamma. This option allows the user to give a specific
value of this gamma constant.

+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : f = { x^3*y^5 + y^2 + x^2*y, x*y + x^2 - 1};                            |
+-----------------------------------------------------------------------------+
|i3 : (m,q,qsols) = mixedVolume(f,StartSystem=>true);                         |
+-----------------------------------------------------------------------------+
|i4 : fsols = trackPaths(f,q,qsols,gamma => exp(ii*pi/3))                     |
|                                                                             |
|o4 = {{.742585+.425943*ii, .270685-1.00715*ii}, {-1.59272, .964857},         |
|     ------------------------------------------------------------------------|
|     {.742585-.425943*ii, .270685+1.00715*ii}, {-.894935-.624334*ii,         |
|     ------------------------------------------------------------------------|
|     .143333+1.14868*ii}, {1.33076-.335184*ii, -.62414+.513163*ii},          |
|     ------------------------------------------------------------------------|
|     {-.764107, -.544612}, {1.33076+.335184*ii, -.62414-.513163*ii},         |
|     ------------------------------------------------------------------------|
|     {-.894935+.624334*ii, .143333-1.14868*ii}}                              |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Reference: {A.J. Sommese, J. Verschelde, and C.W. Wampler. Introduction to
numerical algebraic geometry. In: Solving Polynomial Equations. Foundations,
Algorithms and Applications, volume 14 of Algorithms and Computation in
Mathematics, pages 301-337. Springer-Verlag, 2005.}

Functions with optional argument named gamma:
=============================================

  * trackPaths(...,gamma=>...)
    -- Option to specify the
    value of the constant in the gamma trick

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

The object gamma, is a symbol (Macaulay2Doc).

interactive -- flag to run phc -p or phc -m in interactive mode
***************************************************************

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

There are too many options for the path trackers in phc -p to wrap them
properly within the trackPaths() method. With interactive turned on, the user
can tune all parameters of the path trackers, in the same way as running phc
-p.

The option interactive is also supported to run the polyhedral homotopies to
solve random coefficient systems with phc -c, in the mixedVolume function with
the option StartSystem set to true.

Functions with optional argument named interactive:
===================================================

  * mixedVolume(...,interactive=>...)
    -- option to switch to
    the interactive mode of phc -m
  * trackPaths(...,interactive=>...)
    -- Option to run phc -p
    in interactive mode.

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

The object interactive, is a symbol (Macaulay2Doc).

intermediateSolutions -- option of trackPaths to get all intermediate solutions on a path
*****************************************************************************************

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

By default, when this option is false, on return are only the end points of
each solution path.

With this option set to true, on return are all intermediate solutions along a
path.  For large systems and/or complicated solution paths, the list on return
can be rather large.

Functions with optional argument named intermediateSolutions:
=============================================================

  * trackPaths(...,intermediateSolutions=>...)
    -- option to
    get all intermediate solutions on a path

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

The object intermediateSolutions, is a
symbol (Macaulay2Doc).

intersectSlice -- intersects a witness set by a slice
*****************************************************

Synopsis
========

  * Usage:
        fSols = intersectSlice(w, slice)
  * Inputs:
      * w, a witness set (NAGtypes), a witness set for a
        solution set
      * slice, a list (Macaulay2Doc), a list of linear equations
  * Outputs:
      * fSols, a list (Macaulay2Doc), solutions that satisfy
        w.Equations and the equations in the slice

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

A typical application is to find solutions for slices with real coefficients.

+-----------------------------------------------------------------------------+
|i1 : R=CC[a,b,c,d];                                                          |
+-----------------------------------------------------------------------------+
|i2 : M=matrix for i to 2 list for j to 3 list random(1,R)+random(0,R);       |
|-- warning: experimental computation over inexact field begun                |
|--          results not reliable (one warning given per session)             |
|                                                                             |
|             3      4                                                        |
|o2 : Matrix R  <-- R                                                         |
+-----------------------------------------------------------------------------+
|i3 : I=minors(3,M);                                                          |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : f=flatten entries gens I;                                               |
+-----------------------------------------------------------------------------+
|i5 : (w,ns) = topWitnessSet(f,2);                                            |
+-----------------------------------------------------------------------------+
|i6 : slcmat = matrix applyTable (entries w.Slice, x->1_CC*realPart x);       |
|                                                                             |
|                2         7                                                  |
|o6 : Matrix CC    <-- CC                                                     |
|              53        53                                                   |
+-----------------------------------------------------------------------------+
|i7 : Rtwo = ring w.Equations;                                                |
+-----------------------------------------------------------------------------+
|i8 : X = transpose matrix {gens Rtwo | {1_CC}};                              |
|                                                                             |
|                7         1                                                  |
|o8 : Matrix Rtwo  <-- Rtwo                                                   |
+-----------------------------------------------------------------------------+
|i9 : slcRR = flatten entries (promote(slcmat,Rtwo) * X);                     |
+-----------------------------------------------------------------------------+
|i10 : fsols = intersectSlice(w,slcRR)                                        |
|                                                                             |
|o10 = {{.278563-.243312*ii, -.092976+.923912*ii, -.508131+.698273*ii,        |
|      -----------------------------------------------------------------------|
|      -1.23146-.008271*ii, 2.40419e-15+2.72257e-15*ii,                       |
|      -----------------------------------------------------------------------|
|      -2.43538e-15-3.91302e-15*ii}, {-18.336+8.26936*ii, 3.7764-9.67765*ii,  |
|      -----------------------------------------------------------------------|
|      -13.7891-2.04541*ii, -1.28993+.094382*ii, -7.70412e-12-1.90445e-12*ii, |
|      -----------------------------------------------------------------------|
|      -1.06457e-11-2.38457e-11*ii}, {-5.13593-9.35491*ii, 7.19369+7.77241*ii,|
|      -----------------------------------------------------------------------|
|      1.77961-.856406*ii, -1.30143-.079476*ii, -8.17689e-13+7.72829e-13*ii,  |
|      -----------------------------------------------------------------------|
|      -4.95576e-13-2.07459e-12*ii}, {.171703+.292386*ii, .372401-.2657*ii,   |
|      -----------------------------------------------------------------------|
|      -.141952+.0040302*ii, -1.23561+.00268*ii, -1.73793e-15-4.06085e-15*ii, |
|      -----------------------------------------------------------------------|
|      2.85695e-15+1.00494e-15*ii}, {.07266-.862383*ii, .515658+.767545*ii,   |
|      -----------------------------------------------------------------------|
|      -.0901531-.0279888*ii, -1.23697-.007765*ii,                            |
|      -----------------------------------------------------------------------|
|      -3.08113e-15-2.49173e-15*ii, 4.97412e-15+2.95249e-15*ii},              |
|      -----------------------------------------------------------------------|
|      {.903518-2.84996*ii, 3.23789-.3435*ii, 3.39272-2.9677*ii,              |
|      -----------------------------------------------------------------------|
|      -1.25924-.000908*ii, -1.28671e-13-5.378e-14*ii,                        |
|      -----------------------------------------------------------------------|
|      6.62906e-14-9.24819e-14*ii}}                                           |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+

See also
========

  * topWitnessSet -- returns a witness set and
    nonsolutions for the top dimensional solution set

Ways to use intersectSlice:
===========================

  * "intersectSlice(WitnessSet,List)"

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

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

isCoordinateZero -- checks if coordinate has absolute value less than a given tolerance
***************************************************************************************

Synopsis
========

  * Usage:
        isCoordinateZero(sol,k,tol)
  * Inputs:
      * sol, a point (NAGtypes), solution to a polynomial
        system
      * k, an integer (Macaulay2Doc), index of coordinate
      * tol, a real number (Macaulay2Doc), tolerance on the absolute
        value of the k-th coordinate
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if the k-th
        coordinate of solution has absolute value less than tol, false
        otherwise

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

A solution has a zero k-th coordinate when the abs function evaluates to a
number less than the given tolerance.

+-------------------------------------------------+
|i1 : R = CC[x,y];                                |
+-------------------------------------------------+
|i2 : f = { x^3*y^5 + y^2 + x^2*y, x*y + x^2 - 1};|
+-------------------------------------------------+
|i3 : fSols = solveSystem(f, randomSeed=>3);      |
+-------------------------------------------------+
|i4 : fSols/print                                 |
|{-1, 0}                                          |
|{1, 0}                                           |
|{-1.59272, .964857}                              |
|{.742585+.425943*ii, .270685-1.00715*ii}         |
|{-.764107, -.544612}                             |
|{1.33076-.335184*ii, -.62414+.513163*ii}         |
|{-.894935-.624334*ii, .143333+1.14868*ii}        |
|{1.33076+.335184*ii, -.62414-.513163*ii}         |
|{-.894935+.624334*ii, .143333-1.14868*ii}        |
|{.742585-.425943*ii, .270685+1.00715*ii}         |
|                                                 |
|o4 = {, , , , , , , , , }                        |
|                                                 |
|o4 : List                                        |
+-------------------------------------------------+
|i5 : isCoordinateZero(fSols_0,1,1.0e-10)         |
|                                                 |
|o5 = true                                        |
+-------------------------------------------------+

Good values for the tolerance are relative to the accuracy and the condition
number of the solution. To improve the accuracy of a solution, apply
refineSolutions, with a higher working precision.

See also
========

  * refineSolutions -- refines solutions of a system by
    increasing working precision
  * zeroFilter -- returns solutions with k-th coordinate
    less than the given tolerance
  * nonZeroFilter -- returns solutions with coordinate
    larger than given tolerance

Ways to use isCoordinateZero:
=============================

  * "isCoordinateZero(AbstractPoint,ZZ,RR)"

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

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

isWitnessSetMember -- tests whether a point belongs to a solution set
*********************************************************************

Synopsis
========

  * Usage:
        isWitnessSetMember(W,p)
  * Inputs:
      * W, a witness set (NAGtypes), positive dimensional,
        properly embedded with slack variables
      * p, a point (NAGtypes),
  * Optional inputs (Macaulay2Doc),:
      * Verbose,
        => ..., default value false, option to specify whether additional
        output is wanted
  * Outputs:
      * a Boolean value (Macaulay2Doc), true if p is a member of
        the solution set of W, false otherwise
  * Consequences:
      * Invokes the command phc -f (with option 1)

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

Uses numerical homotopy methods to test whether the point p belongs to the
variety associated to the witness set W.

Although W should be properly embedded, p should be given in the coordinates of
the original system.

+----------------------------------------------------+
|i1 : R = CC[x11,x22,x21,x12,x23,x13];               |
+----------------------------------------------------+
|i2 : system = {x11*x22-x21*x12,x12*x23-x22*x13};    |
+----------------------------------------------------+
|i3 : V = numericalIrreducibleDecomposition (system);|
|found 4 irreducible factors                         |
+----------------------------------------------------+
|i4 : W = first V#4;                                 |
+----------------------------------------------------+
|i5 : isWitnessSetMember(W, point{{0,0,0,0,0,0}})    |
|                                                    |
|o5 = true                                           |
+----------------------------------------------------+

Ways to use isWitnessSetMember:
===============================

  * "isWitnessSetMember(WitnessSet,AbstractPoint)"

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

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

isWitnessSetMember(...,Verbose=>...) -- option to specify whether additional output is wanted
*********************************************************************************************

Synopsis
========

  * Usage:
        isWitnessSetMember(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output, which includes the input and solution
file names used by phc.

+----------------------------------------------------+
|i1 : R = CC[x11,x22,x21,x12,x23,x13];               |
+----------------------------------------------------+
|i2 : system = {x11*x22-x21*x12,x12*x23-x22*x13};    |
+----------------------------------------------------+
|i3 : V = numericalIrreducibleDecomposition (system);|
|found 4 irreducible factors                         |
+----------------------------------------------------+
|i4 : W = first V#4;                                 |
+----------------------------------------------------+
|i5 : isWitnessSetMember(W, point{{0,0,0,0,0,0}})    |
|                                                    |
|o5 = true                                           |
+----------------------------------------------------+

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

  * Default value: false (Macaulay2Doc),
  * Function: isWitnessSetMember, -- tests whether a
    point belongs to a solution set
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

loadSettingsPath -- option of trackPaths to load the settings for a reproducible rerun
**************************************************************************************

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

By default, this option is set to the empty string.

To apply the option, the user should give as string the argument used for the
option saveSettingsPath. With this option, one gets a reproducible run.

Functions with optional argument named loadSettingsPath:
========================================================

  * trackPaths(...,loadSettingsPath=>...)
    -- option to load
    the settings of the path trackers for a reproducible rerun

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

The object loadSettingsPath, is a symbol (Macaulay2Doc).

mixedVolume -- computes mixed volume of a polynomial system
***********************************************************

Synopsis
========

  * Usage:
        mv = mixedVolume(S)
        (mv,sv) = mixedVolume(S,StableMixedVolume => true)
        (mv,q,qsols) = mixedVolume(S,StartSystem => true)
        (mv,sv,q,qsols) = mixedVolume(S,StableMixedVolume => true,StartSystem => true)
        (mv,q,qsols) = mixedVolume(S,StartSystem => true,numThreads=4)
  * Inputs:
      * S, a list (Macaulay2Doc), whose entries are the polynomials
        of a square system
  * Optional inputs (Macaulay2Doc),:
      * interactive,
        => ..., default value false, option to switch to the interactive mode
        of phc -m
      * numThreads,
        => ..., default value 0, option to set the number of threads when
        solving a start system
      * StableMixedVolume,
        => ...,
        default value false, optional input for computation of the stable mixed
        volume
      * StartSystem,
        => ..., default value false, optional input for computation of mixed
        volume by solving a random coefficient system
      * Verbose, => ...,
        default value false, option to specify whether additional output is
        wanted
  * Outputs:
      * mv, an integer (Macaulay2Doc), the mixed volume of the system
        S
      * sv, an integer (Macaulay2Doc), the stable mixed volume of the
        system S
      * q, a list (Macaulay2Doc), whose entries are polynomials in
        a random coefficient system, used as a start system for the homotopy
      * qSols, a list (Macaulay2Doc), whose entries are solutions
        of the start system q
  * Consequences:
      * Writes the system to temporary files
      * Invokes the command phc -m (with option 4)
      * Stores output of phc in temporary file
      * Parses and outputs the solutions.

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

The mixed volume of a polynomial system $S:=\{f_1,\dots,f_n\}$ is defined as
follows: Let $P_1,\dots,P_n$ be the Newton polytopes of $f_1,\dots,f_n$, i.e.,
$P_i$ is the convex hull of the exponents of the monomials in the support of
$f_i$. The mixed volume of $S$ is $$ \sum_{1\leq h\leq n} \sum_{1\leq
i_1\dots\leq i_h\leq n} (-1)^{n-h}V_n(P_{i_1}+\dots+P_{i_h}), $$ where $V_n$
denotes the $n$-dimensional Euclidean volume.

Bernstein's theorem (D. N. Bernstein,The number of roots of a system of
equations, Functional. Anal. Appl 9 (1975), no. 3, 183-185), a generalization
of the classical Bezout's theorem, shows that for a zero-dimensional system,
the mixed volume provides an upper bound on the number of complex isolated
roots. If the coefficients of the system are sufficiently generic, the mixed
volume is a sharp bound.

+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : f = { x^3*y^5 + y^2 + x^2*y, x*y + x^2 - 1};                            |
+-----------------------------------------------------------------------------+
|i3 : I=ideal f;                                                              |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : dim I                                                                   |
|-- warning: experimental computation over inexact field begun                |
|--          results not reliable (one warning given per session)             |
|                                                                             |
|o4 = 0                                                                       |
+-----------------------------------------------------------------------------+
|i5 : degree I                                                                |
|                                                                             |
|o5 = 10                                                                      |
+-----------------------------------------------------------------------------+
|i6 : m = mixedVolume(f) -- counts the number of complex roots in the torus   |
|                                                                             |
|o6 = 8                                                                       |
|-----------------------------------------------------------------------------|
|(without zero components)                                                    |
+-----------------------------------------------------------------------------+
|i7 : (mv,sv) = mixedVolume(f,StableMixedVolume=>true)                        |
|                                                                             |
|o7 = (8, 10)                                                                 |
|                                                                             |
|o7 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i8 : (mv,q,qsols) = mixedVolume(f,StartSystem=>true);                        |
+-----------------------------------------------------------------------------+
|i9 : q --let's take a look at the start system:                              |
|                                                                             |
|                               3 5                          2                |
|o9 = {(- .205377 - .978683*ii)x y  + (.943327 - .331864*ii)x y, (.673112 +   |
|     ------------------------------------------------------------------------|
|                 2                                                           |
|     .739541*ii)x  - .911067 - .412259*ii}                                   |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : qsols --and its solutions:                                             |
|                                                                             |
|o10 = {{.979319-.202321*ii, .930645-.365923*ii}, {-.979319+.202321*ii,       |
|      -----------------------------------------------------------------------|
|      .916812+.399319*ii}, {.979319-.202321*ii, .365923+.930645*ii},         |
|      -----------------------------------------------------------------------|
|      {-.979319+.202321*ii, -.399319+.916812*ii}, {.979319-.202321*ii,       |
|      -----------------------------------------------------------------------|
|      -.930645+.365923*ii}, {-.979319+.202321*ii, -.916812-.399319*ii},      |
|      -----------------------------------------------------------------------|
|      {.979319-.202321*ii, -.365923-.930645*ii}, {-.979319+.202321*ii,       |
|      -----------------------------------------------------------------------|
|      .399319-.916812*ii}}                                                   |
|                                                                             |
|o10 : List                                                                   |
+-----------------------------------------------------------------------------+

Note that only those solutions with nonzero components are shown, even if
StableMixedVolume is true.  See the end of the temporary output file for the
solutions with zero components.

The method mixedVolume calls an Ada translation of ACM TOMS Algorithm 846:
MixedVol: a software package for mixed-volume computation by Tangan Gao, T. Y.
Li, Mengnien Wu, ACM TOMS (see
http://portal.acm.org/citation.cfm?doid=1114268.1114274 ) 31(4):555-560, 2005.

See also
========

  * StableMixedVolume -- optional input for
    computation of the stable mixed volume
  * StartSystem -- optional input to construct and solve a
    random coefficient system

Ways to use mixedVolume:
========================

  * "mixedVolume(List)"

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

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

mixedVolume(...,interactive=>...) -- option to switch to the interactive mode of phc -m
***************************************************************************************

Synopsis
========

  * Usage:
        solveSystem(...,interactive=>true)

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

  * Default value: false (Macaulay2Doc),
  * Function: mixedVolume, -- computes mixed volume of a
    polynomial system
  * Option key: interactive, -- flag to run phc -p or phc -m
    in interactive mode

Functions with optional argument named interactive:
===================================================

  * trackPaths(...,interactive=>...)
    -- Option to run phc -p
    in interactive mode.

mixedVolume(...,numThreads=>...) -- option to set the number of threads when solving a start system
***************************************************************************************************

Synopsis
========

  * Usage:
        solveSystem(...,StartSystems=>true,numThreads=>ZZ)

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

Use numThreads=>4 to run the path trackers with 4 threads.

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

  * Default value: 0
  * Function: mixedVolume, -- computes mixed volume of a
    polynomial system
  * Option key: numThreads, -- the number of threads in the
    path tracker

Functions with optional argument named numThreads:
==================================================

  * solveSystem(...,numThreads=>...)
    -- option to set the
    number of threads
  * trackPaths(...,numThreads=>...)
    -- Option to define the
    number of threads in the path tracker.

mixedVolume(...,StableMixedVolume=>...) -- optional input for computation of the stable mixed volume
****************************************************************************************************

Synopsis
========

  * Usage:
        mixedVolume(...,StableMixedVolume=>Boolean)

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

  * Default value: false (Macaulay2Doc),
  * Function: mixedVolume, -- computes mixed volume of a
    polynomial system
  * Option key: StableMixedVolume, -- optional input
    for computation of the stable mixed volume

mixedVolume(...,StartSystem=>...) -- optional input for computation of mixed volume by solving a random coefficient system
**************************************************************************************************************************

Synopsis
========

  * Usage:
        mixedVolume(...,StartSystem=>Boolean)

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

  * Default value: false (Macaulay2Doc),
  * Function: mixedVolume, -- computes mixed volume of a
    polynomial system
  * Option key: StartSystem, -- optional input to construct
    and solve a random coefficient system

mixedVolume(...,Verbose=>...) -- option to specify whether additional output is wanted
**************************************************************************************

Synopsis
========

  * Usage:
        mixedVolume(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output which includes the input and solution
file names used by phc.

The output file of phc contains timings for the mixed volume and provides
details about the mixed-cell configuration.

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

  * Default value: false (Macaulay2Doc),
  * Function: mixedVolume, -- computes mixed volume of a
    polynomial system
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

nonZeroFilter -- returns solutions with coordinate larger than given tolerance
******************************************************************************

Synopsis
========

  * Usage:
        nonZeroSols = nonZeroFilter(sols,k,tol)
  * Inputs:
      * sols, a list (Macaulay2Doc), solutions of a polynomial
        system
      * k, an integer (Macaulay2Doc), index to a coordinate of a
        solution
      * tol, a real number (Macaulay2Doc), tolerance on the abs value
        of the k-th coordinate
  * Outputs:
      * nonZeroSols, a list (Macaulay2Doc), solutions with k-th
        coordinate larger than the given tolerance

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

A solution has its k-th coordinate non-zero when the abs function evaluates to
a number greater than the given tolerance.

+--------------------------------------------------+
|i1 : R = CC[x,y];                                 |
+--------------------------------------------------+
|i2 : f = { x^3*y^5 + y^2 + x^2*y, x*y + x^2 - 1}; |
+--------------------------------------------------+
|i3 : fSols = solveSystem(f, randomSeed=>3);       |
+--------------------------------------------------+
|i4 : fSols/print                                  |
|{-1, 0}                                           |
|{1, 0}                                            |
|{-1.59272, .964857}                               |
|{.742585+.425943*ii, .270685-1.00715*ii}          |
|{-.764107, -.544612}                              |
|{1.33076-.335184*ii, -.62414+.513163*ii}          |
|{-.894935-.624334*ii, .143333+1.14868*ii}         |
|{1.33076+.335184*ii, -.62414-.513163*ii}          |
|{-.894935+.624334*ii, .143333-1.14868*ii}         |
|{.742585-.425943*ii, .270685+1.00715*ii}          |
|                                                  |
|o4 = {, , , , , , , , , }                         |
|                                                  |
|o4 : List                                         |
+--------------------------------------------------+
|i5 : nonZeroSols = nonZeroFilter(fSols,1,1.0e-10);|
+--------------------------------------------------+
|i6 : nonZeroSols / print                          |
|{-1.59272, .964857}                               |
|{.742585+.425943*ii, .270685-1.00715*ii}          |
|{-.764107, -.544612}                              |
|{1.33076-.335184*ii, -.62414+.513163*ii}          |
|{-.894935-.624334*ii, .143333+1.14868*ii}         |
|{1.33076+.335184*ii, -.62414-.513163*ii}          |
|{-.894935+.624334*ii, .143333-1.14868*ii}         |
|{.742585-.425943*ii, .270685+1.00715*ii}          |
|                                                  |
|o6 = {, , , , , , , }                             |
|                                                  |
|o6 : List                                         |
+--------------------------------------------------+

Here is another system where we filter solutions with `large enough' first
coordinate:

+---------------------------------------------------------+
|i7 : f = {x^2+y^2,y*x+x};                                |
+---------------------------------------------------------+
|i8 : fSols = solveSystem(f);                             |
+---------------------------------------------------------+
|i9 : fSols/print                                         |
|(-2.46519e-32+1.07852e-32*ii, -2.40467e-32+9.0524e-34*ii)|
|{-ii, -1}                                                |
|{ii, -1}                                                 |
|                                                         |
|o9 = {, , }                                              |
|                                                         |
|o9 : List                                                |
+---------------------------------------------------------+
|i10 : zeroSols = zeroFilter(fSols,0,1.0e-10);            |
+---------------------------------------------------------+
|i11 : zeroSols/print                                     |
|(-2.46519e-32+1.07852e-32*ii, -2.40467e-32+9.0524e-34*ii)|
|                                                         |
|o11 = {}                                                 |
|                                                         |
|o11 : List                                               |
+---------------------------------------------------------+

Good values for the tolerance are relative to the accuracy and the condition
number of the solution. To improve the accuracy of a solution, apply
refineSolutions, with a higher working precision.

The method returns the complement of the result of zeroFilter.

See also
========

  * refineSolutions -- refines solutions of a system by
    increasing working precision
  * zeroFilter -- returns solutions with k-th coordinate
    less than the given tolerance

Ways to use nonZeroFilter:
==========================

  * "nonZeroFilter(List,ZZ,RR)"

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

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

numericalIrreducibleDecomposition -- finds the irreducible components of the zero set of a system of polynomials
****************************************************************************************************************

Synopsis
========

  * Usage:
        numericalIrreducibleDecomposition (system)
  * Inputs:
      * system, a list (Macaulay2Doc), a system of polynomials,
        with no more equations than indeterminates
  * Optional inputs (Macaulay2Doc),:
      * StartDimension,
        => ..., default value -1, Option to
        specify the dimension to begin searching for positive dimensional
        components
      * Verbose,
        => ..., default value false, option to specify whether
        additional output is wanted
  * Outputs:
      * a numerical variety (NAGtypes), containing a
        witness set for each irreducible component
  * Consequences:
      * This function calls cascade, and factorWitnessSet.

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

Given a list of generators of an ideal I, this function returns a
NumericalVariety (NAGtypes), with a WitnessSet (NAGtypes),
for each irreducible component of V(I).

+--------------------------------------------------------------+
|i1 : R=CC[x11,x22,x21,x12,x23,x13,x14,x24];                   |
+--------------------------------------------------------------+
|i2 : system={x11*x22-x21*x12,x12*x23-x22*x13,x13*x24-x23*x14};|
+--------------------------------------------------------------+
|i3 : V=numericalIrreducibleDecomposition(system)              |
|found 6 irreducible factors                                   |
|                                                              |
|o3 = V                                                        |
|                                                              |
|o3 : NumericalVariety                                         |
+--------------------------------------------------------------+
|i4 : WitSets=V#5; --witness sets are accessed by dimension    |
+--------------------------------------------------------------+
|i5 : w=first WitSets;                                         |
+--------------------------------------------------------------+
|i6 : w.cache.IsIrreducible                                    |
|                                                              |
|o6 = true                                                     |
+--------------------------------------------------------------+

In the above example we found three components of dimension five, we can check
the solution using symbolic methods.

+-----------------------------------------------------------------------------+
|i7 : R=QQ[x11,x22,x21,x12,x23,x13,x14,x24];                                  |
+-----------------------------------------------------------------------------+
|i8 : system={x11*x22-x21*x12,x12*x23-x22*x13,x13*x24-x23*x14};               |
+-----------------------------------------------------------------------------+
|i9 : PD=primaryDecomposition(ideal(system))                                  |
|                                                                             |
|o9 = {ideal (x13, x23, x11*x22 - x21*x12), ideal (x12, x22, x23*x14 -        |
|     ------------------------------------------------------------------------|
|     x13*x24), ideal (x23*x14 - x13*x24, x21*x14 - x11*x24, x22*x14 -        |
|     ------------------------------------------------------------------------|
|     x12*x24, x12*x23 - x22*x13, x11*x23 - x21*x13, x11*x22 - x21*x12)}      |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+
|i10 : for i from 0 to 2 do print ("dim =" | dim PD_i | "  " | "degree=" |    |
|dim =5  degree=2                                                             |
|dim =5  degree=2                                                             |
|dim =5  degree=4                                                             |
|-----------------------------------------------------------------------------|
|degree PD_i)                                                                 |
+-----------------------------------------------------------------------------+

See also
========

  * cascade -- runs a cascade of homotopies to get witness sets
    for the variety
  * factorWitnessSet -- applies monodromy to factor a
    witness set into irreducible components
  * solveSystem -- a numerical blackbox solver

Ways to use numericalIrreducibleDecomposition:
==============================================

  * "numericalIrreducibleDecomposition(List)"

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

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

numericalIrreducibleDecomposition(...,StartDimension=>...) -- Option to specify the dimension to begin searching for positive dimensional components
****************************************************************************************************************************************************

Synopsis
========

  * Usage:
        numericalIrreducibleDecomposition(...,StartDimension=>ZZ)

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

  * Default value: -1
  * Function: numericalIrreducibleDecomposition,
    -- finds the irreducible components of
    the zero set of a system of polynomials
  * Option key: StartDimension, -- optional input for
    cascade and numericalIrreducibleDecomposition

Functions with optional argument named StartDimension:
======================================================

  * cascade(...,StartDimension=>...)
    -- Option to specify
    the dimension to begin searching for positive dimensional components
  * numericalIrreducibleDecomposition(...,StartDimension=>...)
    -- Option to specify the dimension to begin searching for positive
    dimensional components

numericalIrreducibleDecomposition(...,Verbose=>...) -- option to specify whether additional output is wanted
************************************************************************************************************

Synopsis
========

  * Usage:
        numericalIrreducibleDecomposition(...,Verbose=>Boolean)

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

The value of the Verbose option (by default set to false) is passed to the
methods cascade and factorWitnessSet.

The output file of phc contains timings for all stages in the numerical
irreducible decomposition.

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

  * Default value: false (Macaulay2Doc),
  * Function: numericalIrreducibleDecomposition,
    -- finds the irreducible components of
    the zero set of a system of polynomials
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

numThreads -- the number of threads in the path tracker
*******************************************************

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

Tracking many solution paths is a pleasingly parallel computation. A
multithreaded path tracker has a number of threads working on a queue of path
tracking jobs.  Every path tracking job can be computed without communication
overhead.  For sufficiently large problems, the speedup can as large as the
number of threads.

Functions with optional argument named numThreads:
==================================================

  * mixedVolume(...,numThreads=>...)
    -- option to set the
    number of threads when solving a start system
  * solveSystem(...,numThreads=>...)
    -- option to set the
    number of threads
  * trackPaths(...,numThreads=>...)
    -- Option to define the
    number of threads in the path tracker.

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

The object numThreads, is a symbol (Macaulay2Doc).

randomSeed -- seed for the random number generators
***************************************************

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

To avoid singularities during complex path following, the homotopy methods use
a random constant. Different runs with solveSystem, trackPaths, or mixedVolume
(with StartSystem set to true) may therefore lead to the solutions listed in a
different order. Fixing the value of randomSeed leads to reproducible runs.

Functions with optional argument named randomSeed:
==================================================

  * solveSystem(...,randomSeed=>...)
    -- option to set the
    seed of the random number generators

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

The object randomSeed, is a symbol (Macaulay2Doc).

realSlice1D -- computes a real slice for a one dimensional witness set
**********************************************************************

Synopsis
========

  * Usage:
        slc = realSlice1D(w)
  * Inputs:
      * w, a witness set (NAGtypes), a witness set for a
        solution set
  * Optional inputs (Macaulay2Doc),:
      * searchDelta,
        => ..., default value .1, option of realSlice1D
      * searchNpoints,
        => ..., default value 20, option of realSlice1D
      * searchTolerance,
        => ...,
        default value .0001, option of realSlice1D
  * Outputs:
      * slc, a list (Macaulay2Doc), list of linear equations with
        the largest number of real solutions

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

A real slice is a set of linear equations with the largest number of real
solutions of the equations for a given witness set.

+-------------------+
|i1 : R = CC[x,y,z];|
+-------------------+

See also
========

  * intersectSlice -- intersects a witness set by a
    slice

Ways to use realSlice1D:
========================

  * "realSlice1D(WitnessSet)"

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

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

realSlice1D(...,searchDelta=>...) -- option of realSlice1D
**********************************************************

Synopsis
========

  * Usage:
        realSlice1D(...,searchDelta=>Number)

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

  * Default value: .1
  * Function: realSlice1D, -- computes a real slice for a
    one dimensional witness set
  * Option key: searchDelta, -- option of realSlice1D

Functions with optional argument named searchDelta:
===================================================

  * realSlice1D(...,searchDelta=>...)
    -- option of
    realSlice1D
  * realSlice2D(...,searchDelta=>...)
    -- option of
    realSlice2D

realSlice1D(...,searchNpoints=>...) -- option of realSlice1D
************************************************************

Synopsis
========

  * Usage:
        realSlice1D(...,searchNpoints=>Number)

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

  * Default value: 20
  * Function: realSlice1D, -- computes a real slice for a
    one dimensional witness set
  * Option key: searchNpoints, -- option of realSlice1D

Functions with optional argument named searchNpoints:
=====================================================

  * realSlice1D(...,searchNpoints=>...)
    -- option of
    realSlice1D
  * realSlice2D(...,searchNpoints=>...)
    -- option of
    realSlice2D

realSlice1D(...,searchTolerance=>...) -- option of realSlice1D
**************************************************************

Synopsis
========

  * Usage:
        realSlice1D(...,searchTolerance=>Number)

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

  * Default value: .0001
  * Function: realSlice1D, -- computes a real slice for a
    one dimensional witness set
  * Option key: searchTolerance, -- option of
    realSlice1D

Functions with optional argument named searchTolerance:
=======================================================

  * realSlice1D(...,searchTolerance=>...)
    -- option of
    realSlice1D
  * realSlice2D(...,searchTolerance=>...)
    -- option of
    realSlice2D

realSlice2D -- computes a real slice for a two dimensional witness set
**********************************************************************

Synopsis
========

  * Usage:
        slc = realSlice2D(w)
  * Inputs:
      * w, a witness set (NAGtypes), a witness set for a
        solution set
  * Optional inputs (Macaulay2Doc),:
      * searchDelta,
        => ..., default value .1, option of realSlice2D
      * searchNpoints,
        => ..., default value 5, option of realSlice2D
      * searchTolerance,
        => ...,
        default value .0001, option of realSlice2D
  * Outputs:
      * slc, a list (Macaulay2Doc), list of linear equations with
        the largest number of real solutions

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

A real slice is a set of linear equations with the largest number of real
solutions of the equations for a given witness set.

+-------------------+
|i1 : R = CC[x,y,z];|
+-------------------+

See also
========

  * intersectSlice -- intersects a witness set by a
    slice

Ways to use realSlice2D:
========================

  * "realSlice2D(WitnessSet)"

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

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

realSlice2D(...,searchDelta=>...) -- option of realSlice2D
**********************************************************

Synopsis
========

  * Usage:
        realSlice2D(...,searchDelta=>Number)

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

  * Default value: .1
  * Function: realSlice2D, -- computes a real slice for a
    two dimensional witness set
  * Option key: searchDelta, -- option of realSlice1D

Functions with optional argument named searchDelta:
===================================================

  * realSlice1D(...,searchDelta=>...)
    -- option of
    realSlice1D
  * realSlice2D(...,searchDelta=>...)
    -- option of
    realSlice2D

realSlice2D(...,searchNpoints=>...) -- option of realSlice2D
************************************************************

Synopsis
========

  * Usage:
        realSlice2D(...,searchNpoints=>Number)

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

  * Default value: 5
  * Function: realSlice2D, -- computes a real slice for a
    two dimensional witness set
  * Option key: searchNpoints, -- option of realSlice1D

Functions with optional argument named searchNpoints:
=====================================================

  * realSlice1D(...,searchNpoints=>...)
    -- option of
    realSlice1D
  * realSlice2D(...,searchNpoints=>...)
    -- option of
    realSlice2D

realSlice2D(...,searchTolerance=>...) -- option of realSlice2D
**************************************************************

Synopsis
========

  * Usage:
        realSlice2D(...,searchTolerance=>Number)

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

  * Default value: .0001
  * Function: realSlice2D, -- computes a real slice for a
    two dimensional witness set
  * Option key: searchTolerance, -- option of
    realSlice1D

Functions with optional argument named searchTolerance:
=======================================================

  * realSlice1D(...,searchTolerance=>...)
    -- option of
    realSlice1D
  * realSlice2D(...,searchTolerance=>...)
    -- option of
    realSlice2D

refineSolutions -- refines solutions of a system by increasing working precision
********************************************************************************

Synopsis
========

  * Usage:
        newSols = refineSolutions(f,sols,dp)
  * Inputs:
      * f, a list (Macaulay2Doc), a system of polynomials
      * sols, a list (Macaulay2Doc), solutions of the system f,
        each of type AbstractPoint (NAGtypes), (from a
        previous calculation)
      * dp, an integer (Macaulay2Doc), the number of decimal places
        in working precision
  * Optional inputs (Macaulay2Doc),:
      * Verbose, =>
        ..., default value false, option to specify whether additional output
        is wanted
  * Outputs:
      * newSols, a list (Macaulay2Doc), the solutions sols of f
        refined to increased precision of dp decimal places
  * Consequences:
      * writes a system to a temporary file,
      * invokes the command phc -v (with option 3),
      * stores phc output in a temporary file,
      * parses and prints the refined solutions.

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

The user can specify the number of decimal places desired to refine solutions.

Let us compute a square root with a working precision of 64 decimal places:

+----------------------------------------------------------------------+
|i1 : R = CC[x,y]; S = {x^2 - 1/3, x*y - 1}; ourRoots = solveSystem(S);|
+----------------------------------------------------------------------+
|i4 : r0 = ourRoots#0#Coordinates#1                                    |
|                                                                      |
|o4 = 1.73205080756888                                                 |
|                                                                      |
|o4 : CC (of precision 53)                                             |
+----------------------------------------------------------------------+
|i5 : newRoots = refineSolutions(S,ourRoots,64)                        |
|                                                                      |
|o5 = {{.57735, 1.73205}, {-.57735, -1.73205}}                         |
|                                                                      |
|o5 : List                                                             |
+----------------------------------------------------------------------+
|i6 : newRoots#0 -- recall that solutions are of type Point            |
|                                                                      |
|o6 = {.57735, 1.73205}                                                |
|                                                                      |
|o6 : Point                                                            |
+----------------------------------------------------------------------+
|i7 : r1 = newRoots#0#Coordinates#1                                    |
|                                                                      |
|o7 = 1.73205080756887735414922460641658082304678611432812598193257967 |
|                                                                      |
|o7 : CC (of precision 213)                                            |
+----------------------------------------------------------------------+

Ways to use refineSolutions:
============================

  * "refineSolutions(List,List,ZZ)"

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

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

refineSolutions(...,Verbose=>...) -- option to specify whether additional output is wanted
******************************************************************************************

Synopsis
========

  * Usage:
        refineSolutions(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output which includes the input and solution
file names used by phc -v.

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

  * Default value: false (Macaulay2Doc),
  * Function: refineSolutions, -- refines solutions of a
    system by increasing working precision
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

saveSettingsPath -- option of trackPaths to save the settings for a reproducible rerun
**************************************************************************************

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

By default, this option is set to the empty string.

If the user provides a string that is not the empty string, then the settings
of the path tracker are saved for a rerun. Calling trackPaths, giving the same
string to loadSettingsPath, enables a reproducible run.

Functions with optional argument named saveSettingsPath:
========================================================

  * trackPaths(...,saveSettingsPath=>...)
    -- option to save
    the settings of the path trackers for a reproducible rerun

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

The object saveSettingsPath, is a symbol (Macaulay2Doc).

searchDelta -- option of realSlice1D
************************************

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

In the line search we need to set the width of the search interval. After a
discretization, the golden section search method is applied to the interval [p
- searchDelta, p + searchDelta], where p is the point where the minimum value
after the discretization was found.

Functions with optional argument named searchDelta:
===================================================

  * realSlice1D(...,searchDelta=>...)
    -- option of
    realSlice1D
  * realSlice2D(...,searchDelta=>...)
    -- option of
    realSlice2D

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

The object searchDelta, is a symbol (Macaulay2Doc).

searchNpoints -- option of realSlice1D
**************************************

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

Before the line search, a discretization of the range of the slices is
computed.  The value of searchNpoints sets the number of equidistant points in
this range of slices.

Functions with optional argument named searchNpoints:
=====================================================

  * realSlice1D(...,searchNpoints=>...)
    -- option of
    realSlice1D
  * realSlice2D(...,searchNpoints=>...)
    -- option of
    realSlice2D

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

The object searchNpoints, is a symbol (Macaulay2Doc).

searchTolerance -- option of realSlice1D
****************************************

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

The golden section search method stops when the width of the current interval
which contains the minimum is smaller than searchTolerance. For unimodal
functions, searchTolerance will be the bound on the accuracy of the location of
the minimum.

Functions with optional argument named searchTolerance:
=======================================================

  * realSlice1D(...,searchTolerance=>...)
    -- option of
    realSlice1D
  * realSlice2D(...,searchTolerance=>...)
    -- option of
    realSlice2D

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

The object searchTolerance, is a symbol (Macaulay2Doc).

seeProgress -- flag to monitor the progress of the multithreaded path tracker
*****************************************************************************

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

For a long path tracking job, one could check the progress of the computation
by checking the end of the output file. A multithreaded path tracker no longer
writes the solutions to the output file as soon as they are computed.  For path
tracking jobs that take a very long time, the lack of information on the
progress can be annoying.  With seeProgess turned on, every thread will write a
message to screen for each path tracking job.

Functions with optional argument named seeProgress:
===================================================

  * trackPaths(...,seeProgress=>...)
    -- Option to follow the
    progress of the multithreaded path tracker.

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

The object seeProgress, is a symbol (Macaulay2Doc).

solveRationalSystem -- approximates solutions to a rational system of equations
*******************************************************************************

Synopsis
========

  * Usage:
        solveRationalSystem (f)
  * Inputs:
      * f, a list (Macaulay2Doc), a system of rational equations
        with a finite number of solutions
  * Optional inputs (Macaulay2Doc),:
      * Verbose,
        => ..., default value false, option to specify whether additional
        output is wanted
  * Outputs:
      * a list (Macaulay2Doc), containing the solutions of f, each
        of type Point (NAGtypes),
  * Consequences:
      * converts the rational system into a Laurent system, invokes the
        commands phc -b and phc -z,
      * adds slack variables if needed (i.e. if system is overdetermined),
      * writes the system to temporary file,
      * launches the blackbox solver,
      * stores the output of phc in a temporary file,
      * parses and outputs the solutions.

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

This function returns numerical approximations of all complex solutions of a
rational system. The function converts the system to a Laurent polynomial
system and then calls PHCpack's blackbox solver.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i2 : system = {y-x^2, z-x^3, (x+y+z-1)/x};                                   |
+-----------------------------------------------------------------------------+
|i3 : sols = solveRationalSystem(system)                                      |
|                                                                             |
|o3 = {{.543689, .295598, .160713}, {-.771845-1.11514*ii, -.647799+1.72143*ii,|
|     ------------------------------------------------------------------------|
|     2.41964-.606291*ii}, {-.771845+1.11514*ii, -.647799-1.72143*ii,         |
|     ------------------------------------------------------------------------|
|     2.41964+.606291*ii}}                                                    |
|                                                                             |
|o3 : List                                                                    |
+-----------------------------------------------------------------------------+

The solutions are of type Point (NAGtypes). Each point p
comes with cached diagnostics. For example, p.cache.LastT is the end value of
the continuation parameter; if it equals 1, then the solver reached the end of
the path properly.

+------------------------------------------------------+
|i4 : peek first sols                                  |
|                                                      |
|o4 = Point{cache => CacheTable{...3...}              }|
|           Coordinates => {.543689, .295598, .160713} |
+------------------------------------------------------+

See also
========

  * solveSystem -- a numerical blackbox solver
  * toLaurentPolynomial -- converts a list of
    rational polynomials into Laurent polynomials

Ways to use solveRationalSystem:
================================

  * "solveRationalSystem(List)"

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

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

solveRationalSystem(...,Verbose=>...) -- option to specify whether additional output is wanted
**********************************************************************************************

Synopsis
========

  * Usage:
        solveRationalSystem(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output which includes the input and solution
file names used by phc.

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

  * Default value: false (Macaulay2Doc),
  * Function: solveRationalSystem, -- approximates
    solutions to a rational system of equations
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

solveSystem -- a numerical blackbox solver
******************************************

Synopsis
========

  * Usage:
        solveSystem(S)
        solveSystem(S,numThreads=>4)
        solveSystem(S,computingPrecision=>2)
        solveSystem(S,randomSeed=>12345)
  * Inputs:
      * S, a list (Macaulay2Doc), contains a zero-dimensional
        system of polynomials with complex coefficients that contains at least
        as many equations as indeterminates
  * Optional inputs (Macaulay2Doc),:
      * computingPrecision,
        => ...,
        default value 1, option to specify the working precision
      * numThreads,
        => ..., default value 0, option to set the number of threads
      * randomSeed,
        => ..., default value -1, option to set the seed of the random number
        generators
      * Verbose, => ...,
        default value false, option to specify whether additional output is
        wanted
  * Outputs:
      * a list (Macaulay2Doc), containing the solutions of S, each
        of type Point (NAGtypes).
  * Consequences:
      * Writes the system to temporary file
      * Adds slack variables if needed (i.e. if system is overdetermined)
      * Invokes the command phc -b (launches the blackbox solver)
      * Stores output of phc in temporary file
      * Parses and outputs the solutions.

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

Suppose we want numerical approximations of all complex isolated solutions to
the following system:

+--------------------------------------------+
|i1 : R = CC[x,y,z]                          |
|                                            |
|o1 = R                                      |
|                                            |
|o1 : PolynomialRing                         |
+--------------------------------------------+
|i2 : S = {x+y+z-1, x^2+y^2, x+y-z-3}        |
|                                            |
|                      2    2                |
|o2 = {x + y + z - 1, x  + y , x + y - z - 3}|
|                                            |
|o2 : List                                   |
+--------------------------------------------+

We call PHCpack's blackbox solver:

+-----------------------------------------+
|i3 : L = solveSystem(S)                  |
|                                         |
|o3 = {{1-ii, 1+ii, -1}, {1+ii, 1-ii, -1}}|
|                                         |
|o3 : List                                |
+-----------------------------------------+

The method solveSystem prints the PHCpack input and output file names and
returns two solutions. The solutions are of type Point (NAGtypes),
defined in NAGtypes. Each point
p comes with cached diagnostics. For example, p.cache.LastT is the end value of
the continuation parameter; if it equals 1, then the solver reached the end of
the path properly.

+-------------------------------------------+
|i4 : oneSoln = L_0                         |
|                                           |
|o4 = oneSoln                               |
|                                           |
|o4 : Point                                 |
+-------------------------------------------+
|i5 : peek oneSoln                          |
|                                           |
|o5 = Point{cache => CacheTable{...3...}   }|
|           Coordinates => {1-ii, 1+ii, -1} |
+-------------------------------------------+

The method handles overdetermined systems by inserting slack variables.

+--------------------------------------------------------+
|i6 : system = {y-x^2, z-x^3, x+y+z-1, x+y+ x^3 -1}      |
|                                                        |
|         2         3                      3             |
|o6 = {- x  + y, - x  + z, x + y + z - 1, x  + x + y - 1}|
|                                                        |
|o6 : List                                               |
+--------------------------------------------------------+
|i7 : #system > numcols vars R --overdetermined system   |
|                                                        |
|o7 = true                                               |
+--------------------------------------------------------+
|i8 : solns = solveSystem(system);                       |
|*** after parseSolutions, ring has {x, y, z} ***        |
+--------------------------------------------------------+
|i9 : numSolns = #solns                                  |
|                                                        |
|o9 = 3                                                  |
+--------------------------------------------------------+

Caveat
======

The method solveSystem does not check the dimension of the system; it checks
for number of equations instead. So solveSystem will return an error if there
are less equations than unknowns even if the system is zero-dimensional. In
addition, if the system is square but not zero-dimensional, the output is
meaningless.  Thus, it is suggested that the user checks the dimension of the
system before using solveSystem.

See also
========

  * solveRationalSystem -- approximates solutions
    to a rational system of equations

Ways to use solveSystem:
========================

  * "solveSystem(List)"

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

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

solveSystem(...,computingPrecision=>...) -- option to specify the working precision
***********************************************************************************

Synopsis
========

  * Usage:
        solveSystem(...,computingPrecision=>ZZ)

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

Use computingPrecision=>2 for double double precision.

Use computingPrecision=>4 for quad double precision.

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

  * Default value: 1
  * Function: solveSystem, -- a numerical blackbox solver
  * Option key: computingPrecision, -- flag to switch
    to double double or quad double precision

Functions with optional argument named computingPrecision:
==========================================================

  * solveSystem(...,computingPrecision=>...)
    -- option to
    specify the working precision

solveSystem(...,numThreads=>...) -- option to set the number of threads
***********************************************************************

Synopsis
========

  * Usage:
        solveSystem(...,numThreads=>ZZ)

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

Use numThreads=>4 to run the path trackers with 4 threads.

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

  * Default value: 0
  * Function: solveSystem, -- a numerical blackbox solver
  * Option key: numThreads, -- the number of threads in the
    path tracker

Functions with optional argument named numThreads:
==================================================

  * solveSystem(...,numThreads=>...)
    -- option to set the
    number of threads
  * trackPaths(...,numThreads=>...)
    -- Option to define the
    number of threads in the path tracker.

solveSystem(...,randomSeed=>...) -- option to set the seed of the random number generators
******************************************************************************************

Synopsis
========

  * Usage:
        solveSystem(...,randomSeed=>ZZ)

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

Use randomSeed=>12345 to set the seed to 12345.

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

  * Default value: -1
  * Function: solveSystem, -- a numerical blackbox solver
  * Option key: randomSeed, -- seed for the random number
    generators

Functions with optional argument named randomSeed:
==================================================

  * solveSystem(...,randomSeed=>...)
    -- option to set the
    seed of the random number generators

solveSystem(...,Verbose=>...) -- option to specify whether additional output is wanted
**************************************************************************************

Synopsis
========

  * Usage:
        solveSystem(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output which includes the input and solution
file names used by phc.

The output file of phc contains timings for the stages in the solver.

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

  * Default value: false (Macaulay2Doc),
  * Function: solveSystem, -- a numerical blackbox solver
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

StableMixedVolume -- optional input for computation of the stable mixed volume
******************************************************************************

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

Put StableMixedVolume=>true as an argument in the function mixedVolume,
to count solutions in affine space.

Functions with optional argument named StableMixedVolume:
=========================================================

  * mixedVolume(...,StableMixedVolume=>...)
    -- optional
    input for computation of the stable mixed volume

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

The object StableMixedVolume, is a symbol (Macaulay2Doc).

StartDimension -- optional input for cascade and numericalIrreducibleDecomposition
**********************************************************************************

Synopsis
========

  * Usage:
        cascade(..., StartDimension => ZZ) or numericalIrreducibleDecomposition(..., StartDimension =>ZZ)

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

Optional argument for cascade and numericalIrreducibleDecomposition. These
methods search for positive dimensional components starting at the
StartDimension and then considering all the subsequent lower dimensions.

The default value for StartDimension is the number of variables in the system
minus one.

If the user has a good idea about the top dimension, using a smaller
StartDimension than the default will reduce the computational time.

Functions with optional argument named StartDimension:
======================================================

  * cascade(...,StartDimension=>...)
    -- Option to specify
    the dimension to begin searching for positive dimensional components
  * numericalIrreducibleDecomposition(...,StartDimension=>...)
    -- Option to specify the dimension to begin searching for positive
    dimensional components

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

The object StartDimension, is a symbol (Macaulay2Doc).

StartSystem -- optional input to construct and solve a random coefficient system
********************************************************************************

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

Put StartSystem=>true as an argument in the function mixedVolume,
to tell the method to use polyhedral homotopies.  Polyhedral
homotopies solve a system with the same Newton polytopes as the original system
and with random complex coefficients. This random coefficient system can serve
as a start system to solve the original input system.

Functions with optional argument named StartSystem:
===================================================

  * mixedVolume(...,StartSystem=>...)
    -- optional input for
    computation of mixed volume by solving a random coefficient system

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

The object StartSystem, is a symbol (Macaulay2Doc).

tDegree -- the degree of the continuation parameter
***************************************************

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

By default, the homotopy is created with tDegree equal to 2. This option allows
the user to give another value for tDegree; e.g., a linear homotopy between
start system q and target system f is of the form (1-t)*q + t*f.

In general, if tDegree is k, then the homotopy is of the form (1-t)^k*q +
t^k*f.

A reason for changing the tDegree would be the following: higher degree
homotopies ensure that the system doesn't change as fast in the beginning and
at the end of the homotopy; that is, they force smaller step sizes in the
beginning and end. The default value, 2, is usually sufficient.

+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : f = { x^3*y^5 + y^2 + x^2*y, x*y + x^2 - 1};                            |
+-----------------------------------------------------------------------------+
|i3 : (m,q,qsols) = mixedVolume(f,StartSystem=>true);                         |
+-----------------------------------------------------------------------------+
|i4 : fsols = trackPaths(f,q,qsols,tDegree => 1)                              |
|                                                                             |
|o4 = {{-.894935-.624334*ii, .143333+1.14868*ii}, {-1.59272, .964857},        |
|     ------------------------------------------------------------------------|
|     {.742585-.425943*ii, .270685+1.00715*ii}, {1.33076+.335184*ii,          |
|     ------------------------------------------------------------------------|
|     -.62414-.513163*ii}, {1.33076-.335184*ii, -.62414+.513163*ii},          |
|     ------------------------------------------------------------------------|
|     {-.764107, -.544612}, {.742585+.425943*ii, .270685-1.00715*ii},         |
|     ------------------------------------------------------------------------|
|     {-.894935+.624334*ii, .143333-1.14868*ii}}                              |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

Functions with optional argument named tDegree:
===============================================

  * trackPaths(...,tDegree=>...)
    -- Option to specify the
    degree of the continuation parameter

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

The object tDegree, is a symbol (Macaulay2Doc).

toLaurentPolynomial -- converts a list of rational polynomials into Laurent polynomials
***************************************************************************************

Synopsis
========

  * Usage:
        toLaurentPolynomial(system, w)
  * Inputs:
      * system, a list (Macaulay2Doc), a list of rational
        polynomials from the same ring
      * w, a symbol (Macaulay2Doc), a symbol to be used for new
        indexed variables
  * Outputs:
      * a list (Macaulay2Doc), the same system converted to a
        Laurent polynomial system

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

This function converts a rational system to a Laurent polynomial system.

+--------------------------------------------------+
|i1 : QQ[x,y,z];                                   |
+--------------------------------------------------+
|i2 : sys = {y-x^2, z-x^3, (x+y+z-1)/x};           |
+--------------------------------------------------+
|i3 : describe ring ideal sys                      |
|                                                  |
|o3 = frac(QQ[x..z, Degrees => {3:1}, Heft => {1}])|
+--------------------------------------------------+

There are denominators, so the method will convert these:

+-----------------------------------------------+
|i4 : convertedSys = toLaurentPolynomial(sys,w);|
+-----------------------------------------------+

The system convertedSys is an equivalent system living in a Laurent polynomial
ring. For each denominator, a new variable was created starting with w.

+----------------------------------------------------------------------+
|i5 : printWidth = 300;                                                |
+----------------------------------------------------------------------+
|i6 : toString convertedSys                                            |
|                                                                      |
|o6 = {y-x^2, z-x^3, -w_0^(-1)+z*w_0^(-1)+y*w_0^(-1)+x*w_0^(-1), w_0-x}|
+----------------------------------------------------------------------+
|i7 : ring ideal convertedSys                                          |
|                                                                      |
|o7 = QQ {x..z, w }                                                    |
|                0                                                     |
|                                                                      |
|o7 : PolynomialRing                                                   |
+----------------------------------------------------------------------+

Next, notice that the option "Inverses=>true" shows that this is a ring with
negative exponents allowed:

+-----------------------------------------------------------------------------+
|i8 : describe oo                                                             |
|                                                                             |
|o8 = QQ {x..z, w , Degrees => {4:1}, MonomialOrder => {Weights => {4:-1} },  |
|                0                                     {MonomialSize => 32}   |
|                                                      {GroupRevLex => 4  }   |
|                                                      {Position => Up    }   |
|-----------------------------------------------------------------------------|
|Inverses => true, Local => true, Global => false}                            |
+-----------------------------------------------------------------------------+

Note that if the system is already polynomial, or in Laurent polynomial form,
then toLaurentPolynomial doesn't change it. Of course, sometimes it is possible
that the system is polynomial "in disguise" as in line o10 in the following
example:

+---------------------------+
|i9 : P = QQ[x,y,z];        |
+---------------------------+
|i10 : f = (x*y + z^2*y) / y|
|                           |
|       2                   |
|o10 = z  + x               |
|                           |
|o10 : frac P               |
+---------------------------+
|i11 : liftable(f,P)        |
|                           |
|o11 = true                 |
+---------------------------+

But toLaurentPolynomial detects this and simplifies the system. Instead of
creating Laurent polynomials, it updates the system using the following:

+---------------+
|i12 : lift(f,P)|
|               |
|       2       |
|o12 = z  + x   |
|               |
|o12 : P        |
+---------------+

Ways to use toLaurentPolynomial:
================================

  * "toLaurentPolynomial(List,Symbol)"

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

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

topWitnessSet -- returns a witness set and nonsolutions for the top dimensional solution set
********************************************************************************************

Synopsis
========

  * Usage:
        (w,ns) = topWitnessSet(f,k)
  * Inputs:
      * f, a list (Macaulay2Doc), of polynomials expected to have a
        component of dimension k
      * k, an integer (Macaulay2Doc), the expected (top) dimension of
        the solution set of f
  * Optional inputs (Macaulay2Doc),:
      * Verbose, =>
        ..., default value false, option to specify whether additional output
        is wanted
  * Outputs:
      * w, a witness set (NAGtypes), for the k-dimensional
        solution set of f
      * ns, a list (Macaulay2Doc), solutions with nonzero value for
        the slack variable (the nonsolutions)
  * Consequences:
      * Constructs an embedding using constructEmbedding,
        which calls phc -c
      * Solves the system using solveSystem, which calls
        phc -b
      * Filters the solutions
      * Constructs the witness set of appropriate dimension.

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

The method topWitnessSet constructs an embedding for the given polynomial
system with the given dimension, and then computes generic points on the
solution set.

The computation of a witness set for the twisted cubic is illustrated below.

+---------------------------------------------------------------------------+
|i1 : R = CC[x,y,z];                                                        |
+---------------------------------------------------------------------------+
|i2 : f = { x^2 - y, x^3 - z };                                             |
+---------------------------------------------------------------------------+
|i3 : (w,ns) = topWitnessSet(f,1)                                           |
|                                                                           |
|o3 = (w, {})                                                               |
|                                                                           |
|o3 : Sequence                                                              |
+---------------------------------------------------------------------------+
|i4 : dim(w)                                                                |
|                                                                           |
|o4 = 1                                                                     |
+---------------------------------------------------------------------------+
|i5 : degree(w)                                                             |
|                                                                           |
|o5 = 3                                                                     |
+---------------------------------------------------------------------------+
|i6 : toString equations(w)                                                 |
|                                                                           |
|o6 = {x^2-y+(.380139-.924929*ii)*zz1, x^3-z+(-.45571+.890128*ii)*zz1, zz1} |
+---------------------------------------------------------------------------+
|i7 : toString slice(w)                                                     |
|                                                                           |
|o7 = {(-.205377-.978683*ii)*x+(.943327-.331864*ii)*y+(.673112+.739541*ii)*z|
|     +(-.911067-.412259*ii)*zz1-.883724+.468009*ii}                        |
+---------------------------------------------------------------------------+
|i8 : toString points(w)                                                    |
|                                                                           |
|o8 = VerticalList{new Point from {Coordinates => {-.064406+1.00899*ii,     |
|     -1.0139-.129969*ii, .196438-1.01464*ii, 5.3111e-34-2.32871e-33*ii},   |
|     cache => CacheTable{...3...}}, new Point from {Coordinates =>         |
|     {-1.16558-.143085*ii, 1.3381+.333554*ii, -1.51194-.580247*ii,         |
|     -2.36625e-32+2.72991e-32*ii}, cache => CacheTable{...3...}}, new Point|
|     from {Coordinates => {.840447+.055110*ii, .703315+.092635*ii,         |
|     .585994+.116614*ii, -1.00052e-32-9.34768e-33*ii}, cache =>            |
|     CacheTable{...3...}}}                                                 |
+---------------------------------------------------------------------------+

A witness set for the twisted cubic consists of the embedded system, a random
linear hyperplane to slice the space curve, and three generic points.  Observe
that the value for the last coordinate of all points equals (or is close to)
zero. This last coordinate corresponds to the added slack variable zzk.
Solutions with a nonzero value for the slack variable are called nonsolutions.
In the example above, the list of nonsolutions returned in ns by topWitnessSet
was empty.

Often the solution of the embedded system leads to solutions with nonzero slack
variables, as illustrated in the next example.

+---------------------------------------------------------------------------+
|i9 : R = CC[x,y,z]; f = { (x^2-y)*(x-2), (x^3 - z)*(y-2), (x*y - z)*(z-2) }|
|                                                                           |
|        3     2              3      3                             2        |
|o10 = {x  - 2x  - x*y + 2y, x y - 2x  - y*z + 2z, x*y*z - 2x*y - z  + 2z}  |
|                                                                           |
|o10 : List                                                                 |
+---------------------------------------------------------------------------+
|i11 : (w,ns) = topWitnessSet(f,1);                                         |
+---------------------------------------------------------------------------+
|i12 : dim(w)                                                               |
|                                                                           |
|o12 = 1                                                                    |
+---------------------------------------------------------------------------+
|i13 : degree(w)                                                            |
|                                                                           |
|o13 = 3                                                                    |
+---------------------------------------------------------------------------+
|i14 : #ns                                                                  |
|                                                                           |
|o14 = 10                                                                   |
+---------------------------------------------------------------------------+

The example is constructed to contain not only the twisted cubic, but also at
least one isolated point (2,2,2). This is reflected in the list of
nonsolutions.

The nonsolutions may be used as start solutions in a cascade of homotopies to
find generic points on lower dimensional components.

See also
========

  * constructEmbedding -- constructs an embedding of
    a polynomial system
  * solveSystem -- a numerical blackbox solver

Ways to use topWitnessSet:
==========================

  * "topWitnessSet(List,ZZ)"

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

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

topWitnessSet(...,Verbose=>...) -- option to specify whether additional output is wanted
****************************************************************************************

Synopsis
========

  * Usage:
        topWitnessSet(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output which includes the input and solution
file names used by phc -c.

The output file of phc contains information about the application of the
blackbox solver to the embedded system.

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

  * Default value: false (Macaulay2Doc),
  * Function: topWitnessSet, -- returns a witness set and
    nonsolutions for the top dimensional solution set
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

trackPaths -- tracks paths defined by a typical homotopy between start and end systems
**************************************************************************************

Synopsis
========

  * Usage:
        solsT = trackPaths(T,S,solsS)
  * Inputs:
      * T, a list (Macaulay2Doc), of polynomials, called the target
        system
      * S, a list (Macaulay2Doc), of polynomials, called the start
        system
      * solsS, a list (Macaulay2Doc), solutions of S
  * Optional inputs (Macaulay2Doc),:
      * gamma, => ...,
        default value 0, Option to specify the value of the constant in the
        gamma trick
      * interactive,
        => ..., default value false, Option to run phc -p in interactive mode.
      * intermediateSolutions,
        => ...,
        default value false, option to get all intermediate solutions on a path
      * loadSettingsPath,
        => ...,
        default value "", option to load the settings of the path trackers for
        a reproducible rerun
      * numThreads, =>
        ..., default value 0, Option to define the number of threads in the
        path tracker.
      * saveSettingsPath,
        => ...,
        default value "", option to save the settings of the path trackers for
        a reproducible rerun
      * seeProgress,
        => ..., default value false, Option to follow the progress of the
        multithreaded path tracker.
      * tDegree, => ...,
        default value 2, Option to specify the degree of the continuation
        parameter
      * Verbose, => ...,
        default value false, option to specify whether additional output is
        wanted
  * Outputs:
      * solsT, a list (Macaulay2Doc), containing the solutions of T
        that are at the ends of the paths starting at solsS
  * Consequences:
      * Writes the start system and its solutions to temporary files
      * Invokes the command phc -p
      * After running phc -z, stores output of phc in temporary file
      * Parses and outputs the solutions.

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

A linear homotopy between target T and start S has the form (1-Lambda)*S +
Lambda*T = 0.  The method trackPaths tracks the solution paths defined by the
homotopy for Lambda going from 0 to 1. In the example below, we first construct
a start system using polyhedral homotopies using mixedVolume.

+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y];                                                            |
+-----------------------------------------------------------------------------+
|i2 : f = { x^3*y^5 + y^2 + x^2*y, x*y + x^2 - 1};                            |
+-----------------------------------------------------------------------------+
|i3 : (m,q,qsols) = mixedVolume(f,StartSystem=>true);                         |
+-----------------------------------------------------------------------------+
|i4 : fsols = trackPaths(f,q,qsols)                                           |
|                                                                             |
|o4 = {{-.894935-.624334*ii, .143333+1.14868*ii}, {-1.59272, .964857},        |
|     ------------------------------------------------------------------------|
|     {.742585-.425943*ii, .270685+1.00715*ii}, {1.33076+.335184*ii,          |
|     ------------------------------------------------------------------------|
|     -.62414-.513163*ii}, {1.33076-.335184*ii, -.62414+.513163*ii},          |
|     ------------------------------------------------------------------------|
|     {-.764107, -.544612}, {.742585+.425943*ii, .270685-1.00715*ii},         |
|     ------------------------------------------------------------------------|
|     {-.894935+.624334*ii, .143333-1.14868*ii}}                              |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * gamma -- the constant in the gamma trick, optional input for
    trackPaths
  * interactive -- flag to run phc -p or phc -m in
    interactive mode
  * intermediateSolutions -- option of trackPaths
    to get all intermediate solutions on a path
  * loadSettingsPath -- option of trackPaths to load
    the settings for a reproducible rerun
  * saveSettingsPath -- option of trackPaths to save
    the settings for a reproducible rerun
  * numThreads -- the number of threads in the path tracker
  * seeProgress -- flag to monitor the progress of the
    multithreaded path tracker
  * tDegree -- the degree of the continuation parameter

Ways to use trackPaths:
=======================

  * "trackPaths(List,List,List)"

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

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

trackPaths(...,gamma=>...) -- Option to specify the value of the constant in the gamma trick
********************************************************************************************

Synopsis
========

  * Usage:
        trackPaths(...,gamma=>CC)

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

  * Default value: 0
  * Function: trackPaths, -- tracks paths defined by a
    typical homotopy between start and end systems
  * Option key: gamma, -- the constant in the gamma trick,
    optional input for trackPaths

Functions with optional argument named gamma:
=============================================

  * trackPaths(...,gamma=>...)
    -- Option to specify the
    value of the constant in the gamma trick

trackPaths(...,interactive=>...) -- Option to run phc -p in interactive mode.
*****************************************************************************

Synopsis
========

  * Usage:
        trackPaths(...,interactive=>Boolean)

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

  * Default value: false (Macaulay2Doc),
  * Function: trackPaths, -- tracks paths defined by a
    typical homotopy between start and end systems
  * Option key: interactive, -- flag to run phc -p or phc -m
    in interactive mode

Functions with optional argument named interactive:
===================================================

  * trackPaths(...,interactive=>...)
    -- Option to run phc -p
    in interactive mode.

trackPaths(...,intermediateSolutions=>...) -- option to get all intermediate solutions on a path
************************************************************************************************

Synopsis
========

  * Usage:
        trackPaths(...,intermediateSolutions=>Boolean)

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

  * Default value: false (Macaulay2Doc),
  * Function: trackPaths, -- tracks paths defined by a
    typical homotopy between start and end systems
  * Option key: intermediateSolutions, -- option
    of trackPaths to get all intermediate solutions on a path

Functions with optional argument named intermediateSolutions:
=============================================================

  * trackPaths(...,intermediateSolutions=>...)
    -- option to
    get all intermediate solutions on a path

trackPaths(...,loadSettingsPath=>...) -- option to load the settings of the path trackers for a reproducible rerun
******************************************************************************************************************

Synopsis
========

  * Usage:
        trackPaths(...,loadSettingsPath=>String)

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

  * Default value:
  * Function: trackPaths, -- tracks paths defined by a
    typical homotopy between start and end systems
  * Option key: loadSettingsPath, -- option of
    trackPaths to load the settings for a reproducible rerun

Functions with optional argument named loadSettingsPath:
========================================================

  * trackPaths(...,loadSettingsPath=>...)
    -- option to load
    the settings of the path trackers for a reproducible rerun

trackPaths(...,numThreads=>...) -- Option to define the number of threads in the path tracker.
**********************************************************************************************

Synopsis
========

  * Usage:
        trackPaths(...,numThreads=>ZZ)

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

  * Default value: 0
  * Function: trackPaths, -- tracks paths defined by a
    typical homotopy between start and end systems
  * Option key: numThreads, -- the number of threads in the
    path tracker

Functions with optional argument named numThreads:
==================================================

  * solveSystem(...,numThreads=>...)
    -- option to set the
    number of threads
  * trackPaths(...,numThreads=>...)
    -- Option to define the
    number of threads in the path tracker.

trackPaths(...,saveSettingsPath=>...) -- option to save the settings of the path trackers for a reproducible rerun
******************************************************************************************************************

Synopsis
========

  * Usage:
        trackPaths(...,saveSettingsPath=>String)

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

  * Default value:
  * Function: trackPaths, -- tracks paths defined by a
    typical homotopy between start and end systems
  * Option key: saveSettingsPath, -- option of
    trackPaths to save the settings for a reproducible rerun

Functions with optional argument named saveSettingsPath:
========================================================

  * trackPaths(...,saveSettingsPath=>...)
    -- option to save
    the settings of the path trackers for a reproducible rerun

trackPaths(...,seeProgress=>...) -- Option to follow the progress of the multithreaded path tracker.
****************************************************************************************************

Synopsis
========

  * Usage:
        trackPaths(...,seeProgress=>Boolean)

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

  * Default value: false (Macaulay2Doc),
  * Function: trackPaths, -- tracks paths defined by a
    typical homotopy between start and end systems
  * Option key: seeProgress, -- flag to monitor the progress
    of the multithreaded path tracker

Functions with optional argument named seeProgress:
===================================================

  * trackPaths(...,seeProgress=>...)
    -- Option to follow the
    progress of the multithreaded path tracker.

trackPaths(...,tDegree=>...) -- Option to specify the degree of the continuation parameter
******************************************************************************************

Synopsis
========

  * Usage:
        trackPaths(...,tDegree=>ZZ)

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

  * Default value: 2
  * Function: trackPaths, -- tracks paths defined by a
    typical homotopy between start and end systems
  * Option key: tDegree, -- the degree of the continuation
    parameter

Functions with optional argument named tDegree:
===============================================

  * trackPaths(...,tDegree=>...)
    -- Option to specify the
    degree of the continuation parameter

trackPaths(...,Verbose=>...) -- option to specify whether additional output is wanted
*************************************************************************************

Synopsis
========

  * Usage:
        trackPaths(...,Verbose=>Boolean)

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

Use Verbose=>true for additional output which includes the input and solution
file names used by phc.

The output file of phc contains timings for the path tracker and additional
diagnostics for each path.

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

  * Default value: false (Macaulay2Doc),
  * Function: trackPaths, -- tracks paths defined by a
    typical homotopy between start and end systems
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

versionNumber -- returns the version number and release date of phc
*******************************************************************

Synopsis
========

  * Usage:
        versionNumber(null)
        versionNumber(,Verbose=>true)
  * Inputs:
      * null,
  * Optional inputs (Macaulay2Doc),:
      * Verbose, =>
        ..., default value false, option to print the output of phc --version
        to screen
  * Outputs:
      * a sequence (Macaulay2Doc), The sequence on return
        contains two strings. The first string on return is the version number.
        The second string on return is the release date.

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

The version number and release date of the executable phc are important for
consistency between the methods in this package and preparing the input batch
files for the executable phc.

A successful run of this method verifies whether the location of the executable
phc is in the execution path.

+----------------------------+
|i1 : v = versionNumber(null)|
|                            |
|o1 = (2.4.90, 2024-03-20)   |
|                            |
|o1 : Sequence               |
+----------------------------+
|i2 : print v_0              |
|2.4.90                      |
+----------------------------+
|i3 : print v_1              |
|2024-03-20                  |
+----------------------------+

Ways to use versionNumber:
==========================

  * "versionNumber(Nothing)"

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

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

versionNumber(...,Verbose=>...) -- option to print the output of phc --version to screen
****************************************************************************************

Synopsis
========

  * Usage:
        cascade(...,Verbose=>Boolean)

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

Use Verbose=>true to see the output of phc --version.

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

  * Default value: false (Macaulay2Doc),
  * Function: versionNumber, -- returns the version number
    and release date of phc
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * cascade(...,Verbose=>...)
    -- option to specify whether
    additional output is wanted
  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * constructEmbedding(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * factorWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * isWitnessSetMember(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * numericalIrreducibleDecomposition(...,Verbose=>...),
    --
    option to specify whether additional output is wanted
  * refineSolutions(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * solveRationalSystem(...,Verbose=>...)
    -- option to
    specify whether additional output is wanted
  * solveSystem(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree
  * topWitnessSet(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * trackPaths(...,Verbose=>...)
    -- option to specify
    whether additional output is wanted
  * versionNumber(...,Verbose=>...)
    -- option to print the
    output of phc --version to screen

zeroFilter -- returns solutions with k-th coordinate less than the given tolerance
**********************************************************************************

Synopsis
========

  * Usage:
        zeroSols = zeroFilter(sols,k,tol)
  * Inputs:
      * sols, a list (Macaulay2Doc), containing the solutions of a
        polynomial system
      * k, an integer (Macaulay2Doc), index of a coordinate of a
        solution
      * tol, a real number (Macaulay2Doc), tolerance on the absolute
        value of the k-th coordinate
  * Outputs:
      * zeroSols, a list (Macaulay2Doc), solutions with k-th
        coordinate less than the given tolerance

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

A solution has its k-th coordinate zero when the abs function evaluates to a
number less than or equal to the given tolerance.

+-------------------------------------------------+
|i1 : R = CC[x,y];                                |
+-------------------------------------------------+
|i2 : f = { x^3*y^5 + y^2 + x^2*y, x*y + x^2 - 1};|
+-------------------------------------------------+
|i3 : fSols = solveSystem(f, randomSeed=>3);      |
+-------------------------------------------------+
|i4 : fSols/print                                 |
|{-1, 0}                                          |
|{1, 0}                                           |
|{-1.59272, .964857}                              |
|{.742585+.425943*ii, .270685-1.00715*ii}         |
|{-.764107, -.544612}                             |
|{1.33076-.335184*ii, -.62414+.513163*ii}         |
|{-.894935-.624334*ii, .143333+1.14868*ii}        |
|{1.33076+.335184*ii, -.62414-.513163*ii}         |
|{-.894935+.624334*ii, .143333-1.14868*ii}        |
|{.742585-.425943*ii, .270685+1.00715*ii}         |
|                                                 |
|o4 = {, , , , , , , , , }                        |
|                                                 |
|o4 : List                                        |
+-------------------------------------------------+

There is one solution with zero second coordinate:

+--------------------------------------------+
|i5 : zeroSols = zeroFilter(fSols,1,1.0e-10);|
+--------------------------------------------+
|i6 : zeroSols / print                       |
|{-1, 0}                                     |
|{1, 0}                                      |
|                                            |
|o6 = {, }                                   |
|                                            |
|o6 : List                                   |
+--------------------------------------------+

Here is another system where we filter solutions with `small' first coordinate:

+---------------------------------------------------------+
|i7 : f = {x^2+y^2,y*x+x};                                |
+---------------------------------------------------------+
|i8 : fSols = solveSystem(f);                             |
+---------------------------------------------------------+
|i9 : fSols/print                                         |
|(-2.46519e-32+1.07852e-32*ii, -2.40467e-32+9.0524e-34*ii)|
|{-ii, -1}                                                |
|{ii, -1}                                                 |
|                                                         |
|o9 = {, , }                                              |
|                                                         |
|o9 : List                                                |
+---------------------------------------------------------+
|i10 : zeroSols = zeroFilter(fSols,0,1.0e-10);            |
+---------------------------------------------------------+
|i11 : zeroSols/print                                     |
|(-2.46519e-32+1.07852e-32*ii, -2.40467e-32+9.0524e-34*ii)|
|                                                         |
|o11 = {}                                                 |
|                                                         |
|o11 : List                                               |
+---------------------------------------------------------+

Good values for the tolerance are relative to the accuracy and the condition
number of the solution. To improve the accuracy of a solution, apply
refineSolutions, with a higher working precision.

See also
========

  * refineSolutions -- refines solutions of a system by
    increasing working precision
  * nonZeroFilter -- returns solutions with coordinate
    larger than given tolerance

Ways to use zeroFilter:
=======================

  * "zeroFilter(List,ZZ,RR)"

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

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