SCRAM

SCRAM is a Command-line Risk Analysis Multi-tool.

This project aims to build a command line tool for probabilistic risk analysis. SCRAM is capable of performing event tree analysis, static fault tree analysis, analysis with common cause failure models, probability calculations with importance analysis, and uncertainty analysis with Monte Carlo simulations. This tool can handle non-coherent fault trees, containing NOT logic.

SCRAM input and report files are based on the Open-PSA Model Exchange Format. For the current status of the Open-PSA MEF features in SCRAM, please see the MEF Support documentation.

A complementary GUI front-end is under development for visualization and manipulation of risk analysis models and reports.

To explore the performance of SCRAM or research fault trees, a fault tree generator script is provided, which can create hard-to-analyze fault trees in a short time.

The documentation contains a full description of SCRAM, its current capabilities, and future additions. The latest stable release is packaged for quick installation on various platforms.

Table of Contents

• Building and Installing
  • Git Submodules
  • Dependencies
    • Optional Dependencies
    • Compilers
  • Installing Dependencies
    • Ubuntu
    • macOS
    • Windows
  • Installing SCRAM
• Running SCRAM and Tests
  • To run SCRAM
  • To launch the GUI
  • To run tests
  • To run performance tests
  • To run fuzz testing
    • Cross Validation
• Documentation Building
• Note to a User
• How to Contribute

Building and Installing

Git Submodules

Some dependencies are provided with git submodules (e.g., Google Test). In order to initialize all the submodules, this repository must be cloned recursively with git clone --recursive, or the following commands must be executed after a normal clone.

git submodule update --init --recursive

Dependencies

Package	Minimum Version
CMake	2.8.12
boost	1.61 (1.58 on Linux)
libxml2	2.9.1
Python	2.7.3 or 3.3
Qt	5.2.1

Optional Dependencies

Package	Minimum Version
TCMalloc	1.7
JEMalloc	3.6

Compilers

Package	Minimum Version
GCC/G++	4.9
Clang/LLVM	3.6
Intel	17.0.2

Installing Dependencies

The following installation instructions and scripts are taken from Cyclus.

This guide assumes that the user has root access (to issue sudo commands) and access to a package manager or has some other suitable method of automatically installing libraries.

Ubuntu

This process is tested on Ubuntu 16.04 LTS using apt-get as the package manager.

The command to install a dependency takes the form of:

sudo apt-get install package

Where package is replaced by the correct package name. The minimal list of required library package names is:

1. cmake
2. libboost-all-dev
3. libxml2-dev
4. qtbase5-dev
5. qtbase5-dev-tools
6. qttools5-dev
7. libqt5svg5-dev
8. libqt5opengl5-dev

and (optionally):

1. libgoogle-perftools-dev

compiler:

• gcc g++

For example, in order to install Boost on your system, type:

sudo apt-get install libboost-all-dev

Python and GCC/G++ compilers are assumed to be available on the system. If you'd prefer to copy/paste, the following line will install all major dependencies:

sudo apt-get install -y cmake lib{boost-all,xml2,google-perftools,qt5{svg,opengl}5}-dev qtbase5-dev{,-tools} qttools5-dev

macOS

If on a Mac system, a good manager to use is macports or homebrew. It is assumed that some dependencies are provided by Xcode. The following instructions are tested on OS X 10.9, but it should work for later versions as well.

Using homebrew, the command to install a dependency takes the form of:

brew install package

If the package is already installed the command will fail, instead upgrade the package if necessary:

brew outdated package || brew upgrade package

Where package is replaced by the correct package name. The minimal list of required library package names is:

1. cmake
2. boost
3. libxml2
4. qt5

and (optionally):

1. gperftools

compiler:

• clang/llvm

For example, in order to install Boost on your system, type:

brew install boost

If you'd prefer to copy/paste, the following line will install all major dependencies:

brew install cmake boost libxml2 gperftools qt5

Windows

MSYS2/Mingw-w64 is the recommended platform to work on Windows. Assuming MSYS2 is installed on the system, the following instructions will install SCRAM dependencies.

Using pacman, in MSYS2_64 command shell, a C++ dependency installation takes the form of:

pacman -S mingw-w64-x86_64-package

Where package is replaced by the correct package name:

1. gcc
2. make
3. cmake
4. boost
5. libxml2
6. qt5

and (optionally):

1. jemalloc

If Python has not yet been installed on the system, Python installation takes the form of:

pacman -S python

If you'd prefer to copy/paste, the following line will install all major dependencies:

pacman --noconfirm -S python mingw-w64-x86_64-{gcc,make,cmake,boost,libxml2,qt5,jemalloc}

SCRAM installation and executables must be run inside of the MSYS2 shell.

Installing SCRAM

A python script is provided to make the build/installation process easier. If there are dependency issues, CMake output should guide with errors. CMake can be used directly without the python script to configure the build.

The default installation directory is ~/.local. The default linkage is dynamic; however, tests are statically linked against GoogleTest.

.../scram$ python install.py  --prefix=path/to/installation/directory

The main and test binaries are installed in installation/directory/bin. The input files and schema are copied in installation/directory/share/scram/.

The default build type is Debug with many compiler warnings turned on, but it can be overridden by --release or --build-type CMAKE_BUILD_TYPE. For performance testing and distribution, use --release flag:

.../scram$ python install.py --prefix=path/to/installation/directory --release

For Mingw-w64 on Windows, add --mingw64 flag.

.../scram$ python install.py --prefix=path/to/installation/directory --release --mingw64

Various other flags are described by the script's help prompt.

.../scram$ python install.py --help

Other tools, such as the fault tree generator, can be found in the scripts directory. These tools do not need compilation or installation.

Running SCRAM and Tests

This guide assumes that SCRAM installation directories are in the global path. If this is not the case, path/to/installation/directory/bin/ must be prepended to the command-line calls. However, if SCRAM executables are not in the path, some system tests and scripts cannot be initiated.

To run SCRAM

Example configuration and input files are provided in the input directory.

scram path/to/input/files

On command line, run help to get more detailed information:

scram --help

Various other useful tools and helper scripts, such as the fault tree generator, can be found in the scripts directory. Help prompts and the documentation have more details how to use these tools.

To launch the GUI

To launch the GUI front-end from the command-line:

scram-gui

The command can also take project configuration and/or input files:

scram-gui path/to/input/files

scram-gui --config-file path/to/config/file

scram-gui path/to/input/files --config-file path/to/config/file

To run tests

To run the unit and benchmark tests:

scram_tests

To test the tools in the scripts directory:

nosetests -w scripts/ test/

To test the command-line call of SCRAM:

nosetests -w tests/

To run performance tests

A set of performance tests is provided to evaluate the running times on the host machine and to help developers check for regressions. More details can be found in performance test source files.

To run all performance tests (may take considerable time):

scram_tests --gtest_also_run_disabled_tests --gtest_filter=*Performance*

To run fuzz testing

The main goal of SCRAM fuzz testing is to discover defects in its analysis code. It is recommended to build SCRAM with assertions preserved and sanitizers enabled, for example, address sanitizer in GCC and Clang -fsanitize=address.

In order to speed up the fuzz testing, SCRAM may be built with optimizations but NDEBUG undefined. Additionally, multiple SCRAM instances can be run at once.

An example command to run SCRAM 1000 times with 4 parallel instances:

fuzz_tester.py -n 1000 -j 4

The fuzz tester can be guided with options listed in its help prompt. Some options can be combined, and some are mutually exclusive. The priorities of mutually exclusive options and combinations are hard-coded in the script, and no error messages are produced; however, information messages are given to indicate the interpretation.

fuzz_tester.py --help

Fuzzing inputs and configurations are auto-generated. The fuzz tester collects run configurations, failures, and logs. The auto-generated inputs are preserved for failed runs.

Cross Validation

The Fuzz tester can check the results of qualitative analysis algorithms implemented in SCRAM. If there is any disagreement between various algorithms, the run is reported as failure.

fuzz_tester.py --cross-validate

Documentation Building

Documentation is generated with the configurations on the gh-source branch. The raw documentation files are in the doc directory.

Note to a User

The development may follow the Documentation Driven Development paradigm for some new features. Therefore, some documentation may be ahead of the actual development and describe features under current development or consideration.

For any questions, don't hesitate to ask the user support mailing list (https://groups.google.com/forum/#!forum/scram-users, [email protected]).

For latest releases and information about SCRAM, feel free to subscribe to the announcements (https://groups.google.com/forum/#!forum/scram-announce, [email protected]).

How to Contribute

Please follow the instructions in CONTRIBUTING.md.