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 Sourceforge [*]. The source code of this public version is managed with Git. This public version of the code was released in 2017.

[*]

Sourceforge was chosen to host the code in part for its well-designed “Discussion” section, which 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 MUSIC there.

All the C++ source code and header files can be found in the ‘src/’ directory. MUSIC additionally relies on two external libraries: MPI (Message Passing Interface), which is used to parallelize the code, and 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://git.code.sf.net/p/music-hydro/code music-hydro-code

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

1.1. Running MUSIC

Since the public version of MUSIC is compiled with MPI, it may need to be run using the “mpirun” command:

mpirun -n 1 ./mpihydro input_file

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

The “-n” option of “mpirun” controls how many CPU’s are used to run MUSIC, since the code can run in parallel. Using mpirun -n 2 ./mpihydro input_file would run MUSIC on two CPUs, and so on.

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 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:

mpirun -n 1 ./mpihydro 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
1 Runs hydrodynamics, particlization (Cooper-Frye) and hadronic decays in succession
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 in 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://git.code.sf.net/p/music-hydro/code music-hydro-code

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

# The source code is in "src/"
cd src

# 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 mpich mpich-devel

# This example assumes that you are using the MPICH implentation of MPI
# On certain system (and on most supercomputers), MPI is installed as a module that must be loaded before compiling and running the code
module load mpi/mpich-x86_64

# MUSIC can be compiled with both "CMake" and "make". I use "make" here
make -f makefile_guillimin

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

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

# Then the code can be run with "mpirun" as explained in previously
mpirun -np 1 ./mpihydro music_input_mode_2