Using the DIVINE commandline interface
======================================

The main interface to DIVINE is the command-line tool simply called
`divine`. Additionally, some of the functionality is also available via
`divine.ide` which is documented separately. DIVINE supports a number of input
languages and not all features are available with all input languages. These
limitations are documented here. Additionally, since DIVINE has many build
dependencies and needs substantial amount of RAM and disk space to compile,
many features can be disabled at compile time to reduce some of these
requirements. The binary will normally give you an explanation if you request
an operation that has been disabled at compile time. To get a list of options
your `divine` binary has been compiled with, simply issue

    $ divine --version
    DIVINE version 3.0
    Version: 3.0
    Build-Date: 2013-10-17, 13:17 UTC
    Pointer-Width: 64
    Debug: enabled
    Compile-Flags: POSIX DVE HASH_COMPACTION COIN LLVM
    MPI-Version: n/a
    Architecture: Intel(R) Core(TM) i7-3520M CPU @ 2.90GHz

Synopsis
--------

    divine info <model file>
    divine combine [-f <formula file>] <model file>
    divine compile [--cesmi|--llvm] <model file>
    divine draw [...] <model file>
    divine metrics [...] <model file>
    divine verify [...] <model file>
    divine simulate [...] <model file>

Printing Model Metadata
-----------------------

    divine info {model}

To obtain basic data about a model, use `divine info`. The key part of the
information provided is the list of properties available in the model, and the
name of a property that needs to be passed to the `--property` option of `draw`,
`metrics` or `verify` subcommands:

    $ divine info examples/dve/peterson-liveness.dve
    Available properties:
     * deadlock: deadlock freedom
     * assert: assertion safety
     * LTL: Büchi neverclaim property

In this case, the model has three properties, `deadlock`, `assert` and `LTL`
(the last being a neverclaim property generated from an LTL formula, see
the section on `divine combine` below).

Using LTL Properties
--------------------

    divine combine [-f formula.ltl] [-p N] [-o] [-q] model.dve
    divine combine [-f ...] [...] model.mdve [P1=VAL] [P2=VAL] ...

Some of the input languages have intrinsic support for specifying LTL
properties. In these cases, all suitable LTL properties are automatically made
available for model checking via the `--property` switch to `divine verify`
(see below). However, since the DVE language currently lacks support for
specifying LTL directly, the formulas need to be provided in a separate file
with an `.ltl` suffix. The `combine` subcommand can be used to translate the
LTL formula into an Büchi automaton which is then included in the DVE file. One
DVE file is generated for each LTL formula found in the `.ltl` file. The `.ltl`
file would look, for example, like this:

    #define a_0 (active == 0)
    #define a_1 (active == 1)

    #define w_0 (waiting[0] == 1)
    #define w_1 (waiting[1] == 1)

    #define c_0 (P_0.CS)
    #define c_1 (P_1.CS)

    #property G(F(c_0)) && G(F(c_1))
    #property ((GF(a_0 && w_0)) -> GF(c_0)) && ((GF(a_1 && w_1)) -> GF(c_1))

Each `#define` gives a symbolic name for an atomic proposition, and each
`#property` specifies a single LTL formula. Without the `-p` (`--property`) and
`-o` (`--stdout`) options, the output of `divine combine` looks like this:

    $ divine combine peterson.dve -f peterson.ltl
    peterson.prop1.dve: G(p0cs->F(!p0cs))
    peterson.prop2.dve: G((!p0cs)->Fp0cs)
    peterson.prop3.dve: GFsomeoneincs

    $ divine verify peterson.prop1.dve
    ...

To pick a specific formula, use `-p` N (with N being the sequence number of a
`#property` in the `.ltl` file, in this case 1 or 2). When `-p` is in effect,
`-o` can be used to direct the generated DVE file to standard output.

Syntax of LTL formulas as accepted by DIVINE is as follows:

    F :== un_op F | F bin_op F | (F) | term
    un_op :== '!' (logical negation)
        :== 'X' | 'O' (next)
        :== 'F' | '<>' (future)
        :== 'G' | '[]' (globally)
    bin_op :== '&&' | '*' (and)
        :== '||' | '+' (or)
        :== '->' (implication)
        :== '<->' (equivalence)
        :== '^' (xor)
        :== 'U' (until)
        :== 'V' | 'R' (release)
        :== 'W' (weak until)
    term :== 'true' | 'false'
        :== {_a-z}[_0-9a-z]*  (name of an atomic proposition)

Configuring the Parallel Model Checking Engine
----------------------------------------------

Many of the algorithms DIVINE can use are parallel and optionally
distributed. Both `metrics` and in common cases the `verify` subcommand will
use a parallel algorithm to explore the state space of the system. All the
parallel algorithms have a number of parameters in common, and we will discuss
them in this section.

    divine {metrics|verify} [--statistics [--curses]]
                            [-w N|--workers=N]
                            [--max-memory=N]
                            [--max-time=N]
                            [--disk-fifo=N]
                            [--seed=N]
                            [-i N|--initial-table=N]
                            [--hash-compaction]

`-w N | --workers=N`
:    The number of threads to use for verification. The default is 2. For optimal
     performance, each thread should get one otherwise mostly idle CPU
     core. Your mileage may vary with hyper-threading (it is best to run a few
     benchmarks on your system to find the best configuration).

`--max-memory=N`
:    Limit the amount of memory `divine` is allowed to allocate. This is mainly
     useful to limit swapping. When the verification exceeds available RAM, it
     will usually take extremely long time to finish and put prohibitive strain
     on the IO subsystem. It is recommended that you do not allow `divine` to
     swap excessively, either using this option or by other means.

`--max-time=N`
:    Put a limit of N seconds on the maximal running time.

`--disk-fifo`
:    Most of the memory used by the verifier is split between hash tables and
     queues. This option tells `divine` to use disk storage for long queues,
     since the impact of high latency is much smaller for queues than it is for
     hash tables. This allows more of RAM to be used for hash tables, improving
     overall performance for large models. Location of temporary files can be
     changed by setting TMPDIR, TEMP or TMP environment variables.

`--statistics [--curses]`
:    Print realtime statistics during verification, optionally using curses for
     neater output. Useful as entertainment, for diagnosing performance issues
     and to impress laymen.

Distributed Execution
---------------------

DIVINE can be built with support for MPI-based distributed verification. To
execute DIVINE across multiple machines, you should use `mpiexec` or `mpirun`
from your MPI distribution (consult your MPI manual for details and exact
invocation parameters you need). An usual invocation will look like this:

    $ mpiexec -H hostname1,hostname2 divine -w 4 model.dve

This command will execute DIVINE on 2 machines specified with -H, using 4
worker threads on each (for a total of 8 threads). You should make sure that
your DIVINE binary is available on $PATH for non-interactive ssh commands (try
running `ssh hostname1 divine`). Alternatively, you can specify an absolute
path to your DIVINE binary, assuming it lives in the same place across all
machines. Finally, input file(s) to DIVINE need to be available on each machine
as well, using the same path used in your invocation.

State Space Metrics, Visualisation & Exploration
------------------------------------------------

    divine metrics [--reduce=R] [--no-reduce] [--fair] [--report]
                   [--property=N] [--fair]
                   [engine options]
                   <model file>

The `metrics` sub-command runs a simple reachability on the entire state space
of a system, reporting summary statistics. This is the most efficient algorithm
in DIVINE that explores the state space, both in terms of memory and CPU,
although only by a slight margin. See [next section](#model-checking) on
details of the model-related switches.

    divine draw [--distance=N] [--trace=N,N,N...]
                [-l|--labels|--trace-labels]
                [--bfs-layout]
                [--reduce=R] [--no-reduce] [-f|--fair]
                [--render=<cmd>|-r <cmd>]

To visualise (a part of) the state space, you can use `divine draw`, which
creates a graphviz-compatible representation. By default, it will run "`dot
-Tx11`" to display the resulting graph. You can override the drawing command to
run by using the `-r`/`--render` switch. The command will get the dot-formatted
graph description on its standard input.

Additionally to displaying the graph itself, `draw` can be instructed to
visualise a (presumably counter-example) trace in the graph. Use the `--trace`
switch to supply a trace, in the same format as the `verify` command uses for
counter-examples in the report, using its `--report` option (you can cut&paste
the `CE-Init` line from the report, to which you can optionally append the
`CE-Cycle` list, separated by a comma, to obtain the full lasso-shape
counterexample when working with LTL/neverclaim properties).

    divine simulate [--distance=N] [--trace=N,N,N...]
                    [--reduce=R] [--no-reduce] [-f|--fair]

The `simulate` sub-command is used to interactively explore a state space in a
terminal. Use `?` in the interactive prompt to obtain help on available
commands. You can also use `simulate` non-interactively, supplying a succession
of numbers (using the `--trace` switch analogous to that of `draw`, see above).

Model Checking
--------------

    divine verify [--reachability|--owcty|--map|--nested-dfs]
                  [--property=<name> | -p <name>]
                  [--fair]
                  [--reduce=<reduction>]
                  [--report | -r]
                  [--no-counterexample | -n]
                  [--display-counterexample | -d]
                  [engine options]
                  <model file>

This command is the main workhorse of model checking. It automatically selects
an appropriate algorithm for model checking based on the property type, and an
appropriate model loader / state space generation backend according to the
input file.

    $ divine verify examples/dve/peterson-liveness.dve --property=deadlock --no-reduce
      searching... 	736677 states, 2848427 edges
     =====================================
               The property HOLDS
     =====================================

### Options

`--reachability, --owcty, --map, --nested-dfs`
:    Override the algorithm to use.

`--property=name | -p name`
:    Select which property to model-check. Use `divine info` to
     obtain a list of properties available in any given model. Defaults to
     `deadlock`.

`--fair`
:    Only consider runs that are weakly fair. This option is only
     currently available for DVE models and is mainly useful when checking LTL
     properties. This avoids counterexamples which rely on one of the processes of
     the system never making any progress even though it is not blocked.
     For timed models, this option excludes Zeno runs when verifying LTL
     properties.

`--reduce=X, --no-reduce`
:    This option directs the model checker to use heuristics which
     usually make the process faster and/or use less memory. Not all reductions
     are available with all model types. The default is to enable all reductions,
     namely `tau+,taustore,heap,por`. To disable state space reductions, specify
     `--no-reduce`. In addition, `tau` is available as a weaker alternative to
     `tau+`. The `tau`, `taustore` and `heap` reductions are only available with
     the LLVM backend. The `por` reduction is available with CoIn and DVE inputs
     and may be available with some CESMI models. To specify multiple reductions,
     provide them as a comma-separated list.

`--no-counterexample | -n`
:    Disable generation of counterexamples. This is mainly
     useful for benchmarking verification speed.

`--report | -r`
:    At the end of a verification run, produce a comprehensive,
     machine-readable report.
