In this project, the AtRIS toolkit is used for the simulation of Galactic Cosmic Ray (GCR) particles traversing the Martian atmosphere.

Note: This example project and processing scripts written in python programming language are provided by Lennart Röstel. Feel free to contact me under lennart.roestel@gmx.de.

After cloning the official AtRIS repositoryhttps://gitlab.physik.uni-kiel.de/banjac/atris and following the installation guide, you will need to

1. Clone or download the Mars example repository: https://gitlab.physik.uni-kiel.de/roestel/atris-mars-example-project to obtain the python scripts and example files.
2. Move the AtRIS executable into the Mars example directory. The executable is usually just named “AtRIS”.
3. Test your installation by opening a new console and typing:

python Mars.py 1 4 50

This start the python script Mars.py dedicated to setting up the required simulation files and starting multiple AtRIS processes. The command line arguments are:

• The charge of the incoming particle ion (1 for hydrogen in this case)
• The number of processes to be run in parallel
• The number of particles to be simulated per input energy bin

Open Mars.py and see how multiple AtRIS processes are set up. Feel free to adapt this script to match your own purposes.

If everything went well, the simulation starts and the monitor bash script opens. After about 20 seconds, it should look something like this: If the simulation doesn't start correctly, have a look into the .error, .log and .out output files to find out what the problem is. Note that due to the way the INCLXX geant4 physics list works, the script will display warnings saying: “maximum number of tries exceeded for the proposed XXX. Will resample.” You can ignore those warnings.

The script estimates the time it takes for the simulation to finish. With the above parameters, it will probably take up to a few hours, depending on your machine. Now you can either wait for the processes to finish or cancel the simulations by closing the monitor script (and restart with lower number of particles) if you don't want to wait. In the following, I will assume that you have a finished simulation.

You can use the reset.sh script to clean up your working directory, in the case you want to get rid of the output files of previous simulations. Just do ./reset.sh from your working directory to delete all data outputs.

We can now look at the output files produced by AtRIS. The Mars.py script assigns a random number to each AtRIS process (4 in this case). Each AtRIS process wrote a set of the following data products into the directory you started the simulations in:

• .dose file
• .dose2 file
• .equi file
• .equi2 file
• .binary file
• ioni file
• _h1_h1.1.csv file
• _h2_h2.dir.csv file
• _h2_h2.dos.csv file
• _h2_h2.dos2.csv file
• _h2_h2.equi.csv file
• _h2_h2.equi2.csv file
• _h2_h2.ion.csv file
• _h2_h2.pos.csv file

In this example, we will only deal with the 5 five data output types.

These files contain the absobed dose in the first (.dose) and second (dose2) phantoms.

These files contain the “equivalent dose” in the first (.dose) and second (dose2) phantoms. It is calculated by applying radiation weighting factors as defined in ICRP report 116 http://radon-and-life.narod.ru/pub/ICRP_116.pdf

Each time a particle crosses the interface between two sheets (SDID), AtRIS saves out a set of information about that particle to the .binary files. In this file, each of these event comprises the following information:

• PDG specifying the particle species (see http://pdg.lbl.gov/2007/reviews/montecarlorpp.pdf)

(signed) int - 4 bytes

• next SDID specifies the Sensitive Detector ID of the detector in to which the particle is entering.

usigned short - 2 bytes

• Angle is the angle between the position vector and the direction vector

unsigned short - 2 bytes

• Kinetic energy of the particle at the interface.

float - 4 bytes

• Kinetic energy of the primary particle.

float - 4 bytes

In order to retrieve the desired information, such as the particle fluxes, from the .binary data product,the following processing steps are suggested:

Filter the .binary file for the needed particle type using the filter.cc program supplied in the repository (written by Sasha Banjac). The script combines the output of multiple AtRIS threads and creates a new file containing the filtered entries only. Therefore compile using g++ and make the program executable:

g++ filter.cc -o filter
chmod +x filter

Execute ./filter for information on usage. Now, to filter e.g. for protons (PDG 2212) in sheet interface 50, do

./filter MarsH1 2212 50

In the first argument, the simulation name was specified. Note that the script appended an “H1” for Hydrogen primary to the filenames.

In the repository, you can also find a file named filterMult.cc. This is similar to filter.cc, however, it filters for all particles relevant for dose contribution at once (e.g. it goes through the binary data only once and places several files in the working directory, one for each combination of particle type and layer.) The syntax of executing is:

./filterMult MarsH1 IDMin IDMax

where IDmin and IDmax are the minimal and maximal layers to be considered. When filtering for different kinds of particles, this script can drastically reduce your processing time.

A file named MarsH1.2212_50 was created. It is still in binary format. To convert this file to ascii format, you can use the python script atrisTools.py supplied in the repository. Open a new python session or your favorite python IDE.

import atrisTools as at #import the atris conversion class
at.convert2asci("MarsH1.2212_50") #convert the Mars.2212_50 binary to ascii format

Two new files have been placed in your working directory: MarsH1.2212_50_dn.asci and MarsH1.2212_50_up.asci. As the names suggest, the entries have been filtered for upward (<90°) and downward (>90°) directed particles. The next step is to create a 2d histogram over input (primary) and output (secondary) energies. You can do this by

at.createMatrixXY("MarsH1.2212_50_dn.asci", "Mars.bins","Mars.bins")

where the first parameter is the input energy bin file and the second parameter is the output energy bin file (we'll use the same file in this case). The 2d histogram we created has now to be normalized and scaled to the actual number of particles in a given GCR flux. More on this is following, meanwhile, have a look into atrisTools.py to see how.

In general, at least two types of input files are needed for starting any AtRIS simulation:

• A .gdml file, specifying the planetary geometry, number of layers (detectors), composition, density etc.
• A .mac file, specifying the phantoms to be used for dose calculation, the particle source, type and number of primary particles, energy bins, etc.

In the repository, there is a script Mars.py, which generates a mac file for each AtRIS process using the genMacro function. Please have a look inside this script and modify it to fit your needs. The main lines you always want to adapt to your application are: 1.

/atris/setPhantomFilename icru_b_response.txt 
/atris/setPhantomMass 14.094755 kg
/atris/setPhantomSurface 2827.433 cm2
/atris/setPhantom2Filename radb_response.txt
/atris/setPhantom2Mass 0.13394 g
/atris/setPhantom2Surface 383.25 mm2

Here we specify the filename of the phantom response functions to be used for dose calculation and set the mass and surface area of the phantoms (for the purpose of internal dose calculation).

2.

/gps/particle ion 
/gps/ion Z A Q

Use the geant4 general particle source to specify the type of primary particle to be used. In this case we are shooting on with ions of atmic number Z, mass number A and charge Q.

3.

lines += "/gps/ene/type User\n"
lines += "/gps/hist/type energy\n"
bins   = np.loadtxt(name+'.bins')
lines += "/gps/hist/point %.9f %.9f\n"%(bins[0],0.0) 
for thebin in bins[1:]:
lines += "/gps/hist/point %.9f %.9f\n"%(thebin,1.0)

This section sets our energy binning for the primary particles. It reads in a .bins file and prints one line for each bin edge to the .mac file. After the energy in MeV, the probability of a particle to be generated within this bin (taking the respective energy as upper bin edge) is set to 1.0 for all bins. This means that in this case we are simulating approximately equal numbers of particles per energy bin.

4.

/gps/pos/radius 3471.2 km

Set the radius of the particle source sphere. This is usually to be set to the outer edge of the planetary atmosphere, but beneath the loss volume.

5.

/gps/ang/type cos
/gps/ang/mintheta 0 deg
/gps/ang/maxtheta 90 deg

We set the distribution of the emission angel to follow a cos-law distribution, since we want to achieve an isotropic flux inside the source sphere. Furthermore, we restrict the emission angle to 0deg to 90deg, effectively generating particles only inwards from the source sphere. This is usually not to be modified.

6.

/run/setCut 100. m

Set geant4 cutValues for e-, e+ and gamma particles, please refer to the geant4 documentation for more information on that.

7.

/random/setSeeds nr1 nr2

Set the seeds for the monte carlo simualtion. Make sure to use different seeds for each processes to be run in parallel!

8.

/run/beamOn N

Set the total number of particles to be simulated.

The .gdml file type is native to geant4 and is quite complex for people just wanting to do a quick simulation. Because in principle, our simulation setup only consists of a number of spherical, concentric shells with different compositions, the Planet Specification Format (PSF) was developed for the use with AtRIS. This very much simplifies the process of creating the desired planetary simulation setup. We can use the Interface to the Mars Climate Database (MCD) to easily create such a psf for any given location at any given time of the year at Mars. Then, we just need to convert this psf file to a .gdml using the psf2gdml.py script provided in the repository. The repository contains both a .psf and a .gdml file as example references.