1. MUSIC: software overview

MUSIC is a C++ code that should compile and run on any POSIX system (Linux, OS X; Unix in general). As with any code actively used for research, there exists multiple versions of MUSIC. The one discussed in these notes is the official public version, hosted on GitHub *. The source code of this public version is managed with Git. .. This public version of the code was released in 2017.

*

Note that an older version of the code is hosted on Sourceforge, which was originally chosen for its well-designed “Discussion” section. This Discussion section allows users to ask questions about MUSIC and allows for our replies to these questions to be publicly available to everybody as well.

We have a good track record of replying promptly to questions asked on this Discussion website, and I would highly recommend to ask any question about any version of MUSIC there.

All the C++ source code and header files can be found in the ‘src/’ directory. MUSIC additionally relies on one external library, GSL (GNU Scientific Library), used for interpolation and random number generation.

A copy of the code can be obtained with the command:

git clone https://github.com/MUSIC-fluid/MUSIC.git music-hydro-code

The code can be compiled with ‘CMake’: instructions can be found in the README file (“README.md”).

1.1. Running MUSIC

The code can be run simply by:

./MUSIChydro input_file

where “MUSIChydro” is the name of the executable produced after MUSIC is compiled. The input file is discussed below.

There is obviously a large number of parameters in MUSIC. Some are numerical and some are physical.

  • Numerical parameters include those related to the spacetime grid on which hydrodynamics is solved, for example, or the momentum grid on which Cooper-Frye is evaluated.

  • Physical parameters can be used to make MUSIC solve ideal hydrodynamics instead of viscous hydrodynamics, for example, or to change the value of shear or bulk viscosity in the simulations

All the numerical and physical parameters have default values.

Warning

While it is possible that you want to keep the default values for the numerical parameters, it is extremely unlikely that you want to do the same for the physical parameters.

All the parameters in MUSIC can be changed using an input file. Input files are text files which take the format “parameter value”, one “parameter value” combination per line, and the file ends with the line “EndOfData”:

mode  2
Grid_size_in_y  201
Grid_size_in_x  201
Grid_size_in_eta  1
[...]
EndOfData

The input file is passed to MUSIC as command-line argument:

./MUSIChydro input_file_name

The default value is used for any parameter not specified in the input file.

There is a large number of parameters in MUSIC, and they will be discussed in their respective sections (Hydrodynamics, Particlization, …). The only parameter that is important to discuss here is the parameter mode. MUSIC can simulate the hydrodynamic evolution of a heavy ion collisions, the particlization and the post-particlization hadronic decays. These correspond to different “modes” in MUSIC:

Input parameter mode

Value of parameter

What MUSIC does

2

Runs hydrodynamics only

3

Runs particlization (Cooper-Frye) only (assume mode 2 was run before)

4

Runs hadronic decays only (assume mode 3 was run before)

Note : input parameters & default values

The function that reads the input file is ReadInParameters::read_in_parameters() in “read_in_parameters.cpp”. While the parameters are discussed and explained at various other places, the most accurate reference for the list of input parameters and default values is this function.

1.2. Software licence

MUSIC is released under the GPLv2 software licence.

More practical matters related to academic research are discussed below. .. the README file (“README.md”). .. Here is an abbreviated version, for reference:

  • Publishing results computed with MUSIC

    New results computed with MUSIC may necessitate modifying certain parts of the code (routines computing hadronic observables, transport coefficients, initial conditions, …). To avoid any confusion about the physics behind MUSIC, we ask that publications containing results computed with MUSIC specify the initial conditions, equation of state, transport coefficients (first and second order), freeze-out criteria and other information necessary to reproduce the results.

    The following papers should be cited when referring to MUSIC:

      1. Schenke, S. Jeon, C. Gale. “3+1D hydrodynamic simulation of relativistic heavy-ion collisions” Phys.Rev.C 82, 014903 (2010) [arXiv:1004.1408]

      1. Schenke, S. Jeon, C. Gale. “Elliptic and triangular flow in event-by-event (3+1)D viscous hydrodynamics” Phys.Rev.Lett. 106, 042301 (2011) [arXiv:1009.3244]

    3. J.-F. Paquet, C. Shen, G. S. Denicol, M. Luzum, B. Schenke, S. Jeon and C. Gale. “Production of photons in relativistic heavy-ion collisions” Phys. Rev. C 93, 044906 (2016) [arXiv:1509.06738]

  • Modifying MUSIC

    MUSIC users may need to modify various parts of the code. The GPL licence allows for such modifications to be made and distributed (subject to restrictions that can be found in the licence). Nevertheless, we ask and require that you state clearly any scientifically relevant modifications made to the code when you share this modified version of MUSIC. This is to avoid any misunderstanding about the physics behind the code.

  • Contributing to MUSIC

    Should you make changes to MUSIC that you believe would benefit from being shared with the wider community, please contact the code’s maintainers through the MUSIC website. Contributions will be considered whenever possible. While no promises can be made regarding the inclusion of these modifications in the main version of the code, they could be made available separately on the MUSIC website for other users’ convenience. Bug fixes will be considered separately and will be applied promptly.

1.3. Running MUSIC: a simple example

Here is a simple example of how to run MUSIC for a first time

# Downloading the code with Git
git clone https://github.com/MUSIC-fluid/MUSIC.git music-hydro-code

# Go to the base directory of MUSIC
cd music-hydro-code

# MUSIC requires the libraries GSL and MPI to run.
# If you are on Fedora or a similar Linux flavour, you may be able
# to install the libraries this way:
# yum install gsl

# MUSIC can be compiled with "CMake":
mkdir build; cd build; cmake ..; make -Bj; make install

# The compiled code is called "MUSIChydro". We move it to the base directory and go there
cd ..

# Examples of input files are available in the "examples_inputs" directory.
# Here we copy one of them to the base directory
cp example_inputfiles/IPGlasma_2D/music_input_mode_2 .

# Then the code can be run as explained previously
./MUSIChydro music_input_mode_2