How to create and use custom photon fields

Concept

The idea of custom photon fields is to vastly extend CRPropa's applicability to astrophysical environments where the CMB and IRB photon fields do not sufficiently describe the circumstances at hand. This includes almost all local energetic sources such as accretion discs, jets and supernovae to name a few.

As sources show highly individual behaviour one cannot anticipate each kind of photon field in beforehand, hence the properties of a photon field shall be customizable by the user. Photon fields in CRPropa follow three basic principles:

A photon field may

1. show any behaviour in dependence of energy and redshift (even in non-equidistant spacings)
2. assume any geometrical shape and/or evolution in time
3. be modified in a brick-like manner after CRPropa has been installed

---

Photon Fields: Definitions and Connections

A photon field in CRPropa is represented by a file that encodes the differential photon field density ρ given in 1/eVcm^3 in dependence of the photon energy ε in eV and redshift z. The differential energy density is equal to the photon field's energy density (given in energy per volume) divided by the square of the photon energy, i.e. ρ = energy density / energy^2. The photon field file has to meet a specific format to be understood by CRPropa's modules:

• line 1: n photon energies of the field where it is defined, in ascending order: ε1, ε2, ..., εn
• line 2: m redshift values where the photon field is defined, in ascending order: z1, z2, ..., zm
• line 3: field density at ε1 in redshift-order: ρ(ε1, z1), ρ(ε1, z2), ..., ρ(ε1, zm)
• line 4: field density at ε2 in redshift-order: ρ(ε2, z1), ρ(ε2, z2), ..., ρ(ε2, zm)
• ...
• line n+2: field density at εn in redshift-order: ρ(εn, z1), ρ(εn, z2), ..., ρ(εn, zm)

Furthermore, any line in a photon field file starting with a hashtag # is being ignored. Note that there may be 8 custom photon fields at once which are required to be named PF1, PF2, ... or PF8. The photon field file has then to be put in the ~/share/crpropa/scaling directory.

CRPropa requires several tabulated relating to the photon field files to handle interactions which are located at ~/share/crpropa/. Modules making use of such tabulated files are ElasticScattering, ElectronPairProduction, EMDoublePairProduction, EMInverseComptonScattering, EMPairProduction, EMTripletPairProduction, PhotoDisintegration and PhotoPionProduction. Once a correctly formatted photon field file is at hand, all tabulated data files relating to that photon field can be produced by a helper file called generate_tabFiles.py. This file automatically generates all tabulated data files needed by all interaction modules and adds puts them into their intended folders if used correctly. This file requires two arguments, being 1) the path to the photon field file and 2) the directory where CRPropa stores tabulated data.

That's it! Now we can include the new photon field in our simulation.

Example

step 1: The slot PF1 is to be filled with a custom photon field. This photon field be defined at the energies ε = [0.1, 2.34, 56] at redshifts z = [0, 1.23, 4, 5.6]. The field's differential energy density ρ shall scale according to ρ(ε,z)=ε^2*exp(-z). The corresponding photon field file PF1 thus looks like

and has to be stored in ~/CRPropa/share/crpropa/scaling.

step 2: Assuming that your CRPropa e.g. is installed at /home/user/CRPropa/, this photon field file may now be processed via generate_tabFiles.py "/home/user/CRPropa/share/crpropa/scaling/PF1.txt" "/home/user/CRPropa/share/crpropa/".

PF1 may now be included into the simulation, e.g. by sim.add(PhotoDisintegration(PF1)). If you wish to change the properties of PF1 just create a new photon field file called PF1.txt and create its tabulated files.