PropPy documentation

PropPy is a novel high-performance software tool to propagate individual charged particles in turbulent magnetic fields via a correlated random walk, while statistically satisfying the particle distribution described by the transport equation. This novel method is superior to diffusive propagation codes for compact objects, such as active galactic nuclei (AGN) blobs, pulsars, and supernovas because of its ability to describe the initial transport correctly. This novel method solves the problem of overestimating particle distributions in outer regions of the objects that exist in diffusion codes. Statistical properties of particles such as distributions, escape times, and running diffusion coefficients are in agreement with ballistic methods within the established propagation code CRPropa, while decreasing the computation time significantly.

Module details:

Source code

The source code is available at: gitlab.ruhr-uni-bochum.de/reichp2y/proppy

Getting started

Installation

Requirements

Usage with Python 3.8 and 3.9 is supported and tested. The packages listed in requirements.txt are needed for PropPy and installed automatically by installing PropPy.

Installing from source
  1. Clone the proppy repository:
    git clone https://gitlab.ruhr-uni-bochum.de/reichp2y/proppy
  2. Move into the project folder and run either 
    pip install .
    or if you do not have pip
    python setup.py install
    Note that you should add --user if you do not have root access.

Example notebooks

  • Start by having a look at the basic simulation setup, where the important modules are introduced and basic simulation setup is shown:

  • Details of the individual modules are in the notebook named detailed simulation setup:

  • If you are already familiar with diffusion coefficients, it is advisable to also try anisotropic diffusion, which occurs due to an ordered magnetic fiel:

  • To get a better feeling of how the code works, you should visualize particle trajectories with a dedicated notebook:

  • Spherical observers are a special type of observers that are useful in many astrophysical environments:

  • A special usecase for spherical observers is studied in more detail in the context of AGN plasmoids:

The software is validated against CRPropa 3.1.7, which is an established code for charged particle propagation and interaction. Note that you have to use the branch CRPropa 3.1.7 with log time observer in order to run the scripts:

Dedicated comparisons are shown in the folder comparison:

Basic example

import numpy as np

import matplotlib.pyplot as plt

import pandas as pd

import proppy as pp

The software is modular. After initializing the simulation, we can add the indvidual modules as needed.

Important modules are:

  • source
  • magnetic field
  • propagator
  • observer

Each module contains special classes for different use cases. In the first tutorial, we only use basic classes to demonstrate the basic usage of the propagation software. In the following tutorials, each module with its special classes will be explained in detail. For example, there exist many different observer types such as time evolution observers (lin or log spacing) and spherical observers. 

sim = pp.Simulation()

Source

First, we have to define a source of particles that we want to propagate. The simples source type is the point source that emits particles isotropically. The only user-specified parameters are:

  • energy: Energy of the particles in eV.
  • source position: The position of the point source.
  • number of particles: Number of particles that should be emitted from this source.

The source can be easily added to the simulation. Afterwards, calling the description on the source of the simulation prints all relevant information and the values of the source parameters.

nr_particles = 10**3

source_pos = np.array([0.0, 0.0, 0.0], dtype=np.float32)

energy = 10**15 # eV


source = pp.PointSourceIsotropicPhi(energy, source_pos, nr_particles)

sim.add_source(source)

sim.source.get_description()

Propagator

Propagates particles via a correlated random walk. The overall behaviour is governed by a generalized telegraph equation.

Here, we use isotropic diffusion for simplicity that propagates particles using a correlated random walk in Cartesian coordinates. Isotropic diffusion is given when the turbulence is isotropic and there is no background field. In the other tutorials also the anisotropic diffusion is used.

The only user-specified parameters for the simple case of isotropic diffusion are:

  • mean-free paths: The mean-free paths λ​ can be derived from the diffusion coefficients κ​ via λ​=3κ​/c. Therefore, the diagonal elements of the diagonalized diffusion tensor are needed to determine the characteristics of the transport. For isotropic diffusion all diffusion coefficients are equal​. Typical free-mean paths of charged particles in plasmoids in AGN jets are 10^12m (see Reichherzer et al. (2021)).
  • number of steps: The number of simulation steps for each individual particle.
  • step size: Size of an individual step. Together with the parameter number of steps, the step size determines the trajectory length of the particles.

The propagator can be easily added to the simulation. Afterwards, calling the description on the propagator of the simulation prints all relevant information and the values of the propagation parameters.

nr_steps = 10**4

step_size = 0.2*10**10 # [m]

diffusion_coefficient = 5*10**18 # [m^2/s]

speed_of_light = 3*10**8 # [m/s]

mfp_iso = 3*diffusion_coefficient/speed_of_light

mfp = np.array([mfp_iso, mfp_iso, mfp_iso], dtype=np.float32)  # [m]


propagator = pp.IsotropicPropagator(mfp, nr_steps, step_size)

sim.add_propagator(propagator)

sim.propagator.get_description()

Observer

The Observer determines during the simulation when and what data to write out (observe).In each simulation step, the current particle state is evaluated by the Observer to check if one of the observing conditions is satisfied. The conditions to observe can be based on the time (-> step) or the coordinates of the particle. The conditions to observe can be based on the time (or step) or the coordinates of the particle.

step number [unique_steps] -> time (TimeEvolutionObservers)radius of observer sphere [shperes] -> sphere around source (SphericalObservers)cartesian coordinates [box_dimensions] -> box around source (BoxObserver) (not yet implemented) All special observer will create an Observer object and specify the relevant parameters for the observation conditions (unique_steps, shperes, box_dimensions)

substeps = [False, False, True] # observe only steps (no substeps)

min_step = 1

max_step = nr_steps

nr_obs_steps = 600


observer = pp.TimeEvolutionObserverLog(min_step, max_step, nr_obs_steps, substeps)


sim.add_observer(observer)

sim.observer.get_description()

Run simulation

sim.run_simulation()
sim.save_data('data/data_tut_1')

Analyze Statistics

As the particles propagate via a random walk, statistical properties of many particles are interesting, such as the diffusion coefficients and particle distributions. These quantities can be compared to analytical predictions. Running diffusion coefficients are computed with the mean-squared displacement method: κ(t) = <Δx²>/2t

df = pd.read_pickle("data/data_tut_1.pkl")

df_time_evolution_observer = df.loc[df['radius'] == -1.0]


sta = pp.Statistics(df_time_evolution_observer)

isotropic = True # diffusion is isotropic

errors = False # don't show error bars

df_kappas = sta.plot_diffusion_coefficients(isotropic, errors, None)

running diffusion coefficient

Scientific usage

In principle, this code is used wherever other propagation codes such as CRPropa, DRAGON, GALPROP are already in use. However, the advantages of PropPy are especially in the good performance and the correct description also of the initial propagation, which is not possible for pure diffusive propagation approaches. Therefore, this code is predestined for the simulation of the particle transport in compact objects, where the initial, ballistic transport phase is often relevant (the importance depends on the scales and the energies).

As an example the propagation of charged particles in blobs of blazar jets is discussed in the following. Due to the high performance and the good statistical description even at early times, the software is excellently suited for the calculation of escape times of charged particles from certain zones (blob in the example), which in turn are required in (semi)analytical calculations. Also particle distributions and arrival times can be simulated efficiently.

Contribution on HEASA 2021 conference: poster

Community guidelines

Contribute

Contributions are always welcome! Please fork the repository and open a new pull request for any new features.

After making changes, your code should pass all unit tests. Code can be tested by invoking

pytest

Using pytest -s shows you further details during the test. Please also add a new unittest for testing your new development if appropriate.

Support

Report issues or problems with the software or seek support by open new issues.

Indices and tables