kingmaker.pdf.TemplateSmearedKingPDF

class kingmaker.pdf.TemplateSmearedKingPDF(skymap: ndarray[tuple[Any, ...], dtype[floating]], *, eval_decs: float | ndarray[tuple[Any, ...], dtype[floating]] | None = None, eval_ras: float | ndarray[tuple[Any, ...], dtype[floating]] | None = None, angular_cutoff: float = 3.141592653589793, points_alpha: ndarray[tuple[Any, ...], dtype[floating]] = array([1.00000000e-04, 1.11052098e-04, 1.23325684e-04, 1.36955759e-04, 1.52092243e-04, 1.68901627e-04, 1.87568799e-04, 2.08299086e-04, 2.31320505e-04, 2.56886273e-04, 2.85277595e-04, 3.16806753e-04, 3.51820545e-04, 3.90704095e-04, 4.33885093e-04, 4.81838497e-04, 5.35091759e-04, 5.94230623e-04, 6.59905571e-04, 7.32838980e-04, 8.13833060e-04, 9.03778684e-04, 1.00366519e-03, 1.11459124e-03, 1.23777696e-03, 1.37457728e-03, 1.52649690e-03, 1.69520683e-03, 1.88256274e-03, 2.09062541e-03, 2.32168338e-03, 2.57827809e-03, 2.86323190e-03, 3.17967909e-03, 3.53110033e-03, 3.92136099e-03, 4.35475363e-03, 4.83604526e-03, 5.37052970e-03, 5.96408589e-03, 6.62324249e-03, 7.35524972e-03, 8.16815910e-03, 9.07091202e-03, 1.00734381e-02, 1.11867643e-02, 1.24231364e-02, 1.37961536e-02, 1.53209180e-02, 1.70142008e-02, 1.88946269e-02, 2.09828795e-02, 2.33019278e-02, 2.58772796e-02, 2.87372618e-02, 3.19133321e-02, 3.54404247e-02, 3.93573351e-02, 4.37071462e-02, 4.85377027e-02, 5.39021370e-02, 5.98594538e-02, 6.64751791e-02, 7.38220808e-02, 8.19809693e-02, 9.10415861e-02, 1.01103591e-01, 1.12277659e-01, 1.24686695e-01, 1.38467191e-01, 1.53770720e-01, 1.70765610e-01, 1.89638792e-01, 2.10597856e-01, 2.33873337e-01, 2.59721247e-01, 2.88425893e-01, 3.20303004e-01, 3.55703205e-01, 3.95015871e-01, 4.38673411e-01, 4.87156024e-01, 5.40996984e-01, 6.00788499e-01, 6.67188231e-01, 7.40926526e-01, 8.22814449e-01, 9.13752706e-01, 1.01474155e+00, 1.12689177e+00, 1.25143695e+00, 1.38974699e+00, 1.54334318e+00, 1.71391498e+00, 1.90333854e+00, 2.11369737e+00, 2.34730527e+00, 2.60673174e+00, 2.89483028e+00, 3.21476975e+00]), points_beta: ndarray[tuple[Any, ...], dtype[floating]] = array([1., 1.02353102, 1.04761575, 1.07226722, 1.09749877, 1.12332403, 1.149757, 1.17681195, 1.20450354, 1.23284674, 1.26185688, 1.29154967, 1.32194115, 1.35304777, 1.38488637, 1.41747416, 1.45082878, 1.48496826, 1.51991108, 1.55567614, 1.59228279, 1.62975083, 1.66810054, 1.70735265, 1.7475284, 1.78864953, 1.83073828, 1.87381742, 1.91791026, 1.96304065, 2.009233, 2.05651231, 2.10490414, 2.15443469, 2.20513074, 2.25701972, 2.3101297, 2.36448941, 2.42012826, 2.47707636, 2.53536449, 2.59502421, 2.65608778, 2.71858824, 2.7825594, 2.84803587, 2.91505306, 2.98364724, 3.05385551, 3.12571585, 3.19926714, 3.27454916, 3.35160265, 3.43046929, 3.51119173, 3.59381366, 3.67837977, 3.76493581, 3.85352859, 3.94420606, 4.03701726, 4.1320124, 4.22924287, 4.32876128, 4.43062146, 4.53487851, 4.64158883, 4.75081016, 4.86260158, 4.97702356, 5.09413801, 5.21400829, 5.33669923, 5.46227722, 5.59081018, 5.72236766, 5.85702082, 5.9948425, 6.13590727, 6.28029144, 6.42807312, 6.57933225, 6.73415066, 6.8926121, 7.05480231, 7.22080902, 7.39072203, 7.56463328, 7.74263683, 7.92482898, 8.11130831, 8.30217568, 8.49753436, 8.69749003, 8.90215085, 9.11162756, 9.32603347, 9.54548457, 9.77009957, 10.]), lmax: int | None = None, interpolation_method: str = 'nearest', memory_limit_gb: float = 1.0)[source]

Bases: KingPDF

King PDF convolved with a HEALPix template map using spherical harmonics.

Uses spherical harmonic decomposition to efficiently convolve a King PSF with a template skymap. Pre-computes template harmonics for fast evaluation.

Parameters:

  • skymap (ndarray) – HEALPix map to convolve with King PDF. Will be normalized to integrate to 1.

  • eval_decs (float or ndarray) – Declination(s) in radians where PDF will be evaluated.

  • eval_ras (float or ndarray) – Right ascension(s) in radians where PDF will be evaluated.

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

  • points_alpha (ndarray, optional) – Grid of alpha values for normalization interpolation.

  • points_beta (ndarray, optional) – Grid of beta values for normalization interpolation.

  • lmax (int, optional) – Maximum spherical harmonic degree. Default is 3*nside-1.

  • interpolation_method ({"nearest", "linear"}, optional) – Method used in get_king_b_l to look up b_l coefficients from the precomputed grid. “nearest” (default) snaps to the closest grid point, returning one unique b_l vector per distinct grid cell limiting the number of maps generated and improving efficiency. The “linear” option bilinearly interpolates in log(alpha), log(beta) space.

  • memory_limit_gb (float, optional) – Memory budget in GB for the sph_harm_y_all array allocated in set_coordinates. Points are processed in batches sized so that each batch stays within this limit. Default is 1.0 GB. At nside=256 (lmax=767) each point costs ~9.4 MB, so the default allows ~100 points per batch; at nside=512 (lmax=1535) each point costs ~37.7 MB, so the default allows ~26 points per batch.

__init__(skymap: ndarray[tuple[Any, ...], dtype[floating]], *, eval_decs: float | ndarray[tuple[Any, ...], dtype[floating]] | None = None, eval_ras: float | ndarray[tuple[Any, ...], dtype[floating]] | None = None, angular_cutoff: float = 3.141592653589793, points_alpha: ndarray[tuple[Any, ...], dtype[floating]] = array([1.00000000e-04, 1.11052098e-04, 1.23325684e-04, 1.36955759e-04, 1.52092243e-04, 1.68901627e-04, 1.87568799e-04, 2.08299086e-04, 2.31320505e-04, 2.56886273e-04, 2.85277595e-04, 3.16806753e-04, 3.51820545e-04, 3.90704095e-04, 4.33885093e-04, 4.81838497e-04, 5.35091759e-04, 5.94230623e-04, 6.59905571e-04, 7.32838980e-04, 8.13833060e-04, 9.03778684e-04, 1.00366519e-03, 1.11459124e-03, 1.23777696e-03, 1.37457728e-03, 1.52649690e-03, 1.69520683e-03, 1.88256274e-03, 2.09062541e-03, 2.32168338e-03, 2.57827809e-03, 2.86323190e-03, 3.17967909e-03, 3.53110033e-03, 3.92136099e-03, 4.35475363e-03, 4.83604526e-03, 5.37052970e-03, 5.96408589e-03, 6.62324249e-03, 7.35524972e-03, 8.16815910e-03, 9.07091202e-03, 1.00734381e-02, 1.11867643e-02, 1.24231364e-02, 1.37961536e-02, 1.53209180e-02, 1.70142008e-02, 1.88946269e-02, 2.09828795e-02, 2.33019278e-02, 2.58772796e-02, 2.87372618e-02, 3.19133321e-02, 3.54404247e-02, 3.93573351e-02, 4.37071462e-02, 4.85377027e-02, 5.39021370e-02, 5.98594538e-02, 6.64751791e-02, 7.38220808e-02, 8.19809693e-02, 9.10415861e-02, 1.01103591e-01, 1.12277659e-01, 1.24686695e-01, 1.38467191e-01, 1.53770720e-01, 1.70765610e-01, 1.89638792e-01, 2.10597856e-01, 2.33873337e-01, 2.59721247e-01, 2.88425893e-01, 3.20303004e-01, 3.55703205e-01, 3.95015871e-01, 4.38673411e-01, 4.87156024e-01, 5.40996984e-01, 6.00788499e-01, 6.67188231e-01, 7.40926526e-01, 8.22814449e-01, 9.13752706e-01, 1.01474155e+00, 1.12689177e+00, 1.25143695e+00, 1.38974699e+00, 1.54334318e+00, 1.71391498e+00, 1.90333854e+00, 2.11369737e+00, 2.34730527e+00, 2.60673174e+00, 2.89483028e+00, 3.21476975e+00]), points_beta: ndarray[tuple[Any, ...], dtype[floating]] = array([1., 1.02353102, 1.04761575, 1.07226722, 1.09749877, 1.12332403, 1.149757, 1.17681195, 1.20450354, 1.23284674, 1.26185688, 1.29154967, 1.32194115, 1.35304777, 1.38488637, 1.41747416, 1.45082878, 1.48496826, 1.51991108, 1.55567614, 1.59228279, 1.62975083, 1.66810054, 1.70735265, 1.7475284, 1.78864953, 1.83073828, 1.87381742, 1.91791026, 1.96304065, 2.009233, 2.05651231, 2.10490414, 2.15443469, 2.20513074, 2.25701972, 2.3101297, 2.36448941, 2.42012826, 2.47707636, 2.53536449, 2.59502421, 2.65608778, 2.71858824, 2.7825594, 2.84803587, 2.91505306, 2.98364724, 3.05385551, 3.12571585, 3.19926714, 3.27454916, 3.35160265, 3.43046929, 3.51119173, 3.59381366, 3.67837977, 3.76493581, 3.85352859, 3.94420606, 4.03701726, 4.1320124, 4.22924287, 4.32876128, 4.43062146, 4.53487851, 4.64158883, 4.75081016, 4.86260158, 4.97702356, 5.09413801, 5.21400829, 5.33669923, 5.46227722, 5.59081018, 5.72236766, 5.85702082, 5.9948425, 6.13590727, 6.28029144, 6.42807312, 6.57933225, 6.73415066, 6.8926121, 7.05480231, 7.22080902, 7.39072203, 7.56463328, 7.74263683, 7.92482898, 8.11130831, 8.30217568, 8.49753436, 8.69749003, 8.90215085, 9.11162756, 9.32603347, 9.54548457, 9.77009957, 10.]), lmax: int | None = None, interpolation_method: str = 'nearest', memory_limit_gb: float = 1.0) → None[source]

Methods

__init__(skymap, *[, eval_decs, eval_ras, ...])

cdf(x, alpha, beta)

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

convolve_at_grid_point(alpha, beta)

Evaluate convolved PDF only at pre-set grid points (eval_decs, eval_ras).

convolve_map(alpha, beta)

Convolve the template skymap with a King PSF and return full HEALPix map.

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

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

get_king_b_l(alpha, beta)

Return spherical harmonic expansion coefficients b_l for the King PDF.

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.

precompute_bl_grid()

Precompute b_l coefficients for all (alpha, beta) grid points via matmul.

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

Sample reconstructed positions from the PSF-convolved template skymap.

set_coordinates(eval_decs, eval_ras)

Set evaluation coordinates and pre-compute spherical harmonics.

skymap_to_alm()

Convert the HEALPix skymap to spherical harmonic coefficients.

Attributes

eval_decs

eval_ras

skymap

bl_grid

interpolation_method

eval_decs: ndarray[tuple[Any, ...], dtype[floating]] = array([], dtype=float32)
eval_ras: ndarray[tuple[Any, ...], dtype[floating]] = array([], dtype=float32)
interpolation_method: str
skymap: ndarray[tuple[Any, ...], dtype[floating]]
bl_grid: ndarray[tuple[Any, ...], dtype[floating]]
set_coordinates(eval_decs: float | ndarray[tuple[Any, ...], dtype[floating]], eval_ras: float | ndarray[tuple[Any, ...], dtype[floating]]) → None[source]

Set evaluation coordinates and pre-compute spherical harmonics.

Parameters:

  • eval_decs (float or ndarray) – Declination(s) in radians.

  • eval_ras (float or ndarray) – Right ascension(s) in radians.

skymap_to_alm() → ndarray[tuple[Any, ...], dtype[complexfloating]][source]

Convert the HEALPix skymap to spherical harmonic coefficients.

Returns:

Complex spherical harmonic coefficients a_lm.

Return type:

ndarray

precompute_bl_grid() → ndarray[tuple[Any, ...], dtype[floating]][source]

Precompute b_l coefficients for all (alpha, beta) grid points via matmul.

Evaluates the King PDF over the full (n_alpha, n_beta, n_theta) parameter grid, then computes all b_l integrals in a single matrix multiply. Peak memory scales as O(n_alpha * n_beta * n_theta).

Returns:

Spherical harmonic b_l coefficients for each (alpha, beta) grid point, stored in interpn-ready axis order.

Return type:

ndarray, shape (n_alpha, n_beta, lmax + 1)

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

Return spherical harmonic expansion coefficients b_l for the King PDF.

Looks up b_l values from the precomputed grid (see precompute_bl_grid) using the interpolation method selected at initialization.

“nearest” snaps to the closest (alpha, beta) grid point in log space, so events that fall in the same grid cell reuse the same b_l vector without triggering a new map convolution. “linear” bilinearly interpolates in log(alpha), log(beta) space for smoother variation.

Parameters:

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

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

Returns:

Spherical harmonic coefficients b_l for degrees 0 to lmax.

Return type:

ndarray

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

Convolve the template skymap with a King PSF and return full HEALPix map.

Parameters:

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

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

Returns:

Convolved HEALPix skymap at the same resolution as input.

Return type:

ndarray

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

Evaluate convolved PDF only at pre-set grid points (eval_decs, eval_ras).

Uses pre-computed spherical harmonics from set_coordinates().

Parameters:

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

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

Returns:

Convolved PDF value(s) at evaluation coordinates.

Return type:

float or ndarray

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

Sample reconstructed positions from the PSF-convolved template skymap.

Convolves the template with the King PSF in harmonic space, then draws pixel indices weighted by the convolved map values. This is equivalent to drawing a true position from the template and applying a King PSF offset, but is more efficient because the convolution is done once for the whole map rather than per-event.

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) – Unused. Sampling draws directly from pixel weights of the convolved map.

Returns:

  • reco_ra (ndarray) – Reconstructed right ascension values in radians, shape (n,).

  • reco_dec (ndarray) – Reconstructed declination values in radians, shape (n,).

Notes

Samples land at HEALPix pixel centres. The positional resolution is therefore limited by the skymap pixelisation (~`hp.nside2resol(nside)`).