Skip to content

Core (low-level)

The C++ core, exposed as delta._core and re-exported at the top level. These are the building blocks the high-level pipeline orchestrates — basis evaluation, convolution, the penalized GLS solver, thin-plate splines, stamp detection, noise decorrelation, and FITS I/O.

Advanced

Most users should use the high-level pipeline instead. These functions are documented for advanced use and for understanding the internals. Signatures and docstrings are sourced from the _core.pyi type stub. The compiled _core.subtract is re-exported as delta.subtract_model to avoid colliding with the high-level delta.subtract.

Basis & convolution

gauss_hermite_basis1d 

gauss_hermite_basis1d(
    beta: float, n_max: int, radius: int = ...
) -> NDArray[float64]

1-D sampled Gauss-Hermite basis functions, shape (n_max+1, ksize).

Source code in python/delta/_core.pyi 
138
139
def gauss_hermite_basis1d(beta: float, n_max: int, radius: int = ...) -> NDArray[np.float64]:
    """1-D sampled Gauss-Hermite basis functions, shape (n_max+1, ksize)."""

gauss_hermite_kernels 

gauss_hermite_kernels(
    beta: float, n_max: int, radius: int = ...
) -> tuple[NDArray[int32], NDArray[float32]]

(orders, kernels) for the 2-D Gauss-Hermite components.

Source code in python/delta/_core.pyi 
141
142
143
144
def gauss_hermite_kernels(
    beta: float, n_max: int, radius: int = ...
) -> tuple[NDArray[np.int32], NDArray[np.float32]]:
    """(orders, kernels) for the 2-D Gauss-Hermite components."""

basis_convolve 

basis_convolve(
    image: NDArray[float32],
    beta: float,
    n_max: int,
    radius: int = ...,
) -> NDArray[float32]

Convolve image with each basis component; returns (ncomp, H, W).

Source code in python/delta/_core.pyi 
146
147
148
149
def basis_convolve(
    image: NDArray[np.float32], beta: float, n_max: int, radius: int = ...
) -> NDArray[np.float32]:
    """Convolve image with each basis component; returns (ncomp, H, W)."""

Spatial model (thin-plate splines)

grid_knots 

grid_knots(
    x0: float,
    y0: float,
    x1: float,
    y1: float,
    nx: int,
    ny: int,
) -> NDArray[float64]

Regular nxny grid of knots over [x0,x1]x[y0,y1], shape (nxny, 2).

Source code in python/delta/_core.pyi 
211
212
def grid_knots(x0: float, y0: float, x1: float, y1: float, nx: int, ny: int) -> NDArray[np.float64]:
    """Regular nx*ny grid of knots over [x0,x1]x[y0,y1], shape (nx*ny, 2)."""

tps_design 

tps_design(
    knots: NDArray[float64], points: NDArray[float64]
) -> NDArray[float64]

Thin-plate regression-spline design matrix, shape (m, n_basis).

Source code in python/delta/_core.pyi 
214
215
def tps_design(knots: NDArray[np.float64], points: NDArray[np.float64]) -> NDArray[np.float64]:
    """Thin-plate regression-spline design matrix, shape (m, n_basis)."""

tps_penalty 

tps_penalty(knots: NDArray[float64]) -> NDArray[float64]

Thin-plate bending-energy penalty, shape (n_basis, n_basis).

Source code in python/delta/_core.pyi 
217
218
def tps_penalty(knots: NDArray[np.float64]) -> NDArray[np.float64]:
    """Thin-plate bending-energy penalty, shape (n_basis, n_basis)."""

tps_fit 

tps_fit(
    knots: NDArray[float64],
    points: NDArray[float64],
    values: NDArray[float64],
    lam: float,
) -> NDArray[float64]

Unweighted penalised fit: (D^T D + lam P) theta = D^T values.

Source code in python/delta/_core.pyi 
220
221
222
223
224
225
226
def tps_fit(
    knots: NDArray[np.float64],
    points: NDArray[np.float64],
    values: NDArray[np.float64],
    lam: float,
) -> NDArray[np.float64]:
    """Unweighted penalised fit: (D^T D + lam P) theta = D^T values."""

tps_evaluate 

tps_evaluate(
    knots: NDArray[float64],
    points: NDArray[float64],
    coeffs: NDArray[float64],
) -> NDArray[float64]

Evaluate a fitted TPS field at points: design(points) @ coeffs.

Source code in python/delta/_core.pyi 
228
229
230
231
232
233
def tps_evaluate(
    knots: NDArray[np.float64],
    points: NDArray[np.float64],
    coeffs: NDArray[np.float64],
) -> NDArray[np.float64]:
    """Evaluate a fitted TPS field at points: design(points) @ coeffs."""

Solver

solve_gls 

solve_gls(
    knots: NDArray[float64],
    points: NDArray[float64],
    target: NDArray[float64],
    weights: NDArray[float64],
    bn: NDArray[float64],
    lam: float,
) -> GlsResult

Penalised GLS at fixed lambda over the factorized A&L model.

Source code in python/delta/_core.pyi 
235
236
237
238
239
240
241
242
243
def solve_gls(
    knots: NDArray[np.float64],
    points: NDArray[np.float64],
    target: NDArray[np.float64],
    weights: NDArray[np.float64],
    bn: NDArray[np.float64],
    lam: float,
) -> GlsResult:
    """Penalised GLS at fixed lambda over the factorized A&L model."""

solve_gls_gcv 

solve_gls_gcv(
    knots: NDArray[float64],
    points: NDArray[float64],
    target: NDArray[float64],
    weights: NDArray[float64],
    bn: NDArray[float64],
    lambda_grid: NDArray[float64],
) -> GlsResult

Penalised GLS selecting lambda by GCV over lambda_grid.

Source code in python/delta/_core.pyi 
245
246
247
248
249
250
251
252
253
def solve_gls_gcv(
    knots: NDArray[np.float64],
    points: NDArray[np.float64],
    target: NDArray[np.float64],
    weights: NDArray[np.float64],
    bn: NDArray[np.float64],
    lambda_grid: NDArray[np.float64],
) -> GlsResult:
    """Penalised GLS selecting lambda by GCV over lambda_grid."""

solve_gls_cv 

solve_gls_cv(
    knots: NDArray[float64],
    points: NDArray[float64],
    target: NDArray[float64],
    weights: NDArray[float64],
    bn: NDArray[float64],
    lambda_grid: NDArray[float64],
    group: NDArray[int32],
    n_groups: int,
) -> GlsResult

Penalised GLS selecting lambda by k-fold group cross-validation.

Source code in python/delta/_core.pyi 
255
256
257
258
259
260
261
262
263
264
265
def solve_gls_cv(
    knots: NDArray[np.float64],
    points: NDArray[np.float64],
    target: NDArray[np.float64],
    weights: NDArray[np.float64],
    bn: NDArray[np.float64],
    lambda_grid: NDArray[np.float64],
    group: NDArray[np.int32],
    n_groups: int,
) -> GlsResult:
    """Penalised GLS selecting lambda by k-fold group cross-validation."""

weighted_mean 

weighted_mean(
    data: NDArray[float32],
    variance: NDArray[float32],
    mask: NDArray[uint8],
) -> float

Inverse-variance weighted mean over unmasked pixels.

Source code in python/delta/_core.pyi 
116
117
118
119
120
121
def weighted_mean(
    data: NDArray[np.float32],
    variance: NDArray[np.float32],
    mask: NDArray[np.uint8],
) -> float:
    """Inverse-variance weighted mean over unmasked pixels."""

Detection & stamps

detect_stamps 

detect_stamps(
    data: NDArray[float32],
    mask: NDArray[uint8] | None = ...,
    stamp_radius: int = ...,
    threshold_sigma: float = ...,
    max_stamps: int = ...,
    saturation: float = ...,
    isolation_radius: int = ...,
    border: int = ...,
    fwhm_radius: int = ...,
    match_radius: int = ...,
) -> DetectedStamps

Detect bright, isolated, unsaturated point-source stamps.

Source code in python/delta/_core.pyi 
156
157
158
159
160
161
162
163
164
165
166
167
168
def detect_stamps(
    data: NDArray[np.float32],
    mask: NDArray[np.uint8] | None = ...,
    stamp_radius: int = ...,
    threshold_sigma: float = ...,
    max_stamps: int = ...,
    saturation: float = ...,
    isolation_radius: int = ...,
    border: int = ...,
    fwhm_radius: int = ...,
    match_radius: int = ...,
) -> DetectedStamps:
    """Detect bright, isolated, unsaturated point-source stamps."""

select_stamps 

select_stamps(
    science: NDArray[float32],
    reference: NDArray[float32],
    science_mask: NDArray[uint8] | None = ...,
    reference_mask: NDArray[uint8] | None = ...,
    catalog_x: NDArray[int32] | None = ...,
    catalog_y: NDArray[int32] | None = ...,
    stamp_radius: int = ...,
    threshold_sigma: float = ...,
    max_stamps: int = ...,
    saturation: float = ...,
    isolation_radius: int = ...,
    border: int = ...,
    fwhm_radius: int = ...,
    match_radius: int = ...,
) -> StampSelection

Select matched stamps across both images and the convolution direction.

Source code in python/delta/_core.pyi 
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
def select_stamps(
    science: NDArray[np.float32],
    reference: NDArray[np.float32],
    science_mask: NDArray[np.uint8] | None = ...,
    reference_mask: NDArray[np.uint8] | None = ...,
    catalog_x: NDArray[np.int32] | None = ...,
    catalog_y: NDArray[np.int32] | None = ...,
    stamp_radius: int = ...,
    threshold_sigma: float = ...,
    max_stamps: int = ...,
    saturation: float = ...,
    isolation_radius: int = ...,
    border: int = ...,
    fwhm_radius: int = ...,
    match_radius: int = ...,
) -> StampSelection:
    """Select matched stamps across both images and the convolution direction."""

Fit & subtract

fit_kernel 

fit_kernel(
    science: NDArray[float32],
    reference: NDArray[float32],
    knots: NDArray[float64],
    stamp_x: NDArray[int32],
    stamp_y: NDArray[int32],
    stamp_radius: int,
    beta: float,
    n_max: int,
    lambda_grid: NDArray[float64],
    radius: int = ...,
    clip_sigma: float = ...,
    clip_iterations: int = ...,
    min_stamps: int = ...,
    cv_folds: int = ...,
    science_var: NDArray[float32] | None = ...,
    reference_var: NDArray[float32] | None = ...,
    science_mask: NDArray[uint8] | None = ...,
    reference_mask: NDArray[uint8] | None = ...,
) -> KernelFit

Fit the matching kernel + background via penalised GLS with per-stamp sigma clipping. The returned dict adds reduced_chi2, n_stamps_total/used/ rejected and per-stamp stamp_x/stamp_y/stamp_chi2/stamp_accepted.

Source code in python/delta/_core.pyi 
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
def fit_kernel(
    science: NDArray[np.float32],
    reference: NDArray[np.float32],
    knots: NDArray[np.float64],
    stamp_x: NDArray[np.int32],
    stamp_y: NDArray[np.int32],
    stamp_radius: int,
    beta: float,
    n_max: int,
    lambda_grid: NDArray[np.float64],
    radius: int = ...,
    clip_sigma: float = ...,
    clip_iterations: int = ...,
    min_stamps: int = ...,
    cv_folds: int = ...,
    science_var: NDArray[np.float32] | None = ...,
    reference_var: NDArray[np.float32] | None = ...,
    science_mask: NDArray[np.uint8] | None = ...,
    reference_mask: NDArray[np.uint8] | None = ...,
) -> KernelFit:
    """Fit the matching kernel + background via penalised GLS with per-stamp
    sigma clipping. The returned dict adds reduced_chi2, n_stamps_total/used/
    rejected and per-stamp stamp_x/stamp_y/stamp_chi2/stamp_accepted."""

subtract 

subtract(
    science: NDArray[float32],
    reference: NDArray[float32],
    knots: NDArray[float64],
    theta: NDArray[float64],
    beta: float,
    n_max: int,
    radius: int = ...,
    saturation: float = ...,
    science_var: NDArray[float32] | None = ...,
    reference_var: NDArray[float32] | None = ...,
    science_mask: NDArray[uint8] | None = ...,
    reference_mask: NDArray[uint8] | None = ...,
) -> DiffProducts

Full-frame spatially-varying subtraction with variance/mask propagation; saturation>0 masks and grows bright/saturated cores.

Source code in python/delta/_core.pyi 
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
def subtract(
    science: NDArray[np.float32],
    reference: NDArray[np.float32],
    knots: NDArray[np.float64],
    theta: NDArray[np.float64],
    beta: float,
    n_max: int,
    radius: int = ...,
    saturation: float = ...,
    science_var: NDArray[np.float32] | None = ...,
    reference_var: NDArray[np.float32] | None = ...,
    science_mask: NDArray[np.uint8] | None = ...,
    reference_mask: NDArray[np.uint8] | None = ...,
) -> DiffProducts:
    """Full-frame spatially-varying subtraction with variance/mask propagation;
    saturation>0 masks and grows bright/saturated cores."""

photometric_scale 

photometric_scale(
    knots: NDArray[float64],
    theta: NDArray[float64],
    component_sums: NDArray[float64],
    height: int,
    width: int,
) -> NDArray[float32]

Per-pixel photometric scale field sum_n a_n(x,y) S_n, shape (H, W).

Source code in python/delta/_core.pyi 
308
309
310
311
312
313
314
315
def photometric_scale(
    knots: NDArray[np.float64],
    theta: NDArray[np.float64],
    component_sums: NDArray[np.float64],
    height: int,
    width: int,
) -> NDArray[np.float32]:
    """Per-pixel photometric scale field sum_n a_n(x,y) S_n, shape (H, W)."""

photometric_scale_at 

photometric_scale_at(
    knots: NDArray[float64],
    theta: NDArray[float64],
    component_sums: NDArray[float64],
    points: NDArray[float64],
) -> NDArray[float64]

Photometric scale evaluated at points, shape (m,).

Source code in python/delta/_core.pyi 
317
318
319
320
321
322
323
def photometric_scale_at(
    knots: NDArray[np.float64],
    theta: NDArray[np.float64],
    component_sums: NDArray[np.float64],
    points: NDArray[np.float64],
) -> NDArray[np.float64]:
    """Photometric scale evaluated at points, shape (m,)."""

estimate_background 

estimate_background(
    data: NDArray[float32],
    mask: NDArray[uint8] | None = ...,
) -> tuple[float, float]

Robust (median, MAD-sigma) background over unmasked pixels.

Source code in python/delta/_core.pyi 
151
152
153
154
def estimate_background(
    data: NDArray[np.float32], mask: NDArray[np.uint8] | None = ...
) -> tuple[float, float]:
    """Robust (median, MAD-sigma) background over unmasked pixels."""

Noise: decorrelation & scoring

decorrelation_kernel 

decorrelation_kernel(
    kernel: NDArray[float32],
    var_science: float,
    var_reference: float,
    n: int,
) -> NDArray[float32]

Real-space decorrelation kernel (centred, n x n) for QA.

Source code in python/delta/_core.pyi 
333
334
335
336
337
338
339
def decorrelation_kernel(
    kernel: NDArray[np.float32],
    var_science: float,
    var_reference: float,
    n: int,
) -> NDArray[np.float32]:
    """Real-space decorrelation kernel (centred, n x n) for QA."""

decorrelate_block 

decorrelate_block(
    image: NDArray[float32],
    kernel: NDArray[float32],
    var_science: float,
    var_reference: float,
) -> NDArray[float32]

Whiten one square block with a constant kernel/noise (FFT core).

Source code in python/delta/_core.pyi 
325
326
327
328
329
330
331
def decorrelate_block(
    image: NDArray[np.float32],
    kernel: NDArray[np.float32],
    var_science: float,
    var_reference: float,
) -> NDArray[np.float32]:
    """Whiten one square block with a constant kernel/noise (FFT core)."""

decorrelate 

decorrelate(
    difference: NDArray[float32],
    knots: NDArray[float64],
    theta: NDArray[float64],
    beta: float,
    n_max: int,
    var_science: NDArray[float32],
    var_reference: NDArray[float32],
    block: int = ...,
    radius: int = ...,
    kernel_cell_blocks: int = ...,
) -> DecorrelateResult

Spatially-varying noise decorrelation via apodized FFT blocks.

Returns {'difference', 'variance'} where variance is the post-whitening noise level (for pulls and the match-filtered score).

Source code in python/delta/_core.pyi 
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
def decorrelate(
    difference: NDArray[np.float32],
    knots: NDArray[np.float64],
    theta: NDArray[np.float64],
    beta: float,
    n_max: int,
    var_science: NDArray[np.float32],
    var_reference: NDArray[np.float32],
    block: int = ...,
    radius: int = ...,
    kernel_cell_blocks: int = ...,
) -> DecorrelateResult:
    """Spatially-varying noise decorrelation via apodized FFT blocks.

    Returns ``{'difference', 'variance'}`` where ``variance`` is the
    post-whitening noise level (for pulls and the match-filtered score).
    """

matched_filter 

matched_filter(
    image: NDArray[float32],
    psf: NDArray[float32],
    variance: NDArray[float32],
) -> NDArray[float32]

Match-filtered score image (per-pixel S/N map). variance must be a same-shape float32 image of per-pixel noise variance.

Source code in python/delta/_core.pyi 
380
381
382
383
384
385
386
def matched_filter(
    image: NDArray[np.float32],
    psf: NDArray[np.float32],
    variance: NDArray[np.float32],
) -> NDArray[np.float32]:
    """Match-filtered score image (per-pixel S/N map). variance must be a
    same-shape float32 image of per-pixel noise variance."""

FITS I/O

read_fits 

read_fits(path: str) -> FitsLayers

Read a FITS file into {'data', 'variance', 'mask'} arrays.

Source code in python/delta/_core.pyi 
123
124
def read_fits(path: str) -> FitsLayers:
    """Read a FITS file into {'data', 'variance', 'mask'} arrays."""

write_fits 

write_fits(
    path: str,
    data: NDArray[float32],
    variance: NDArray[float32] | None = ...,
    mask: NDArray[uint8] | None = ...,
    overwrite: bool = ...,
) -> None

Write data plus optional variance/mask layers to a FITS file.

Raises if the file exists unless overwrite=True.

Source code in python/delta/_core.pyi 
126
127
128
129
130
131
132
133
134
135
136
def write_fits(
    path: str,
    data: NDArray[np.float32],
    variance: NDArray[np.float32] | None = ...,
    mask: NDArray[np.uint8] | None = ...,
    overwrite: bool = ...,
) -> None:
    """Write data plus optional variance/mask layers to a FITS file.

    Raises if the file exists unless ``overwrite=True``.
    """