+---------------------------------------------------------------+
| W e l c o m e t o : |
| _____ _ _ _____ ______ ____ |
| / ____|| | | | /\ | __ \ | ____| |___ \ |
| | (___ | |__| | / \ | |__) || |__ __ __ __) | |
| \___ \ | __ | / /\ \ | _ / | __|\ \ / /|__ < |
| ____) || | | | / ____ \ | | \ \ | |____\ V / ___) | |
| |_____/ |_| |_|/_/ \_\|_| \_\|______|\_/ |____/ |
| |
| Statistical with REsonances |
| HAdronization |
| ... and CHARM |
+---------------------------------------------------------------+
Authors: M. Petran, J. Letessier, J. Rafelski, G. Torrieri
Comments, concerns and suggestions to:
michal.petran@cern.ch
===========
0. CONTENTS
===========
This file contains a installation guide for SHARE with CHARM (SHAREv3)
program and a quick start guide. All of these sections are taken
over from a complete SHARE with CHARM manual available at
http://www.physics.arizona.edu/~gtshare/SHARE/share.html
This README is divided into the following sections:
1. QUICK START
2. INSTALLATION
2.1 Pre-requisites
2.2 Organization of the program package
2.3 Recommended compilation - using 'make'
2.4. Manual compilation
3. RUNNING SHARE WITH CHARM
==============
1. QUICK START
==============
This section provides a quick reference how to install SHARE with CHARM on most common
PC with GNU Linux system, namely we assume gfortran and g++ compilers and cernlib
installed. If you encounter any problems following this quick guide, please refer to Section 2 for
detailed installation guide.
1) In a terminal, navigate into a folder where you want to install SHARE with CHARM and
download the package with the command
wget http://www.physics.arizona.edu/~gtshare/SHARE/sharev3.zip
2) Unzip the package contents with the command (this will create a new subfolder sharev3)
unzip sharev3.zip
3) Enter the unpacked folder and compile SHARE with CHARM using
cd sharev3
make
===============
2. INSTALLATION
===============
2.1 Pre-requisites
==================
Before you start installing SHARE with CHARM, make sure you
have the following installed on your system:
- Fortran 77 compiler, we have tested GNU gfortran
and Intel ifort compilers.
- C++ compiler (including C++ standard libraries), we have tested GNU g++
and Intel icpc compilers.
- CERNLIB libraries. They are available in standard repositories
for most GNU Linux distributions, alternatively, the source code
is available for download at Homepage of CERNLIB,
Debian based linux distribution (Ubuntu,...) users should locate
and install the package cernlib from their system repository.
Red Hat base (Fedora Project, SLC,...) can install cernlib from a
rpm package available, for example, at CERNLIB rpm package list
2.2 Organization of the program package
========================================
The SHARE with CHARM program comes in a single .zip archive
labeled sharev3.zip. The package is available at
http://www.physics.arizona.edu/~gtshare/SHARE/share.html.
After obtaining the program package, unpack it using the
following command (it will create a folder called sharev3
with all the files in it):
unzip sharev3.zip
The following files will be created in this directory
from the archive contents. The files are
enough for a 'representative' run of SHARE with CHARM.
src/sharev3.0.0.F -- SHARE source code in Fortran 77.
src/CharmDistribution_v1.9.cpp -- CHARM module source code in C++.
decays.data -- The complete Particle Data Group decay tree
of light hadrons (Section 3.3.1 of the manual).
HFfeed.data -- The complete Particle Data Group decay tree
of charm hadrons (Section 3.3.3 of the manual).
LHC1020MI.data -- A representative input data files (Section 3.4 of the manual)
containing experimental yields data for centrality bin 10-20%
based on data from the ALICE experiment as of August 2013,
see (M. Petran, et al., Phys.Rev.C 88, 034907 (2013), [arXiv:1303.2098])
and references therein.
makefile -- A makefile of the project, useful for program compilation, see Section 2.3 below.
particles.data -- Particle properties with full widths (Section 3.2 of the manual).
partnowdt.data -- Particle properties with no widths (Section 3.2 of the manual).
Calculations with this input file require significantly less computational time,
and the use of full widths has not yet been justified, see for example
recent comparison in (M. Petran, et al., arXiv:1309.6382).
ratioset.data -- The parameter ranges input file (Section 3.1.2 of the manual).
ratioset.test -- The parameter ranges input file for Quick Start test run.
sampleoutput -- Directory containing sample output files resulting from a ‘representative’
sample run with input files we provide as part of the package.
sharerun.data -- A ‘representative’ run input file (Section 4) including an analysis of hadron
yields at LHC presented by members of our collaboration in
(M. Petran, et al., Phys.Rev.C 88, 034907 (2013), [arXiv:1303.2098]).
thermo.data -- The list of model parameters (Section 3.1 of the manual).
weak.feed -- A sample weak decay file (Section 3.3.2 of the manual).
README.txt -- This file.
2.3 Recommended compilation - using 'make'
===========================================
The recommended way to compile SHARE with CHARM
is to make use of the GNU make utility, available on most
GNU Linux systems (if this is not your case, proceed to Section 1.4 below).
The most common combination of available compilers is gfortran and g++. If this is your case,
after unzipping the contents of the program package into a folder, use the command
make
in this directory to compile the program. If you are using different compilers,
edit the header of the included makefile to specify compilers available
on your system. When done, use make (as above) to compile SHARE with CHARM.
Using make with the included makefile processes the two source files in the src folder,
compiles each of them into an object file, which is stored in the obj folder
and then links the object files together with CERN libraries into an executable share,
which is ready to be run from the command line. We provide the two most common
targets in the makefile, all to compile the program and clean to remove objects
and executable file. You may also need to specify the location
of the CERN libraries on your system in the makefile, for instance,
LIBS = -L/usr/local/cernlib/2006/lib -lstdc++ ...
2.4. Manual compilation
=======================
SHARE with CHARM consists of two source code files, both located in the src subdirectory.
Manual compilation consists of three steps.
1) Compiling SHARE Fortran code into an object. For example, using the GNU Fortran compiler
gfortran, this is done via the following command (in the src folder):
gfortran sharev3.0.0.F -c -o sharev3.0.0.o
Note the -c option to prevent linking. You may need to consult your Fortran compiler
documentation for equivalent command line options.
2) Compiling the CHARM module written in C++ is accomplished similarly to the above step,
using an example command line with GNU C++ compiler g++:
g++ CharmDistribution_v1.9.cpp -c -o CharmDistribution_v1.9.o
3) Linking all object files with the necessary libraries into an executable binary file share is
accomplished using the Fortran compiler used in step 1 on the following command line :
gfortran sharev3.0.0.o CharmDistribution_v1.9.o \
-lstdc++ -lkernlib -lmathlib -lpacklib -o share
In case you compiled CERN libraries manually, you may need to specify the location of the
libraries on the last command line using the -L//lib option in order
to link them properly. If necessary, consult your compiler and CERN libraries
documentation for details.
When all three steps are completed without errors, move (copy) the executable binary of
SHARE with CHARM (share in the above example) to the parent directory (i.e., one directory
up) where all SHARE input files are located. The program is invoked with ./share command
(unless a different name was chosen by the user during compilation). The program opens the
sharerun.data file located in the current directory and performs tasks specified therein. See
Section 4 for details on how to run the program. The provided copy of sharerun.data should
produce detailed output showing the program capabilities, which can used to check correct
program operation by comparing with the provided sample output in the sampleoutput directory.
Tests were run on both 32 and 64 bit processors with two different versions of CERN libraries.
Differences between platforms appear when fitted parameters are not constrained by data, see
Section 4.6 of the manual.
===========================
3. Running SHARE with CHARM
===========================
Once SHARE with CHARM is compiled, it can be run in a terminal with the command
./share
If you have not already, it is a good idea to run the program once with the default setup.
Individual operations SHARE performs during a run are specified in the file sharerun.data.
Without any changes to the input files after installation, the program is preset
to read the provided input files and to perform a chemical non-equilibrium fit
to 10-20% centrality data from Pb–Pb collisions at LHC with only 2 free parameters
(this calculation takes less than 10 seconds). Let us show how to modify the input files
in order to perform a semi-equilibrium fit to the same data set. This requires a few steps;
changing the fit output filename, changing a parameter value and fixing a parameter
(rather than fitting it).
Changing fit output file name
-----------------------------
Looking at the contents of sharerun.data in a text editor, the
fitting command is the following line
CALC FITRATIOS fitTESTne.out
It tells SHARE to perform a fit (FITRATIOS) all free parameters to experimental data, and
that the output file name is fit1020ne.out. The file is over-written every run. So let us
redirect the new output to another file by changing this line to
CALC FITRATIOS fitTESTse.out
so we have both outputs for comparison. The output filename has to be 13 characters long.
Remember to keep two spaces between each word.
Setting parameter value
-----------------------
Parameter values are set in thermo.data file. Open it in a text editor
of your choice. Chemical semi-equilibrium is defined by gamma_q = 1
and thus we need to change the line starting
with the parameter name, gamq, to read
gamq 1.
Remember to keep four spaces after the parameter name and always enter
a decimal point even for integer values. Changing initial parameter
values advisable to assure the fit stability, i.e., that the fit
converges to the same minimum from a different starting point(s) in the
parameter space.
Fixing/Fitting a parameter
--------------------------
Parameter ranges are defined in ratioset.test file (equivalent
to ratioset.data, Section 3.1.2 of the manual). Upon opening the file
in a text editor, you will notice that each parameter has a separate
line such as the following one for gams (gamma_s):
gams 0.1 9. 0.1 0
In the previous non-equilibrium fit, gams was fixed. Parameter with 0
in the last column will be kept constant during a fit, whereas parameters
with 1 in the last column are to be changed within the allowed range
(first two numbers on the line). The different value of gamma_q
we set in the previous step will result in a new value of gamma_s,
so let us release gams, change the 0 to 1 on the above q
uoted line, so the line should read:
gams 0.1 9. 0.1 1
and let the program find the best value of gamma_s to describe the data.
With the above modifications, running ./share again will produce a new
output file with semi-equilibrium fit (with 3 free parameters, T , V and gamma_s)
to the same experimental data defined in the file LHC1020MI.data. Note that
the resulting fit will have lower quality as other parameters
are fixed to their non-equilibrium values.
Changing experimental data point
--------------------------------
Every line in LHC1020MI.data contains one data point
name, experimental value, statistical and systematic error and whether or not
this data point is fitted or only evaluated during a fit. For example,
the yield of Lambda is defined on the following line:
Lm1115zer prt_yield 17. 2.0 0. 1
One can change the value from 17 +/- 2 to a different one by changing the numbers.
The data point can be excluded from the fit by changing the 1 to a 0
in the last column. Similarly to fixing a parameter above, this implies
that the experimental value will not be fitted, its theoretical value will be
calculated based on the model parameters irrespective of its experimental value.
SHARE with CHARM program is far more capable than the basic operation shown in this
Quick Start guide, we refer the reader to the program manual at
http://www.physics.arizona.edu/~gtshare/SHARE/share.html
for details about program operation, input file structure,
and full description of its capabilities.