Installation

Requirements

Required

Fortran Compiler: Currently SCONE requires gfortran (>=8.3). Support for other compilers is pending.
CMake: CMake cross-platform build system is used to run all configuration scripts. Version (>=3.10) is required.
LAPACK and BLAS Libraries: For the moment, SCONE requires LAPACK and BLAS linear algebra libraries. However, they are not used extensively in the code and this dependency will become optional or will be removed.
GNU/Linux operating system: In principle any UNIX-like operating system should support SCONE. However people have experienced some significant run-time bugs when running on MacOS. Since we do not have an access to a Macintosh we were not able to identify the problem yet.

Optional

pFUnit 4 test framework and Python interpreter: Both the unit and the integration tests in SCONE use pFUnit framework. To run it requires a python interpreter. NOTE that version 4 (contrarily to the older 3.0) requires the use of gfortran version 8.3 or newer.

MPI and OpenMP for parallelism

Getting gfortran

To verify that you have gfortran available by typing:

gfortran --version

If you do not or its version is too old you will need to get it. If you have root access to your machine you can your package manager to install gfortran. On Debian/Ubuntu Linux a command like that will suffice:

sudo apt-get install gfortran

On other operating systems it might different. You will need to find information on how to use package manager in your Linux distribution. Pre-compiled gfortran packages can be found here

Without administrator privileges you may want to compile GCC from source. Of course that requires having a C compiler.

Download the source code of GCC from one of the mirrors

Extract the archive and use a provided script to download all prerequisites:

tar -xf gcc-9.1.0.tar.gz
cd gcc-9.1.0
./contrib/download_prerequisites

Now configure the compilation. The command below is crude. We only set a prefix where gcc will be installed after successful compilation and select languages (frontends) we want to include. Documentation of the configure script is available
```
./configure --prefix=/path/to/install --enable-languages=c,c++,fortran
```
Providing that the configuration was successful, you can now start compiling GCC. It is a large code base and the process can take as much as few hours. To speed it up you can use parallel compilation with make -j 8 assuming that you have 8 processors available. You can use nproc in console to check how many are available. When ready type:
```
make -j8
make install
```
Once your finished now you need to modify some of your environmental variables to allow OS to find the executables and relevant libraries. In your .bashrc` add the following lines (depending on your install directory):
```
export export PATH=/path/to/install/bin:$PATH
export LD_LIBRARY_PATH=/path/to/install/lib64:$LD_LIBRARY_PATH
```

Getting CMake

If you have root access to your machine use package manager to obtain the latest version of CMake. If you don’t you can follow the instructions.

Download the installation shell script for Linux from the website e.g. cmake-3.17.0-rc1-Linux-x86_64.sh.
Then you can install CMake by typing and following the instructions:
```
bash ./cmake-3.17.0-rc1-Linux-x86_64.sh
```

Add the CMake to you PATH in .bashrc:

export PATH=/cmake/install/folder/bin:$PATH

Installing pFUnit

This is only required if the unit tests are to be build.

Make sure python can be invoked by a command python by typing:
```
python --version
```

Download the pFUnit repository and enter the source code folder:

git clone https://github.com/Goddard-Fortran-Ecosystem/pFUnit.git
cd pFUnit

Create a build folder:
```
mkdir build
cd build
```

#. Compile the code. Note that pFUnit 4 compiles with MPI support on by default, so MPI needs to be available. More specifically, for compatibility with SCONE, mpi_f08 needs to be available:

cmake -DENABLE_MPI_F08=YES ./..

Alternatively, if one does’t have access to mpi_f08 and wants to compile SCONE without MPI support:

cmake -DSKPI_MPI=YES ./..

Run make and install application

make tests make install
Export environmental variables required by pFUnit:
```
export F90=gfortran
export F90_VENDOR=GNU
```

LAPACK and BLAS

If you have root access it is best to install these with your package manager. Follow the instructions only if you want to compile LAPACK and BLAS from source

Download a version of LAPACK from official website.
In some directory on your filesystem extract the archive.
Configure compilation with cmake by typing:
```
mkdir Build
cd Build
cmake ./..
```
If you don’t have a root access on your machine or you want to install LAPACK to a custom directory, use ccmake to change CMAKE_INSTALL_PREFIX. In Build directory type:
```
ccmake ./..
<Navigate to CMAKE_INSTALL_PREFIX and change it to your folder>
Press [c] to configure
Press [g] to generate and exit
```
Now compile LAPACK and install by typing:
```
make
make install
```

Compiling SCONE

If you want to install with tests set PFUNIT_INSTALL environmental variable to directory in which pFUnit was installed. It may be worth adding the line to your .bashrc
```
export PFUNIT_DIR=~/pFUnit/build/
```
If your LAPACK installation is not in default system directories use LAPACK_INSTALL enviromental variable to help CMAKE find the library. e.g.
```
export LAPACK_INSTALL=~/LAPACK
```

Download the repository. Run the following commands:

git clone https://github.com/CambridgeNuclear/SCONE

Create build folder in the project directory (e.g. build):
```
cd ./scone
mkdir build
```

Generate makefile with CMake and compile:

cmake -E chdir ./build cmake ./..
make -C build

To switch off compilation of tests use the following commands:

cmake -E chdir ./build cmake ./.. -DBUILD_TESTS=OFF
make -C build

Note that you can use ccmake utility to modify avalible options and regenerate your make file just type the following into your terminal and follow the instructions:
```
ccmake ./build
```

CMake options

LTO

Enable link-time optimisation. It allows the compiler to perform extra optimisations between different compilation units (modules in Fortran). It is crucial for performance in SCONE, since it enables inlining of small type-bound procedures. Set to ON by default. To disable:

cmake .. -DLTO=OFF

COVERAGE

Collect code coverage information. If ON it allows to use lcov and genhtml to create an HTML coverage report. It is OFF by default. Enable with:

cmake -DCOVERAGE=ON

BUILD_TESTS

Build unit and integration tests. It is ON by default. If enabled, the pFUnit must be installed and PFUNIT_INSTALL set. To disable tests:

cmake -DBUILD_TESTS=OFF

DEBUG

Enable extra run-time checks available in the compiler. It is OFF by default. To enable:

cmake -DDEBUG=ON

OPENMP

Sets up OpenMP to allow for shared memory parallelism. It is ON by default. To disable:

cmake -DOPENMP=OFF

MPI

Links SCONE with MPI to allow for multi-process parallelism. It is ON by default. To disable:

cmake -DMPI=OFF

Note

Suppress message during MPI runs

When running SCONE with MPI the message ‘No protocol specified’ might appear. This was already documented and reported in:

https://github.com/open-mpi/ompi/issues/7701

Since there doesn’t seem to be an established solution to this, one can suppress the message for convenience by adding to the .bashrc file the line:

export HWLOC_COMPONENTS=-gl

Run Tests to Verify

If you compiled SCONE with tests enabled (you should by the way) you can now verify that it works correctly by running the automated test suites. You must execute the following commands from the scone directory. Some integration tests use files in IntegrationTestFiles and have hard-coded relative paths. Integration tests may fail if they are run from other directory. Run:

./build/unitTests
./build/integrationTests

This assume that build is the build directory. If the tests were successful that is great. If some of them failed it is troubling. Please open an Issue in the online repository so we can try to resolve what is the problem. Provide at least the following information:

Compiler Used (with version)
Operating System

Unfortunately we do not have access to Intel Fortran compiler so we cannot test SCONE with it. We are planning to add support for Flang soon.

Obtaining Nuclear Data

SCONE requires ACE-formatted nuclear data. The JEFF-3.3 evaluation can be download from the OECD NEA website. In addition SCONE requires its own library file. An example of it is given in IntegrationTestFiles/testLib. Its format is:

! This is a comment line
! Each line needs to contain three entries
! ZAID   Line Number   PATH
92233.03c;  1;       <absolute_path>/9233JEF33.ace;
1001.03c;   4069;    <absolute_path>/1001JEF33.ace;
...

Line Number is the line in the file at which a particular data card begins. Each line cannot contain more then a single entry. Each component must be delimited by a semi-colon.

To generate the library file from the collection of raw ACE files one can use the scripts/make_ace_lib.sh bash script. It can be run with the following command:

./scripts/make_ace_lib.sh <output> <MODE> <search_keyword> <path_to_base_folder>

To get extra help run the script without any arguments. In the line above, <output> is the file that will be created; <MODE> can be either CE for continuous energy neutron data cards and SAB for thermal scattering S(α,β) cards; <search_keyword> will restrict the search to files that include this keyword in their name; <path_to_base_folder> is the path to the folder than contains the ace files. The script can search recursively inside folder structures too.

Some useful choices for the input <search_keyword> could be: ace, nc (e.g., for ENDFB/VIII.0), t for thermal scattering data, sssth for the Serpent thermal scattering file, or '*' to search all files available in the path specified. Some example calls are:

./scripts/make_ace_lib.sh ./endfb8.aceXS CE nc  ./Lib80x/
./scripts/make_ace_lib.sh ./jeff40.aceXS CE '*' ./JEFF40/

Sadly the script can search only for a single type of card in one pass. Thus to create a full library with thermal data we need to do the following:

./scripts/make_ace_lib.sh ./tempCE  CE  ace ./path_to_CE_ace_files/
./scripts/make_ace_lib.sh ./tempSAB SAB t   ./path_to_SAB_ace_files/
cat tempCE tempSAB > fullLib.xsfile

Having made this file, one can optionally define the environmental variable SCONE_ACE, e.g., in the .basrhc file and refer to it in input files which use the aceNeutronDatabase. To do so, in the .bashrc file include:

export SCONE_ACE=/path/to/fullLib.xsfile