This is SLPexpressions.info, produced by Macaulay2, version 1.22

SLPexpressions -- Straight Line Programs and expressions for evaluation circuits
********************************************************************************

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

Many polynomials can be stored and evaluated efficiently when represented as a
straight line program (SLP), also known as an algebraic circuit (see
https://en.wikipedia.org/wiki/Circuit_(computer_science) ). By contrast,
elements of a PolynomialRing (Macaulay2Doc), in Macaulay2
are necessarily represented in "expanded" form, e.g. via a monomial basis.

This package provides basic types and methods for constructing and evaluating
SLPs.

Here is a simple example illustrating an advantage of SLP representations.

+-----------------------------------------------------------------------------+
|i1 : declareVariable x                                                       |
|                                                                             |
|o1 = x                                                                       |
|                                                                             |
|o1 : InputGate                                                               |
+-----------------------------------------------------------------------------+
|i2 : f = x + 1                                                               |
|                                                                             |
|o2 = (x + 1)                                                                 |
|                                                                             |
|o2 : SumGate                                                                 |
+-----------------------------------------------------------------------------+
|i3 : n = 12;                                                                 |
+-----------------------------------------------------------------------------+
|i4 : for i from 1 to n do f = f*f -- f = (x+1)^(2^n)                         |
+-----------------------------------------------------------------------------+
|i5 : slp = makeInterpretedSLProgram({x},{f})                                 |
|                                                                             |
|o5 = InterpretedSLProgram{cache => CacheTable{}               }              |
|                          "constant positions" => {-2}                       |
|                          "constants" => | 1 |                               |
|                          "number of inputs" => 1                            |
|                          "number of outputs" => 1                           |
|                          RawSLProgram => SLProgram (                        |
|                                            consts+vars: 2                   |
|                                            noninput nodes: 13               |
|                                            output nodes: 1                  |
|                                            )                                |
|                                                                             |
|                          "variable positions" => {-1}                       |
|                                                                             |
|o5 : InterpretedSLProgram                                                    |
+-----------------------------------------------------------------------------+
|i6 : time A = evaluate(slp,matrix{{1}});                                     |
|     -- used 0.000376905 seconds                                             |
|                                                                             |
|              1        1                                                     |
|o6 : Matrix ZZ  <--- ZZ                                                      |
+-----------------------------------------------------------------------------+
|i7 : ZZ[y];                                                                  |
+-----------------------------------------------------------------------------+
|i8 : time B = sub((y+1)^(2^n),{y=>1})                                        |
|     -- used 4.35263 seconds                                                 |
|                                                                             |
|o8 = 104438888141315250669175271071662438257996424904738378038423348328395390|
|     797155745684882681193499755834089010671443926283798757343818579360726323|
|     608785136527794595697654370999834036159013438371831442807001185594622637|
|     631883939771274567233468434458661749680790870580370407128404874011860911|
|     446797778359802900668693897688178778594690563019026094059957945343282346|
|     930302669644305902501597239986771421554169383555988529148631823791443449|
|     673408781187263949647510018904134900841706167509366833385055103297208826|
|     955076998361636941193301521379682583718809183365675122131849284636812555|
|     022599830041234478486259567449219461702380650591324561082573183538008760|
|     862210283427019769820231316901767800667519548507992163641937028537512478|
|     401490715913545998279051339961155179427110683113409058427288427979155484|
|     978295432353451706522326906139490598769300212296339568778287894844061600|
|     741294567491982305057164237715481632138063104590291613692670834285644073|
|     044789997190178146576347322385026725305989979599609079946920177462481771|
|     844986745565925017832907047311943316555080756822184657174637329688491281|
|     952031745700244092661691087414838507841192980452298185733897764810312608|
|     590300130241346718972667321649151113160292078173803343609024380470834040|
|     3154190336                                                              |
+-----------------------------------------------------------------------------+
|i9 : A == B                                                                  |
|                                                                             |
|o9 = true                                                                    |
+-----------------------------------------------------------------------------+

See also
========

  * NAGtypes -- Common types used in Numerical Algebraic
    Geometry
  * makeCompiledSLProgram (missing documentation)

Authors
=======

  * Anton Leykin (see https://people.math.gatech.edu/~aleykin3 )
    <leykin@math.gatech.edu>
  * Timothy Duff (see http://people.math.gatech.edu/~tduff3 )
    <tduff3@gatech.edu>
  * Justin Chen (see https://people.math.gatech.edu/~jchen646 )
    <jchen646@math.gatech.edu>
  * Mike Stillman (see http://www.math.cornell.edu/~mike )
    <mike@math.cornell.edu>

Version
=======

This documentation describes version 1.21 of SLPexpressions.

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

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

Exports
=======

  * Types
      * CompiledSLProgram (missing documentation)
      * "DetGate" -- see Gate, -- the class of all gates
      * "DivideGate" -- see Gate, -- the class of all gates
      * Gate -- the class of all gates
      * "InputGate" -- see Gate, -- the class of all gates
      * "ProductGate" -- see Gate, -- the class of all gates
      * "SumGate" -- see Gate, -- the class of all gates
      * GateMatrix -- a matrix of Gates
      * "InterpretedSLProgram" -- see makeInterpretedSLProgram,
        -- create a straight-line program
      * SLProgram (missing documentation)
      * "ValueHashTable" -- see valueHashTable, --
        creates a hash table of values for evaluation
  * Functions and commands
      * "detGate" -- see creating gates,
      * "inputGate" -- see creating gates,
      * "productGate" -- see creating gates,
      * "sumGate" -- see creating gates,
      * declareVariable -- assigns an input gate to a
        given variable name
      * gateMatrix -- create a GateMatrix
      * gatePolynomial -- creates an input gate for a
        given polynomial
      * getVarGates -- returns the input gates for
        variables in a polynomial ring
      * makeCompiledSLProgram (missing documentation)
      * makeInterpretedSLProgram -- create a
        straight-line program
      * makeSLProgram -- create a straight-line program
        (either interpreted or compiled)
      * "setTryJustInTimeCompilation" -- see makeSLProgram,
        -- create a straight-line program (either interpreted or
        compiled)
      * "countGates" -- see measuring the size of circuits,
      * undeclareVariable -- clears assignment of an
        input gate to a variable name
      * valueHashTable -- creates a hash table of values
        for evaluation
  * Methods
      * "- Gate" -- see arithmetic with circuits,
      * "Gate * Gate" -- see arithmetic with circuits,
      * "Gate * Matrix" -- see arithmetic with circuits,
      * "Gate * Number" -- see arithmetic with circuits,
      * "Gate * RingElement" -- see arithmetic with circuits,
      * "Gate + Gate" -- see arithmetic with circuits,
      * "Gate + Number" -- see arithmetic with circuits,
      * "Gate + RingElement" -- see arithmetic with circuits,
      * "Gate - Gate" -- see arithmetic with circuits,
      * "Gate - Number" -- see arithmetic with circuits,
      * "Gate - RingElement" -- see arithmetic with circuits,
      * "Gate / Gate" -- see arithmetic with circuits,
      * "Gate ^ ZZ" -- see arithmetic with circuits,
      * "GateMatrix * GateMatrix" -- see arithmetic with circuits,
      * "GateMatrix * Matrix" -- see arithmetic with circuits,
      * "GateMatrix * RingElement" -- see arithmetic with circuits,
      * "GateMatrix + GateMatrix" -- see arithmetic with circuits,
      * "GateMatrix + Matrix" -- see arithmetic with circuits,
      * "GateMatrix - GateMatrix" -- see arithmetic with circuits,
      * "GateMatrix - Matrix" -- see arithmetic with circuits,
      * "GateMatrix ^ List" -- see arithmetic with circuits,
      * "Matrix * Gate" -- see arithmetic with circuits,
      * "Matrix * GateMatrix" -- see arithmetic with circuits,
      * "Matrix + GateMatrix" -- see arithmetic with circuits,
      * "Matrix - GateMatrix" -- see arithmetic with circuits,
      * "Number * Gate" -- see arithmetic with circuits,
      * "Number + Gate" -- see arithmetic with circuits,
      * "Number - Gate" -- see arithmetic with circuits,
      * "RingElement * Gate" -- see arithmetic with circuits,
      * "RingElement * GateMatrix" -- see arithmetic with circuits,
      * "RingElement + Gate" -- see arithmetic with circuits,
      * "RingElement - Gate" -- see arithmetic with circuits,
      * "compress(Gate)" -- see compressing circuits,
      * "compress(GateMatrix)" -- see compressing circuits,
      * "detGate(List)" -- see creating gates,
      * "inputGate(Thing)" -- see creating gates,
      * "productGate(List)" -- see creating gates,
      * "sumGate(List)" -- see creating gates,
      * "declareVariable(IndexedVariable)" -- see declareVariable,
        -- assigns an input gate to a given variable name
      * "declareVariable(InputGate)" -- see declareVariable,
        -- assigns an input gate to a given variable name
      * "declareVariable(Symbol)" -- see declareVariable,
        -- assigns an input gate to a given variable name
      * "declareVariable(Thing)" -- see declareVariable,
        -- assigns an input gate to a given variable name
      * "diff(GateMatrix,GateMatrix)" -- see differentiating circuits,
      * "diff(InputGate,Gate)" -- see differentiating circuits,
      * "diff(InputGate,GateMatrix)" -- see differentiating circuits,
      * "evaluate(SLProgram,Matrix)" -- see
        evaluate(SLProgram,MutableMatrix,MutableMatrix),
        -- evaluate a
        straight-line program
      * evaluate(SLProgram,MutableMatrix,MutableMatrix)
        -- evaluate a
        straight-line program
      * "value(DetGate,ValueHashTable)" -- see evaluating gates,
      * "value(DivideGate,ValueHashTable)" -- see evaluating gates,
      * "value(GateMatrix,ValueHashTable)" -- see evaluating gates,
      * "value(InputGate,ValueHashTable)" -- see evaluating gates,
      * "value(ProductGate,ValueHashTable)" -- see evaluating gates,
      * "value(SumGate,ValueHashTable)" -- see evaluating gates,
      * "gateMatrix(GateMatrix)" -- see gateMatrix, -- create
        a GateMatrix
      * "gateMatrix(List)" -- see gateMatrix, -- create a
        GateMatrix
      * "gateMatrix(Matrix)" -- see gateMatrix, -- create a
        GateMatrix
      * "gatePolynomial(Matrix)" -- see gatePolynomial,
        -- creates an input gate for a given polynomial
      * "gatePolynomial(RingElement)" -- see gatePolynomial,
        -- creates an input gate for a given polynomial
      * "getVarGates(PolynomialRing)" -- see getVarGates, --
        returns the input gates for variables in a polynomial ring
      * isConstant(InputGate) -- whether an
        input gate is constant
      * "makeInterpretedSLProgram(GateMatrix,GateMatrix)" -- see
        makeInterpretedSLProgram, -- create a
        straight-line program
      * "makeInterpretedSLProgram(List,List)" -- see
        makeInterpretedSLProgram, -- create a
        straight-line program
      * "makeSLProgram(GateMatrix,GateMatrix)" -- see makeSLProgram,
        -- create a straight-line program (either interpreted or
        compiled)
      * "makeSLProgram(List,List)" -- see makeSLProgram,
        -- create a straight-line program (either interpreted or compiled)
      * "setTryJustInTimeCompilation(Boolean)" -- see makeSLProgram,
        -- create a straight-line program (either interpreted or
        compiled)
      * "countGates(GateMatrix)" -- see measuring the size of circuits,
      * "depth(DetGate)" -- see measuring the size of circuits,
      * "depth(DivideGate)" -- see measuring the size of circuits,
      * "depth(GateMatrix)" -- see measuring the size of circuits,
      * "depth(InputGate)" -- see measuring the size of circuits,
      * "depth(ProductGate)" -- see measuring the size of circuits,
      * "depth(SumGate)" -- see measuring the size of circuits,
      * "undeclareVariable(InputGate)" -- see undeclareVariable,
        -- clears assignment of an input gate to a variable
        name
      * "valueHashTable(List,List)" -- see valueHashTable,
        -- creates a hash table of values for evaluation
      * "determinant(GateMatrix)" -- see working with gate matrices,
      * "entries(GateMatrix)" -- see working with gate matrices,
      * "GateMatrix _ List" -- see working with gate matrices,
      * "GateMatrix _ Sequence" -- see working with gate matrices,
      * "GateMatrix | GateMatrix" -- see working with gate matrices,
      * "GateMatrix | Matrix" -- see working with gate matrices,
      * "GateMatrix || GateMatrix" -- see working with gate matrices,
      * "GateMatrix || Matrix" -- see working with gate matrices,
      * "Matrix | GateMatrix" -- see working with gate matrices,
      * "Matrix || GateMatrix" -- see working with gate matrices,
      * "numColumns(GateMatrix)" -- see working with gate matrices,
      * "numRows(GateMatrix)" -- see working with gate matrices,
      * "submatrix(GateMatrix,List,List)" -- see working with gate matrices,
      * "substitute(GateMatrix,GateMatrix,GateMatrix)" -- see working with gate matrices,
      * "substitute(GateMatrix,HashTable)" -- see working with gate matrices,
      * "substitute(GateMatrix,List)" -- see working with gate matrices,
      * "substitute(GateMatrix,Option)" -- see working with gate matrices,
      * "transpose(GateMatrix)" -- see working with gate matrices,

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

The object SLPexpressions, is a package (Macaulay2Doc).

arithmetic with circuits
************************

There are many arithmetic operations that can be performed on gates.
This makes it easy to create combine existing gates into new gates.

+------------------------------------------------+
|i1 : declareVariable X; declareVariable Y;      |
+------------------------------------------------+
|i3 : m1 = Y*Y                                   |
|                                                |
|o3 = (Y * Y)                                    |
|                                                |
|o3 : ProductGate                                |
+------------------------------------------------+
|i4 : m2 = X^3                                   |
|                                                |
|o4 = (X * X * X)                                |
|                                                |
|o4 : ProductGate                                |
+------------------------------------------------+
|i5 : F = m1-m2-X                                |
|                                                |
|o5 = (((Y * Y) + (-1 * (X * X * X))) + (-1 * X))|
|                                                |
|o5 : SumGate                                    |
+------------------------------------------------+

If one of the inputs is a Number (Macaulay2Doc), it is first
converted to an InputGate,:

+------------+
|i6 : X + 2  |
|            |
|o6 = (X + 2)|
|            |
|o6 : SumGate|
+------------+

By extension, arithmetic operations also work with gate matrices,:

+-----------------------------------------------------+
|i7 : M = matrix {{X, Y}}                             |
|                                                     |
|o7 = {{X, Y}}                                        |
|                                                     |
|o7 : GateMatrix                                      |
+-----------------------------------------------------+
|i8 : 3*M                                             |
|                                                     |
|o8 = {{(3 * X), (3 * Y)}}                            |
|                                                     |
|o8 : GateMatrix                                      |
+-----------------------------------------------------+
|i9 : transpose M * M                                 |
|                                                     |
|o9 = {{((X * X)), ((X * Y))}, {((Y * X)), ((Y * Y))}}|
|                                                     |
|o9 : GateMatrix                                      |
+-----------------------------------------------------+

See also
========

  * InputGate -- the class of all gates
  * GateMatrix -- a matrix of Gates

CompiledSLProgram
*****************

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

  * makeCompiledSLProgram (missing documentation)

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

  * evaluate(CompiledSLProgram,MutableMatrix,MutableMatrix) (missing
    documentation)

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

The object CompiledSLProgram (missing documentation) is a type (Macaulay2Doc),
with ancestor classes SLProgram (missing documentation) <
HashTable (Macaulay2Doc) < Thing (Macaulay2Doc).

compressing circuits
********************

Synopsis
========

  * Usage:
        g' = compress g
        G' = compress G
  * Inputs:
      * g, an instance of the type Gate,
      * G, an instance of the type GateMatrix,
  * Outputs:
      * g', an instance of the type Gate,
      * G', an instance of the type GateMatrix,

These commands attempt to remove superfluous operations involving constants
from the building blocks of a compound Gate, or GateMatrix.
The example below is contrived, but illustrates what may happen in
general.

+----------------------------------------------------------------------+
|i1 : declareVariable \ {a,b,c}                                        |
|                                                                      |
|o1 = {a, b, c}                                                        |
|                                                                      |
|o1 : List                                                             |
+----------------------------------------------------------------------+
|i2 : x = inputGate 1                                                  |
|                                                                      |
|o2 = 1                                                                |
|                                                                      |
|o2 : InputGate                                                        |
+----------------------------------------------------------------------+
|i3 : y = inputGate 2                                                  |
|                                                                      |
|o3 = 2                                                                |
|                                                                      |
|o3 : InputGate                                                        |
+----------------------------------------------------------------------+
|i4 : G = gateMatrix{{(x+y)+3+4+b+4+c+4*(a+b+2)}}                      |
|                                                                      |
|o4 = {{(((((((1 + 2) + 3) + 4) + b) + 4) + c) + (4 * ((a + b) + 2)))}}|
|                                                                      |
|o4 : GateMatrix                                                       |
+----------------------------------------------------------------------+
|i5 : cG = compress G                                                  |
|                                                                      |
|o5 = {{(((4 + (10 + b)) + c) + (4 * (2 + (a + b))))}}                 |
|                                                                      |
|o5 : GateMatrix                                                       |
+----------------------------------------------------------------------+
|i6 : depth G                                                          |
|                                                                      |
|o6 = 7                                                                |
+----------------------------------------------------------------------+
|i7 : depth cG                                                         |
|                                                                      |
|o7 = 4                                                                |
+----------------------------------------------------------------------+
|i8 : countGates G                                                     |
|                                                                      |
|o8 = HashTable{cache => CacheTable{...17...}}                         |
|               InputGate => 7                                         |
|               ProductGate => 1                                       |
|               SumGate => 9                                           |
|                                                                      |
|o8 : HashTable                                                        |
+----------------------------------------------------------------------+
|i9 : countGates cG                                                    |
|                                                                      |
|o9 = HashTable{cache => CacheTable{...13...}}                         |
|               InputGate => 6                                         |
|               ProductGate => 1                                       |
|               SumGate => 6                                           |
|                                                                      |
|o9 : HashTable                                                        |
+----------------------------------------------------------------------+

See also
========

  * measuring the size of circuits

creating gates
**************

Synopsis
========

  * Usage:
        inputGate L
        sumGate L
        productGate L
  * Inputs:
      * L, a list (Macaulay2Doc),
  * Outputs:
      * an instance of the type InputGate,

This method returns a type of Gate, from the given data. Some
specific Gate,s are constructed as follows:

InputGate, is constructed with inputGate,
name, if name is a number then this gate is assumed to be constant.

+----------------------+
|i1 : declareVariable X|
|                      |
|o1 = X                |
|                      |
|o1 : InputGate        |
+----------------------+
|i2 : declareVariable Y|
|                      |
|o2 = Y                |
|                      |
|o2 : InputGate        |
+----------------------+
|i3 : inputGate 3      |
|                      |
|o3 = 3                |
|                      |
|o3 : InputGate        |
+----------------------+

See SumGate, is constructed with sumGate, L,
where L is a list of gates, or Gate + Gate.

+-----------------+
|i4 : X + 1       |
|                 |
|o4 = (X + 1)     |
|                 |
|o4 : SumGate     |
+-----------------+
|i5 : sumGate{X,Y}|
|                 |
|o5 = (X + Y)     |
|                 |
|o5 : SumGate     |
+-----------------+

See ProductGate, is constructed with productGate,
L, where L is a list of gates, or Gate * Gate.

+------------------------+
|i6 : 2*Y                |
|                        |
|o6 = (2 * Y)            |
|                        |
|o6 : ProductGate        |
+------------------------+
|i7 : productGate{X,-X,Y}|
|                        |
|o7 = (X * (-1 * X) * Y) |
|                        |
|o7 : ProductGate        |
+------------------------+

See DivideGate, is constructed with Gate / Gate.

+---------------+
|i8 : X / Y     |
|               |
|     X         |
|o8 = -         |
|     Y         |
|               |
|o8 : DivideGate|
+---------------+

See DetGate, is constructed with detGate, L,
where L is a doubly-nested list of gates, or det A, where A is a
GateMatrix.

+---------------------------------+
|i9 : detGate {{X, Y}, {-Y, X}}   |
|                                 |
|o9 = det| X        Y |           |
|        | (-1 * Y) X |           |
|                                 |
|o9 : DetGate                     |
+---------------------------------+
|i10 : det matrix{{Y, 1}, {-1, X}}|
|                                 |
|o10 = det| Y  1 |                |
|         | -1 X |                |
|                                 |
|o10 : DetGate                    |
+---------------------------------+

See also
========

  * Gate -- the class of all gates

declareVariable -- assigns an input gate to a given variable name
*****************************************************************

Synopsis
========

  * Usage:
        declareVariable x
  * Inputs:
      * x, a symbol (Macaulay2Doc), or an IndexedVariable (Macaulay2Doc),
  * Outputs:
      * an instance of the type InputGate,

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

This method assigns an InputGate, which has the same Name (Macaulay2Doc),
as the given symbol or the baseName (Macaulay2Doc),
of the given IndexedVariable (Macaulay2Doc),
so that later references to the symbol will be
treated (and can be used) as an InputGate. This can be reverted
with undeclareVariable.

+----------------------+
|i1 : declareVariable x|
|                      |
|o1 = x                |
|                      |
|o1 : InputGate        |
+----------------------+
|i2 : x + 1            |
|                      |
|o2 = (x + 1)          |
|                      |
|o2 : SumGate          |
+----------------------+

See also
========

  * undeclareVariable -- clears assignment of an
    input gate to a variable name

Ways to use declareVariable :
=============================

  * "declareVariable(IndexedVariable)"
  * "declareVariable(InputGate)"
  * "declareVariable(Symbol)"
  * "declareVariable(Thing)"

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

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

differentiating circuits
************************

The output of these commands is generally a circuit for evaluating the
derivative of the second argument with respect to the first.

+-----------------------------------------------------------------------------+
|i1 : declareVariable X; declareVariable Y;                                   |
+-----------------------------------------------------------------------------+
|i3 : F = Y^2-X^3-X                                                           |
|                                                                             |
|o3 = (((Y * Y) + (-1 * (X * X * X))) + (-1 * X))                             |
|                                                                             |
|o3 : SumGate                                                                 |
+-----------------------------------------------------------------------------+
|i4 : diff(X,F)                                                               |
|                                                                             |
|o4 = (((0 + 0) + (0 + ((-1) * ((X * X) + (X * X) + (X * X))))) + (0 + (-1))) |
|                                                                             |
|o4 : SumGate                                                                 |
+-----------------------------------------------------------------------------+
|i5 : J = diff(gateMatrix{{X,Y}},gateMatrix{{F}})                             |
|                                                                             |
|o5 = {{(((0 + 0) + (0 + ((-1) * ((X * X) + (X * X) + (X * X))))) + (0 +      |
|     ------------------------------------------------------------------------|
|     (-1))), ((((Y) + (Y)) + (0 + ((-1) * (0 + 0 + 0)))) + (0 + 0))}}        |
|                                                                             |
|o5 : GateMatrix                                                              |
+-----------------------------------------------------------------------------+
|i6 : (numrows J, numcols J)                                                  |
|                                                                             |
|o6 = (1, 2)                                                                  |
|                                                                             |
|o6 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * InputGate -- the class of all gates
  * GateMatrix -- a matrix of Gates

evaluate(SLProgram,MutableMatrix,MutableMatrix) -- evaluate a straight-line program
***********************************************************************************

Synopsis
========

  * Function: evaluate (NAGtypes),
  * Usage:
        evaluate(slp, inp, out)
  * Inputs:
      * slp, an instance of the type SLProgram (missing documentation),
      * inp, a mutable matrix (Macaulay2Doc), of inputs
      * out, a mutable matrix (Macaulay2Doc), of outputs
  * Consequences:
      * The second argument (i.e. the mutable matrix out) is changed to be the
        value of the straight-line program on the input inp.

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

This method evaluates an object of type SLProgram (missing documentation) on a
given input. The two matrices inp and out should both be mutable (Macaulay2Doc),
of the same sizes, and be defined over the same
ring.

+-----------------------------------------------------------------------------+
|i1 : declareVariable X; declareVariable C;                                   |
+-----------------------------------------------------------------------------+
|i3 : XpC = X+C                                                               |
|                                                                             |
|o3 = (X + C)                                                                 |
|                                                                             |
|o3 : SumGate                                                                 |
+-----------------------------------------------------------------------------+
|i4 : XXC = productGate{X,X,C}                                                |
|                                                                             |
|o4 = (X * X * C)                                                             |
|                                                                             |
|o4 : ProductGate                                                             |
+-----------------------------------------------------------------------------+
|i5 : detXCCX = detGate{{X,C},{C,X}}                                          |
|                                                                             |
|o5 = det| X C |                                                              |
|        | C X |                                                              |
|                                                                             |
|o5 : DetGate                                                                 |
+-----------------------------------------------------------------------------+
|i6 : XoC = X/C                                                               |
|                                                                             |
|     X                                                                       |
|o6 = -                                                                       |
|     C                                                                       |
|                                                                             |
|o6 : DivideGate                                                              |
+-----------------------------------------------------------------------------+
|i7 : slp = makeInterpretedSLProgram(matrix{{C,X}},matrix{{XXC,detXCCX,XoC,XpC|
|                                                                             |
|o7 = InterpretedSLProgram{cache => CacheTable{}              }               |
|                          "constant positions" => {-3}                       |
|                          "constants" => | 2 |                               |
|                          "number of inputs" => 2                            |
|                          "number of outputs" => 4                           |
|                          RawSLProgram => SLProgram (                        |
|                                            consts+vars: 3                   |
|                                            noninput nodes: 5                |
|                                            output nodes: 4                  |
|                                            )                                |
|                                                                             |
|                          "variable positions" => {-1, -2}                   |
|                                                                             |
|o7 : InterpretedSLProgram                                                    |
|-----------------------------------------------------------------------------|
|+2}})                                                                        |
+-----------------------------------------------------------------------------+
|i8 : inp = mutableMatrix{{1.2,-1}}                                           |
|                                                                             |
|o8 = | 1.2 -1 |                                                              |
|                                                                             |
|o8 : MutableMatrix                                                           |
+-----------------------------------------------------------------------------+
|i9 : out = mutableMatrix(ring inp,1,4)                                       |
|                                                                             |
|o9 = | 0 0 0 0 |                                                             |
|                                                                             |
|o9 : MutableMatrix                                                           |
+-----------------------------------------------------------------------------+
|i10 : evaluate(slp,inp,out)                                                  |
+-----------------------------------------------------------------------------+
|i11 : clean_0.001(out - mutableMatrix {{1.2, -.44, -.833333, 2.2}}) == 0     |
|                                                                             |
|o11 = true                                                                   |
+-----------------------------------------------------------------------------+

The straight-line program can also be evaluated at different inputs in
different rings:

+---------------------------------------+
|i12 : inp = mutableMatrix{{-5_QQ,3}}   |
|                                       |
|o12 = | -5 3 |                         |
|                                       |
|o12 : MutableMatrix                    |
+---------------------------------------+
|i13 : ring inp                         |
|                                       |
|o13 = QQ                               |
|                                       |
|o13 : Ring                             |
+---------------------------------------+
|i14 : out = mutableMatrix(ring inp,1,4)|
|                                       |
|o14 = 0                                |
|                                       |
|o14 : MutableMatrix                    |
+---------------------------------------+
|i15 : evaluate(slp, inp, out)          |
+---------------------------------------+
|i16 : out                              |
|                                       |
|o16 = | -45 -16 -3/5 0 |               |
|                                       |
|o16 : MutableMatrix                    |
+---------------------------------------+

See also
========

  * SLProgram (missing documentation)
  * InterpretedSLProgram -- create a
    straight-line program
  * CompiledSLProgram (missing documentation)

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

  * "evaluate(SLProgram,Matrix)"
  * evaluate(SLProgram,MutableMatrix,MutableMatrix)
    -- evaluate a
    straight-line program

evaluating gates
****************

The standard method value (Macaulay2Doc), provides a way to
evaluate Gate,s at particular inputs, provided in the form of a
ValueHashTable. The results are cached, and thus are not
recomputed when called again with the same Gate, and
ValueHashTable, as inputs.

+-----------------------------------------------------+
|i1 : declareVariable X                               |
|                                                     |
|o1 = X                                               |
|                                                     |
|o1 : InputGate                                       |
+-----------------------------------------------------+
|i2 : declareVariable Y                               |
|                                                     |
|o2 = Y                                               |
|                                                     |
|o2 : InputGate                                       |
+-----------------------------------------------------+
|i3 : C = sumGate {X+Y,Y,X}                           |
|                                                     |
|o3 = ((X + Y) + Y + X)                               |
|                                                     |
|o3 : SumGate                                         |
+-----------------------------------------------------+
|i4 : D = productGate {X*Y,Y,C}                       |
|                                                     |
|o4 = ((X * Y) * Y * ((X + Y) + Y + X))               |
|                                                     |
|o4 : ProductGate                                     |
+-----------------------------------------------------+
|i5 : h = valueHashTable({X,Y},{1,ii})                |
|                                                     |
|o5 = ValueHashTable{...2...}                         |
|                                                     |
|o5 : ValueHashTable                                  |
+-----------------------------------------------------+
|i6 : v = value(D,h)                                  |
|                                                     |
|o6 = -2-2*ii                                         |
|                                                     |
|o6 : CC (of precision 53)                            |
+-----------------------------------------------------+
|i7 : v == product{value(X*Y,h),value(Y,h),value(C,h)}|
|                                                     |
|o7 = true                                            |
+-----------------------------------------------------+

See also
========

  * valueHashTable -- creates a hash table of values for
    evaluation

Gate -- the class of all gates
******************************

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

A gate is a building block of an evaluation circuit. For instance, an
InputGate, represents an abstract unit of input, and a SumGate,
takes a list of inputs, and has an output which represents the sum of the
inputs. For more information on the types of gates available in this package,
as well as how to construct gates, see creating input gates.

Types of Gate :
===============

  * "DetGate"
  * "DivideGate"
  * "InputGate"
  * "ProductGate"
  * "SumGate"

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

  * "- Gate" -- see arithmetic with circuits,
  * "Gate * Gate" -- see arithmetic with circuits,
  * "Gate * Matrix" -- see arithmetic with circuits,
  * "Gate * Number" -- see arithmetic with circuits,
  * "Gate * RingElement" -- see arithmetic with circuits,
  * "Gate + Gate" -- see arithmetic with circuits,
  * "Gate + Number" -- see arithmetic with circuits,
  * "Gate + RingElement" -- see arithmetic with circuits,
  * "Gate - Gate" -- see arithmetic with circuits,
  * "Gate - Number" -- see arithmetic with circuits,
  * "Gate - RingElement" -- see arithmetic with circuits,
  * "Gate / Gate" -- see arithmetic with circuits,
  * "Gate ^ ZZ" -- see arithmetic with circuits,
  * "Matrix * Gate" -- see arithmetic with circuits,
  * "Number * Gate" -- see arithmetic with circuits,
  * "Number + Gate" -- see arithmetic with circuits,
  * "Number - Gate" -- see arithmetic with circuits,
  * "RingElement * Gate" -- see arithmetic with circuits,
  * "RingElement + Gate" -- see arithmetic with circuits,
  * "RingElement - Gate" -- see arithmetic with circuits,
  * "compress(Gate)" -- see compressing circuits,
  * "diff(InputGate,Gate)" -- see differentiating circuits,

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

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

GateMatrix -- a matrix of Gates
*******************************

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

An object of this type is a matrix with Gates as entries. Some algebraic
operations (matrix multiplication, determinant, etc.) are defined for this
type. It is provided, in part, for convenience of setting up involved
evaluation circuits. To see how to create a GateMatrix, see
gateMatrix. For information about operations that can be
performed on gate matrices, see working with gate matrices.

See also
========

  * Gate -- the class of all gates
  * gateMatrix -- create a GateMatrix
  * working with gate matrices

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

  * "GateMatrix * GateMatrix" -- see arithmetic with circuits,
  * "GateMatrix * Matrix" -- see arithmetic with circuits,
  * "GateMatrix * RingElement" -- see arithmetic with circuits,
  * "GateMatrix + GateMatrix" -- see arithmetic with circuits,
  * "GateMatrix + Matrix" -- see arithmetic with circuits,
  * "GateMatrix - GateMatrix" -- see arithmetic with circuits,
  * "GateMatrix - Matrix" -- see arithmetic with circuits,
  * "GateMatrix ^ List" -- see arithmetic with circuits,
  * "Matrix * GateMatrix" -- see arithmetic with circuits,
  * "Matrix + GateMatrix" -- see arithmetic with circuits,
  * "Matrix - GateMatrix" -- see arithmetic with circuits,
  * "RingElement * GateMatrix" -- see arithmetic with circuits,
  * cCode(GateMatrix,GateMatrix,File) (missing documentation)
  * "compress(GateMatrix)" -- see compressing circuits,
  * detGate(GateMatrix) (missing documentation)
  * "diff(GateMatrix,GateMatrix)" -- see differentiating circuits,
  * "diff(InputGate,GateMatrix)" -- see differentiating circuits,
  * "value(GateMatrix,ValueHashTable)" -- see evaluating gates,
  * flatten(GateMatrix) (missing documentation)
  * "gateMatrix(GateMatrix)" -- see gateMatrix, -- create a
    GateMatrix
  * makeCompiledSLProgram(GateMatrix,GateMatrix) (missing documentation)
  * "makeInterpretedSLProgram(GateMatrix,GateMatrix)" -- see
    makeInterpretedSLProgram, -- create a
    straight-line program
  * "makeSLProgram(GateMatrix,GateMatrix)" -- see makeSLProgram,
    -- create a straight-line program (either interpreted or
    compiled)
  * matrix(GateMatrix) (missing documentation)
  * "countGates(GateMatrix)" -- see measuring the size of circuits,
  * "depth(GateMatrix)" -- see measuring the size of circuits,
  * "determinant(GateMatrix)" -- see working with gate matrices,
  * "entries(GateMatrix)" -- see working with gate matrices,
  * "GateMatrix _ List" -- see working with gate matrices,
  * "GateMatrix _ Sequence" -- see working with gate matrices,
  * "GateMatrix | GateMatrix" -- see working with gate matrices,
  * "GateMatrix | Matrix" -- see working with gate matrices,
  * "GateMatrix || GateMatrix" -- see working with gate matrices,
  * "GateMatrix || Matrix" -- see working with gate matrices,
  * "Matrix | GateMatrix" -- see working with gate matrices,
  * "Matrix || GateMatrix" -- see working with gate matrices,
  * "numColumns(GateMatrix)" -- see working with gate matrices,
  * "numRows(GateMatrix)" -- see working with gate matrices,
  * "submatrix(GateMatrix,List,List)" -- see working with gate matrices,
  * "substitute(GateMatrix,GateMatrix,GateMatrix)" -- see working with gate matrices,
  * "substitute(GateMatrix,HashTable)" -- see working with gate matrices,
  * "substitute(GateMatrix,List)" -- see working with gate matrices,
  * "substitute(GateMatrix,Option)" -- see working with gate matrices,
  * "transpose(GateMatrix)" -- see working with gate matrices,

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

The object GateMatrix, is a type (Macaulay2Doc),
with ancestor classes List (Macaulay2Doc), < VisibleList (Macaulay2Doc)
< BasicList (Macaulay2Doc) <
Thing (Macaulay2Doc).

gateMatrix -- create a GateMatrix
*********************************

Synopsis
========

  * Usage:
        gateMatrix M
  * Inputs:
      * M, a matrix (Macaulay2Doc), or a table (a nested
        List (Macaulay2Doc))
  * Outputs:
      * an instance of the type GateMatrix,

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

This methods creates a GateMatrix, from the given input data,
which should be a matrix or a doubly-nested list.

The package SLPexpressions, overrides matrix (Macaulay2Doc),
to allow a table (a nested list) of Gate,s as
an argument.

+-----------------------------------------------------------------------------+
|i1 : declareVariable x; declareVariable y;                                   |
+-----------------------------------------------------------------------------+
|i3 : A = matrix { apply(5,i->i*x) }                                          |
|                                                                             |
|o3 = {{0, x, (2 * x), (3 * x), (4 * x)}}                                     |
|                                                                             |
|o3 : GateMatrix                                                              |
+-----------------------------------------------------------------------------+
|i4 : A#0                                                                     |
|                                                                             |
|o4 = {0, x, (2 * x), (3 * x), (4 * x)}                                       |
|                                                                             |
|o4 : List                                                                    |
+-----------------------------------------------------------------------------+
|i5 : A#0#0                                                                   |
|                                                                             |
|o5 = 0                                                                       |
|                                                                             |
|o5 : InputGate                                                               |
+-----------------------------------------------------------------------------+
|i6 : B = matrix { apply(4,i->y^i) }                                          |
|                                                                             |
|o6 = {{1, (y), (y * y), (y * y * y)}}                                        |
|                                                                             |
|o6 : GateMatrix                                                              |
+-----------------------------------------------------------------------------+
|i7 : C = transpose A * B                                                     |
|                                                                             |
|o7 = {{(0), (0), (0), (0)}, {(x), ((x * (y))), ((x * (y * y))), ((x * (y * y |
|     ------------------------------------------------------------------------|
|     * y)))}, {((2 * x)), (((2 * x) * (y))), (((2 * x) * (y * y))), (((2 * x)|
|     ------------------------------------------------------------------------|
|     * (y * y * y)))}, {((3 * x)), (((3 * x) * (y))), (((3 * x) * (y * y))), |
|     ------------------------------------------------------------------------|
|     (((3 * x) * (y * y * y)))}, {((4 * x)), (((4 * x) * (y))), (((4 * x) *  |
|     ------------------------------------------------------------------------|
|     (y * y))), (((4 * x) * (y * y * y)))}}                                  |
|                                                                             |
|o7 : GateMatrix                                                              |
+-----------------------------------------------------------------------------+
|i8 : numrows C, numcols C                                                    |
|                                                                             |
|o8 = (5, 4)                                                                  |
|                                                                             |
|o8 : Sequence                                                                |
+-----------------------------------------------------------------------------+

See also
========

  * GateMatrix -- a matrix of Gates

Ways to use gateMatrix :
========================

  * "gateMatrix(GateMatrix)"
  * "gateMatrix(List)"
  * "gateMatrix(Matrix)"

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

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

gatePolynomial -- creates an input gate for a given polynomial
**************************************************************

Synopsis
========

  * Usage:
        gatePolynomial f
  * Inputs:
      * f, a ring element (Macaulay2Doc),
  * Outputs:
      * an instance of the type Gate, representing the polynomial
        $f$

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

This methods creates a Gate, from the given input polynomial $f$.
The resulting Gate, is a SumGate, whose terms are
product gates, corresponding to monomials of $f$.

+-----------------------------------------------------------------------------+
|i1 : R = QQ[x,y]                                                             |
|                                                                             |
|o1 = R                                                                       |
|                                                                             |
|o1 : PolynomialRing                                                          |
+-----------------------------------------------------------------------------+
|i2 : f = random(3, R)                                                        |
|                                                                             |
|     9 3   1 2    9   2   1 3                                                |
|o2 = -x  + -x y + -x*y  + -y                                                 |
|     2     2      4       2                                                  |
|                                                                             |
|o2 : R                                                                       |
+-----------------------------------------------------------------------------+
|i3 : gatePolynomial f                                                        |
|                                                                             |
|       9                         1                             9             |
|o3 = ((- * ([x] * [x] * [x])) + (- * (([x] * [x]) * ([y]))) + (- * (([x]) *  |
|       2                         2                             4             |
|                                                                             |
|o3 : SumGate                                                                 |
|-----------------------------------------------------------------------------|
|                 1                                                           |
|([y] * [y]))) + (- * ([y] * [y] * [y])))                                     |
|                 2                                                           |
+-----------------------------------------------------------------------------+

See also
========

  * Gate -- the class of all gates

Ways to use gatePolynomial :
============================

  * "gatePolynomial(Matrix)"
  * "gatePolynomial(RingElement)"

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

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

getVarGates -- returns the input gates for variables in a polynomial ring
*************************************************************************

Synopsis
========

  * Usage:
        getVarGates R
  * Inputs:
      * R, a polynomial ring (Macaulay2Doc),
  * Outputs:
      * a list (Macaulay2Doc), of input gates for the variables in
        $R$

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

This methods returns a List (Macaulay2Doc), of input gates,
corresponding to variables in the given polynomial $R$, and caches the
result in the ring for future use.

+-------------------+
|i1 : R = QQ[x,y]   |
|                   |
|o1 = R             |
|                   |
|o1 : PolynomialRing|
+-------------------+
|i2 : getVarGates R |
|                   |
|o2 = {[x], [y]}    |
|                   |
|o2 : List          |
+-------------------+

See also
========

  * Gate -- the class of all gates

Ways to use getVarGates :
=========================

  * "getVarGates(PolynomialRing)"

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

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

isConstant(InputGate) -- whether an input gate is constant
**********************************************************

Synopsis
========

  * Function: isConstant (Macaulay2Doc),
  * Usage:
        isConstant g
  * Inputs:
      * g, an instance of the type InputGate,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether g is a constant

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

An input gate is constant if its Name (Macaulay2Doc), is
either a Number (Macaulay2Doc), or a RingElement (Macaulay2Doc).

+----------------------+
|i1 : declareVariable X|
|                      |
|o1 = X                |
|                      |
|o1 : InputGate        |
+----------------------+
|i2 : isConstant X     |
|                      |
|o2 = false            |
+----------------------+
|i3 : isConstant 3     |
|                      |
|o3 = true             |
+----------------------+

See also
========

  * InputGate -- the class of all gates

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

  * isConstant(InputGate) -- whether an input
    gate is constant

makeCompiledSLProgram
*********************

Ways to use makeCompiledSLProgram :
===================================

  * makeCompiledSLProgram(GateMatrix,GateMatrix) (missing documentation)
  * makeCompiledSLProgram(List,List) (missing documentation)

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

The object makeCompiledSLProgram (missing documentation) is a method function (Macaulay2Doc).

makeInterpretedSLProgram -- create a straight-line program
**********************************************************

Synopsis
========

  * Usage:
        makeInterpretedSLProgram(inL, outL)
  * Inputs:
      * inL, a list (Macaulay2Doc), of inputs
      * outL, a list (Macaulay2Doc), of outputs
  * Outputs:
      * an instance of the type InterpretedSLProgram,

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

This method returns an object of type InterpretedSLProgram,
which encodes a method for evaluating an algebraic
circuit.

+-----------------------------------------------------------------------------+
|i1 : declareVariable X; declareVariable C;                                   |
+-----------------------------------------------------------------------------+
|i3 : XpC = X+C                                                               |
|                                                                             |
|o3 = (X + C)                                                                 |
|                                                                             |
|o3 : SumGate                                                                 |
+-----------------------------------------------------------------------------+
|i4 : XXC = productGate{X,X,C}                                                |
|                                                                             |
|o4 = (X * X * C)                                                             |
|                                                                             |
|o4 : ProductGate                                                             |
+-----------------------------------------------------------------------------+
|i5 : detXCCX = detGate{{X,C},{C,X}}                                          |
|                                                                             |
|o5 = det| X C |                                                              |
|        | C X |                                                              |
|                                                                             |
|o5 : DetGate                                                                 |
+-----------------------------------------------------------------------------+
|i6 : XoC = X/C                                                               |
|                                                                             |
|     X                                                                       |
|o6 = -                                                                       |
|     C                                                                       |
|                                                                             |
|o6 : DivideGate                                                              |
+-----------------------------------------------------------------------------+
|i7 : slp = makeInterpretedSLProgram(matrix{{C,X}},matrix{{XXC,detXCCX,XoC,XpC|
|                                                                             |
|o7 = InterpretedSLProgram{cache => CacheTable{}              }               |
|                          "constant positions" => {-3}                       |
|                          "constants" => | 2 |                               |
|                          "number of inputs" => 2                            |
|                          "number of outputs" => 4                           |
|                          RawSLProgram => SLProgram (                        |
|                                            consts+vars: 3                   |
|                                            noninput nodes: 5                |
|                                            output nodes: 4                  |
|                                            )                                |
|                                                                             |
|                          "variable positions" => {-1, -2}                   |
|                                                                             |
|o7 : InterpretedSLProgram                                                    |
|-----------------------------------------------------------------------------|
|+2}})                                                                        |
+-----------------------------------------------------------------------------+

See also
========

  * evaluate(SLProgram,MutableMatrix,MutableMatrix)
    -- evaluate a
    straight-line program

Ways to use makeInterpretedSLProgram :
======================================

  * "makeInterpretedSLProgram(GateMatrix,GateMatrix)"
  * "makeInterpretedSLProgram(List,List)"

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

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

makeSLProgram -- create a straight-line program (either interpreted or compiled)
********************************************************************************

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

Passes the arguments to makeInterpretedSLProgram,
or makeCompiledSLProgram (missing documentation)
depending on the flag set by setTryJustInTimeCompilation.
(Giving `true` as a value triggers a search for gnu C++ compiler and, if
successful, makes a makeCompiledSLProgram (missing documentation) the default
choice. Currently, just-in-time compilation works over RR_53 and CC_53)

Ways to use makeSLProgram :
===========================

  * "makeSLProgram(GateMatrix,GateMatrix)"
  * "makeSLProgram(List,List)"

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

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

measuring the size of circuits
******************************

Synopsis
========

  * Usage:
        d = depth g
        d = depth G
        H = countGates g
        H = countGates G
  * Inputs:
      * g, an instance of the type Gate,
      * G, an instance of the type GateMatrix,
  * Outputs:
      * d, an integer (Macaulay2Doc), circuit depth
      * H, a hash table (Macaulay2Doc), total number of gates
        of each type

The depth of an algebraic circuit is the length of the longest path of
evaluations from any input gate to any output gate.

+----------------------------------------------------+
|i1 : declareVariable x                              |
|                                                    |
|o1 = x                                              |
|                                                    |
|o1 : InputGate                                      |
+----------------------------------------------------+
|i2 : f = x + 1                                      |
|                                                    |
|o2 = (x + 1)                                        |
|                                                    |
|o2 : SumGate                                        |
+----------------------------------------------------+
|i3 : n = 12;                                        |
+----------------------------------------------------+
|i4 : for i from 1 to n do f = f*f -- f = (x+1)^(2^n)|
+----------------------------------------------------+
|i5 : depth f                                        |
|                                                    |
|o5 = 13                                             |
+----------------------------------------------------+

depth is not the sole indicator of circuit complexity. For instance, the total
number of gates in a circuit (sometimes referred to as its "size") also plays a
role. "countGates" returns the number of constituent Gate,s
according to their type.

+--------------------------------------------------------------------+
|i6 : x = symbol x                                                   |
|                                                                    |
|o6 = x                                                              |
|                                                                    |
|o6 : Symbol                                                         |
+--------------------------------------------------------------------+
|i7 : n = 8                                                          |
|                                                                    |
|o7 = 8                                                              |
+--------------------------------------------------------------------+
|i8 : varGates = declareVariable \ for i from 1 to n list x_i        |
|                                                                    |
|o8 = {x , x , x , x , x , x , x , x }                               |
|       1   2   3   4   5   6   7   8                                |
|                                                                    |
|o8 : List                                                           |
+--------------------------------------------------------------------+
|i9 : G1 = gateMatrix{{x_1+x_2+x_3+x_4+x_5+x_6+x_7+x_8}}             |
|                                                                    |
|o9 = {{(((((((x  + x ) + x ) + x ) + x ) + x ) + x ) + x )}}        |
|               1    2     3     4     5     6     7     8           |
|                                                                    |
|o9 : GateMatrix                                                     |
+--------------------------------------------------------------------+
|i10 : G2 = gateMatrix{{((x_1+x_2)+(x_3+x_4))+((x_5+x_6)+(x_7+x_8))}}|
|                                                                    |
|o10 = {{(((x  + x ) + (x  + x )) + ((x  + x ) + (x  + x )))}}       |
|            1    2      3    4        5    6      7    8            |
|                                                                    |
|o10 : GateMatrix                                                    |
+--------------------------------------------------------------------+
|i11 : depth G1                                                      |
|                                                                    |
|o11 = 7                                                             |
+--------------------------------------------------------------------+
|i12 : depth G2                                                      |
|                                                                    |
|o12 = 3                                                             |
+--------------------------------------------------------------------+
|i13 : countGates G1                                                 |
|                                                                    |
|o13 = HashTable{cache => CacheTable{...15...}}                      |
|                InputGate => 8                                      |
|                SumGate => 7                                        |
|                                                                    |
|o13 : HashTable                                                     |
+--------------------------------------------------------------------+
|i14 : countGates G2                                                 |
|                                                                    |
|o14 = HashTable{cache => CacheTable{...15...}}                      |
|                InputGate => 8                                      |
|                SumGate => 7                                        |
|                                                                    |
|o14 : HashTable                                                     |
+--------------------------------------------------------------------+

See also
========

  * compressing circuits

SLProgram
*********

Types of SLProgram :
====================

  * CompiledSLProgram (missing documentation)
  * "InterpretedSLProgram" -- see makeInterpretedSLProgram,
    -- create a straight-line program

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

  * "evaluate(SLProgram,Matrix)" -- see
    evaluate(SLProgram,MutableMatrix,MutableMatrix),
    -- evaluate a
    straight-line program
  * evaluate(SLProgram,MutableMatrix,MutableMatrix)
    -- evaluate a
    straight-line program

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

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

undeclareVariable -- clears assignment of an input gate to a variable name
**************************************************************************

Synopsis
========

  * Usage:
        undeclareVariable x
  * Inputs:
      * x, a symbol (Macaulay2Doc), or an IndexedVariable (Macaulay2Doc),
  * Outputs:
      * an instance of the type InputGate,

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

This method undoes the action of declareVariable, by
reverting the assignment of an InputGate, to a symbol.

+------------------------+
|i1 : declareVariable x  |
|                        |
|o1 = x                  |
|                        |
|o1 : InputGate          |
+------------------------+
|i2 : x + 1              |
|                        |
|o2 = (x + 1)            |
|                        |
|o2 : SumGate            |
+------------------------+
|i3 : undeclareVariable x|
|                        |
|o3 = x                  |
|                        |
|o3 : Symbol             |
+------------------------+
|i4 : x                  |
|                        |
|o4 = x                  |
|                        |
|o4 : Symbol             |
+------------------------+

See also
========

  * declareVariable -- assigns an input gate to a given
    variable name

Ways to use undeclareVariable :
===============================

  * "undeclareVariable(InputGate)"

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

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

valueHashTable -- creates a hash table of values for evaluation
***************************************************************

Synopsis
========

  * Usage:
        valueHashTable(L1, L2)
  * Inputs:
      * L1, a list (Macaulay2Doc), of InputGate,s
      * L2, a list (Macaulay2Doc), of values
  * Outputs:
      * an instance of the type ValueHashTable,

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

This methods creates an object of type ValueHashTable,
from a List (Macaulay2Doc), of InputGate,s and a
List (Macaulay2Doc), of corresponding values. The evaluations of the input
gates at the values can be performed using the method value (Macaulay2Doc).

+-------------------------------------+
|i1 : declareVariable X               |
|                                     |
|o1 = X                               |
|                                     |
|o1 : InputGate                       |
+-------------------------------------+
|i2 : declareVariable Y               |
|                                     |
|o2 = Y                               |
|                                     |
|o2 : InputGate                       |
+-------------------------------------+
|i3 : h = valueHashTable({X,Y},{1,ii})|
|                                     |
|o3 = ValueHashTable{...2...}         |
|                                     |
|o3 : ValueHashTable                  |
+-------------------------------------+
|i4 : peek h                          |
|                                     |
|o4 = ValueHashTable{X => 1 }         |
|                    Y => ii          |
+-------------------------------------+

See also
========

  * evaluating gates

Ways to use valueHashTable :
============================

  * "valueHashTable(List,List)"

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

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

working with gate matrices
**************************

Many typical matrix operations can also be performed on gate matrices,
such as obtaining entries, number of rows and columns, transpose,
and vertical or horizontal concatenation.

+----------------------------------------------------------------+
|i1 : R = RR[x,y]                                                |
|                                                                |
|o1 = R                                                          |
|                                                                |
|o1 : PolynomialRing                                             |
+----------------------------------------------------------------+
|i2 : M = gateMatrix basis(3, R)                                 |
|-- warning: experimental computation over inexact field begun   |
|--          results not reliable (one warning given per session)|
|                                                                |
|        3   2      2   3                                        |
|o2 = {{x , x y, x*y , y }}                                      |
|                                                                |
|o2 : GateMatrix                                                 |
+----------------------------------------------------------------+
|i3 : numcols M, numrows M                                       |
|                                                                |
|o3 = (4, 1)                                                     |
|                                                                |
|o3 : Sequence                                                   |
+----------------------------------------------------------------+

Rows or entries can be accessed with &#95; or #:

+--------------------------+
|i4 : M_0                  |
|                          |
|       3   2      2   3   |
|o4 = {x , x y, x*y , y }  |
|                          |
|o4 : List                 |
+--------------------------+
|i5 : M#0                  |
|                          |
|       3   2      2   3   |
|o5 = {x , x y, x*y , y }  |
|                          |
|o5 : List                 |
+--------------------------+
|i6 : M#0#0                |
|                          |
|      3                   |
|o6 = x                    |
|                          |
|o6 : InputGate            |
+--------------------------+
|i7 : entries M            |
|                          |
|        3   2      2   3  |
|o7 = {{x , x y, x*y , y }}|
|                          |
|o7 : List                 |
+--------------------------+

Horizontal (resp. vertical) concatenation is done with |,
(resp. see ||):

+------------------------------------------------------------------+
|i8 : N = gateMatrix {delete(x^2*y^2, flatten entries basis(4, R))}|
|                                                                  |
|        4   3      3   4                                          |
|o8 = {{x , x y, x*y , y }}                                        |
|                                                                  |
|o8 : GateMatrix                                                   |
+------------------------------------------------------------------+
|i9 : M | N                                                        |
|                                                                  |
|        3   2      2   3   4   3      3   4                       |
|o9 = {{x , x y, x*y , y , x , x y, x*y , y }}                     |
|                                                                  |
|o9 : GateMatrix                                                   |
+------------------------------------------------------------------+
|i10 : M || N                                                      |
|                                                                  |
|         3   2      2   3     4   3      3   4                    |
|o10 = {{x , x y, x*y , y }, {x , x y, x*y , y }}                  |
|                                                                  |
|o10 : GateMatrix                                                  |
+------------------------------------------------------------------+

The determinant of a gate matrix is a DetGate,:

+-----------------------------------------------------------------------------+
|i11 : P = transpose M*M                                                      |
|                                                                             |
|           3    3       3    2        3      2       3    3         2        |
|o11 = {{((x  * x )), ((x  * x y)), ((x  * x*y )), ((x  * y ))}, {((x y *     |
|      -----------------------------------------------------------------------|
|       3       2     2        2       2       2     3           2    3       |
|      x )), ((x y * x y)), ((x y * x*y )), ((x y * y ))}, {((x*y  * x )),    |
|      -----------------------------------------------------------------------|
|           2    2          2      2         2    3         3    3       3    |
|      ((x*y  * x y)), ((x*y  * x*y )), ((x*y  * y ))}, {((y  * x )), ((y  *  |
|      -----------------------------------------------------------------------|
|       2        3      2       3    3                                        |
|      x y)), ((y  * x*y )), ((y  * y ))}}                                    |
|                                                                             |
|o11 : GateMatrix                                                             |
+-----------------------------------------------------------------------------+
|i12 : det P                                                                  |
|                                                                             |
|o12 = det|    3    3        3    2         3      2        3    3     |      |
|         | ((x  * x ))   ((x  * x y))   ((x  * x*y ))   ((x  * y ))   |      |
|         |    2     3       2     2        2       2       2     3    |      |
|         | ((x y * x ))  ((x y * x y))  ((x y * x*y ))  ((x y * y ))  |      |
|         |      2    3        2    2         2      2        2    3   |      |
|         | ((x*y  * x )) ((x*y  * x y)) ((x*y  * x*y )) ((x*y  * y )) |      |
|         |    3    3        3    2         3      2        3    3     |      |
|         | ((y  * x ))   ((y  * x y))   ((y  * x*y ))   ((y  * y ))   |      |
|                                                                             |
|o12 : DetGate                                                                |
+-----------------------------------------------------------------------------+

The native method substitute (Macaulay2Doc), has also been
overloaded to work with gate matrices: the input should be a list of
options (Macaulay2Doc), of the form "A => B" where A is an
InputGate, and B is a Gate,; and the output is another
GateMatrix.

See also
========

  * GateMatrix -- a matrix of Gates