Distribution functions#

pianistpy.compute_df(), pianistpy.DistributionFunction

compute_df(component) returns the untruncated distribution function of a component as a DistributionFunction. compute_df computes the distribution function by the analytic inversion of the density. compute_df returns the distribution function even where the distribution function is negative or not monotonic, and the result states the energies at which the distribution function is negative or not monotonic. The attribute k_t_min is the lowest truncation energy that truncate accepts. k_t_min is zero when the distribution function is non-negative and non-decreasing everywhere and the model is not a Type II model. One result serves every Method I truncation of the same component, so a scan over truncation energies needs one compute_df call.

halo = pp.Component(pp.DoublePowerLaw.nfw(), pp.Anisotropy(beta_c=0.25))
df = pp.compute_df(halo)

DistributionFunction.from_function(component, f) validates a distribution function from elsewhere, such as a fitting function or the output of another code, with the checks of compute_df:

  • f(k, depth) takes an array of energies \(\mathcal{K}\) in internal units and the array of their depths below the center, \(P_0 - \mathcal{K}\). It returns the distribution function \(F\) at each energy, not its logarithm. The depth carries no rounding error at every energy \(\mathcal{K} \ge 1/2\), so a fit written in the depth near the center can use depth. A function of the energy alone may ignore depth.

  • The function is tabulated on the energy grid that compute_df uses for the same component and settings. The table is then continued beyond its ends, checked for sign and validated against the density, as for compute_df.

  • The function gives \(F\) only, so the validation report marks its check of the table’s logarithmic slope, slope_column, as "not judged".

  • A file written from the result stores the table and the function’s name, not the function.

  • A value that is not finite raises InputError, which states the first such energy.

  • truncate raises InputError for a distribution function from from_function, because a truncation needs values of the inversion that a distribution function from from_function does not carry.

import numpy as np
from scipy.special import beta

# the isotropic Plummer model's DF in closed form, F = A K^(7/2)
plummer = pp.Component(pp.DoublePowerLaw.plummer(), pp.Anisotropy())
amplitude = 3.0 / (4.0 * np.pi * np.sqrt(2.0) * beta(4.5, 1.5))
df = pp.DistributionFunction.from_function(plummer, lambda k, depth: amplitude * k**3.5)

A DistributionFunction holds:

  • the distribution function tabulated on its energy grid, with its logarithmic slope;

  • the asymptotic forms of the distribution function at the center and at the outer end, which continue the distribution function beyond the table;

  • where it is negative or not monotonic, and k_t_min;

  • the inputs and the settings it was computed from;

  • its validation report and its identity string, a digest of the inputs, the settings and the package version.

A result can be written to a file and read back equal (Input and output). Only a Model can be sampled or projected, and truncate builds the model from a distribution function (Truncation in phase space).