kingmaker.pdf.KingPDF

class kingmaker.pdf.KingPDF(*, angular_cutoff: float = 3.141592653589793)[source]

Bases: object

Calculate the probability density function (PDF) and cumulative distribution function (CDF) for the King spatial distribution.

This class manages PDF and CDF evaluations with support for angular cutoffs and proper normalization over the sphere.

Parameters:

angular_cutoff (float, optional) – Maximum angular separation in radians. Default is pi (full sphere).

__init__(*, angular_cutoff: float = 3.141592653589793) → None[source]

Methods

__init__(*[, angular_cutoff])

cdf(x, alpha, beta)

Evaluate the normalized King CDF at given angular separation(s).

evaluate(source_ras, source_decs, event_ras, ...)

Evaluate the King PDF for all (event, source) pairs and return a sparse matrix.

norm(alpha, beta)

Compute the normalization constant for given King parameters.

pdf(x, alpha, beta)

Evaluate the normalized King PDF at given angular separation(s).

pdf_from_norm(x, alpha, beta, norm)

Evaluate the King kernel given a precomputed normalization constant.

sample(n, alpha, beta[, rng, n_grid])

Sample angular separations from the King distribution via inverse CDF.
norm(alpha: float | ndarray[tuple[Any, ...], dtype[floating]], beta: float | ndarray[tuple[Any, ...], dtype[floating]]) → float | ndarray[tuple[Any, ...], dtype[floating]][source]

Compute the normalization constant for given King parameters.

Parameters:

  • alpha (float or ndarray) – King distribution alpha parameter (scale) in radians.

  • beta (float or ndarray) – King distribution beta parameter (tail weight).

Returns:

Normalization constant(s) such that PDF integrates to 1.

Return type:

float or ndarray

pdf_from_norm(x: float | ndarray[tuple[Any, ...], dtype[floating]], alpha: float | ndarray[tuple[Any, ...], dtype[floating]], beta: float | ndarray[tuple[Any, ...], dtype[floating]], norm: float | ndarray[tuple[Any, ...], dtype[floating]]) → float | ndarray[tuple[Any, ...], dtype[floating]][source]

Evaluate the King kernel given a precomputed normalization constant.

Computes norm * unnormalized_pdf(x, alpha, beta) directly. No validation of alpha, beta, or x is performed; the caller is responsible for ensuring inputs are in-range.

Parameters:

  • x (float or ndarray) – Angular separation(s) in radians. Must already be <= self.angular_cutoff; this is NOT checked.

  • alpha (float or ndarray) – King distribution alpha parameter (scale) in radians. Must already be > 0; this is NOT checked.

  • beta (float or ndarray) – King distribution beta parameter (tail weight). Must already be > 1; this is NOT checked.

  • norm (float or ndarray) – Precomputed normalization constant(s), e.g. from norm().

Returns:

norm * unnormalized_pdf(x, alpha, beta), broadcast over inputs.

Return type:

float or ndarray

pdf(x: float | ndarray[tuple[Any, ...], dtype[floating]], alpha: float | ndarray[tuple[Any, ...], dtype[floating]], beta: float | ndarray[tuple[Any, ...], dtype[floating]]) → float | ndarray[tuple[Any, ...], dtype[floating]][source]

Evaluate the normalized King PDF at given angular separation(s).

Returns zero for points beyond the angular cutoff. Handles broadcasting of input arrays and masks invalid regions.

Parameters:

  • x (float or ndarray) – Angular separation(s) from the source in radians.

  • alpha (float or ndarray) – King distribution alpha parameter (scale) in radians.

  • beta (float or ndarray) – King distribution beta parameter (tail weight).

Returns:

Normalized PDF value(s) with units of probability/steradian.

Return type:

ndarray

cdf(x: float | ndarray[tuple[Any, ...], dtype[floating]], alpha: float | ndarray[tuple[Any, ...], dtype[floating]], beta: float | ndarray[tuple[Any, ...], dtype[floating]]) → float | ndarray[tuple[Any, ...], dtype[floating]][source]

Evaluate the normalized King CDF at given angular separation(s).

Returns 1 for points beyond the angular cutoff. Handles broadcasting of input arrays and masks invalid regions.

Parameters:

  • x (float or ndarray) – Angular separation(s) from the source in radians.

  • alpha (float or ndarray) – King distribution alpha parameter (scale) in radians.

  • beta (float or ndarray) – King distribution beta parameter (tail weight).

Returns:

Normalized CDF value(s) (cumulative probability).

Return type:

ndarray

sample(n: int, alpha: float, beta: float, rng: Generator | None = None, n_grid: int = 10000) → ndarray[tuple[Any, ...], dtype[floating]][source]

Sample angular separations from the King distribution via inverse CDF.

Parameters:

  • n (int) – Number of samples to draw.

  • alpha (float) – King distribution alpha parameter (scale) in radians.

  • beta (float) – King distribution beta parameter (tail weight).

  • rng (np.random.Generator, optional) – Random number generator. If None, uses np.random.default_rng().

  • n_grid (int, optional) – Number of points in the CDF lookup grid. Higher values give more accurate sampling at the cost of memory and setup time. Default is 10000, which gives ~arcminute accuracy.

Returns:

Angular separations in radians, shape (n,).

Return type:

ndarray

evaluate(source_ras: ndarray[tuple[Any, ...], dtype[floating]], source_decs: ndarray[tuple[Any, ...], dtype[floating]], event_ras: ndarray[tuple[Any, ...], dtype[floating]], event_decs: ndarray[tuple[Any, ...], dtype[floating]], alpha: ndarray[tuple[Any, ...], dtype[floating]], beta: ndarray[tuple[Any, ...], dtype[floating]], *, mask: csr_array | None = None) → csr_array[source]

Evaluate the King PDF for all (event, source) pairs and return a sparse matrix.

On the first call, identifies pairs within angular_cutoff via a declination pre-filter and a full great-circle distance check, then evaluates the King PDF for those pairs. On repeated calls with the same event and source positions, pass the result of a previous call as mask to skip the masking step entirely and go straight to vectorized PDF evaluation using the cached sparsity pattern.

Parameters:

  • source_ras (ndarray, shape (n_sources,)) – Source right ascensions in radians.

  • source_decs (ndarray, shape (n_sources,)) – Source declinations in radians.

  • event_ras (ndarray, shape (n_events,)) – Reconstructed event right ascensions in radians.

  • event_decs (ndarray, shape (n_events,)) – Reconstructed event declinations in radians.

  • alpha (ndarray, shape (n_events,)) – Per-event King alpha parameter in radians.

  • beta (ndarray, shape (n_events,)) – Per-event King beta parameter.

  • mask (csr_array, optional) – Sparse array whose nonzero structure encodes the valid (event, source) pairs. When provided, the angular-distance loop is skipped and only the indexed pairs are evaluated. Pass the result of a previous evaluate() call to reuse the geometry.

Returns:

Sparse array of PDF values, indexed [event_index, source_index].

Return type:

csr_array, shape (n_events, n_sources)