2. Installation and tests¶
2.1. Mandatory packages¶
ROOT/CERN package (requires \(\geq 6.00\))
The easiest way, if available, is to install directly all relevant ROOT packages (using apt-get, dnf, or brew, etc.); do not forget the development (
-devel) packages and specific ROOT libraries (
Minuit2). Alternatively, you may want to compile locally ROOT. To do so, download a version and follows the configuration/compilation instructions to build ROOT. In addition, in the latter case:
Please define (e.g., in your *~/.bashrc*) the ROOT environment variables
export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$ROOTSYS/lib[Mac OS only]
For Mac OSX, we recommend to install ROOT via homebrew. To define the environment variable
ROOTSYS, you need to source, e.g., in your configuration file
thisroot.csh. To know where it is, type, e.g. for ROOT 6,
brew info root6.
2.2. USINE download/install¶
Clone from git repository:
> git clone https://gitlab.com/dmaurin/USINE.git
or see the GitLab repository for alternative download forms. Once USINE is cloned, you can always choose a specific version (e.g.
git checkout tags/V3.4), but we recommend that you always use the latest (which is the one cloned).
> cd USINE
> mkdir build; cd build; cmake ../(to have build files in separate directory)
> make -jN[using N=2, 3,… cores]
Define the USINE environment variables (e.g., in your ~/.bashrc):
export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$USINE/lib# [Mac OS only]
Do not forget to
`> source ~/.bashrc` to ensure that the environment variables are set in your current xterm (
`$echo $USINE` should point to the directory where you installed USINE).
This version was successfully installed and tested on:
- Ubuntu 17.10 (gcc 7.2.0)
- MacOS X High Sierra 10.13.4 (clang-900.0.39.2)
- Fedora 25 (gcc 6.4.1)
2.3. Tests in USINE¶
Testing is one of the most important step of code development, to ensure that
- the production version (i.e. user compiled version) behaves as expected,
- modifications of the code by developers do not break any functionality.
Is my installation successful?
To ensure that USINE is ready to use, type
> cd $USINE
> ./bin/usine -tUSINE
If all tests pass, then you are good to go (jump to Tutorial: ./bin/usine)! If not, check that some tests are indeed performed (i.e. there is some chatter when you run the test), and then: (i) if no chatter, it probably has to do with your installation (missing environment variable, missing ROOT package…); (ii) if you are told that some checks failed, it may be related to your machine architecture/compiler, so contact the USINE developers (send your .fail test files) who will evaluate the severity of the problem.
On Mac OS systems, we observe that the last digit differs from the one in the reference file ((in many test files). This is likely due to the different architecture of systems but you can still consider that the tests passed!
What tests are performed?
The realm of testing is large. The tests implemented in USINE are a mixture of unit tests and integration tests. We also performed static and dynamic code analysis.
|Unit tests from |
|Unit tests are narrow in scope and allow to check that pieces of code are doing what they are intended to. To build unit tests, each USINE class and namespace (see Inside USINE (c++)) contains a
|Integration tests from |
|The purpose of integration tests is to demonstrate that different pieces of the system work together. The system here is the list of USINE classes performing Galactic propagation. USINE integration tests cover all run options. Analogous to the implementation of unit tests, the expected output of propagation runs are stored in reference files ($USINE/usine.test/) and compared against the output of modified code versions. These tests encompass outputs of propagated flux calculation for all USINE models, minimisation runs, etc.|
Git repositories usually come with Continuous Integration (CI) tools. We may rely on CI for the code in the future (the code documentation already does, to ensure recompilation for any edit).
|Static and dynamic code analysis:|
|The difference between the two analyses is that one does not need to run the code, while the other does. USINE was analysed with the static analysis tool cppcheck . We also used valgrind to perform dynamic analyses, in particular to track and fix memory leaks (run with
|Profiling and optimisation:|
|So far, we have not used any profiler to check which pieces of code should deserve extra scrutiny for speed. This will be examined for the second release.|
2.4. USINE files and directories¶
- Files in
|CmakeLists.txt||File used by cmake for compilation|
|FindROOT.cmake||Called by CmakeLists.txt to find path to ROOT installation|
|README.md||README file (for gitlab website)|
- Directories in
|doc/||This documentation, see (Re)generate the doc|
|usine.MACROS/||Example of ROOT macros with USINE|
|usine.tests/||Reference test files, see Tests in USINE|
|include/TU*.h src/TU*.cc||USINE header and source files, see Inside USINE (c++)|
|FunctionParser/||Third-party library to handle generic formulae in USINE|
For more details, see USINE input files
|…and created at compilation time|
|bin/usine||USINE executable, see Tutorial: ./bin/usine|
|lib/lib*||USINE and function parser libraries|
2.5. (Re)generate the doc¶
The documentation you are reading is built with Sphinx (and readthedoc theme). If you wish to generate it locally, install the relevant python packages, and type
You can create also a pdf (or ps) document with the commands
The code documentation can be generated based on the Doxygen package and a configuration file (Doxyfile) provided. Just type