=== .bins file ===

The main goal of AtRIS is to calculate how particles of given energy are stopped within a certain atmosphere (how deep they penetrate). In other words, for a particle with an initial energy $E$, we determine how much energy on average the particle losses in each atmospheric sheet. In addition, AtRIS calculates what is the typical contribution to the {{https://en.wikipedia.org/wiki/Absorbed_dose|Absorbed dose}} in each atmospheric sheet. 

These results are best summarized in form of a pair of two dimensional histograms:
  * average ion production rate in (ions/ccm/s), shown over a grid of altitude Vs. input energy
  * average absorbed dose the particle would impinge on an {{https://www.iaea.org/ns/tutorials/regcontrol/intro/glossaryi.htm|ICRU spherical phantom}}, shown over a grid of altitude Vs. input energy

Technically, this has been achieved using Geant4's {{https://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/Analysis/managers.html|csv analysis library}}. However, the author wanted to give the user explicit control over the energy binning. Therefor, the user has to provide a file containing the energy bins which are going to be used for the creation of the specified histograms. This file has a simple structure:

   * Each line corresponds to a single binedge
   * The binedges specify the energy in MeV
   * No header lines are allowed
   * Use floating point format

{{atris:proxcen.bins|Here}} you can find an example file.

=== .diff file ===

The summarizes how average effects of energetic particles in atmospheres are obtained and stored. In a real world, we are  not interested what on average a single particle does, but instead we want to know what effect a certain particle flux produces. The authors provide several python scripts which take as input a differential flux and fold the ionization rate matrices in such a way to determine:
  * the net ionization in the atmosphere for each atmospheric sheet
  * the net average absorbed dose for each atmospheric sheet

Using the .diff file we specify the differential particle flux. Here are some facts about the format:
   * Each line corresponds to an (Energy, differential flux) point
   * Energies are specified in MeV
   * Differential fluxes are specified in particles/(cm^2 s sr MeV)
   * If you are using a time integrated flux, make sure to divide by  the interval duration in seconds
   * Header lines start with "#"
   * Number of header lines is unlimited
   * You should describe the source of the data, the duration of the event and similar relevant infos
   * The number of lines of data must be exactly one less then the number of binedges in the .bins file
   * Each energy must lie somewhere within the corresponding bin

Note that the .bins and .diff file are interrelated. Typical, one will start with a .diff file and produce with this a .bins file. This requires careful consideration on how the original data has been derived. We give below one particular example generated using python+numpy. 
<code>
import numpy as np
diff = np.loadspec('proxcen.diff')         # we load the data
binwidths = (diff[1:]-diff[:-1])*0.5       # we calculate the bin widths
bins      = [diff[0]-binwidths[0]]         # We add the first binedge, since
for k in range(binwidths.shape[0]):        # it is special. Now we can do a for loop
    bins.append(diff[k]+binwidths[k])      # We add the remaining binedges
np.savetxt('proxcen.bins',bins,fmt=".4f")  # We save the data
</code>

In this particular approach, we have defined the .diff energies to be "running mids" of energy bins. How you define your bins depends on how your differential spectrum data has been obtained. Feel free to experiment! The above {{atris:proxcen.bins|.bins}} has been generated using this code from this {{atris:proxcen.diff|.diff}} file example[(Note that the example has three columns. The second and the third column both describe differential fluxes. In this particular case one represents an upper limit, while the other represents a lower limit. We have implemented in to our analysis scripts the possibility to specify the index of the differential flux column which should be used, making easy switching possible.)]. 


=== Folding the .diff to obtain .spec ====

We can now see a further interdependence of two files :
  * To perform a folding procedure of the 2d histograms, we need to know how many particles belong to each energy bin.
  * The differential flux has to be integrated to obtain this.

~~REFNOTES~~