CASINO manual - Theory of Condensed Matter
CASINO manual - Theory of Condensed Matter
CASINO manual - Theory of Condensed Matter
You also want an ePaper? Increase the reach of your titles
YUMPU automatically turns print PDFs into web optimized ePapers that Google loves.
B<br />
Appendix 2: Automatic testing <strong>of</strong> <strong>CASINO</strong><br />
B.1 Overview<br />
A facility for automatically testing casino can be found in <strong>CASINO</strong>/examples/TEST. This directory<br />
contains another directory called Input, which holds a large number <strong>of</strong> examples designed to test most<br />
aspects <strong>of</strong> casino, and a script called autotest, which will run casino for each <strong>of</strong> those examples<br />
in turn. This facility is intended to help developers ensure that they do not inadvertently break the<br />
code when adding new features.<br />
B.2 Running the set <strong>of</strong> examples<br />
The first time that autotest is run, a stable, trusted version <strong>of</strong> casino should be used to create a<br />
library <strong>of</strong> standard output files, with which subsequent results can be compared. Type ./autotest<br />
--library to achieve this. (Note that the casino binary compiled with debugging flags will be used<br />
by default.)<br />
Subsequently, just type ./autotest to run the examples and compare the output with that in the library.<br />
The script will warn you if casino fails or halts unexpectedly, or if the output differs from that in<br />
the library (don’t worry if it scrolls <strong>of</strong>f the screen too fast; all output is saved in the autotest.log<br />
file). Note that rounding errors <strong>of</strong>ten affect the last couple <strong>of</strong> digits in the results <strong>of</strong> optimization<br />
calculations. Moreover, there are <strong>of</strong>ten trivial differences between the results produced with different<br />
compilers, so, when testing the code, it is best to use the same compiler as was used to generate the<br />
library.<br />
The autotest script uses runqmc to run casino, and one may pass options to runqmc directly using<br />
the syntax ‘-- 〈extra-runqmc-options〉 (i.e., use a double hyphen to separate autotest options<br />
from the ones to be passed to runqmc, as in ‘runqmc --nproc=100’. This allows, for example, running<br />
Shm and OpenMP autotests, controlling the number <strong>of</strong> cores used on <strong>of</strong> parallel autotests, running the<br />
debug, opt, or dev versions <strong>of</strong> the code, and so on.<br />
To skip a particular example use, e.g., ‘--not carbon atom’. To run the test for a particular example<br />
only, use e.g. ‘--only neon atom’. Use --missing to only run tests which have not been run already,<br />
or were interrupted; use --error to only run tests which have not been run already, or were interrupted,<br />
or resulted in an error; use --mismatch to only run tests which have not been run already,<br />
or were interrupted, or did not match the library output. If you want to get rid <strong>of</strong> all the results<br />
(including the library results), either remove the Library and Output directories by hand, or type<br />
./autotest --clean. Type ./autotest --help to get a full list <strong>of</strong> options.<br />
The facility is good at picking up minor bugs when used in conjunction with the NAG compiler with<br />
debugging flags. The facility should be run after any substantial modification <strong>of</strong> casino.<br />
B.3 Adding a new example<br />
If a new feature is added to casino then an appropriate example should be added to the automatic<br />
testing facility. Create a new directory in Input with name describing the system, and create one<br />
or more subdirectories in it with names indicative <strong>of</strong> the run type; see other examples for guidance.<br />
Let’s refer to these directories as system and system/run, respectively. Place common files (e.g.,<br />
xwfn.data files, pseudopotentials, etc) under system, and files which change from run to run (e.g.,<br />
input) in the individual system/run subdirectories.<br />
Note that the examples should run very quickly; it doesn’t matter whether good results will be<br />
produced. The great majority <strong>of</strong> bugs will show up when the results <strong>of</strong> the modified version <strong>of</strong><br />
casino are compared with the ‘standard’ version.<br />
B.4 Using git-bisect with autotest<br />
Bisecting is a very simple, yet powerful, feature <strong>of</strong> git which aids locating the commit at which a<br />
regression was introduced, and thus (hopefully) determine how to fix it.<br />
Suppose you have a clean working directory (no modifications over the last commit), and when you<br />
run the autotest you find a crash, an output mismatch, a large increase in CPU time or any other<br />
217