\section{constraints}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
  Minion supports many constraints and these are regularly being
  improved and added to. In some cases multiple implementations of the
  same constraints are provided and we would appreciate additional
  feedback on their relative merits in your problem.

  Minion does not support nesting of constraints, however this can be
  achieved by auxiliary variables and reification.

  Variables can be replaced by constants. You can find out more on
  expressions for variables, vectors, etc. in the section on variables.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  help variables
\end{verbatim}
}
\section{constraints abs}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   abs(x,y)

makes sure that x=|y|, i.e. x is the absolute value of y.
\end{verbatim}
}
\paragraph{Reference}
{\footnotesize
\begin{verbatim}
help constraints abs
\end{verbatim}
}
\section{constraints alldiff}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Forces the input vector of variables to take distinct values.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
Suppose the input file had the following vector of variables defined:

DISCRETE myVec[9] {1..9}

To ensure that each variable takes a different value include the
following constraint:

alldiff(myVec)
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
Enforces the same level of consistency as a clique of not equals
constraints.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See

   help constraints gacalldiff

for the same constraint that enforces GAC.
\end{verbatim}
}
\section{constraints alldiffciaran}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Forces the input vector of variables to take distinct values. This is for experiment only.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint enforces an unknown consistency.
\end{verbatim}
}
\section{constraints alldiffmatrix}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
For a latin square this constraint is placed on the whole matrix once for each
value.
It ensures there is a bipartite matching between rows and columns where the
edges
in the matching correspond to a pair (row, column) where the variable in
position
(row,column) in the matrix may be assigned to the given value.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}

alldiffmatrix(myVec, Value)
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint adds some extra reasoning in addition to the GAC Alldifferents
on the rows and columns.
\end{verbatim}
}
\section{constraints difference}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   difference(x,y,z)

ensures that z=|x-y| in any solution.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint can be expressed in a much longer form, this form both avoids
requiring an extra variable, and also gets better propagation. It gets bounds
consistency.
\end{verbatim}
}
\section{constraints diseq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Constrain two variables to take different values.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
Achieves arc consistency.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
diseq(v0,v1)
\end{verbatim}
}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Constrain two variables to take different values.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
Achieves arc consistency.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
diseq(v0,v1)
\end{verbatim}
}
\section{constraints div}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   div(x,y,z)

ensures that floor(x/y)=z.

For example:

10/3 = 3
(-10)/3 = -4
10/(-3) = -4
(-10)/(-3) = 3

div and mod satisfy together the condition that:

y*(x/y) + x % y = x

The constraint is always false when y = 0
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints modulo
\end{verbatim}
}
\section{constraints div\textunderscore undefzero}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   div_undefzero(x,y,z)

is the same as div (it ensures that floor(x/y)=z)
except the constraint is always true when y = 0,
instead of false.

This constraint exists for certain special requirements.
In general, if you are unsure what constraint to use,
then what you want is a plain div constraint!
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints div
\end{verbatim}
}
\section{constraints element}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   element(vec, i, e)

specifies that, in any solution, vec[i] = e and i is in the range
[0 .. |vec|-1].
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}

Warning: This constraint is not confluent. Depending on the order the
propagators are called in Minion, the number of search nodes may vary when
using element. To avoid this problem, use watchelement instead. More details
below.

The level of propagation enforced by this constraint is not named, however it
works as follows. For constraint vec[i]=e:

- After i is assigned, ensures that min(vec[i]) = min(e) and
  max(vec[i]) = max(e).

- When e is assigned, removes idx from the domain of i whenever e is not an
  element of the domain of vec[idx].

- When m[idx] is assigned, removes idx from i when m[idx] is not in the domain
  of e.

This level of consistency is designed to avoid the propagator having to scan
through vec, except when e is assigned. It does a quantity of cheap propagation
and may work well in practise on certain problems.

Element is not confluent, which may cause the number of search nodes to vary
depending on the order in which constraints are listed in the input file, or
the order they are called in Minion. For example, the following input causes
Minion to search 41 nodes.

MINION 3
**VARIABLES**
DISCRETE x[5] {1..5}
**CONSTRAINTS**
element([x[0],x[1],x[2]], x[3], x[4])
alldiff([x])
**EOF**

However if the two constraints are swapped over, Minion explores 29 nodes.
As a rule of thumb, to get a lower node count, move element constraints
to the end of the list.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See the entry

   constraints watchelement

for details of an identical constraint that enforces generalised arc
consistency.
\end{verbatim}
}
\section{constraints element\textunderscore one}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint element one is identical to element, except that the
vector is indexed from 1 rather than from 0.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See

   help constraints element

for details of the element constraint which is almost identical to this
one.
\end{verbatim}
}
\section{constraints eq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Constrain two variables to take equal values.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
eq(x0,x1)
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
Achieves bounds consistency.
\end{verbatim}
}
\paragraph{Reference}
{\footnotesize
\begin{verbatim}
help constraints minuseq
\end{verbatim}
}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Constrain two variables to take equal values.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
eq(x0,x1)
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
Achieves bounds consistency.
\end{verbatim}
}
\paragraph{Reference}
{\footnotesize
\begin{verbatim}
help constraints minuseq
\end{verbatim}
}
\section{constraints gacalldiff}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Forces the input vector of variables to take distinct values.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
Suppose the input file had the following vector of variables defined:

DISCRETE myVec[9] {1..9}

To ensure that each variable takes a different value include the
following constraint:

gacalldiff(myVec)
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint enforces generalized arc consistency.
\end{verbatim}
}
\section{constraints gacschema}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
An extensional constraint that enforces GAC. The constraint is
specified via a list of tuples.

The format, and usage of gacschema, is identical to the 'table' constraint.
It is difficult to predict which out of 'table' and 'gacschema' will be faster
for any particular problem.
\end{verbatim}
}
\section{constraints gcc}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The Generalized Cardinality Constraint (GCC) constrains the number of each value
that a set of variables can take.

gcc([primary variables], [values of interest], [capacity variables])

For each value of interest, there must be a capacity variable, which specifies
the number of occurrences of the value in the primary variables.

This constraint only restricts the number of occurrences of the values in
the value list. There is no restriction on the occurrences of other values.
Therefore the semantics of gcc are identical to a set of occurrence
constraints:

occurrence([primary variables], val1, cap1)
occurrence([primary variables], val2, cap2)
...
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
Suppose the input file had the following vectors of variables defined:

DISCRETE myVec[9] {1..9}
BOUND cap[9] {0..2}

The following constraint would restrict the occurrence of values 1..9 in myVec
to be at most 2 each initially, and finally equal to the values of the cap
vector.

gcc(myVec, [1,2,3,4,5,6,7,8,9], cap)
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint enforces a hybrid consistency. It reads the bounds of the
capacity variables, then enforces GAC over the primary variables only.  Then the
bounds of the capacity variables are updated using flow algorithms similar to
those proposed by Quimper et al, Improved Algorithms for the Global Cardinality
Constraint (CP 2004).

This constraint provides stronger propagation to the capacity variables than the
gccweak constraint.
\end{verbatim}
}
\section{constraints gccweak}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The Generalized Cardinality Constraint (GCC) (weak variant) constrains the
number of each value that a set of variables can take.

gccweak([primary variables], [values of interest], [capacity variables])

For each value of interest, there must be a capacity variable, which specifies
the number of occurrences of the value in the primary variables.

This constraint only restricts the number of occurrences of the values in
the value list. There is no restriction on the occurrences of other values.
Therefore the semantics of gccweak are identical to a set of occurrence
constraints:

occurrence([primary variables], val1, cap1)
occurrence([primary variables], val2, cap2)
...
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
Suppose the input file had the following vectors of variables defined:

DISCRETE myVec[9] {1..9}
BOUND cap[9] {0..2}

The following constraint would restrict the occurrence of values 1..9 in myVec
to be at most 2 each initially, and finally equal to the values of the cap
vector.

gccweak(myVec, [1,2,3,4,5,6,7,8,9], cap)
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint enforces a hybrid consistency. It reads the bounds of the
capacity variables, then enforces GAC over the primary variables only.  Then the
bounds of the capacity variables are updated by counting values in the domains
of the primary variables.

The consistency over the capacity variables is weaker than the gcc constraint,
hence the name gccweak.
\end{verbatim}
}
\section{constraints haggisgac}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
An extensional constraint that enforces GAC. This constraint make uses
of 'short tuples', which allow some values to be marked as don't care.
When this allows the set of tuples to be reduced in size, this leads to
performance gains.

The variables used in the constraint have to be BOOL or DISCRETE variables.
Other types are not supported.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}

Consider the constraint 'min([x1,x2,x3],x4)'' on Booleans variables
x1,x2,x3,x4.

Represented as a TUPLELIST for a table or gacschema constraint, this would
look like:

**TUPLELIST**
mycon 8 4
0 0 0 0
0 0 1 0
0 1 0 0
0 1 1 0
1 0 0 0
1 0 1 0
1 1 0 0
1 1 1 1

Short tuples give us a way of shrinking this list. Short tuples consist
of pairs (x,y), where x is a varible position, and y is a value for that
variable. For example:

[(0,0),(3,0)]

Represents 'If the variable at index 0 is 0, and the variable at index
3 is 0, then the constraint is true'.

This allows us to represent our constraint as follows:

**SHORTTUPLELIST**
mycon 4
[(0,0),(3,0)]
[(1,0),(3,0)]
[(2,0),(3,0)]
[(0,1),(1,1),(2,1),(3,1)]

Note that some tuples are double-represented here. The first 3 short
tuples all allow the assignment '0 0 0 0'. This is fine. The important
thing for efficency is to try to give a small list of short tuples.

We use this tuple by writing:

haggisgac([x1,x2,x3,x4], mycon)

and now the variables [x1,x2,x3,x4] will satisfy the constraint mycon.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help input shorttuplelist
help constraints table
help constraints negativetable
help constraints shortstr2
\end{verbatim}
}
\section{constraints haggisgac-stable}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
An extensional constraint that enforces GAC. haggisgac-stable
is a variant of haggisgac which uses less memory in some cases,
and can also be faster (or slower). The input is identical to
haggisgac.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints haggisgac
\end{verbatim}
}
\section{constraints hamming}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   hamming(X,Y,c)

ensures that the hamming distance between X and Y is at least c. That is, that
the size of the set {i | X[i] != y[i]} is greater than or equal to c.
\end{verbatim}
}
\section{constraints ineq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   ineq(x, y, k)

ensures that

   x <= y + k

in any solution.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
Minion has no strict inequality (<) constraints. However x < y can be
achieved by

   ineq(x, y, -1)
\end{verbatim}
}
\section{constraints lexleq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   lexleq(vec0, vec1)

takes two vectors vec0 and vec1 of the same length and ensures that
vec0 is lexicographically less than or equal to vec1 in any solution.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraints achieves GAC.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See also

   help constraints lexless

for a similar constraint with strict lexicographic inequality.
\end{verbatim}
}
\section{constraints lexleq[rv]}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
  The constraint

  lexle[rv](vec0, vec1)

  takes two vectors vec0 and vec1 of the same length and ensures that
  vec0 is lexicographically less than or equal to vec1 in any solution.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
  This constraint achieves GAC even when some variables are repeated in
  vec0 and vec1. However, the extra propagation this achieves is rarely
  worth the extra work.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints lexleq[quick]

  for a much faster logically identical constraint, with lower
  propagation.
\end{verbatim}
}
\section{constraints lexless}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   lexless(vec0, vec1)

takes two vectors vec0 and vec1 of the same length and ensures that
vec0 is lexicographically less than vec1 in any solution.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint maintains GAC.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See also

   help constraints lexleq

for a similar constraint with non-strict lexicographic inequality.
\end{verbatim}
}
\section{constraints lighttable}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
An extensional constraint that enforces GAC. The constraint is
specified via a list of tuples. lighttable is a variant of the
table constraint that is stateless and potentially faster
for small constraints.

For full documentation, see the help for the table constraint.
\end{verbatim}
}
\section{constraints litsumgeq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint litsumgeq(vec1, vec2, c) ensures that there exists at least c
distinct indices i such that vec1[i] = vec2[i].
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
A SAT clause {x,y,z} can be created using:

   litsumgeq([x,y,z],[1,1,1],1)

Note also that this constraint is more efficient for smaller values of c. For
large values consider using watchsumleq.
\end{verbatim}
}
\paragraph{Reifiability}
{\footnotesize
\begin{verbatim}
This constraint is not reifiable.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See also

   help constraints watchsumleq
   help constraints watchsumgeq
\end{verbatim}
}
\section{constraints max}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   max(vec, x)

ensures that x is equal to the maximum value of any variable in vec.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See

   help constraints min

for the opposite constraint.
\end{verbatim}
}
\section{constraints mddc}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
MDDC (mddc) is an implementation of MDDC(sp) by Cheng and Yap. It enforces GAC
on a
constraint using a multi-valued decision diagram (MDD).

The MDD required for the propagator is constructed from a set of satisfying
tuples. The constraint has the same syntax as 'table' and can function
as a drop-in replacement.

For examples on how to call it, see the help for 'table'. Substitute 'mddc' for
'table'.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint enforces generalized arc consistency.
\end{verbatim}
}
\section{constraints min}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   min(vec, x)

ensures that x is equal to the minimum value of any variable in vec.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See

   help constraints max

for the opposite constraint.
\end{verbatim}
}
\section{constraints minuseq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Constraint

   minuseq(x,y)

ensures that x=-y.
\end{verbatim}
}
\paragraph{Reference}
{\footnotesize
\begin{verbatim}
help constraints eq
\end{verbatim}
}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Constraint

   minuseq(x,y)

ensures that x=-y.
\end{verbatim}
}
\paragraph{Reference}
{\footnotesize
\begin{verbatim}
help constraints eq
\end{verbatim}
}
\section{constraints mod\textunderscore undefzero}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   mod_undefzero(x,y,z)

is the same as mod except the constraint is always
true when y = 0, instead of false.

This constraint exists for certain special requirements.
In general, if you are unsure what constraint to use,
then what you want is a plain mod constraint!
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints mod
\end{verbatim}
}
\section{constraints modulo}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   modulo(x,y,z)

ensures that x%y=z i.e. z is the remainder of dividing x by y.
For negative values, we ensure that:

y(x/y) + x%y = x

To be fully concrete, here are some examples:

3 % 5 = 3
-3 % 5 = 2
3 % -5 = -2
-3 % -5 = -3
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints div
\end{verbatim}
}
\section{constraints negativemddc}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Negative MDDC (negativemddc) is an implementation of MDDC(sp) by Cheng and Yap.
It enforces GAC on a constraint using a multi-valued decision diagram (MDD).

The MDD required for the propagator is constructed from a set of unsatisfying
(negative) tuples. The constraint has the same syntax as 'negativetable' and
can function as a drop-in replacement.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint enforces generalized arc consistency.
\end{verbatim}
}
\section{constraints negativetable}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
An extensional constraint that enforces GAC. The constraint is
specified via a list of disallowed tuples.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
See entry

   help input negativetable

for how to specify a table constraint in minion input. The only
difference for negativetable is that the specified tuples are
disallowed.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help input table
help input tuplelist
\end{verbatim}
}
\section{constraints nvaluegeq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   nvaluegeq(V,x)

ensures that there are >= x different values assigned to the list of variables
V.
\end{verbatim}
}
\section{constraints nvalueleq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   nvalueleq(V,x)

ensures that there are <= x different values assigned to the list of variables
V.
\end{verbatim}
}
\section{constraints occurrence}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   occurrence(vec, elem, count)

ensures that there are count occurrences of the value elem in the
vector vec.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
elem must be a constant, not a variable.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints occurrenceleq
help constraints occurrencegeq
\end{verbatim}
}
\section{constraints occurrencegeq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   occurrencegeq(vec, elem, count)

ensures that there are AT LEAST count occurrences of the value elem in
the vector vec.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
elem and count must be constants
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints occurrence
help constraints occurrenceleq
\end{verbatim}
}
\section{constraints occurrenceleq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   occurrenceleq(vec, elem, count)

ensures that there are AT MOST count occurrences of the value elem in
the vector vec.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
elem and count must be constants
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints occurrence
help constraints occurrencegeq
\end{verbatim}
}
\section{constraints pow}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   pow(x,y,z)

ensures that x^y=z.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint is only available for positive domains x, y and z.
\end{verbatim}
}
\section{constraints product}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   product(x,y,z)

ensures that z=xy in any solution.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint can be used for (and, in fact, has a specialised
implementation for) achieving boolean AND, i.e. x & y=z can be modelled
as

   product(x,y,z)

The general constraint achieves bounds generalised arc consistency for
positive numbers.
\end{verbatim}
}
\section{constraints reification}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Reification is provided in two forms: reify and reifyimply.

   reify(constraint, r) where r is a 0/1 var

ensures that r is set to 1 if and only if constraint is satisfied. That is, if r
is 0 the constraint must NOT be satisfied; and if r is 1 it must be satisfied as
normal. Conversely, if the constraint is satisfied then r must be 1, and if not
then r must be 0.

   reifyimply(constraint, r)

only checks that if r is set to 1 then constraint must be satisfied. If r is not
1, constraint may be either satisfied or unsatisfied. Furthermore r is never set
by propagation, only by search; that is, satisfaction of constraint does not
affect the value of r.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
ALMOST ALL constraints are are reifiable. Individual constraint entries mention
if the constraint is NOT reifiable.

ALL constraints are reifyimplyable.
\end{verbatim}
}
\section{constraints reify}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See
   help constraints reification
\end{verbatim}
}
\section{constraints reifyimply}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See
   help constraints reification
\end{verbatim}
}
\section{constraints shortctuplestr2}
\paragraph{Description}
{\footnotesize
\begin{verbatim}

This constraint extends the ShortSTR2 algorithm to support short c-tuples
(that is, short tuples which contain can contain more than one domain value
per constraint).
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}

Input format is similar to that used by other short tuple constraints,
such as haggisgac or shortstr2. Refer to the haggisgac and
shorttuplelist pages for more information.

The important change is that more than one literal may be given for each
variable. Variables which are not mentioned are assumed to be allowed
to take any value

Example:

**SHORTTUPLELIST**
mycon 4
[(0,0),(0,1),(3,0)]
[(1,0),(1,2),(3,0)]
[(2,0),(3,0),(3,1)]
[(0,1),(1,1),(2,1),(3,1)]

**CONSTRAINTS**
shortctuplestr2([x1,x2,x3,x4], mycon)
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help input shorttuplelist
help constraints table
help constraints negativetable
help constraints haggisgac
help constraints haggisgac-stable
help constraints shortstr2
\end{verbatim}
}
\section{constraints shortcuplestr2}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint enforces generalized arc consistency.
\end{verbatim}
}
\section{constraints shortstr2}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
ShortSTR2 is the algorithm described in the IJCAI 2013 paper by Jefferson and
Nightingale. It is an extension of STR2+ by Christophe Lecoutre, adapted for
short supports.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}

Input format is exactly the same as haggisgac. Refer to the haggisgac and
shorttuplelist pages for more information.

Example:

**SHORTTUPLELIST**
mycon 4
[(0,0),(3,0)]
[(1,0),(3,0)]
[(2,0),(3,0)]
[(0,1),(1,1),(2,1),(3,1)]

**CONSTRAINTS**
shortstr2([x1,x2,x3,x4], mycon)
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint enforces generalized arc consistency.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help input shorttuplelist
help constraints table
help constraints negativetable
help constraints haggisgac
help constraints haggisgac-stable
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
This constraint enforces generalized arc consistency.
\end{verbatim}
}
\section{constraints str2plus}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
str2plus is an implementation of the STR2+ algorithm by Christophe Lecoutre.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}

str2plus is invoked in the same way as all other table constraints, such
as table and mddc.

str2plus([x,y,z], {<1,2,3>, <1,3,2>})
\end{verbatim}
}
\section{constraints sumgeq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   sumgeq(vec, c)

ensures that sum(vec) >= c.
\end{verbatim}
}
\section{constraints sumleq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   sumleq(vec, c)

ensures that sum(vec) <= c.
\end{verbatim}
}
\section{constraints table}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help input tuplelist
help input table
help input haggisgac
\end{verbatim}
}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
An extensional constraint that enforces GAC. The constraint is
specified via a list of tuples.

The variables used in the constraint have to be BOOL or DISCRETE variables.
Other types are not supported.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
To specify a constraint over 3 variables that allows assignments
(0,0,0), (1,0,0), (0,1,0) or (0,0,1) do the following.

1) Add a tuplelist to the **TUPLELIST** section, e.g.:

**TUPLELIST**
myext 4 3
0 0 0
1 0 0
0 1 0
0 0 1

N.B. the number 4 is the number of tuples in the constraint, the
number 3 is the -arity.

2) Add a table constraint to the **CONSTRAINTS** section, e.g.:

**CONSTRAINTS**
table(myvec, myext)

and now the variables of myvec will satisfy the constraint myext.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
The constraints extension can also be specified in the constraint
definition, e.g.:

table(myvec, {<0,0,0>,<1,0,0>,<0,1,0>,<0,0,1>})
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help input tuplelist
help input gacschema
help input negativetable
help input haggisgac
\end{verbatim}
}
\section{constraints w-inintervalset}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint w-inintervalset(x, [a1,a2, b1,b2, ... ]) ensures that the value
of x belongs to one of the intervals  {a1,...,a2}, {b1,...,b2} etc. The list of
intervals must be given in numerical order.
\end{verbatim}
}
\section{constraints w-inrange}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
  The constraint w-inrange(x, [a,b]) ensures that a <= x <= b.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints w-notinrange
\end{verbatim}
}
\section{constraints w-inset}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint w-inset(x, [a1,...,an]) ensures that x belongs to the set
{a1,..,an}.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints w-notinset
\end{verbatim}
}
\section{constraints w-literal}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
  The constraint w-literal(x, a) ensures that x=a.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints w-notliteral
\end{verbatim}
}
\section{constraints w-notinrange}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
  The constraint w-notinrange(x, [a,b]) ensures that x < a or b < x.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints w-inrange
\end{verbatim}
}
\section{constraints w-notinset}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint w-notinset(x, [a1,...,an]) ensures that x does not belong to the
set {a1,..,an}.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints w-inset
\end{verbatim}
}
\section{constraints w-notliteral}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
  The constraint w-notliteral(x, a) ensures that x =/= a.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints w-literal
\end{verbatim}
}
\section{constraints watched-and}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

  watched-and({C1,...,Cn})

ensures that the constraints C1,...,Cn are all true.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
pointless, bearing in mind that a CSP is simply a conjunction of constraints
already! However sometimes it may be necessary to use a conjunction as a child
of another constraint, for example in a reification:

   reify(watched-and({...}),r)
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints watched-or
\end{verbatim}
}
\section{constraints watched-or}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

  watched-or({C1,...,Cn})

ensures that at least one of the constraints C1,...,Cn is true.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints watched-and
\end{verbatim}
}
\section{constraints watchelement}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   watchelement(vec, i, e)

specifies that, in any solution, vec[i] = e and i is in the range
[0 .. |vec|-1].
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
Enforces generalised arc consistency.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See entry

   help constraints element

for details of an identical constraint that enforces a lower level of
consistency.
\end{verbatim}
}
\section{constraints watchelement\textunderscore one}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
This constraint is identical to watchelement, except the vector
is indexed from 1 rather than from 0.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See entry

   help constraints watchelement

for details of watchelement which watchelement_one is based on.
\end{verbatim}
}
\section{constraints watchelement\textunderscore undefzero}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   watchelement_undefzero(vec, i, e)

specifies that, in any solution, either:
a)  vec[i] = e and i is in the range [0 .. |vec|-1]
b)  i is outside the index range of vec, and e = 0

Unlike watchelement (and element) which are false if i is outside
the index range of vec.

In general, use watchelement unless you have a special reason to
use this constraint!
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
Enforces generalised arc consistency.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See entry

   help constraints watchelement

for details of the standard element constraint, which is false
when the array value is out of bounds.
\end{verbatim}
}
\section{constraints watchless}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint watchless(x,y) ensures that x is less than y.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints ineq
\end{verbatim}
}
\section{constraints watchsumgeq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
  The constraint watchsumgeq(vec, c) ensures that sum(vec) >= c.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
  For this constraint, small values of c are more efficient.

  Equivalent to litsumgeq(vec, [1,...,1], c), but faster.

  This constraint works on 0/1 variables only.
\end{verbatim}
}
\paragraph{Reifiability}
{\footnotesize
\begin{verbatim}
  This constraint is not reifiable.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints watchsumleq
  help constraints litsumgeq
\end{verbatim}
}
\section{constraints watchsumleq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
  The constraint watchsumleq(vec, c) ensures that sum(vec) <= c.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
  Equivalent to litsumgeq([vec1,...,vecn], [0,...,0], n-c) but faster.

  This constraint works on binary variables only.

  For this constraint, large values of c are more efficient.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
  See also

  help constraints watchsumgeq
  help constraints litsumgeq
\end{verbatim}
}
\section{constraints watchvecneq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   watchvecneq(A, B)

ensures that A and B are not the same vector, i.e., there exists some index i
such that A[i] != B[i].
\end{verbatim}
}
\section{constraints weightedsumgeq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   weightedsumgeq(constantVec, varVec, total)

ensures that constantVec.varVec >= total, where constantVec.varVec is
the scalar dot product of constantVec and varVec.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints weightedsumleq
help constraints sumleq
help constraints sumgeq
\end{verbatim}
}
\section{constraints weightedsumleq}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The constraint

   weightedsumleq(constantVec, varVec, total)

ensures that constantVec.varVec <= total, where constantVec.varVec is
the scalar dot product of constantVec and varVec.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints weightedsumgeq
help constraints sumleq
help constraints sumgeq
\end{verbatim}
}
\section{input}
\paragraph{Description}
{\footnotesize
\begin{verbatim}

Minion expects to be provided with the name of an input file as an
argument. This file contains a specification of the CSP to be solved
as well as settings that the search process should use. The format is

Minion3Input::= MINION 3
                <InputSection>+
                **EOF**

InputSection::= <VariablesSection>
              | <SearchSection>
              | <ConstraintsSection>
              | <TuplelistSection>
              | <ShortTuplelistSection>

i.e. 'MINION 3' followed by any number of variable, search,
constraints and tuplelists sections (can repeat) followed by
'**EOF**', the end of file marker.

All text from a '#' character to the end of the line is ignored.

See the associated help entries below for information on each section.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
You can give an input file via standard input by specifying '--' as the file
name, this might help when minion is being used as a tool in a shell script or
for compressed input, e.g.,

   gunzip -c myinput.minion.gz | minion
\end{verbatim}
}
\section{input constraints}
\paragraph{Description}
{\footnotesize
\begin{verbatim}

The constraints section consists of any number of constraint
declarations on separate lines.

ConstraintsSection::= **CONSTRAINTS**
                      <ConstraintDeclaration>*
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
**CONSTRAINTS**
eq(bool,0)
alldiff(d)
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See help entries for individual constraints under

   help constraints

for details on constraint declarations.
\end{verbatim}
}
\section{input example}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
Below is a complete minion input file with commentary, as an example.

MINION 3

# While the variable section doesn't have to come first, you can't
# really do anything until
# You have one...
**VARIABLES**

# There are 4 type of variables
BOOL bool         # Boolean don't need a domain
BOUND b {1..3}    # Bound vars need a domain given as a range
DISCRETE d {1..3} # So do discrete vars

#Note: Names are case sensitive!

# Internally, Bound variables are stored only as a lower and upper bound
# Whereas discrete variables allow any sub-domain

SPARSEBOUND s {1,3,6,7} # Sparse bound variables take a sorted list of values

# We can also declare matrices of variables!

DISCRETE q[3] {0..5} # This is a matrix with 3 variables: q[0],q[1] and q[2]
BOOL bm[2,2] # A 2d matrix, variables bm[0,0], bm[0,1], bm[1,0], bm[1,1]
BOOL bn[2,2,2,2] # You can have as many indices as you like!

#The search section is entirely optional
**SEARCH**

# Note that everything in SEARCH is optional, and can only be given at
# most once!

# If you don't give an explicit variable ordering, one is generated.
# These can take matrices in interesting ways like constraints, see below.
VARORDER [bool,b,d]

# If you don't give a value ordering, 'ascending' is used
#VALORDER [a,a,a,a]

# You can have one objective function, or none at all.
MAXIMISING bool
# MINIMISING x3

# both (MAX/MIN)IMISING and (MAX/MIN)IMIZING are accepted...

# Print statement takes a vector of things to print

PRINT [bool, q]

# You can also give:
# PRINT ALL (the default)
# PRINT NONE

# Declare constraints in this section!
**CONSTRAINTS**

# Constraints are defined in exactly the same way as in MINION input
formats 1 & 2
eq(bool, 0)
eq(b,d)

# To get a single variable from a matrix, just index it
eq(q[1],0)
eq(bn[0,1,1,1], bm[1,1])

# It's easy to get a row or column from a matrix. Just use _ in the
# indices you want
# to vary. Just giving a matrix gives all the variables in that matrix.

#The following shows how flattening occurs...

# [bm] == [ bm[_,_] ] == [ bm[0,0], bm[0,1], bm[1,0], bm[1,1] ]
# [ bm[_,1] ] = [ bm[0,1], bm[1,1] ]
# [ bn[1,_,0,_] = [ bn[1,0,0,0], b[1,0,0,1], b[1,1,0,0], b[1,1,0,1] ]

# You can string together a list of such expressions!

lexleq( [bn[1,_,0,_], bool, q[0]] , [b, bm, d] )

# One minor problem.. you must always put [ ] around any matrix expression, so
# lexleq(bm, bm) is invalid

lexleq( [bm], [bm] ) # This is OK!

# Can give tuplelists, which can have names!
# The input is: <name> <num_of_tuples> <tuple_length> <numbers...>
# The formatting can be about anything..

**TUPLELIST**

Fred 3 3
0 2 3
2 0 3
3 1 3

Bob 2 2 1 2 3 4

#No need to put everything in one section! All sections can be reopened..
**VARIABLES**

# You can even have empty sections.. if you want

**CONSTRAINTS**

#Specify tables by their names..

table([q], Fred)

# Can still list tuples explicitally in the constraint if you want at
# the moment.
# On the other hand, I might remove this altogether, as it's worse than giving
# Tuplelists

table([q],{ <0,2,3>,<2,0,3>,<3,1,3> })

#Must end with the **EOF** marker!

**EOF**

Any text down here is ignored, so you can write whatever you like (or
nothing at all...)
\end{verbatim}
}
\section{input search}
\paragraph{Description}
{\footnotesize
\begin{verbatim}

Inside the search section one can specify

- variable orderings,
- value orderings,
- optimisation function, and
- details of how to print out solutions.

   SearchSection::= <VarValOrdering>*
                    <OptimisationFn>?
                    <PrintFormat>?

If no varval ordering is given then the variables are assigned in instantiation
order and the values tried in ascending order.

If a variable order is given as a command line argument it will override
anything specified in the input file.

Multiple variable orders can be given, each with an optional value ordering:

   VarValOrdering::= <VarOrder>
                     <ValOrder>?

In each VarOrder an instantiation order is specified for a subset of
variables. Variables can optionally be \"auxiliary variables\" (add \"AUX\" to
the varorder) meaning that if there are several solutions to the problem
differing only in the auxiliary variables, only one is reported by minion.

   VarOrder::= VARORDER AUX? <ORDER>? [ <varname>+ ]

      where

   <ORDER>::= STATIC | SDF | SRF | LDF | ORIGINAL | WDEG | CONFLICT |
DOMOVERWDEG

The value ordering allows the user to specify an instantiation order
for the variables involved in the variable order, either ascending (a)
or descending (d) for each. When no value ordering is specified, the
default is to use ascending order for every search variable.

   ValOrder::= VALORDER[ (a|d)+ ]

To model an optimisation problem the user can specify to minimise
or maximise a variable's value.

   OptimisationFn::= MAXIMISING <varname>
                   | MINIMISING <varname>

Finally, the user can control some aspects of the way solutions are
printed. By default (no PrintFormat specified) all the variables are
printed in declaration order. Alternatively a custom vector, or ALL
variables, or no (NONE) variables can be printed. If a matrix or, more
generally, a tensor is given instead of a vector, it is automatically
flattened into a vector as described in 'help variables vectors'.

   PrintFormat::= PRINT <vector>
                | PRINT ALL
                | PRINT NONE
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See also

   switches -varorder
\end{verbatim}
}
\section{input shorttuplelist}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
A shorttuplelist section lists of allowed tuples for haggisgac,
shortstr2, shortctuplestr2 and other constraints which accept
short tuple lists.

The required format is

TuplelistSection::= **TUPLELIST**
                    <Tuplelist>*

Tuplelist::= <name> <num_tuples> <short_tuple>+

short_tuple ::= [ <literal>*, ]

literal ::= (<num>, <num>)
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
**SHORTTUPLELIST**
mycon 4
[(0,0),(3,0)]
[(1,0),(3,0)]
[(2,0),(3,0)]
[(0,1),(1,1),(2,1),(3,1)]

Represents the same constraint as:

**TUPLELIST**
mycon 8 4
0 0 0 0
0 0 1 0
0 1 0 0
0 1 1 0
1 0 0 0
1 0 1 0
1 1 0 0
1 1 1 1

Short tuples give us a way of shrinking this list. Short tuples consist
of pairs (x,y), where x is a varible position, and y is a value for that
variable. For example:

[(0,0),(3,0)]

Represents 'If the variable at index 0 is 0, and the variable at index
3 is 0, then the constraint is true'.

Some constraints (currently just shortctuplestr2) allow more than
one literal per variable for example:

[(0,0),(0,1),(3,0)]

Represents 'If the variable at index 0 is 0 or 1, and the variable at index
3 is 0, then the constraint is true'.

Note that some tuples are double-represented in the example 'mycon'.
The first 3 short tuples all allow the assignment '0 0 0 0'. This is fine.
The important thing for efficency is to try to give a small list of
short tuples.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints haggisgac
help constraints haggisgac-stable
help input tuplelist
\end{verbatim}
}
\section{input tuplelist}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
A tuplelist section lists of allowed tuples for table constraints
can be specified. This technique is preferable to specifying the
tuples in the constraint declaration, since the tuplelists can be
shared between constraints and named for readability.

The required format is

TuplelistSection::= **TUPLELIST**
                    <Tuplelist>*

Tuplelist::= <name> <num_tuples> <tuple_length> <numbers>+
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
**TUPLELIST**
AtMostOne 4 3
0 0 0
0 0 1
0 1 0
1 0 0
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
help constraints table
help input shorttuplelist
\end{verbatim}
}
\section{input variables}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
The variables section consists of any number of variable declarations
on separate lines.

VariablesSection::= **VARIABLES**
                    <VarDeclaration>*
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
 **VARIABLES**

BOOL bool                          #boolean var
BOUND b {1..3}                     #bounds var
SPARSEBOUND myvar {1,3,4,6,7,9,11} #sparse bounds var
DISCRETE d[3] {1..3}               #array of discrete vars
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
See the help section

   help variables

for detailed information on variable declarations.
\end{verbatim}
}
\section{switches}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Minion supports a number of switches to augment default behaviour.  To
see more information on any switch, use the help system. The list
below contains all available switches. For example to see help on
-quiet type something similar to

   minion help switches -quiet

replacing 'minion' by the name of the executable you're using.
\end{verbatim}
}
\section{switches -check}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Check solutions for correctness before printing them out.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
    This option is the default for DEBUG executables.
\end{verbatim}
}
\section{switches -cpulimit}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    To stop search after N seconds (CPU time), do

       minion -cpulimit N myinput.minion
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
    help switches -timelimit
    help switches -nodelimit
    help switches -sollimit
\end{verbatim}
}
\section{switches -dumptree}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Print out the branching decisions and variable states at each node.
\end{verbatim}
}
\section{switches -findallsols}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Find all solutions and count them. This option is ignored if the
problem contains any minimising or maximising objective.
\end{verbatim}
}
\section{switches -gap}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Give name of gap executable (defaults to gap.sh)
\end{verbatim}
}
\section{switches -makeresume}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Write a resume file on timeout or being killed.
\end{verbatim}
}
\section{switches -map-long-short}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Automatically generate a short tuple list from each long tuple list.

    The methods of compression are:

    none : No short tuple list generated (default)
    eager : Use a fast algorithm to produce a reasonable short tuple list (best
    as first choice)
    lazy : Work harder (possibly exponentially) to produce a shorter short tuple
    list
    keeplong : Make a 'short tuple list' with no short tuples (only for
    benchmarking)
\end{verbatim}
}
\section{switches -nocheck}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Do not check solutions for correctness before printing them out.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
    This option is the default on non-DEBUG executables.
\end{verbatim}
}
\section{switches -nodelimit}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    To stop search after N nodes, do

       minion -nodelimit N myinput.minion
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
    help switches -cpulimit
    help switches -timelimit
    help switches -sollimit
\end{verbatim}
}
\section{switches -noprintsols}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Do not print solutions.
\end{verbatim}
}
\section{switches -noresume}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Do not write a resume file on timeout or being killed. (default)
\end{verbatim}
}
\section{switches -outputCompressed}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Output a Minion instance with some basic reasoning performed to
    reduce the size of the file. This file should produce identical
    output the original instance but may solve faster.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
    To compress a file 'infile.minion' to a file 'smaller.minion'

       minion infile.minion -outputCompressed smaller.minion
\end{verbatim}
}
\section{switches -outputCompressedDomains}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Try to rduce the initial domains of variables, and output them.
    This is in general not useful for users, but is provided for other systems.
\end{verbatim}
}
\section{switches -preprocess}
\paragraph{}
{\footnotesize
\begin{verbatim}

    This switch allows the user to choose what level of preprocess is
    applied to their model before search commences.

    The choices are:

    - GAC
    - generalised arc consistency (default)
    - all propagators are run to a fixed point
    - if some propagators enforce less than GAC then the model will
    not necessarily be fully GAC at the outset

    - SACBounds
    - singleton arc consistency on the bounds of each variable
    - AC can be achieved when any variable lower or upper bound is a
    singleton in its own domain

    - SAC
    - singleton arc consistency
    - AC can be achieved in the model if any value is a singleton in
    its own domain

    - SSACBounds
    - singleton singleton bounds arc consistency
    - SAC can be achieved in the model when domains are replaced by either
    the singleton containing their upper bound, or the singleton containing
    their lower bound

    - SSAC
    - singleton singleton arc consistency
    - SAC can be achieved when any value is a singleton in its own domain

    These are listed in order of roughly how long they take to
    achieve. Preprocessing is a one off cost at the start of search. The
    success of higher levels of preprocessing is problem specific; SAC
    preprocesses may take a long time to complete, but may reduce search
    time enough to justify the cost.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
    To enforce SAC before search:

       minion -preprocess SAC myinputfile.minion
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
    help switches -prop-node
\end{verbatim}
}
\section{switches -printonlyoptimal}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    In optimisation problems, only print the optimal value, and
    not intermediate values.
\end{verbatim}
}
\section{switches -printsols}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Print solutions (default).
\end{verbatim}
}
\section{switches -printsolsonly}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Print only solutions and a summary at the end.
\end{verbatim}
}
\section{switches -prop-node}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Allows the user to choose the level of consistency to be enforced
    during search.

    See entry 'help switches -preprocess' for details of the available
    levels of consistency.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
    To enforce SSAC during search:

       minion -prop-node SSAC input.minion
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
    help switches -preprocess
\end{verbatim}
}
\section{switches -quiet}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Do not print parser progress (default)
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
    help switches -verbose
\end{verbatim}
}
\section{switches -randomiseorder}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Randomises the ordering of the decision variables, and the value ordering.
    If the input file specifies as ordering it will randomly permute this. If no
    ordering is
    specified a random permutation of all the variables is used.
\end{verbatim}
}
\section{switches -randomseed}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Set the pseudorandom seed to N. This allows 'random' behaviour to be
    repeated in different runs of minion.
\end{verbatim}
}
\section{switches -redump}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Print the minion input instance file to standard out. No search is
carried out when this switch is used.
\end{verbatim}
}
\section{switches -skipautoaux}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    By default Minion adds all variables to the varorder, to ensure that all
    variables
    are branched assigned before a solution is outputted. This option disables
    that
    behaviour. This means minion Minion may output solutions incorrectly, or
    incorrect
    numbers of solutions. This flag is provided because some users require this
    low-level control over the search, but is in general useless and dangerous.
    In particular,
    it will not speed up search (except when the speed up is due to producing
    garbage of course!)
\end{verbatim}
}
\section{switches -sollimit}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    To stop search after N solutions have been found, do

       minion -sollimit N myinput.minion
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
    help switches -cpulimit
    help switches -nodelimit
    help switches -timelimit
\end{verbatim}
}
\section{switches -solsout}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Append all solutionsto a named file.
    Each solution is placed on a line, with no extra formatting.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
    To add the solutions of myproblem.minion to mysols.txt do

       minion -solsout mysols.txt myproblem.minion
\end{verbatim}
}
\section{switches -split}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    When Minion is terminated before the end of search, write out two new input
    files that split the remaining search space in half. Each of the files will
    have
    all the variables and constraints of the original file plus constraints that
    rule out the search already done. In addition, the domain of the variable
    under
    consideration when Minion was stopped is split in half with each of the new
    input files considering a different half.

    This feature is experimental and intended to facilitate parallelisation --
    to
    parallelise the solving of a single constraint problem, stop and split
    repeatedly. Please note that large-scale testing of this feature was limited
    to
    Linux systems and it might not work on others (especially Windows).

    The name of the new input files is composed of the name of the original
    instance, the string 'resume', a timestamp, the process ID of Minion, the
    name
    of the variable whose domain is being split and 0 or 1. Each of the new
    input
    files has a comment identifying the name of the input file which it was
    split
    from. Similarly, Minion's output identifies the new input files it writes
    when
    splitting.

    The new input files can be run without any special flags.

    This flag is intended to be used with the -timelimit, -sollimit, -nodelimit
    or -cpulimit flags. Please note that changing other flags between
    runs (such as -varorder) may have unintended consequences.

    Implies -makeresume.
\end{verbatim}
}
\section{switches -split-stderr}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    The flag -split-stderr has the same function as the flag -split, however the
    two new Minion input files are sent to standard error rather than written to
    files.

    See documentation for -split.
\end{verbatim}
}
\section{switches -tableout}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Append a line of data about the current run of minion to a named file.
    This data includes minion version information, arguments to the
    executable, build and solve time statistics, etc. See the file itself
    for a precise schema of the supplied information.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
    To add statistics about solving myproblem.minion to mystats.txt do

       minion -tableout mystats.txt myproblem.minion
\end{verbatim}
}
\section{switches -timelimit}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    To stop search after N seconds (real time), do

       minion -timelimit N myinput.minion
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
    help switches -cpulimit
    help switches -nodelimit
    help switches -sollimit
\end{verbatim}
}
\section{switches -varorder}
\paragraph{Description}
{\footnotesize
\begin{verbatim}

Enable a particular variable ordering for the search process. This
flag is experimental and minion's default ordering might be faster.

The available orders are:

- sdf - smallest domain first, break ties lexicographically

- sdf-random - sdf, but break ties randomly

- srf - smallest ratio first, chooses unassigned variable with smallest
  percentage of its initial values remaining, break ties lexicographically

- srf-random - srf, but break ties randomly

- ldf - largest domain first, break ties lexicographically

- ldf-random - ldf, but break ties randomly

- random - random variable ordering

- static - lexicographical ordering
\end{verbatim}
}
\section{switches -verbose}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
    Print parser progress.
\end{verbatim}
}
\paragraph{References}
{\footnotesize
\begin{verbatim}
    help switches -quiet
\end{verbatim}
}
\section{variables}
\paragraph{General}
{\footnotesize
\begin{verbatim}
Minion supports 4 different variable types, namely

- 0/1 variables,
- bounds variables,
- sparse bounds variables, and
- discrete variables.

Sub-dividing the variable types in this manner affords the greatest
opportunity for optimisation. In general, we recommend thinking of the
variable types as a hierarchy, where 1 (0/1 variables) is the most
efficient type, and 4 (Discrete variables) is the least. The
user should use the variable which is the highest in the hierarchy,
yet encompasses enough information to provide a full model for the
problem they are attempting to solve.

Minion also supports use of constants in place of variables, and constant
vectors in place of vectors of variables. Using constants will be at least
as efficient as using variables when the variable has a singleton domain.

See the entry on vectors for information on how vectors, matrices and,
more generally, tensors are handled in minion input. See also the
alias entry for information on how to multiply name variables for
convenience.
\end{verbatim}
}
\section{variables 01}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
01 variables are used very commonly for logical expressions, and for
encoding the characteristic functions of sets and relations. Note that
wherever a 01 variable can appear, the negation of that variable can
also appear. A boolean variable x's negation is identified by !x.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
Declaration of a 01 variable called bool in input file:

BOOL bool

Use of this variable in a constraint:

eq(bool, 0) #variable bool equals 0
\end{verbatim}
}
\section{variables alias}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Specifying an alias is a way to give a variable another name. Aliases
appear in the **VARIABLES** section of an input file. It is best
described using some examples:

ALIAS c = a

ALIAS c[2,2] = [[myvar,b[2]],[b[1],anothervar]]
\end{verbatim}
}
\section{variables bounds}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Bounds variables, where only the upper and lower bounds of the domain
are maintained. These domains must be continuous ranges of integers
i.e. holes cannot be put in the domains of the variables.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}

Declaration of a bound variable called myvar with domain between 1
and 7 in input file:

BOUND myvar {1..7}

Use of this variable in a constraint:

eq(myvar, 4) #variable myvar equals 4
\end{verbatim}
}
\section{variables constants}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Minion supports the use of constants anywhere where a variable can be used. For
example, in a constraint as a replacement for a single variable, or a vector of
constants as a replacement for a vector of variables.
\end{verbatim}
}
\paragraph{Examples}
{\footnotesize
\begin{verbatim}
Use of a constant:

   eq(x,1)

Use of a constant vector:

   element([10,9,8,7,6,5,4,3,2,1],idx,e)
\end{verbatim}
}
\section{variables discrete}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
In discrete variables, the domain ranges between the specified lower and upper
bounds, but during search any domain value may be pruned, i.e., propagation and
search may punch arbitrary holes in the domain.
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
Declaration of a discrete variable x with domain {1,2,3,4} in input file:

DISCRETE x {1..4}

Use of this variable in a constraint:

eq(x, 2) #variable x equals 2
\end{verbatim}
}
\section{variables sparsebounds}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
In sparse bounds variables the domain is composed of discrete values
(e.g. {1, 5, 36, 92}), but only the upper and lower bounds of the
domain may be updated during search. Although the domain of these
variables is not a continuous range, any holes in the domains must be
there at time of specification, as they can not be added during the
solving process.
\end{verbatim}
}
\paragraph{Notes}
{\footnotesize
\begin{verbatim}
Declaration of a sparse bounds variable called myvar containing values
{1,3,4,6,7,9,11} in input file:

SPARSEBOUND myvar {1,3,4,6,7,9,11}

Use of this variable in a constraint:
eq(myvar, 3) #myvar equals 3
\end{verbatim}
}
\section{variables vectors}
\paragraph{Description}
{\footnotesize
\begin{verbatim}
Vectors, matrices and tensors can be declared in minion
input. Matrices and tensors are for convenience, as constraints do not
take these as input; they must first undergo a flattening process to
convert them to a vector before use. Additional commas at the end of
vectors are ignored (see example below).
\end{verbatim}
}
\paragraph{Examples}
{\footnotesize
\begin{verbatim}
A vector of 0/1 variables:

BOOL myvec[5]

A matrix of discrete variables:

DISCRETE sudoku[9,9] {1..9}

A 3D tensor of 0/1s:

BOOL mycube[3,3,2]

One can create a vector from scalars and elements of vectors, etc.:

alldiff([x,y,myvec[1],mymatrix[3,4]])

When a matrix or tensor is constrained, it is treated as a vector
whose entries have been strung out into a vector in index order with
the rightmost index changing most quickly, e.g.

alldiff(sudoku)

is equivalent to

alldiff([sudoku[0,0],...,sudoku[0,8],...,sudoku[8,0],...,sudoku[8,8]])

Furthermore, with indices filled selectively and the remainder filled
with underscores (_) the flattening applies only to the underscore
indices:

alldiff(sudoku[4,_])

is equivalent to

alldiff([sudoku[4,0],...,sudoku[4,8]])

Lastly, one can optionally add square brackets ([]) around an
expression to be flattened to make it look more like a vector:

alldiff([sudoku[4,_]])

is equivalent to

alldiff(sudoku[4,_])
\end{verbatim}
}
\paragraph{Example}
{\footnotesize
\begin{verbatim}
Additional hanging commas at the end of array are ignored, e.g.

lexleq([A,B,C,],[D,E,F,])

is equivalent to

lexleq([A,B,C],[D,E,F])

This feature is provided to make it easier to computer-generate input
files.
\end{verbatim}
}


\subsection{Chunks, Trees and Data Integrity}

\begin{frame}[t]{\alt<5->{It's chunks all the way down...}{Chunks}}
% \begin{overlayarea}{⟨area width⟩}{⟨area height⟩}
%   ⟨environment contents⟩
% \end{overlayarea}
\begin{overlayarea}{\textwidth}{10cm}
Under the hood swarm does not deal in files but in \emph{chunks.}

\begin{itemize}
 \item<2-> All data is broken into pieces of size 4kB: ``chunks".
 \item<4-> Chunks are hashed and the hash is used as their ID/address.
 \item<5-> Chunk hashes are also packaged into 4kB chunks...
\end{itemize}

\begin{onlyenv}<1-2>
 \begin{center}
  \includegraphics[width=0.4\textwidth]{devcon-files.jpg}
  \transdissolve<3>
 \end{center}
\end{onlyenv}

 \begin{center}
  \begin{tikzpicture}
   \node[chunk,visible on=<3>] at (0,0) (achunk){};
   \node[visible on=<3>] at (-1.8,0) (labeltext){A ``chunk:"};
   \node[chunk,visible on=<3->] at (-4,-3) (a){};
   \node[chunk,visible on=<3->] at (-2,-3) (b){};
   \node[chunk,visible on=<3->] at (0,-3) (c){};
   \node[chunk,visible on=<3->] at (2,-3) (d){};
   \node[chunk,visible on=<3->] at (4,-3) (e){};

   \node at (-4.2,-1.3) (dummy1) {};
   \node at (4.2,-1.7) (dummy2) {};
   \node[chunk,fit=(dummy1)(dummy2),visible on=<5>]{};

   \node[scale=0.8,draw,visible on=<4-5>] at (-4,-1.5) (ha){$h_1$}
     (a.north) edge[-,visible on=<4>] (ha.south);
   \node[scale=0.8,draw,visible on=<4-5>] at (-2,-1.5) (hb){$h_2$}
     (b.north) edge[-,visible on=<4>] (hb.south);
   \node[scale=0.8,draw,visible on=<4-5>] at (0,-1.5) (hc){$h_3$}
     (c.north) edge[-,visible on=<4>] (hc.south);
   \node[scale=0.8,draw,visible on=<4-5>] at (2,-1.5) (hd){$h_4$}
     (d.north) edge[-,visible on=<4>] (hd.south);
   \node[scale=0.8,draw,visible on=<4-5>] at (4,-1.5) (he){$h_5$}
     (e.north) edge[-,visible on=<4>] (he.south);

   \node[chunk,visible on=<6>] at (0,-1.5) {};
     \end{tikzpicture}

 \end{center}
\end{overlayarea}
\end{frame}

\begin{frame}
\begin{overlayarea}{\textwidth}{10cm}

 \begin{columns}[T]
  \begin{column}{0.5\textwidth}
  Chunks are assembled in a \textbf{Merkle Tree}.
  \small
    \begin{itemize}
     \item<1->{Files are retrievable using a single 32byte hash.}
     \item<2->{Built-in integrity protection and random access.}
     \item<3->{Merkle-proofs enable proof-of-custody schemes.}
     \item<4->{Treversible using ASCII charactes due to branching factor of 128.}
    \end{itemize}

  \end{column}
  \begin{column}{0.5\textwidth}
   \only<1-2>{\includegraphics[width=6cm]{devcon-merkle-tree.png}}
   \only<3>{
   \begin{tikzpicture}
    \node[scale=0.4] {
    \input{devcon-merkle-proof.tex}
    };
   \end{tikzpicture}
   }
   \only<4>{
     \begin{tikzpicture}
      \node[scale=0.6] {
         \begin{tikzpicture}
	  \node[draw,dashed] (root) at (5,3) {hash of chunk $h_1$ - $h_{128}$};
	  \node[draw,dashed] (h1) at (1,1) {$h_1$};
	  \node[draw,dashed] (h2) at (2,1) {$h_2$};
	  \node[draw,dashed] (h3) at (3,1) {$h_3$};
	  \node (dots) at (5,1) {$\cdots$};
	  \node[draw,dashed] (h128) at (7,1) {$h_{128}$};
	  % \node[draw,fit=(h1) (h2) (h3) (dots) (h128)]{};
	  \draw (root) -- (h1);
	  \draw (root) -- (h2);
	  \draw (root) -- (h3);
	  \draw (root) -- (h128);
      \end{tikzpicture}
      };
      \end{tikzpicture}
      }
  \end{column}
 \end{columns}

\end{overlayarea}
\end{frame}

\begin{frame}{Manifests}
 We can take this one step further, be tying together various swarm assets under a new root-hash by generating a new tree: A \textbf{Manifest}.\\
 \begin{block}{A Swarm Manifest...}
  ...is a Merkle tree whose leaves are root-hashes of other swarm assets (files, collections, manifests, chunks...)
 \end{block}
 The only difference between this and the chunk-tree of a file, is that it is not balanced and has metadata.
\end{frame}

\begin{frame}
 For example, \uncover<2->{the Swarm landing page
 \begin{center}
  \texttt{swarm-gateways.net/bzz:/swarm/}
 \end{center}
 }
 \end{frame}

\begin{frame}
 \includegraphics[width=0.8\textwidth]{devcon-swarmsite.pdf}
\end{frame}

\begin{frame}[fragile]
\frametitle{Manifests}
 ...is loaded from this 4-entry manifest:\\
\tiny
\begin{semiverbatim}
\{"entries":[\{
"path":"Swarm_files/",
"hash":"0294e48456a49fe7c02162c83b068075ff9ae6aaafb46439dba32da7de548379",
"contentType":"application/bzz-manifest+json",
"status":0\},
\{"path":"ethersphere/orange-papers/"...
\{"path":"i"...
\{"path":"talks/"...
\{"path":"",
"hash":"6fac0b0c1f118f7f383792c0f01c80d1b2dc94f0e166d62ff4f999a926e9d94a",
"contentType":"text/html;charset=utf-8","status":0\}]\}\end{semiverbatim}
\uncover<2->{\small
 Manifests translate a URL path into swarm hashes (URL defines manifest merkle-tree traversal).\\[2mm]
 When combined with the Ethereum Name Service (ENS) to register a name for the manifest's own root hash, we can \textbf{serve any and all swarm data directly to your browser using human readable names}.
}
\end{frame}

\begin{subsection}{Example: Swarm File Manager}
 \begin{frame}
  With manifests, you can navigate swarm just like you would navigate your own filesystem.\\
  \uncover<2->{Let us open the swarm landing page in the swarm file manager:\\}
  \uncover<3->{\includegraphics[width=11cm]{devcon-swarmfilemanager.pdf}}
 \end{frame}
\end{subsection}

\begin{subsection}{Manifest Uses}

\begin{frame}

\begin{block}{Using Manifests...}
\begin{itemize}
 \item Two-way translation possible from directories to manifests
  \begin{itemize}
   \item Filesystem API
   \item Dropbox, rsync, ...
   \item Filesystem driver (fuse)
  \end{itemize}
 \item Only root hashes must be registered (ENS) on blockchain. Beyond this the whole site is integrity protected.
 \item Metadata for any manifest entry can include
    \begin{itemize}
      \item copyright information
      \item access control
      \item payment triggers
      \item auto-play continuation
      \item subscription information
      \item database layout info
    \end{itemize}
 \item Version control system (mango = git over swarm)
\end{itemize}
\end{block}

\end{frame}
\end{subsection}


\documentclass[10pt]{article}
\usepackage[T1]{fontenc}

% Document Details
\newcommand{\CLASS}{AMATH 563}
\newcommand{\assigmentnum}{Nueral Networks}

\usepackage[margin = 1in, left=0.75in,right=0.75in]{geometry}
\input{../../import/title.tex} % Title Styling
\input{../../import/styling.tex} % General Styling
\input{../../import/code.tex} % Code Display Setup
\input{../../import/math.tex} % Math shortcuts

\usepackage{dblfloatfix}    % To enable figures at the bottom of page

% Problem
\newenvironment{problem}[1]{\vspace{2em}{\large\sffamily\textbf{#1}}\itshape\par}{}

\usepackage{nameref}
\newcommand{\vln}{\rotatebox{90}{--}}

\begin{document}

\twocolumn[{%
\begin{@twocolumnfalse}
\maketitle
\vspace{2em}
\begin{abstract}
We outline a how neural networks might be applied to the study of systems governed by possibly unknown PDEs. In particular we show that future state predictions are possible for some systems, even if they are chaotic. We address how high dimensional data can be rank reduced first in order to allow for training on a smaller neural net. While some results are encouraging, we find that it is quite difficult to correctly tune the neural networks in a limited time.
\end{abstract}

\vspace{4em}
%\tableofcontents
%\vspace{3em}
\pagebreak\end{@twocolumnfalse}
}]

\section{Introduction and Overview}
With recent increases in computation power and data storage capabilities our ability effectively process data computationally has increases substantially. Machine learning uses statistical techniques to gather information about a dataset and use it to make predictions or understand trends. One class of machine learning methods, neural networks, is particularly effective given large datasets. If neural nets can be effectively used to predict solutions of PDEs then we can step away from trying to guess at the PDEs which actually describe systems and move towards generating trajectories using these neural nets.

\section{Theoretical Background}
\subsection{Neural Network Basics}
Suppose we have sets \( \hat{X}_0 \) and \( \hat{X}_N \) with elements of size \( m \) and \( n \) respectively. Let \( \hat{f}:\hat{X}_0 \to \hat{X}_N \) be an injection. The goal of a neural network is to be able to accurately compute this injection to make predictions about elements of \( \hat{X}_0 \) for which we do not know the actual value of \( \hat{f} \).

A feed forward neural network is a function of the form,
\begin{align}
    X_N = f_N(b_{N-1}+\cdots f_2(b_1+ W_1f_1(b_0 + W_0x_0))) \label{NN}
\end{align}
where the the ``activation'' functions \( f_j:\RR\to\RR \) are applied componentwise.

Each ``layer'' is of the form,
\begin{align*}
    x_{j+1} = f_{j+1}j(W_j x_{j} + b_j), && j=0,1,\ldots, N-1
\end{align*}

Note that \( W_j \) can be of any shape compatible with \( x_j \) with the constraint that \( W_{N-1} \) must also give something of the dimension of \( x_N \).

The goal is to set the parameters \( W_j \) and \( b_j \) so that the neural network is equal to \( \hat{f} \). However, it is clear that unless we know the output of \( f \) on all of \( \hat{X}_0 \) this will not be possible even if our neural net has the same form as \( \hat{f} \). Since in general we would like to be able to make predictions about unknown data we will have to settle for the neural network being an approximation to \( \hat{f} \).

More specifically, let \( X_0\subset \hat{X}_0 \) and suppose the value of \( \hat{f}(x) \) is known for all \( x\in X_0 \). For convenience we will write \( X_0 \) as a matrix of size \( n\times t \). Define \( X_N\subset \hat{X}_N \) as the \( m\times t \) matrix found by applying \( \hat{f} \) to the columns of \( X_0 \). We will use the data from \( X_0 \) to train the neural net to (hopefully) give us a good approximation for \( \hat{f} \). Since the neural network can take any element of \( \hat{X}_0 \) as input, we hope that it can be used for predictions about the value of \( \hat{f} \) on these elements.

\subsection{Loss functions}
Given a neural network we would like to train it to be able to make predictions. In order to do this we need some way of saying what a good prediction is. In general this is done by defining a loss function which is small when the network gives good predictions, and large when it gives bad predictions.

More specifically, let \( X_0\in\RR^{n} \) and \( X_N\in\RR^{m} \) be the input data and target data respectively. Let \( f:\RR^{n}\times\RR^{Z}\to\RR^{m} \) be a neural network as defined above, where \( Z \) is the number of free parameters. The residual error of the network for a fixed set of parameters \( \beta\in\RR^{Z} \) is \( Y - f(X,\beta) \).

Ideally the residual error is zero. By picking some metric with which to measure the residual error, we have a minimization problem. In this paper we often chose to minimize the mean square error, which amounts to solving,
\begin{align}
    \min_{\beta} \sum_{x_0\in X_0} \norm{\hat{f}(x_0)-f(x_0,\beta)}_2^2 \label{mse}
\end{align}

\subsection{Optimizers}
In order to minimize expressions such as (\ref{mse}) an optimization algorithm must be applied. Since the input and output lie in such high dimensional spaces, the loss function often has many local minimum or saddle points. As such, traditional methods such as gradient decent may not work very well. Instead there are many popular gradient based algorithms which introduce some stochasticity in order to avoid ``getting stuck''. Since our neural network can be expressed as the composition of fairly straightforward functions, the gradient with respect to entries of \( \beta \) can be easily computed using the chain rule (done by something called back-propagation).

\subsection{SVD and Data reduction}
When training a neural network the size of the input and output are determine by the data given. This means the network may have to be very large the the beginning and end nodes. On approach to reduce the size of the network is to project the input and target data into lower dimensional subspaces and then train on the projections. This is equivalent to the first and last hidden layers of the neural net being of smaller size and with fixed weights. If the weights are not fixed, the net will determine the ``best'' projection. However, since the SVD already computes the optimal low rank approximation in the 2-norm or Frobenius norm, it may be beneficial to set these weights so that the net does not have to learn them.

Suppose our input data \( X \) is in \( \RR^{N} \) and we have \( T \) samples. We then have a \( N\times T \) data matrix. We would like to find a subspace of \( \RR^{N} \) of lower dimension where our data can be approximated well. Our data has a rank \( k \) reduced SVD,
\begin{align}
    X \approx U\Sigma V^* \label{SVD_eq}
\end{align}
where \( U  \) is \( N\times k \), \( \Sigma \) is \( k\times k \), and \( V^* \) is \( k\times T \). We interpret this in the following way: the columns of \( U \) are the dominant modes in our data, and the rows of \( \Sigma V^* \) tell us how these modes vary in time. We can therefore use the columns of \( \Sigma V^* \), which are of height \( k \), as our approximation to the input data.

In general the input and target data will not be of the same size or, for time series data, of the same dynamics. However, in the case that they are the rank reduction used on the input and output can be computed simultaneously saving a large computation. While it will no longer be the optimal reduction for each of these, it will be near optimal. In this paper we are generally building steppers, and so the input and target are of the same system at different times. We therefore compute the low dimensional spaces by taking the SVD of the full data set, and then split it into the input and target data sets.

\section{Algorithm Implementation and Development}

\subsection{Neural Network Framework}
We use the python libraries Keras and Tensorflow for most of our neural nets. In addition the neural network package for MATLAB is occasionally used.

In general, the setup and labeling of the data was the primary focus of this project. It is straightforward to change the net structure and tune other hyperparameters once this has been done. However, doing so is time consuming. If any of the nets work at all this should be taken as very encouraging since they were generally chosen at random without much justification.

\subsection{Data Generation}
To generate data for our systems we generally use an ODE stepper to solve a system of ODEs corresponding to the discrimination of a PDE. The target data is taken to be the training data one step forward in time (with respect to some fixed time mesh). Multiple initial conditions are generated in a variety of ways depending on

\subsection{Kuramoto-Sivashinsky Equation}
We are provided with a stepper to produce solutions to the Kuramoto-Sivashinsky equation (\ref{KS_eqn}) with periodic boundary conditions on a given mesh (with \( N \) spatial points and \( T \) time points).
\begin{align}
    \pp{u}{t} = -u \pp{u}{x} - \pp[2]{u}{x} - \pp[4]{u}{x} \label{KS_eqn}
\end{align}

In order to train our network to step forward in time we must generate a batch of trajectories stemming from some class of initial conditions. To do this we start with a zero initial condition and then randomly set a fixed (generally two or three) number Fourier modes to have weights with real and imaginary parts uniformly distributed on \( [-N/2,N/2] \). This produces periodic initial conditions which lead to fairly nice behavior. We then generate a solutions with these initial conditions and save them.

The data is then imported to Python and formatted into the training and target data sets by appropriate slicing. A neural net defined in Keras is trained to predict the value of \( u(t+\Delta t) \) given the value of \( u(t) \).

\begin{figure}[t]\centering
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/svd_mode_1.pdf}
    \caption{1st left singular vector reshaped}
    \label{1mode}
\end{subfigure}\hfill
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/svd_mode_100.pdf}
    \caption{100th singular vector reshaped}
    \label{100mode}
\end{subfigure}
\caption{SVD modes for \( u \) (left) and \( v \) (right) }
\label{SVD_modes}
\end{figure}

\begin{figure}[t]\centering
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/svd_coeff_1.pdf}
    \caption{1st right singular vector varying in time}
    \label{1coeff}
\end{subfigure}
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/svd_coeff_100.pdf}
    \caption{100th right singular vector varying in time}
    \label{100coeff}
\end{subfigure}
\caption{coefficients of SVD modes vs dataset}
\label{SVD_coeff}
\end{figure}

\subsection{ \( \boldsymbol\lambda \)-\( \boldsymbol\omega \) Reaction-Diffusion Equation}
We can apply similar methods to a PDE in two dimensions.
With,
\begin{align*}
    {\bf u} = \left[\begin{array}{c}u \\ v\end{array}\right], &&
    {\bf D} = \left[\begin{array}{cc}d_1 \\ & d_2 \end{array}\right]
\end{align*}
the Kuramoto-Sivashinsky equation is defined as,
\begin{align}
    \pp{{\bf u}}{t} =
    \left[\begin{array}{cc}
        \lambda(s) & -\omega(s) \\
        \omega(s) & \lambda(s)
    \end{array}\right]
    {\bf u}
    + {\bf D} \nabla^2 {\bf u} \label{RD_eqn}
\end{align}
where,
\begin{align*}
    s^2 = u^2 + v^2, &&
    \lambda = 1-s^2, &&
    \omega = -\beta s^2
\end{align*}

Again we are given a stepper which produces trajectories on a fixed mesh. Like with the KS equation, we generate initial conditions by picking some Fourier modes to be nonzero and use these to generate trajectories which we load into Python.

Since the data is much larger than before, training a neural net (we tried) is very slow. While the size of data used in industry is often massive, they also have massive computers and lots of time. We don't, so to deal with the large data set we reduce the rank of our data and train on the projections. Since the training and target data come from the same space we compute the SVD the entire dataset before splitting it into training and target data. This allows us to find a single subspace for both the training and target data, saving on computing and saving two subspaces (which would turn out to be almost identical since the vast majority of the data in each of these sets would be the same).

\begin{figure*}[h]\centering
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/sample_KS_trajectory.pdf}
    \caption{trajectory generated by {\tt solve\_ivp}}
    \label{sample_KS_trajectory}
\end{subfigure}\hfill
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/predicted_KS_trajectory.pdf}
    \caption{trajectory generated by neural net}
    \label{predicted_KS_trajectory}
\end{subfigure}
\caption{``actual'' and neural net predicted trajectories for Kuramoto-Sivashinsky equation (\ref{KS_eqn})}
\label{KS_trajectory}
\end{figure*}

Figure~\ref{1mode} shows the dominant left singular vector and Figure~\ref{1coeff} shows how the first right singular vector varies in time. The ``spikes'' down clearly are related to the initial conditions of the data. However, after each spike there is an oscillation in this mode. Moreover, the mode itself has quite a bit of structure, which it seems to have inherited from the way we generated initial conditions. It is not clear whether this structure would die out if we ran the simulations for longer time. Regardless, since the structure is present in our data set we can use this to train a neural net on the rank-reduced data.

We take the rank \( k \) SVD (\ref{SVD_eq}) (determined by a parameter flag) and then train the network on the weights of the basis of the subspace spanned by the first \( k \) columns of \( U \).

To test our prediction we take a trajectory not used for training, project it to the column span of \( U \), iteratively apply the network, and then embed back to the original space.

\subsection{Lorenz Equation}
The Lorenz equation (\ref{lorenz_eq}) is a system of ODEs which have chaotic solutions for some parameters. It was demonstrated in \cite{lecture_notes} that for a fixed \( \Delta t \) a simple neural network can be trained to predict the position at a time \( t+\Delta t \) given the position at time \( t \) accurately enough that the trajectory determined by iteratively applying the trained neural net matches the trajectory of a given ODE solver almost exactly. Given that the system is chaotic for these values it is somewhat surprising that the neural net manages to follow the same trajectory by only predicting one step at a time. Training data was generating using Scipy's {\tt solve\_ivp} with a tolerance of \( 10^{-10} \) and evaluating the solution along a mesh of uniformly spaced times.

\begin{align}
    \pp{}{t} \left[\begin{array}{c}x\\y\\z\end{array}\right]
    =
    \left[\begin{array}{c}
        \sigma(y-x) \\
        x (\rho-z)-y \\
        x y-\beta z
    \end{array}\right] \label{lorenz_eq}
\end{align}

We explore the Lorenz equation in two further ways, namely trying to predict trajectories for varying values of the parameter \( \rho \) and trying to predict when the solution will transition from one lobe to another.

The first task is straightforward. In particular, a neural net is trained on data where the input corresponds to the current position as well as the value of \( \rho \), and the output is the position after a time of \( \Delta t \). More specifically, we fix \( \sigma = 10 \), \( \beta = 8/3 \), and train on data with \( \rho = 10,28,40 \). We then try to use this net to predict trajectories for \( \rho = 17 \) and \( \rho = 35 \).

The second tasks requires some interpretation. We decided to train a network to determine how long until a lobe switch. To train such a network requires that we know how long it will be until the solution switches lobes. To do this we first classify what it means to be at a given lobe. This is done by separating the data with plane as shown in Figure~\ref{separating_hyperplane}. Let \( c \) be a normal vector for this hyperplane. Then the sign of \( c^Tx \) will determine which side of the plane a given point is on.

We pick \( c \) roughly in the direction of the vector connecting the two centers in the \( x \)-\( y \) plane. While there are probably better ways to do this, it seems like the projection to this plane provides a straightforward way to separate points circle different lobes.

Therefore, given a trajectory \( X \), each point in the trajectory can be classified as ``left'' or ``right''. Once this is done, we know that transitions across the plane occur when the trajectory switches from ``left'' to ``right'' or from ``right'' to ``left''. We compute these transition points by taking the difference of consecutive points in \( \operatorname{sign}(c^TX) \). If the difference is nonzero then the trajectory has switched lobes. Once we have these transition points it is relatively straightforward label each point in the trajectory with far each point is from the next crossover.

As a minor note, some of the data from the end of the each trajectory is discarded because it is not possible to tell when the next transition will occur without stepping out the solution further. We then train a neural network to try and predict the time until a crossover.
\begin{figure}[tb!]\centering
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/uv_t180.pdf}
    \caption{original data}
    \label{time_image}
\end{subfigure}\hfill
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/svd_t180.pdf}
    \caption{SVD (rank 100)}
    \label{SVD_time_image}
\end{subfigure}
\caption{snapshot of \( u \) (left) and \( v \) (right) at time \( t=180 \)}
\label{RD_SVD}
\end{figure}

\begin{figure}[b!]\centering
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/prediction_t15.pdf}
    \caption{actual trajectory}
    \label{sample_RD_trajectory}
\end{subfigure}\hfill
\begin{subfigure}{.45\textwidth}\centering
    \includegraphics[width=\textwidth]{img/svd_prediction_t15.pdf}
    \caption{predicted trajectory}
    \label{predicted_RD_trajectory}
\end{subfigure}
\caption{``actual'' and neural net predicted trajectories for Reaction Diffusion Equation (\ref{RD_eqn}) at \( t=15 \)}
\label{RD_trajectory}
\end{figure}

\begin{figure}[t!]\centering
\begin{subfigure}{.45\textwidth}\centering
\includegraphics[width=\textwidth]{img/NN_lrz17_trajectory.pdf}
\caption{\( \rho = 17 \)}
\end{subfigure}\hfill
\begin{subfigure}{.45\textwidth}\centering
\includegraphics[width=\textwidth]{img/NN_lrz35_trajectory.pdf} \hfill
\caption{\( \rho = 35 \)}
\end{subfigure}
\caption{Actual trajectory (solid) vs predicted trajectory (dotted) for variious values of \( \rho \)}
\label{xyz_trajectory}
\end{figure}

\section{Computational Results}

\subsection{Kuramoto-Sivashinsky Equation}

Figure~\ref{sample_KS_trajectory} shows a sample trajectory generated by our ODE stepper (not part of traninig data). Figure~\ref{predicted_KS_trajectory} shows the prediction of the neural net on the same trajectory. However, as time progresses the neural net predicted solution does not really change, while the reaction diffusion equation does continue to evolve.

\subsection{ \( \boldsymbol\lambda \)-\( \boldsymbol\omega \) Reaction-Diffusion Equation}
Figure~\ref{time_image} shows a snaptshot of a trajectory at time \( t=180 \). Figure~\ref{SVD_time_image} shows the same snapshot after it has been projected into a 100 dimensional subspace determined by the SVD. While a plot of the singular values shows no clear cutoff in the rank, visually it seems that the data is fairly well represented by the first 100 modes. We proceed to train a neural network on the rank reduced data.

\begin{figure}[bt!]\centering
\begin{subfigure}{.45\textwidth}\centering
\includegraphics[width=\textwidth]{img/separating_hyerplane.pdf}
\caption{Projection of sample trajectory onto the \( x \)-\( y \) plane along with image of plane \( y + 5x +0z = 0 \).}
\label{separating_hyperplane}
\end{subfigure}\hfill
\begin{subfigure}{.45\textwidth}\centering
\includegraphics[width=\textwidth]{img/jump_predictor.pdf}
\caption{Actual time to jump (solid) vs. predicted time to jump (dotted) for sample trajectory .}
\label{jump_predictor}
\end{subfigure}
\caption{}
\end{figure}

\subsection{Lorenz Equation}
Sample predictions for \( \rho = 17 \) and \( \rho = 35 \) produced by the trained net are shown in Figure~\ref{xyz_trajectory}. Note that we do not cross validate in the normal sense, since that would be testing how well our net can predict one step in the future. In fact, the cross validation would show a very high accuracy since we are able to predict the long term behavior relatively well despite only training n the current position.

Figure~\ref{jump_predictor} shows the results of applying the trained net to every point in a trajectory. This plot makes it clear that we are actually able to fairly effectively determine when a jump will occur given only the current position. Note here that the horizontal axis labeling is just the index of the point in the trajectory and has no impact on the neural net's prediction as it is applied independently to each point.

\pagebreak
\section{Summary and Conclusions}
It is clear that the trajectories of the Kuramoto-Sivashinsky and Reaction Difussion equations were not effectively predicted. On the other hand, solutions to the Lorenz equation, even for values of \( \rho \) which the neural net had never seen, were quite successful. Finally, we were able to train a neural net to predict how long it would take a trajectory to switch lobes.

Due to time constraints only simple nets were used and all hyperparameter training was done by guessing. We instead chose to focus on producing the training data in a scalable way so that in the future it would be a trivial task to generate data at large mesh sizes. With the current state of our codebase, testing new neural nets is as easy as changing a few lines in Keras. Given more time we would have liked to set up convolutional neural nets to see if the local structure of the data would be enough to determine the global behavior. In general we probably did not use enough data, and the nets we used are probably too small to be able to get very good results. However, what we did find is somewhat encouraging and given more time would be worth pursuing.

\bibliographystyle{plain}
\bibliography{hw2}

\onecolumn
\section{Appendix A}
\label{AppendixA}
All functions are included in the code in Appendix B as they are specific to the task performed in each of the files.

%\pagebreak
\section{Appendix B}
\lstinputlisting[]{PDECODES/KS_data_gen.m}
\lstinputlisting[]{python/hw2_ks.py}
\lstinputlisting[]{PDECODES/RD_data_gen.m}
\lstinputlisting[]{python/hw2_rd.py}
\lstinputlisting[]{python/hw2_lrz.py}
\lstinputlisting[]{python/lrz_classifier.py}

\end{document}