January 31, 2022 Dataset Open Access

Modulation Module for HelMod-4

Boschini, M.J.; Della Torre, S.; Gervasi, M.; La Vacca, G.; Rancoita, P.G.

The SDE integration with HelMod results in a quite expensive effort from the computational point of view since, to minimize the uncertainties, a huge amount of events should be integrated from Earth to the heliosphere boundary. Monte Carlo integration allows us to evaluate the normalized probability function (G) that a particle observed at Earth with rigidity R0 entered into the heliosphere with rigidity R. The convolution of the normalized probability function with the very local interstellar spectra result in the modulation of differential intensity for the time and solar distance where G was evaluated. In the present dataset, we provide the numerical output of HelMod-4 model (www.helmod.org) in the form of normalized probability histograms. The python script attached is able to convert GALPROP output (or plain text LIS file) to modulated spectrum for periods of selected experiments.

This dataset was used as part of the publications in the references.

For any information about the HelMod-4 Model, please refer to the official website.

How to install and configure 

Install python (>3.0) packages

• astropy
• scypy >=0.17.0
• numpy >=1.10
• matplotlib

Download the Python OfflineModule and the HelModArchive. The archive is provided in tgz format, thus it needs to be first unpacked with the command tar -xvzf <ArchiveName>.tgz. 

The archive structure:

The HelModArchives.tgz contains several directories each one with the name of a space or balloon mission. Each folder should be considered as an HelMod Archive containing the following files:

• ExpList.list : List of nuclei and isotopes simulated (to not modify)
• ExpList_Plot.list: List of nuclei available in the archive, reference and plots properties (do not modify first and second columns, the others can be updated to modify the output plots)
• ParameterSimulated.list: list of folders in the form RawPar_HelMod4_XX,  (at least one line should start with '+', if not, please add it to first line)
• ParameterSimulated_DB.list: list of folders in the form RawPar_HelMod4_XX, with description
• Version.txt : Version notes
• DataTXT : experimental energy and rigidity binning used for simulations
• RawPar_HelMod4_00 : HelMod simulations outputs

How to use the module:

The usage of the module requires three elements:

• An Helmod Archive unpacked in some known folder. E.g. let's <ArcPath>=/home/test/Archive1
• A LIS from galprop fits file OR plain text file format (hereafter called <LIS_FILE>). 
• The label of the ion/dataset (hereafter called <ExpNameKey>) that are intended to be modulated.

The list of available <ExpNameKey>  in each archive may be found in the file ExpList_Plot.list or using the command-line 

python3 HelMod_Module.py -a <ArcPath> -l

The basic command to get the modulated spectrum is:

python3 HelMod_Module.py -a <ArcPath> --LIS <LIS_FILE> --SimName <ExpNameKey>

other available options:

• -h help description
• -t use this option to specify that <LIS_FILE> is a two-column plain text file (see below).
• -p <PAR_SET_NAME>  Choose a different set of parameters. The list of available parameter set names is available in the file ParameterSimulated_DB.list .
• --MakePlotCreate a Plot in png format.
• --SumAllIsotpes (can be used with GALPROP LIS inputs) evaluate the modulated spectra as the sum of the modulated isotopes spectra (note that without this option only the LIS of the isotope specified in <ExpNameKey> is considered by the script). 
• --PrintLIS  Create a file with the LIS in the format of a two-column plain text file.
• --SimUnit <Tkin/Rigi> force the Output Unit of the module: use Tkin to select Kinetic Energy per Nucleon [GeV/n], use Rigi to select Rigidity [GV]. If not specified, the output is chosen accordingly to the original format of the experimental dataset.
• -o <FILE_NAME> Use a custom name for the output file.

LIS in text format

Users can provide a txt file for LIS with the following characteristics:

• The file must be a text file.
• The file must contain two columns only:
  1. one for kinetic energy per nucleon [GeV]
  2. the second for the LIS flux [ (m² s sr GeV)^-1].
• The file may contain comments. Line starting with '#' character will be ignored.