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

RandomPoints -- Obtain random points in a variety
*************************************************

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

RandomPointsFind random points inside a variety.

This package provides tools for quickly finding a point (rational, or over a
field extension) in the vanishing set of an ideal.  The search is highly
customizable.  This package also includes tools for finding submatrices of a
given rank at some point.  Furthermore, it provides tools for generic
projections and producing collections of linear forms with specified
properties.
Core functions:
  * randomPoints,:  This tries to find a point in the
    vanishing set of an ideal.
  * findANonZeroMinor,:  This finds a submatrix of a
    given matrix that is nonsingular at a point of a given ideal.
  * extendIdealByNonZeroMinor,:  This extends
    an ideal by a minor produced by findANonZeroMinor.
  * projectionToHypersurface, and
    genericProjection,:  These functions provide
    customizable projection.

Acknowledgements:

The authors would like to thank David Eisenbud and Mike Stillman for useful
conversations and comments on the development of this package.  The authors
began work on this package at the virtual Cleveland 2020 Macaulay2 workshop.

Authors
=======

  * Sankhaneel Bisui (see https://sites.google.com/view/sankhaneelbisui/home )
    <sbisu@tulane.edu>
  * Zhan Jiang (see http://www-personal.umich.edu/~zoeng/ ) <zoeng@umich.edu>
  * Sarasij Maitra (see https://sarasij93.github.io/ ) <sm3vg@virginia.edu>
  * Thai Nguyen (see https://sites.google.com/view/thainguyenmath  )
    <tnguyen11@tulane.edu>
  * Frank-Olaf Schreyer (see https://www.math.uni-sb.de/ag/schreyer/index.php/
    ) <schreyer@math.uni-sb.de>
  * Karl Schwede (see https://www.math.utah.edu/~schwede/ )
    <schwede@math.utah.edu>

Version
=======

This documentation describes version 1.5.2 of RandomPoints.

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

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

Exports
=======

  * Functions and commands
      * dimViaBezout -- computes the dimension of the
        given ideal $I$ probabilistically
      * extendIdealByNonZeroMinor -- extends
        the ideal to aid finding singular locus
      * findANonZeroMinor -- finds a non-vanishing
        minor at some randomly chosen point
      * genericProjection -- finds a random
        (somewhat) generic projection of the ring or ideal
      * getRandomLinearForms -- retrieve a list of
        random degree 1 and 0 forms of specified types
      * projectionToHypersurface -- Generic
        projection to a hypersurface
      * randomCoordinateChange -- produce linear
        automorphism of the ring
      * randomPoints -- a function to find random points
        in a variety.
  * Methods
      * "dimViaBezout(Ideal)" -- see dimViaBezout, --
        computes the dimension of the given ideal $I$ probabilistically
      * "extendIdealByNonZeroMinor(ZZ,Matrix,Ideal)" -- see
        extendIdealByNonZeroMinor, -- extends the
        ideal to aid finding singular locus
      * "findANonZeroMinor(ZZ,Matrix,Ideal)" -- see findANonZeroMinor,
        -- finds a non-vanishing minor at some randomly
        chosen point
      * "genericProjection(Ideal)" -- see genericProjection,
        -- finds a random (somewhat) generic projection of
        the ring or ideal
      * "genericProjection(Ring)" -- see genericProjection,
        -- finds a random (somewhat) generic projection of
        the ring or ideal
      * "genericProjection(ZZ,Ideal)" -- see genericProjection,
        -- finds a random (somewhat) generic projection of
        the ring or ideal
      * "genericProjection(ZZ,Ring)" -- see genericProjection,
        -- finds a random (somewhat) generic projection of
        the ring or ideal
      * "getRandomLinearForms(Ring,List)" -- see getRandomLinearForms,
        -- retrieve a list of random degree 1 and 0 forms
        of specified types
      * "projectionToHypersurface(Ideal)" -- see
        projectionToHypersurface, -- Generic
        projection to a hypersurface
      * "projectionToHypersurface(Ring)" -- see projectionToHypersurface,
        -- Generic projection to a hypersurface
      * "randomCoordinateChange(Ring)" -- see randomCoordinateChange,
        -- produce linear automorphism of the ring
      * "randomPoints(Ideal)" -- see randomPoints, -- a
        function to find random points  in a variety.
      * "randomPoints(ZZ,Ideal)" -- see randomPoints, -- a
        function to find random points  in a variety.
  * Symbols
      * DecompositionStrategy -- control how
        ideals of points are factored into minimal primes
      * DimensionFunction -- an option for specifying
        custom dimension functions
      * "DimensionIntersectionAttempts" -- see dimViaBezout,
        -- computes the dimension of the given ideal $I$
        probabilistically
      * "MinimumFieldSize" -- see dimViaBezout, -- computes
        the dimension of the given ideal $I$ probabilistically
      * ExtendField -- an option used to specify if
        extending the finite field is permissible here
      * "MinorPointAttempts" -- see findANonZeroMinor,
        -- finds a non-vanishing minor at some randomly chosen point
      * MaxCoordinatesToReplace -- The maximum
        number of coordinates to turn into non-monomial functions when calling
        {\tt randomCoordinateChange}
      * NumThreadsToUse -- number of threads that the
        function will use in a brute force search for a point
      * PointCheckAttempts -- Number of times that
        the function will search for a point
      * "Codimension" -- see projectionToHypersurface,
        -- Generic projection to a hypersurface
      * "BruteForce" -- see randomPoints(...,Strategy=>...),
        -- values for the
        option Strategy when calling randomPoints
      * "LinearIntersection" -- see randomPoints(...,Strategy=>...),
        -- values for the
        option Strategy when calling randomPoints
      * "MultiplicationTable" -- see randomPoints(...,Strategy=>...),
        -- values for the
        option Strategy when calling randomPoints
      * "Full" -- see Replacement, -- When changing
        coordinates, whether to replace variables by general degree 1 forms,
        binomials, etc.
      * Replacement -- When changing coordinates, whether
        to replace variables by general degree 1 forms, binomials, etc.
      * "Trinomial" -- see Replacement, -- When changing
        coordinates, whether to replace variables by general degree 1 forms,
        binomials, etc.

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

The object RandomPoints, is a package (Macaulay2Doc).

DecompositionStrategy -- control how ideals of points are factored into minimal primes
**************************************************************************************

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

In many cases using a multiplication table (ie, computing how a variable acts
on residue fields of points in two different ways) can be used to more quickly
decompose ideals.  This is turned on by setting DecompositionStrategy =>
MultiplicationTable.  However, in other cases, especially when there are many
variables, using DecompositionStrategy => Decompose can be substantially
faster.  Currently MultiplicationTable only works with homogeneous ideals and
will not find geometric points.

Functions with optional argument named DecompositionStrategy :
==============================================================

  * "extendIdealByNonZeroMinor(...,DecompositionStrategy=>...)"
  * "findANonZeroMinor(...,DecompositionStrategy=>...)"
  * "randomPoints(...,DecompositionStrategy=>...)"

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

The object DecompositionStrategy, is a
symbol (Macaulay2Doc).

DimensionFunction -- an option for specifying custom dimension functions
************************************************************************

Synopsis
========

  * Usage:
        DimensionFunction => myFunction

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

This package provides a custom dimension function for probabilistically
computing the dimension, dimViaBezout.  However, in some cases this can be
substantially slower than calling the built in function dim.  Thus the user may
switch to using the built in function, or their own custom dimension function,
via the option DimensionFunction => ....

See also
========

  * dim (Macaulay2Doc) -- compute the Krull dimension
  * dimViaBezout -- computes the dimension of the given
    ideal $I$ probabilistically

Functions with optional argument named DimensionFunction :
==========================================================

  * "extendIdealByNonZeroMinor(...,DimensionFunction=>...)" -- see
    extendIdealByNonZeroMinor, -- extends the ideal
    to aid finding singular locus
  * "findANonZeroMinor(...,DimensionFunction=>...)" -- see
    findANonZeroMinor, -- finds a non-vanishing minor at
    some randomly chosen point
  * "randomPoints(...,DimensionFunction=>...)" -- see randomPoints,
    -- a function to find random points  in a variety.

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

The object DimensionFunction, is a symbol (Macaulay2Doc).

dimViaBezout -- computes the dimension of the given ideal $I$ probabilistically
*******************************************************************************

Synopsis
========

  * Usage:
        dimViaBezout(I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), in a polynomial ring over a
        field
  * Optional inputs (Macaulay2Doc),:
      * DimensionIntersectionAttempts => an integer (Macaulay2Doc),
        default value null, the number of linear spaces to try before moving to
        the next dimension
      * MinimumFieldSize => an integer (Macaulay2Doc), default value
        null, if the ambient field is smaller than this value it will
        automatically be replaced with an extension
      * Homogeneous => ..., default value true
      * Replacement, => ..., default value Full, When
        changing coordinates, whether to replace variables by general degree 1
        forms, binomials, etc.
      * Verbose => ..., default value false
  * Outputs:
      * an integer (Macaulay2Doc), d = dimension of the ideal $I$

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

This intersects $V(I)$ with successively higher dimensional random linear
spaces until there is an intersection.  For example, if $V(I)$ intersect a
random line has a point, then we expect that $V(I)$ contains a hypersurface.
If there was no intersection, this function tries a 2-dimensional linear space,
and so on.  This greatly speeds up some computations, although in other
examples, the built in dim function is much faster.

+---------------------------------------------------------------+
|i1 : kk=ZZ/101;                                                |
+---------------------------------------------------------------+
|i2 : S=kk[y_0..y_8];                                           |
+---------------------------------------------------------------+
|i3 : I=ideal random(S^1,S^{-2,-2,-2,-2})+(ideal random(2,S))^2;|
|                                                               |
|o3 : Ideal of S                                                |
+---------------------------------------------------------------+
|i4 : elapsedTime dimViaBezout(I)                               |
| -- 4.50868 seconds elapsed                                    |
|                                                               |
|o4 = 4                                                         |
+---------------------------------------------------------------+
|i5 : elapsedTime dim I                                         |
| -- 14.5747 seconds elapsed                                    |
|                                                               |
|o5 = 4                                                         |
+---------------------------------------------------------------+

The user may set the MinimumFieldSize to ensure that the field being worked
over is big enough.  For instance, there are relatively few linear spaces over
a field of characteristic 2, and this can cause incorrect results to be
provided.  If no size is provided, the function tries to guess a good size
based on ambient ring.

If the option Homogeneous=>true then we use homogeneous linear spaces if the
ideal itself is homogeneous.  Otherwise our linear spaces are not homogeneous.

The user may also specify what sort of linear forms to intersect with via the
Replacement, option.

See also
========

  * DimensionFunction -- an option for specifying
    custom dimension functions

Ways to use dimViaBezout :
==========================

  * "dimViaBezout(Ideal)"

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

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

ExtendField -- an option used to specify if extending the finite field is permissible here
******************************************************************************************

Synopsis
========

  * Usage:
        ExtendField => b
  * Inputs:
      * b, a Boolean value (Macaulay2Doc), whether the base
        field is allowed to be extended

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

Various functions which produce points, or call functions which produce points,
may naturally find scheme theoretic points that are not rational over the base
field (for example, by intersecting with a random linear space).  Setting
ExtendField => true will tell the function that such points are valid.  Setting
ExtendField => false will tell the function ignore such points.  This sometimes
can slow computation, and other times can speed it up.  In some cases, points
over extended fields may also have better randomness properties for
applications.

See also
========

  * randomPoints -- a function to find random points  in a
    variety.
  * findANonZeroMinor -- finds a non-vanishing minor
    at some randomly chosen point
  * extendIdealByNonZeroMinor -- extends the
    ideal to aid finding singular locus

Functions with optional argument named ExtendField :
====================================================

  * "extendIdealByNonZeroMinor(...,ExtendField=>...)"
  * "findANonZeroMinor(...,ExtendField=>...)"
  * "randomPoints(...,ExtendField=>...)"

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

The object ExtendField, is a symbol (Macaulay2Doc).

extendIdealByNonZeroMinor -- extends the ideal to aid finding singular locus
****************************************************************************

Synopsis
========

  * Usage:
        extendIdealByNonZeroMinor(n,M,I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), in a polynomial ring over QQ
        or ZZ/p for p prime
      * M, a matrix (Macaulay2Doc), over the polynomial ring
      * n, an integer (Macaulay2Doc), the size of the minors to
        consider
  * Optional inputs (Macaulay2Doc),:
      * Strategy, => a
        symbol (Macaulay2Doc), default value Default, specify
        which strategy to use when calling randomPoints,
      * Homogeneous => a Boolean value (Macaulay2Doc), default
        value false, controls if the computations are homogeneous (in calls to
        randomPoints)
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, turns on or off verbose output
      * MinorPointAttempts => an integer (Macaulay2Doc), default
        value 5, how many points to check the rank of the matrix at
      * DimensionFunction => a function (Macaulay2Doc), default
        value dim, specify a custom dimension function, such as the default
        dimViaBezout or the Macaulay2 function dim
      * DecompositionStrategy, => ..., default
        value null, control how ideals of points are factored into minimal
        primes
      * ExtendField, => ..., default value true, an option
        used to specify if extending the finite field is permissible here
      * NumThreadsToUse, => ..., default value 1, number
        of threads that the function will use in a brute force search for a
        point
      * PointCheckAttempts, => ..., default value 0,
        Number of times that the function will search for a point
      * Replacement, => ..., default value Binomial, When
        changing coordinates, whether to replace variables by general degree 1
        forms, binomials, etc.
  * Outputs:
      * an ideal (Macaulay2Doc), the original ideal extended by
        the determinant of the non vanishing minor found

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

This function finds a submatrix of size $n\times n$ using findANonZeroMinor; it
extracts the last entry of the output, finds its determinant and adds it to the
ideal $I$, thus extending $I$.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/5[x,y,z];                                                        |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(random(3,R)-2, random(2,R));                                  |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : M = jacobian(I);                                                        |
|                                                                             |
|             3       2                                                       |
|o3 : Matrix R  <--- R                                                        |
+-----------------------------------------------------------------------------+
|i4 : extendIdealByNonZeroMinor(2,M,I, Strategy => LinearIntersection)        |
|                                                                             |
|                3       2     3    2     2        2       2     3            |
|o4 = ideal (- 2x  - 2x*y  - 2y  + x z - y z + 2x*z  - 2y*z  - 2z  - 2, - 2x*z|
|     ------------------------------------------------------------------------|
|                2    3     2       2    3     2             2       2      2 |
|     + 2y*z - 2z , 2x  - 2x y - x*y  + y  + 2x z - x*y*z + y z + x*z  + y*z )|
|                                                                             |
|o4 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+

One use for this function can be in showing a certain rings are R1 (regular in
codimension 1).  Consider the following example which is R1 where computing the
dimension of the singular locus takes around 30 seconds as there are 15500
minors of size $4 \times 4$ in the associated $7 \times 12$ Jacobian matrix.
However, we can use this function to quickly find interesting minors.

+-----------------------------------------------------------------------------+
|i5 : T = ZZ/101[x1,x2,x3,x4,x5,x6,x7];                                       |
+-----------------------------------------------------------------------------+
|i6 : I =  ideal(x5*x6-x4*x7,x1*x6-x2*x7,x5^2-x1*x7,x4*x5-x2*x7,x4^2-x2*x6,x1*|
|                                                                             |
|o6 : Ideal of T                                                              |
|-----------------------------------------------------------------------------|
|x4-x2*x5,x2*x3^3*x5+3*x2*x3^2*x7+8*x2^2*x5+3*x3*x4*x7-8*x4*x7+x6*x7,x1*x3^3* |
|-----------------------------------------------------------------------------|
|x5+3*x1*x3^2*x7+8*x1*x2*x5+3*x3*x5*x7-8*x5*x7+x7^2,x2*x3^3*x4+3*x2*x3^2*x6+8*|
|-----------------------------------------------------------------------------|
|x2^2*x4+3*x3*x4*x6-8*x4*x6+x6^2,x2^2*x3^3+3*x2*x3^2*x4+8*x2^3+3*x2*x3*x6-8*x2|
|-----------------------------------------------------------------------------|
|*x6+x4*x6,x1*x2*x3^3+3*x2*x3^2*x5+8*x1*x2^2+3*x2*x3*x7-8*x2*x7+x4*x7,x1^2*x3^|
|-----------------------------------------------------------------------------|
|3+3*x1*x3^2*x5+8*x1^2*x2+3*x1*x3*x7-8*x1*x7+x5*x7);                          |
+-----------------------------------------------------------------------------+
|i7 : M = jacobian I;                                                         |
|                                                                             |
|             7       12                                                      |
|o7 : Matrix T  <--- T                                                        |
+-----------------------------------------------------------------------------+
|i8 : i = 0;                                                                  |
+-----------------------------------------------------------------------------+
|i9 : J = I;                                                                  |
|                                                                             |
|o9 : Ideal of T                                                              |
+-----------------------------------------------------------------------------+
|i10 : elapsedTime(while (i < 10) and dim J > 1 do (i = i+1; J =              |
| -- 5.58081 seconds elapsed                                                  |
|-----------------------------------------------------------------------------|
|extendIdealByNonZeroMinor(4, M, J)) );                                       |
+-----------------------------------------------------------------------------+
|i11 : dim J                                                                  |
|                                                                             |
|o11 = 1                                                                      |
+-----------------------------------------------------------------------------+
|i12 : i                                                                      |
|                                                                             |
|o12 = 5                                                                      |
+-----------------------------------------------------------------------------+

In this particular example, there tend to be about 5 associated primes when
adding the first minor to J, and so one would expect about 5 steps as each
minor computed most likely will eliminate one of those primes.

There is some similar functionality obtained via heuristics (as opposed to
actually finding rational points) in the package "FastMinors".

See also
========

  * findANonZeroMinor -- finds a non-vanishing minor
    at some randomly chosen point

Ways to use extendIdealByNonZeroMinor :
=======================================

  * "extendIdealByNonZeroMinor(ZZ,Matrix,Ideal)"

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

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

findANonZeroMinor -- finds a non-vanishing minor at some randomly chosen point
******************************************************************************

Synopsis
========

  * Usage:
        findANonZeroMinor(n,M,I)
  * Inputs:
      * I, an ideal (Macaulay2Doc), in a polynomial ring over QQ
        or ZZ/p for p prime
      * M, a matrix (Macaulay2Doc), over the polynomial ring
      * n, an integer (Macaulay2Doc), the size of the minors to
        consider
  * Optional inputs (Macaulay2Doc),:
      * Strategy, => a
        symbol (Macaulay2Doc), default value Default, to specify
        which strategy to use when calling randomPoints,
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, set to true for verbose output
      * Homogeneous => a Boolean value (Macaulay2Doc), default
        value false, controls if the computations are homogeneous (in calls to
        randomPoints)
      * MinorPointAttempts => an integer (Macaulay2Doc), default
        value 5, how many points to check the rank of the matrix at
      * DimensionFunction => a function (Macaulay2Doc), default
        value dim, specify a custom dimension function, such as the default
        dimViaBezout or the Macaulay2 function dim
      * DecompositionStrategy, => ..., default
        value null, control how ideals of points are factored into minimal
        primes
      * ExtendField, => ..., default value true, an option
        used to specify if extending the finite field is permissible here
      * NumThreadsToUse, => ..., default value 1, number
        of threads that the function will use in a brute force search for a
        point
      * PointCheckAttempts, => ..., default value 0,
        Number of times that the function will search for a point
      * Replacement, => ..., default value Binomial, When
        changing coordinates, whether to replace variables by general degree 1
        forms, binomials, etc.
  * Outputs:
      * a sequence (Macaulay2Doc), The functions outputs the
        following:  1. randomly chosen point $P$ in $V(I)$,  2. the indexes of
        the columns of $M$ that stay linearly independent upon plugging $P$
        into $M$,  3. the indices of the linearly independent rows of the
        matrix extracted from $M$ using (2),  4. a random $n\times n$ submatrix
        of $M$ that has full rank at $P$.

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

Given an ideal, a matrix, an integer and a user defined Strategy, this function
uses the randomPoints function to find a point in $V(I)$. Then it plugs the
point in the matrix and tries to find a non-zero  minor of size equal to the
given integer. It outputs the point and also one of the submatrices of interest
along with the column and row indices that were used sequentially.

+--------------------------------------------------------------+
|i1 : R = ZZ/5[x,y,z];                                         |
+--------------------------------------------------------------+
|i2 : I = ideal(random(3,R)-2, random(2,R));                   |
|                                                              |
|o2 : Ideal of R                                               |
+--------------------------------------------------------------+
|i3 : M = jacobian(I);                                         |
|                                                              |
|             3       2                                        |
|o3 : Matrix R  <--- R                                         |
+--------------------------------------------------------------+
|i4 : findANonZeroMinor(2,M,I)                                 |
|                                                              |
|o4 = ({-2, 0, 2}, {0, 1}, {0, 1}, {1} | -2z -x2-2y2+2xz+2z2 |)|
|                                  {1} | 2z  xy-y2-2yz-2z2   | |
|                                                              |
|o4 : Sequence                                                 |
+--------------------------------------------------------------+

The option MinorPointAttempts is how many points to attempt before giving up.

See also
========

  * randomPoints -- a function to find random points  in a
    variety.

Ways to use findANonZeroMinor :
===============================

  * "findANonZeroMinor(ZZ,Matrix,Ideal)"

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

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

genericProjection -- finds a random (somewhat) generic projection of the ring or ideal
**************************************************************************************

Synopsis
========

  * Usage:
        genericProjection(n, I)
        genericProjection(n, R)
        genericProjection(I)
        genericProjection(R)
  * Inputs:
      * I, an ideal (Macaulay2Doc), in a polynomial ring
      * R, a ring (Macaulay2Doc), a quotient of a polynomial ring
      * n, an integer (Macaulay2Doc), an integer specifying how many
        dimensions to drop
  * Optional inputs (Macaulay2Doc),:
      * MaxCoordinatesToReplace, => an
        integer (Macaulay2Doc), default value infinity, to be passed to
        randomCoordinateChange
      * Replacement, => a symbol (Macaulay2Doc),
        default value Full, to be passed to
        randomCoordinateChange
      * Homogeneous => a Boolean value (Macaulay2Doc), default
        value true, to be passed to randomCoordinateChange
      * Verbose,
        => ..., default value false, turns out Verbose (debugging) output
  * Outputs:
      * a list (Macaulay2Doc), a list with two entries, the generic
        projection map, and the ideal if I was provided, or the ring if R was
        provided

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

This gives the projection map from $\mathbb{A}^N \mapsto\mathbb{A}^{N-n}$ and
the defining ideal of the projection of $V(I)$

+-----------------------------------------------------------------------------+
|i1 : R=ZZ/5[x,y,z,w];                                                        |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(x,y^2,w^3+x^2);                                               |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : genericProjection(2,I)                                                  |
|                                                                             |
|              ZZ                                                 4    3      |
|o3 = (map (R, --[z, w], {- 2x + 2z - 2w, - x - 2y - 2z}), ideal(z  - z w +   |
|               5                                                             |
|     ------------------------------------------------------------------------|
|      2 2      3    4                                                        |
|     z w  - z*w  + w ))                                                      |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+

If no integer $n$ is provided, then drops one dimension, in other words it
treats $n = 1$.

+-----------------------------------------------------------------------------+
|i4 : R=ZZ/5[x,y,z,w];                                                        |
+-----------------------------------------------------------------------------+
|i5 : I = ideal(x,y^2);                                                       |
|                                                                             |
|o5 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i6 : genericProjection(I)                                                    |
|                                                                             |
|              ZZ                                                             |
|o6 = (map (R, --[y..z, w], {- 2x + 2z + w, - 2x + 2z - 2w, - 2x + y + 2z}),  |
|               5                                                             |
|     ------------------------------------------------------------------------|
|            2          2                 2                                   |
|     ideal(y  + y*z - z  + 2y*w + z*w + w ))                                 |
|                                                                             |
|o6 : Sequence                                                                |
+-----------------------------------------------------------------------------+

Alternately, instead of I, you may pass it a quotient ring.  It will then
return the inclusion of the generic projection ring into the given ring,
followed by the source of that inclusion.  It is essentially the same
functionality as calling genericProjection(n, ideal R) although the format of
the output is slightly different.

+-----------------------------------------------------------------------------+
|i7 : R = ZZ/13[x,y,z];                                                       |
+-----------------------------------------------------------------------------+
|i8 : I = ideal(y^2*z-x*(x-z)*(x+z));                                         |
|                                                                             |
|o8 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i9 : genericProjection(R/I)                                                  |
|                                                                             |
|                   R          ZZ                                             |
|o9 = (map (-----------------, --[y..z], {3x + 5y + 6z, 3x + 5y - 6z}),       |
|              3    2       2  13                                             |
|           - x  + y z + x*z                                                  |
|     ------------------------------------------------------------------------|
|     ZZ                                                                      |
|     --[y..z])                                                               |
|     13                                                                      |
|                                                                             |
|o9 : Sequence                                                                |
+-----------------------------------------------------------------------------+

This method works by calling randomCoordinateChange before dropping some
variables.  It passes the options Replacement, MaxCoordinatesToReplace,
Homogeneous to that function.

This function makes no attempt to verify that the projection is actually
generic with respect to the ideal.

See also
========

  * randomCoordinateChange -- produce linear
    automorphism of the ring

Ways to use genericProjection :
===============================

  * "genericProjection(Ideal)"
  * "genericProjection(Ring)"
  * "genericProjection(ZZ,Ideal)"
  * "genericProjection(ZZ,Ring)"

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

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

genericProjection(...,Verbose=>...) -- turns out Verbose (debugging) output
***************************************************************************

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

Set the option Verbose => true to turn on verbose output.  This may be useful
in debugging or in determining why an computation is running slowly.

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

  * Default value: false (Macaulay2Doc),
  * Function: genericProjection, -- finds a random
    (somewhat) generic projection of the ring or ideal
  * Option key: Verbose (Macaulay2Doc), -- request verbose
    feedback

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

  * "check(...,Verbose=>...)" -- see check (Macaulay2Doc), --
    perform tests of a package
  * "checkDegrees(...,Verbose=>...)" -- see checkDegrees (Isomorphism),
    -- compares the degrees of generators of two
    modules
  * "copyDirectory(...,Verbose=>...)" -- see
    copyDirectory(String,String) (Macaulay2Doc),
  * "copyFile(...,Verbose=>...)" -- see copyFile(String,String) (Macaulay2Doc),
  * "dimViaBezout(...,Verbose=>...)" -- see dimViaBezout,
    -- computes the dimension of the given ideal $I$ probabilistically
  * "extendIdealByNonZeroMinor(...,Verbose=>...)" -- see
    extendIdealByNonZeroMinor, -- extends the ideal
    to aid finding singular locus
  * "findANonZeroMinor(...,Verbose=>...)" -- see findANonZeroMinor,
    -- finds a non-vanishing minor at some randomly chosen
    point
  * "findProgram(...,Verbose=>...)" -- see findProgram (Macaulay2Doc),
    -- load external program
  * genericProjection(...,Verbose=>...)
    -- turns out Verbose
    (debugging) output
  * "projectionToHypersurface(...,Verbose=>...)"
  * "randomCoordinateChange(...,Verbose=>...)"
  * "randomPoints(...,Verbose=>...)"
  * "getRandomLinearForms(...,Verbose=>...)" -- see getRandomLinearForms,
    -- retrieve a list of random degree 1 and 0 forms of
    specified types
  * "installPackage(...,Verbose=>...)" -- see installPackage (Macaulay2Doc),
    -- load and install a package and its
    documentation
  * "isIsomorphic(...,Verbose=>...)" -- see isIsomorphic (Isomorphism),
    -- Probabilistic test for isomorphism of modules
  * "moveFile(...,Verbose=>...)" -- see moveFile(String,String) (Macaulay2Doc),
  * "runProgram(...,Verbose=>...)" -- see runProgram (Macaulay2Doc),
    -- run an external program
  * "symlinkDirectory(...,Verbose=>...)" -- see
    symlinkDirectory(String,String) (Macaulay2Doc),
    -- make symbolic links
    for all files in a directory tree

getRandomLinearForms -- retrieve a list of random degree 1 and 0 forms of specified types
*****************************************************************************************

Synopsis
========

  * Usage:
        getRandomLinearForms(R, L)
  * Inputs:
      * R, a ring (Macaulay2Doc), the ring where the forms should
        live
      * L, a list (Macaulay2Doc), a list with 6 entries, each a
        number of types of forms.  Constant forms, monomial forms (plus a
        constant term if Homogeneous => false), monomial forms, binomial forms,
        trinomial forms, and random forms.
  * Optional inputs (Macaulay2Doc),:
      * Verify => a Boolean value (Macaulay2Doc), default value
        false, whether to check if the output linear forms have Jacobian of
        maximal rank
      * Verbose => a Boolean value (Macaulay2Doc), default value
        false, turn on or off verbose output
      * Homogeneous => a Boolean value (Macaulay2Doc), default
        value false, allows constant terms on some linear forms if true
  * Outputs:
      * a list (Macaulay2Doc), a list of random forms of the
        specified types

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

This will give you a list of random forms (ring elements) of the specified
types.  This is useful, because in many cases, for instance when doing generic
projection, you only need a a certain number of the forms in the map to be
fully random.  Furthermore, at the cost of some randomness, using monomial or
binomial forms can be much faster.

The types of form are specified via the second argument, a list with 5 entries.
The first entry is how many constant forms are allowed.

+-------------------------------------------+
|i1 : R = ZZ/31[a,b,c]                      |
|                                           |
|o1 = R                                     |
|                                           |
|o1 : PolynomialRing                        |
+-------------------------------------------+
|i2 : getRandomLinearForms(R, {2,0,0,0,0,0})|
|                                           |
|o2 = {1, -12}                              |
|                                           |
|o2 : List                                  |
+-------------------------------------------+

The second entry in the list is how many monomial forms are returned.  Note if
Homogeneous=>false then these forms will usually have constant terms.

+---------------------------------------------------------------+
|i3 : getRandomLinearForms(R, {0,2,0,0,0,0}, Homogeneous=>true) |
|                                                               |
|o3 = {a, a}                                                    |
|                                                               |
|o3 : List                                                      |
+---------------------------------------------------------------+
|i4 : getRandomLinearForms(R, {0,2,0,0,0,0}, Homogeneous=>false)|
|                                                               |
|o4 = {b + 13, a + 7}                                           |
|                                                               |
|o4 : List                                                      |
+---------------------------------------------------------------+

Next, the third entry is how many monomial forms (without constant terms, even
if Homogeneous=>false).

+---------------------------------------------------------------+
|i5 : getRandomLinearForms(R, {0,0,2,0,0,0}, Homogeneous=>false)|
|                                                               |
|o5 = {c, c}                                                    |
|                                                               |
|o5 : List                                                      |
+---------------------------------------------------------------+

The fourth entry is how many binomial forms should be returned.

+---------------------------------------------------------------+
|i6 : getRandomLinearForms(R, {0,0,0,1,0,0}, Homogeneous=>true) |
|                                                               |
|o6 = {b - 12c}                                                 |
|                                                               |
|o6 : List                                                      |
+---------------------------------------------------------------+
|i7 : getRandomLinearForms(R, {0,0,0,1,0,0}, Homogeneous=>false)|
|                                                               |
|o7 = {- 14c + 2}                                               |
|                                                               |
|o7 : List                                                      |
+---------------------------------------------------------------+

The ultimate entry is how many truly random forms to produce.

+---------------------------------------------------------------+
|i8 : getRandomLinearForms(R, {0,0,0,0,0,1}, Homogeneous=>true) |
|                                                               |
|o8 = {13a + 14b + 3c}                                          |
|                                                               |
|o8 : List                                                      |
+---------------------------------------------------------------+
|i9 : getRandomLinearForms(R, {0,0,0,0,0,1}, Homogeneous=>false)|
|                                                               |
|o9 = {- 12a - 10b + 7c + 15}                                   |
|                                                               |
|o9 : List                                                      |
+---------------------------------------------------------------+

You may combine the different specifications to create a list of the desired
type.  The order is randomized.

If the option Verify=>true, then this will check the jacobian of the list of
forms (discounting the constant forms), to make sure it has maximal rank.
Random forms in small numbers of variables over small fields will produce
non-injective ring maps occasionally otherwise.

Ways to use getRandomLinearForms :
==================================

  * "getRandomLinearForms(Ring,List)"

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

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

MaxCoordinatesToReplace -- The maximum number of coordinates to turn into non-monomial functions when calling {\tt randomCoordinateChange}
******************************************************************************************************************************************

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

When calling randomCoordinateChange, the user can specify that only a specified
number of coordinates should be non-monomial.  Sometimes, generic coordinate
changes where all coordinates are modified, can be very slow.  This is a way to
mitigate for that. This option is passed to randomCoordinateChange by other
functions that call it.

+-----------------------------------------------------------------------------+
|i1 : S = ZZ/11[a..e]                                                         |
|                                                                             |
|o1 = S                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : randomCoordinateChange(S, MaxCoordinatesToReplace=>2)                   |
|                                                                             |
|             ZZ                                                              |
|o2 = map (S, --[a..e], {d, a, - 4a - 3b - c + 3d + 3e, - 4a - 3b - 3c + 5d - |
|             11                                                              |
|                                                                             |
|                    ZZ                                                       |
|o2 : RingMap S <--- --[a..e]                                                 |
|                    11                                                       |
|-----------------------------------------------------------------------------|
|4e, c})                                                                      |
+-----------------------------------------------------------------------------+

See also
========

  * randomCoordinateChange -- produce linear
    automorphism of the ring

Functions with optional argument named MaxCoordinatesToReplace :
================================================================

  * "genericProjection(...,MaxCoordinatesToReplace=>...)"
  * "projectionToHypersurface(...,MaxCoordinatesToReplace=>...)"
  * "randomCoordinateChange(...,MaxCoordinatesToReplace=>...)"

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

The object MaxCoordinatesToReplace, is a
symbol (Macaulay2Doc).

NumThreadsToUse -- number of threads that the function will use in a brute force search for a point
***************************************************************************************************

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

When calling randomPoints, and functions that call it, with a BruteForce
strategy, this denotes the number of threads to use in brute force point
checking.

Caveat
======

Currently multi threading creates instability.  Use at your own risk.

See also
========

  * randomPoints -- a function to find random points  in a
    variety.

Functions with optional argument named NumThreadsToUse :
========================================================

  * "extendIdealByNonZeroMinor(...,NumThreadsToUse=>...)"
  * "findANonZeroMinor(...,NumThreadsToUse=>...)"
  * "randomPoints(...,NumThreadsToUse=>...)"

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

The object NumThreadsToUse, is a symbol (Macaulay2Doc).

PointCheckAttempts -- Number of times that the function will search for a point
*******************************************************************************

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

When calling randomPoints, and functions that call it, with a BruteForce
strategy strategy, this denotes the number of trials for brute force point
checking.  When calling it with a LinearIntersection strategy, this controls
how many linear spaces are created.

+----------------------------------------------+
|i1 : R = ZZ/11[x,y,z];                        |
+----------------------------------------------+
|i2 : I = ideal(x,y);                          |
|                                              |
|o2 : Ideal of R                               |
+----------------------------------------------+
|i3 : randomPoints(I, PointCheckAttempts=>1)   |
|                                              |
|o3 = {{0, 0, 1}}                              |
|                                              |
|o3 : List                                     |
+----------------------------------------------+
|i4 : randomPoints(I, PointCheckAttempts=>1000)|
|                                              |
|o4 = {{0, 0, 1}}                              |
|                                              |
|o4 : List                                     |
+----------------------------------------------+

See also
========

  * randomPoints -- a function to find random points  in a
    variety.
  * extendIdealByNonZeroMinor -- extends the
    ideal to aid finding singular locus
  * findANonZeroMinor -- finds a non-vanishing minor
    at some randomly chosen point

Functions with optional argument named PointCheckAttempts :
===========================================================

  * "extendIdealByNonZeroMinor(...,PointCheckAttempts=>...)"
  * "findANonZeroMinor(...,PointCheckAttempts=>...)"
  * "randomPoints(...,PointCheckAttempts=>...)"

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

The object PointCheckAttempts, is a symbol (Macaulay2Doc).

projectionToHypersurface -- Generic projection to a hypersurface
****************************************************************

Synopsis
========

  * Usage:
        projectionToHypersurface I
        projectionToHypersurface R
  * Inputs:
      * I, an ideal (Macaulay2Doc), an ideal in a polynomial ring
      * R, a ring (Macaulay2Doc), a quotient of a polynomial ring
  * Optional inputs (Macaulay2Doc),:
      * Codimension => an integer (Macaulay2Doc), default value null,
        specified if you already know the codimension of your Ideal (or
        QuotientRing) in your ambient ring
      * MaxCoordinatesToReplace, => an
        integer (Macaulay2Doc), default value infinity, to be passed to
        randomCoordinateChange
      * Replacement, => a symbol (Macaulay2Doc),
        default value Binomial, to be passed to
        randomCoordinateChange
      * Homogeneous => a Boolean value (Macaulay2Doc), default
        value true, to be passed to randomCoordinateChange
      * Verbose,
        => a Boolean value (Macaulay2Doc), default value false,
        set to true for verbose output
  * Outputs:
      * a ring map (Macaulay2Doc), a list with two entries, the
        generic projection map, and the ideal if I was provided, or the ring if
        R was provided

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

This creates a projection to a hypersurface.  It differs from
genericProjection(codim I - 1, I) as it only tries to find a hypersurface
equation that vanishes along the projection, instead of finding one that
vanishes exactly at the projection.  This can be faster, and can be useful for
finding points.

+-----------------------------------------------------------------------------+
|i1 : R=ZZ/5[x,y,z];                                                          |
+-----------------------------------------------------------------------------+
|i2 : I = ideal(random(3,R)-2, random(2,R));                                  |
|                                                                             |
|o2 : Ideal of R                                                              |
+-----------------------------------------------------------------------------+
|i3 : projectionToHypersurface(I)                                             |
|                                                                             |
|              ZZ                             6     5      4 2       5    6   |
|o3 = (map (R, --[y..z], {x, y - 2z}), ideal(y  - 2y z - 2y z  - 2y*z  + z  - |
|               5                                                             |
|     ------------------------------------------------------------------------|
|       2       2                                                             |
|     2y z + y*z  - 1))                                                       |
|                                                                             |
|o3 : Sequence                                                                |
+-----------------------------------------------------------------------------+
|i4 : projectionToHypersurface(R/I)                                           |
|                                                                             |
|                                                                             |
|                                                                             |
|                                                   R                         |
|o4 = (map (------------------------------------------------------------------|
|                3       2     3    2     2        2       2     3            |
|           (- 2x  - 2x*y  - 2y  + x z - y z + 2x*z  - 2y*z  - 2z  - 2, - 2x*z|
|     ------------------------------------------------------------------------|
|                                               ZZ                            |
|                                               --[y..z]                      |
|                                                5                            |
|     --------------, --------------------------------------------------------|
|                 2    6    5      4 2     2 4      5     3    2       2    3 |
|      + 2y*z - 2z )  y  - y z + 2y z  - 2y z  - y*z  + 2y  - y z - y*z  + z  |
|     ------------------------------------------------------------------------|
|                                                      ZZ                     |
|                                                      --[y..z]               |
|                                                       5                     |
|     ---, {y + 2z, x + z}), -------------------------------------------------|
|                             6    5      4 2     2 4      5     3    2       |
|     + 1                    y  - y z + 2y z  - 2y z  - y*z  + 2y  - y z - y*z|
|     ------------------------------------------------------------------------|
|     ----------)                                                             |
|     2    3                                                                  |
|       + z  + 1                                                              |
|                                                                             |
|o4 : Sequence                                                                |
+-----------------------------------------------------------------------------+

If you already know the codimension is c, you can set Codimension=>c so the
function does not compute it.

See also
========

  * genericProjection -- finds a random (somewhat)
    generic projection of the ring or ideal

Ways to use projectionToHypersurface :
======================================

  * "projectionToHypersurface(Ideal)"
  * "projectionToHypersurface(Ring)"

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

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

randomCoordinateChange -- produce linear automorphism of the ring
*****************************************************************

Synopsis
========

  * Usage:
        randomCoordinateChange R
  * Inputs:
      * R, a ring (Macaulay2Doc), a polynomial Ring
  * Optional inputs (Macaulay2Doc),:
      * MaxCoordinatesToReplace, => an
        integer (Macaulay2Doc), default value infinity, how many
        coordinates should be replaced by linear functions
      * Replacement, => a symbol (Macaulay2Doc),
        default value Full, whether coordinate
        replacements should be binomial (Binomial) or fully random (Full)
      * Homogeneous => a Boolean value (Macaulay2Doc), default
        value true, whether coordinate replacements should be Homogeneous
      * Verbose,
        => a Boolean value (Macaulay2Doc), default value false,
        set to true for verbose output
  * Outputs:
      * a ring map (Macaulay2Doc), the coordinate change map.

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

Given a polynomial ring, this will produce a linear automorphism of the ring.

+--------------------------------------------------------+
|i1 : R=ZZ/5[x,y,z]                                      |
|                                                        |
|o1 = R                                                  |
|                                                        |
|o1 : PolynomialRing                                     |
+--------------------------------------------------------+
|i2 : randomCoordinateChange(R)                          |
|                                                        |
|             ZZ                                         |
|o2 = map (R, --[x..z], {- 2x - 2y, 2x - 2y - z, x - 2y})|
|              5                                         |
|                                                        |
|                    ZZ                                  |
|o2 : RingMap R <--- --[x..z]                            |
|                     5                                  |
+--------------------------------------------------------+

In some applications, a full change of coordinates is not desired, as it might
cause code to run slowly, and so a Binomialr change of coordinates might be
preferred. These Binomial changes of coordinates can be accomplished with the
options Replacement and MaxCoordinatesToReplace. Replacement can take either
Binomial or Full.  If Binomial is specified, then only binomial changes of
coordinates will be produced.

+-------------------------------------------------------------------+
|i3 : S = ZZ/11[a..e]                                               |
|                                                                   |
|o3 = S                                                             |
|                                                                   |
|o3 : PolynomialRing                                                |
+-------------------------------------------------------------------+
|i4 : randomCoordinateChange(S, Replacement=>Binomial)              |
|                                                                   |
|             ZZ                                                    |
|o4 = map (S, --[a..e], {a + 3b, 5c + e, - b + d, - 5a + b, c + 3d})|
|             11                                                    |
|                                                                   |
|                    ZZ                                             |
|o4 : RingMap S <--- --[a..e]                                       |
|                    11                                             |
+-------------------------------------------------------------------+

Finally, if Homogeneous is set to false, then our change of coordinates is not
homogeneous (although it is still linear).

+--------------------------------------------------------------------+
|i5 : randomCoordinateChange(R, Homogeneous=>false)                  |
|                                                                    |
|             ZZ                                                     |
|o5 = map (R, --[x..z], {x + 2y + 2z + 1, - 2y - 2z + 1, 2x - y + 1})|
|              5                                                     |
|                                                                    |
|                    ZZ                                              |
|o5 : RingMap R <--- --[x..z]                                        |
|                     5                                              |
+--------------------------------------------------------------------+

Note, this function already checks whether the function is an isomorphism by
computing the Jacobian.

Ways to use randomCoordinateChange :
====================================

  * "randomCoordinateChange(Ring)"

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

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

randomPoints -- a function to find random points  in a variety.
***************************************************************

Synopsis
========

  * Usage:
        randomPoints(I)
        randomPoints(n, I)
  * Inputs:
      * n, an integer (Macaulay2Doc), an integer denoting the number
        of desired points.
      * I, an ideal (Macaulay2Doc), inside a polynomial ring.
      * R, a ring (Macaulay2Doc), a polynomial ring
  * Optional inputs (Macaulay2Doc),:
      * Strategy, => a
        symbol (Macaulay2Doc), default value Default, to specify
        which strategy to use, Default, BruteForce, LinearIntersection.
      * ExtendField, => a Boolean value (Macaulay2Doc),
        default value false, whether to allow points
        not rational over the base field
      * Homogeneous => a Boolean value (Macaulay2Doc), default
        value true, whether to include the origin as a valid point to output
        PointCheckAttempts => ZZ points to search in total, see
        PointCheckAttempts,
      * NumThreadsToUse, => an integer (Macaulay2Doc),
        default value 1, number of threads to use in the
        BruteForce strategy, see NumThreadsToUse,
      * DimensionFunction => a function (Macaulay2Doc), default
        value dim, specify a custom dimension function, such as the default
        dimViaBezout or the Macaulay2 function dim
      * DecompositionStrategy, => a symbol (Macaulay2Doc),
        default value null, see
        DecompositionStrategy,
      * PointCheckAttempts, => ..., default value 0,
        Number of times that the function will search for a point
      * Replacement, => ..., default value Binomial, When
        changing coordinates, whether to replace variables by general degree 1
        forms, binomials, etc.
      * Verbose,
        => ..., default value false, turns out Verbose (debugging) output
  * Outputs:
      * a list (Macaulay2Doc), a list of points in the variety with
        possible repetitions.

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

Gives at most $n$ many point in a variety $V(I)$.

+-------------------------------------------------------+
|i1 : R = ZZ/5[t_1..t_3];                               |
+-------------------------------------------------------+
|i2 : I = ideal(t_1,t_2+t_3);                           |
|                                                       |
|o2 : Ideal of R                                        |
+-------------------------------------------------------+
|i3 : randomPoints(3, I)                                |
|                                                       |
|o3 = {{0, -1, 1}, {0, -1, 1}, {0, -1, 1}}              |
|                                                       |
|o3 : List                                              |
+-------------------------------------------------------+
|i4 : randomPoints(4, I, Strategy => Default)           |
|                                                       |
|o4 = {{0, -1, 1}, {0, -1, 1}, {0, -1, 1}, {0, -1, 1}}  |
|                                                       |
|o4 : List                                              |
+-------------------------------------------------------+
|i5 : randomPoints(4, I, Strategy => LinearIntersection)|
|                                                       |
|o5 = {{0, -1, 1}, {0, -1, 1}, {0, -1, 1}, {0, -1, 1}}  |
|                                                       |
|o5 : List                                              |
+-------------------------------------------------------+

The default strategy switches between LinearIntersection and
MultiplicationTable for the DecompositionStrategy,
(after first trying a brute force strategy).

Using DecompositionStrategy => MultiplicationTable (currently only implemented
for Homogeneous ideals) is sometimes faster and other times not.  It tends to
work better in rings with few variables.  Because of this, the default strategy
runs MultiplicationTable first in rings with fewer variables and runs Decompose
first in rings with more variables.

+-----------------------------------------------------------------------------+
|i6 : S=ZZ/103[y_0..y_30];                                                    |
+-----------------------------------------------------------------------------+
|i7 : I=minors(2,random(S^3,S^{3:-1}));                                       |
|                                                                             |
|o7 : Ideal of S                                                              |
+-----------------------------------------------------------------------------+
|i8 : elapsedTime randomPoints(I, Strategy=>LinearIntersection, DecompositionS|
| -- 8.8253 seconds elapsed                                                   |
|                                                                             |
|o8 = {{-4, -35, -7, 0, 0, 1, 5, -13, 0, -47, 0, 41, 0, -51, -46, 35, 0, 0,   |
|     ------------------------------------------------------------------------|
|     -47, 14, -30, 42, 30, 4, -41, 24, 0, 0, 15, 20, 1}}                     |
|                                                                             |
|o8 : List                                                                    |
|-----------------------------------------------------------------------------|
|trategy=>MultiplicationTable)                                                |
+-----------------------------------------------------------------------------+
|i9 : elapsedTime randomPoints(I, Strategy=>LinearIntersection, DecompositionS|
| -- 4.92275 seconds elapsed                                                  |
|                                                                             |
|o9 = {{11, 9, -9, -15, -7, 27, 19, -36, 48, 26, -4, 3, 29, -8, 7, -32, 16,   |
|     ------------------------------------------------------------------------|
|     11, 7, 7, 25, -14, -39, 17, -16, 4, -50, -12, 21, -50, 51}}             |
|                                                                             |
|o9 : List                                                                    |
|-----------------------------------------------------------------------------|
|trategy=>Decompose)                                                          |
+-----------------------------------------------------------------------------+

Ways to use randomPoints :
==========================

  * "randomPoints(Ideal)"
  * "randomPoints(ZZ,Ideal)"

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

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

randomPoints(...,Strategy=>...) -- values for the option Strategy when calling randomPoints
*******************************************************************************************

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

When calling randomPoints, set the strategy to one of these. BruteForce simply
tries random points and sees if they are on the variety.

LinearIntersection intersects with an random linear space.  Setting the
DecompositionStrategy => MultiplicationTable or
DecompositionStrategy=>Decompose will change how ideals corresponding to points
are broken up into minimal primes which can have a substantial impact on speed.
Otherwise, the function chooses which strategy it thinks will be better.  See
DecompositionStrategy.

Default performs a sequence of different strategies, with successively
increasing complexity of the linear subspaces that are intersected.

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

  * Default value: Default (Macaulay2Doc),
  * Function: randomPoints, -- a function to find random
    points  in a variety.
  * Option key: Strategy (Macaulay2Doc), -- an optional argument

See also
========

  * randomPoints -- a function to find random points  in a
    variety.
  * randomKRationalPoint (Macaulay2Doc) -- Pick a
    random K rational point on the scheme X defined by I
  * projectionToHypersurface -- Generic
    projection to a hypersurface

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

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

Replacement -- When changing coordinates, whether to replace variables by general degree 1 forms, binomials, etc.
*****************************************************************************************************************

Synopsis
========

  * Usage:
        Replacement => Full
        Replacement => Monomial
        Replacement => Binomial
        Replacement => Trinomial

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

When calling various functions, setting Replacement => Full will mean that
coordinates are changed to a general degree 1 form.  If Replacement =>
Binomial, the coordinates are only changed to binomials, which can be much
faster for certain applications.  Other options include Replacement => Monomial
and Replacement => Trinomial.

+-----------------------------------------------------------------------------+
|i1 : R = ZZ/101[a,b,c,d,e];                                                  |
+-----------------------------------------------------------------------------+
|i2 : randomCoordinateChange(R, Replacement=>Monomial)                        |
|                                                                             |
|              ZZ                                                             |
|o2 = map (R, ---[a..e], {a, d, e, b, c})                                     |
|             101                                                             |
|                                                                             |
|                     ZZ                                                      |
|o2 : RingMap R <--- ---[a..e]                                                |
|                    101                                                      |
+-----------------------------------------------------------------------------+
|i3 : randomCoordinateChange(R, Replacement=>Binomial)                        |
|                                                                             |
|              ZZ                                                             |
|o3 = map (R, ---[a..e], {- 16a + d, -12c, - 24d + e, a + 19d, b + 21c})      |
|             101                                                             |
|                                                                             |
|                     ZZ                                                      |
|o3 : RingMap R <--- ---[a..e]                                                |
|                    101                                                      |
+-----------------------------------------------------------------------------+
|i4 : randomCoordinateChange(R, Replacement=>Trinomial)                       |
|                                                                             |
|              ZZ                                                             |
|o4 = map (R, ---[a..e], {22b + 45d + e, 47b + 40d, 11b + c + 36d, - 11a + d +|
|             101                                                             |
|                                                                             |
|                     ZZ                                                      |
|o4 : RingMap R <--- ---[a..e]                                                |
|                    101                                                      |
|-----------------------------------------------------------------------------|
|43e, a - 16b - 48d})                                                         |
+-----------------------------------------------------------------------------+
|i5 : randomCoordinateChange(R, Replacement=>Full)                            |
|                                                                             |
|              ZZ                                                             |
|o5 = map (R, ---[a..e], {- 10a + 30b - 18c + 39d + 27e, 24a - 30b - 48c - 15d|
|             101                                                             |
|                                                                             |
|                     ZZ                                                      |
|o5 : RingMap R <--- ---[a..e]                                                |
|                    101                                                      |
|-----------------------------------------------------------------------------|
|+ 39e, 29a - 47b + 15c - 37d - 13e, - 22a + 32b - 9c - 32d - 20e, 33b - 49c -|
|-----------------------------------------------------------------------------|
|33d - 19e})                                                                  |
+-----------------------------------------------------------------------------+

If Homogeneous => false in these cases, then there will be constant terms, and
we view $mx + b$ as a monomial.

+-----------------------------------------------------------------------------+
|i6 : S = ZZ/103[x,y,z,u,v];                                                  |
+-----------------------------------------------------------------------------+
|i7 : randomCoordinateChange(S, Replacement => Monomial, Homogeneous => false)|
|                                                                             |
|              ZZ                                                             |
|o7 = map (S, ---[x..z, u..v], {z + 4, y + 9, x + 13, v - 28, u - 41})        |
|             103                                                             |
|                                                                             |
|                     ZZ                                                      |
|o7 : RingMap S <--- ---[x..z, u..v]                                          |
|                    103                                                      |
+-----------------------------------------------------------------------------+
|i8 : randomCoordinateChange(S, Replacement => Binomial, Homogeneous          |
|                                                                             |
|              ZZ                                                             |
|o8 = map (S, ---[x..z, u..v], {- 32y + 3, - 32y + u - 24, z - 30u +          |
|             103                                                             |
|                                                                             |
|                     ZZ                                                      |
|o8 : RingMap S <--- ---[x..z, u..v]                                          |
|                    103                                                      |
|-----------------------------------------------------------------------------|
|=> false)                                                                    |
|                                                                             |
|                                                                             |
|16, x - 43v - 4, - 37x + v - 11})                                            |
+-----------------------------------------------------------------------------+
|i9 : randomCoordinateChange(S, Replacement => Trinomial, Homogeneous =>      |
|                                                                             |
|              ZZ                                                             |
|o9 = map (S, ---[x..z, u..v], {- 14u + 30v + 7, - 20y + 41z + 28, - 19x      |
|             103                                                             |
|                                                                             |
|                     ZZ                                                      |
|o9 : RingMap S <--- ---[x..z, u..v]                                          |
|                    103                                                      |
|-----------------------------------------------------------------------------|
|false)                                                                       |
|                                                                             |
|                                                                             |
|+ 42y + 49, 30x + 48v - 50, 8x + y - 31z - 43})                              |
+-----------------------------------------------------------------------------+
|i10 : randomCoordinateChange(S, Replacement => Full, Homogeneous => false)   |
|                                                                             |
|               ZZ                                                            |
|o10 = map (S, ---[x..z, u..v], {6x - 11y - 35z + 28u - 31v - 30, 30x + 4y +  |
|              103                                                            |
|                                                                             |
|                      ZZ                                                     |
|o10 : RingMap S <--- ---[x..z, u..v]                                         |
|                     103                                                     |
|-----------------------------------------------------------------------------|
|22z + 5u - 22v + 44, 19x - 49z - 30u + 47v + 20, 5x - 39y - 35z - 30u + 42v +|
|-----------------------------------------------------------------------------|
|26, 23x - 39y - 25z + 44u - 41v - 23})                                       |
+-----------------------------------------------------------------------------+

See also
========

  * randomCoordinateChange -- produce linear
    automorphism of the ring

Functions with optional argument named Replacement :
====================================================

  * "dimViaBezout(...,Replacement=>...)"
  * "extendIdealByNonZeroMinor(...,Replacement=>...)"
  * "findANonZeroMinor(...,Replacement=>...)"
  * "genericProjection(...,Replacement=>...)"
  * "projectionToHypersurface(...,Replacement=>...)"
  * "randomCoordinateChange(...,Replacement=>...)"
  * "randomPoints(...,Replacement=>...)"

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

The object Replacement, is a symbol (Macaulay2Doc).