SMASH (Simulating Many Accelerated Strongly-interacting Hadrons) is a relativistic hadronic transport approach for the dynamical description of heavy ion reactions. Please see Phys. Rev. C 94, 054905 (2016) for details and cite this reference together with the software DOI for the specific code version employed, if you are using SMASH. A BibTeX entry for the software DOI is found on the respective Zenodo pages.
See CONTRIBUTING for development hints. A complete User Guide can be found here. For a more detailed development documentation, see here.
If Pythia is used, please cite the following references: T. Sjöstrand, S. Mrenna and P. Skands, JHEP05 (2006) 026, Comput. Phys. Comm. 178 (2008).
Report issues at https://github.com/smash-transport/smash/issues or contact us by email at [email protected].
SMASH is known to compile and work with one of these compilers (which have the required C++11 features):
- gcc >= 5.0
- clang >= 3.2
It requires the following tools & libraries:
- cmake >= 3.9
- the GNU Scientific Library >= 2.0
- the Eigen3 library for linear algebra (see http:https://eigen.tuxfamily.org)
- boost filesystem >= 1.49
- Pythia = 8.307
Support for ROOT, HepMC3 and Rivet output is automatically enabled if a suitable version (ROOT >= 5.34, HepMC3 >= 3.2.3, Rivet >= 3.1.4) is found on the system. Please, note that enabling Rivet output or using ROOT >= 6.24.00 requires a compiler supporting C++14 features.
SMASH is tightly coupled to Pythia and thus requires a specific version, which is currently 8.307. Using a different version than specified above may or may not work. If the required version is not already installed or if there are issues, it is recommended to build Pythia with similar flags as used for SMASH:
wget https://pythia.org/download/pythia83/pythia8307.tgz
tar xf pythia8307.tgz && rm pythia8307.tgz
cd pythia8307
./configure --cxx-common='-std=c++11 -march=native -O3 -fPIC'
make
To tell cmake
where to find Pythia while building SMASH see the Building SMASH section.
Note that although Pythia is statically linked into SMASH, access to
share/Pythia8/xmldoc
is required at runtime.
-
The
wget
command is not directly available on OSX. Although this can be easily installed e.g. viabrew install wget
, to download Pythia it is enough to use thecurl
command (see example below). -
On recent Apple machines provided with M1 (ARM) processors, no
gcc
compiler is available andclang
is to be used. The compiler flag-march=native
is not defined and has to be dropped.
The commands above to build Pythia on a M1 Apple machine become:
curl https://pythia.org/download/pythia83/pythia8307.tgz -o pythia8307.tgz
tar xf pythia8307.tgz && rm pythia8307.tgz
cd pythia8307
./configure --cxx-common='-std=c++11 -O3 -fPIC'
make
Usually it is possible to install Eigen with a package manager (it requires admin privileges) and in this case CMake should be able to find the header files without the need of any additional option. For example, on an Apple machine you have the possibility to install Eigen via brew install eigen
, while, under GNU/Linux Ubuntu, via sudo apt-get install libeigen3-dev
.
If for some reason this is not a viable approach, then you can still proceed to a manual installation as described in the following.
Let's assume Eigen headers will be unpacked in $HOME
.
Download the latest stable release of Eigen
from http:https://eigen.tuxfamily.org and unpack it via
tar -xf [latest-eigen].tar.gz -C $HOME
To tell cmake
where to find Eigen header files while bilding SMASH, pass the path to them adding the option
-DCMAKE_PREFIX_PATH=$HOME/[latest-eigen]/
to the cmake
command in the following section.
Use the following commands to build SMASH in a separate directory:
mkdir build
cd build
cmake .. -DPythia_CONFIG_EXECUTABLE=[...]/pythia8307/bin/pythia8-config
make
To build in parallel on N cores:
make -jN
To run it with specific settings:
vi config.yaml
./smash
A few GNU/Linux distributions provide pre-built Pythia binaries without pythia8-config. In this case, using the -DPythia_CONFIG_EXECUTABLE
option as shown above is not possible and the top installation directory of Pythia containing lib
has to be specified in either of the following ways:
- Either set the bash environment variables
PYTHIA8
orPYTHIA_ROOT_DIR
(e.g.export PYTHIA_ROOT_DIR=/opt/pythia8307
) or - use the CMake
-DPYTHIA_ROOT_DIR
option (e.g.cmake .. -DPYTHIA_ROOT_DIR=/opt/pythia8307
).
If no variables are set and no options are passed, CMake searches for Pythia under the default path /usr
.
We recall that it is possible to check which environment variables related to PYTHIA are currently set with:
printenv | grep PYTHIA
To install SMASH do
make install
This will install into /usr/local
. If you want to change the installation directory,
define CMAKE_INSTALL_PREFIX
when configuring the source tree. For example, if you want to install in ~/.local
, do
cmake -DCMAKE_INSTALL_PREFIX=$HOME/.local ..
make install
With CMAKE_INSTALL_PREFIX
=prefix the installation will be
- prefix
/bin
will contain programs - e.g.,smash
, - prefix
/lib
will contain libraries - e.g.,libsmash.so
, - prefix/
include/smash
will contain headers, and - prefix/
share/smash
will contain data files
If compilation fails (especially after changing a library), using a fresh build folder can sometimes fix the problem.
If running SMASH fails with "illegal instruction", it is likely due to running SMASH on a different platform than the one where it was compiled. By default, SMASH is compiled with platform-specific optimizations, implying that the binary only works on such platforms.
There are three possible ways to fix this issue:
- Make sure to compile SMASH on the platform where you run it. When running SMASH on a computing cluster, this requires making the compilation step part of the job script.
- Only run SMASH on platforms similar to the one where it was compiled. When running SMASH on a computing cluster, this requires restricting the jobs to the correct platform.
- Compile SMASH without machine-specific optimizations by removing
-march=native
fromCMakeLists.txt
. This is the easiest solution, however it results in less efficient code.
Note that the same applies to any other libraries you compile with
-march=native
, like for instance Pythia.
If compilation of SMASH in combination with a pre-compiled ROOT binary fails, please install and compile ROOT locally from source (see http:https://root.cern.ch) and compile SMASH again in a clean build directory.
Please note that after compilation the smash
directory (including build
)
has a size of about 4GB. By default, the unit tests are always compiled, which
requires a lot of the disk space. If disk space is restricted, consider to just run
make smash
which will only compile the SMASH binary. It is still recommended to run the unit tests at least once, when compiling in a new environment to ensure that everything works as expected. To see how to run the tests, see CONTRIBUTING.
In order to use a particular compiler, you can set the following environment variables:
export CC=gcc
export CXX=g++
Alternatively the compiler can also be specified to cmake like this:
cmake .. -DCMAKE_CXX_COMPILER=g++
Note: The FPE environment only works with gcc, so e.g. you won't get backtraces from floating point traps with clang.
Producing ROOT output requires ROOT installed (see http:https://root.cern.ch). If ROOT is found, the support for ROOT output is automatically enabled. In order to disable it, one can do the following:
cmake -DTRY_USE_ROOT=OFF <source_dir>
make
The same rules apply to the HepMC output.
cmake -DTRY_USE_HEPMC=OFF <source_dir>
make
See http:https://hepmc.web.cern.ch/hepmc/ for download and the projects' README for
installation. If the HepMC installation is not found, provide the
install destination ($HEPMC_INS
) with
cmake -DCMAKE_PREFIX_PATH=$HEPMC_INS ..
Note that if multiple CMAKE_PREFIX_PATHs are necessary, a semicolon-separated list of directories can be specified.
When compiling SMASH with ROOT >= 6.24.00 it is necessary to use a compiler supporting the C++ standard 14 and add the following argument to the cmake
command:
cmake .. -DCMAKE_CXX_STANDARD=14
When using pre-compiled ROOT binaries it might be necessary to use:
cmake .. -DCMAKE_CXX_STANDARD=17
The Rivet website is: https://rivet.hepforge.org/
The interface with SMASH has been tested with version 3.1.4.
The installation script, downloadable with:
wget https://gitlab.com/hepcedar/rivetbootstrap/raw/3.1.4/rivet-bootstrap
provides a convenient way to install Rivet and its dependencies
(HepMC3 is among those, but, if you have already installed it, you can edit the
script so that Rivet uses your installation).
More infomation about Rivet, its installation and basic usage can be found in
the tutorials in the Rivet website.
Please, note that the compiler must support standard c++14 (e.g. gcc version > 5).
This also means that the c++14 standard has to be set for the SMASH build (ideally
from a clean build directory) by adding the following to the cmake
command:
cmake .. -DCMAKE_CXX_STANDARD=14
Please, also note that, every time Rivet is used, some environment variables must be set in advance. The script rivetenv.sh, in the Rivet installation directory, takes care of this step:
source [...]/rivetenv.sh
where [...]
is not a command, but a shortand for the path of the directory in
which Rivet is installed.
If Rivet (with all its dependencies) is installed and the environment variables are set, it will be automatically detected by cmake.
Download and unpack GSL:
wget ftp:https://ftp.gnu.org/gnu/gsl/gsl-latest.tar.gz
tar -zxvf gsl-latest.tar.gz
This creates a folder named gsl-[version_number]
called $GSL
here.
cd $GSL
./configure --prefix $GSL
make -jN
make install
Here N is the number of cores to use in the make
command. When compiling
SMASH, run cmake
with
cmake -DGSL_ROOT_DIR=$GSL ..
Note: In case of problems, make sure to start with a clean build folder.
Alternatively to building SMASH, a Docker image of the latest or recently tagged version can be pulled from the Github container registry. Get the newest version with
docker pull ghcr.io/smash-transport/smash:newest
Start the container with
docker run -it ghcr.io/smash-transport/smash:newest
A ready-to-use exectuable of smash is found in the smash_bin
directory. Run as
explained below. SMASH can also be build inside the container as explained at
the beginning of the README (the SMASH source and Pythia are also found in the
/SMASH
directory).
Two container versions of SMASH are offered: a small version
(ghcr.io/smash-transport/smash
) with a minimal set of dependencies
pre-installed and a maximum version with all possible external dependencies,
e.g. ROOT, HepMC and Rivet, already included
(ghcr.io/smash-transport/smash-max
). Running SMASH inside of a Docker container
might negatively affect performance. More information on container usage is
found in the README files in the containers
directory.
SMASH ships with example configuration files for the collider, box, sphere, and
list modus. By default, i.e. by running ./smash
, the simulation is set up from
the collider configuration file, called config.yaml
, and the default
particles and decaymodes files, particles.txt
and decaymodes.txt
. They are
located in /input
.
Additionally, example configuration files for the box, sphere and list modus can
be found in the respective directories /input/{box,sphere,list}
. In case of the
box simulation, in order to allow for equilibration, different default particles
and decaymodes files need to be used. These files are also provided in
/input/box
. For the list modus, an input list file to be read in is required.
This file, example_list0
, is located in /input/list
.
To run SMASH with a non-default configuration file, use the -i
command.
For example, for the sphere or list example file:
./smash -i ../input/sphere/config.yaml
./smash -i ../input/list/config.yaml
Further, using non-default particles and decaymodes files is necessary, and these
can be specified through the -p
and -d
options. In the box and the dileptons
example,
this means:
./smash -i ../input/box/config.yaml -p ../input/box/particles.txt -d ../input/box/decaymodes.txt
./smash -i ../input/dileptons/config.yaml -d ../input/dileptons/decaymodes.txt
All command line options can be viewed with
./smash -h
To run SMASH completely silently for production runs, we recommend to redirect stdout to /dev/null, warnings and error messages will still be displayed.
./smash > /dev/null
SMASH is licensed under the terms of the GNU General Public License, Version 3 or above. The build scripts are licensed under terms of the BSD 3-clause license. See LICENSE.
SMASH source and documentation are provided to check and reproduce published results of the authors. Cooperation and joint projects with outside researchers are encouraged and comparison to results by experimental collaborations is supported. SMASH can be used as a 3rd party library, for examples see ${SMASH_DIR}/examples/ folder. If you are interested in starting a project, please contact us to avoid interference with current thesis topics. If your project involves changes to the code, please refer to CONTRIBUTING for coding guidelines and helpful tools.