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

NumericalImplicitization -- implicitization using numerical algebraic geometry
******************************************************************************

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

This package supports user-friendly calculation of basic invariants of the
image of a polynomial map. The computational techniques (interpolation,
homotopy continuation and monodromy) come from numerical algebraic geometry.

Many varieties of interest in algebraic geometry and its applications are
usefully described as images of polynomial maps, via a parametrization.
Implicitization is the process of converting a parametric description of a
variety into an intrinsic, or implicit, description. Classically,
implicitization refers to the procedure of computing the defining equations of
a parametrized variety, and in theory this is accomplished by finding the
kernel of a ring homomorphism, via Gr&ouml;bner bases. In practice however,
symbolic Gr&ouml;bner basis computations are often time consuming, even for
medium scale problems, and do not scale well with respect to the size of the
input.

Despite this, one would often like to know basic information about a
parametrized variety, even when symbolic methods are prohibitively expensive.
Examples of such information are discrete invariants such as the
dimension, the degree, or
Hilbert function, values. Other examples include
Boolean tests, for example whether a particular point lies on,
a parametrized variety. The goal of this package is to provide such
information; in other words to numerically implicitize a parametrized variety.

NumericalImplicitization builds on existing numerical algebraic geometry
software: NAG4M2 (NumericalAlgebraicGeometry), Bertini,
and PHCpack. The user may specify any of
these to use for path tracking and point sampling; by default, the native
software NAG4M2 is used. Currently, all methods are implemented for reduced and
irreducible varieties.

Reference:

[1] A.J. Sommese and C.W. Wampler, The numerical solution of systems of
polynomials. World Scientific Publishing (2005).

Authors
=======

  * Justin Chen (see https://people.math.gatech.edu/~jchen646/ )
    <justin.chen@math.gatech.edu>
  * Joe Kileel (see https://web.math.princeton.edu/~jkileel/ )
    <jkileel@math.princeton.edu>

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

Version 2.1.0 of this package was accepted for publication in volume 9 (see
https://msp.org/jsag/2019/9-1/ ) of The Journal of Software for Algebra and
Geometry (see http://j-sag.org/ ) on 11 April 2019, in the article Numerical
implicitization (see https://msp.org/jsag/2019/9-1/p07.xhtml ). That version
can be obtained from the journal (see
https://msp.org/jsag/2019/9-1/jsag-v9-n1-x07-NumericalImplicitization.m2 ) or
from the Macaulay2 source code repository (see
http://github.com/Macaulay2/M2/blob/2f801d123692462f4a65ccb135d411be425c28bd/M2
/Macaulay2/packages/NumericalImplicitization.m2 ).

Version
=======

This documentation describes version 2.2.0 of NumericalImplicitization.

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

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

Exports
=======

  * Types
      * NumericalInterpolationTable -- the
        class of all NumericalInterpolationTables
      * PseudoWitnessSet -- the class of all
        pseudo-witness sets
  * Functions and commands
      * extractImageEquations -- finds implicit
        equations in a fixed degree for the image of a variety
      * isOnImage -- tests whether a point lies on the image
        of a variety
      * numericalHilbertFunction -- computes
        the values of the Hilbert function for the image of a variety
      * numericalImageDegree -- computes the
        degree of the image of a variety
      * numericalImageDim -- computes the dimension
        of the image of a variety
      * numericalImageSample -- samples general
        points on the image of a variety
      * numericalNullity -- computes numerical kernel
        dimension of a matrix
      * numericalSourceSample -- samples a
        general point on a variety
      * pseudoWitnessSet -- computes a pseudo-witness
        set for the image of a variety
      * "lineSearch" -- see realPoint, -- samples a real point
        on a variety
      * "optimizeNelderMead" -- see realPoint, -- samples a
        real point on a variety
      * realPoint -- samples a real point on a variety
  * Methods
      * "extractImageEquations(List,Ideal,ZZ)" -- see
        extractImageEquations, -- finds implicit
        equations in a fixed degree for the image of a variety
      * "extractImageEquations(Matrix,Ideal,ZZ)" -- see
        extractImageEquations, -- finds implicit
        equations in a fixed degree for the image of a variety
      * "extractImageEquations(NumericalInterpolationTable)" -- see
        extractImageEquations, -- finds implicit
        equations in a fixed degree for the image of a variety
      * "extractImageEquations(RingMap,Ideal,ZZ)" -- see
        extractImageEquations, -- finds implicit
        equations in a fixed degree for the image of a variety
      * "isOnImage(List,Ideal,Point)" -- see isOnImage, --
        tests whether a point lies on the image of a variety
      * "isOnImage(Matrix,Ideal,Point)" -- see isOnImage, --
        tests whether a point lies on the image of a variety
      * "isOnImage(PseudoWitnessSet,Point)" -- see isOnImage,
        -- tests whether a point lies on the image of a variety
      * "isOnImage(RingMap,Ideal,Point)" -- see isOnImage, --
        tests whether a point lies on the image of a variety
      * "numericalHilbertFunction(List,Ideal,List,ZZ)" -- see
        numericalHilbertFunction, -- computes the
        values of the Hilbert function for the image of a variety
      * "numericalHilbertFunction(List,Ideal,ZZ)" -- see
        numericalHilbertFunction, -- computes the
        values of the Hilbert function for the image of a variety
      * "numericalHilbertFunction(Matrix,Ideal,List,ZZ)" -- see
        numericalHilbertFunction, -- computes the
        values of the Hilbert function for the image of a variety
      * "numericalHilbertFunction(Matrix,Ideal,ZZ)" -- see
        numericalHilbertFunction, -- computes the
        values of the Hilbert function for the image of a variety
      * "numericalHilbertFunction(RingMap,Ideal,List,ZZ)" -- see
        numericalHilbertFunction, -- computes the
        values of the Hilbert function for the image of a variety
      * "numericalHilbertFunction(RingMap,Ideal,ZZ)" -- see
        numericalHilbertFunction, -- computes the
        values of the Hilbert function for the image of a variety
      * "numericalImageDegree(List,Ideal)" -- see numericalImageDegree,
        -- computes the degree of the image of a variety
      * "numericalImageDegree(Matrix,Ideal)" -- see numericalImageDegree,
        -- computes the degree of the image of a variety
      * "numericalImageDegree(PseudoWitnessSet)" -- see
        numericalImageDegree, -- computes the degree of
        the image of a variety
      * "numericalImageDegree(RingMap,Ideal)" -- see
        numericalImageDegree, -- computes the degree of
        the image of a variety
      * "numericalImageDim(List,Ideal)" -- see numericalImageDim,
        -- computes the dimension of the image of a variety
      * "numericalImageDim(List,Ideal,Point)" -- see numericalImageDim,
        -- computes the dimension of the image of a variety
      * "numericalImageDim(Matrix,Ideal)" -- see numericalImageDim,
        -- computes the dimension of the image of a variety
      * "numericalImageDim(Matrix,Ideal,Point)" -- see numericalImageDim,
        -- computes the dimension of the image of a variety
      * "numericalImageDim(RingMap,Ideal)" -- see numericalImageDim,
        -- computes the dimension of the image of a variety
      * "numericalImageDim(RingMap,Ideal,Point)" -- see
        numericalImageDim, -- computes the dimension of the
        image of a variety
      * "numericalImageSample(List,Ideal)" -- see numericalImageSample,
        -- samples general points on the image of a
        variety
      * "numericalImageSample(List,Ideal,List,ZZ)" -- see
        numericalImageSample, -- samples general points
        on the image of a variety
      * "numericalImageSample(List,Ideal,ZZ)" -- see
        numericalImageSample, -- samples general points
        on the image of a variety
      * "numericalImageSample(Matrix,Ideal)" -- see numericalImageSample,
        -- samples general points on the image of a
        variety
      * "numericalImageSample(Matrix,Ideal,List,ZZ)" -- see
        numericalImageSample, -- samples general points
        on the image of a variety
      * "numericalImageSample(Matrix,Ideal,ZZ)" -- see
        numericalImageSample, -- samples general points
        on the image of a variety
      * "numericalImageSample(RingMap,Ideal)" -- see
        numericalImageSample, -- samples general points
        on the image of a variety
      * "numericalImageSample(RingMap,Ideal,List,ZZ)" -- see
        numericalImageSample, -- samples general points
        on the image of a variety
      * "numericalImageSample(RingMap,Ideal,ZZ)" -- see
        numericalImageSample, -- samples general points
        on the image of a variety
      * "net(NumericalInterpolationTable)" -- see
        NumericalInterpolationTable, -- the class
        of all NumericalInterpolationTables
      * "numericalNullity(List,Boolean)" -- see numericalNullity,
        -- computes numerical kernel dimension of a matrix
      * "numericalNullity(Matrix)" -- see numericalNullity,
        -- computes numerical kernel dimension of a matrix
      * "numericalNullity(Matrix,Boolean)" -- see numericalNullity,
        -- computes numerical kernel dimension of a matrix
      * "numericalSourceSample(Ideal)" -- see numericalSourceSample,
        -- samples a general point on a variety
      * "numericalSourceSample(Ideal,Point)" -- see
        numericalSourceSample, -- samples a general
        point on a variety
      * "numericalSourceSample(Ideal,Thing,ZZ)" -- see
        numericalSourceSample, -- samples a general
        point on a variety
      * "numericalSourceSample(Ideal,WitnessSet)" -- see
        numericalSourceSample, -- samples a general
        point on a variety
      * "numericalSourceSample(Ideal,ZZ)" -- see numericalSourceSample,
        -- samples a general point on a variety
      * "net(PseudoWitnessSet)" -- see PseudoWitnessSet,
        -- the class of all pseudo-witness sets
      * "pseudoWitnessSet(List,Ideal)" -- see pseudoWitnessSet,
        -- computes a pseudo-witness set for the image of a
        variety
      * "pseudoWitnessSet(List,Ideal,List,Thing)" -- see
        pseudoWitnessSet, -- computes a pseudo-witness set
        for the image of a variety
      * "pseudoWitnessSet(List,Ideal,Point)" -- see pseudoWitnessSet,
        -- computes a pseudo-witness set for the image of a
        variety
      * "pseudoWitnessSet(Matrix,Ideal)" -- see pseudoWitnessSet,
        -- computes a pseudo-witness set for the image of a
        variety
      * "pseudoWitnessSet(Matrix,Ideal,List,Thing)" -- see
        pseudoWitnessSet, -- computes a pseudo-witness set
        for the image of a variety
      * "pseudoWitnessSet(Matrix,Ideal,Point)" -- see pseudoWitnessSet,
        -- computes a pseudo-witness set for the image of a
        variety
      * "pseudoWitnessSet(RingMap,Ideal)" -- see pseudoWitnessSet,
        -- computes a pseudo-witness set for the image of a
        variety
      * "pseudoWitnessSet(RingMap,Ideal,List,Thing)" -- see
        pseudoWitnessSet, -- computes a pseudo-witness set
        for the image of a variety
      * "pseudoWitnessSet(RingMap,Ideal,Point)" -- see pseudoWitnessSet,
        -- computes a pseudo-witness set for the image of a
        variety
      * "lineSearch(Ideal,Matrix)" -- see realPoint, --
        samples a real point on a variety
      * "optimizeNelderMead(FunctionClosure,List)" -- see realPoint,
        -- samples a real point on a variety
      * "optimizeNelderMead(Ideal)" -- see realPoint, --
        samples a real point on a variety
      * "realPoint(Ideal)" -- see realPoint, -- samples a real
        point on a variety
  * Symbols
      * ConvertToCone -- specifies whether to convert
        image to a cone
      * "AttemptZZ" -- see extractImageEquations,
        -- finds implicit equations in a fixed degree for the image of a
        variety
      * MaxThreads -- specifies the maximum number of
        processor threads
      * "UseSLP" -- see numericalHilbertFunction,
        -- computes the values of the Hilbert
        function for the image of a variety
      * "hilbertFunctionArgument" -- see NumericalInterpolationTable,
        -- the class of all
        NumericalInterpolationTables
      * "hilbertFunctionValue" -- see NumericalInterpolationTable,
        -- the class of all
        NumericalInterpolationTables
      * "imagePoints" -- see NumericalInterpolationTable,
        -- the class of all
        NumericalInterpolationTables
      * "interpolationBasis" -- see NumericalInterpolationTable,
        -- the class of all
        NumericalInterpolationTables
      * "interpolationMatrix" -- see NumericalInterpolationTable,
        -- the class of all
        NumericalInterpolationTables
      * "interpolationSVD" -- see NumericalInterpolationTable,
        -- the class of all
        NumericalInterpolationTables
      * "Precondition" -- see numericalNullity, --
        computes numerical kernel dimension of a matrix
      * "SVDGap" -- see numericalNullity, -- computes
        numerical kernel dimension of a matrix
      * "generalCombinations" -- see PseudoWitnessSet,
        -- the class of all pseudo-witness sets
      * "imageSlice" -- see PseudoWitnessSet, -- the
        class of all pseudo-witness sets
      * "isCompletePseudoWitnessSet" -- see PseudoWitnessSet,
        -- the class of all pseudo-witness sets
      * "sourceEquations" -- see PseudoWitnessSet, --
        the class of all pseudo-witness sets
      * "sourceSlice" -- see PseudoWitnessSet, -- the
        class of all pseudo-witness sets
      * "witnessPointPairs" -- see PseudoWitnessSet, --
        the class of all pseudo-witness sets
      * "DoRefinements" -- see pseudoWitnessSet, --
        computes a pseudo-witness set for the image of a variety
      * "DoTraceTest" -- see pseudoWitnessSet, --
        computes a pseudo-witness set for the image of a variety
      * "MaxAttempts" -- see pseudoWitnessSet, --
        computes a pseudo-witness set for the image of a variety
      * "MaxPoints" -- see pseudoWitnessSet, --
        computes a pseudo-witness set for the image of a variety
      * "Repeats" -- see pseudoWitnessSet, -- computes
        a pseudo-witness set for the image of a variety
      * "TraceThreshold" -- see pseudoWitnessSet, --
        computes a pseudo-witness set for the image of a variety
      * "Initial" -- see realPoint, -- samples a real point on
        a variety

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

The object NumericalImplicitization, is a package (Macaulay2Doc).

ConvertToCone -- specifies whether to convert image to a cone
*************************************************************

Synopsis
========

  * Usage:
        numericalHilbertFunction(..., ConvertToCone => false)

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

This option specifies whether to replace the image $F(V(I))$ with the cone over
$F(V(I))$. If true, then internally the target variety is treated as the affine
cone over its projective closure - to be precise, the map $F$ is replaced with
$t[F, 1]$, where $t$ is a new variable. The default value is false (Macaulay2Doc).

Since numericalHilbertFunction, works by
interpolating monomials (and thus only finds graded relations in the ideal of
the image), this option is necessary when the map is not homogeneous. The
following example demonstrates this for an affine rational curve.

+-----------------------------------------------------------------------------+
|i1 : R = CC[t]                                                               |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : F = {t, t^4, t^6}                                                       |
|                                                                             |
|          4   6                                                              |
|o2 = {t, t , t }                                                             |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : I = ideal 0_R                                                           |
|                                                                             |
|o3 = ideal 0                                                                 |
|                                                                             |
|o3 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i4 : (numericalHilbertFunction(F, I, 3, Verbose => false                     |
|-- warning: experimental computation over inexact field                      |
|--          results not reliable (one warning given per                      |
|                                                                             |
|o4 = true                                                                    |
|-----------------------------------------------------------------------------|
|)).hilbertFunctionValue == 0                                                 |
|begun                                                                        |
|session)                                                                     |
+-----------------------------------------------------------------------------+
|i5 : T = numericalHilbertFunction(F, I, 3, ConvertToCone => true)            |
|Sampling image points ...                                                    |
|     -- used .0254134 seconds                                                |
|Creating interpolation matrix ...                                            |
|     -- used .00725685 seconds                                               |
|Performing normalization preconditioning ...                                 |
|     -- used .00245554 seconds                                               |
|Computing numerical kernel ...                                               |
|     -- used .000341153 seconds                                              |
|                                                                             |
|o5 = a "numerical interpolation table", indicating                           |
|     the space of degree 3 forms in the ideal of the image has dimension 3   |
|                                                                             |
|o5 : NumericalInterpolationTable                                             |
+-----------------------------------------------------------------------------+
|i6 : extractImageEquations(T, AttemptZZ => true)                             |
|                                                                             |
|o6 = | -y_0^2y_2+y_1^2y_3 -y_1^3+y_2^2y_3 -y_0^2y_1+y_2y_3^2 |               |
|                                                                             |
|                          1                    3                             |
|o6 : Matrix (CC  [y ..y ])  <--- (CC  [y ..y ])                              |
|               53  0   3            53  0   3                                |
+-----------------------------------------------------------------------------+

See also
========

  * numericalHilbertFunction -- computes the
    values of the Hilbert function for the image of a variety

Functions with optional argument named ConvertToCone :
======================================================

  * "numericalHilbertFunction(...,ConvertToCone=>...)"

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

The object ConvertToCone, is a symbol (Macaulay2Doc).

extractImageEquations -- finds implicit equations in a fixed degree for the image of a variety
**********************************************************************************************

Synopsis
========

  * Usage:
        extractImageEquations(F, I, d)
        extractImageEquations T
  * Inputs:
      * T, a numerical interpolation table,
        a numerical interpolation table for $F(V(I))$ of degree $d$
      * F, a matrix (Macaulay2Doc), or list (Macaulay2Doc),
        or ring map (Macaulay2Doc),
        specifying a map
      * I, an ideal (Macaulay2Doc), which is prime, specifying a
        source variety $V(I)$
      * d, an integer (Macaulay2Doc), the argument of the Hilbert
        function of $F(V(I))$
  * Optional inputs (Macaulay2Doc),:
      * AttemptZZ => ..., default value false
      * Threshold => ..., default value 5
  * Outputs:
      * a matrix (Macaulay2Doc), of implicit degree d equations
        for $F(V(I))$

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

This method finds (approximate) implicit degree $d$ equations for the image of
a variety, by numerical interpolation. The
option AttemptZZ specifies whether to use the LLL (LLLBases),
algorithm to compute "short" equations over ZZ (Macaulay2Doc). The
default value is false (Macaulay2Doc).

If a numerical interpolation table has already been computed, then to avoid
repetitive calculation one may run this function with the interpolation table
as input.

For example, we determine the defining quadrics of the twisted cubic, as
follows.

+----------------------------------------------------------------+
|i1 : R = CC[s,t]                                                |
|                                                                |
|o1 = R                                                          |
|                                                                |
|o1 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i2 : F = basis(3, R)                                            |
|-- warning: experimental computation over inexact field begun   |
|--          results not reliable (one warning given per session)|
|                                                                |
|o2 = | s3 s2t st2 t3 |                                          |
|                                                                |
|             1       4                                          |
|o2 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i3 : extractImageEquations(F, ideal 0_R, 2, AttemptZZ => true)  |
|Sampling image points ...                                       |
|     -- used .00331822 seconds                                  |
|Creating interpolation matrix ...                               |
|     -- used .003182 seconds                                    |
|Performing normalization preconditioning ...                    |
|     -- used .000901236 seconds                                 |
|Computing numerical kernel ...                                  |
|     -- used .000269246 seconds                                 |
|                                                                |
|o3 = | y_1^2-y_0y_2 y_1y_2-y_0y_3 y_2^2-y_1y_3 |                |
|                                                                |
|                          1                    3                |
|o3 : Matrix (CC  [y ..y ])  <--- (CC  [y ..y ])                 |
|               53  0   3            53  0   3                   |
+----------------------------------------------------------------+

Here is how to do the same computation symbolically.

+---------------------------------------------------------------+
|i4 : gens ker map(QQ[s,t], QQ[y_0..y_3], {s^3,s^2*t,s*t^2,t^3})|
|                                                               |
|o4 = | y_2^2-y_1y_3 y_1y_2-y_0y_3 y_1^2-y_0y_2 |               |
|                                                               |
|                        1                  3                   |
|o4 : Matrix (QQ[y ..y ])  <--- (QQ[y ..y ])                    |
|                 0   3              0   3                      |
+---------------------------------------------------------------+

We determine the $5$ Pl&uuml;cker quadrics defining the Grassmannian $Gr(3,5)$
of $P^2$'s in $P^4$, in the ambient space $P^9$.

+-----------------------------------------------------------------------------+
|i5 : R = CC[x_(1,1)..x_(3,5)]; I = ideal 0_R;                                |
|                                                                             |
|o6 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i7 : F = (minors(3, genericMatrix(R, 3, 5)))_*;                              |
+-----------------------------------------------------------------------------+
|i8 : T = numericalHilbertFunction(F, I, 2, Verbose => false);                |
+-----------------------------------------------------------------------------+
|i9 : extractImageEquations(T, AttemptZZ => true)                             |
|                                                                             |
|o9 = | y_3y_5-y_2y_6+y_0y_9 y_2y_4-y_1y_5+y_0y_7 y_3y_4-y_1y_6+y_0y_8        |
|     ------------------------------------------------------------------------|
|     y_3y_7-y_2y_8+y_1y_9 y_6y_7-y_5y_8+y_4y_9 |                             |
|                                                                             |
|                          1                    5                             |
|o9 : Matrix (CC  [y ..y ])  <--- (CC  [y ..y ])                              |
|               53  0   9            53  0   9                                |
+-----------------------------------------------------------------------------+

The option Threshold sets the threshold for rounding the interpolation matrix.
If this option has value $n$, then the interpolation matrix will be rounded to
$n$ decimal digits, after which LLL will be performed. The default value is
$5$.

See also
========

  * numericalHilbertFunction -- computes the
    values of the Hilbert function for the image of a variety
  * NumericalInterpolationTable -- the
    class of all NumericalInterpolationTables

Ways to use extractImageEquations :
===================================

  * "extractImageEquations(List,Ideal,ZZ)"
  * "extractImageEquations(Matrix,Ideal,ZZ)"
  * "extractImageEquations(NumericalInterpolationTable)"
  * "extractImageEquations(RingMap,Ideal,ZZ)"

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

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

isOnImage -- tests whether a point lies on the image of a variety
*****************************************************************

Synopsis
========

  * Usage:
        isOnImage(W, p)
        isOnImage(F, I, p)
  * Inputs:
      * W, a pseudo-witness set, a pseudo-witness set
        for $F(V(I))$
      * p, a point (NAGtypes), a point in the ambient space of
        $F(V(I))$
      * F, a matrix (Macaulay2Doc), or list (Macaulay2Doc),
        or ring map (Macaulay2Doc),
        specifying a map
      * I, an ideal (Macaulay2Doc), which is prime, specifying a
        source variety $V(I)$
  * Optional inputs (Macaulay2Doc),:
      * MaxThreads, => ..., default value 1, specifies the
        maximum number of processor threads
      * Software,
        => ..., default value M2engine, specify software for homotopy
        continuation
      * Threshold, => ..., default value 5, computes a
        pseudo-witness set for the image of a variety
      * Verbose,
        => ..., default value true, display detailed output
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether the point $p$
        lies on $F(V(I))$

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

This method determines if a point in the ambient target space lies on the image
of a variety. This is done via computing a pseudo-witness set for the image.

If a pseudo-witness set has already been computed, then to avoid repetitive
calculation one may run this function with the pseudo-witness set as input.

The following example determines whether a point lies on the Grassmannian
$Gr(2,4)$ of $P^1$'s in $P^3$, under its Pl&uuml;cker embedding in $P^5$.

+----------------------------------------------------------------+
|i1 : R = CC[x_(1,1)..x_(2,4)]; I = ideal 0_R;                   |
|                                                                |
|o2 : Ideal of R                                                 |
+----------------------------------------------------------------+
|i3 : F = (minors(2, genericMatrix(R, 2, 4)))_*;                 |
+----------------------------------------------------------------+
|i4 : W = pseudoWitnessSet(F, I, Repeats => 2, Verbose => false);|
+----------------------------------------------------------------+
|i5 : q = first numericalImageSample(F, I)                       |
|                                                                |
|o5 = q                                                          |
|                                                                |
|o5 : Point                                                      |
+----------------------------------------------------------------+
|i6 : isOnImage(W, q)                                            |
|                                                                |
|o6 = true                                                       |
+----------------------------------------------------------------+
|i7 : isOnImage(W, point random(CC^1, CC^#F))                    |
|                                                                |
|o7 = false                                                      |
+----------------------------------------------------------------+
|i8 : isOnImage(W, point{{1_CC,0,0,0,0,0}})                      |
|                                                                |
|o8 = true                                                       |
+----------------------------------------------------------------+

See also
========

  * pseudoWitnessSet -- computes a pseudo-witness set
    for the image of a variety
  * PseudoWitnessSet -- the class of all
    pseudo-witness sets

Ways to use isOnImage :
=======================

  * "isOnImage(List,Ideal,Point)"
  * "isOnImage(Matrix,Ideal,Point)"
  * "isOnImage(PseudoWitnessSet,Point)"
  * "isOnImage(RingMap,Ideal,Point)"

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

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

MaxThreads -- specifies the maximum number of processor threads
***************************************************************

Synopsis
========

  * Usage:
        pseudoWitnessSet(..., MaxThreads => allowableThreads)
        numericalImageDegree(..., MaxThreads => allowableThreads)
        isOnImage(..., MaxThreads => allowableThreads)

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

This option sets the maximum number of processor threads that will be used for
parallel computation. This distributes the paths to track in each monodromy
loop among the processors as evenly as possible. The value of this option
should not exceed the value of the variable allowableThreads. The default value
is $1$.

Caveat
======

Parallel computation in $Macaulay2$ is under development. Unexpected errors may
be printed to output while computing a pseudo-witness set - however, the loop
will still run, and an answer will still be returned.

If the number of paths to track is too low (i.e. less than or equal to $20$),
then parallel computing will not be used.

See also
========

  * numericalImageDegree -- computes the degree of
    the image of a variety
  * pseudoWitnessSet -- computes a pseudo-witness set
    for the image of a variety
  * isOnImage -- tests whether a point lies on the image of a
    variety

Functions with optional argument named MaxThreads :
===================================================

  * "isOnImage(...,MaxThreads=>...)"
  * "numericalImageDegree(...,MaxThreads=>...)"
  * "pseudoWitnessSet(...,MaxThreads=>...)"

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

The object MaxThreads, is a symbol (Macaulay2Doc).

numericalHilbertFunction -- computes the values of the Hilbert function for the image of a variety
**************************************************************************************************

Synopsis
========

  * Usage:
        numericalHilbertFunction(F, I, S, d)
        numericalHilbertFunction(F, I, d)
  * Inputs:
      * F, a matrix (Macaulay2Doc), or list (Macaulay2Doc),
        or ring map (Macaulay2Doc),
        specifying a map
      * I, an ideal (Macaulay2Doc), which is prime, specifying a
        source variety $V(I)$
      * S, a list (Macaulay2Doc), of general points on $F(V(I))$
      * d, an integer (Macaulay2Doc), the argument of the Hilbert
        function of $F(V(I))$
  * Optional inputs (Macaulay2Doc),:
      * ConvertToCone, => ..., default value false,
        specifies whether to convert image to a cone
      * Precondition, => ..., default value true,
        computes numerical kernel dimension of a matrix
      * Software,
        => ..., default value M2engine, specify software for homotopy
        continuation
      * SVDGap, => ..., default value 100000, computes
        numerical kernel dimension of a matrix
      * UseSLP => ..., default value false
      * Verbose,
        => ..., default value true, display detailed output
  * Outputs:
      * a numerical interpolation table,
        containing the number of linearly independent degree $d$ forms in the
        ideal of the projective closure of $F(V(I))$, along with approximations
        of those forms

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

This method computes values of the Hilbert function of the image of a variety,
by numerical interpolation. In more detail, given a list $S$ of general points
on $F(V(I))$ and a degree $d$, the method forms a matrix whose entries are the
evaluations of monomials of degree $d$ at points in $S$. The kernel of this
interpolation matrix gives degree $d$ equations of the image (provided the
number of points in $S$ is at least the number of degree $d$ monomials). This
technique circumvents the calculation of the kernel of the associated ring map.

In order to speed up computation, the list $S$ of points can be precomputed
(see numericalImageSample). This list of points
can then be re-used in multiple interpolation computations (which can yield a
large speedup over performing separate sampling instances, if the ideal $I$ is
not the zero ideal).

For a further speedup, the option UseSLP allows for the usage of
straight-line programs (SLPexpressions), in creating the interpolation
matrix.

In the following, we compute the dimension of the space of quartics in the
ideal of the twisted cubic and obtain the expected answer, $22$. Note that one
can verify this by dimension counting: quartics in the coordinate ring pull
back to forms of degree $12$ on $P^1$, of which there is a $13$-dimensional
space; thus the space of quartics in the defining ideal has dimension $35 - 13
= 22$.

+---------------------------------------------------------------------------+
|i1 : R = CC[s,t]                                                           |
|                                                                           |
|o1 = R                                                                     |
|                                                                           |
|o1 : PolynomialRing                                                        |
+---------------------------------------------------------------------------+
|i2 : F = basis(3, R)                                                       |
|-- warning: experimental computation over inexact field begun              |
|--          results not reliable (one warning given per session)           |
|                                                                           |
|o2 = | s3 s2t st2 t3 |                                                     |
|                                                                           |
|             1       4                                                     |
|o2 : Matrix R  <--- R                                                      |
+---------------------------------------------------------------------------+
|i3 : numericalHilbertFunction(F, ideal 0_R, 4)                             |
|Sampling image points ...                                                  |
|     -- used .0317569 seconds                                              |
|Creating interpolation matrix ...                                          |
|     -- used .0334276 seconds                                              |
|Performing normalization preconditioning ...                               |
|     -- used .0164707 seconds                                              |
|Computing numerical kernel ...                                             |
|     -- used .001477 seconds                                               |
|                                                                           |
|o3 = a "numerical interpolation table", indicating                         |
|     the space of degree 4 forms in the ideal of the image has dimension 22|
|                                                                           |
|o3 : NumericalInterpolationTable                                           |
+---------------------------------------------------------------------------+

The following example computes the dimension of Pl&uuml;cker quadrics in the
defining ideal of the Grassmannian $Gr(2,4)$ of $P^1$'s in $P^3$, in the
ambient space $P^5$.

+--------------------------------------------------------------------------+
|i4 : R = CC[x_(1,1)..x_(2,4)];                                            |
+--------------------------------------------------------------------------+
|i5 : F = (minors(2, genericMatrix(R, 2, 4)))_*;                           |
+--------------------------------------------------------------------------+
|i6 : S = numericalImageSample(F, ideal 0_R, 60);                          |
+--------------------------------------------------------------------------+
|i7 : numericalHilbertFunction(F, ideal 0_R, S, 2, UseSLP => true)         |
|Creating interpolation matrix ...                                         |
|     -- used .00305004 seconds                                            |
|Performing normalization preconditioning ...                              |
|     -- used .0748517 seconds                                             |
|Computing numerical kernel ...                                            |
|     -- used .00144959 seconds                                            |
|                                                                          |
|o7 = a "numerical interpolation table", indicating                        |
|     the space of degree 2 forms in the ideal of the image has dimension 1|
|                                                                          |
|o7 : NumericalInterpolationTable                                          |
+--------------------------------------------------------------------------+

See also
========

  * NumericalInterpolationTable -- the
    class of all NumericalInterpolationTables
  * extractImageEquations -- finds implicit
    equations in a fixed degree for the image of a variety

Ways to use numericalHilbertFunction :
======================================

  * "numericalHilbertFunction(List,Ideal,List,ZZ)"
  * "numericalHilbertFunction(List,Ideal,ZZ)"
  * "numericalHilbertFunction(Matrix,Ideal,List,ZZ)"
  * "numericalHilbertFunction(Matrix,Ideal,ZZ)"
  * "numericalHilbertFunction(RingMap,Ideal,List,ZZ)"
  * "numericalHilbertFunction(RingMap,Ideal,ZZ)"

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

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

numericalImageDegree -- computes the degree of the image of a variety
*********************************************************************

Synopsis
========

  * Usage:
        numericalImageDegree W
        numericalImageDegree(F, I)
  * Inputs:
      * W, a pseudo-witness set, a pseudo-witness set
        for $F(V(I))$
      * F, a matrix (Macaulay2Doc), or list (Macaulay2Doc),
        or ring map (Macaulay2Doc),
        specifying a map
      * I, an ideal (Macaulay2Doc), which is prime, specifying a
        source variety $V(I)$
  * Optional inputs (Macaulay2Doc),:
      * DoRefinements, => ..., default value false,
        computes a pseudo-witness set for the image of a variety
      * DoTraceTest, => ..., default value true,
        computes a pseudo-witness set for the image of a variety
      * MaxAttempts, => ..., default value 5, computes
        a pseudo-witness set for the image of a variety
      * MaxPoints, => ..., default value infinity,
        computes a pseudo-witness set for the image of a variety
      * MaxThreads, => ..., default value 1, specifies the
        maximum number of processor threads
      * Repeats, => ..., default value 3, computes a
        pseudo-witness set for the image of a variety
      * Software,
        => ..., default value M2engine, specify software for homotopy
        continuation
      * Threshold, => ..., default value 5, computes a
        pseudo-witness set for the image of a variety
      * TraceThreshold, => ..., default value .00001,
        computes a pseudo-witness set for the image of a variety
      * Verbose,
        => ..., default value true, display detailed output
  * Outputs:
      * an integer (Macaulay2Doc), the degree of $F(V(I))$

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

This method computes the degree of the image of a variety, by computing a
pseudo-witness set for the image (cf. pseudo-witness set,
for more on the techniques and options used).

If a pseudo-witness set has already been computed, then to avoid repetitive
calculation one may run this function with the pseudo-witness set as input.

The following example determines the degree of the Grassmannian $Gr(2,4)$ of
$P^1$'s in $P^3$, under its Pl&uuml;cker embedding in $P^5$.

+---------------------------------------------------------------+
|i1 : R = CC[x_(1,1)..x_(2,4)]; I = ideal 0_R;                  |
|                                                               |
|o2 : Ideal of R                                                |
+---------------------------------------------------------------+
|i3 : F = (minors(2, genericMatrix(R, 2, 4)))_*;                |
+---------------------------------------------------------------+
|i4 : numericalImageDegree(F, I, Repeats => 2, Verbose => false)|
|                                                               |
|o4 = 2                                                         |
+---------------------------------------------------------------+

See also
========

  * pseudoWitnessSet -- computes a pseudo-witness set
    for the image of a variety
  * PseudoWitnessSet -- the class of all
    pseudo-witness sets

Ways to use numericalImageDegree :
==================================

  * "numericalImageDegree(List,Ideal)"
  * "numericalImageDegree(Matrix,Ideal)"
  * "numericalImageDegree(PseudoWitnessSet)"
  * "numericalImageDegree(RingMap,Ideal)"

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

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

numericalImageDegree(...,Verbose=>...) -- display detailed output
*****************************************************************

Synopsis
========

  * Usage:
        pseudoWitnessSet(..., Verbose => true)
        numericalImageDegree(..., Verbose => true)
        numericalHilbertFunction(..., Verbose => true)
        isOnImage(..., Verbose => true)
        numericalNullity..., Verbose => true)

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

This option determines whether detailed output is displayed during an
interpolation or monodromy computation, including timings for various
intermediate computations. The default value is true (Macaulay2Doc).

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

  * Default value: true (Macaulay2Doc),
  * Function: numericalImageDegree, -- computes the
    degree of the image of a variety
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

See also
========

  * numericalHilbertFunction -- computes the
    values of the Hilbert function for the image of a variety
  * numericalImageDegree -- computes the degree of
    the image of a variety
  * pseudoWitnessSet -- computes a pseudo-witness set
    for the image of a variety
  * isOnImage -- tests whether a point lies on the image of a
    variety

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

  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabalistic test for isomorphism of modules
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * "isOnImage(...,Verbose=>...)"
  * "numericalHilbertFunction(...,Verbose=>...)"
  * numericalImageDegree(...,Verbose=>...)
    -- display
    detailed output
  * "numericalNullity(...,Verbose=>...)"
  * "pseudoWitnessSet(...,Verbose=>...)"
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree

numericalImageDim -- computes the dimension of the image of a variety
*********************************************************************

Synopsis
========

  * Usage:
        numericalImageDim(F, I, p)
        numericalImageDim(F, I)
  * Inputs:
      * F, a matrix (Macaulay2Doc), or list (Macaulay2Doc),
        or ring map (Macaulay2Doc),
        specifying a map
      * I, an ideal (Macaulay2Doc), which is prime, specifying a
        source variety $V(I)$
      * p, a point (NAGtypes), a sample point on the source $V(I)$
  * Optional inputs (Macaulay2Doc),:
      * Software,
        => ..., default value M2engine, specify software for homotopy
        continuation
  * Outputs:
      * an integer (Macaulay2Doc), the dimension of $F(V(I)))$

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

The method computes the dimension of the image of a variety numerically. Even
if the source variety and map are projective, the affine (Krull) dimension is
returned. This ensures consistency with dim (Macaulay2Doc).

The following example computes the affine dimension of the Grassmannian
$Gr(2,4)$ of $P^1$'s in $P^3$, under its Pl&uuml;cker embedding in $P^5$.

+-----------------------------------------------+
|i1 : R = CC[x_(1,1)..x_(2,4)];                 |
+-----------------------------------------------+
|i2 : F = (minors(2, genericMatrix(R, 2, 4)))_*;|
+-----------------------------------------------+
|i3 : numericalImageDim(F, ideal 0_R)           |
|                                               |
|o3 = 5                                         |
+-----------------------------------------------+

For comparison, here is how to do the same computation symbolically.

+-----------------------------------------------+
|i4 : R = QQ[x_(1,1)..x_(2,4)];                 |
+-----------------------------------------------+
|i5 : F = (minors(2, genericMatrix(R, 2, 4)))_*;|
+-----------------------------------------------+
|i6 : dim ker map(R,QQ[y_0..y_(#F-1)],F)        |
|                                               |
|o6 = 5                                         |
+-----------------------------------------------+

Next is an example where direct symbolic computation fails to terminate
quickly. Part of the Alexander-Hirschowitz theorem states that the $14$th
secant variety of the $4$th Veronese of $P^4$ has affine dimension $69$, rather
than the expected $14*4 + 13 + 1 = 70$. See J. Alexander, A. Hirschowitz,
$Polynomial interpolation in several variables$, J. Alg. Geom. 4(2) (1995),
201-222. We numerically verify this below.

+---------------------------------------------------------------------------+
|i7 : R = CC[a_(1,1)..a_(14,5)];                                            |
+---------------------------------------------------------------------------+
|i8 : F = sum(1..14, i -> basis(4, R, Variables=>toList(a_(i,1)..a_(i,5))));|
|-- warning: experimental computation over inexact field begun              |
|--          results not reliable (one warning given per session)           |
|                                                                           |
|             1       70                                                    |
|o8 : Matrix R  <--- R                                                      |
+---------------------------------------------------------------------------+
|i9 : time numericalImageDim(F, ideal 0_R)                                  |
|     -- used 0.165684 seconds                                              |
|                                                                           |
|o9 = 69                                                                    |
+---------------------------------------------------------------------------+

Ways to use numericalImageDim :
===============================

  * "numericalImageDim(List,Ideal)"
  * "numericalImageDim(List,Ideal,Point)"
  * "numericalImageDim(Matrix,Ideal)"
  * "numericalImageDim(Matrix,Ideal,Point)"
  * "numericalImageDim(RingMap,Ideal)"
  * "numericalImageDim(RingMap,Ideal,Point)"

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

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

numericalImageSample -- samples general points on the image of a variety
************************************************************************

Synopsis
========

  * Usage:
        numericalImageSample(F, I, P, s)
        numericalImageSample(F, I, s)
        numericalImageSample(F, I)
  * Inputs:
      * F, a matrix (Macaulay2Doc), or list (Macaulay2Doc),
        or ring map (Macaulay2Doc),
        specifying a map
      * I, an ideal (Macaulay2Doc), which is prime, specifying a
        source variety $V(I)$
      * P, a list (Macaulay2Doc), of points on $F(V(I))$
      * s, an integer (Macaulay2Doc), the number of points to sample
        in $F(V(I))$
  * Optional inputs (Macaulay2Doc),:
      * Software,
        => ..., default value M2engine, specify software for homotopy
        continuation
  * Outputs:
      * a list (Macaulay2Doc), of sample points on $F(V(I)))$

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

This method computes a list of sample points on the image of a variety
numerically, by calling numericalSourceSample.

If the number of points $s$ is unspecified, then it is assumed that $s = 1$.

One can optionally provide an initial list of points $P$ on $F(V(I))$, which
will then be completed to a list of $s$ points on $F(V(I))$.

The following example samples a point from the twisted cubic. We then
independently verify that this point does lie on the twisted cubic.

+--------------------------------------------------------------+
|i1 : R = CC[s,t];                                             |
+--------------------------------------------------------------+
|i2 : F = {s^3,s^2*t,s*t^2,t^3};                               |
+--------------------------------------------------------------+
|i3 : p = first numericalImageSample(F, ideal 0_R)             |
|                                                              |
|o3 = p                                                        |
|                                                              |
|o3 : Point                                                    |
+--------------------------------------------------------------+
|i4 : A = matrix{p#Coordinates_{0,1,2}, p#Coordinates_{1,2,3}};|
|                                                              |
|                2          3                                  |
|o4 : Matrix CC    <--- CC                                     |
|              53         53                                   |
+--------------------------------------------------------------+
|i5 : numericalNullity A == 2                                  |
|                                                              |
|o5 = true                                                     |
+--------------------------------------------------------------+

Here is how to sample a point from the Grassmannian $Gr(2,4)$ of $P^1$'s in
$P^3$, under its Pl&uuml;cker embedding in $P^5$. We take maximal minors of a
$2 x 4$ matrix, whose row span gives a $P^1$ in $P^3$.

+-----------------------------------------------------------------------------+
|i6 : R = CC[x_(1,1)..x_(2,4)];                                               |
+-----------------------------------------------------------------------------+
|i7 : F = (minors(2, genericMatrix(R, 2, 4)))_*;                              |
+-----------------------------------------------------------------------------+
|i8 : numericalImageSample(F, ideal 0_R)                                      |
|                                                                             |
|o8 = {{-.434457-.140153*ii, -.374655-.460763*ii, -.192528-.151059*ii,        |
|     ------------------------------------------------------------------------|
|     -.113152+.276111*ii, .222593+.353053*ii, .100773+.425004*ii}}           |
|                                                                             |
|o8 : List                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * numericalSourceSample -- samples a general
    point on a variety

Ways to use numericalImageSample :
==================================

  * "numericalImageSample(List,Ideal)"
  * "numericalImageSample(List,Ideal,List,ZZ)"
  * "numericalImageSample(List,Ideal,ZZ)"
  * "numericalImageSample(Matrix,Ideal)"
  * "numericalImageSample(Matrix,Ideal,List,ZZ)"
  * "numericalImageSample(Matrix,Ideal,ZZ)"
  * "numericalImageSample(RingMap,Ideal)"
  * "numericalImageSample(RingMap,Ideal,List,ZZ)"
  * "numericalImageSample(RingMap,Ideal,ZZ)"

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

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

NumericalInterpolationTable -- the class of all NumericalInterpolationTables
****************************************************************************

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

This is a type of hash table storing the output of a polynomial interpolation
computation, with the following keys:

  * \bf hilbertFunctionArgument: the argument, $d$, to the Hilbert function
  * \bf hilbertFunctionValue: the value of the Hilbert function at $d$
  * \bf imagePoints: a (vertical) list of sample points on the image
  * \bf interpolationBasis: a matrix consisting of the degree $d$ monomials
  * \bf interpolationSVD: the singular value decomposition of the interpolation
    matrix
  * \bf interpolationMatrix: the matrix obtained by evaluating degree $d$
    monomials at the sample points
  * \bf map: the map $F$, of which the image is under consideration
+--------------------------------------------------------------------------+
|i1 : R = CC[x_(1,1)..x_(2,4)];                                            |
+--------------------------------------------------------------------------+
|i2 : F = (minors(2, genericMatrix(R, 2, 4)))_*;                           |
+--------------------------------------------------------------------------+
|i3 : T = numericalHilbertFunction(F, ideal 0_R, 2, Verbose => false)      |
|-- warning: experimental computation over inexact field begun             |
|--          results not reliable (one warning given per session)          |
|                                                                          |
|o3 = a "numerical interpolation table", indicating                        |
|     the space of degree 2 forms in the ideal of the image has dimension 1|
|                                                                          |
|o3 : NumericalInterpolationTable                                          |
+--------------------------------------------------------------------------+
|i4 : (T.hilbertFunctionArgument, T.hilbertFunctionValue)                  |
|                                                                          |
|o4 = (2, 1)                                                               |
|                                                                          |
|o4 : Sequence                                                             |
+--------------------------------------------------------------------------+

See also
========

  * numericalHilbertFunction -- computes the
    values of the Hilbert function for the image of a variety

Functions and methods returning a numerical interpolation table :
=================================================================

  * "numericalHilbertFunction(List,Ideal,List,ZZ)" -- see
    numericalHilbertFunction, -- computes the values
    of the Hilbert function for the image of a variety
  * "numericalHilbertFunction(List,Ideal,ZZ)" -- see
    numericalHilbertFunction, -- computes the values
    of the Hilbert function for the image of a variety
  * "numericalHilbertFunction(Matrix,Ideal,List,ZZ)" -- see
    numericalHilbertFunction, -- computes the values
    of the Hilbert function for the image of a variety
  * "numericalHilbertFunction(Matrix,Ideal,ZZ)" -- see
    numericalHilbertFunction, -- computes the values
    of the Hilbert function for the image of a variety
  * "numericalHilbertFunction(RingMap,Ideal,List,ZZ)" -- see
    numericalHilbertFunction, -- computes the values
    of the Hilbert function for the image of a variety
  * "numericalHilbertFunction(RingMap,Ideal,ZZ)" -- see
    numericalHilbertFunction, -- computes the values
    of the Hilbert function for the image of a variety

Methods that use a numerical interpolation table :
==================================================

  * "extractImageEquations(NumericalInterpolationTable)" -- see
    extractImageEquations, -- finds implicit equations
    in a fixed degree for the image of a variety
  * "net(NumericalInterpolationTable)"

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

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

numericalNullity -- computes numerical kernel dimension of a matrix
*******************************************************************

Synopsis
========

  * Usage:
        numericalNullity M
  * Inputs:
      * M, a matrix (Macaulay2Doc), with real or complex entries
  * Optional inputs (Macaulay2Doc),:
      * Precondition => ..., default value false
      * SVDGap => ..., default value 100000
      * Verbose,
        => ..., default value false, display detailed output
  * Outputs:
      * an integer (Macaulay2Doc), dimension of the kernel of M

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

This method computes the dimension of the kernel of a matrix with real or
complex entries numerically, via singular value decomposition (see SVD (Macaulay2Doc)).

If $\sigma_1 \ge \ldots \ge \sigma_n$ are the singular values of $M$, then to
establish the nullity numerically we look for the largest "significant" gap
between two consecutive singular values, where the gap between $\sigma_i$ and
$\sigma_{i+1}$ is "significant" if the ratio $\sigma_i / \sigma_{i+1}$ exceeds
the value of SVDGap. If a gap is found which is greater than this threshold,
then all singular values after this gap are considered as numerically zero; if
all gaps are less than this threshold, then the matrix is considered
numerically full rank. The default value of SVDGap is $1e5$.

The option Precondition specifies whether the rows of M will be normalized to
have norm $1$ before computing the SVD. This helps reveal nullity if the matrix
is dense (e.g. for a generic interpolation matrix), but not if the matrix is
sparse (e.g. diagonal). The default value is false (Macaulay2Doc).

+-----------------------------------------------------------------------+
|i1 : numericalNullity(matrix{{2, 1}, {0, 1e-5}}, Precondition => false)|
|                                                                       |
|o1 = 1                                                                 |
+-----------------------------------------------------------------------+
|i2 : numericalNullity(map(CC^2,CC^2,0))                                |
|                                                                       |
|o2 = 2                                                                 |
+-----------------------------------------------------------------------+

Caveat
======

The option SVDGap may require tuning by the user.

See also
========

  * SVD (Macaulay2Doc) -- singular value decomposition of a matrix
  * numericalRank (NumericalLinearAlgebra) -- numerical
    rank of a matrix

Ways to use numericalNullity :
==============================

  * "numericalNullity(List,Boolean)"
  * "numericalNullity(Matrix)"
  * "numericalNullity(Matrix,Boolean)"

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

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

numericalSourceSample -- samples a general point on a variety
*************************************************************

Synopsis
========

  * Usage:
        numericalSourceSample(I, W, s)
        numericalSourceSample(I, p, s)
        numericalSourceSample(I, W)
        numericalSourceSample(I, p)
        numericalSourceSample(I, s)
        numericalSourceSample(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), which is prime, specifying a
        variety $V(I)$
      * W, a witness set (NAGtypes), a witness set for $V(I)$
      * p, a point (NAGtypes), a point on the source $V(I)$
      * s, an integer (Macaulay2Doc), the number of points to sample
        on the source $V(I)$
  * Optional inputs (Macaulay2Doc),:
      * Software,
        => ..., default value M2engine, specify software for homotopy
        continuation
  * Outputs:
      * a list (Macaulay2Doc), of sample points on the source
        $V(I)$
  * Consequences:
      * If $I$ is not the zero ideal, and a sampling function is not specified
        via Software, then a numerical irreducible decomposition of $I$ is
        performed, and cached under I.cache.WitnessSet.

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

This method computes a list of sample points on a variety numerically. If $I$
is the zero ideal in a polynomial ring of dimension $n$, then an $n$-tuple of
random elements in the ground field is returned. Otherwise, a numerical irreducible decomposition (NumericalAlgebraicGeometry),
of
$I$ is computed, which is then used to sample points.

If the number of points $s$ is unspecified, then it is assumed that $s = 1$.

One can provide a witness set for $V(I)$ if a witness set is already known.

In the example below, we sample a point from $A^3$ and then $3$ points from
$V(x^2 + y^2 + z^2 - 1)$ in $A^3$.

+-----------------------------------------------------------------------------+
|i1 : R = CC[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i2 : samp = numericalSourceSample(ideal 0_R)                                 |
|                                                                             |
|o2 = {{.892712+.673395*ii, .29398+.632944*ii, .025888+.714827*ii}}           |
|                                                                             |
|o2 : List                                                                    |
+-----------------------------------------------------------------------------+
|i3 : samp#0                                                                  |
|                                                                             |
|o3 = {.892712+.673395*ii, .29398+.632944*ii, .025888+.714827*ii}             |
|                                                                             |
|o3 : Point                                                                   |
+-----------------------------------------------------------------------------+
|i4 : I = ideal(x^2 + y^2 + z^2 - 1);                                         |
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i5 : numericalSourceSample(I, 3)                                             |
|                                                                             |
|o5 = {{.0639312+.363095*ii, .349078+.480802*ii, -1.12512+.169804*ii},        |
|     ------------------------------------------------------------------------|
|     {1.824+.510044*ii, -.745985+1.12127*ii, -.080127+1.17155*ii},           |
|     ------------------------------------------------------------------------|
|     {.904524-.892533*ii, 1.19581+.66524*ii, .0902927+.13085*ii}}            |
|                                                                             |
|o5 : List                                                                    |
+-----------------------------------------------------------------------------+

As of version 2.2.0 (Nov 2020), it is also possible to specify a custom
sampling function: namely, one can specify the value of the option Software to
be a function (Macaulay2Doc), which takes in the ideal
$I$ and returns a point.

The following example shows how to sample a point from SO(5, $\mathbb{R}$).

+-----------------------------------------------------------------------------+
|i6 : n = 5                                                                   |
|                                                                             |
|o6 = 5                                                                       |
+-----------------------------------------------------------------------------+
|i7 : R = RR[a_(1,1)..a_(n,n)]                                                |
|                                                                             |
|o7 = R                                                                       |
|                                                                             |
|o7 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i8 : A = genericMatrix(R,n,n);                                               |
|                                                                             |
|             5       5                                                       |
|o8 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i9 : I = ideal(A*transpose A - id_(R^n));                                    |
|                                                                             |
|o9 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i10 : q = first numericalSourceSample(I, Software => I -> realPoint(I,       |
|                                                                             |
|o10 = q                                                                      |
|                                                                             |
|o10 : Point                                                                  |
|-----------------------------------------------------------------------------|
|Iterations => 100))                                                          |
+-----------------------------------------------------------------------------+
|i11 : matrix pack(n, q#Coordinates)                                          |
|                                                                             |
|o11 = | -.514585 -.0590333 -.340792 .739251 .262836  |                       |
|      | .794998  -.127686  -.519368 .270682 .0930521 |                       |
|      | .218364  .714315   .3546    .47793  -.296496 |                       |
|      | .204042  -.603484  .670006  .36953  .0933285 |                       |
|      | .117732  .325223   .198658  -.12356 .908647  |                       |
|                                                                             |
|                 5          5                                                |
|o11 : Matrix RR    <--- RR                                                   |
|               53         53                                                 |
+-----------------------------------------------------------------------------+
|i12 : norm evaluate(gens I, q)                                               |
|                                                                             |
|o12 = .00000340327416159525                                                  |
|                                                                             |
|o12 : RR (of precision 53)                                                   |
+-----------------------------------------------------------------------------+

Caveat
======

Since numerical irreducible decompositions are done over CC (Macaulay2Doc),
if $I$ is not the zero ideal, then by default the output
will be a point in complex space (regardless of the ground field of the ring of
$I$).

See also
========

  * numericalImageSample -- samples general points
    on the image of a variety
  * realPoint -- samples a real point on a variety

Ways to use numericalSourceSample :
===================================

  * "numericalSourceSample(Ideal)"
  * "numericalSourceSample(Ideal,Point)"
  * "numericalSourceSample(Ideal,Thing,ZZ)"
  * "numericalSourceSample(Ideal,WitnessSet)"
  * "numericalSourceSample(Ideal,ZZ)"

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

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

PseudoWitnessSet -- the class of all pseudo-witness sets
********************************************************

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

This is a type of hash table storing the output of a pseudo-witness set
computation using monodromy, with the following keys:

  * \bf isCompletePseudoWitnessSet: whether the pseudo-witness set has passed
    the trace test, according to the trace test threshold
  * \bf degree: the number of image points found by monodromy
  * \bf map: the map $F$, of which the image is under consideration
  * \bf sourceEquations: the defining ideal $I$ of the source variety
  * \bf sourceSlice: additional equations to form a zero-dimensional system
    (only needed if the map is not finite-to-one)
  * \bf generalCombinations: additional equations to form a zero-dimensional
    system (only needed if the source ideal is not a complete intersection)
  * \bf imageSlice: the pullback under F of a general complementary-dimensional
    linear space to $F(V(I))$
  * \bf witnessPointPairs: a vertical list of 2-point sequences $(p, F(p))$,
    where $p$ lies on the source $V(I)$ and $F(p)$ lies on imageSlice
  * \bf trace: the result of the trace test applied to witnessPointPairs

For a discussion of pseudo-witness sets, see J.D. Hauenstein and A.J. Sommese,
$Witness sets of projections$, Appl. Math. Comput. 217(7) (2010), 3349-3354.

The following example demonstrates the output for the degree $3$ embedding of
$P^1$ into $P^3$, whose image is the twisted cubic.

+-----------------------------------------------------------------------------+
|i1 : R = CC[s,t];                                                            |
+-----------------------------------------------------------------------------+
|i2 : W = pseudoWitnessSet(basis(3,R), ideal 0_R, Verbose => false);          |
|-- warning: experimental computation over inexact field begun                |
|--          results not reliable (one warning given per session)             |
+-----------------------------------------------------------------------------+
|i3 : peek W                                                                  |
|                                                                             |
|o3 = PseudoWitnessSet{degree => 3                                            |
|                      generalCombinations => 0                               |
|                      imageSlice => | (.0258884+.714827ii)s3+(.89189+.231053i|
|                      isCompletePseudoWitnessSet => true                     |
|                      map => | s3 s2t st2 t3 |                               |
|                      sourceEquations => ideal 0                             |
|                      sourceSlice => 0                                       |
|                      trace => 8.09873e-12                                   |
|                      witnessPointPairs => {({-.378607-.511124*ii, .596166+1.|
|                                           {({1.18221+.736333*ii, -.445585+.4|
|                                           {({.892712+.673395*ii, .29398+.632|
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|i)s2t+(.461944+.775187ii)st2+(.909047+.314897ii)t3+2.27491+.509688ii         |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|31216*ii}, {.24246-.0862685*ii, -.578137+.076024*ii, 1.31698+.106034*        |
|23262*ii}, {-.270643+2.68814*ii, -1.11808-.413689*ii, .300672-.431649        |
|944*ii}, {-.502996+1.3046*ii, -.660011+.57085*ii, -.531085+.120643*ii        |
|-----------------------------------------------------------------------------|
|                                                                             |
|                                                                             |
|(.0741835+.808694ii)s3+(.362835+.706096ii)s2t+(.127435+.254482ii)st2+(.741046|
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                                             |
|ii, -2.86749-.860156*ii})}                                                   |
|*ii, .151012+.176283*ii})}                                                   |
|, -.327914-.0894633*ii}) }                                                   |
|-----------------------------------------------------------------------------|
|                                 }                                           |
|                                                                             |
|+.108386ii)t3+2.06657+.790512ii |                                            |
+-----------------------------------------------------------------------------+

See also
========

  * pseudoWitnessSet -- computes a pseudo-witness set
    for the image of a variety
  * numericalImageDegree -- computes the degree of
    the image of a variety

Functions and methods returning a pseudo-witness set :
======================================================

  * "pseudoWitnessSet(List,Ideal)" -- see pseudoWitnessSet,
    -- computes a pseudo-witness set for the image of a
    variety
  * "pseudoWitnessSet(List,Ideal,List,Thing)" -- see pseudoWitnessSet,
    -- computes a pseudo-witness set for the image of a
    variety
  * "pseudoWitnessSet(List,Ideal,Point)" -- see pseudoWitnessSet,
    -- computes a pseudo-witness set for the image of a
    variety
  * "pseudoWitnessSet(Matrix,Ideal)" -- see pseudoWitnessSet,
    -- computes a pseudo-witness set for the image of a
    variety
  * "pseudoWitnessSet(Matrix,Ideal,List,Thing)" -- see pseudoWitnessSet,
    -- computes a pseudo-witness set for the image of a
    variety
  * "pseudoWitnessSet(Matrix,Ideal,Point)" -- see pseudoWitnessSet,
    -- computes a pseudo-witness set for the image of a
    variety
  * "pseudoWitnessSet(RingMap,Ideal)" -- see pseudoWitnessSet,
    -- computes a pseudo-witness set for the image of a
    variety
  * "pseudoWitnessSet(RingMap,Ideal,List,Thing)" -- see pseudoWitnessSet,
    -- computes a pseudo-witness set for the image of a
    variety
  * "pseudoWitnessSet(RingMap,Ideal,Point)" -- see pseudoWitnessSet,
    -- computes a pseudo-witness set for the image of a
    variety

Methods that use a pseudo-witness set :
=======================================

  * "isOnImage(PseudoWitnessSet,Point)" -- see isOnImage, --
    tests whether a point lies on the image of a variety
  * "numericalImageDegree(PseudoWitnessSet)" -- see numericalImageDegree,
    -- computes the degree of the image of a variety
  * "net(PseudoWitnessSet)"

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

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

pseudoWitnessSet -- computes a pseudo-witness set for the image of a variety
****************************************************************************

Synopsis
========

  * Usage:
        pseudoWitnessSet(F, I)
        pseudoWitnessSet(F, I, p)
        pseudoWitnessSet(F, I, P, L)
  * Inputs:
      * F, a matrix (Macaulay2Doc), or list (Macaulay2Doc),
        or ring map (Macaulay2Doc),
        specifying a map
      * I, an ideal (Macaulay2Doc), which is prime, specifying a
        source variety $V(I)$
      * p, a point (NAGtypes), a general point on the source
        $V(I)$
      * P, a list (Macaulay2Doc), of pairs $(p, q)$ with $p$ a
        general point on the source $V(I)$, and $q = F(p)$. In this case an
        input slice $L$ must also be provided, and $q$ should additionally lie
        on $L$.
      * L, a matrix (Macaulay2Doc), representing a linear slice
        of $F(V(I))$. The format should be a row matrix, whose entries are
        linear forms in the ambient target space of $F(V(I))$. If this is
        provided then a nonempty list $P$ of point pairs must also be provided.
  * Optional inputs (Macaulay2Doc),:
      * DoRefinements => ..., default value false
      * DoTraceTest => ..., default value true
      * MaxAttempts => ..., default value 5
      * MaxPoints => ..., default value infinity
      * MaxThreads, => ..., default value 1, specifies the
        maximum number of processor threads
      * Repeats => ..., default value 3
      * Software,
        => ..., default value M2engine, specify software for homotopy
        continuation
      * Threshold => ..., default value 5
      * TraceThreshold => ..., default value .00001
      * Verbose,
        => ..., default value true, display detailed output
  * Outputs:
      * a pseudo-witness set, a pseudo-witness set for
        $F(V(I))$

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

This method computes a pseudo-witness set, for the
image of a variety, by computing the intersection of the image with a
complementary-dimensional linear slice via tracking monodromy loops with
homotopy continuation, and then applying the trace test. If the trace test
fails, only a lower bound for the degree and an incomplete pseudo-witness set
is returned. This technique circumvents the calculation of the kernel of the
associated ring map.

The method also allows the user to provide a particular linear slice $L$ of the
image. In this case a list of point pairs $(p, q)$ such that $p$ is in $V(I)$,
$q = F(p)$, and $q$ is in $L$, must be provided (to have an initial input point
to the monodromy - even if it only consists of a single such pair). The method
then applies monodromy to try to compute the entire intersection $F(V(I))\cap
L$. If no linear slice is given, then a random complementary-dimensional linear
slice will be chosen, in which case no seed is needed, as an initial point pair
will be chosen to lie on the slice.

The following example computes the degree of the Grassmannian $Gr(2,4)$ of
$P^1$'s in $P^3$, under its Pl&uuml;cker embedding in $P^5$.

+-----------------------------------------------+
|i1 : R = CC[x_(1,1)..x_(2,4)];                 |
+-----------------------------------------------+
|i2 : F = (minors(2, genericMatrix(R, 2, 4)))_*;|
+-----------------------------------------------+
|i3 : W = pseudoWitnessSet(F, ideal 0_R)        |
|Sampling point in source ...                   |
|Tracking monodromy loops ...                   |
|Points found: 2                                |
|Points found: 2                                |
|Points found: 2                                |
|Points found: 2                                |
|Running trace test ...                         |
|                                               |
|o3 = a "pseudo-witness set", indicating        |
|     the image has degree 2                    |
|                                               |
|o3 : PseudoWitnessSet                          |
+-----------------------------------------------+
|i4 : W.isCompletePseudoWitnessSet              |
|                                               |
|o4 = true                                      |
+-----------------------------------------------+
|i5 : W.degree                                  |
|                                               |
|o5 = 2                                         |
+-----------------------------------------------+

This method can also handle cases where the parameterization has positive
dimensional fibers. In the example below, we verify that the variety of $3 x 3
x 3$ tensors of border rank $<= 4$, i.e. the $4$th secant variety of $P^2 x P^2
x P^2$, has degree $9$. This is a hypersurface, with defining equation known as
Strassen's invariant, and it is also a defective secant variety (meaning its
dimension is less than expected). Here, the parametrization has $10$
dimensional fibers. For more on this example, see V. Strassen, $The asymptotic
spectrum of tensors$, J. Reine Angew. Math. 384 (1988), 102-152.

+------------------------------------------------------------------+
|i6 : R = CC[a_(0,0)..a_(3,2), b_(0,0)..b_(3,2), c_(0,0)..c_(3,2)];|
+------------------------------------------------------------------+
|i7 : F = toList apply((0,0,0)..(2,2,2), (i,j,k) ->                |
|        a_(0,i)*b_(0,j)*c_(0,k) +                                 |
|        a_(1,i)*b_(1,j)*c_(1,k) +                                 |
|        a_(2,i)*b_(2,j)*c_(2,k) +                                 |
|        a_(3,i)*b_(3,j)*c_(3,k));                                 |
+------------------------------------------------------------------+
|i8 : pseudoWitnessSet(F, ideal 0_R, Repeats => 2)                 |
|Sampling point in source ...                                      |
|Tracking monodromy loops ...                                      |
|Points found: 1                                                   |
|Points found: 2                                                   |
|Points found: 3                                                   |
|Points found: 5                                                   |
|Points found: 7                                                   |
|Points found: 9                                                   |
|Points found: 9                                                   |
|Points found: 9                                                   |
|Running trace test ...                                            |
|                                                                  |
|o8 = a pseudo-witness set, indicating                             |
|    the degree of the image is 9                                  |
|                                                                  |
|o8 : PseudoWitnessSet                                             |
+------------------------------------------------------------------+

Finally, this method has a large number of optional inputs which may be
specified by the user to fit a particular problem instance.

The option Repeats sets the maximum number of consecutive repetitive monodromy
loops when computing a pseudo-witness set. A repetitive monodromy loop is one
where no new points in the image are discovered. After this many consecutive
repetitive monodromy loops occur, the trace test is applied to determine if a
complete pseudo-witness set has been found. The default value is $3$.

The option MaxAttempts sets the maximum number of times the trace test will be
attempted when computing a pseudo-witness set. After a trace test fails, a new
slice is chosen, the previous points are tracked to the new slice, and
monodromy is performed anew. If the trace test has failed MaxAttempts many
times, an incomplete pseudo-witness set is returned. The default value is $5$.

Here is an example in which a badly chosen random seed results in a failed
trace test on the first attempt.  In later attempts, the trace test passes and
the degree of the twisted cubic is correctly computed to be $3$.

+----------------------------------------------------------------+
|i6 : setRandomSeed 10                                           |
|                                                                |
|o6 = 10                                                         |
+----------------------------------------------------------------+
|i7 : R = CC[s,t]                                                |
|                                                                |
|o7 = R                                                          |
|                                                                |
|o7 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i8 : F = basis(3, R)                                            |
|-- warning: experimental computation over inexact field begun   |
|--          results not reliable (one warning given per session)|
|                                                                |
|o8 = | s3 s2t st2 t3 |                                          |
|                                                                |
|             1       4                                          |
|o8 : Matrix R  <--- R                                           |
+----------------------------------------------------------------+
|i9 : pseudoWitnessSet(F, ideal 0_R)                             |
|Sampling point in source ...                                    |
|Tracking monodromy loops ...                                    |
|Points found: 2                                                 |
|Points found: 2                                                 |
|Points found: 2                                                 |
|Points found: 2                                                 |
|Running trace test ...                                          |
|Failed trace test! Trace: .0128189                              |
|Tracking monodromy loops ...                                    |
|Points found: 2                                                 |
|Points found: 3                                                 |
|Points found: 3                                                 |
|Points found: 3                                                 |
|Points found: 3                                                 |
|Running trace test ...                                          |
|                                                                |
|o9 = a "pseudo-witness set", indicating                         |
|     the image has degree 3                                     |
|                                                                |
|o9 : PseudoWitnessSet                                           |
+----------------------------------------------------------------+

We compare this with the native $Macaulay2$ function degree (Macaulay2Doc),
(using a symbolic Gr&ouml;bner basis
computation).

+------------------------------------------------------------------+
|i10 : degree ker map(QQ[s,t], QQ[y_0..y_3], {s^3,s^2*t,s*t^2,t^3})|
|                                                                  |
|o10 = 3                                                           |
+------------------------------------------------------------------+

The option MaxPoints sets a number of points such that if more than this number
of points is found following a monodromy loop, then the method gracefully
exits. The option is especially useful in the case that the user specifies a
linear slice $L$ (as discussed above) which is in special position with respect
to $F(V(I))$ (e.g. if $F(V(I))\cap L$ is positive-dimensional). The default
value is infinity (Macaulay2Doc).

The option DoRefinements specifies whether or not to refine solution points
found via monodromy. Refinement of points may improve their accuracy. If the
value of this option is true, then refinement occurs after every tracking
(which may increase the time for computation). The default value is
false (Macaulay2Doc).

The option DoTraceTest specifies whether or not to run the trace test. This is
useful when the user specifies a special linear slice $L$ (as in the discussion
on MaxPoints above). The default value is true (Macaulay2Doc).

The option TraceThreshold sets the threshold for a pseudo-witness set to pass
the trace test. The trace for a complete exact pseudo-witness set is $0$; large
nonzero values indicate failure (the larger the value, the worse the failure).
The default value is $1e-5$.

The option Threshold sets the threshold for determining point equality. If this
option has value $n$, then two points are considered equal iff their first $n$
significant digits agree (equivalently, in scientific notation, the exponents
and first $n$ digits of the mantissa agree). The default value is $5$.

See also
========

  * PseudoWitnessSet -- the class of all
    pseudo-witness sets
  * numericalImageDegree -- computes the degree of
    the image of a variety

Ways to use pseudoWitnessSet :
==============================

  * "pseudoWitnessSet(List,Ideal)"
  * "pseudoWitnessSet(List,Ideal,List,Thing)"
  * "pseudoWitnessSet(List,Ideal,Point)"
  * "pseudoWitnessSet(Matrix,Ideal)"
  * "pseudoWitnessSet(Matrix,Ideal,List,Thing)"
  * "pseudoWitnessSet(Matrix,Ideal,Point)"
  * "pseudoWitnessSet(RingMap,Ideal)"
  * "pseudoWitnessSet(RingMap,Ideal,List,Thing)"
  * "pseudoWitnessSet(RingMap,Ideal,Point)"

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

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

pseudoWitnessSet(...,Software=>...) -- specify software for homotopy continuation
*********************************************************************************

Synopsis
========

  * Usage:
        pseudoWitnessSet(..., Software => M2engine)
        numericalImageDegree(..., Software => M2engine)
        numericalImageSample(..., Software => M2engine)
        numericalImageDim(..., Software => M2engine)
        numericalHilbertFunction(..., Software => M2engine)
        isOnImage(..., Software => M2engine)

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

This option specifies the software used for polynomial homotopy continuation
(used for path tracking) and numerical irreducible decompositions (used for
sampling points). The default value is M2engine (native to $Macaulay2$). Other
possible values are Bertini, and PHCpack,
(only if the user has these packages installed).

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

  * Default value: M2engine (NumericalAlgebraicGeometry),
  * Function: pseudoWitnessSet, -- computes a
    pseudo-witness set for the image of a variety
  * Option key: Software (NumericalAlgebraicGeometry), --
    specify internal or external software

See also
========

  * pseudoWitnessSet -- computes a pseudo-witness set
    for the image of a variety
  * numericalImageDegree -- computes the degree of
    the image of a variety
  * numericalSourceSample -- samples a general
    point on a variety
  * numericalImageSample -- samples general points
    on the image of a variety
  * numericalImageDim -- computes the dimension of
    the image of a variety
  * numericalHilbertFunction -- computes the
    values of the Hilbert function for the image of a variety
  * isOnImage -- tests whether a point lies on the image of a
    variety

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

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

realPoint -- samples a real point on a variety
**********************************************

Synopsis
========

  * Usage:
        realPoint I
  * Inputs:
      * I, an ideal (Macaulay2Doc), specifying a source variety
        $V(I)$
  * Optional inputs (Macaulay2Doc),:
      * Initial => ..., default value "random"
      * Iterations => ..., default value 1000
      * Tolerance => ..., default value 1e-10
  * Outputs:
      * a point (NAGtypes), a sample real point on $V(I)$

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

This method samples a real point on a variety numerically, using a combination
of the Nelder-Mead simplex method (see
https://en.wikipedia.org/wiki/Nelder%E2%80%93Mead_method ) and line search (see
https://en.wikipedia.org/wiki/Line_search ) with gradient descent. This can be
much quicker than performing a numerical irreducible decomposition.

The option Tolerance specifies a requested error tolerance for the point, with
respect to the generating set of the ideal.

The option Iterations specifies an upper limit on the number of iterations to
run the approximation algorithms. If this value is too low, then the method
will return a point which may not be within the specified error tolerance.

The following example shows how to sample a point from the 4 x 5 funtf variety.

+--------------------------------------------------------------------------+
|i1 : (n,r) = (4,5)                                                        |
|                                                                          |
|o1 = (4, 5)                                                               |
|                                                                          |
|o1 : Sequence                                                             |
+--------------------------------------------------------------------------+
|i2 : R = RR[x_(1,1)..x_(n,r)]                                             |
|                                                                          |
|o2 = R                                                                    |
|                                                                          |
|o2 : PolynomialRing                                                       |
+--------------------------------------------------------------------------+
|i3 : A = transpose genericMatrix(R,r,n)                                   |
|                                                                          |
|o3 = {-1} | x_(1,1) x_(1,2) x_(1,3) x_(1,4) x_(1,5) |                     |
|     {-1} | x_(2,1) x_(2,2) x_(2,3) x_(2,4) x_(2,5) |                     |
|     {-1} | x_(3,1) x_(3,2) x_(3,3) x_(3,4) x_(3,5) |                     |
|     {-1} | x_(4,1) x_(4,2) x_(4,3) x_(4,4) x_(4,5) |                     |
|                                                                          |
|             4       5                                                    |
|o3 : Matrix R  <--- R                                                     |
+--------------------------------------------------------------------------+
|i4 : I1 = ideal(A*transpose A - (r/n)*id_(R^n));                          |
|                                                                          |
|o4 : Ideal of R                                                           |
+--------------------------------------------------------------------------+
|i5 : I2 = ideal apply(entries transpose A, row -> sum(row, v -> v^2) - 1);|
|                                                                          |
|o5 : Ideal of R                                                           |
+--------------------------------------------------------------------------+
|i6 : I = I1 + I2;                                                         |
|                                                                          |
|o6 : Ideal of R                                                           |
+--------------------------------------------------------------------------+
|i7 : elapsedTime p = realPoint(I, Iterations => 100)                      |
| -- 0.490509 seconds elapsed                                              |
|                                                                          |
|o7 = p                                                                    |
|                                                                          |
|o7 : Point                                                                |
+--------------------------------------------------------------------------+
|i8 : matrix pack(5, p#Coordinates)                                        |
|                                                                          |
|o8 = | .722359  .289465  -.295808  .591752  -.454678 |                    |
|     | -.110166 .0700102 .908882   .630235  .0984753 |                    |
|     | .621173  -.330116 -.0305848 .0539234 .866787  |                    |
|     | .283207  .895726  .292392   -.499725 .179584  |                    |
|                                                                          |
|                4          5                                              |
|o8 : Matrix RR    <--- RR                                                 |
|              53         53                                               |
+--------------------------------------------------------------------------+
|i9 : norm evaluate(gens I, p)                                             |
|                                                                          |
|o9 = .00000574047029489044                                                |
|                                                                          |
|o9 : RR (of precision 53)                                                 |
+--------------------------------------------------------------------------+

See also
========

  * numericalSourceSample -- samples a general
    point on a variety

Ways to use realPoint :
=======================

  * "realPoint(Ideal)"

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

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