\section{Fl---The Meta Language of Voss}

In this section\footnote{This section is to a large extent modeled
after Chapter 1 in the HOL System DESCRIPTION from Cambridge University.
In particular, many of the early examples are taken from this source.}
we provide an introduction to the functional language FL.

Similar to many theorem provers (e.g., the HOL%
\index{HOL}%
{}
system~\cite{HOLsystem,HOLbook}) the
Voss command language for the verification system is a general
purpose programming language%
\index{programming language}%
{}.
In fact, the FL language shows a strong degree of influence from
the version of ML%
\index{ML}%
{} used in the HOL-88%
\index{HOL-88}%
{} system.
However, there are several differences:  many syntactic but some
more fundamental.
In particular, the functional language used in Voss has lazy evaluation
semantics.
In other words, no expression is evaluated until it is
absolutely needed.
Similarly, no expression is evaluated more than once.
Another difference is that Boolean functions are first-class
objects and can be created, evaluated, compared and printed out.
For efficiency reasons these Boolean functions are represented as
ordered binary decision diagrams%
\index{ordered binary decision diagrams}%
{}.

Fl is an interactive language.
At top-level one can:
\begin{enumerate}
\item define functions (possibly of arity 0),
\item define new concrete types,
\item define aliases for types,
\item modify the parser, and
\item evaluate expressions.
\end{enumerate}
In this section we introduce the language by several examples.

\subsection{Invoking FL}

If the Voss system is installed on your system
and you have the suitable search path set up, it suffices
to type \verb@fl@ to get a stand-alone version of FL. In this manual, we
have used Voss 1.8b throughout. In other words, typing \verb@fl@ yielded:

\begin{hol}
% fl
      /\verb@\@
     /  \verb@\@/\verb@\@
 /\verb@\@ /      \verb@\@
/  Voss 1.8b\verb@\@
VOSS-LIBRARY-DIRECTORY = /isd/local/generic/lib/vosslib

:
\end{hol}
Note that the VOSS-LIBRARY-DIRECTORY%
\index{VOSS-LIBRARY-DIRECTORY}%
{} is installation dependent.
We return to this below and in Section~\ref{vossrc}.

The fl program can take a number of arguments.
\index{command-line arguments}
In particular,
\begin{description}
\item[-d]
Turn debugging mode%
\index{debugging mode}%
{} on.
In this mode a function call trace%
\index{call trace}%
{} will be generated
when a failure that is not caught by an exception handler occurs.
This feature is not as useful as in many other languages, but
is retained for backwards compatibility.
\item[-D]
Turn debugging mode off.
Unless the DEBUG-ON flag is set in the .vossrc file, the default
is for debugging mode to be turned off.
\item[-f n]
Start FL by first reading in the content of the file named n.
\item[-h]
A flag that is needed when fl is used as a subroutine in the
HOL%
\index{HOL}%
{} theorem prover in the HOL-Voss%
\index{HOL-Voss}%
{}
system~\cite{JoyceSegerDAC,SegerJoyceTwoLevel}.
This flag should not be used when FL is used stand-alone.
\item[-I dir]
Set the default search directory%
\index{search directory}%
{} to dir.
\item[-s i]
Set the initial OBDD table size to be $2^i$, where $i$ can range
from 12 to 24.
Note that each OBDD node in this table requires 16 bytes, and thus
the memory requirement increases very rapidly with increasing table size.
Note that FL automatically grows the OBDD table if it needs to, and
the only reason using this flag is to reduce the time it takes
to grow the tables.
The flag is kept for historical reasons, but with the modern
dynamical re-ordering version of the OBDD table, this user setable
constant is rarely needed.
\index{OBDD!table size}
\index{dynamic variable re-ordering}
\item[-o]
Before reaching the fl command prompt, print out all defaults
read from the .vossrc%
\index{.vossrc}%
{} file.
This is useful both for finding out the names of most (but unfortunately
not all) options%
\index{options}%
{} as well as checking that a particular option
has the correct value.
\item[-r i]
Initialize the random number%
\index{random number}%
{} generator with the seed i.
This allows the {\tt rvariable}
\index{rvariable}%
{} command to create new sets
of random variable values.
See the rvariable command description in Section~\ref{rvariable} for
more details.
\item[-v fn]
Store the variable ordering obtained by dynamic variable re-ordering%
\index{variable re-ordering}%
{}
in the file fn.
\index{dynamic variable re-ordering}
\end{description}

\subsection{Expressions}
\index{expressions}
The Fl prompt%
\index{prompt}%
{} is : so lines beginning with this contain
the user's input; all other lines are output of the system.
\begin{hol}
: 2+3;
it::int
5
\end{hol}
Here we simply evaluated the expression 2+3 and FL reduced
it to normal form; in this case computed the result 5. Note that
fl does only support integers%
\index{integers}%
{} as number types.
The integers are represented in arbitrary precision, and grow as needed.

Note also that Voss stores the result of the most recent expression
in a variable called {\tt it}.
\index{it}%
Thus, continuing the example by evaluating the expression {\tt it;} yields:
\begin{hol}
: it;
it::int
5
\end{hol}

\subsection{Declarations}

The declaration%
\index{declaration}%
{} let x = e binds a computation of e to
the variable x.
Note that it does not evaluate e (since the language is fully lazy%
\index{lazy}%
{}).
Only if x is printed or used in some other expression that is evaluated
will it be evaluated.
Also, once e is evaluated, x will refer to the result of the evaluation
rather than the computation.
Hence, the expression e is evaluated at most once, but it may
not be evaluated at all.
\begin{hol}
: let x = 3+3;
x::int
\end{hol}
Note that when expressions are bound to variables, the system simply
prints out the inferred type%
\index{inferred type}%
{} of the expression. We will return to
the typing scheme in FL later.
For now, it suffices to say that FL tries to find as general type as
possible that is consistent with the type of the expression.

A declaration%
\index{declaration!local}%
{} can be made local to the evaluation of an expression
e by evaluating the expression decl in e.
For example:
\begin{hol}
: let y = let x = 4 in x-5;
y::int
\end{hol}
would bind the expression 4 to x only inside the expression
bound to y. Thus, we get:
\begin{hol}
: let x = 2;
x::int
: let y = let x = 4 in x-5;
y::int
: x;
2
: y;
-1
\end{hol}
FL is lexically scoped%
\index{scoping}%
{}, and thus
the binding in effect at the time of definition is the one used.
In other words, if we write:
\begin{hol}
: let x = 2;
x::int
: let y = x*5;
y::int
: let x = 12;
x::int
\end{hol}
and we then evaluate y we will get 10
rather than 60.

Contrary to ML, at the top level FL 1.8b does not allow
simultaneous bindings%
\index{simultaneous bindings}%
{}.
Hence, if we would like to bind the expressions 2 and 4-5 to the
variables x and y respectively, we would have to write:
\begin{hol}
: let x = 2;
x::int
: let y = 4-5;
y::int
\end{hol}
However, inside local bindings, a special keyword {\tt val}
\index{val}%
{}
is available to take a complicated object apart automatically.
For example, if e is an expression of type (int\verb@#@bool) then
we could write:
\begin{hol}
: let top\_level q =
	val (i,b) = q in
	i < 3 => b | F;
top\_level::(int\verb@#@bool)->bool
\end{hol}
In general, the expression to the right of the val keyword
can be an arbitrary complex pattern similar to the patterns%
\index{patterns}%
{}
allowed in function definitions and lambda expressions.
For more details, see the section on pattern matching on page~\ref{val}.

\subsection{Functions}

To define a function%
\index{function}%
{} f with formal parameter x and body e one performs
the declaration: let f x = e.
To apply the function f to an actual parameter e one evaluates
the expression f e.
\begin{hol}
: let f x = x+2;
f::(int) -> (int)
: f 4;
6
\end{hol}
Note that the type inferred for f is essentially ``a function taking
an int as argument and returning an int''.
Applications binds more tightly than anything else in FL; thus for example:
f 3 * 4 would be evaluated as: ((f 3)*4) and thus yield 20.

Functions of several arguments can also be defined:
\begin{hol}
: let add x y = x+2*y;
add::(int) -> ((int) -> (int))
: add 1 4;
9
: let f = add 1;
f::(int) -> (int)
: f 4;
9
\end{hol}
Applications associate%
\index{association rules}%
{} to the left so add 3 4 means (add 3) 4. In the
expression add 3, the
function add is partially applied to 3; the resulting value is the
function of type int\funarrow int which
adds 3 to twice its argument. Thus add takes its arguments one at a time.
We could have made add take a single argument of the cartesian product%
\index{cartesian product}%
{}
type (int\verb@#@int):
\begin{hol}
: let add (x,y) = x+y;
add::((int # int)) -> (int)
: add (3,4);
7
: add 3;
===Type mismatch: (int # int) and int
#### Run-time error
---- Type error
\end{hol}
As well as taking structured arguments (e.g. (3,4)) functions may also return
structured results:
\begin{hol}
: let manhat\_dist (x1,y1) (x2,y2) = (x2-x1, y2-y1);
manhat\_dist::((int # int)) -> (((int # int)) -> ((int # int)))
: manhat\_dist (1,1) (3,5);
(2,4)
\end{hol}

Trying to print%
\index{print}%
{} a function with insufficient number of actual arguments
yield a dash for the function and the type of the expression is printed out.
For example:
\begin{hol}
: (5, manhat\_dist (1,2));
(5,-) ::(int # ((int # int)) -> ((int # int)))
\end{hol}
The only exception to this rule is for concrete types
for which the user has installed a printing function%
\index{printing function}%
{}.
For more details of concrete types, see page~\ref{concreteTypes}.

\subsection{Recursion}

The following is an attempt to define the factorial function:
\begin{hol}
: let fact n = n=0 => 1 | n*fact (n-1);
#### Run-time error
---- Undefined variable (fact)
\end{hol}
The problem is that any free variables in the body of a function have
the bindings they had
just before the function was declared; fact is such a free variable
in the body of the declaration
above, and since it is not defined before its own declaration, an error
results. To make things
clear consider:
\begin{hol}
: let f n = n+1;
f::(int) -> (int)
: let f n = n=0 => 1 | n*f (n-1);
f::(int) -> (int)
: f 3;
9
\end{hol}
Here 3 results in the evaluation of 3*(f 2), but now the first f is
used so f 2 evaluates to 2+1=3.
To make a function declaration hold within its own body, letrec%
\index{letrec}%
{}
instead of let must be used.
The correct recursive%
\index{recursive}%
{} definition of the factorial function is thus:
\begin{hol}
: letrec fact n = n=0 => 1 | n*fact (n-1);
fact::(int) -> (int)
: fact 5;
120
\end{hol}

It should be pointed out that FL currently does not allow direct definition
of mutually recursive functions%
\index{mutually recursive functions}%
{}.
For an example on how this limitation can be dealt with, see
the subsection on concrete type decalartions.

\subsection{Tuples}

If $e\_1, e\_2, \ldots , e\_n$ have types $t\_1, t\_2, \ldots , t\_n$, then
the FL expression $(e\_1, e\_2, \ldots , e\_n)$ have type
$t\_1$\verb@#@$t\_2$\verb@#@$\ldots$\verb@#@$t\_n$.
The standard functions on tuples are fst%
\index{fst}%
{} (first), snd%
\index{snd}%
{} (second), and the infix
operation , (pair%
\index{pair}%
{}).
\begin{hol}
: let q = ((1,2),3);
q::((int # int) # int)
: let qq = (1,2,3);
qq::(int # (int # int))
: q;
((1,2),3)
: qq;
(1,2,3)
: let qqq = (1,"abc");
qqq::(int # string)
: qqq;
(1,"abc")
\end{hol}

\subsection{Lists}

If $e\_1, e\_2, \ldots , e\_n$ have type $t$, then the FL expression
$[e\_1, e\_2, \ldots , e\_n]$ has type ($t$ list%
\index{list}%
{}).
The standard functions on lists are hd%
\index{hd}%
{} (head%
\index{head}%
{}), tl%
\index{tl}%
{} (tail%
\index{tail}%
{}), []%
\index{[]}%
{} (the empty list%
\index{empty list}%
{}), and the infix operation : (cons%
\index{cons}%
{}).
Note that all elements of a list must have the same type (compare
this with a tuple where the size is determined but each member of
the tuple can have different type).
\begin{hol}
: let l = [1,2,3,3,2,1,2];
l::(int list)
: hd l;
1
: tl l;
[2,3,3,2,1,2]
: 0:l;
[0,1,2,3,3,2,1,2]
: letrec (len [] = 0) /\verb!\! (len (a:rest) = 1+len rest);
len::((* list)) -> (int)
: len l;
7
\end{hol}

\subsection{Strings}

A sequence of characters enclosed between \verb@"@ or \verb@`@ is a string%
\index{string}%
{}.
The standard functions on strings are \verb@^@ (catenation%
\index{catenation}%
{}), explode%
\index{explode}%
{}
(make string into list of strings) and
implode%
\index{implode}%
{} (make list of strings into single string).
There are also int2str%
\index{int2str}%
{} and bool2str%
\index{bool2str}%
{} functions that create a string
from an integer or an object of type boolean.
We will return to these later.
\begin{hol}
: let q = "abc and \_12!@@#";
q::string
: let qq = `qw"q qw`;
qq::string
: q^qq;
"abc and \_12!@@#qw"q qw"
: explode q;
["a","b","c"," ","a","n","d"," ","\_","1","2","!","@","@","#"]
: implode ["1", "2"];
"12"
: int2str (1-34);
"-33"
: bool2str ((variable "a") AND (variable "b"));
"a&b"
\end{hol}

\subsection{Polymorphism}

The list processing functions hd, tl, etc. can be used on all types of lists.
\begin{hol}
: hd [1,2,3];
1
: hd ["abc", "edf"];
"abc"
: (hd ["a", "b"]), hd [4,2,1];
("a",4)
: let q = [T,T,F];
q::(bool list)
: hd q;
T
\end{hol}
Thus hd has several types; for example, it is used above with types
(int list) \funarrow int,
(string list) \funarrow string, and (bool list) \funarrow bool.
In fact if ty is any type then hd has the type (ty list) \funarrow ty.
Functions, like hd, with many types are called polymorphic%
\index{polymorphic}%
{},
and FL uses type variables%
\index{type variables}%
{} *, **, ***, etc. to represent their types.
\begin{hol}
: let f x = hd x;
f::((* list)) -> (*)
: letrec map fn [] = []
   /\verb!\!    map fn (h:rest) = (fn h) : (map fn rest);
map::((*) -> (**)) -> (((* list)) -> ((** list)))
: letrec fact n = n=0 => 1 | n*fact (n-1);
fact::(int) -> (int)
: map fact [1,2,3,4,5,6,7];
[1,2,6,24,120,720,5040]
\end{hol}
The FL function map%
\index{map}%
{} takes a function f (with argument type * and result
type **), and a list l
(of elements of type *), and returns the list obtained by applying
f to each element of l
(which is a list of elements of type **). Map can be used at any instance
of its type: above, both *
and ** were instantiated to int; below, * is instantiated to (int list)
and ** to bool. Notice that the
instance need  not be  specified; it is determined by the type checker.
\begin{hol}
: let eq1 x = x=1;
eq1::(int) -> (bool)
: map eq1 [1,2,3,4,12,2,1,2];
[T,F,F,F,F,F,T,F]
\end{hol}

It should be pointed out that FL has a polymorphic type system that
is sightly different from
standard ML's. In particular, only ``top-level'' user-defined functions
can be polymorphic. In
other words, the following works as we would expect.
\begin{hol}
: let null l = l = [];
null::((* list)) -> (bool)
: let f x y = null x OR null y;
f::((* list)) -> (((** list)) -> (bool))
: f [1,2,3] ["abc", "cdef"];
F
\end{hol}
However, if we use the same declaration inside the expression, it must
be monomorphic%
\index{monomorphic}%
{}. In other
words, the following example fails.
\begin{hol}
: let f x y =
    let null l = l = [] in
    null x OR null y;
f::((* list)) -> (((* list)) -> (bool))
: f [1,2,3] ["abc", "cdef"];
===Type mismatch: int and string
#### Run-time error
---- Type error
\end{hol}
In this respect, FL is similar to the functional language called
Miranda\footnote{Miranda is a trademark of
Research Software Ltd.}~\cite{Miranda}.

\subsection{Type Annotations}
Sometimes it is useful to inform the type inference mechanism
of FL what type is expected.
In particular, when using overloaded%
\index{overloaded}%
{} operators or functions
it is quite common to have to explicitly type arguments.
In FL a variable or expression can be annotated%
\index{type annotation}%
{} with its expected
type by enclosing it in curly braces and decorate the expression
with a type expression.
In particular, if we would like to define a function ihd that
return the head of a list, but that only can be used on integer lists,
we could define ihd as follows:
\begin{hol}
let ihd \{l::int list\} = hd l;
\end{hol}
Similarly, if we have overloaded the operator + to either
operate over strings or integers, we can extend this opverloading
with yet another function by declaring
\begin{hol}
overload + \{+::int->int->int\} \{+::string->string->string\} foo;
\end{hol}
If we now were to write a function that adds three integer numbers
we would have to decorate the types so that the overload resolution
can succeed. For example, we could write:
\begin{hol}
let f \{x::int\} \{y::int\} \{z::int\} = x+y+z;
\end{hol}
or we could write
\begin{hol}
let f x y z = \{x+\{y::int\} ::int\}+z;
\end{hol}
although the former is easier to read and more general.

\subsection{Lambda Expressions}

The expression \verb@\@x.e evaluates to a function with formal parameter x
and body e. Thus the
declaration let f x = e is equivalent to let f = \verb@\@x.e. The character
\verb@\@ is our representation of lambda,
and expressions like \verb@\@x.e are called lambda-expressions%
\index{lambda-expressions}%
{}.
\begin{hol}
: \verb!\!x.x+1;
- ::(int) -> (int)

: let q = \verb!\!x.x+1;
q::(int) -> (int)
: q 1;
2
: map (\verb!\!x.x*x) [1,2,3,4,5];
[1,4,9,16,25]
\end{hol}

\subsection{Failures}

Some standard functions fail at run-time on certain arguments, printing
out a string (which is usually the function name) to identify the sort
of failure. A failure%
\index{failure}%
{} with string "t" may also be
generated explicitly by evaluating the expression error "t" (or more
generally error%
\index{error}%
{} e where e has type string).
\begin{hol}
: hd(tl [2]);
Failure:    ----  Cannot compute hd of the empty list

: 1/0;
Failure:    ----  Division by zero

: error "My message";
Failure:    ----   My message
\end{hol}

A failure can be trapped%
\index{trap a failure}%
{} by catch%
\index{catch}%
{}; the value of the expression $e\_1$ catch
$e\_2$ is that of $e\_1$, unless
$e\_1$ causes a failure, in which case it is the value of $e\_2$. One important
property of catch is that it is
(very) strict in its first argument. In other words, (hd ($e\_1$ catch
$e\_2$)) will completely evaluate $e\_1$
even though only the first element in the list may be needed. In view
of FL's lazy semantics%
\index{lazy semantics}%
{}, the
use of catch should be very carefully considered. In particular, the
bindings of catch is dynamic
rather than static so the user beware!

\subsection{Boolean Expressions}

All Boolean expressions%
\index{Boolean expression}%
{} in FL are maintained as ordered binary decision
diagrams. Hence, it
is very easy to compare complex Boolean expressions and to combine
them in different ways.
Boolean variables%
\index{Boolean variable}%
{} are created by variable%
\index{variable}%
{} s, where s is of type string.
The system uses name
equivalence, and thus
\begin{hol}
: let v = variable "v";
v::bool
: v=v;
T
: variable "v" = variable"v";
T
\end{hol}

The constants true%
\index{true}%
{} and false%
\index{false}%
{} are denoted T and F respectively. The
standard boolean functions
are available, i.e., AND%
\index{AND}%
{}, OR%
\index{OR}%
{}, NOT%
\index{NOT}%
{}, XOR%
\index{XOR}%
{}, and =%
\index{=}%
{} are all defined for objects of type Boolean..
Furthermore, there
is a special identity%
\index{identity}%
{} operator ==%
\index{==}%
{} that return true or false depending
on whether the two arguments
represent the same Boolean function or not.

Note that the variable ordering%
\index{variable ordering}%
{} in the OBDD representation is defined
by the order in which each variable function call {\em gets evaluated}.
Since FL is a fully lazy language%
\index{lazy language}%
{}, and thus the order in which expressions
are evaluated is often difficult to predict, it is strongly recommended
that each variable declaration is forced to be evaluated before it
is being used.
Alternatively, one can request that FL re-orders the variables
by evaluating the function var\_order%
\index{var\_order}%
{} and give as argument a list
of variable names.
FL will then apply the dynamic variable re-ordering mechanism and
enforce that the variables mentioned in the list will be the first
arguments and that they will occur in exactly this order.
\begin{hol}
: let a = variable "a";
a::bool
: let b = variable "b";
b::bool
: a AND b;
a&b
: a OR b;
a + b
: NOT a AND NOT b AND T;
a'&b'
: a = b;
a&b + a'&b'
:  a == b;
F
: (a=b) == (a AND b OR NOT a AND NOT b);
T
\end{hol}

The default style for printing Boolean expressions%
\index{printing Boolean expressions}%
{} is as a sum-of-products%
\index{sum-of-products}%
{}.
Since this may require printing an extremely large expression, there
is a user-setable limit on how many products that will be printed
and the maximum size of a product.
For more details how to modify these two parameters, see Section~\ref{vossrc}.

\subsection{Quantifiers}

There are several ways of using quantification%
\index{quantification}%
{}.
The ``traditional'' !x. e%
\index{$!x.\,e$}%
{} (for all x) and ?x. e%
\index{$?x. e$}%
{}
(there is an x) can be used as long as the type of x and e is bool.
In addition, you can also quantify away a variable in an expression
by quant\_forall%
\index{quant\_forall}%
{} v e or quant\_thereis%
\index{quant\_thereis}%
{} v e.
\begin{hol}
: !a. ?b. (a XOR b);
T
: let a = variable "a"; let b = variable "b"; let c = variable "c";
a::bool
b::bool
c::bool
: : : a AND b OR c;
a&b + c
:  quant\_forall a (a AND b OR c);
c
: quant\_thereis (a OR c) (a AND b OR c);
T
\end{hol}
In fact, quant\_forall and quant\_thereis quantifies away all variables
in the first Boolean expression.
For example:
\begin{hol}
: let v s = variable s;
v::(string) -> (bool)
: let a = v "a"; let b = v "b"; let c = v "c"; let d = v "d";
a::bool
b::bool
c::bool
d::bool
: : : : let ex = (a AND NOT b);
ex::bool
: ex;
a&b'
: let nex = ex AND (a=c) AND (b=d);
nex::bool
: quant\_thereis (a AND b) nex;
c&d'
\end{hol}
Note that the actual Boolean expression used as first argument is irrelevant.
The only important fact is on what variables the expression depends.

\subsection{Dependencies}

Sometimes it is useful to find out which Boolean variables a
Boolean function actually depends on.
The built-in function depends%
\index{depends}%
{} takes a list of elements of type
bool and return the union of the variables these functions depend on.
For example:
\begin{hol}
: let v s = variable s;
v::(string) -> (bool)
: let a = v "a"; let b = v "b"; let c = v "c"; let d = v "d";
a::bool
b::bool
c::bool
d::bool
: : : : let ex1 = (a=c) AND d;
ex1::bool
: let ex2 = a = b;
ex2::bool
: depends [ex1];
["a","c","d"]
: depends [ex1,ex2];
["a","b","c","d"]
\end{hol}

Note that the order of the variables in the list returned by depends
is the variable order of the OBDD representation.

\subsection{Substitutions}

Given a Boolean function represented as an OBDD, it is convenient to
be able to apply the function to some arguments.
This can be accomplished by the substitute%
\index{substitute}%
{} command that takes a
list of (variable name, expression) and an expression in which the
simultaneous substitution%
\index{substitution}%
{} is to be made.
For example,:
\begin{hol}
: let v s = variable s;
v::(string) -> (bool)
: let a = v "a"; let b = v "b"; let c = v "c"; let d = v "d";
a::bool
b::bool
c::bool
d::bool
: : : : let ex = (a AND NOT b);
ex::bool
: ex;
a&b'
: substitute [("a", c), ("b", d)] ex;
c&d'
\end{hol}

It should be pointed out that there are no restrictions on the expressions
in the substitutions.
In particular, it is possible to ``swap'' variables.
We illustrate this by continuing the example above:
\begin{hol}
: ex;
a&b'
: substitute [("a", b), ("b", a)] ex;
a'&b
\end{hol}

\subsection{Type Abbreviations}
\index{type abbreviations}

Types can be given names:
\begin{hol}
: new\_type\_abbrev pair = int#int;
: let p = (1,2);
p::(int # int)
\end{hol}
However, as can be seen from the example, the system does not
make any distinction between the new type name
and the actual type. It is purely a short hand that is useful when
defining concrete types below.

\subsection{Concrete Types}

New types (rather than mere abbreviations) can also be defined.
Concrete types%
\index{concrete type}%
{} are types
defined by a set of constructors%
\index{type constructor}%
{} which can be used to create objects
of that type and also (in
patterns) to decompose objects of that type. For example, to define
a type card one could use the
construct type:
\begin{hol}
: lettype card = king | queen | jack | other int;
other::(int) -> (card)
jack::card
queen::card
king::card
\end{hol}
Such a declaration declares king, queen, jack and other as constructors
and gives them
values. The value of a 0-ary constructor such as king is the constant
value king. The value of a
constructor such as other is a function that given an integer value
n produces other(n).
\begin{hol}
: king;
- ::card

: other 9;
- ::card
\end{hol}

Note that there is no print routine%
\index{print routine}%
{} for concrete types. If a print
routine is desired, one has to
define it.
To define functions that take their argument from a concrete type,
we introduce the idea of pattern matching%
\index{pattern matching}%
{}.
In particular
\begin{hol}
let f pat1 = e1
 /\verb@\@ f pat2 = e2
 /\verb@\@ ...
 /\verb@\@ f patn = en;
\end{hol}
denotes a function that given a value v selects the first pattern that
matches $v$, say pati, binds the variables of pati to
the corresponding components of the value $v$ and then evaluates the
expression ei.
We could for example define a print function for the cards in the following way:
\begin{hol}
: let pr\_card king = "K"
  /\verb@\@  pr\_card queen = "Q"
  /\verb@\@  pr\_card jack = "J"
  /\verb@\@  pr\_card (other n) = int2str n;
pr\_card::(card) -> (string)
: pr\_card king;
"K"
: pr\_card queen;
"Q"
: pr\_card jack;
"J"
: pr\_card (other 5);
"5"
\end{hol}
If we now issue the top-level command
\begin{hol}
: install\_print\_function pr\_card;
Installed pretty printer for objects of type: card
\end{hol}
\index{install\_print\_function}
every time we evaluate an expression of type card this routine would
be called and the string printed out on standard out.

Mutually recursive types%
\index{mutually recursive types}%
{} can also be defined. To do so, simply list
the type names on the left
hand side of the equality sign and list the type expressions on the
right hand side. For example:
\begin{hol}
: lettype IExpr, BExpr = Ivar string | Plus IExpr IExpr | ITE BExpr IExpr IExpr,
                         And BExpr BExpr | GEQ IExpr IExpr;
GEQ::IExpr->IExpr->BExpr
And::BExpr->BExpr->BExpr
ITE::BExpr->IExpr->IExpr->IExpr
Plus::IExpr->IExpr->IExpr
Ivar::string->IExpr
\end{hol}
defines two mutually recursive concrete data types for integer expressions
and Boolean expressions (very simple versions!).

Currently, FL does not provide any direct way of defining
mutually recursive functions%
\index{mutually recursive functions}%
{}.
The easiest work-around is to pass the later defined functions as
parameters to the earlier function.
After all functions have been defined, one can re-define the early ones.
To illustrate the approach, consider writing functions that converts
objects of type IExpr and BExpr to strings.
One possible solution is as follows:
\begin{hol}
: let prIExpr prBexpr expr =
    letrec prIExpr (Ivar s) = s
     /\verb@\@    prIExpr (Plus a b) = (prIExpr a)^" + "^(prIExpr b)
     /\verb@\@    prIExpr (ITE c t e) = "if "^(prBexpr c)^" then "^
                                 (prIExpr t)^" else "^(prIExpr e) in
    prIExpr expr;
prIExpr::(BExpr->string)->IExpr->string

: letrec prBExpr (And a b) = (prBExpr a) ^ " AND " ^ (prBExpr b)
   /\verb@\@    prBExpr (GEQ a b) = (prIExpr prBExpr a)^" >= "^
			     (prIExpr prBExpr b);
prBExpr::BExpr->string

: let prIExpr e = prIExpr prBExpr e;
prIExpr::IExpr->string
\end{hol}
Note that we simply pass prBExpr as an argument to the initial definition
of prIExpr.

\subsection{Abstract Types}

In FL one can also hide the definitions of types, type constructors,
and functions. By
enclosing a sequence of type declarations and function definitions
within begin\_abstype%
\index{begin\_abstype}%
{}
end\_abstype%
\index{end\_abstype}%
{} elist, only the constructors and/or functions mentioned
in the elist will be visible
and accessible for other functions and definitions. Thus, one can protect
a concrete type and only
make some abstract constructor functions available. To illustrate the
concept, consider defining a
concrete type called theorem. The only way we would like the user to
be able to create a new theorem is to give a Boolean expression that
denotes a tautology (something always true).
First we define the expression type.
\begin{hol}
: lettype expr =  Forall string expr |
                Thereis string expr |
                Var string |
                True |
                False |
                And expr expr |
                Or expr expr |
                Not expr;
Not::(expr) -> (expr)
Or::(expr) -> ((expr) -> (expr))
And::(expr) -> ((expr) -> (expr))
False::expr
True::expr
Var::(string) -> (expr)
Thereis::(string) -> ((expr) -> (expr))
Forall::(string) -> ((expr) -> (expr))
\end{hol}

We then define the concrete type theorem and the constructor function
is\_taut. Note that we
also define a couple of help functions. However, only the is\_taut function
is exported out of the
abstract type%
\index{abstract type}%
{}, and thus is the only way of creating a theorem.
\begin{hol}
: begin\_abstype;
: lettype theorem = Thm expr;
Thm::(expr) -> (theorem)
: letrec assoc x l = l = [] => error "assoc" |
                let h = hd l in
                (fst h) = x => (snd h) | assoc x (tl l);
assoc::(*) -> ((((* # **) list)) -> (**))
: letrec  (eval (Forall s e) al = !x.(eval e ((s,x):al))) /\verb@\@
        (eval (Thereis s e) al = ?x.(eval e ((s,x):al))) /\verb@\@
        (eval (Var s) al = (assoc s al) catch
                                   (error "Free variable")) /\verb@\@
        (eval True al = T) /\verb@\@
        (eval False al = F) /\verb@\@
        (eval (And e1 e2) al = (eval e1 al) AND (eval e2 al))/\verb@\@
        (eval (Or e1 e2) al = (eval e1 al) OR (eval e2 al)) /\verb@\@
        (eval (Not e) al = NOT (eval e al));
eval::(expr) -> ((((string # bool) list)) -> (bool))
: let is\_taut e = ((eval e []) == T) => Thm e |
                                       error "Not a tautology";
is\_taut::(expr) -> (theorem)
end\_abstype is\_taut;
\end{hol}

We can now use this very safe theorem system, since we can only generate
theorems that are
tautologies. For example
\begin{hol}
: let e = (Forall "a" (Thereis "b" (And (Var "a") (Var "b"))));
e::expr
: is\_taut e;
Failure:    ----   Not a tautology

: let f = (Forall "a" (Thereis "b" (Or (Var "a") (Var "b"))));
f::expr
: is\_taut f;
- ::theorem
\end{hol}

\subsection{Infix Operators}

In order to make the FL code more readable, it is possible to declare
a function to be infix%
\index{infix}%
{} (associating from the left), infixr%
\index{infixr}%
{}
(associating from the right), nonfix%
\index{nonfix}%
{} (no fixity at all), prefix
\index{prefix}%
{} (prefix operator with tighter binding than ``normal'' function definitions),
postfix%
\index{postfix}%
{}, or
of a binder%
\index{binder}%
{} type.
For the infix and infixr directives, the precedence can be given as
a number from 1 to 9, where a higher number binds tighter.
Similarly, prefix also takes a precedence number, but only 0 or 1.
Note that prefix and postfix functions bind higher than any infix function.
Beware that the fixity declaration modifies the parser and
thus remains in effect whether
the function is exported out of an abstract data type or note.
As an illustration of this idea, consider the following example:
\begin{hol}
: lettype expr = Var int |
                Mult expr expr |
                Plus expr expr |
                Negate expr;
Negate::expr->expr
Plus::expr->expr->expr
Mult::expr->expr->expr
Var::int->expr
: letrec eval (Var i) = i
  /\verb@\@     eval (Mult e1 e2) = (eval e1) * (eval e2)
  /\verb@\@     eval (Plus e1 e2) = (eval e1) + (eval e2)
  /\verb@\@     eval (Negate e1) = 0-(eval e1);
eval::expr->int
: let ** a b = Mult a b;
**::expr->expr->expr
: let ++ a b = Plus a b;
++::expr->expr->expr
: infix 4 **;
: infix 3 ++;
: let ' i = Var i;
'::int->expr
: prefix 0 ';
: let q = '1 ++ Negate '2 ** Negate '4;
q::expr
: eval q;
it::int
9
\end{hol}

The next example illustrates how postfix declarations can make the
code more readable.
\begin{hol}
: let ns i = 1000*i;
ns::(int) -> (int)
: postfix ns;
: let to a b = (a,b);
to::(*) -> ((**) -> ((* # **)))
: infix 3 to;
: 2 ns to 4 ns;
(2000,4000)
\end{hol}

Our final example deals with the binder declaration.
The command binder takes a function and makes it into a binder, i.e., an
object that introduces a new bound variable in an expression.
Note that the type of the function declared to be a binder must be
(*\funarrow **)\funarrow string\funarrow **, since the first argument of
a binder function will be a lambda expression and the second argument will
be a string with the name of the bound variable.
Thus, if a function f has been declared as a binder, then
f x.E will be parsed as f (\protect\verb!\! x.E) "x".

\subsection{Overloading}

FL supports a limited amount of user defined overloading%
\index{overloading}%
{} of functions
and operators.
However, in order to avoid an exponential type inference algorithm, the
overloaded operators must be resolved from the types of their arguments only.
To illustrate the construct, consider the following example:
\begin{hol}
: let pplus (a,b) (c,d) = (a+c, b+d);
pplus::(int#int)->(int#int)->(int#int)
: let pprod (a,b) (c,d) = (a*c, b*d);
pprod::(int#int)->(int#int)->(int#int)
: overload + + pplus;
: overload * * pprod;
: (1,2)+(3,4)*(9,3*2);
it::int#int
(28,26)
\end{hol}
Here we overloaded the symbols + and *.
Note that we essentially added new meanings to + and * since we included
the (built-in) versions as possible candidates.

The one area where overloaded operators are somewhat cumbersome to use is
when defining new functions.
Here it is often necessary to decorate the arguments to the functions
in order to make the resolution function succeed.
\begin{hol}
: let f x y z = x*(y+z);
===Type error around line 1
Cannot resolve overloading of `+'
Both `pplus' and `+' matches the type
: let f \{x::int\} \{y::int\} \{z::int\} = x*(y+z);
f::int->int->int->int
\end{hol}
Finally, overloaded operators and functions can of course also
be declared infix, binders, or postfix as any other function or operator.

\subsection{Quotation of Expressions}
\index{quotation of expression}
Sometimes it is convenient to retain the actual text that was used
to denote an expression.
By enclosing the expression in \verb@``@ and \verb@''@, FL will return
a pair consisting of the text of the expression as well as the expression
itself.
\begin{hol}
: `` 1+3*4 '';
it::string#int
(" 1+3*4 ",13)
\end{hol}
Note that it is advisable to include an extra space after the opening quotes
and before the closing quotes since the parser otherwise is likely to
view the quotes as being part of an operator or variable.

\subsection{Circuit Models}

Since the main use of the FL system, and its historical root, is related
to hardware verification, there are a number of built-in
functions specifically tailored towards hardware modeling
and symbolic trajectory evaluation in particular.
Internally, a circuit is represented by a list of nodes (names),
and a next state function%
\index{next state function}%
{}.
The next state function is mapping the current state of the circuit
(including the current values on the inputs) to a new state
of the circuit.
Since the circuit representation is intended for trajectory evaluation,
the value domain for each node in the circuit is $\{0,1,\X,\top\}$
and thus the next state function consists of quaternary%
\index{quaternary}%
{} (four-valued)
extensions of the usual Boolean function.
The type of such circuit is fsm%
\index{fsm}%
{} (for finite state machine%
\index{finite state machine}%
{}) and, by
default, it does not have a print function (since the machines
are usually much too large to be meaningful anyway to the user.
However, for the curious reader, the command print\_fsm%
\index{print\_fsm}%
{} will print out
a pretty complete version of the state machine.
Note that for efficiency reasons, the next state function also
contains delay and fan-in and fan-out information to aid in the
efficient simulation.

In general, there are two ways of creating a fsm object:
\begin{enumerate}
\item
Loading a pre-compiled version of a circuit in .exe format.
\item
Converting a FL structure into an fsm.
\end{enumerate}

\subsubsection{Loading a .exe File}

If the original circuit was described in Berkeley .sim format or
as a SILOS II gate list, there are programs distributed with the
system that can be used to compile an fsm model directly from
these formats.
The common format for such pre-compiled circuit model is a (binary)
file with a .exe%
\index{.exe file}%
{} suffix.
%In Section~\ref{CompanionTools} we discuss in more detail how
%to create such .exe file.
Loading in the .exe file and making it an fsm object simply
involves calling the load\_exe function.

For example, if there is a full\_adder.exe file in the current
working directory, the following command would create an fsm object
of the circuit.
\begin{hol}
: let ckt1 = load\_exe "full\_adder.exe";
ckt1::fsm
\end{hol}
Note that there is no theoretical limit on the number of circuit that can
be loaded into the FL system at any particular point in time.
However, since fsm models are often quite large, it is generally
advisable not to load more models than absolutely necessary.
%(In most cases, only one model will be used, but there are times
%when several models can be useful. We will return to this later
%in Section~\ref{ModelChecking}.)

\subsubsection{Creating an fsm Object Inside FL}
\label{makeSTEsection}

{\bf Warning:} This addition is fairly young and has thus not
been extensively tested. Also, it leaves quite a bit to
be desired in terms of not being very ``clean and simple''.
For a reader that is more interested in using the Voss system rather
than writing a new conversion program from some other netlist format, this
section can be skipped.

The main routine for creating an fsm object is make\_fsm%
\index{make\_fsm}%
{}.
The type of make\_fsm is (Set)\funarrow (fsm)\footnote{Currently, when
FL is invoked, the type of make\_fsm is actually (*)\funarrow (fsm), but
this is a bug that will be removed in the next release.}
Before going into how an object of type Set%
\index{Set}%
{} can be constructed, we
need to make a small digression and introduce the quaternary logic type.
For historical reasons, the name of the quaternary objects is tern%
\index{tern}%
{},
and tern is defined as the concrete type:
\begin{hol}
: lettype tern =  One |
                Zero |
                X |
                Z |
                Val string |
                And tern tern |
                Or tern tern |
                Not tern |
                Glb tern tern |
                Lub tern tern;
Lub::tern->tern->tern
Glb::tern->tern->tern
Not::tern->tern
Or::tern->tern->tern
And::tern->tern->tern
Val::string->tern
Z::tern
X::tern
Zero::tern
One::tern
\end{hol}
where One%
\index{One}%
{}, Zero%
\index{Zero}%
{}, X%
\index{X}%
{},  And%
\index{And}%
{}, Or%
\index{Or}%
{}, and Not%
\index{Not}%
{} are the obvious functions.
Glb%
\index{Glb}%
{} stands for the greatest lower bound and Lub%
\index{Lub}%
{} for the least upper bound.
Z%
\index{Z}%
{} is used to represent the top value%
\index{top value}%
{}.
Finally, Val%
\index{Val}%
{} s is used to refer to the value on node s.
Thus, as a concrete example, the next state function of a node "o" may
be described as (Not (And (Val "in1") (Val "in2"))).

There are four constructor functions for an object of type Set:
\begin{enumerate}
\item
Empty%
\index{Empty}%
{},
\item
Element%
\index{Element}%
{} (string\verb@#@((tern\verb@#@tern) list)),
\item
Union%
\index{Union}%
{} Set Set, and
\item
Sequential%
\index{Sequential}%
{} Set Set.
\end{enumerate}
The Empty is introduced to make writing functions that generate
objects of type Set easier.
Element is the constructor that actually introduces new nodes and
also give driver functions for the node.
In general, Element n gvl, will create a node named n.
This node will at least have (more about this later) the drivers
listed in the gvl list.
A driver is simply a pair of quaternary expressions:
the first object of the pair is a guard, and the second part
is the value being driven when the guard is true.
For a combinational node, the driver list is a single pair whose
guard is One and whose value component is the next state function
of the gate.
For more complex nodes, like register nodes or bus nodes, the guard-value
list is often much longer.

The Union construct is used to gather a collection of these Element
declarations so that an fsm can eventually be made.
Finally, the Sequential constructor takes two objects S1 and S2 of
type Set and merges them into a single object of type Set.
In that sense, Sequential behaves exactly like Union.
The difference is how the two deal with nodes defined in both set S1 and set S2
and for which both nodes may have at least one of their guards enabled
at the same time.
Union will find the greatest lower bound of the values being driven
at the same time whereas Sequential will assume that the driver in the
second set overrides the driver in the first.
To illustrate the difference, consider the following example:
\begin{hol}
: let a = Element ("in1", [(One, One)]);
a::Set
: let b = Element ("in1", [(One, Zero)]);
b::Set
: let ex1 = Union a b;
ex1::Set
: let ex2 = Sequential a b;
ex2::Set
: let m1 = make\_fsm ex1;
m1::fsm
: let m2 = make\_fsm ex2;
m2::fsm
: m1;
\end{hol}
Now m1 and m2 will both be fsm models with a single node called in1.
However, in m1, the next state function of in1 will be $\X$, since that
is the most we can say from the inconsistent driver commands given
in the example.
On the other hand, the next state function of the in1 node in m2 will be Zero.

For an example of using this facility, the directory HDL in the demo
distribution illustrates how one can go about defining a new description
language in order to create an fsm object.

\subsection{Queries to the Circuit Model}

There are five built-in functions that are useful in dealing with
an fsm model: nodes%
\index{nodes}%
{}, fanin%
\index{fanin}%
{}, fanout%
\index{fanout}%
{}, is\_stable%
\index{is\_stable}%
{}, and get\_node\_val%
\index{get\_node\_val}%
{}.
Nodes takes an fsm model and returns a {\em list of lists} of circuit nodes.
The reason for the double listing is that a node may have more than
one name (only from .exe file translations).
Fanin takes an fsm model and a name of a node and returns the
list of node names that the next state function depend on.
Fanout works in a similar way, but for the fanout nodes.
Is\_stable returns T (true) if the circuit is currently stable.
It is mainly used when the simulation is aborted at some
particular time with the "-m" option to STE.
Finally, get\_node\_val takes an fsm object and the name of a node
and returns the encoded version of the current value of the node.
The encoding used is: $\X = (T,T)$, $1=(T,F)$, $0=(F,T)$, and $\top=(F,F)$.
Of course, the two Boolean values are often Boolean functions over some
variables.
The main use of the get\_node\_val function is when the simulation
is aborted for some reason.
Get\_node\_val can then be used to probe the current state of the system.
For example, assuming there is a full\_adder.exe file in the current
working directory, we would get:
\begin{hol}
: let ckt = load\_exe "full\_adder.exe";
ckt::fsm
: nodes ckt;
..[["cout"],["t4"],["t3"],["t2"],["result"],["cin"],["t1"],["b"],["a"]]
: fanin ckt "cout";
["t2","t3","t4"]
: fanout ckt "t3";
["cout"]
: fanout ckt "t4";
["cout"]
: fanout ckt "a";
["t3","t2","t1"]
: get\_node\_val ckt "t2";
..(T,T)
\end{hol}

If the user also loads in the "default.fl" standard library, there is
the very useful function {\em excitation}%
\index{excitation}
that also takes an fsm model
and a node name, but that returns the next state function for binary inputs.
Note, however, that the current version of the excitation function
only works correctly for unit delay nodes.
\begin{hol}
: load "defaults.fl";
-Loading file defaults.fl
T

: excitation ckt "cout";
....
Trace started for node: cout
        Current value:X
.Time: 1
.Trace: Node cout  at time 1: t4' + t3' + t2'
Time: 2

Trace ended for node: cout
"t4' + t3' + t2'"
\end{hol}
We will return to this in Section~\ref{vossrc}.

\subsection{Symbolic Trajectory Evaluation}

There is actually only one built-in command for symbolic trajectory%
\index{symbolic trajectory evaluation}%
{}
evaluation called STE%
\index{STE}%
{}.
In general, STE determines, through symbolic trajectory evaluation, whether
an antecedent/consequent pair hold in for some circuit.
STE will return a Boolean function that gives the condition for the
verification to succeed.
For most applications the desired return value is T.

In general STE is invoked as
\begin{hol}
STE options fsm weak\_list ant\_list cons\_list trace\_list
\end{hol}
where options%
\index{STE options}%
{} is a string that can contain a combinations of the
following flags:
\begin{description}
\item[-a] Abort%
\index{abort STE}%
{} the verification at the first antecedent or consequent failure.
If the verification is aborted, STE will return a Boolean function that
gives {\em the condition for this failure to manifest itself}.
Note that this is contrary to STE's usual behavior which is to return
the Boolean function that gives the conditions for the verification to
succeed.
\item [-m n]
Abort the verification after reaching time n.
\item [-e]
Evaluate evey node in the circuit whether the node is in the
fan-in tree of some node that is checked or traced or not.
In other words, with the -e option, the simulator will compute
the value on every node. Normally, a node whose value
cannot be observed (directly or indirectly) is simply kept at X.
Of course, the STE command can run significantly slower with the
-e option, so beware!
\item [-i]
Allow antecedent failures%
\index{antecedent failures}%
{}.
In other words, compute a straight implication.
The normal behavior of the verification process is to disallow
antecedent failures.
Thus the default verification condition is both to check that every
trajectory the circuit can go thorough that is consistent with the
antecedent is also consistent with the consequent, and that there
is at least one (real) circuit trajectory that is consistent
with the antecedent.
\item [-n]
Allow over-constrained values, i.e., allow nodes to take
on the top value in the value lattice.
Normally, over-constrained values are viewed as failures.
\item[-w]
Do not print out warning messages%
\index{warning messages}%
{}.
\item[-t s]
In addition to printing out trace messages on stderr, also send
the trace events in Postscript%
\index{Postscript waveform}%
{} format to the file s.
By previewing or printing out the file the user gets a waveform diagram for
the traced signals.
\item[-T s]
Same as -t, but generate Postscript code in landscape mode.
\end{description}

The second argument to STE must be an object of the fsm type representing
a circuit that is to be simulated.

The weak\_list is a list of 4-tuples.
Each 4-tuple is of the form (g,n,f,t), where $n$ is a node name, $f$ and $t$
denote start and stop times, and $g$ is a Boolean function
denoting the domain for which this node should be weakened%
\index{weakened}%
{}.
For assignments making the guard true, the next state function of the
circuit node is set to $X$.
This is often useful when verifying a subsystem of a larger system
that has shared input signals.
By weakening%
\index{weakening}%
{} the model, unnecessary computations does not have
to be performed.
Note that weakening a model is a ``safe'' operation in that
the monotonicity of the circuit models guarantee that if we
can verify something in the weakened model, then that same property
is guaranteed to hold in the original model.

The ant\_list and cons\_list are  both lists of five-tuples.
Each five-tuple%
\index{five-tuple}%
{} is of the form $(g,n,v,s,t)$, where $g$ is a Boolean function
denoting the domain for which this assertion/check should be carried out,
$n$ is the name of a node, $v$ is the value to be asserted/checked, and
$s$ and $t$ denote the start and stop times for this assertion/check
respectively.

Finally, the last argument to STE is a list of triples.
Each triple is of the form $(n,s,t)$, where $n$ is a name of a node
to be traced%
\index{traced}%
{} and $s$ and $t$ are the start and stop times for this
trace respectively.

Of course, in practice, it would be quite tedious to have to
write all specifications in terms of lists of five-tuples.
Consequently, a small language (actually a small set of useful functions)
has been defined in the library file "verification.fl".
These functions make it much easier to write specification.
However, it should be remembered that when the verification
is actually performed, all these higher level constructs gets translated
down to the two lists of five-tuples.

For more details on how to use the STE function, we refer the reader
to Section~\ref{tutorial}.


\section{\scshape Testing Dataset}\label{sec:testing-dataset}

\subsection*{Dataset Overview}
\begin{frame}{Dataset Overview}
	\begin{table}[ht]
		\centering
		\caption{Testing dataset overview (95 banknotes in 80 images)}
		\small
		\begin{tabu} to \textwidth { X[4.2,l,m] X[l,m] X[l,m] X[l,m] X[l,m] X[l,m] X[l,m] X[l,m] }
			\textbf{Banknote value} & 5\,\euro{} & 10\,\euro{} & 20\,\euro{} & 50\,\euro{} & 100\,\euro{} & 200\,\euro{} & 500\,\euro{}	\\
			\noalign{\vskip 1mm}
			\hline
			\noalign{\vskip 1mm}
			\textbf{Nº of banknotes}			& 15		 & 12		   & 19			 & 19		   & 6			  & 9			 & 15			\\
		\end{tabu}
		\label{tab:dataset-overview}
	\end{table}

	\begin{table}[ht]
		\caption{Number of banknotes per image}
		\centering
		\small
		\begin{tabu} { X[c,m] X[c,m] X[c,m] }
			\rowfont{\bfseries\itshape} Images with 1 banknote & Images with 2 banknotes & Images with 3 banknotes \\
			\noalign{\vskip 1.5mm}
			\hline
			\noalign{\vskip 1.5mm}
			67			   & 11				  & 2	\\
		\end{tabu}
		\label{tab:number-of-banknotes-per-image}
	\end{table}
\end{frame}


\documentclass[xcolor=dvipsnames]{beamer}

\usepackage[utf8]{inputenc}
\usepackage{default}
\usepackage{beamerthemesplit}
\usepackage{tikz}
\usetikzlibrary{positioning,shapes,arrows}
\usetheme{Berkeley}
\usecolortheme[named=Black]{structure}

\title[]{Floating Base Rigid Body Dynamics Estimation}
\author[]{Francesco Nori, Jorhabib Eljaik}
\date{\today}

\begin{document}
% \maketitle

\begin{frame}
 \titlepage
\end{frame}

\begin{frame}
 \frametitle{Table of contents}
 \tableofcontents
\end{frame}

\section{Introduction}
\begin{frame}
  \frametitle{Sensor fusion on the iCub}
\begin{figure}
  \centering
	  \includegraphics[height=0.55\hsize]{images/png/FT.png}
	  \includegraphics[height=0.55\hsize]{images/png/acc.png}
	  \includegraphics[height=0.55\hsize]{images/png/gyroAcc.png}
\end{figure}
\end{frame}

\begin{frame}
  \frametitle{Sensor fusion on the iCub}
\begin{figure}
  \centering
	  \includegraphics[height=0.55\hsize]{images/pdf/rigidBody.pdf}
\end{figure}
\end{frame}

\begin{frame}
  \frametitle{Sensor fusion on the iCub}
\begin{figure}
  \centering
	  \includegraphics[height=0.55\hsize]{images/pdf/foot.pdf}
\end{figure}
\end{frame}

\begin{frame}
  \frametitle{Sensor fusion on the iCub}
 \begin{eqnarray*}
m    \dot v^B    + \omega^B \times (m       v^B) & = & f^B_1  + ... + f^B_n + mg^B \\
I^B \dot \omega^B + \omega^B \times (I^B \omega^B) & = & \mu^B_1 + ... + \mu^B_n
\end{eqnarray*}
\begin{itemize}
\item $I^B$    : inertia in the body reference frame
\item $m$      : mass of the rigid body
\item $f^B_i$  : i-th force expressed in the body reference frame
\item $\mu^B_i$ : i-th torque expressed in the body reference frame
\item $\omega^B$: angular velocity expressed in the body reference frame
\item $v^B$    : linear velocity in the body reference frame
\item $q$      : quaternion representing the rigid body orientation
\end{itemize}
\end{frame}

\begin{frame}
  \frametitle{Sensor fusion on the iCub}
 \begin{eqnarray*}
m    \textcolor{red}{\dot v^B}    + \omega^B \times (m       v^B) & = & \textcolor{red}{f^B_1  + ... + f^B_n} + mg^B \\
I^B \dot \omega^B + \omega^B \times (I^B \omega^B) & = & \textcolor{red}{\mu^B_1 + ... + \mu^B_n}
\end{eqnarray*}
\begin{itemize}
\item $I^B$    : inertia in the body reference frame
\item $m$      : mass of the rigid body
\item \textcolor{red}{$f^B_i$}  : i-th force expressed in the body reference frame
\item \textcolor{red}{$\mu^B_i$} : i-th torque expressed in the body reference frame
\item \textcolor{green}{$\omega^B$}: angular velocity expressed in the body reference frame
\item \textcolor{red}{$\dot v^B$}    : linear acceleration in the body reference frame
\item $q$      : quaternion representing the rigid body orientation
\end{itemize}
\end{frame}

\section{Bayesian Network for a Floating Base Rigid Body System}
\begin{frame}
 \frametitle{Bayesian Network for a Floating Base Rigid Body System}

 \centering
 \begin{tikzpicture}[
  node distance=1cm and 0cm,
  mynode/.style={draw,circle,text width=1cm,align=center}
  ]
  \node[mynode] (x) {$x$};
  \node[mynode,below=of x] (y) {$y$};
  \path (x) edge[-latex] (y);

  \node[right=of x, right=0.5cm of x]
  {
  $x = \left[ v^B \quad \omega^B \quad f_o \quad \mu_o \quad f_c \quad \mu_c \right]^T$
   };

   \node[right=of y, right=0.5cm of y]
   {
   $y = \left[ f_o \quad \mu_o \quad f_c \quad \mu_c \quad \dot{v}^B \right]^T$
   };
 \end{tikzpicture}

\end{frame}

\section{The Extended Kalman Filter}
\begin{frame}
  \frametitle{The Extended Kalman Filter}
  Given a nonlinear system:
  \begin{align}
   y_k &= h(x) + \rho_m \\
   x_k &= f(x_{k-1}) + \rho_p
  \end{align}

  Where $y$, the measurement vector and $x$, the state vector have gaussian uncertainties.

  After linearizing our dynamical system about an estimate of the current state ${x}_{k|k-1}$, the corresponding Extended Kalman Filter can be obtained following a \textbf{prediction} and \textbf{update} steps.
  \begin{alertblock}{Prediction}
    $\mathbf{x}_{k|k-1} = f(\mathbf{x}_{k-1|k-1})$
  \end{alertblock}

  \begin{alertblock}{\textbf{Update}}
    $\mathbf{x}_{k|k} = x_{k|k-1} + K_k(y_k - h(\mathbf{x}_{k|k-1}))$
  \end{alertblock}
\end{frame}

\begin{frame}
  \frametitle{The Extended Kalman Filter}
 Linearized measurement model: $y = Cx + e$ where:\\
 y = \begin{pmatrix}
  0& 0& \mathbf{I}& 0& 0& 0\\
  0& 0& 0& \mathbf{I}& 0& 0\\
  0& 0& 0& 0& \mathbf{I}& 0\\
  0& 0& 0& 0& 0& \mathbf{I}\\
  S(\bar{\omega}_B)& -S(\bar{V}_B)& \mathbf{I}& 0& \mathbf{I}& 0
 \end{pmatrix} x
+ \begin{pmatrix}
   0\\
   0\\
   0\\
   0\\
   S(\bar{V}^B)\bar{\omega}^B
  \end{pmatrix}
\end{frame}

\begin{frame}
  \frametitle{Extended Kalman Filter results}
  Linear Velocities smoothing
\begin{figure}
  \centering
	  \includegraphics[height=0.70\hsize]{images/png/linVel.png}
\end{figure}
\end{frame}

\begin{frame}
  \frametitle{Extended Kalman Filter results}
   Angular velocities smoothing
\begin{figure}
  \centering
	  \includegraphics[height=0.70\hsize]{images/png/angVel.png}
\end{figure}
\end{frame}

% \section{Update Step of the Kalman Filter as a Bayesian Network}
% \begin{frame}
%   \frametitle{Update Step of the Kalman Filter as a Bayesian Network}
%   \textbf{Update Step} $\leftrightarrow $ \textbf{Conditional probability of} $\mathbf{x}_{k|k-1}$ \textbf{given} $\mathbf{y}_k$ \\
%   in other words, we can also obtain $\mathbf{x}_{k|k}$ as:
%   \begin{equation}
%   \mathbf{x}_{k|k} = E[x_k \; \vert \; y_k, x_{k|k-1}]
%   \end{equation}
%   Where:
%   \begin{align}
%   \mathbf{y}_k \vert_{x_{k|k-1}} &\backsim \mathcal{N}(C\mathbf{x}, R) \\
%   \mathbf{x} &\backsim \mathcal{N}(x_{k|k-1},P_{k|k-1})
%   \end{align}
%
%   And $\mathbf{y}$ has been linearized as: $y=Cx + e$
% \end{frame}

% \section{Solving a Linear System with a Bayesian Network}
% \begin{frame}
%   \frametitle{Solving a Linear System with a Bayesian Network}
%   Given a linear system $\mathbf{Ax} = \mathbf{b}$, the computation of the solution vector $\mathbf{x^*}$ is identical to the inference of the vector of marginal means $\mu = \{\mu_1, ... , \mu_n\}$ over the graph $\mathcal{G}$ with the associated Joint Gaussian Probability Density Function
%
%  \begin{equation}
%   p(\mathbf{x}) \backsim \mathcal{N}(\mu \triangleq \mathbf{A}^{-1}\mathbf{b}, \mathbf{A}^{-1})
%  \end{equation}
%
%  The mean of this probability distribution is the target solution. The solution of the system implies inferring the marginal densities:
%
%  \begin{equation}
%   p(x_i) \backsim \mathcal{N}(\mu_i = \{\mathbf{A^{-1}}\mathbf{b}\}_i,P^{-1}_i = \{\mathbf{A}^{-1}_{ii})
%  \end{equation}
%
%  Where $\mu_i$ and $P_i$ are the marginal mean and inverse variance.
%
% %  Reference: Gaussian Belief Propagation Solver for Systems of Linear Equations. Ori Shental 1 , Paul H. Siegel and Jack K.   Wolf, Danny Bickson and Danny Dolev
% \end{frame}

\end{document}


\section{Debugging}%
\label{sec:debugging}%
\subsection{Net Weights}
\label{subsec:net_weights}
%
In an attempt to better understand the source of this unexpected behavior,
multiplicative weights (referred to as `nw' for `network weights' in
Fig.~\ref{fig:bad_convergence}) were introduced to scale the individual
contribution from each of the `learned' functions $S$, $T$, and $Q$,
explicitly:
%
\begin{align}
  S &\rightarrow \alpha_{S}\, S \\
  T &\rightarrow \alpha_{T}\, T \\
  Q &\rightarrow \alpha_{Q}\, Q.
\end{align}
%
By varying each of these weights individually allows us to selectively `tune'
how much each of these functions contribute when running inference on the
trained model.
%
Note that in the limit $\alpha_{S}, \alpha_{T}, \alpha_{Q} \rightarrow 0$, we
recover generic HMC, and as can be seen in Fig.~\ref{fig:bad_convergence},
the error in the average plaquette $\delta_{\phi_{P}} \simeq 0$, as expected.
%
As an additional sanity check, we looked at how the error in the average
plaquette behaves for different values of the weights $\alpha_{i}$ ($i = S, T,
Q$).
%
Explicitly, beginning with $\vec{\alpha} \equiv [\alpha_{S}, \alpha_{Q},
\alpha_{T}] = [0, 0, 0]$, we increase each of the weights one by one and compute
the average value of the plaquette difference.
%
For example, the blue line (Transformation $(Q)$ function) in
Fig.~\ref{fig:plaq_diff_vs_net_weights} was obtained by keeping both
$\alpha_{S}$ and $\alpha_{T}$ fixed and $0$ and varying $\alpha_{Q} \in
[0.1, 0.25, 0.5, 0.75, 1.0, 1.5, 2.0, 5.0]$, and similarly for $\alpha_{S}$ and
$\alpha_{Q}$.
%
\begin{figure}
  \centering
  \begin{subfigure}[t]{0.48\textwidth}
    \caption{$N_{LF} = 10$}
    \includegraphics[width=\textwidth]{new_figures/plaq_error/plaq_diff_vs_net_weights_lf10.pdf}
  \end{subfigure}
  % \vspace{2pt}
  % \hfill
  % \centering
  \begin{subfigure}[t]{0.48\textwidth}
    \caption{$N_{LF} = 12$}
    \includegraphics[width=\textwidth]{new_figures/plaq_error/plaq_diff_vs_net_weights_lf12.pdf}
  \end{subfigure}
  % \vspace{2pt}
  \begin{subfigure}[b]{0.48\textwidth}
    \caption{$N_{LF} = 16$}
    \includegraphics[width=\textwidth]{new_figures/plaq_error/plaq_diff_vs_net_weights_lf16.pdf}
  \end{subfigure}
  \caption{Plaquette difference $\delta_{\phi_{P}}$ for different values of the
    net weights $\vec{\alpha} \equiv [\alpha_{S}, \alpha_{T}, \alpha_{Q}]$.
    Note that $\delta_{\phi_{P}} \rightarrow 0$ as $\vec{\alpha} \rightarrow
  [0, 0, 0]$, as expected.}%
\label{fig:plaq_diff_vs_net_weights}
\end{figure}
%
These results seem to indicate that each of the individual functions contribute
separately to the error, with the scaling ($S$) and translation ($T$) functions
having the largest effect.
%  }}}
\subsection{Updates (11/11/2019)}
\begin{todolist}
  \item[\done] Ensure reproducibility across training/inference runs when
    using same input parameters.
    \begin{itemize}
      \item Essential for debugging the bias in the average plaquette.
      \item Somewhat tricky problem due to the fact that tensorflow
        has two distinct methods of specifying a seed: graph-level and
        operation-level. Additionally, when using horovod for distributed
        training across multiple ranks, we must ensure that each rank gets a
        different seed otherwise they will all be training identical copies of
        the model.
    \end{itemize}

  \item[\done] Implement reversibility checker that ensures that the L2HMC
    dynamics (i.e.\ the augmented HMC sampler) is reversible.
    \begin{itemize}
      \item Starting with $\xi = (x, v, d)$, run the dynamics in the forward
        direction to get $\xi^{\prime}$. If $\mathbf{L}_{\theta}
        \xi =  \xi^{\prime}$, and $\mathbf{F} \xi = \mathbf{F} (x, v, d) = (x,
        v, -d)$, then a complete (invertible) update step can be written as
        $\mathbf{FL}_{\theta}\xi = \xi^{\prime}$.
        %
      \item If our sampler is reversible, running the dynamics backwards on
        $\xi^{\prime}$ should return us to the original state $\xi$.
        %
        \begin{equation}
          \mathbf{FL}_{\theta}\mathbf{FL}_{\theta} \xi = \xi
        \end{equation}
    \end{itemize}

  \item[\done] Try increasing floating point precision (\texttt{tf.float32 -->
    tf.float64}) (\textbf{\textcolor{red}{Error still present.}})

  \item[\done] Try anti-symmetric Gaussian Mixture Model and see if the trained
    model is an accurate representation of the target distribution (e.g.\ by
    looking at the locations of the means).
    % \href{https://l2hmc.slack.com/archives/CK0SMC6NS/p1567623563026900}{(link
    % to post)}.

  \item[\done] At James' suggestion, we decided to look at the
    kinetic/potential energies and the Hamiltonian at the beginning and end of
    each trajectory (\textbf{\textcolor{red}{Solved! Issue was being caused by
    unexpected resampling of the momentum}}).
    % Fig~\ref{fig:potential_energy},~\ref{fig:kinetic_energy},~\ref{fig:hamiltonian}).
  \end{todolist}
\section{GMM Results}%
\label{sec:gmm_results}
\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.5\textwidth]{updates/single_chain}
  \caption{Inference run shown for a single chain using the L2HMC
  sampler trained on this gaussian mixture model.}%
  \label{fig:gmm_single_chain}
\end{figure}

\begin{figure}[htpb]
  \centering
  \begin{subfigure}[t]{0.48\textwidth}
    \caption{L2HMC samples}
    \includegraphics[width=\textwidth]{updates/means_hist_observed}
  \end{subfigure}
  % \hfill
  \begin{subfigure}[t]{0.48\textwidth}
    \caption{true target distribution}
    \includegraphics[width=\textwidth]{updates/means_hist_true}
  \end{subfigure}
  \caption{Histograms of $\langle x\rangle$ and $\langle y\rangle$ in this
  two-dimensional target space.}
\end{figure}
% }}}


\section{FEAST file format}

Extension: {\bf .feast}

\subsubsection*{Preliminaries}
FEAST files are plain ASCII files in a line-based format, using shared-vertex data representations. Empty lines are not allowed.
Comment lines can be arbitrarily placed, the special character~\# marks any such line. If the comment
character~\# occurs in a line, the rest of this line will be ignored by FEAST.\\

Each FEAST \emph{project} consists of six separate files:
\begin{enumerate}
\item header file (filename.feast)
\item static geometry file (filename.fgeo)
\item fictitious boundary file (filename.ffgeo)
\item mesh file (filename.fmesh)
\item partitioning file (filename.fpart)
\item boundary condition file (filename.fbc)
\end{enumerate}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection*{Header file}

The header file lists those files that are included in the current project.

\begin{code}{FEAST 2D -- Header}{Spezifikation_feast_2d_header}
\begin{verbatim}
FEAST              # ID-tag
2D                 # mode
3                  # version major
0                  # version minor
description        # single line description of the project
# file locations
filename.fgeo      # relative path to static geometry file
filename.ffgeo     # relative path to fictitious geometry
filename.fmesh     # relative path to mesh file
filename.fpart     # relative path to partitioning file
filename.fbc       # relative path to boundary condition file
\end{verbatim}
\end{code}

The keyword \texttt{NONE} instead of a path indicates that no such file is used. Note that FEAST and the DeViSoR might crash if you exclude
vital files.

Paths are relative to the location of the header file.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection*{Geometry files}

Both static and fictitious geometry files have the same format.

Each geometry file starts with the following header:

\begin{code}{FEAST 2D -- geometry}{Spezifikation_feast_2d_numbers1}
\begin{verbatim}
FEAST_GEOM         # ID-tag
2D                 # mode
3                  # version major
0                  # version minor
6  # number of boundary components
\end{verbatim}
\end{code}

Supported boundary types are:
\begin{itemize}
\item segment lists containing segments (single type or mixed) of the following types
\begin{itemize}
\item line segments defined by cartesian start coordinates and vector from start to end point
\item circle segments defined by midpoint cartesian coordinates, radius plus dummy, start and end angle in radians
(angles are measured counterclockwise starting from the 3 o'clock position)
\item NURBS segments are defined by the degree $n$, a flag to distinguish between open and closed curves, $m+1$ control
points, $m+1$ weights and a node vector of length $m+1$.
\end{itemize}
For each segment, the parameter interval is stored additionally, including the starting point, excluding the endpoint.
\item analytic (via reference to some object file which returns cartesian coordinates for each parameter value and maximum parameter value)
\end{itemize}

All boundary types are editable in the \devisor, for analytic boundaries, this
means editing and recompiling some Fortran or C or whatever code. These
functions have to provide three calls: \texttt{PARXC(t)}, \texttt{PARYC(t)},
\texttt{TMAXC} returning $x$ and $y$ coordinates for a given parameter value
and the length of the parameter interval (implicitly starting at parameter
value $0$).

Note that closed circles and closed NURBS curves must be the only boundary
type in each segment list!

\begin{code}{FEAST 2D -- Boundary components}{Spezifikation_feast_2d_rand}
\begin{verbatim}
4         # number of segments on first boundary
0         # type of first segment: line
-1.0 1.0  # cartesian coordinates of start point
0.0 -2.0  # vector from start to end point
0.0 0.25  # parameter interval
0         # type of second segment: line
-1.0 -1.0 # cartesian coordinates of start point
2.0 0.0   # vector from start to end point
0.25 0.5  # parameter interval
0         # type of third segment: line
1.0 -1.0  # cartesian coordinates of start point
0.0 2.0   # vector from start to end point
0.5 0.75  # parameter interval
0         # type of 4th segment: line
1.0 1.0   # cartesian coordinates of start point
-2.0 0.0  # vector from start to end point
0.75 1.0  # parameter interval

1         # number of segments on second boundary
1         # type of first (only) segment: circle
1.0 1.0   # cartesian coordinates of center
1.0 0.0   # radius and some dummy variable
0.0 6.28... # start and end angles
0.0 1.0   # parameter interval

1         # number of segments on third boundary
2         # type of third boundary: open nurbs curve
3         # degree n
6         # number of control points m+1
0.0 1.0 0.25 # X,Y,weight of first control point
...
1.0 1.0 0.25 # X,Y,weight of last control point
0.0       # node vector entry 0 to n
0.1       # node vector entry n+1
...
0.9       # node vector entry m
1.0       # node vector entry m+1 to n+m+1
0.0 1.0   # parameter interval

1         # number of segments on fourth boundary
3         # type of third boundary: closed nurbs curve
3         # degree n
6         # number of control points m+1
0.0 1.0 0.25 # X,Y,weight of first control point
...
1.0 1.0 0.25 # X,Y,weight of last control point
0.0       # node vector entry 0
...
0.1       # node vector entry m+1
0.0 1.0   # parameter interval

1           # number of segments on this boundary
4           # type: analytic
source file # path to source file
\end{verbatim}
\end{code}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%5

\subsection*{Mesh file}

Each mesh file starts with the following header:

\begin{code}{FEAST 2D -- mesh}{Spezifikation_feast_2d_numbers2}
\begin{verbatim}
FEAST_MESH         # ID-tag
2D                 # mode
3                  # version major
0                  # version minor
0                  # type of mesh (0=quad,1=tri,2=hybrid)
25                 # number of macro nodes
16                 # number of macro elements
40                 # number of macro edges
\end{verbatim}
\end{code}

\paragraph{Nodes} FEAST2D supports three kind of nodes: inner nodes (cartesian nodes),
parameterized nodes and fictious boundary nodes. Parameterisation is equal to FEAT2D, fictitious
boundary nodes are used in moving boundary scenarios.

\begin{code}{FEAST 2D -- Nodes}{Spezifikation_feast_2d_nodes}
\begin{verbatim}
# Nodes
0.0  0.0 0  # X,Y,0 for inner node
0.0 0.0 -5  # X,Y,nodal property for inner nodes carrying an
            # additional nodal property
0.25 0.0 1  # parameter value 0.25, dummy, boundary number 1
# ...
\end{verbatim}
\end{code}
As the boundary list is indexed from 1 upwards, inner nodes can be distinguished from boundary
nodes unambiguously by testing the third value of each line against zero.
\paragraph{Edges}

Edges are defined by giving the numbers of start and end nodes.

\begin{code}{FEAST 2D -- Edges}{Spezifikation_feast_2d_edges}
\begin{verbatim}
# Edges
1 2  # index of start and end node
# ...
\end{verbatim}
\end{code}

\paragraph{Elements}
Elements are defined using tons of information: First up the numbers of the nodes that make up the macro,
listed counterclockwisely for both quads and triangles. Next the numbers of the edges, from first node to
second node, from second to third and so on. The next couple of lines contain neighbourhood information:
First up the numbers of those elements sharing a common edge, then the numbers of those elements sharing a
common node but not an edge. Number 0 is used to mark that there is no neighbour. There can be at most one
edge neighbour per edge, but an arbitrary number of node neighbours. The following trick is used:
instead of printing out the number of the neighbour element, the count of neighbours is printed out as
a negative integer. For all such negative tags an additional line is inserted directly after the node
neighbour line containing the corresponding element neighbours. The third part of the macro definition
lists anisotropic refinement data. This is coded into five numerical values:
\begin{enumerate}
\item Initial refinement level both in $x$ and in $y$ direction
\item Refinement control is coded into four bits. The LSB controls refinement in $x$ direction, the LSB+1
controls direction (left or right). The MSB and MSB-1 contain this information for the $y$ direction.
The integer representing this information is stored.
\item The last three double values give the refinement factors the underlying algorithm uses.
\end{enumerate}
\begin{code}{FEAST 2D -- Elements}{Spezifikation_feast_2d_elements}
\begin{verbatim}
# Macro number 1
0        # type (0=quad, 1=tri)
1 2 7 6  # indices of nodes
1 2 3 4  # indices of edges
0 2 5 0  # Indices of edge neighbours
0 6 0 0  # Indices of node neighbours
1 0 0.5 0.5 0.5   # refinement level, refinement mode
                  # three factors
# cell number 2
1        # type (0=quad, 1=tri)
1 2 7    # indices of nodes
1 2 3    # indices of edges
0 2 5    # Indices of edge neighbours
0 6 0    # Indices of node neighbours
1 2      # refinement level and subdivision mode
# ...
\end{verbatim}
\end{code}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%5

\subsection*{Partition file}
For each element, the partition file contains one single line containing the
indices of the matrix and parallel blocks for each element. Element numbering
is based on the \texttt{fmesh} file.
\begin{code}{FEAST 2D -- partition}{Spezifikation_feast_2d_numbers3}
\begin{verbatim}
FEAST_PART         # ID-tag
2D                 # mode
3                  # version major
0                  # version minor
47                 # number of elements
4                  # number of parallel blocks
1 4                # parallel and matrix block for element 1
...
\end{verbatim}
\end{code}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%5

\subsection*{Boundary condition file}

This file defines the boundary conditions. The user can extend the default boundary conditions
dirichlet and neumann with self defined condition tags (user defined boundary status).
Also he can add additional information to each boundary specification (user defined boundary information).
Several boundary condition building blocks can be defined. Each block has as default zero dirichlet condition.
Each line in such a block defines a certain condition on a given interval or point. The interval can be
defined via parameter value (\verb+PDEFINT+ with \verb+PAR1 PAR2+) or via node
indices (\verb+NDEFINT+ with \verb+NODE1 NODE2+) (note that parameter
intervals are only unique for a single boundary, thus, boundary references are
given if parameters are used),
a point can also be defined via parameter value (\verb+PDEFNODE+ with \verb+PAR1+) or via node index (\verb+NDEFNODE+ with \verb+NODE1+).
The boundary value can be a float constant or a tag, telling the library to call a user defined function.

\begin{code}{FEAST 2D -- boundary conditions}{Spezifikation_feast_2d_bc}
\begin{verbatim}
# FEAST2D boundary condition file
#
FEAST_BC           # ID-tag
2D                 # mode
3                  # version major
0                  # version minor
#
2 # number of user defined boundary status (UDBS)
SUPERSONICIN
SUPERSONICOUT
#
2     # number of user defined boundary information
# name INT|FLOAT
USERVALUE1 INT
USERVALUE2 FLOAT
#
3     # number of bcbb (boundary condition building blocks)
#
# bcbb 1
U1    # name (string constant)
3     # number of bcbbd (bcbb definitions)
PDEFINT DIR 0.0 0.0 1.0 1 2.0
# bcbbd :  PDEFINT|PDEFNODE|NDEFINT|NDEFNODE
#          DIR|NEU|UDBS1|..|UDBSn
#          BVALUE|FUNC
#          BDIX PAR1 [PAR2] | NODE1 [NODE2]
#          USERVALUE1|FUNC..USERVALUEn|FUNC
#
#    if FUNC is given, for parameter evaluation a user
#    given routine
#    pboundaryvalue(bs,bcbb,bcbbd,par1,par2,par,valueindex)
#    is called
#
PDEFNODE NEU FUNC 2.0 1 2.0
NDEFINT SUPERSONICIN 0.0 1 2 1 2.0
#
# bcbb 2
U2
1
PDEFINT DIR 0.0 0.0 1.0
#
# bcbb 3
P
2
NDEFINT NEU 0.0 2 4
NDEFNODE DIR 10.0 3
\end{verbatim}
\end{code}

%#######################################################################################

\section{Data file}

Extension: {\bf .dat}

At the moment the entries in this file must have the same sequence and
arrangement. The entries are the following

\verb+PROJECTID:+ deprecated

\verb+PROJECTDIR:+ This defines the complete absolute path without \verb+~+
 to the feast subfolder

\verb+LOGDIR:+ This defines the complete absolute path without \verb+~+ to the folder, where
the log files should be saved. This could be a tmp file area.

\verb+MSG_LEVEL:+     level of verbosity  ( 0 = none, 9 = all messages )

\verb+GRIDFILE:+ This is a path relatively to PROJECTDIR to the grid file describing
the domain

\verb+LOADBALANCE:+ deprecated, should be 0

\verb+LOADBALFILE:+ deprecated

\verb+AUTOPARTITION:+  YES/NO This switch defines, if the auto partition is used.
If it is activated, then the number of started processes is used to get the number
of partitions, otherwise the information in the FEAST file is used.

\verb+WEIGHTEDPART:+  YES/NO This switch defines if in case of auto partititon
load balancing is used.

\verb+CONSTMALMUL:+  YES/NO This switch determines if the faster constant matrix
multiplication is used, if possible.

\verb+FASTMATASS:+ deprecated

\verb+CALCSMOOTHNORM:+  YES/NO This switch defines if after a smoothing operation
in the multigrid driver the norm of the defect is calculated. This is not
necessary for the algorithm, only for debugging purposes. For production runs
you should set this to NO.

\verb+LONGFORM:+ This defines if the output of the master program is in long or
short format.

The next area describes the discretisation of the problem. A discretisation
consists of a finite element and a cubature formula. For efficency reasons
you have the possibilty to define more than one bilinear forms ('matrix')
over one discretisation.

The entry NDISCR defines the number of discretisation. For each
discretisation, the entries \verb+ELE+, \verb+NBF+ and \verb+BF+ have to be defined.
The \verb+ELE+
identifier defines the type of the element used for test and ansatz functions,
and the used quadrature formulas for building the matrix, the right hand side and for
incorporating Neuann boundary conditions. Therefore, the last cubature formula maut be a
1D cubature formula.
Currently only the quadraliteral bilinear Finite Element with the id \verb+Q1+ is fully
supported. For the quadrature formulas have a look to the description of the
cubature module. The entry \verb+NBF+ determines the number of bilinear forms defined
in this discretisation. The last entry \verb+BF+ describes the bilinear form
itself. As example let us have a look to the discretisation of the
Poisson equation

$$
        -\Delta u = f
$$
with the weak formulation
$$
c_1 (a_x,b_x) + c_2 ( a_y, b_y ) = (f,b).
$$

The first integer of the \verb+BLF+ entry describes the number of terms in the bilinear form,
here two.

Every following line in the BLF entry describes one term as follows: coefficient,
ansatz function, test function. If the coefficent is set to \verb+VAR+, then the
function \verb+pcoeff+ from the \verb+userdef+ module is used to calculat the
value of the coefficient. For the ansatz and test functions $\varphi$ the following values
can be used:

\verb+FUNC+  -- $\varphi$\\
\verb+DERX+  -- $\varphi_x$\\
\verb+DERY+  -- $\varphi_y$\\
\verb+DERXX+ -- $\varphi_{xx}$\\
\verb+DERXY+ -- $\varphi_{xy}$\\
\verb+DERYY+ -- $\varphi_{yy}$\\

The next parameter defines the number of terms of the right hand side, in
this case one term, the function itself.

The last parameter is an string identifier for the matrix in short and long
form.

The next section describes the assignment of the \scarc{} algorithms to the
matrices. The entry  NSCARC defines the number of \scarc{} files to be
included. The next entries consists of two parameters each line, first
parameter the relative path to the \scarc{} algorithm file (format described
later) and the identifier of the matrix, the algorithm should solve. This
assignment can be changed later in the code by API routines. See the
description of the sample program.

\verb+OUTPUTFILE:+    name of the gmv/avs file without suffix\\
\verb+OUTPUTLEVEL:+   the multigrid level, on which the solution shall be
                      written in the output file\\
\verb+LASTSOLUTION:+  deprecated\\
\verb+LASTMATRIX:+    deprecated\\
\verb+STORAGE_DES:+   number of storage descriptors, problem size dependent
\verb+STORAGE_SIZE:+  heap size\\
\verb+MAXMGLEVEL:+    maximum multigrid level\\
\verb+ANISOREFMODE:+  deprecated, should be MODE2

The following entries allows the setting of a certain SBBLAS implementation.

\verb+SBBLASMV:+  implementation of the MV algorithm\\
\verb+SBBLASPRSLOWL:+  implementation of the TriGS algorithm\\
\verb+SBBLASPRSLINE:+  implementation of the MVline algorithm\\
\verb+SBBLASPRSLINE:+  implementation of the Tri algorithm\\
\verb+SBBLASOVERRIDE:+  is it is set to YES, the above defined values are used\\
\verb+SBBLASCONF:+  path to the sbblas.conf file

The further entries in this file are application dependent.

%#######################################################################################

\section{\scarc{} application file}

extension {\bf .scarc}

This file describes the structure of a \scarc{} algorithm over the
various hierachical layers.

The definition starts with the keyword SOLVER.

At the moment, two main solvers are supported, multigrid (MG) and
conjugate gradient (CG/BICG) schemes. When the latter are intendend to work as
smoothers in an outer multigrid scheme (e.g. when solving multidimensional problems)
then this can be indicated by CG\_SMOOTH and BICG\_SMOOTH, respectively. (The effect is
that the necessary structures are allocated on all multgrid levels). The direct solvers are intented for solving the coarse grid problem in the multigrid scheme.

\begin{verbatim}
SOLVER=[CG|CG_SMOOTH],[iter],[exit-crit],[Hlayer]
  PREC=ALL,0,[omega],[scarcflag],[Hlayerflag]
  [SOLVER|LSMOOTHER]

SOLVER=[BICG|BICG_SMOOTH],[iter],[exit-crit],[Hlayer]
  PREC=ALL,0,[omega],[scarcflag],[Hlayerflag]
  [SOLVER|LSMOOTHER]

SOLVER=MG,[iter],[exit-crit],[cycle],[npresmooth],[npostsmooth],[Hlayer]
  SMOOTH=ALL,0,[omega],[scarcflag],[Hlayerflag]
  [SOLVER|LSMOOTHER]
  COARSE=[SOLVER]

SOLVER=GLOBAL

SOLVER=PGLOBAL

SOLVER=MGLOBAL

LSMOOTHER =  JACOBI|TRIGS|ADITRIGS|ILU
\end{verbatim}

\begin{itemize}
\item \verb+[iter]+  : iteration count
\item \verb+[exit-crit]+ : exit criterion absolute (\verb+ABS+) or relative (\verb+REL+). \verb+ABS:1E-6+
	    e.g. indicates, that the iteration process shall end, if the absolute residual is smaller than
	    $10^{-6}$.
\item \verb+[omega]+ : damping parameter for this level
\item \verb+[Hlayer]+ : hierachical layer this scheme works on
\item \verb+[scarcflag]+ : If this parameter is 0, the next scheme is a simple local
              smoother LSMOOTHER, otherwise a further \scarc{} solver.
\item \verb+[Hlayerflag]+ : if this parameter is 0, the next scheme works on a different
               hierachical layer, otherwise on the same.
\item \verb+[cycle]+ : multigrid cycle type V,W or F
\item \verb+[npresmooth],[npostsmooth]+ : number of pre- and postsmoothing steps
\end{itemize}

Lets have a look to the following example:

\begin{tabbing}
\verb+SOLVER=CG,32,REL:1.0E-6,HL_SD+ \phantom{xxxxxxx} \=   The global scheme is a CG scheme which stops after \\
				      \> 32 iterations or if a relative accuracy of $10^{-6}$ is reached. \\
\\
\verb+  PREC=ALL,1,1.0,HL_SD,1,1+   \>   The preconditioning is done with damping factor 1.0.  \\
                                    \>   The precondiotioner is of \scarc{} type and acts on \\
				    \>   the same hierachical level.  \\
\\
\verb+SOLVER=MG,1,REL:1.0E-6,V,1,1,HL_SD+  \>  As preconditioner acts a global multigrid scheme  \\
\verb+SMOOTHER=ALL,0,0.8,HL_SD,1,0+  \>   which performs one global step. The exit criterion  \\
                                     \>    has in this case no meaning. The global multigrid  \\
				     \>   performs 1 pre- and 1 postsmoothing step. The  \\
				     \>   preconditioner is of \scarc{} type and works not on \\
				     \>   the same hierachical level.  \\
\\
\verb+  SOLVER=MG,1,REL:1.0E-6,F,4,4,HL_PB+   \> As smoother works a local multigrid scheme,   \\
\verb+    SMOOTHER=ALL,0,1.0,HL_PB,0,0+   \>   which works seperatly on the parallel subdomains  \\
                                           \> It performs one step and 4 pre- and 4 postsmoothing \\
					\>  steps. The smoother for this scheme is a local smoother. \\
					\> In this case the last parameter has no meaning.  \\
\\
\verb+      LSMOOTHER=TRIGS+      \>            Local smoother triGaussSeidel  \\
\\
\verb+    COARSE=CG,512,REL:1.0E-6,HL_PB+  \>   The coarse grid solver for the local multigrid scheme \\
\verb+      PREC=ALL,1,1.0,HL_PB,0,0+   \>     It performs up to 512 steps till an accuracy of relatively  \\
\verb+        LSMOOTHER=JACOBI+      \>        $10^{-6}$ is reached. It is preconditioned with the Jacobi method.\\
\\
\verb+  COARSE=CG,512,REL:1.0E-6,HL_SD+    \>        The coarse grid solver for the global multigrid scheme.\\
\verb+    PREC=ALL,1,1.0,HL_SD,0,0+     \>       It has the same parameters as the local scheme.\\
\verb+      LSMOOTHER=JACOBI+
\end{tabbing}