
This package contains a script which can be used to verify that a given
version of LB3D produces results which are binary-identical to a
known-good set. This makes it much easier to check that changes to the
code haven't altered its behaviour.

Currently, the only test supported off-the-shelf is a simulation of
oil-water-surfactant mix, with no obstacles. It should be
straightforward to add more tests; the script can also be used to
generate many runs for different numbers of CPUs, for example to test
performance.

It's based around two perl scripts: one which sets up simulations to be
run, and another which verifies the MD5 hashes of output files.
Verification of a version of LB3D is performed by restarting a
simulation from a standard checkpoint file, running it for a few hundred
timesteps, and then comparing the output with known-good output files.

The scripts require perl 5.6 ; they can be persuaded to run on 5.004 if
really required.


How to verify a version of LB3D
===============================


(1) Compile LB3D, with -DMALLEABLE_NP_CHECKPOINT .

(2) Unpack this package, and copy the LB3D binary into the code/
directory; call it, say, "lbe-test".

(3) cd into the code/ directory.

(4) Run:

./test-integrity.pl -b ./lbe-test -l mytest -n 2,1

        This sets up two simulation runs: one over 1 CPU, and the other
        over 2 CPUs. The arguments to the script are:

                -b : specify which LB3D binary to run
                -l : a label or name for the simulation runs
                -n : comma-separated list of CPU numbers

        The script will set up input files and output directories
        appropriately. If all is successful, it will print an mpirun
        command line for each simulation, eg:

       mpirun -np 2 ./lbe-test -f ./input-file-mytest-2cpu -r t000100-1504718078
       mpirun -np 1 ./lbe-test -f ./input-file-mytest-1cpu -r t000100-1504718078

(5) Run the simulations as directed.

(6) cd into the output/ directory. For each simulation directory, run
    ./checkmd5.pl <dirname>
    If it terminates silently, then no differences were found.

    If it prints out some MD5 sums and "Checksums do not match --
    exiting.", then something has changed the output from LB3D.


A quick example
===============

(after untarring the test system into /tmp/newtest/ )

% cd code
% ./test-integrity.pl -b ./lbe-picasso -l mytest -n 1
mpirun -np 1 ./lbe-picasso -f ./input-file-mytest-1cpu -r t000100-1504718078
% mpirun -np 1 ./lbe-picasso -f ./input-file-mytest-1cpu -r t000100-1504718078

[ lots of LB3D output follows ]

% cd ../output
% ls
checkmd5.pl  mytest-1cpu  test-master-checkpoint  test-master-results
% ./checkmd5.pl mytest-1cpu
%

[ therefore everything's ok. ]

