4. Inside USINE (c++)

This section provide an overview of the code structure and organisation. A detailed description of each class content (members and role in the USINE ecology) is given in the header files (include/TU*.h).

4.1. Classes

Fig. 4.1 is a sketch of all USINE classes, grouped by items to underline the most relevant features of the code:

  • CR physics (blue box, top): classes for CR base ingredients, with CR charts, data, and cross-sections set from input files — see USINE input files.
  • USINE utilities (grey box, bottom): the most important class is TUValsTXYZCrE.h, a handler for formula (or values on a grid) dependent on generic CR, energy, and space-time coordinates — see Tutorial: ./bin/usine. The dashed arrows indicate the classes involved and where it is used (for transport, ISM description, and source parameters).
  • Models (orange box, right-hand side): dedicated classes for Galactic propagation and Solar modulation models.
  • Initialisation parameters (red box, left-hand side): class reading the parameter file (see Initialisation file) to set and initialise all classes for a run.
  • Free parameters (red box, centre): class handling all fit-able parameters. Red arrows connecting red boxes highlight classes with free parameters (spatial coordinates, XS, ISM, transport, sources, Solar modulation) — see Fit parameters and minimizer for the syntax.

Fig. 4.1 Organisation chart of USINE classes.

4.2. Inheritance diagrams

Two important classes in USINE largely rely on inheritance: Fig. 4.2 and Fig. 4.3 below were obtained with Doxygen (enabling graphviz).


Fig. 4.2 Inheritance diagram for propagation models.

Structure of propagation model classes (class TUModelBase.h):
→ inherit from
  • CR list (charts/properties) and energy ‘axis’
  • Propagation switches (effects switched on or off)
  • CR data
  • List of data on which to normalise primary fluxes
  • CR source templates (to be used as CR sources)
  • Cross-sections (inelastic, production, etc.)
  • List of free parameters for the model
→ have members for
  • Transport parameters
  • ISM description
  • Source description
  • All other free parameters (model and ingredients)
Structure of free parameters (class TUInitPars.h):

if existing, the free parameters of a class are stored in a TUFreeParList object. They are themselves collected in a global list of free parameters. This allows a very simple declaration of the parameters the user wishes to let free in a minimisation (see Fit parameters and minimizer)


Fig. 4.3 Inheritance diagram for free parameters.

4.3. Enumerators

USINE relies on many enumerators. Most of these enumerators are for developers only, but some of them are relevant for users as well, as given in Table 4.1. The complete list of enumerators is defined in $USINE/include/TUEnum.h.

Table 4.1 Enumerators to use in the arguments (of ./bin/usine) and/or initialisation file.
Enumerator Description Enabled
gENUM_ETYPE Energy unit/type for data and plots kEKN, kR, kETOT, kEK for kinetic energy per nucleon [GeV/n], rigidity [GV], total energy [GeV], and kinetic energy [GeV]
gENUM_ERRTYPE Handling of data errors kERRSTAT, kERRSYST, kERRTOT, kERRCOV for statistical, systematics, total (stat+syst in quadrature), or covariance
gENUM_FCNTYPE Parametrisation kFORMULA, kGRID for a formula or a grid of values
gENUM_PROPAG_MODEL Propagation models kMODEL0DLEAKYBOX, kMODEL1DKISOVC, kMODEL2DKISOVC for Leaky-Box, 1D, or 2D semi-analytical diffusion model
gENUM_SOLMOD_MODEL Solar modulation models kSOLMOD0DFF for Force-Field approximation

4.4. Coding conventions

If ever you want to have a look at the code, or develop some new modules, it may be useful to know that USINE relies loosely on the coding conventions used in ROOT. In addition, we use the following syntax:

  • lower_case_underscore_separated \(\rightarrow\) local variables
  • UpperCaseSeparated \(\rightarrow\) method names
  • gUPPERCASE \(\rightarrow\) global variables
  • kUPPERCASE \(\rightarrow\) enumerators (see list of enumerators above)

To ensure homogeneity in the indentation throughout USINE sources (*.cc files), we use astyle and the ROOT/CERN style obtained by copying the lines below in ~/.astylerc:

# ROOT code formatting style