This is MonodromySolver.info, produced by Macaulay2, version 1.25.05

MonodromySolver -- solve polynomial systems via homotopy continuation and monodromy
***********************************************************************************

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

This packages provides randomized methods for numerically solving polynomial
systems of equations that occur in parametric families, by exploiting the
transitive action of an associated monodromy group. The package implements the
graph-based framework described in the third reference below. There are three
main functions that may be used to solve a system of a family of systems:

  * solveFamily -- a solver for parametric families with
    simple output
  * sparseMonodromySolve -- an "out of the box"
    polynomial system solver
  * monodromySolve -- the main function of the
    MonodromySolver package

See monodromySolve, is the core function, whose input may be
a polynomial system (NAGtypes), or $ofClass GateSystem$. As an
additional input, a seed pair consisting of initial parameter and solution
values may be provided. See solveFamily, is a wrapper function
that returns specific solutions and parameter values. See
sparseMonodromySolve, is a blackbox solver for systems
without parameters, that calls the core function. These functions have many
options in common, which are summarized in MonodromySolverOptions.
Here is an example illustrating how to solve a
parametric family for specific parameter values.

+-----------------------------------------------------------------------------+
|i1 : setRandomSeed 0;                                                        |
| -- setting random seed to 0                                                 |
+-----------------------------------------------------------------------------+
|i2 : declareVariable \ {A,B,C,D,X,Y};                                        |
+-----------------------------------------------------------------------------+
|i3 : F = gateSystem(matrix{{A,B,C,D}},matrix{{X,Y}},matrix{{A*(X-1)^2-B},    |
|-----------------------------------------------------------------------------|
|{C*(Y+2)^2+D}});                                                             |
+-----------------------------------------------------------------------------+
|i4 : p0 = point{{1,1,1,1}};                                                  |
+-----------------------------------------------------------------------------+
|i5 : sols = solveFamily(p0, F, NumberOfNodes=>3);                            |
+-----------------------------------------------------------------------------+
|i6 : for i from 0 to 3 list norm(evaluate(F, p0, sols#i))                    |
|                                                                             |
|o6 = {4.39145e-23, 4.39145e-23, 4.39145e-23, 4.39145e-23}                    |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

Each solver works by assembling randomly generated systems within a
HomotopyGraph, and tracking paths between them. They are also
equipped with a number of options, which may be useful for speeding up
computation or increasing the probability of success.

In the example above, the system is linear in parameters, allowing for the seed
pair to be computed automatically. The current seeding implementation will
report failure in other cases. Depending on the problem of interest, there may
still be a natural way to generate the seed pair, as in
monodromySolve(System,AbstractPoint,List).

Some references for numerical monodromy methods:

Sommese, Andrew J., Jan Verschelde, and Charles W. Wampler. "Numerical
decomposition of the solution sets of polynomial systems into irreducible
components." SIAM Journal on Numerical Analysis 38.6 (2001): 2022-2046.

del Campo, Abraham Martin, and Jose Israel Rodriguez. "Critical points via
monodromy and local methods." Journal of Symbolic Computation 79 (2017):
559-574.

Duff, Timothy, Cvetelina Hill, Anders Jensen, Kisun Lee, Anton Leykin, and Jeff
Sommars. "Solving polynomial systems via homotopy continuation and monodromy."
IMA Journal of Numerical Analysis 39.3 (2019): 1421-1446.

Authors
=======

  * Timothy Duff <timduff@uw.edu>
  * Cvetelina Hill <cvetelina.hill@math.gatech.edu>
  * Anders Nedergaard Jensen <jensen@math.au.dk>
  * Kisun Lee <klee669@math.gatech.edu>
  * Anton Leykin <leykin@math.gatech.edu>
  * Jeff Sommars <sommars1@uic.edu>

Version
=======

This documentation describes version 1.16 of MonodromySolver.

Citation
========

If you have used this package in your research, please cite it as follows:

+-----------------------------------------------------------------------------+
|@misc{MonodromySolverSource,                                                 |
|  title = {{MonodromySolver: solving polynomial systems                      |
|  author = {Timothy Duff and Cvetelina Hill and Anders                       |
|  howpublished = {A \emph{Macaulay2} package available                       |
|    "http://www.math.gatech.edu/~leykin"}                                    |
|}                                                                            |
|-----------------------------------------------------------------------------|
| via monodromy. Version~1.16}},                                              |
|Nedergaard Jensen and Kisun Lee and Anton Leykin and Jeff Sommars},          |
|at                                                                           |
+-----------------------------------------------------------------------------+

Exports
=======

  * Types
      * HomotopyGraph
      * HomotopyNode
      * PointArray -- a container for solutions
  * Functions and commands
      * appendPoint -- append a point at the end of a
        PointArray
      * appendPoints -- append a list of points at the end
        of a PointArray
      * completeGraphAugment -- augment graph with
        the complete graph structure
      * completeGraphInit -- initialize the topology
        of a complete graph
      * computeMixedVolume -- compute mixed volume
        via Gfan
      * createSeedPair -- create initial seed for the
        homotopy continuation
      * dynamicFlowerSolve -- a naive dynamic
        strategy
      * flowerGraphAugment -- augment graph with the
        flower graph structure
      * flowerGraphInit -- solve via monodromy by using
        flower shaped graph
      * getTrackTime -- elapsed time taken by solver
      * homotopyGraph -- HomotopyGraph Constructor
      * makeBatchPotential -- batch sensitive
        potentialE
      * monodromyGroup -- compute the group of
        permutations implicitly defined by a homotopy graph
      * monodromySolve -- the main function of the
        MonodromySolver package
      * pointArray -- constructor for PointArray
      * potentialE -- the "expected" potential of an edge
      * potentialLowerBound -- the potential which
        is equal to the minimal number of new points guaranteed to be
        discovered
      * selectBestEdgeAndDirection, --
        selects edge and direction based on highest potential for obtaining new
        information
      * selectRandomEdgeAndDirection, --
        random selection of edge and direction for homotopy
      * solveFamily -- a solver for parametric families
        with simple output
      * sparseMonodromySolve -- an "out of the
        box" polynomial system solver
      * specializeSystem -- specialize parametric
        system at a point in the parameter space.
  * Methods
      * "appendPoint(PointArray,AbstractPoint)" -- see appendPoint,
        -- append a point at the end of a PointArray
      * "appendPoints(PointArray,List)" -- see appendPoints,
        -- append a list of points at the end of a PointArray
      * betti(HomotopyGraph) (missing documentation)
      * "computeMixedVolume(List)" -- see computeMixedVolume,
        -- compute mixed volume via Gfan
      * computeMixedVolume(System) (missing documentation)
      * "createSeedPair(System)" -- see createSeedPair,
        -- create initial seed for the homotopy continuation
      * "createSeedPair(System,AbstractPoint)" -- see createSeedPair,
        -- create initial seed for the homotopy continuation
      * "getTrackTime(HomotopyGraph)" -- see getTrackTime,
        -- elapsed time taken by solver
      * homotopyGraph(System) (missing documentation)
      * indices(PointArray) -- returns indices
        of a PointArray
      * isAffineLinearFunction(GateSystem) (missing documentation)
      * isMember(AbstractPoint,PointArray)
        -- test point membership in a
        PointArray
      * isMember(AbstractPoint,PointArray,FunctionClosure) (missing
        documentation)
      * length(PointArray) -- number of items
        stored in a PointArray
      * "monodromyGroup(System)" -- see monodromyGroup,
        -- compute the group of permutations implicitly defined by a homotopy
        graph
      * "monodromyGroup(System,AbstractPoint,List)" -- see
        monodromyGroup, -- compute the group of permutations
        implicitly defined by a homotopy graph
      * monodromyGroup(HomotopyGraph) (missing documentation)
      * monodromySolve(System) -- the main
        function of the MonodromySolver package
      * monodromySolve(System,AbstractPoint,List)
        -- the main function
        of the MonodromySolver package
      * net(PointArray) -- pretty printing
      * "solveFamily(AbstractPoint,System)" -- see solveFamily,
        -- a solver for parametric families with simple output
      * "solveFamily(System)" -- see solveFamily, -- a
        solver for parametric families with simple output
      * "sparseMonodromySolve(PolySystem)" -- see sparseMonodromySolve,
        -- an "out of the box" polynomial system solver
      * "specializeSystem(AbstractPoint,Matrix)" -- see specializeSystem,
        -- specialize parametric system at a point in the
        parameter space.
      * "specializeSystem(AbstractPoint,PolySystem)" -- see
        specializeSystem, -- specialize parametric system at
        a point in the parameter space.
      * specializeSystem(AbstractPoint,GateSystem) (missing documentation)
  * Symbols
      * "PartialSols" -- see HomotopyNode,
      * "SpecializedSystem" -- see HomotopyNode,
      * "AugmentEdgeCount" -- see MonodromySolverOptions,
      * "AugmentGraphFunction" -- see MonodromySolverOptions,
      * "AugmentNodeCount" -- see MonodromySolverOptions,
      * "AugmentNumberOfRepeats" -- see MonodromySolverOptions,
      * "BatchSize" -- see MonodromySolverOptions,
      * "EdgesSaturated" -- see MonodromySolverOptions,
      * "Equivalencer" -- see MonodromySolverOptions,
      * "FilterCondition" -- see MonodromySolverOptions,
      * "GraphInitFunction" -- see MonodromySolverOptions,
      * MonodromySolverOptions
      * "NumberOfEdges" -- see MonodromySolverOptions,
      * "NumberOfNodes" -- see MonodromySolverOptions,
      * "NumberOfRepeats" -- see MonodromySolverOptions,
      * "PointArrayTol" -- see MonodromySolverOptions,
      * "Potential" -- see MonodromySolverOptions,
      * "Randomizer" -- see MonodromySolverOptions,
      * "SelectEdgeAndDirection" -- see MonodromySolverOptions,
      * "StoppingCriterion" -- see MonodromySolverOptions,
      * "TargetSolutionCount" -- see MonodromySolverOptions,

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

The object MonodromySolver, is a package (Macaulay2Doc),
defined in MonodromySolver.m2, with auxiliary files in
MonodromySolver/.

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:60:0.

appendPoint -- append a point at the end of a PointArray
********************************************************

  * Usage:
        appendPoint(A,p)
  * Inputs:
      * A, an instance of the type PointArray,
      * p, a point (NAGtypes),

Ways to use appendPoint:
========================

  * "appendPoint(PointArray,AbstractPoint)"

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:616:0.

appendPoints -- append a list of points at the end of a PointArray
******************************************************************

  * Usage:
        appendPoints(A,L)
  * Inputs:
      * A, an instance of the type PointArray,
      * L, a list (Macaulay2Doc),

Ways to use appendPoints:
=========================

  * "appendPoints(PointArray,List)"

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:629:0.

completeGraphAugment -- augment graph with the complete graph structure
***********************************************************************

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

This is a possible value of the option AugmentGraphFunction of the function
monodromySolve. It will augment the graph while respecting the complete graph
structure, so it should be used in conjunction with flowerGraphInit. To use it,
it is necessary to specify a number of nodes or edges to augment by using
AugmentNodeCount or AugmentEdgeCount.

+-----------------------------------------------------------------------------+
|i1 : R = CC[a,b,c,d][x,y];                                                   |
+-----------------------------------------------------------------------------+
|i2 : polys = polySystem {a*x+b*y^2,c*x*y+d};                                 |
+-----------------------------------------------------------------------------+
|i3 : monodromySolve(polys,GraphInitFunction => flowerGraphInit,              |
|                                                                             |
|o3 = (HomotopyNode{...7...}, 24)                                             |
|                                                                             |
|o3 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|AugmentGraphFunction=>completeGraphAugment,AugmentNodeCount=>1,              |
|-----------------------------------------------------------------------------|
|AugmentNumberOfRepeats=>3)                                                   |
+-----------------------------------------------------------------------------+

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

The object completeGraphAugment, is a
function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:529:0.

completeGraphInit -- initialize the topology of a complete graph
****************************************************************

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

This is an option for the function monodromySolve which uses a complete graph.
For instance, the user can choose to have 4 vertices and 2 edges connecting
each pair of vertices. Then the homotopy will run on the complete graph on 4
vertices, where each edge is doubled.

+-----------------------------------------------------------------+
|i1 : R = CC[a,b,c,d][x,y];                                       |
+-----------------------------------------------------------------+
|i2 : polys = polySystem {a*x+b*y^2,c*x*y+d};                     |
+-----------------------------------------------------------------+
|i3 : monodromySolve(polys,GraphInitFunction => completeGraphInit)|
|                                                                 |
|o3 = (HomotopyNode{...7...}, 4)                                  |
|                                                                 |
|o3 : Sequence                                                    |
+-----------------------------------------------------------------+

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

The object completeGraphInit, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:646:0.

computeMixedVolume -- compute mixed volume via Gfan
***************************************************

  * Usage:
        d = computeMixedVolume polys
  * Inputs:
      * polys, a list (Macaulay2Doc), containing polynomials
  * Outputs:
      * d, an integer (Macaulay2Doc),

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

Computes mixed volume of a polynomial system using the package {TO
gfanInterface}. For generic systems of a given support set, this is the generic
root count.

+----------------------------+
|i1 : setRandomSeed 0;       |
| -- setting random seed to 0|
+----------------------------+

Ways to use computeMixedVolume:
===============================

  * "computeMixedVolume(List)"
  * computeMixedVolume(System) (missing documentation)

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:491:0.

createSeedPair -- create initial seed for the homotopy continuation
*******************************************************************

  * Usage:
        (p0,x0) = createSeedPair PS
        (p0, x0) = createSeedPair(PS,x0)
  * Inputs:
      * PS, an instance of the type System (NAGtypes), a
        parametric polynomial system
      * x0, a point (NAGtypes), an initial solution for
        some system
  * Optional inputs (Macaulay2Doc),:
      * affinity tolerance
      * initial parameters
      * Verbose (missing documentation) => ..., default value false,
  * Outputs:
      * p0, an instance of the type Point (NAGtypes),
        representing a random system
      * x0, an instance of the type Point (NAGtypes),
        representing a solution to the system defined by p0

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

The "seed pair" appearing in the output of this function is used to initialize
the HomotopyGraph, in blackbox solvers. To diagnose
failures for the parametric solvers, it may be helpful to check that seeding
worked as in the example provided below.

+-----------------------------------------------------------------------------+
|i1 : setRandomSeed 0                                                         |
| -- setting random seed to 0                                                 |
|                                                                             |
|o1 = 0                                                                       |
+-----------------------------------------------------------------------------+
|i2 : R = CC[a,b,c,d][x,y];                                                   |
+-----------------------------------------------------------------------------+
|i3 : polys = polySystem {a*x+b*y^2,c*x*y+d};                                 |
+-----------------------------------------------------------------------------+
|i4 : (p0,x0) := createSeedPair polys;                                        |
+-----------------------------------------------------------------------------+
|i5 : polys0=specializeSystem(p0,polys);                                      |
+-----------------------------------------------------------------------------+
|i6 : apply(polys0,p->sub(p,{x=>first x0.Coordinates,y=>last x0.Coordinates}))|
|                                                                             |
|o6 = {0, 2.77556e-17+8.32667e-17*ii}                                         |
|                                                                             |
|o6 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * monodromySolve(System,AbstractPoint,List)
    -- the main function of
    the MonodromySolver package

Ways to use createSeedPair:
===========================

  * "createSeedPair(System)"
  * "createSeedPair(System,AbstractPoint)"

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:240:0.

dynamicFlowerSolve -- a naive dynamic strategy
**********************************************

  * Usage:
        (L, npaths) = dynamicFlowerSolve(M,p0,L)
  * Inputs:
      * M, a matrix (Macaulay2Doc), defining polynomial system
      * p0, a point (NAGtypes), associated to a
        specialized system
      * L, a list (Macaulay2Doc), containing partial solutions
        associated to p0
  * Optional inputs (Macaulay2Doc),:
      * RandomPointFunction (missing documentation) => ..., default value null,
      * StoppingCriterion, => ..., default value
        FunctionClosure[../../../../Macaulay2/packages/MonodromySolver/
        solveViaMonodromy.m2:110:110-110:120],
      * TargetSolutionCount (missing documentation) => ..., default value null,
  * Outputs:
      * L, a list (Macaulay2Doc),
      * npaths, an integer (Macaulay2Doc),

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

Output is verbose. For other dynamic strategies, see
MonodromySolverOptions.

+------------------------------------------------------------+
|i1 : R = CC[a,b,c,d][x,y];                                  |
+------------------------------------------------------------+
|i2 : polys = polySystem {a*x+b*y^2,c*x*y+d};                |
+------------------------------------------------------------+
|i3 : (p0, x0) = createSeedPair polys;                       |
+------------------------------------------------------------+
|i4 : (L, npaths) = dynamicFlowerSolve(polys.PolyMap,p0,{x0})|
| -- .00988461s elapsed                                      |
| -- .00573391s elapsed                                      |
| -- .000398016s elapsed                                     |
| -- .00346283s elapsed                                      |
| -- .00378124s elapsed                                      |
| -- .000338465s elapsed                                     |
| -- .00383996s elapsed                                      |
| -- .00382239s elapsed                                      |
| -- .00031945s elapsed                                      |
| -- .00382329s elapsed                                      |
| -- .0038282s elapsed                                       |
| -- .000348814s elapsed                                     |
|--backup directory created: /tmp/M2-103653-0/1              |
|  H01: 1                                                    |
|  H10: 1                                                    |
|number of paths tracked: 2                                  |
|found 1 points in the fiber so far                          |
|  H01: 1                                                    |
|  H10: 1                                                    |
|number of paths tracked: 4                                  |
|found 1 points in the fiber so far                          |
|  H01: 1                                                    |
|  H10: 1                                                    |
|number of paths tracked: 6                                  |
|found 1 points in the fiber so far                          |
|  H01: 1                                                    |
|  H10: 1                                                    |
|number of paths tracked: 8                                  |
|found 1 points in the fiber so far                          |
|                                                            |
|o4 = ({{.892712+.673395*ii, .29398+.632944*ii}}, 8)         |
|                                                            |
|o4 : Sequence                                               |
+------------------------------------------------------------+

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:603:0.

flowerGraphAugment -- augment graph with the flower graph structure
*******************************************************************

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

This is a possible value of the option AugmentGraphFunction,
of the function monodromySolve. It will augment the
graph while respecting the flower graph structure, so it should be used in
conjunction with flowerGraphInit. To use it, it is
necessary to specify a number of nodes or edges to augment by using
AugmentNodeCount or AugmentEdgeCount.

+-----------------------------------------------------------------------------+
|i1 : R = CC[a,b,c,d][x,y];                                                   |
+-----------------------------------------------------------------------------+
|i2 : polys = polySystem {a*x+b*y^2,c*x*y+d};                                 |
+-----------------------------------------------------------------------------+
|i3 : monodromySolve(polys,GraphInitFunction => flowerGraphInit,              |
|                                                                             |
|o3 = (HomotopyNode{...7...}, 24)                                             |
|                                                                             |
|o3 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|AugmentGraphFunction=>flowerGraphAugment,AugmentNodeCount=>1,                |
|-----------------------------------------------------------------------------|
|AugmentNumberOfRepeats=>3)                                                   |
+-----------------------------------------------------------------------------+

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

The object flowerGraphAugment, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:510:0.

flowerGraphInit -- solve via monodromy by using flower shaped graph
*******************************************************************

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

This is an option for the function monodromySolve which uses a flower graph.
That is, the seed system is the central vertex of the graph; it is connected to
all other vertices by two paths, thus creating a "petal" for each additional
vertex.

+---------------------------------------------------------------+
|i1 : R = CC[a,b,c,d][x,y];                                     |
+---------------------------------------------------------------+
|i2 : polys = polySystem {a*x+b*y^2,c*x*y+d};                   |
+---------------------------------------------------------------+
|i3 : monodromySolve(polys,GraphInitFunction => flowerGraphInit)|
|                                                               |
|o3 = (HomotopyNode{...7...}, 24)                               |
|                                                               |
|o3 : Sequence                                                  |
+---------------------------------------------------------------+

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

The object flowerGraphInit, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:465:0.

getTrackTime -- elapsed time taken by solver
********************************************

  * Usage:
        t = getTrackTime G
  * Inputs:
      * G, an instance of the type HomotopyGraph,
  * Outputs:
      * t, a real number (Macaulay2Doc),

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

This only works on graphs which have been modified by a solver.

See also
========

  * elapsedTime (Macaulay2Doc) -- time a computation
    including time elapsed

Ways to use getTrackTime:
=========================

  * "getTrackTime(HomotopyGraph)"

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:575:0.

HomotopyGraph
*************

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

The graph of systems connected by homotopies. Inherits from
MutableHashTable (Macaulay2Doc).

Keys associated with HomotopyGraph
----------------------------------

  * Edges: a mutable list of edges
  * Family: the parametric system (or null)
  * Potential: the potential function used (or null)
  * Vertices: a mutable list of nodes

See also
========

  * HomotopyNode

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

  * homotopyGraph -- HomotopyGraph Constructor

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

  * betti(HomotopyGraph) (missing documentation)
  * "getTrackTime(HomotopyGraph)" -- see getTrackTime, --
    elapsed time taken by solver
  * monodromyGroup(HomotopyGraph) (missing documentation)

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:425:0.

homotopyGraph -- HomotopyGraph Constructor
******************************************

  * Usage:
        G = homotopyGraph PS
  * Inputs:
      * PS, an instance of the type System (NAGtypes),
  * Optional inputs (Macaulay2Doc),:
      * Equivalencer (missing documentation) => ..., default value null,
      * FilterCondition (missing documentation) => ..., default value null,
      * LinearSegment (missing documentation) => ..., default value true,
      * Potential (missing documentation) => ..., default value null,
      * Randomizer (missing documentation) => ..., default value null,
      * Verbose (missing documentation) => ..., default value null,
  * Outputs:
      * G, an instance of the type HomotopyGraph,

Ways to use homotopyGraph:
==========================

  * homotopyGraph(System) (missing documentation)

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:556:0.

HomotopyNode
************

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

Object associated to a polynomial system.

Keys associated with HomotopyNode
---------------------------------

  * BasePoint: the parameter point defining some system
  * Edges: a mutable list of edges
  * Graph: a HomotopyGraph containing the node
  * PartialSols: PointArray, of solutions for
    SpecializedSystem
  * SpecializedSystem: list of equations for system specialized at the
    BasePoint

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:406:0.

indices(PointArray) -- returns indices of a PointArray
******************************************************

  * Function: indices (Macaulay2Doc),
  * Usage:
        indices A
  * Inputs:
      * A, an instance of the type PointArray,

See also
========

  * indices (Macaulay2Doc) -- indices of a polynomial; also
    components for a direct sum

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

  * indices(PointArray) -- returns indices of a
    PointArray
-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:717:0.

isMember(AbstractPoint,PointArray) -- test point membership in a PointArray
***************************************************************************

  * Function: isMember (Macaulay2Doc),
  * Usage:
        member(p,A)
  * Inputs:
      * p, a point (NAGtypes),
      * A, an instance of the type PointArray,

See also
========

  * isMember (Macaulay2Doc) -- test membership in a list or set

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

  * isMember(AbstractPoint,PointArray)
    -- test point membership in a
    PointArray
-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:758:0.

length(PointArray) -- number of items stored in a PointArray
************************************************************

  * Function: length (Macaulay2Doc),
  * Usage:
        length A
  * Inputs:
      * A, an instance of the type PointArray,
  * Outputs:
      * an integer (Macaulay2Doc),

See also
========

  * length (Macaulay2Doc) -- length of an object

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

  * length(PointArray) -- number of items stored
    in a PointArray
-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:731:0.

makeBatchPotential -- batch sensitive potentialE
************************************************

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

This is a more general potentialE, which accounts for the
fact that the expected number of points discovered along an edge depends on the
BatchSize.

See also
========

  * potentialE -- the "expected" potential of an edge
  * MonodromySolverOptions

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:543:0.

monodromyGroup -- compute the group of permutations implicitly defined by a homotopy graph
******************************************************************************************

  * Usage:
        monodromyGroup S
        monodromyGroup(S, p0, x0s)
  * Inputs:
      * S, an instance of the type System (NAGtypes),
      * p0, a point (NAGtypes), a basepoint for the
        monodromy group in the parameter space for S
      * x0s, a list (Macaulay2Doc), points in the fiber over S
  * Optional inputs (Macaulay2Doc),:
      * FileName (missing documentation) => a string (Macaulay2Doc),
        default value null, a name for an output file
        suitable for reading by GAP. Default value is null.
      * msOptions
      * RootCount

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

If the monodromy group is full symmetric and the degree is large, then the
default settings have a good chance of generating the whole group. However, you
will need to use a bigger graph than the default settings to fully generate
imprimitive groups, as in the following example of a Euclidean distance degree
calculation.

+-----------------------------------------------------------------------------+
|i1 : setRandomSeed 100;                                                      |
| -- setting random seed to 100                                               |
+-----------------------------------------------------------------------------+
|i2 : declareVariable \ {t_1,t_2,u_0,u_1,u_2,u_3};                            |
+-----------------------------------------------------------------------------+
|i3 : paramMatrix = gateMatrix{{u_0,u_1,u_2,u_3}};                            |
+-----------------------------------------------------------------------------+
|i4 : varMatrix = gateMatrix{{t_1,t_2}};                                      |
+-----------------------------------------------------------------------------+
|i5 : phi = transpose gateMatrix{{t_1^3, t_1^2*t_2, t_1*t_2^2, t_2^3}};       |
+-----------------------------------------------------------------------------+
|i6 : loss = sum for i from 0 to 3 list (u_i - phi_(i,0))^2;                  |
+-----------------------------------------------------------------------------+
|i7 : dLoss = diff(varMatrix, gateMatrix{{loss}});                            |
+-----------------------------------------------------------------------------+
|i8 : G = gateSystem(paramMatrix,varMatrix,transpose dLoss);                  |
+-----------------------------------------------------------------------------+
|i9 : monodromyGroup(G,"msOptions" => {NumberOfEdges=>10})                    |
|                                                                             |
|o9 = {{13, 10, 8, 15, 4, 7, 6, 11, 12, 9, 14, 5, 2, 16, 1, 17, 0, 3, 19, 20, |
|     ------------------------------------------------------------------------|
|     18}, {10, 9, 15, 20, 0, 8, 13, 12, 17, 16, 4, 2, 3, 14, 6, 18, 1, 19, 5,|
|     ------------------------------------------------------------------------|
|     7, 11}, {13, 10, 8, 15, 6, 7, 9, 11, 12, 4, 14, 5, 2, 16, 1, 17, 0, 3,  |
|     ------------------------------------------------------------------------|
|     19, 20, 18}, {0, 1, 2, 20, 4, 7, 6, 11, 8, 9, 10, 5, 12, 13, 14, 18, 16,|
|     ------------------------------------------------------------------------|
|     19, 15, 17, 3}, {1, 6, 3, 19, 16, 2, 0, 8, 15, 13, 9, 12, 17, 10, 4, 20,|
|     ------------------------------------------------------------------------|
|     14, 18, 11, 5, 7}, {13, 10, 5, 15, 4, 12, 6, 2, 7, 9, 14, 8, 11, 16, 1, |
|     ------------------------------------------------------------------------|
|     17, 0, 3, 19, 20, 18}, {11, 10, 8, 13, 6, 20, 9, 18, 12, 4, 14, 19, 2,  |
|     ------------------------------------------------------------------------|
|     5, 1, 16, 7, 0, 3, 15, 17}, {13, 10, 8, 15, 6, 7, 9, 11, 12, 4, 14, 5,  |
|     ------------------------------------------------------------------------|
|     2, 16, 1, 17, 0, 3, 19, 20, 18}, {15, 9, 0, 7, 10, 8, 14, 12, 13, 1, 4, |
|     ------------------------------------------------------------------------|
|     2, 16, 17, 6, 11, 3, 5, 19, 20, 18}, {10, 9, 15, 20, 0, 8, 13, 12, 17,  |
|     ------------------------------------------------------------------------|
|     16, 4, 2, 3, 14, 6, 18, 1, 19, 5, 7, 11}, {10, 9, 7, 0, 12, 17, 2, 3,   |
|     ------------------------------------------------------------------------|
|     11, 8, 4, 15, 5, 14, 6, 13, 1, 16, 19, 20, 18}, {16, 6, 3, 19, 10, 2,   |
|     ------------------------------------------------------------------------|
|     14, 8, 15, 1, 9, 12, 17, 0, 4, 20, 13, 18, 11, 5, 7}, {3, 1, 6, 19, 0,  |
|     ------------------------------------------------------------------------|
|     2, 13, 8, 9, 16, 10, 12, 4, 15, 14, 20, 17, 18, 11, 5, 7}, {15, 1, 0, 7,|
|     ------------------------------------------------------------------------|
|     4, 8, 6, 12, 13, 9, 10, 2, 16, 17, 14, 11, 3, 5, 19, 20, 18}, {10, 0, 5,|
|     ------------------------------------------------------------------------|
|     2, 6, 19, 9, 20, 7, 4, 13, 18, 11, 14, 16, 8, 1, 12, 17, 3, 15}, {13,   |
|     ------------------------------------------------------------------------|
|     10, 8, 15, 6, 7, 9, 11, 12, 4, 14, 5, 2, 16, 1, 17, 0, 3, 19, 20, 18},  |
|     ------------------------------------------------------------------------|
|     {1, 6, 3, 19, 16, 2, 0, 8, 15, 13, 9, 12, 17, 10, 4, 20, 14, 18, 11, 5, |
|     ------------------------------------------------------------------------|
|     7}, {3, 1, 6, 5, 16, 2, 0, 8, 9, 13, 10, 12, 4, 15, 14, 7, 17, 11, 18,  |
|     ------------------------------------------------------------------------|
|     19, 20}, {11, 10, 12, 13, 6, 20, 9, 18, 2, 4, 14, 19, 8, 5, 1, 16, 7, 0,|
|     ------------------------------------------------------------------------|
|     3, 15, 17}, {16, 6, 3, 19, 10, 2, 14, 8, 15, 1, 9, 12, 17, 0, 4, 20, 13,|
|     ------------------------------------------------------------------------|
|     18, 11, 5, 7}, {1, 6, 3, 19, 16, 2, 0, 8, 15, 13, 9, 12, 17, 10, 4, 20, |
|     ------------------------------------------------------------------------|
|     14, 18, 11, 5, 7}, {13, 10, 5, 15, 4, 12, 6, 2, 7, 9, 14, 8, 11, 16, 1, |
|     ------------------------------------------------------------------------|
|     17, 0, 3, 19, 20, 18}, {6, 10, 12, 13, 11, 20, 5, 18, 2, 7, 14, 19, 8,  |
|     ------------------------------------------------------------------------|
|     9, 1, 16, 4, 0, 3, 15, 17}, {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12,  |
|     ------------------------------------------------------------------------|
|     13, 14, 15, 16, 17, 18, 19, 20}, {3, 6, 1, 19, 16, 2, 0, 8, 10, 13, 9,  |
|     ------------------------------------------------------------------------|
|     12, 14, 15, 4, 20, 17, 18, 11, 5, 7}, {0, 1, 6, 20, 7, 15, 11, 17, 9, 5,|
|     ------------------------------------------------------------------------|
|     10, 3, 4, 13, 14, 18, 16, 19, 2, 8, 12}, {13, 10, 19, 2, 6, 5, 9, 7, 20,|
|     ------------------------------------------------------------------------|
|     4, 14, 11, 18, 16, 1, 8, 0, 12, 17, 3, 15}, {0, 1, 2, 20, 4, 7, 6, 11,  |
|     ------------------------------------------------------------------------|
|     8, 9, 10, 5, 12, 13, 14, 18, 16, 19, 15, 17, 3}, {0, 1, 2, 3, 4, 5, 6,  |
|     ------------------------------------------------------------------------|
|     7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20}, {7, 10, 8, 13, 6, |
|     ------------------------------------------------------------------------|
|     20, 9, 18, 12, 4, 14, 19, 2, 11, 1, 16, 5, 0, 3, 15, 17}, {7, 1, 9, 0,  |
|     ------------------------------------------------------------------------|
|     12, 17, 2, 3, 4, 8, 10, 15, 6, 11, 14, 13, 5, 16, 19, 20, 18}, {1, 6, 3,|
|     ------------------------------------------------------------------------|
|     19, 16, 2, 0, 8, 15, 13, 9, 12, 17, 10, 4, 20, 14, 18, 11, 5, 7}, {0, 1,|
|     ------------------------------------------------------------------------|
|     15, 20, 4, 8, 6, 12, 17, 9, 10, 2, 3, 13, 14, 18, 16, 19, 5, 7, 11}, {6,|
|     ------------------------------------------------------------------------|
|     10, 12, 13, 11, 20, 5, 18, 2, 7, 14, 19, 8, 9, 1, 16, 4, 0, 3, 15, 17}, |
|     ------------------------------------------------------------------------|
|     {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19,  |
|     ------------------------------------------------------------------------|
|     20}, {0, 9, 15, 20, 10, 8, 14, 12, 17, 1, 4, 2, 3, 13, 6, 18, 16, 19, 5,|
|     ------------------------------------------------------------------------|
|     7, 11}, {13, 10, 8, 15, 6, 7, 9, 11, 12, 4, 14, 5, 2, 16, 1, 17, 0, 3,  |
|     ------------------------------------------------------------------------|
|     19, 20, 18}, {16, 6, 3, 19, 1, 2, 10, 8, 15, 14, 9, 12, 17, 0, 4, 20,   |
|     ------------------------------------------------------------------------|
|     13, 18, 11, 5, 7}, {10, 9, 15, 20, 0, 8, 13, 12, 17, 16, 4, 2, 3, 14, 6,|
|     ------------------------------------------------------------------------|
|     18, 1, 19, 5, 7, 11}, {13, 10, 19, 2, 6, 5, 9, 7, 20, 4, 14, 11, 18, 16,|
|     ------------------------------------------------------------------------|
|     1, 8, 0, 12, 17, 3, 15}, {16, 1, 3, 19, 9, 2, 4, 8, 15, 6, 10, 12, 17,  |
|     ------------------------------------------------------------------------|
|     0, 14, 20, 13, 18, 11, 5, 7}, {13, 10, 5, 15, 4, 12, 6, 2, 7, 9, 14, 8, |
|     ------------------------------------------------------------------------|
|     11, 16, 1, 17, 0, 3, 18, 19, 20}, {10, 9, 15, 20, 0, 8, 13, 12, 17, 16, |
|     ------------------------------------------------------------------------|
|     4, 2, 3, 14, 6, 18, 1, 19, 5, 7, 11}, {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10,|
|     ------------------------------------------------------------------------|
|     11, 12, 13, 14, 15, 16, 17, 18, 19, 20}, {0, 1, 2, 20, 4, 7, 6, 11, 8,  |
|     ------------------------------------------------------------------------|
|     9, 10, 5, 12, 13, 14, 18, 16, 19, 15, 17, 3}, {19, 14, 4, 16, 2, 3, 8,  |
|     ------------------------------------------------------------------------|
|     15, 6, 12, 1, 17, 9, 20, 10, 0, 18, 13, 11, 5, 7}, {0, 1, 6, 20, 7, 2,  |
|     ------------------------------------------------------------------------|
|     11, 8, 9, 5, 10, 12, 4, 13, 14, 18, 16, 19, 15, 17, 3}, {13, 1, 19, 2,  |
|     ------------------------------------------------------------------------|
|     6, 5, 9, 7, 20, 4, 10, 11, 18, 16, 14, 8, 0, 12, 17, 3, 15}, {3, 1, 2,  |
|     ------------------------------------------------------------------------|
|     19, 4, 16, 6, 0, 8, 9, 10, 13, 12, 15, 14, 20, 17, 18, 11, 5, 7}, {0, 1,|
|     ------------------------------------------------------------------------|
|     2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 19, 20, 18}, {0,|
|     ------------------------------------------------------------------------|
|     1, 6, 3, 7, 2, 11, 8, 9, 5, 10, 12, 4, 13, 14, 15, 16, 17, 18, 19, 20}, |
|     ------------------------------------------------------------------------|
|     {13, 10, 8, 15, 6, 7, 9, 11, 12, 4, 14, 5, 2, 16, 1, 17, 0, 3, 19, 20,  |
|     ------------------------------------------------------------------------|
|     18}, {0, 1, 2, 20, 4, 7, 6, 11, 8, 9, 10, 5, 12, 13, 14, 18, 16, 19, 15,|
|     ------------------------------------------------------------------------|
|     17, 3}, {16, 14, 4, 19, 2, 3, 8, 15, 6, 12, 1, 17, 9, 0, 10, 20, 13, 18,|
|     ------------------------------------------------------------------------|
|     11, 5, 7}, {6, 10, 7, 13, 2, 20, 8, 18, 11, 12, 14, 19, 5, 9, 1, 16, 4, |
|     ------------------------------------------------------------------------|
|     0, 3, 15, 17}}                                                          |
|                                                                             |
|o9 : List                                                                    |
+-----------------------------------------------------------------------------+

Caveat
======

This is still somewhat experimental.

Ways to use monodromyGroup:
===========================

  * "monodromyGroup(System)"
  * "monodromyGroup(System,AbstractPoint,List)"
  * monodromyGroup(HomotopyGraph) (missing documentation)

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:794:0.

monodromySolve -- the main function of the MonodromySolver package
******************************************************************

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

Ways to use:
------------

  * monodromySolve(System,AbstractPoint,List)
    -- the main function of
    the MonodromySolver package
  * monodromySolve(System) -- the main
    function of the MonodromySolver package

Ways to use monodromySolve:
===========================

  * monodromySolve(System) -- the main
    function of the MonodromySolver package
  * monodromySolve(System,AbstractPoint,List)
    -- the main function of
    the MonodromySolver package

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:140:0.

monodromySolve(System) -- the main function of the MonodromySolver package
**************************************************************************

  * Function: monodromySolve,

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

This blackbox solver is similar in usage to sparseMonodromySolve,
but with "technical" output.

+-----------------------------------------------------------------------------+
|i1 : R = CC[a,b,c,d][A,B]                                                    |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : polys = polySystem {A^2*a+B^2*b,A*B*c+d}                                |
|                                                                             |
|o2 = polys                                                                   |
|                                                                             |
|o2 : PolySystem                                                              |
+-----------------------------------------------------------------------------+
|i3 : setRandomSeed 0;                                                        |
| -- setting random seed to 0                                                 |
+-----------------------------------------------------------------------------+
|i4 : (V,npaths) = monodromySolve(polys, NumberOfNodes => 3);                 |
+-----------------------------------------------------------------------------+
|i5 : peek V                                                                  |
|                                                                             |
|o5 = HomotopyNode{BasePoint => {-.78761-.616174*ii, .976163-.21704*          |
|                  Edges => MutableList{...8...}                              |
|                  Graph => HomotopyGraph{...12...}                           |
|                  PartialSolBins => {PointArray( 4 points: 3 0 2 1           |
|                                                                             |
|                  PartialSols => {PointArray( 4 points: 0 1 3 2 ),           |
|                                                                             |
|                  Position => 2                                              |
|                                                                2            |
|                  SpecializedSystem => {(- .78761 - .616174*ii)A  +          |
|-----------------------------------------------------------------------------|
|ii, -.416188-.909278*ii, .85817-.513365*ii}                                  |
|                                                                             |
|                                                                             |
|), {.48801-.872838*ii, .814076-.580758*ii}, {-.872838-.48801*ii, .580758+.814|
|                                                                             |
|{.48801-.872838*ii, .814076-.580758*ii}, {-.872838-.48801*ii, .580758+.814076|
|                                                                             |
|                                                                             |
|                       2                                                     |
| (.976163 - .21704*ii)B , (- .416188 - .909278*ii)A*B + .85817 - .513365*ii} |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|                                                                             |
|076*ii}, {-.48801+.872838*ii, -.814076+.580758*ii}, {.872838+.48801*         |
|                                                                             |
|*ii}, {-.48801+.872838*ii, -.814076+.580758*ii}, {.872838+.48801*ii,         |
|-----------------------------------------------------------------------------|
|                         }                                                   |
|                                                                             |
|                                                                             |
|ii, -.580758-.814076*ii}}                                                    |
|                                                                             |
| -.580758-.814076*ii}}                                                       |
+-----------------------------------------------------------------------------+

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

  * monodromySolve(System) -- the main
    function of the MonodromySolver package
-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:185:0.

monodromySolve(System,AbstractPoint,List) -- the main function of the MonodromySolver package
*********************************************************************************************

  * Function: monodromySolve,
  * Usage:
        (N, npaths) = monodromySolve(PS,p0,L)
  * Inputs:
      * PS, an instance of the type System (NAGtypes), with
        parametric coefficients
      * p0, a point (NAGtypes), representing a
        parametrized system
      * L, a list (Macaulay2Doc), containing solutions associated
        to p0, each represented as a AbstractPoint (NAGtypes).
  * Optional inputs (Macaulay2Doc),:
      * AugmentEdgeCount, => ..., default value
        0,
      * AugmentGraphFunction, => ..., default
        value null,
      * AugmentNodeCount, => ..., default value
        0,
      * AugmentNumberOfRepeats, => ..., default
        value null,
      * BatchSize, => ..., default value
        infinity,
      * EdgesSaturated, => ..., default value
        false,
      * Equivalencer (missing documentation) => ..., default value null,
      * FilterCondition (missing documentation) => ..., default value null,
      * GraphInitFunction, => ..., default value
        completeGraphInit,
      * new tracking routine
      * NumberOfEdges, => ..., default value
        null,
      * NumberOfNodes, => ..., default value
        null,
      * NumberOfRepeats, => ..., default value
        10,
      * PointArrayTol (missing documentation) => ..., default value .0001,
      * Potential, => ..., default value null,
      * Randomizer (missing documentation) => ..., default value null,
      * SelectEdgeAndDirection, => ..., default
        value selectFirstEdgeAndDirection,
      * StoppingCriterion, => ..., default value
        null,
      * TargetSolutionCount, => ..., default
        value null,
      * Verbose, => ..., default value false,
  * Outputs:
      * N, an instance of the type HomotopyNode,
      * npaths, an integer (Macaulay2Doc), reporting the number of
        paths tracked.

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

Most solvers rely on the manual seeding function createSeedPair.
The example below demonstrates how one might seed manually
when some equations don't have parameters—ie. the projection map onto the
variables is non-dominant.

+-----------------------------------------------------------------------------+
|i1 : setRandomSeed 0;                                                        |
| -- setting random seed to 0                                                 |
+-----------------------------------------------------------------------------+
|i2 : S = CC[a,b,c];                                                          |
+-----------------------------------------------------------------------------+
|i3 : R = S[x,w];                                                             |
+-----------------------------------------------------------------------------+
|i4 : (h, f) = (a*x+b*w+c, 3*x^2 - w + 1);                                    |
+-----------------------------------------------------------------------------+
|i5 : x0 = point {{ii_CC,-2}}; -- clearly a zero of f                         |
+-----------------------------------------------------------------------------+
|i6 : l = apply(2,i->random CC);                                              |
+-----------------------------------------------------------------------------+
|i7 : p0 = point({append(l,- sum apply(l, x0.Coordinates,(i,x)->i*x))});      |
+-----------------------------------------------------------------------------+
|i8 : (N, npaths) = monodromySolve(polySystem {h,f},p0,{x0},NumberOfNodes=>3);|
+-----------------------------------------------------------------------------+

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

  * monodromySolve(System,AbstractPoint,List)
    -- the main function of
    the MonodromySolver package
-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:171:0.

MonodromySolverOptions
**********************

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

Here are some options for the solvers. The current defaults for a given solver
may be accessed like so:

+-----------------------------------------------------------------------+
|i1 : options monodromySolve                                            |
|                                                                       |
|o1 = OptionTable{AugmentEdgeCount => 0                                }|
|                 AugmentGraphFunction => null                          |
|                 AugmentNodeCount => 0                                 |
|                 AugmentNumberOfRepeats => null                        |
|                 BatchSize => infinity                                 |
|                 EdgesSaturated => false                               |
|                 Equivalencer => null                                  |
|                 FilterCondition => null                               |
|                 GraphInitFunction => completeGraphInit                |
|                 "new tracking routine" => true                        |
|                 NumberOfEdges => null                                 |
|                 NumberOfNodes => null                                 |
|                 NumberOfRepeats => 10                                 |
|                 PointArrayTol => .0001                                |
|                 Potential => null                                     |
|                 Randomizer => null                                    |
|                 SelectEdgeAndDirection => selectFirstEdgeAndDirection |
|                 StoppingCriterion => null                             |
|                 TargetSolutionCount => null                           |
|                 Verbose => false                                      |
|                                                                       |
|o1 : OptionTable                                                       |
+-----------------------------------------------------------------------+

List of Options
---------------

  * Augmentation Options (trigger dynamic strategies)
      * AugmentEdgeCount: number of edges added in augmentation step
      * AugmentGraphFunction: see flowerGraphAugment,
        and completeGraphAugment,
      * AugmentNodeCount: number of nodes in augmentation step (dynamic
        strategy triggered if >0)
      * AugmentNumberOfRepeats: max number of augmentation steps should be set
        to ensure termination
  * BatchSize: maximum number of solutions tracked across an edge
  * EdgesSaturated: fills correspondence tables after stopping criteria
    satisfied
  * Equivalencer: a numeric function of solutions (default (x -> x) that
    divides partial solutions into equivalence classes
  * FilterCondition: boolean function (default (p, x) -> false)) that evaluates
    true when we don't want to collect x (useful when x is an extraneous
    solution produced by path-jumping)
  * GraphInitFunction: the underlying graph topology, see
    completeGraphInit, and flowerGraphInit,
  * NumberOfEdges: number of edges in underlying graph
  * NumberOfNodes: number of nodes in underlying graph
  * NumberOfRepeats: argument for StoppingCriterion
  * PointArrayTol: tolerance used for comparing elements contained inan
    instance of the type PointArray,
  * Potential: a function that assigns a number to each edge in each iteration,
    indicating its potential for producing new solutions. Current supported
    potential functions are potentialE, and
    potentialLowerBound,
  * Randomizer: a function of the parameters that randomizes the homotopies'
    endpoints. Defaults to the
  * gamma (NumericalAlgebraicGeometry)
    -- options for core functions of Numerical Algebraic Geometry
  *  trick when linear in parameters, otherwise no randomization (p -> p)
  * SelectEdgeAndDirection: accepts either selectBestEdgeAndDirection,
    or selectRandomEdgeAndDirection.
    The former also requires setting a
    potential. Default is an internal function that selects the first available
    edge.
  * StoppingCriterion: eg. stop if no progress has been made
  * TargetSolutionCount: expected/desired number of solutions (overrides
    StoppingCriterion)
  * Verbose: reports progress in each iteration

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

The object MonodromySolverOptions, is a
symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:386:0.

net(PointArray) -- pretty printing
**********************************

  * Function: net (Macaulay2Doc),
  * Usage:
        net A
  * Inputs:
      * A, an instance of the type PointArray,
  * Outputs:
      * a net (Macaulay2Doc),

See also
========

  * Net (Macaulay2Doc) -- the class of all nets and strings

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

  * net(PointArray) -- pretty printing
-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:744:0.

PointArray -- a container for solutions
***************************************

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

PointArray is a data structure that organizes the solutions found by a solver.
Each HomotopyNode, object V has an associated PointArray
accessed via V.PartialSols. A "fingerprinting" scheme allows for equality of
points to be checked quickly.

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

  * "appendPoint(PointArray,AbstractPoint)" -- see appendPoint,
    -- append a point at the end of a PointArray
  * "appendPoints(PointArray,List)" -- see appendPoints, --
    append a list of points at the end of a PointArray
  * indices(PointArray) -- returns indices of a
    PointArray
  * isMember(AbstractPoint,PointArray)
    -- test point membership in a
    PointArray
  * isMember(AbstractPoint,PointArray,FunctionClosure) (missing documentation)
  * length(PointArray) -- number of items stored
    in a PointArray
  * net(PointArray) -- pretty printing

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:704:0.

pointArray -- constructor for PointArray
****************************************

  * Usage:
        A = pointArray L
  * Inputs:
      * L, a list (Macaulay2Doc), containing objects of type
        AbstractPoint (NAGtypes),
  * Outputs:
      * A, an instance of the type PointArray,

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:691:0.

potentialE -- the "expected" potential of an edge
*************************************************

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

This is an option for the Potential option for monodromySolve,
when we use selectBestEdgeAndDirection,
option to select edge and direction. This option
computes the expected number of new points obtained by tracking points (under
suitable randomness assumptions about the permutations generated by the
underlying graph.) The expected value is computed by the ratio of unmatched
points and the difference between the total solution count and the number of
the known points.

+------------------------------------------------------------------+
|i1 : R = CC[a,b,c,d,e,f,g,h][x,y,z];                              |
+------------------------------------------------------------------+
|i2 : polys = polySystem {a*x+b*y+c*z,d*x*y+e*x*z+f*y*z,g*x*y*z+h};|
+------------------------------------------------------------------+

In here, we need the target number of solutions, and we will use the mixed
volume for that.

+-----------------------------------------------------------------------------+
|i3 : (p0,x0) := createSeedPair polys                                         |
|                                                                             |
|o3 = ({-.395781-.24074*ii, 1.15221-.036791*ii, -.339811+.226642*ii,          |
|     ------------------------------------------------------------------------|
|     .225376-.140718*ii, -.324066-.135951*ii, .509177+.360148*ii,            |
|     ------------------------------------------------------------------------|
|     .287657+.283636*ii, .130507+.183897*ii}, {.892712+.673395*ii,           |
|     ------------------------------------------------------------------------|
|     .29398+.632944*ii, .025888+.714827*ii})                                 |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+

We will comput the mixed volume to find the number of solution counts.

+-----------------------------------------------------------------------------+
|i4 : mixedVol = computeMixedVolume specializeSystem(p0,polys)                |
|                                                                             |
|o4 = 6                                                                       |
+-----------------------------------------------------------------------------+
|i5 : monodromySolve(polys,p0,{x0},SelectEdgeAndDirection=>                   |
|                                                                             |
|o5 = (HomotopyNode{...7...}, 10)                                             |
|                                                                             |
|o5 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|selectBestEdgeAndDirection, Potential=>potentialE,                           |
|-----------------------------------------------------------------------------|
|TargetSolutionCount=>mixedVol)                                               |
+-----------------------------------------------------------------------------+

See also
========

  * selectBestEdgeAndDirection -- selects
    edge and direction based on highest potential for obtaining new information
  * potentialLowerBound -- the potential which is
    equal to the minimal number of new points guaranteed to be discovered
  * computeMixedVolume -- compute mixed volume via
    Gfan
  * Potential

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

The object potentialE, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:677:0.

potentialLowerBound -- the potential which is equal to the minimal number of new points guaranteed to be discovered
*******************************************************************************************************************

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

This is an option for the Potential option for monodromySolve,
when we use selectBestEdgeAndDirection,
option to select edge and direction. This option
observes discovered and undiscovered points first, and then follows the
homotopy which has the minimal number of new points guaranteed to be found.

+-----------------------------------------------------------------------------+
|i1 : R = CC[a,b,c,d][x,y];                                                   |
+-----------------------------------------------------------------------------+
|i2 : polys = polySystem {a*x+b*y^2,c*x*y+d};                                 |
+-----------------------------------------------------------------------------+
|i3 : (V, npaths) = monodromySolve(polys,SelectEdgeAndDirection=>             |
|                                                                             |
|o3 = (HomotopyNode{...7...}, 3)                                              |
|                                                                             |
|o3 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|selectBestEdgeAndDirection, Potential=>potentialLowerBound)                  |
+-----------------------------------------------------------------------------+
|i4 : G = V.Graph;                                                            |
+-----------------------------------------------------------------------------+
|i5 : apply(toList G.Edges,e->e.Potential12)--potentials for all edges of a   |
|                                                                             |
|o5 = {0, 0, 0, 0}                                                            |
|                                                                             |
|o5 : List                                                                    |
|-----------------------------------------------------------------------------|
|given direction                                                              |
+-----------------------------------------------------------------------------+

See also
========

  * selectBestEdgeAndDirection -- selects
    edge and direction based on highest potential for obtaining new information
  * potentialE -- the "expected" potential of an edge
  * HomotopyEdge (missing documentation)

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

The object potentialLowerBound, is a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:448:0.

selectBestEdgeAndDirection -- selects edge and direction based on highest potential for obtaining new information
*****************************************************************************************************************

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

By default, the solver option SelectEdgeAndDirection is set to
selectRandomEdgeAndDirection; it may be changed to selectBestEdgeAndDirection
as shown below. This will return an error unless the option Potential,
is also set.

+-----------------------------------------------------------------------------+
|i1 : R = CC[a,b,c,d][x,y];                                                   |
+-----------------------------------------------------------------------------+
|i2 : polys = polySystem {a*x+b*y^2,c*x*y+d};                                 |
+-----------------------------------------------------------------------------+
|i3 : (V,npaths) = monodromySolve(polys,SelectEdgeAndDirection=>              |
|                                                                             |
|o3 = (HomotopyNode{...7...}, 3)                                              |
|                                                                             |
|o3 : Sequence                                                                |
|-----------------------------------------------------------------------------|
|selectBestEdgeAndDirection, Potential=>potentialLowerBound)                  |
+-----------------------------------------------------------------------------+

See also
========

  * selectRandomEdgeAndDirection -- random
    selection of edge and direction for homotopy
  * potentialLowerBound -- the potential which is
    equal to the minimal number of new points guaranteed to be discovered
  * potentialE -- the "expected" potential of an edge
  * HomotopyEdge (missing documentation)
  * MonodromySolverOptions

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

The object selectBestEdgeAndDirection, is a
function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:277:0.

selectRandomEdgeAndDirection -- random selection of edge and direction for homotopy
***********************************************************************************

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

This is the random edge-selection strategy for solvers. An edge is chosen
uniformly at random from all edges in the underlying HomotopyGraph,
then its direction is chosen randomly. This is currently the
default behavior for all solvers.

See also
========

  * selectBestEdgeAndDirection -- selects
    edge and direction based on highest potential for obtaining new information
  * HomotopyEdge (missing documentation)
  * MonodromySolverOptions

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

The object selectRandomEdgeAndDirection, is
a function closure (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:256:0.

solveFamily -- a solver for parametric families with simple output
******************************************************************

  * Usage:
        (p, sols) = solveFamily PS
        (p, sols) = solveFamily(p, P)
  * Inputs:
      * PS, an instance of the type System (NAGtypes), : a
        parametric polynomial system, represented as either a PolySystem (NAGtypes),
        whose underlying coefficient ring itself a
        polynomial ring in the parameters, or a GateSystem (NumericalAlgebraicGeometry),
        with parameters.
      * p, a point (NAGtypes), consisting of target
        parameter values (optional.)
  * Optional inputs (Macaulay2Doc),:
      * AugmentEdgeCount, => ..., default value
        0,
      * AugmentGraphFunction, => ..., default
        value null,
      * AugmentNodeCount, => ..., default value
        0,
      * AugmentNumberOfRepeats, => ..., default
        value null,
      * BatchSize, => ..., default value
        infinity,
      * EdgesSaturated, => ..., default value
        false,
      * Equivalencer, => ..., default value null,
      * FilterCondition, => ..., default value
        null,
      * GraphInitFunction, => ..., default value
        completeGraphInit,
      * new tracking routine
      * NumberOfEdges, => ..., default value
        null,
      * NumberOfNodes, => ..., default value
        null,
      * NumberOfRepeats, => ..., default value
        10,
      * PointArrayTol (missing documentation) => ..., default value .0001,
      * Potential, => ..., default value null,
      * Randomizer, => ..., default value null,
      * SelectEdgeAndDirection, => ..., default
        value selectFirstEdgeAndDirection,
      * StoppingCriterion, => ..., default value
        null,
      * TargetSolutionCount, => ..., default
        value null,
      * Verbose, => ..., default value false,
  * Outputs:
      * p, an instance of the type Point (NAGtypes),
        parameter values. If not part of the input, they are chosen uniformly
        as complex numbers w/ modulus 1.
      * sols, an instance of the type PointArray, containing
        solutions to PS specialized at p.

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

The output of monodromySolve, is opaque. This method is
intended for users uninterested in the underlying HomotopyGraph,
and its satellite data. When the number of solutions is small,
it can help to increase options like NumberOfNodes,
or NumberOfEdges, above
their default value, as shown here:

+-----------------------------------------------------------------------------+
|i1 : setRandomSeed 0                                                         |
| -- setting random seed to 0                                                 |
|                                                                             |
|o1 = 0                                                                       |
+-----------------------------------------------------------------------------+
|i2 : R = CC[a,b,c,d,e,f][x,y];                                               |
+-----------------------------------------------------------------------------+
|i3 : q  = a*x^2+b*y+c;                                                       |
+-----------------------------------------------------------------------------+
|i4 : l = d*x+e*y+f;                                                          |
+-----------------------------------------------------------------------------+
|i5 : (sys, sols) = solveFamily(polySystem{q,l}, NumberOfNodes=>3)            |
|                                                                             |
|o5 = (sys, {{1.7698-.292574*ii, 2.03236+1.25703*ii}, PointArray( 2 points: 1 |
|     ------------------------------------------------------------------------|
|     0 ), {-.770087+.316588*ii, .35355-.743892*ii}})                         |
|                                                                             |
|o5 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Caveat
======

This function is somewhat less flexible than monodromySolve.

Ways to use solveFamily:
========================

  * "solveFamily(AbstractPoint,System)"
  * "solveFamily(System)"

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:126:0.

sparseMonodromySolve -- an "out of the box" polynomial system solver
********************************************************************

  * Usage:
        sols = sparseMonodromySolve PS
  * Inputs:
      * PS, an instance of the type System (NAGtypes), whose
        coefficients are complex numbers
  * Optional inputs (Macaulay2Doc),:
      * AugmentEdgeCount, => ..., default value
        0,
      * AugmentGraphFunction, => ..., default
        value null,
      * AugmentNodeCount, => ..., default value
        0,
      * AugmentNumberOfRepeats, => ..., default
        value null,
      * BatchSize, => ..., default value
        infinity,
      * EdgesSaturated, => ..., default value
        false,
      * Equivalencer, => ..., default value null,
      * FilterCondition, => ..., default value
        null,
      * GraphInitFunction, => ..., default value
        completeGraphInit,
      * new tracking routine
      * NumberOfEdges, => ..., default value
        null,
      * NumberOfNodes, => ..., default value
        null,
      * NumberOfRepeats, => ..., default value
        10,
      * PointArrayTol (missing documentation) => ..., default value .0001,
      * Potential, => ..., default value null,
      * Randomizer, => ..., default value null,
      * SelectEdgeAndDirection, => ..., default
        value selectFirstEdgeAndDirection,
      * StoppingCriterion, => ..., default value
        null,
      * TargetSolutionCount, => ..., default
        value null,
      * Verbose, => ..., default value false,
  * Outputs:
      * sols, a list (Macaulay2Doc), containing solutions to sys,
        each represented as a Point (NAGtypes).

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

Blackbox monodromy solver for a square polynomial system without parameters.
The example below finds all six intersection of a generic cubic F with its
quadratic polar curve P.

+-----------------------------------------------------------------------------+
|i1 : setRandomSeed 2021;                                                     |
| -- setting random seed to 2021                                              |
+-----------------------------------------------------------------------------+
|i2 : R=CC[x,y,z];                                                            |
+-----------------------------------------------------------------------------+
|i3 : F=random(3,R);                                                          |
|-- warning: experimental computation over inexact field begun                |
|--          results not reliable (one warning given per session)             |
+-----------------------------------------------------------------------------+
|i4 : P=sum apply(gens R,g->diff(g,F)*random CC);                             |
+-----------------------------------------------------------------------------+
|i5 : PS = polySystem {F,P,random(1,R)-1};                                    |
+-----------------------------------------------------------------------------+
|i6 : sols = sparseMonodromySolve PS;                                         |
+-----------------------------------------------------------------------------+
|i7 : length points sols                                                      |
|                                                                             |
|o7 = 6                                                                       |
+-----------------------------------------------------------------------------+
|i8 : for i from 0 to 5 list norm evaluate(PS, sols#i)                        |
|                                                                             |
|o8 = {4.44089e-15, 1.0732e-14, 1.11022e-16, 6.66134e-16, 2.78677e-13,        |
|     ------------------------------------------------------------------------|
|     2.98937e-16}                                                            |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

For systems with dense support such as the above, the total number of paths
tracked is generally not optimal, though timings may be comparable.

Ways to use sparseMonodromySolve:
=================================

  * "sparseMonodromySolve(PolySystem)"

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:92:0.

specializeSystem -- specialize parametric system at a point in the parameter space.
***********************************************************************************

  * Usage:
        equations = specializeSystem(p0, PS)
  * Inputs:
      * p0, a point (NAGtypes), in parameter space
      * PS, an instance of the type System (NAGtypes), with
        parameters as coefficients
  * Outputs:
      * equations, a list (Macaulay2Doc), containing equations of
        system with parameters specialized at p0

Ways to use specializeSystem:
=============================

  * "specializeSystem(AbstractPoint,Matrix)"
  * "specializeSystem(AbstractPoint,PolySystem)"
  * specializeSystem(AbstractPoint,GateSystem) (missing documentation)

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

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

-------------------------------------------------------------------------------

The source of this document is in MonodromySolver/Documentation.m2:203:0.