Low Level Utilities — flaremodel 0.2.0 documentation

# Low Level Utilities

Here, we introduce low level utilities provided with the package to develop variety of models. The functions given here is a bit more picky than normal python functions. In some cases, we note that it is necessary to provide numpy arrays in C contiguous form. We will not discuss the details here, but in case of relevant errors, following can be used:

    arr = np.ascontiguousarray(arr)

## Synchrotron Utilities

We provide two methods to calculate synchrotron emissivity and absorption coefficent:

> - brute (`j_nu_brute()`, `a_nu_brute()`): Numerical computation using built-in electron distributions

> - userdist (`j_nu_userdist()`, `a_nu_userdist()`) Numerical computation from an arbitrary numerical distribution on a grid. It is often better to provide a grid equidistant in logspace.

j_nu_brute(double[::1] nu, double ne, double B, list params, unicode edist, double incang=-1, int steps=50, double gamma_min=1.1, double gamma_max=1e7)

  Numerical calculation of synchrotron emissivity for a given (pre-defined) electron distribution.

  Parameters

    - nu (np.ndarray) – C contiguous 1-D numpy array of frequencies to calculate the coefficient.

    - ne (float) – electron density [1/cm3]

    - B (float) – Magnetic fied [G]

    - params (list) – Set of parameters for the electron distribution

    - edist (str) – Name of the electron distribution

    - incang (float, default=-1) – Inclination angle, -1 for angle averaged [rad]

    - steps (int, default=50) – Steps per decade in gamma for integration

    - gamma_min (float, default=1.1) – Lower limit of gamma range used for integration. If the distribution has the parameters, the value is taken from distribution parameters

    - gamma_max (float, default=1e7) – Same as gamma_min but upper limit

  Returns

    j_nu – Synchrotron emissivity, same size as nu [ergs cm-3 s-1 Hz-1 sr-1]

  Return type

    np.ndarray

a_nu_brute(double[::1] nu, double ne, double B, list params, unicode edist, double incang=-1, int steps=50, double gamma_min=1.1, double gamma_max=1e7)

  Numerical calculation of synchrotron absorption coefficient for a given (pre-defined) electron distribution.

  Parameters

    - nu (np.ndarray) – C contiguous 1-D numpy array of frequencies to calculate the coefficient.

    - ne (float) – electron density [1/cm3]

    - B (float) – Magnetic fied [G]

    - params (list) – Set of parameters for the electron distribution

    - edist (str) – Name of the electron distribution

    - incang (float, default=-1) – Inclination angle, -1 for angle averaged [rad]

    - steps (int, default=50) – Steps per decade in gamma for integration

    - gamma_min (float, default=1.1) – Lower limit of gamma range used for integration. If the distribution has the parameters, the value is taken from distribution parameters

    - gamma_max (float, default=1e7) – Same as gamma_min but upper limit

  Returns

    a_nu – Synchrotron absorption coefficient, same size as nu [cm-1]

  Return type

    np.ndarray

j_nu_userdist(double[::1] nu, double B, double[::1] gamma, double[::1] e_dist, double incang=-1)

  Numerical calculation of synchrotron emissivity for a given numerical electron distribution.

  Parameters

    - nu (np.ndarray) – C contiguous 1-D numpy array of frequencies to calculate the coefficient.

    - B (float) – Magnetic fied [G]

    - gamma (np.ndarray) – C contiguous grid points in gamma for corresponding e_dist

    - e_dist (np.ndarray) – C contiguous grid points for dN/dgamma [cm-3]

    - incang (float, default=-1) – Inclination angle, -1 for angle averaged [rad]

  Returns

    j_nu – Synchrotron emissivity, same size as nu [ergs cm-3 s-1 Hz-1 sr-1]

  Return type

    np.ndarray

a_nu_userdist(double[::1] nu, double B, double[::1] gamma, double[::1] e_dist, double incang=-1)

  Numerical calculation of synchrotron absorption coefficient for a given numerical electron distribution.

  Parameters

    - nu (np.ndarray) – C contiguous 1-D numpy array of frequencies to calculate the coefficient.

    - B (float) – Magnetic fied [G]

    - gamma (np.ndarray) – C contiguous grid points in gamma for corresponding e_dist

    - e_dist (np.ndarray) – C contiguous grid points for dN/dgamma [cm-3]

    - incang (float, default=-1) – Inclination angle, -1 for angle averaged [rad]

  Returns

    a_nu – Synchrotron absorption coefficient, same size as nu [cm-1]

  Return type

    np.ndarray

## Inverse Compton Utilities

Inverse Compton calculations are the most computationally expensive routines by far in this package. Hence, we provide two alternatives; one written in C and parallelized with OpenMP, alternative version targets GPUs with PyOpenCL implementation. Depending on hardware or on a specific problem, one may be more optimal than the other. While the GPU version will thrive on high end hardware, it is hardware agnostic and can be ran on integrated GPUs as well.

compton_emissivity(double[::1] epsilon, double[::1] gamma, double[::1] nu, double[::1] n_ph, double[::1] e_dist)

  Integrates KN cross-section for scattering of n_ph(epsilon) seed photons from electron distribution e_dist(gamma) with frequency nu.

  Parameters

    - epsilon (np.ndarray) – Input incident photon energies, note h*nu [ergs]

    - gamma (np.ndarray) – Gamma of electron distribution

    - nu (np.ndarray) – Requested scattered photon frequencies [Hz]

    - n_ph (np.ndarray) – Photon densities at corresponding epsilons [cm-3]

    - e_dist (np.ndarray) – Electron densities at corresponding gammas [cm-3]

  Returns

    res – Compton emissivity [erg cm-3 Hz-1 sr-1]

  Return type

    np.ndarray

class gComptonEmissivity(*args)

  PyOpenCL implementation of `compton_emissivity()`. Note that this is a class not a function. It needs to be executed as:

      >>> gComptonIntegral(nu, epsilon, gamma)(n_ph, e_dist)

  The reason is to bypass the overhead of compiling OpenCL code and setting up the calculation grid. So, it can be used for repetitive calculations,

      >>> g_compton_emissivity = gComptonEmissivity(nu, epsilon, gamma)
      >>> for i in range(n):
      ...     res_i = g_compton_emissivity(n_ph_i, e_dist_i)

  Parameters

    - nu (np.ndarray) – Requested scattered photon frequencies [Hz]

    - epsilon (np.ndarray) – Input incident photon energies, note h*nu

    - gamma (np.ndarray) – Gamma of electron distribution

  __call__(n_ph, e_dist)
    Parameters

      - n_ph (np.ndarray) – Photon densities at corresponding epsilons

      - e_dist (np.ndarray) – Electron densities at corresponding gammas

    Returns

      res – Compton emissivity [erg s-1 cm-3 sr-1]

    Return type

      np.ndarray

## Temporal Evolution

cool_onestep(double[::1] e_dist, double[::1] gamma, double[::1] e_dist_inj, double B, double R, double dt, double exp_b, double t_esc, double inj_r)

  One step generic temporal evolution function for a “blob”. Adiabatic and synchrotron cooling are included. It is also possible to inject electrons and define an escpace time.

  Note

  This function doesn’t include any sanity check for given `dt`. If it is too fast for given set of parameters, the function will return garbage results without a warning.

  Parameters

    - e_dist (np.ndarray) – 1-D electron distribution to evaluated for the next step (Note: changed in place!)

    - gamma (np.ndarray) – 1-D gamma array same size of e_dist

    - e_dist_inj (np.ndarray) – Normalized 1-D injected electron distribution same size of e_dist

    - B (float) – Magnetic field [G]

    - R (float) – Radius of the blob [cm]

    - dt (float) – Time resolution [s], ie. the function returns the state after dt.

    - exp_b (float) – Expansion speed of the blob [c](speed of light)

    - t_esc (float) – Escape timescale [s]

    - inj_r (float) – Injection rate [e-/s], e_dist_inj multiplied by this.

  Returns

    - B (float) – Updated B after time dt (if exp_b > 0)

    - R (float) – Updated R after time dt (if exp_b > 0)

## Radiative Transfer

ray_tracing(double[:, :, ::1] j_nu, double[:, :, ::1] a_nu, double dx)

  This is a pythonic radiative transfer computation function in the sense that it operates pre-constructed j_nu and a_nu grid. The function expects 3-D arrays. Ray tracing is performed along the last axis. First two axis are reserved for nu and iteration of traces.

  Parameters

    - j_nu (np.ndarray) – 3-D grid of emissivities [erg s-1 cm-3 sr-1 Hz-1]

    - a_nu (np.ndarray) – 3-D grid of absorption coefficienties [cm-1]

    - dx (float) – Distance between each grid point along the traces

  Returns

    I_nu – 3-D array of I_nu [erg s-1 cm-2 sr-1 Hz-1]

  Return type

    np.ndarray