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

RandomObjects -- a Framework for the construction of random points of unirational moduli spaces
***********************************************************************************************

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

This package provides the framework for the implementation of unirationality
constructions.

A moduli space $M$ of objects is unirational if there exists a dominant
rational map $\phi:\mathbb{P}^n --> M$. If the function $\phi$ is explicitly
given it can be translated into a construction function that computes $\phi(P)$
for a given $P \in \mathbb{P}^n$. If $P$ is chosen randomly (over a finite
field $F_q$ or over a subset of $\mathbb{Q}$ limited by a given height) it may
not lie in the open subset of $\mathbb{P}^n$ where $\phi$ is defined. This can
be remedied by calling the function several times, i.e. allowing a certain
number of Attempts. One is also interested in certifying the constructed object
meaning that it satisfies certain reasonable properties.

Authors
=======

  * Hans-Christian Graf v. Bothmer (see http://www.crcg.de/wiki/User:Bothmer )
    <bothmer@uni-math.gwdg.de>
  * Florian Geiss (see http://www.math.uni-sb.de/ag/schreyer/ )
    <fg@math.uni-sb.de>
  * Daniel R. Grayson (see http://www.math.uiuc.edu/~dan/ ) <dan@math.uiuc.edu>
  * Frank-Olaf Schreyer (see http://www.math.uni-sb.de/ag/schreyer/ )
    <schreyer@math.uni-sb.de>

Version
=======

This documentation describes version 0.2 of RandomObjects.

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

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

Exports
=======

  * Types
      * RandomObject -- framework for creation of random
        objects
  * Functions and commands
      * randomObjectTemplate -- a template for the
        implementation of a random object
  * Methods
      * random(RandomObject) -- returns a
        function that constructs a random object
  * Symbols
      * Attempts -- number of attempts in the construction of
        a random object
      * Certify -- whether to certify the object
      * Construction -- key of randomObject that contains
        the construction function

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

The object RandomObjects, is a package (Macaulay2Doc).

Attempts -- number of attempts in the construction of a random object
*********************************************************************

Synopsis
========

  * Usage:
        (random randomObjectClass)(args,Attempts=>...)

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

Attempts can be assigned a nonnegative integer or infinity

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

The object Attempts, is a symbol (Macaulay2Doc).

Certify -- whether to certify the object
****************************************

Synopsis
========

  * Usage:
        (random randomObjectClass)(args,Certify=>...)

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

The object Certify, is a symbol (Macaulay2Doc).

Construction -- key of randomObject that contains the construction function
***************************************************************************

Synopsis
========

  * Usage:
        randomObject.Construction(args)
  * Outputs:
      * a thing (Macaulay2Doc),

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

The object Construction, is a symbol (Macaulay2Doc).

random(RandomObject) -- returns a function that constructs a random object
**************************************************************************

Synopsis
========

  * Usage:
        f=random(randomObjectClass)
  * Inputs:
      * randomObjectClass, an instance of the type RandomObject,
  * Outputs:
      * f, a function (Macaulay2Doc), that constructs a random
        object

The returned function f takes the following options:

* Attempts => ...  a nonnegative integer or infinity (default) that limits the
maximal number of attempts for the construction of an object

* Certify => ...  true or false (default) whether the output is certified. The
certifying properties are encoded in the Certification function of the
randomObjectClass

See also
========

  * Attempts -- number of attempts in the construction of a
    random object
  * Certify -- whether to certify the object

RandomObject -- framework for creation of random objects
********************************************************

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

RandomObject bundles the necessary functions for the construction of certified
random objects parametrized by a unirational moduli space $M$.

RandomObject is a MutableHashTable as ancestor and needs to have the following
keys:

* Construction: the method function assigned to this key contains a
unirationality construction.

* Certification: the method function assigned to this key checks whether the
constructed object fulfills certain conditions.

In the following example we construct plane curves of degree $d$. The
Certification checks whether they are irreducible over the coefficient field.

+-----------------------------------------------------------------------------+
|i1 : constructPlaneCurve = method(TypicalValue=>Ideal,                       |
|                                                                             |
|o1 = constructPlaneCurve                                                     |
|                                                                             |
|o1 : MethodFunctionWithOptions                                               |
|-----------------------------------------------------------------------------|
|Options=>{Certify=>false})                                                   |
+-----------------------------------------------------------------------------+
|i2 : constructPlaneCurve(ZZ,PolynomialRing):=opt->(d,R) -> ideal             |
|                                                                             |
|o2 = -*Function[stdio:2:44-2:78]*-                                           |
|                                                                             |
|o2 : FunctionClosure                                                         |
|-----------------------------------------------------------------------------|
|random(R^1,R^{1:-d})                                                         |
+-----------------------------------------------------------------------------+
|i3 : certifyPlaneCurve = method(TypicalValue=>Boolean)                       |
|                                                                             |
|o3 = certifyPlaneCurve                                                       |
|                                                                             |
|o3 : MethodFunction                                                          |
+-----------------------------------------------------------------------------+
|i4 : certifyPlaneCurve(Ideal,ZZ,PolynomialRing):=(I,d,R)-> #decompose I==1   |
|                                                                             |
|o4 = -*Function[stdio:4:52-4:69]*-                                           |
|                                                                             |
|o4 : FunctionClosure                                                         |
+-----------------------------------------------------------------------------+
|i5 : planeCurve = new RandomObject from {                                    |
|          Construction => constructPlaneCurve,                               |
|          Certification => certifyPlaneCurve                                 |
|          }                                                                  |
|                                                                             |
|o5 = planeCurve                                                              |
|                                                                             |
|o5 : RandomObject                                                            |
+-----------------------------------------------------------------------------+

We construct a curve of degree $2$ as follows

+-------------------------------------+
|i6 : setRandomSeed("alpha");         |
+-------------------------------------+
|i7 : R=ZZ/3[x_0..x_2];               |
+-------------------------------------+
|i8 : (random planeCurve)(2,R)        |
|                                     |
|              2                      |
|o8 = ideal(- x  - x x  + x x  - x x )|
|              0    0 1    0 2    1 2 |
|                                     |
|o8 : Ideal of R                      |
+-------------------------------------+

We can certify the curve by using the option Certify

+-------------------------------------------+
|i9 : (random planeCurve)(2,R,Certify=>true)|
|                                           |
|              2    2           2           |
|o9 = ideal(- x  + x  + x x  + x )          |
|              0    1    0 2    2           |
|                                           |
|o9 : Ideal of R                            |
+-------------------------------------------+

We have chosen a small finite field as ground field. Hence, there is a certain
chance that the curve is not irreducible. We can check this if we limit the
number of attempts to $1$. If the curve is then reducible, null is returned.

+-----------------------------------------------------------------------------+
|i10 : tally apply(3^4,i->(random planeCurve)(2,R,Certify=>true,Attempts=>1)  |
|                                                                             |
|o10 = Tally{false => 66}                                                     |
|            true => 15                                                       |
|                                                                             |
|o10 : Tally                                                                  |
|-----------------------------------------------------------------------------|
|=== null)                                                                    |
+-----------------------------------------------------------------------------+

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

  * random(RandomObject) -- returns a function
    that constructs a random object

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

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

randomObjectTemplate -- a template for the implementation of a random object
****************************************************************************

Synopsis
========

  * Usage:
        t=randomObjectTemplate(name)
  * Inputs:
      * name, a string (Macaulay2Doc), name of the object
  * Outputs:
      * t, a string (Macaulay2Doc), template for the
        implementation of "(random name)"

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

A template for the implementation of a new random object. Remember to document
what Certify => true actually certifies.

+---------------------------------------------------+
|i1 : randomObjectTemplate("foo")                   |
|                                                   |
|o1 = export {                                      |
|       constructFoo,                               |
|       certifyFoo,                                 |
|       foo                                         |
|       }                                           |
|                                                   |
|     constructFoo=method(Options=>{Certify=>false})|
|     constructFoo(Thing):=opt->(args)->(           |
|        )                                          |
|                                                   |
|     undocumented constructFoo                     |
|                                                   |
|     certifyFoo=method()                           |
|     certifyFoo(Thing,Thing)->(object,args)->(     |
|        )                                          |
|                                                   |
|     undocumented certifyFoo                       |
|                                                   |
|     foo = new RandomObject from {                 |
|                                                   |
|                    Construction  => constructFoo, |
|                                                   |
|                    Certification => certifyFoo}   |
|                                                   |
|     doc ///                                       |
|        Key                                        |
|         foo                                       |
|        Headline                                   |
|        Usage                                      |
|         (random foo)(args)                        |
|        Inputs                                     |
|         args : Thing                              |
|        Outputs                                    |
|     Consequences                                  |
|       Item                                        |
|     Description                                   |
|       Text                                        |
|       Tree                                        |
|       Code                                        |
|       Pre                                         |
|       Example                                     |
|       CannedExample                               |
|     ExampleFiles                                  |
|     Acknowledgement                               |
|     Contributors                                  |
|     References                                    |
|     Caveat                                        |
|     SeeAlso                                       |
|     Subnodes                                      |
|     ///                                           |
+---------------------------------------------------+

Ways to use randomObjectTemplate :
==================================

  * randomObjectTemplate(String) (missing documentation)

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

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