Modifications

October 2013
Updated CRT Howto.


CRT HOWTO

Hopefully this page will provide you with some information you need to efficiently use CRT. If you have any questions please contact us.


CRT Overview

Method

CRT uses Runge-Kutta integration methods to determine the trajectory of a charged particle through specified magnetic fields models. Particles are created by a specified type of source at some location (Earth, galactic (G), or extra-galactic (EXG)), injected at some energy, and followed until an end criterium is satisfied. Particle can be forward- or back-tracked from G or EXG sources, or backtracked from Earth. Backtracking is accomplished by following the anti-particle (changing the sign of the charge and initial velocity vector). Energy losses are NOT tracked during propagation (Check back for updates which may include this functionality).

Dependences

CRT's only dependencies are GSL (for random number generation) and FFTW (for Fourier Transformation libraries).

Default Values

The chosen convention for uninitialized parameters or irrelevant output values (for example, observed latitude for an UNOBSERVED particle) is the value (-999).

Coordinate Systems

The Galactic coordinate system is used when referring to directions in the sky. There are two Cartesian coordinate systems used: one defined exclusively within the magnetic field model (Field System) and is used to define the paramterizations of the Symmetric Spiral field models, and another everywhere else within the program (System A).

System A is defined as follows:
  • The x-hat unit vector points towards the Galactic center (Gal long., Gal lat.)=(0, 0)
  • The y-hat unit vector points towards (Gal long., Gal lat.)=(90degrees, 0)
  • The z-hat unit vector point towards the Galactic North Pole (Gal long., Gal lat.)=(0, 90degrees)
 Field Systems are defined only within the field strength calculations. If a user wishes to add a new field using a different coordinate system they must implement the new coordinate system.


Runtime Arguments

All option flags are set at runtime and include:
  • infile - specifies name and location of file containing source/field lists. REQUIRED!!
  • seed - random number seed, default time(NULL)
  • detR - size of detector, when backtracking, this flag sets injection disk radius at Earth. Units given in [kpc], default 0.1
  • tmax - maximum distance of particle propagation, units [year], default 1e6
  • tstep - size of timesteps during propagation, units [year], default 10
  • err - magnitude of truncation error during integration steps, default 1e-8
  • ofile - output file, default to standard output.
 The only required option is 'infile'. All others have default values. The absolute minimum program call is:

$ ./CRT infile=FULLPATHTOINPUTFILE

The following illustrates how to use each option:

seed=1 -rk5 -rk853 -backtrack detR=0.5 tmax=1000 tstep=0.1 err=0.0034 infile=/home/myinput.file ofile=/home/myoutput.file


Option Flags

Options are accessed by prepending - to the option name. Example:
-myoption
sets the flag myoption to TRUE.
All option flags are set at runtime and include:
  • rk5 - select the Stepperdopr5 method from Num.Rec.,default FALSE
  • rk853 - select the Stepperdopr853 method, default TRUE
  • backtrack - sets injection site at Earth and tracks antiparticles to 20kpc galactocentric distance. This affects the ENTIRE simulation. default FALSE. If you plan on backtracking particles, it is important that you use this flag;
    DO NOT ACTUALLY SET THE PARTICLE CHARGE TO ITS NEGATIVE IN THE INPUT FILE!!!!


Input

Overview

A certain format is defined for reading a file containing a list of source types and magnetic field configurations. Comments in the input file are defined as lines starting with a #. Since the particle only 'feels' the total magnetic field, the program will add together any individual field components that the user specifies. A wide variety of sources can be generated, including multi-component sources (proton plus iron, for example). The order in which fields and sources does not matter, as long as each declaration is complete. The units for each option can be found in the full page on the Input File Format. The delimiter between lines is a CARRIAGE RETURN on the system in which CRT was compiled. Example input format follows below.

Sources

  • isotropic:
    I NPSRC CRSHIFT CRINDEX EMIN EMAX PMASS PCHARGE
  • isotropic-mono-plaw-auger:
    X NPSRC CRSHIFT CRINDEX EMIN EMAX PMASS PCHARGE
  • point:
    P NPSRC CRSHIFT CRINDEX EMIN EMAX D LONG LAT BEAMANGLE PMASS PCHARGE
  • long:
    L NPSRC CRSHIFT ENERGY STARTANGLE PMASS PCHARGE
  • long-mono-plaw-auger:
    Y NPSRC CRSHIFT ENERGY STARTANGLE PMASS PCHARGE
  • lat:
    B NPSRC CRSHIFT ENERGY STARTANGLE PMASS PCHARGE
  • lat-mono-plaw-auger:
    Z NPSRC CRSHIFT ENERGY STARTANGLE PMASS PCHARGE
  • CR:
    C ENERGY LONG LAT PMASS PCHARGE
  • ArbTraj:
    A ENERGY PX PY PZ VX VY VZ PMASS PCHARGE
  • EGsrc:
    E NPSRC CRSHIFT CRINDEX EMIN EMAX D LONG LAT BRAND LCORR LEG PMASS PCHARGE
  • isotropic-broken-plaw:
    BPI NPSRC CRSHIFT INDEX0 INDEX1 EBREAK EMIN EMAX PMASS PCHARGE
  • isotropic-broken-plaw-auger (backtrk and Auger exposure):
    BPX NPSRC CRSHIFT INDEX0 INDEX1 EBREAK EMIN EMAX PMASS PCHARGE

MAGNETIC FIELDS

  • ASS_A:
    F ass_a model NORM PITCH SCALE1 SCALE2 SCALE3 SCALE4 ZCUT
  • ASS_S:
    F ass_s model NORM PITCH SCALE1 SCALE2 SCALE3 SCALE4 ZCUT
  • BSS_A:
    F bss_a model NORM PITCH SCALE1 SCALE2 SCALE3 SCALE4 ZCUT
  • BSS_S:
    F bss_s model NORM PITCH SCALE1 SCALE2 SCALE3 SCALE4 ZCUT
  • UNIFORM:
    F uniform BX BY BZ
  • DIPOLE:
    F dipole NORM
  • SIMRNDM:
    F simprand norm corrlen sigmalen sigmanorm
  • RING:
    F ring NORM INNEREDGE OUTEREDGE SCALE5
  • TOROID:
    F toroidal TORRAD SCALE6 LORWIDTH BMAX


Output

Overview

Comments in the output file are defined as lines starting with a #. The header information can be found at the beginning of the output file, it describes the parameters used during the run. The final #-line labels the columns of data to be output after propagation. Regardless of detection, every column is filled for every particle. The delimiter between columns is a TAB (\t). The delimiter between lines is a CARRIAGE RETURN on the system in which CRT was compiled.

Data Columns

  • Src Num- refers to source identification
  • CR Energy- energy of particle in units of EeV
  • Src.Long.- in case of forwardtracking, Galactic longitude of source. In case of backtracking, projected longitude of source based on final velocity direction of particle
  • Src.Lat.- in case of forwardtracking, Galactic latitude of source. In case of backtracking, projected latitude of source based on final velocity direction of particle
  • EXG [XYZ]coor.- in case of forwardtracking, [xyz]-coordinate of particle's initial position. In case of backtracking, final [xyz]-coordinate of particle's position
  • Hit- hit status for particle. In case of backtracking, this is ALWAYS 1
  • Obs.Long.- in case of forwardtracking, projected observed longitude based on direction of particle's velocity at 'time of hit'. If the particle is NOT observed, this defaults to (-999). In case of backtracking, this is the longitude of the observed event or initial injection direction
  • Obs.Lat.- in case of forwardtracking, projected observed latitude based on direction of particle's velocity at 'time of hit'. If the particle is NOT observed, this defaults to (-999). In case of backtracking, this is the latitude of the observed event or initial injection direction
  • Ang.Sep.- when a particle is 'observed', this is the space angle between Src Long/Lat and Obs Long/Lat. In case of NO hit, this defaults to (-999)
  • Imp. Angle- if the event is a hit, then this is set to (90)
  • Imp. Param.- the impact parameter regardless of hit status or tracking method
  • Particle Mass - mass of the particle in units of proton mass
  • Particle Charge - charge of the particle in units of proton charge
  • Evt. Number - the total event number of the event within the simulation
  • Earth [XYZ]coor. - in case of forward-tracking, the [xyz]-coordinate of the particle when detected. In case of backtracking, [xyz]-coordinate of the injection site
  • Event Quality - a flag for indicating the exit status and state of the particle

SAMPLE HEADER

# Run command:
# RNGseed: 0
# 1 srcs, 10 total events, detector size=0.1kpc
# I 10 0.01 -2.7 3 200 1 1 1
#
# F bss_s stanev 2 -10 10.55 1 1 4 0.5
# F bss_s hmr 2 -10 10.55 2 0.3 4 1
#
# (x,y,z) refers to: backtracking-> final coordinates, forwardtracking-> injection site
# Src Num CR Energy[EeV] Src.Long.[deg] Src.Lat.[deg] EXG Xcoor. [kpc] EXG Ycoor. [kpc] EXG Zcoor. [kpc] Hit(1=Y,0=N) Obs.Long.[deg] Obs.Lat.[deg] Ang.Sep.[deg] Imp. Angle[deg] Imp. Param.[kpc] Particle Mass Particle Charge Evt.Number Earth Xcoor. [kpc] Earth XYoor. [kpc] Earth Zcoor. [kpc] Event Quality