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]
                            [--compression]

`-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.

`--compression`
:    Use lossless compression of state space to reduce memory consumption of
     verification. The default compression method is tree compression.
     See [state space compression](#state-space-compression)
     on details of compression.

`--shared`
:    This option switches between two graph traversal algorithms.
     Use this switch to turn on Shared algorithm instead of Partitioned
     algorithm. Default option is to use Partitioned algorithm.
     See [graph traversal algorithms](#divine-graph-traversal-algorithms)
     on details.

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[=<report format>] | -r]
                   [--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 and reporting.

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

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[=<report format>] | -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[=<report format>] | -r`
:    At the end of a verification run, produce a comprehensive,
     machine-readable report.

     There are several formats of reports supported by DIVINE.
     Also it is possible to specify `--report` option repeatedly
     to get multiple reports (for example to file and on console).

     The value of `<report format>` can be one of:

     `text`
     :    Report good for both machine and human readability, produced
          on standard output.

     `text:file`
     :    Same as `text` but output is saved to given file (which is overwritten
          if already present).

     `plain`
     :    Similar to `text` but optimized for machine readability, without
          empty lines.

     `plain:file`
     :    `plain` into file.

     `sql:table:ODBC connection string`
     :    Report is saved into given table of database, ODBC with given
          connection string is used to connect to database. This feature
          requires DIVINE compiled with ODBC support.

          The report is saves as follows: for every line of report (in text
          format) the table column name is derived from value name (which
          is converted to lowercase and all non alphanumeric characters are
          converted to underscode). Then table is queried for available column
          names and columns which are both in table and in report are saved
          (as text).

          If table is not present DIVINE will attempt to create it.
          Automatically created table will contain all collumns of report.

DIVINE Explicit State Space Generator
----------------------------------
    divine gen-explicit [--fair] [--reduce=<reduction>]
                        [--report[=<report format>]]
                        [engine options]
                        [--no-save-states]
                        [-o <file> | --output=<file>]

The `gen-explicit` subcommand can be used to generate the entire state-space
of a model into file which can then be processed either by DIVINE or any other
tool capable of loading
[DIVINE Explicit State Space Format](#divine-explicit-state-space-format).

The output file contains both forward and backward edges of the state space and
may contain the memory associated with each node of the state space. Please
note that the size of the output file approximately corresponds to the amount
of memory required for verification (it is smaller if state memory is omitted,
though).

The `gen-explicit` command can run in parallel and can use MPI, but it is not
yet available in conjunction with the `--shared` option.  If `gen-explicit` is
used with MPI, it expects that the output file is located on a shared
filesystem (for example NFS).

State Space Compression
-----------------------

DIVINE supports lossless state space compression based on tree compression.
This compression mechanism is particularly efficient on large models with
relatively large state vectors (individual states). Therefore LLVM and timed
automata verification benefits the most from state space compression -- the
compression can often reduce large state spaces (several gigabytes and more) to
less than one tenth of their original size. Also, for these modelling
formalisms, the time overhead from compression is usually negligible.

The compression is supported by all verification algorithms and can be enabled
by supplying the `--compression` switch (alternatively,
`--compression=tree`). The following DIVINE commands allow compression option:
`metrics`, `verify`, `gen-explicit`, `draw`.

There are no limitations on other options implied by use of compression, it is
supported with parallel verification (including MPI); however, to achieve best
compression ratio it is recommended to use shared-memory verification
(`--shared`), if possible.

DIVINE Graph Traversal Algorithms
---------------------------------

DIVINE implements two different graph traversal algorithms. Both of them are
designed to run in parallel environment and they implements pseudo BFS.
However, each of them has different pros and cons and is suitable for different
situations.

### Partitioned

The main idea of this algorithm is that a graph is partitioned into
parts where each part is assigned to exactly one working thread
(and vice versa, every thread has exactly one part of a graph).
DIVINE generates a graph "on the fly" so it is not possible to anyhow
analyse the particular graph in advance, in order to optimize the partitioning.
That is the reason why the partitioning is done via hashing nodes of a graph,
which may cause imbalanced and heavy communication workload.

Every working thread has an independent store (simple hash table) for
already visited nodes of the graph and a queue of nodes to-be-processed.
Due to the independence of partitioning no synchronizations are required
for standard operations. This is not the case with Shared algorithm
(see below), therefore the performance of single threaded run of DIVINE
is better if Partitioned algorithm is used. However, the independence implies
worse efficiency of the tree compression, in other respects this algorithm can
run in distributed environment without any penalty (except network cost).

### Shared

When using Shared algorithm, no partitioning is done. Two main data
structures -- the store and queue -- are shared among all working threads.
A working thread pushes already processed nodes of a graph into the store,
and takes to-be-processed nodes from the queue. Shared algorithm is
significantly better than the previous one when is DIVINE is supposed to be run
on a multi-core machine with high amount of memory.

The store is a hash table that allows for parallel access. This data structure
is limited to only three operations -- insert, find, and grow. Our
implementation in DIVINE does not use explicit locks, although it contains
a few global implicit locks (or better atomic flags) to ensure correctness.

The grow operation can also be done in parallel with a support of independent
participating working threads (besides the thread that called grow). Anyway,
more participating workers may improve the time needed for rehashing the old
table into the new one.

The usage of the tree compression together with Shared algorithm significantly
decreases amount of memory needed by DIVINE. However, Shared algorithm
is not the best choice for single threaded run due to a small performance
penalty caused by synchronizations inside the hash table.

As of time of this writing Shared algorithm cannot run in a distributed memory.

Compiling
---------

The command `divine compile` can be used to compile either CESMI module or DVE
model into native code or C/C++ code into LLVM bitcode. See
[model checking C and C++ code](#model-checking-c-and-c-code-via-llvm-bitcode)
for more details. The mode of compilation is recognized by an extension of name
of input file in some cases -- .dve for DVE models, .m for MURPHI models.
The default mode of compilation is to compile C/C++ program via clang into LLVM
bitcode. The selection of compilation CESMI module may be done by specifying
`-c` or `--cesmi` option.

    divine compile [-j N|--jobs=N]
                   [-l|--llvm]
                   [-c|--cesmi]
                   [--keep-build-directory]
                   [--cflags=<flags>|-f <flags>]
                   [--libraries-only]
                   [--precompiled=<path>]
                   [-o <name>|--output-file=<name>]
                   [--cmd-clang=<value>]
                   [--dont-link]
                   [--no-modeline]
                   [-D <definition> | --definition=<definition>]
                   [--snapshot=<path>]
                   [--stdin=<path>]
                   <file input>

`-j N | --jobs=N`
:    Enable parallel build. If not specified, `N` is assumed to be 1.

`-l | --llvm`
:    Set compilation mode explicitly to build an LLVM bitcode. This option
     is suppressed when extension of the input file is `.dve` or `.m`.
     Without this option a warning is emitted if compilation mode defaulted.

`-c | --cesmi`
:    Set compilation mode to build a CESMI module.

`--keep-build-directory`
:    This option prevents from deletion of a temporary build directory.

`-f <flags> | --cflags=<flags>`
:    This option is used to pass additional arguments to a compiler.

`--libraries-only`
:    By specifying this option DIVINE compiles only libraries such as
     libc++, PDCLib, and virtual file system. The compiled libraries
     may be later used repeatedly. This option is recognized only when
     LLVM bitcode is compiled. This option does not use any other file
     input.

`--precompiled=<path>`
:    Path to a directory where pre-compiled libraries are placed. The libraries
     are to be linked with the verified program. This option is recognized
     only when LLVM bitcode is compiled.

`-o <name> | --output-file=<name>`
:    Specify a name of a product of the compilation.

`--cmd-clang=<value>`
:    Set how to run clang. Useful when default path is not correct.

`--dont-link`
:    Compile the source files, but do not link. This option is recognized
     only when LLVM bitcode is compiled.

`--no-modeline`
:    Disable DIVINE modeline parsing. Modelines are used in examples
     of C/C++ programs to automatically set `--cflags`.

`-D <definition> | --definition=<definition>`
:    Add definition for generator, can be specified multiple times. This
     option is recognized only when DVE model is compiled.

`--snapshot=<path>`
:    DIVINE takes a snapshot of the specified directory which becomes a root
     of the virtual file system. This option is recognized only when LLVM
     bitcode is compiled.

`--stdin=<path>`
:    DIVINE uses the specified file to be the standard input for the verified
     program (file descriptor 0, therefore `stdin` and `std::cin`). This option
     is recognized only when LLVM bitcode is compiled.
