API Reference

This page documents the public classes and functions, their parameters, and the units and redshift conventions they use. For the physics behind them see Physics Background; for the cooling-time formulae see Models.

Everything lives in the grplinst namespace (C++) or the grplinst module (Python). The umbrella header pulls in all components:

#include <grplinst.h>   // Flow, Medium, Geometry, PlasmaInstability

Architecture at a glance

A typical grplinst run is composed from four ingredients:

  MediumDensity     ──┐
  MediumTemperature  ─┤
  Flow (beam density) ┼──►  PlasmaInstability*  ──►  CRPropa ModuleList
                      │        (a CRPropa Module)
    energy, z      ───┘

All classes derive from CRPropa’s reference-counted Referenced/Module type and are held through crpropa::ref_ptr, so memory is managed automatically.

Class hierarchy:

crpropa::Module
└── PlasmaInstability    (abstract)
    ├── PlasmaInstabilityBroderick2012
    ├── PlasmaInstabilitySironi2014
    ├── PlasmaInstabilitySchlickeiser2012
    ├── PlasmaInstabilityVafin2018
    ├── PlasmaInstabilityBret2010TwoStream
    ├── PlasmaInstabilityBret2010Filamentation
    ├── PlasmaInstabilityShalaby2020
    └── PlasmaInstabilityMiniati2013

crpropa::Referenced
├── Flow                              (abstract)
│   ├── FlowHomogeneous
│   └── FlowJet1D
├── MediumDensity                     (abstract)
│   └── MediumDensityHomogeneous
│   └── MediumDensityGrid
├── MediumTemperature                 (abstract)
│   └── MediumTemperatureHomogeneous
│   └── MediumTemperatureGrid
└── EmissionGeometry                  (abstract)
    └── Cone

PlasmaInstability (base class)

Header: include/grplinst/PlasmaInstability.h. The abstract CRPropa module that applies the effective cooling.

Constructor

PlasmaInstability(ref_ptr<Flow> flow, ref_ptr<MediumDensity> density, ref_ptr<MediumTemperature> temperature, double efficiency = 1.0, double limit = 0.1);

Parameters

Configuration methods

The core method: process(candidate)

For each candidate the base class:

  1. returns immediately unless the particle is an electron or positron;
  2. evaluates the local-frame energy
    \(\quad E = E_\mathrm{obs}(1+z)\)
    and de-redshifted step
    \(\quad \mathrm{d}x \approx \dfrac{\Delta x}{1+z}\);
  3. asks the subclass for the cooling time τ = energyLossTime(candidate);
  4. forms the energy loss per length,
    \(\quad \dfrac{\mathrm{d}E}{\mathrm{d}x} = \eta \, \dfrac{E}{c \tau}\)
    via computeEnergyLossPerLength (returns 0 if \(\tau \le 0\), which safely disables the loss);
  5. updates the energy to
    \(\quad \max \!\left( 0, \, E - \dfrac{\mathrm{d}E}{\mathrm{d}x} \, \Delta x \right)\)
    stored back as
    \(\quad \dfrac{E_\mathrm{new}}{1+z}\);
  6. limits the next step to \(\quad \ell \, E \left( \dfrac{\mathrm{d}E}{\mathrm{d}x} \right)^{-1}\),
    where \(\ell\) is the limit (see setLimit / getLimit).

Virtual interface (implemented by each model)

virtual double energyLossTime(const crpropa::Candidate& candidate) const = 0;

Returns the characteristic cooling time τ in seconds. This is the only method a new prescription must provide. The concrete subclasses are listed in Models.

Flow

Header: include/grplinst/Flow.h. Abstract base describing the pair-beam density.

Key virtual method

virtual double getDensity(double energy, const crpropa::Vector3d& position, double redshift = 0) const = 0;

Returns the beam number density (m⁻³) for a pair of the given energy at position and redshift. (Note the leading energy argument — this distinguishes it from MediumDensity::getDensity.)

Shared configuration

Pre-implemented types

Accessors: setDistanceProfile, setDensityProfile, setInterpolateLog, getDistanceProfile, getDensityProfile.

createFlowMiniati2013

ref_ptr<Flow> createFlowMiniati2013(double luminosity, crpropa::Vector3d centre = {0, 0, 0}, bool logDistance = true);

Builds a FlowJet1D from the 16-point beam-density profile of Miniati & Elyiv (2013), scaled linearly with luminosity / 10³⁸ W. Used internally byPlasmaInstabilityMiniati2013.

MediumDensity

Header: include/grplinst/Medium.h. Abstract base for the ambient plasma density.

virtual double getDensity(const crpropa::Vector3d& position, const double& redshift = 0.) const = 0;

$$$MediumDensityHomogeneous`:

MediumDensityHomogeneous(double density);   // comoving density in m^-3

getDensity returns \(n_0 (1+z)^3\). Accessors: setDensityValue, getDensityValue.

MediumTemperature

Header: include/grplinst/Medium.h. Abstract base for the ambient temperature.

virtual double getTemperature(const crpropa::Vector3d& position, const double& redshift = 0.) const = 0;

// convenience: thermal velocity sqrt(k_B T / m) for particle `id`
double getVelocity(int id, const crpropa::Vector3d& position, const double& redshift = 0) const;

MediumTemperatureHomogeneous

MediumTemperatureHomogeneous(double temperature);   // K

getTemperature returns \(T_0 (1+z)\). Accessors: setTemperatureValue, getTemperatureValue.

Helper functions

double plasmaFrequency(double density, int id = 11);
double maximumLinearGrowthFrequency(double beamDensity, double mediumDensity, double lorentzFactor, int id = 11);

Geometry (infrastructure)

Header: include/grplinst/Geometry.h.

EmissionGeometry (abstract) and its concrete Cone describe an emission region and can compute an area and a volume.

These classes are provided for future emission-geometry calculations and are not used by the instability models; you can ignore them for standard cascade runs.

Constants and units

grplinst uses SI units throughout, consistent with CRPropa. Where CRPropa unit symbols (TeV, Mpc, kpc, eV, …) are available they are used.

Quantity Unit
Energy J internally; CRPropa exposes eV, TeV, … multipliers
Number density (n, n_b) m⁻³
Temperature K
Luminosity W
Length / position m (Mpc, kpc multipliers)
Cooling time τ, frequencies s, Hz

Two module-internal constants worth noting (include/grplinst/Common.h):

Python bindings

The SWIG interface (python/grplinst.i) exposes every public class and function under the grplinst Python module, with a few conveniences: