pbhstat: A Python Package for Calculating the Primordial Black Hole Abundance

Abstract

We present pbhstat, a publicly available Python package designed to compute the mass function and total abundance of primordial black holes (PBHs) from a given primordial power spectrum. The package offers a modular framework using multiple statistical approaches, including Press–Schechter theory, peaks theory, and formalisms based on the non-linear compaction function. Currently, the implementation is limited to scenarios with nearly Gaussian initial conditions.

1. Introduction

The possibility that dark matter consists of primordial black holes (PBHs) presents an intriguing avenue from both theoretical and observational perspectives [1,2,3,4,5,6,7,8,9,10]. We focus on the case in which PBHs are seeded by large-amplitude inflationary perturbations [11,12,13]. In this context, accurately determining the PBH abundance remains highly sensitive to the interplay between various contributing factors (see [14,15,16] for reviews on the subject). Central to this is the choice of collapse statistics, which relate the probability of black hole formation to the initial conditions and the non-linear dynamics involved. Within a given statistical framework, further ambiguities arise—such as the eventual choice of a window function, the threshold criterion that an estimator must exceed to trigger collapse, and the numerical coefficients used in the computation (inferred, for instance, from numerical simulations [17,18,19]). These elements, whether explicitly chosen or inherently defined by the framework, collectively have a substantial impact on the resulting PBH abundance, e.g., [20,21,22,23,24,25,26]. Furthermore, PBHs are challenging to search for, meaning that theoretical predictions of their mass distribution are valuable in order to better inform and refine observational approaches.

Motivated by this, we present pbhstat as a simple tool that allows for the consistent computation of PBH abundance across different methods for ease of comparison. We aim for this tool to be accessible to non-experts who may not work directly on PBH formation, by providing an easy way to generate PBH mass functions from pre-defined primordial power spectra using consistent statistical formalisms. At the same time, it is designed to support experts in the field, allowing them to input custom power spectra and make detailed choices within various statistical approaches. While many researchers have developed private implementations of these methods, to the best of our knowledge, they have not yet been integrated into a publicly available, unified codebase. We hope that this package will remove the need to re-implement standard techniques and serve as a platform for reproducibility and cross-checks across different approaches.

We implement three choices of statistics to describe how fluctuations collapse to form PBHs. The Press–Schechter theory [27,28] provides a relatively simple method based on the probability that the density contrast exceeds a critical threshold. It usually assumes a Gaussian distribution for the linear overdensity and integrates over all regions above this threshold to estimate the collapse fraction, offering a first-order approximation that is easy to implement. Peaks theory [29] was first applied to the PBH context in the mid-2000s in ref. [30], extending beyond Press–Schechter by modelling PBHs as forming from rare, high peaks in the curvature perturbation field. It is generally considered to be a more accurate description of PBH formation and has been explored and developed extensively in the literature (see, e.g., [20,24,31,32]). Finally, we place particular emphasis on the more involved implementation of the non-linear compaction function statistics [25,33,34]. This approach relies on using the initial conditions of the compaction function as the primary statistical measure. It focuses on identifying regions where the overdensity exhibits a pronounced peak; the compaction function attains its maximum at a characteristic smoothing scale relative to this peak, and this maximum surpasses the critical threshold necessary for the initial overdensity to collapse to form a black hole. We do not delve into the underlying physics of the statistical methodologies used and instead refer the reader to the relevant references for detailed discussions.

Under the assumption of nearly Gaussian initial conditions, all methods depend exclusively on the initial power spectrum. The latter should be motivated by a realisable inflationary scenario; see, e.g., [35] for a review on inflationary mechanisms that lead to PBH production.

Additional effects—such as quantum diffusion [36,37,38,39] and non-Gaussianities [40,41,42,43,44,45,46,47,48,49,50]—may play a crucial role in shaping the final abundance. Nonetheless, even when one adopts the simplifying assumption that the primordial curvature perturbations are Gaussian with a known power spectrum, the present tool provides useful first-order calculations of the mass function, illustrating the number of components that must be taken into account in different statistical approaches. We envisage implementing additional refinements in future versions of the code.

This companion to the code is organised as follows: In Section 2, we outline the main output of the code. In Section 3, we present the three statistical methods for calculating PBH abundance that we implement, along with the primordial power spectra and window functions in Section 4. We lay out the modular structure of the code in Section 5 and provide installation and quick-start usage instructions in Section 6. Finally, we comment on future additions and summarise in Section 7.

2. Output of the Code

The main output of pbhstat is the mass function of primordial black holes $f\left(M\right)$, which represents the fraction of energy density contained in primordial black holes per logarithmic mass interval:

$$f\left(M\right)={\displaystyle \frac{1}{{\Omega }_{\mathrm{CDM}}}}{\displaystyle \frac{d{\Omega }_{\mathrm{PBH}}}{dlnM}}$$

(1)

which satisfies

$$\int f\left(M\right)dlnM=f_{\mathrm{PBH}}\equiv {\Omega }_{\mathrm{PBH}}/{\Omega }_{\mathrm{CDM}},$$

(2)

where M is the mass of the PBH, $f_{\mathrm{PBH}}$ is the fraction of dark matter energy density contained in PBHs today, and ${\Omega }_{\mathrm{CDM}}$ is the energy density in cold dark matter today. Various definitions of the mass function are present in the literature, often simply related to the one above by a rescaling or numerical coefficients.

The PBH abundance today, ${\Omega }_{\mathrm{PBH}}$, can be obtained by integrating the contributions over all scales:

$${\Omega }_{\mathrm{PBH}}=\int dlnR\left({\displaystyle \frac{R_{\mathrm{eq}}}{R}}\right)\beta \left(R\right),$$

(3)

where R is the physical scale of the horizon at the time of formation, which is related to the horizon mass, $M_{\mathrm{H}}$, as follows [51]:

$$R={\left({\displaystyle \frac{M_H}{M_{\mathrm{eq}}}}\right)}^{1/2}{R}_{\mathrm{eq}},$$

(4)

where $\beta \left(R\right)$ is the mass fraction of PBHs at the time of formation, i.e., $\beta ={\rho }_{\mathrm{PBH}}/{\rho }_{\mathrm{tot}}{|}_{\mathrm{formation}}$. The factor ${(M_{\mathrm{eq}}/M_H)}^{1/2}$ scales $\beta$ to its value at matter-radiation equality exploiting the fact that during radiation domination, $\beta \propto {\rho }_{PBH}/{\rho }_R\propto a$, and $a_{\mathrm{eq}}/a\left(M_H\right)={(M_{\mathrm{eq}}/M_H)}^{1/2}$. We use $M_{\mathrm{e}q}=2.8\times {10}^{17}{M}_{\odot }$ and $k_{\mathrm{e}q}=1/R_{\mathrm{e}q}=0.01({\Omega }_m/0.31){\mathrm{Mpc}}^{-1}$, neglecting for simplicity the small correction due to the evolution of the number of relativistic degrees of freedom in Equation (4). In practice, the integral over all scales in Equation (3) will be computed over horizon mass, where it is best to integrate between extrema that correspond to the scales where the primordial power spectrum has decreased by a factor of 10 from its peak amplitude. The implementation of $\beta$ has a different form depending on how the perturbations are assumed to collapse. We provide three methods from the literature for calculating $\beta$ that assume three different statistics, namely Press–Schechter, peaks theory, and non-linear compaction statistics. The key ingredient to $\beta \left(R\right)$ is the primordial power spectrum, which can be either analytically calculated or loaded as a bespoke spectrum in the package. A separate module smooths the power spectrum and calculates the relevant width parameters $\sigma \left(R\right)$ which are fed to $\beta \left(R\right)$ as described in Section 4. To finally arrive at the PBH mass function, one has to invert the expression for the PBH mass in terms of the horizon mass and the statistical estimator chosen (see below).

3. Choice of Statistics

In all three statistics methods, we use the compaction function (in its linear or non-linear version in $\zeta$) as an estimator. The compaction function, denoted with C, measures the mass excess within a given areal radius [52]. In the long-wavelength approximation, and by exploiting the (approximate) spherical symmetry of high peaks in a randomly distributed Gaussian field (in this case, $\zeta$) [29], the time-independent super-horizon compaction function can be written as [53]

$$C\left(R\right)=g\left(R\right)\left(1-{\displaystyle \frac{3}{8}}g\left(R\right)\right),$$

(5)

where

$$g=-{\displaystyle \frac{4}{3}}R{\partial }_R\zeta \left(R\right)$$

(6)

which is sometimes referred to as the linear compaction function.1 Here, $\zeta \left(R\right)$ denotes the radial profile of the comoving curvature perturbation in a coordinate system centred on one of its peaks. The compaction function C on super-horizon scales is bounded from above, with $C\le 2/3$. This bound is reached for $g=4/3$, which separates standard Type I fluctuations ($g\le 4/3$) from more exotic Type II fluctuations ($g>4/3$), with the latter being characterised by a non-monotonic areal radius. The current implementation of the code considers only Type I fluctuations. Critical collapse for Type II fluctuations is currently under investigation—see [54,55,56,57], and a dedicated statistical framework should be developed to properly explore this case. Accordingly, we bound our integral in g to $4/3$. In practice, this consideration is relevant primarily for the non-linear statistics discussed in Section 3.3. For the statistics in Section 3.1 and Section 3.2, the constant threshold is sufficiently far from $4/3$ that Type II fluctuations are naturally excluded.

3.1. Press–Schechter

We implement Press–Schechter statistics in the PressSchechterModel class within the collapse_stats.py module following [58] (and references therein). Note that in the original Press–Schechter formalism for PBHs, the mass fraction is typically expressed as an integral over the density contrast $\delta$, which is assumed to be Gaussian. When the time-independent component of the linear density contrast is averaged over a volume enclosed by a sphere of radius R, it becomes equivalent to the compaction function estimator C (see for instance [59]) on super-horizon scales. This is valid for the linear (in $\zeta$) term of the compaction function, i.e., g, and the linear smoothed density contrast. Using g and adjusting the critical threshold $C_c$ accordingly [58] means that we can write the subsequent expressions in terms of g in place of the original $\delta$.

The form of $\beta$ in terms of the horizon mass (which can be converted from R using Equation (4)) is

$$\beta \left(M_H\right)=2{\int }_{g_c}^{4/3}dg{\displaystyle \frac{M}{M_H}}P\left(g\right)$$

(7)

where $P\left(g\right)$ is the probability distribution function of the initial density perturbations and the upper limit of the integral is a result of excluding Type II fluctuations. Under the Gaussian approximation, this reads as

$$P\left(g\right)={\displaystyle \frac{1}{\sqrt{2\pi {\sigma }^2(M_H})}}exp\left(-{\displaystyle \frac{g^2}{2{\sigma }^2\left(M_H\right)}}\right)$$

(8)

where $\sigma \left(M_H\right)$ is the mass variance, which corresponds to the zero-th width parameter ${\sigma }_0$ in the hierarchy of moments2

$${\sigma }_n^2={\displaystyle \frac{16}{81}}{\int }_0^{\infty }{\displaystyle \frac{dk}{k}}{\left(kR\right)}^{4+2n}{W}^2(k,R){\mathcal{P}}_{\zeta }$$

(9)

where ${\left(kR\right)}^4$ accounts for the super-horizon growth of the density perturbations, described by the dimensionless primordial power spectrum of the comoving curvature perturbation ${\mathcal{P}}_{\zeta }$, defined by $\langle {\zeta }_{\mathbf{k}}{\zeta }_{{\mathbf{k}}^{\prime }}\rangle ={\left(2\pi \right)}^3\delta (\mathbf{k}+{\mathbf{k}}^{\prime })(2{\pi }^2/k^3){\mathcal{P}}_{\zeta }\left(k\right)$, and $W(k,R)$ is a window function chosen to filter the perturbations over the smoothing scale R.

The window functions implemented for use with Press–Schechter are the Gaussian window function3 and the real-space top-hat window function. A real-space top-hat window corresponds to averaging over a sharp spherical region of radius R:

$$W_{\mathrm{TH}}\left(kR\right)=3{\displaystyle \frac{sin\left(kR\right)-kRcos\left(kR\right)}{{\left(kR\right)}^3}}$$

(10)

while the Gaussian window function corresponds to a weighted average over all space, where points closer to the centre are weighted more heavily, and the weight decays exponentially with distance

$$W_{\mathrm{G}}\left(kR\right)=e^{-x^2/4}$$

(11)

where we have defined $x\equiv kR$. From Equation (6), one can show that ${\sigma }_g^2\equiv \langle gg\rangle ={\sigma }_0^2$ [33,34] in Equation (9), with the window function automatically given by the real-space top-hat one.

The critical scaling behaviour of the PBH mass can be written as [60]

$$M=K{M}_H{(g-g_c)}^{{\gamma }_{\mathrm{cr}}},$$

(12)

where K, ${\gamma }_{\mathrm{cr}}$, and $g_c$ are numerical coefficients that should be chosen to be consistent with the smoothing function used to calculate $\sigma \left(M_H\right)$. Standard choices based on fiducial profiles are $\{K=4,g_c=0.77\}$ for the real-space top-hat window function [59] and $\{K=10,g_c=0.28\}$ for the Gaussian window function [32]. These values of $g_c$ are obtained by solving Equation (5) for g with $C=0.55$ for the top-hat, and $C=0.25$ for the Gaussian window functions, respectively, so as to account for the fact that we are using only the linear term of the compaction function [61]. ${\gamma }_{\mathrm{cr}}$ is implemented as an optional argument with a default value of 0.36 in the MassVariance class within the mass_variance.py module. As is customary in these statistics, we do not consider here the profile dependence of the threshold. We note that for the real-space top-hat window function, the integral over $\beta \left(R\right)$ diverges and therefore we implement a large-k cut-off as an optional argument in the MassVariance class, following [58]. This is placed at the point where the window function reaches its first trough, at $k=4.49/R$. This removes the divergence from the integral, but the window function is no longer a true top-hat function.

Combining Equations (7) and (8), and trading the variable g for M by inverting Equation (12), we can write $f\left(M\right)$ as

$$f\left(M\right)={\displaystyle \frac{1}{{\Omega }_{\mathrm{CDM}}}}\int \mathrm{d}{M}_H\sqrt{{\displaystyle \frac{M_{\mathrm{eq}}}{M_H}}}{\displaystyle \frac{{\left(\frac{M}{K{M}_H}\right)}^{1/{\gamma }_{\mathrm{cr}}}}{{\gamma }_{\mathrm{cr}}{M}_H^2}}MP\left(g_{•}\right),$$

(13)

where $g_{•}$ denotes g expressed in terms of the other variables by inverting the critical scaling relation in Equation (12):

$$g_{•}\equiv g(M,M_H)={\left({\displaystyle \frac{M}{K{M}_H}}\right)}^{1/{\gamma }_{\mathrm{cr}}}+g_c.$$

(14)

3.2. Peaks Theory

We implement peaks theory statistics [29,30] in the PeaksTheoryModel class within the collapse_stats.py module in the following way. The mass fraction is given by

$$\beta \left(M_H\right)=b{\int }_{g_c}^{4/3}dg{\displaystyle \frac{M}{M_H}}n\left({\displaystyle \frac{g}{\sigma \left(M_H\right)}}\right)$$

(15)

where b is a pre-factor that accounts for the volume over which the window function is integrated, taking $b=\{{\left(2\pi \right)}^{{\displaystyle \frac{3}{2}}},4\pi /3\}$ for Gaussian and top-hat window functions, respectively [24]. n is the number density of peaks given by

$$n\left(g,M_H\right)={\displaystyle \frac{1}{3^{\frac{3}{2}}{\left(2\pi \right)}^2}}{\left({\displaystyle \frac{{\sigma }_1\left(M_H\right)}{{\sigma }_0\left(M_H\right)}}\right)}^3{\left({\displaystyle \frac{g}{{\sigma }_0\left(M_H\right)}}\right)}^{3}exp\left(-{\displaystyle \frac{1}{2}}{\left({\displaystyle \frac{g}{{\sigma }_0\left(M_H\right)}}\right)}^2\right),$$

(16)

with ${\sigma }_0$ and ${\sigma }_1$ as defined in Equation (9). Note that we have absorbed the usual $R^3$ factor in this equation into the dimensionless expression for ${\sigma }_1$; see Equation (9).

The window functions implemented for use with the PeakTheoryModel are the same as for the PressSchechterModel, namely the Gaussian window function and the real-space top-hat window function. The recommended choices for the numerical coefficients are the same as in the previous Section 3.1. The large-k cut-off flag is also compatible with this statistics choice and can be implemented in the MassVariance class within the mass_variance.py module.

Putting Equations (15) and (16) together with Equation (1), we compute the mass function with [58]

$$f\left(M\right)={\displaystyle \frac{b}{2}}{\displaystyle \frac{1}{{\Omega }_{\mathrm{CDM}}}}{\displaystyle \frac{1}{{\gamma }_{\mathrm{cr}}{K}^{\frac{1}{{\gamma }_{\mathrm{cr}}}}}}\int d{M}_H\sqrt{{\displaystyle \frac{M_{\mathrm{eq}}}{M_{\mathrm{H}}^3}}}{\left({\displaystyle \frac{M}{M_H}}\right)}^{1+{\displaystyle \frac{1}{{\gamma }_{\mathrm{cr}}}}}n\left(g_{•},M_H\right),$$

(17)

where once again $g_{•}$ is given in Equation (14) by inverting the critical scaling relation in Equation (12).

3.3. Non-Linear Compaction Function Statistics

We implement non-linear compaction function statistics [33] in the NonLinearModel class within the collapse_stats.py module. For this method, the estimator for the PBH abundance is the full super-horizon compaction function C in Equation (5). Since PBH formation occurs when the super-horizon C at its maximum ($R=R_m$) exceeds a certain threshold $C_c$ [21], it is useful to introduce the following variables:

$$v=R{g}^{\prime },w=-R^2{g}^{″},$$

(18)

where primes denote derivatives with respect to the comoving radial coordinate R. In the following expressions, these quantities are understood to be evaluated at the maximum of C.

By requiring that these three conditions are satisfied—(i) the overdensity has a peak, (ii) the compaction function reaches a maximum ($v=0$ and $w\ge 0$), and (iii) this maximum exceeds a critical threshold ($g\ge g_c$)—one can rewrite $\beta \left(R\right)$ in the following convenient form [34] (see also [25]):

$$\beta \left(M_H\right)={\displaystyle \frac{2\pi }{3}}{\int }_0^{\infty }dww{\int }_{g_c\left(w\right)}^{4/3}dg{\displaystyle \frac{f\left(\frac{\chi }{{\sigma }_{\chi }}\right)}{{\left(2\pi \right)}^{3/2}(\sqrt{3}{\sigma }_1/{\sigma }_2)}}{\displaystyle \frac{M}{M_H}}P(g,w,v=0),$$

(19)

where $\chi =2g+w$ is the trace of the Hessian at the position of the peak’s centre under the condition $v=0$. It should be noted that, here and in the following, $(g,w)$ are evaluated at the maximum of the compaction function. The explicit form of the function f, arising from condition (i), is given in Equation (A15) of Ref. [29]. The probability distribution function $P(g,w,v=0)$, obtained from the three conditions mentioned above, is given by

$$P(g,w,v=0)=p(v=0)p(g,w)={\displaystyle \frac{1}{\sqrt{2\pi {\sigma }_v^2}}}p(g,w),$$

(20)

where $p(v=0)$ is the (assumed) Gaussian distribution of v evaluated at $v=0$, i.e., the probability of having a peak in the compaction function, multiplied by the conditional joint probability of the other two variables $p(g,w)$. Assuming again for simplicity that primordial fluctuations, and therefore g, are Gaussian, $p(g,w)$ becomes a bi-variate Gaussian distribution for the two correlated variables w and g with an extra correction inherited from imposing the condition $v=0$. We then have (using ${\sigma }_x^2\equiv \langle x^2\rangle$, ${\sigma }_{xy}\equiv \langle xy\rangle$, ${\gamma }_{xy}\equiv {\displaystyle \frac{{\sigma }_{xy}}{{\sigma }_x{\sigma }_y}}$)

$$p(w,g)={\displaystyle \frac{1}{2\pi \sqrt{det\Sigma }}}exp\left(-{\displaystyle \frac{1}{2}}{\overrightarrow{X}}^T{\Sigma }^{-1}\overrightarrow{X}\right),$$

(21)

where

$${\overrightarrow{X}}^T=\left(wg\right),\Sigma =\left(\begin{array}{cc}{\tilde{\sigma }}_w^2& {\tilde{\sigma }}_{wg}^2\\ {\tilde{\sigma }}_{gw}^2& {\tilde{\sigma }}_g^2,\end{array}\right),$$

(22)

with

$$\begin{array}{c}\hfill {\tilde{\sigma }}_g^2={\sigma }_g^2(1-{\gamma }_{vg}^2),{\tilde{\sigma }}_w^2={\sigma }_w^2(1-{\gamma }_{vw}^2),{\tilde{\sigma }}_{wg}^2={\sigma }_{wg}^2-{\displaystyle \frac{{\sigma }_{wv}^2{\sigma }_{vg}^2}{{\sigma }_v^2}}.\end{array}$$

(23)

The probability distribution function can therefore be explicitly written as

$$\begin{array}{cc}\hfill p(g,w)& ={\displaystyle \frac{1}{\sqrt{2\pi {\tilde{\sigma }}_w^2(1-{\tilde{\gamma }}^2)}}}exp\left(-{\displaystyle \frac{{(w-\tilde{\gamma }\frac{{\tilde{\sigma }}_w}{{\tilde{\sigma }}_g}g)}^2}{2{\tilde{\sigma }}_w^2(1-{\tilde{\gamma }}^2)}}\right){\displaystyle \frac{1}{\sqrt{2\pi {\tilde{\sigma }}_g^2}}}exp\left(-{\displaystyle \frac{g^2}{2{\tilde{\sigma }}_g^2}}\right),\hfill \end{array}$$

(24)

or analogously exchanging g with w. $\tilde{\gamma }$, the so-called Pearsol coefficient, tells us the strength of the cross-correlation between the two variables:

$$\tilde{\gamma }={\displaystyle \frac{{\tilde{\sigma }}_{wg}^2}{{\tilde{\sigma }}_w{\tilde{\sigma }}_g}}.$$

(25)

The threshold depends on the shape of the compaction function and is characterised by the function $g_c\left(w\right)$, where the dimensionless curvature of the linear compaction function w parametrises the profile. In the current implementation, we adopt the threshold derived using the “q-approach” [62], which asymptotically approaches $4/3$ for large w, corresponding to sharply peaked compaction function profiles. This method relies on fiducial C profiles expressed in terms of the normalised variable $q\equiv -R^2{C}^{″}/\left[4C(1-\frac{3}{2}C)\right].$ One first inverts the universal threshold on the average compaction function [62,63] to obtain the threshold of the compaction function as a function of q:

$$C_c\left(q\right)={\displaystyle \frac{4}{15}}{e}^{-1/q}{\displaystyle \frac{q^{1-\frac{5}{2q}}}{\Gamma \left(\frac{5}{2q}\right)-\Gamma \left(\frac{5}{2q},\frac{1}{q}\right)}},$$

(26)

where $\Gamma \left(x\right)$ and $\Gamma (x,y)$ denote the Euler gamma function and the upper incomplete gamma function, respectively. Then, to express the threshold as a function of w, one uses the relation4

$$w=-R^2{C}^{″}=4qC\sqrt{1-{\displaystyle \frac{3}{2}}C}.$$

(27)

Evaluating the right-hand side of the previous expression at the threshold $C_c$ and substituting (26), one finds $q\left(w\right)$. Finally, this expression is substituted into the inverted relation for g as a function of C to obtain the threshold for g as a function of w:

$$g_c\left(w\right)={\displaystyle \frac{4}{3}}\left(1-\sqrt{1-{\displaystyle \frac{3}{2}}{C}_c\left(q\left(w\right)\right)}\right).$$

(28)

The steps outlined in Equations (26)–(28) are implemented in the module stats_utils.py to compute $g_c\left(w\right)$.

Within this method, it is customary to express the mass of the PBHs using the critical scaling given in terms of the compaction function as

$$M=\tilde{K}{M}_H{\left[C\left(g\right)-C\left(g_c\left(w\right)\right)\right]}^{{\gamma }_{\mathrm{cr}}}.$$

(29)

The term in parentheses, when expanded around $g_c$, reduces to Equation (12) with a different re-scaled coefficient, which we denote by $\tilde{K}$. The two numerical coefficients are optional arguments in the code, but we choose $K=6$ and critical exponent ${\gamma }_{\mathrm{cr}}=0.36$ as default values [62].

The final abundance depends crucially on the choice of the profile-dependent threshold $g_c\left(w\right)$ and, to some extent, the critical scaling. Both elements are subject to ongoing scrutiny in the literature (e.g., [54,55,56,57]) and can be readily modified within the stats_utils.py module of the code in the future.

By inverting (29) and trading the variable g for M, one can derive the mass function [25]:

$$f\left(M\right)={\displaystyle \frac{2\pi \tilde{K}}{3}}\int dln{M}_H{\int }_0^{\infty }dw{\displaystyle \frac{w{\left(\frac{M}{K{M}_H}\right)}^{\frac{1}{{\gamma }_{\mathrm{cr}}}+1}}{{\gamma }_{\mathrm{cr}}(1-\frac{3}{4}{g}_{•})}}{\left({\displaystyle \frac{M_{\mathrm{eq}}}{M_H}}\right)}^{1/2}P(g_{•},w,v=0){\displaystyle \frac{f\left(\frac{2g_{•}+w}{{\sigma }_{\chi }}\right)}{{\left(2\pi \right)}^{3/2}(\sqrt{3}{\sigma }_1/{\sigma }_2)}}.$$

(30)

Here, $g_{•}$ denotes g evaluated by inverting Equation (29).

For completeness, we report the expressions for the various correlators used in this choice of statistics. All of them can be derived from the definitions of the relevant variables in Equations (6) and (18), the $\sigma$ defined in Equation (9), and the standard expression for the dimensionless primordial power spectrum given just below that equation:

$$\begin{array}{cc}\hfill {\sigma }_g^2& ={\sigma }_0^2,{\sigma }_w^2={\sigma }_2^2-4{\sigma }_1^2+4{\sigma }_0^2,{\sigma }_{\chi }^2={\sigma }_2^2\hfill \\ \hfill {\sigma }_v^2& ={\displaystyle \frac{16}{81}}\int {\displaystyle \frac{dk}{k}}{\left(3xsinx-x^{2}W\left(x\right)\right)}^2{\mathcal{P}}_{\zeta }\hfill \\ \hfill {\sigma }_{vg}& \equiv \langle vg\rangle ={\displaystyle \frac{16}{81}}{\int }_0^{\infty }{\displaystyle \frac{dk}{k}}\left(3xsinx-x^{2}W\left(x\right)\right)W\left(x\right)x^2{\mathcal{P}}_{\zeta }\hfill \\ \hfill {\sigma }_{gw}& ={\displaystyle \frac{16}{81}}{\int }_0^{\infty }{\displaystyle \frac{dk}{k}}\left(x^6-2x^4\right)W^2\left(x\right){\mathcal{P}}_{\zeta }\hfill \\ \hfill {\sigma }_{vw}& ={\displaystyle \frac{16}{81}}{\int }_0^{\infty }{\displaystyle \frac{dk}{k}}\left(3xsinx-x^{2}W\left(x\right)\right)\left(x^4-2x^2\right)W\left(x\right){\mathcal{P}}_{\zeta },\hfill \end{array}$$

(31)

where we have defined $x\equiv kR$. Note that, if one strictly takes as an estimator the orthodox definition of the compaction function C (as in Equation (5)), then W, playing the role of the window function in the formula above, is automatically the real-space top-hat function.

In practice, we choose the range of k-values so that only those corresponding to amplitudes of the primordial power spectrum within a factor of 10 of the peak amplitude are integrated over. In this way, the code determines an effective width of the power spectrum and sets the limits of both w (see [25]) and $M_H\sim R^2\sim k^{-2}$ accordingly. This threshold_factor can be modified from its default value of 0.1 in the collapse_stats.py module. We emphasise that it may be particularly important to test different values if the input power spectrum is especially broad, to ensure convergence of the $\sigma$’s in Equation (31) and to properly account for high values of w.

As already mentioned, if initial non-Gaussianity is assumed to be present, the expressions in this Section 3 have to be corrected with the specific form of non-Gaussianity included (see, e.g., [47,48,49,50]).

4. Power Spectra and Smoothing

We implement both pre-set options for the primordial power spectrum, as well as the possibility for a user-defined primordial power spectrum that can be defined analytically or by uploading an array of ${\mathcal{P}}_{\mathcal{R}}$ along with their corresponding wavenumbers k.

The key pre-set options are piecewise, defined as

$${\mathcal{P}}_{\mathcal{R}}\left(k\right)=\left\{\begin{array}{cc}A{\left({\displaystyle \frac{k}{k_{★}}}\right)}^{n_g},\hfill & \mathrm{if}k\le k_{★}\hfill \\ A{\left({\displaystyle \frac{k}{k_{★}}}\right)}^{-n_d},\hfill & \mathrm{if}k>k_{★}\hfill \end{array}\right.$$

(32)

where A is the amplitude of the peak of the power spectrum, $k_{★}$ is the position of the peak in the power spectrum, $n_g$ is the index of the growing slope and $n_d\ge 0$ is the index of the decaying slope. We also set the minimum amplitude of the power spectrum at any k to be $A=2\times {10}^{-9}$ in order to match CMB observations at large scales. While such small amplitude perturbations will not affect PBH abundance, this setting can be overridden by adjusting the value of min_amplitude in the power_spectrum.py module.

The lognormal power spectrum class is defined by

$${\mathcal{P}}_{\mathcal{R}}\left(k\right)=Aexp\left(-{\displaystyle \frac{1}{2}}{\left({\displaystyle \frac{ln(k/k_{★})}{{\sigma }_{\ln }}}\right)}^2\right)$$

(33)

where A is the amplitude of the peak, $k_{★}$ the position of the peak, and ${\sigma }_{\ln }$ the width of the log-normal distribution. We also implement a delta class by setting ${\sigma }_{\ln }$ to be very small (e.g., 0.001). This produces a very narrow log-normal distribution which can be used to approximate a delta-function and avoids numerical issues with using a true delta-function in the same framework as the rest of the code. We note that this type of power spectrum is unphysical but it is often used for simplicity.

The flat power spectrum class is scale-invariant across the range of scales provided by the user, simply defined with an amplitude A.

These pre-set power spectra aim to capture the key classes of inflationary models in the literature that lead to PBH production. We emphasise that a numerical power spectrum calculated by evolving the equations of motion for the inflaton with a given inflationary potential should be used in order to calculate the precise PBH abundance from specific initial conditions.

Finally, the custom class allows the user to load an array of ${\mathcal{P}}_{\mathcal{R}}$ values that correspond to an array of k-values.

The values of ${\mathcal{P}}_{\mathcal{R}}$ are fed to the MassVariance class. The calculation of the relevant $\sigma \left(R\right)$, depending on the choice of statistics, involves convolving ${\mathcal{P}}_{\mathcal{R}}$ with the chosen window function to find the smoothed power spectrum for Press–Schechter and peaks theory methods, as well as other combinations for the non-linear statistics. These expressions are then integrated over the user-defined k-range such that the output of the MassVariance class is an interpolating function for the relevant $\sigma \left(R\right)$, where the R-range of validity for the interpolators are given by $R=1/k$.

5. Structure of the Code and Installation

The pbhstat package is organised into modular components, each handling a distinct stage of the calculation pipeline outlined above, from reading the initial primordial power spectrum to computing the PBH mass function. The core codebase resides in the src/ directory, structured as follows:

• power_spectrum.py
  Contains the PowerSpectrum class, which defines and evaluates the primordial curvature power spectrum. There are some pre-defined forms for the power spectrum which can be loaded, such as flat and piecewise. It also supports both analytical and tabulated user-defined spectra, which can be implemented directly into the class or loaded as an array. The class then provides interpolation over a user-specified range of wavenumbers k.
• mass_variance.py
  Implements the MassVariance class, which computes the smoothed mass variance ${\sigma }^2\left(R\right)$ over a range of scales, using the power spectrum and a choice of window function. Currently, the Gaussian window function and the real-space top-hat window functions are implemented, with a large-k cut-off optional for the latter.
• collapse_stats.py
  Provides statistical models for PBH formation. It includes classes for the Press–Schechter formalism (PressSchechterModel), peaks theory (PeaksTheoryModel), and for non-linear compaction statistics (NonLinearModel). These classes set up the computation of the mass function of primordial black holes as a function of mass.
• mass_function.py
  Contains the MassFunction class, which wraps around the collapse statistics to compute the differential PBH mass function $f\left(M\right)$ and total abundance $f_{\mathrm{PBH}}$.
• stats_utils.py
  Hosts auxiliary functions used predominantly for the NonLinearkModel class, such as critical threshold calculations, filtering functions, and intermediate formulae that can be pre-computed.
• plot_utils.py
  Provides helper routines for plotting key quantities such as the power spectrum, mass variance, and PBH mass function.
• constants.py
  Stores fiducial values of cosmological quantities that can be edited and will be imported for abundance calculations.

This modular architecture is designed to be user-friendly and easily adaptable with extensions and further refinements as the user sees fit.

6. Usage Instructions

6.1. Installation

To install, it is recommended to create either a Python virtual environment or a conda environment, and then run the following:

• pip install pbhstat

We provide two example jupyter Python notebooks for quick-start examples of how to use the code when installed using pip. Alternatively, download the code from github with

• git clone https://github.com/pipcole/pbhstat.git

• and run

• cd pbhstat
• pip install -e .

• {for an editable install. The required dependencies are numpy, matplotlib, scipy, and tqdm.

The code has been tested with Python version 3.9.15 on an Apple M3 Pro running macOS Sonoma 14.1 and with Python 3.12.3 on a Lenovo Yoga 7 2-in-1 14IML9 running Ubuntu 24.04 LTS as well as with Python version 3.11 in a Google Colab notebook.

6.2. Example Usage

We provide two example Python notebooks with the code release for calculating the mass function and PBH abundance from a custom primordial power spectrum and from a pre-defined piecewise power spectrum. We annotate below the step-by-step code snippets to perform this.

First, import numpy, pickle, or similar if loading own arrays from file and pbhstat, assuming it has been successfully installed with pip. Then, import the relevant classes and functions from the package. Note that the imports will need to be edited if the package is not installed with pip.

Next, define a power spectrum and corresponding k-values. All inverse length units should be in ${\mathrm{Mpc}}^{-1}$. This could be a custom power spectrum either defined analytically, for example,

• or loaded from file:

• which should then be instantiated with

• Alternatively, the power spectrum can be generated from one of the pre-set options, for example, a piecewise power spectrum which can be instantiated directly:

We will now assume that we are using ps_piecewise for the remainder of these instructions. The next step is to instantiate the mass variance (and higher moments) with a choice of window function (realtophat or gaussian) and statistics (press, peaks, or nonlinear). When choosing the real top-hat window function, there is also an option to use the large-k cut-off as described in Section 3.1—the default is False. There are some incompatible choices which will throw an exception, for example, that the non-linear statistics must be chosen together with the real top-hat window function.

Finally, all that is left is to instantiate the mass function class with the same statistics model as the mass variance, and evaluate on a grid of M values, calculating $f_{\mathrm{PBH}}$ as well if desired. Numerical values of K, $g_c$, and $\gamma$ can be defined by the user here as optional arguments when instantiating the mass function class, but recommended values are defaulted to.

Furthermore, correlations with v can be enabled or disabled in the non-linear compaction function statistic using the flag vcorr. By toggling vcorr, the user can assess the impact of consistently accounting for the conditional probability of $v=0$, i.e., the probability of being at an extremum of the compaction function. In particular, setting vcorr=False implies that all $\tilde{\sigma }$ in Equation (23) reduce to their untilde versions. It has been shown analytically in [25] that for a broad spectrum, these correlations are subleading for $R\sim 1/k_{\mathrm{IR}}$, where $k_{\mathrm{IR}}$ is the infrared scale associated with the broad power spectrum.

The number of M values that $f\left(M\right)$ is calculated for can be adjusted from the default 50 with the optional argument mpbh_vals in the mass function evaluate call.

• Key quantities can be plotted using the routines in plot_utils.py.

• We plot a comparison of mass functions for different statistics choices in Figure 1 for a broad log-normal distribution and in Figure 2 for a narrow step function.

In Figure 1, the non-linear compaction function statistics yields a narrower and higher peak toward the infrared part of the spectrum compared to the other two statistical approaches considered. This behaviour has been extensively discussed in Ref. [25], and we adopt the same underlying assumptions here, particularly regarding the threshold criterion. It was shown that for broad power spectra, the mass function is dominated by infrared modes associated with curvature profiles in which the compaction function is sharply peaked (i.e., with large values of w). In the mildly broad log-normal example considered here, these infrared modes produce PBHs that are not-so-heavy due to the suppression implied by the critical scaling relation in Equation (29), namely $M\simeq M_H{w}^{-2{\gamma }_{\mathrm{cr}}}$ for large w, resulting in PBHs with masses significantly below the horizon mass. It is worth noting that while Press–Schechter and peaks theory lead to mass functions with the same shape, their overall amplitudes agree only because we choose the power spectrum amplitudes such that the total PBH abundance for the two cases are comparable. If instead the same value for the power spectrum amplitude is used for both methods, there is a difference of 2–3 orders of magnitude in the resulting PBH abundance as demonstrated in, e.g., ref. [64]. In Figure 2, as a benchmark for a narrow spectrum, we use a top-hat profile with width $k_{\mathrm{UV}}/k_{\mathrm{IR}}=1.3$. For such narrow spectra, all statistics prefer the same comoving scale, namely $r\sim 2.74/k_p$, which corresponds to the first maximum of ${\sigma }_g^2$. The difference in the position of the main peak in the resulting mass function arises from the different choices of threshold and overall normalisation in the critical scaling relation. Specifically, we adopt the same parameters for Press–Schechter and peaks theory (see Section 3), namely $(K,g_c)=(4, 0.77)$. For the non-linear compaction function statistics, we instead choose $\tilde{K}=6$, and for a narrow spectrum, $g_c\simeq 0.91$ [25].

In the case of a monochromatic power spectrum, all methods produce mass functions that are nearly identical in shape because the statistical profile of the various estimators is essentially fixed. In contrast, for broader spectra, the situation becomes significantly more complex due to the influence of different statistical realisations. This influence is more relevant for the non-linear compaction function statistics, where one scans over different realisations of the curvature of the compaction function. Furthermore, the dependence on the threshold on w provides a way to account for the influence of UV modes on IR modes. Whether this approach is sufficient is still under investigation. In contrast, for the other two statistics, this effect is incorporated by imposing an artificial cut-off at $k\sim 4.49/R$ (see discussion in Section 3.1). These are the sources of the discrepancy behind the different curves in Figure 1. As stated in the introduction, the present tool introduced in this work is also intended to explore differences between distinct statistical approaches that remain under active investigation in the literature.

Finally, we provide a simple interface so that mass functions can be overlaid with the observational constraints available in the PBHbounds repository [65], available here: https://github.com/bradkav/PBHbounds/ (accessed on 3 July 2025). Arrays of $f\left(M\right)$ and corresponding M values can be saved to the directory in which PBHbounds is located with

• Then, a modified version of the default script PlotPBHbounds.py is available at https://github.com/pipcole/pbhstat (accessed on 3 July 2025) to be run in the directory of PBHbounds. This will overplot the mass function produced with pbhstat with the bounds (that can be specified via the command line, if not all bounds are desired) from PBHbounds. We emphasise that the constraints themselves depend on the form of the mass function, and therefore overlaying broad mass functions with monochromatic PBH constraints is inconsistent. We recommend that this utility should only be used for narrow mass functions, and in any case as an approximate guide. See [66] for a method for converting constraints from monochromatic to extended mass functions.

7. Summary and Outlook

pbhstat is a simple, user-friendly tool for computing the mass function of primordial black holes from an initial primordial power spectrum. Given the many sensitivities of this calculation to the choice of power spectrum, window function, numerical coefficients, and statistics that describe the collapse of the perturbations, we aim to provide a community tool that enables easy comparisons. Furthermore, we hope it will be useful for researchers who are non-experts on primordial black holes, who need a reasonable PBH mass function to input into their pipelines for calculating, e.g., observational constraints from pulsar timing arrays [67,68] or microlensing experiments [69,70]. The code could also provide a supporting tool for future and ongoing efforts toward a complete framework for computing gravitational wave signatures from PBHs, as is in progress within the LISA Cosmology Working Group.

The current version of the code includes the three statistical methods briefly outlined in Section 3 and assumes that the comoving curvature perturbation follows an approximately Gaussian distribution. We would like, in the future, to add the ability to deal with additional complications such as the softening of the equation of state during the QCD phase transition [71,72,73] (relevant for $\sim M_{\odot }$ black holes) and non-Gaussianity [40,41,42,43,44,45,46,47,48,49,50,74] as well as keeping the package up to date with theoretical advances as they are established. We welcome feedback and suggestions at https://github.com/pipcole/pbhstat (accessed on 3 July 2025).