Skip to content

torchsky.map.operators.epsf

Experimental surface

These APIs are under active development. Names, defaults, and result objects may change between minor releases; pin a version if you depend on them in production.

Continuous-position pixel-integrated responses and Gaussian stamp profiling.

Guides: psf-conventions

This reference is generated from the package source. Names are grouped by the module that defines them; import every name from the public namespace torchsky.map.operators.epsf unless the group text says otherwise.

Top-level namespace

PixelIntegratedResponse

<class 'torchsky.map.operators.epsf.PixelIntegratedResponse'>

Continuous-position pixel-integrated responses and Gaussian stamp profiling.

This bounded lane consumes independent native detector stamps with known, fixed, diagonal Gaussian variances. It does not register/resample observations, infer a source catalogue, or require a global field. Response callables return the already pixel-integrated response per unit incident stellar flux: applying another pixel integral or normalizing a cropped stamp changes that convention.

GaussianPixelResponse dataclass 

GaussianPixelResponse(sigma_xy: Tensor)

Exact axis-aligned Gaussian integrated over unit-square detector pixels.

sigma_xy is a positive scalar or (sigma_x, sigma_y) tensor, in pixels. The underlying continuous density has unit integral on the infinite plane and zero centroid. The ePSF has infinite support; every finite footprint loses the analytically determined tail rather than redistributing it. This reference family assumes uniform intra-pixel sensitivity, no rotation, and a response independent of source flux/color/detector history.

The supplied tensor retains its graph. For positive nonlinear fitting, construct a response with log_sigma.exp() within the optimization step.

sigma_xy instance-attribute 

sigma_xy: Tensor

__call__ 

__call__(offset_xy: Tensor) -> Tensor

NativePixelStamp dataclass 

NativePixelStamp(
    data: Tensor,
    variance: Tensor,
    pixel_xy: Tensor,
    mask: Tensor | None = None,
)

One unresampled detector footprint with fixed independent variances.

data and variance are [H,W]; pixel_xy is [H,W,2], containing actual detector pixel centers, not registered offsets. mask=True keeps a measurement. Masked data/variance may be nonfinite; kept data must be finite and kept variances strictly positive. Pixel coordinates remain finite even at masked measurements. No transformations are inferred.

data instance-attribute 

data: Tensor

mask class-attribute instance-attribute 

mask: Tensor | None = None

pixel_xy instance-attribute 

pixel_xy: Tensor

valid_mask property 

valid_mask: Tensor

variance instance-attribute 

variance: Tensor

__post_init__ 

__post_init__() -> None

NativeStarFit dataclass 

NativeStarFit(
    flux: Tensor,
    background_coefficients: Tensor,
    prediction: Tensor,
    residual: Tensor,
    chi2: Tensor,
    degrees_of_freedom: int,
    conditional_covariance: Tensor,
    retained_response: Tensor,
    valid_response: Tensor,
)

Gaussian variable-projection result at fixed centroid and response.

conditional_covariance concerns linear coefficients (flux first), conditional on the supplied response, centroid, basis and known variances. It excludes their uncertainty and is neither joint nuisance uncertainty nor a residual-scaled/regularized covariance. Flux/background coefficients are signed unbiased Gaussian estimators even for a nonnegative response. retained_response sums response over the whole footprint; valid_response sums over kept pixels only. These are fractions for a unit-throughput response, and retain throughput for a lossy response.

background_coefficients instance-attribute 

background_coefficients: Tensor

chi2 instance-attribute 

chi2: Tensor

conditional_covariance instance-attribute 

conditional_covariance: Tensor

degrees_of_freedom instance-attribute 

degrees_of_freedom: int

flux instance-attribute 

flux: Tensor

prediction instance-attribute 

prediction: Tensor

residual instance-attribute 

residual: Tensor

retained_response instance-attribute 

retained_response: Tensor

valid_response instance-attribute 

valid_response: Tensor

native_pixel_stamp 

native_pixel_stamp(
    image: Tensor,
    variance: Tensor,
    *,
    x_slice: slice,
    y_slice: slice,
    mask: Tensor | None = None,
) -> NativePixelStamp

Slice native exposure pixels without interpolation or normalization.

Exposure pixel centers use zero-based integer (x,y) coordinates. Slices must have unit step and explicit in-bounds endpoints; detector edges are represented by choosing a smaller footprint, never padded measurements. Data/variance/mask are tensor views of the supplied exposure.

profile_native_star 

profile_native_star(
    stamp: NativePixelStamp,
    response: PixelIntegratedResponse,
    centroid_xy: Tensor,
    *,
    background_basis: Tensor | None = None,
    rcond: float | None = None,
) -> NativeStarFit

Profile stellar flux and local additive coefficients on native pixels.

The mean is flux * response(pixel_xy-centroid_xy) + basis @ background. By default the background basis is a constant column. Supply [H,W,K] basis values explicitly (K=0 for no background). Response and basis must be finite on the footprint. The weighted QR least-squares solve preserves gradients with respect to the continuous centroid and response parameters.

Rank is checked on the whitened design via singular values. rcond is only a relative numerical rank tolerance (default eps*max(rows,columns)), never a truncation, ridge penalty or pseudoinverse: deficiency fails closed. The nonlinear centroid/response optimizer is chosen by the caller. Only fixed diagonal Gaussian noise is supported here; this is not a Poisson, correlated-noise, crowded-field or shared-exposure uncertainty solver.