Skip to content

torchsky.map.operators.detector_response

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.

Exact moments for one linear, integrated photon-counting exposure.

Guides: likelihoods

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.detector_response unless the group text says otherwise.

Top-level namespace

Exact moments for one linear, integrated photon-counting exposure.

Independent incident photon arrivals are optically routed/thinned into pixel photoelectrons, independently collected dark electrons are added, and fixed linear charge mixing acts on their sum. Gaussian read noise and deterministic read offsets follow charge mixing. These are moment references, not a normalized Poisson-Gaussian likelihood or a calibrated-residual noise model. Saturation, nonlinear charge transport, brighter-fatter effects, and read-ramp history require other models and are deliberately outside this interface.

IntegratedDetectorMoments dataclass 

IntegratedDetectorMoments(
    mean: Tensor,
    photoelectron_mean: Tensor,
    dark_electron_mean: Tensor,
    _read_variance: Tensor,
    _gain: Tensor,
    _charge_response: LinearDetectorResponse | None,
    _read_noise_response: LinearDetectorResponse | None,
)

Mean and exact matrix-free covariance, built by the factory below.

Tensor values and callback captures are borrowed, not copied; do not mutate them during this object's lifetime. Rebuild for a new calibration or photon mean. mean is in output units and covariance_action(v) is the covariance matrix in output-units squared applied to v. Correlation means this object intentionally exposes no variance plane.

_charge_response instance-attribute 

_charge_response: LinearDetectorResponse | None

_gain instance-attribute 

_gain: Tensor

_read_noise_response instance-attribute 

_read_noise_response: LinearDetectorResponse | None

_read_variance instance-attribute 

_read_variance: Tensor

dark_electron_mean instance-attribute 

dark_electron_mean: Tensor

mean instance-attribute 

mean: Tensor

photoelectron_mean instance-attribute 

photoelectron_mean: Tensor

__post_init__ 

__post_init__() -> None

covariance_action 

covariance_action(vector: Tensor) -> Tensor

Apply G [D diag(photo + dark) D^T + C_read] G^T exactly.

G is diagonal 1 / electrons_per_output_unit. Read noise has C_read = R diag(read_variance_electrons2) R^T; identity R gives independent read noise. R operates after charge mixing and need not commute with D. Both terms retain off-diagonal covariance.

LinearDetectorResponse dataclass 

LinearDetectorResponse(
    forward: Callable[[Tensor], Tensor],
    adjoint: Callable[[Tensor], Tensor],
)

A fixed, shape-preserving real linear map and its exact Euclidean adjoint.

Callbacks must preserve tensor shape, dtype, and device. Their linearity and adjoint relationship are caller contracts; they cannot be established from one evaluation. Keep callbacks and all captured tensors fixed for the lifetime of any moments object that uses them; rebuild after calibration changes. This interface does not promise a particular callback complexity.

adjoint instance-attribute 

adjoint: Callable[[Tensor], Tensor]

forward instance-attribute 

forward: Callable[[Tensor], Tensor]

__post_init__ 

__post_init__() -> None

_apply 

_apply(value: Tensor, *, transpose: bool = False) -> Tensor

integrated_detector_moments 

integrated_detector_moments(
    photoelectron_mean: Tensor,
    *,
    dark_electron_mean: Tensor | float = 0.0,
    charge_response: LinearDetectorResponse | None = None,
    read_offset_electrons: Tensor | float = 0.0,
    read_variance_electrons2: Tensor | float = 0.0,
    read_noise_response: LinearDetectorResponse
    | None = None,
    electrons_per_output_unit: Tensor | float = 1.0,
    subtracted_mean_output_units: Tensor | float = 0.0,
) -> IntegratedDetectorMoments

Build exact moments of independent Poisson collection plus Gaussian read.

photoelectron_mean and dark_electron_mean are expected integrated electrons before charge mixing; dark includes its own duration conversion and does not undergo the optical response. Both are finite nonnegative physical means, never signed calibrated residuals. Read offsets are signed deterministic electron means after charge mixing. Read variance is in electrons squared; optional R factors correlated Gaussian noise.

All tensor parameters must be scalar or exactly match the photoelectron shape, dtype and device. Gain is positive electrons per output unit. Subtraction is a signed deterministic output-unit mean: subtracting a background or dark expectation retains its original shot covariance. A deterministic flat calibration is expressible through gain and changes covariance on both sides. Uncertainty in fitted subtraction/flat terms is not represented by these fixed-calibration moments.

integrated_photoelectron_mean 

integrated_photoelectron_mean(
    incident_photon_rate: Tensor,
    *,
    exposure_time_s: Tensor | float,
    foreground_photon_rate: Tensor | None = None,
    optical_mean_response: Callable[[Tensor], Tensor]
    | None = None,
    electrons_per_photon: Tensor | float = 1.0,
) -> Tensor

Convert incident and foreground photon/s into independent electron means.

Input rates are photons/s in each bin of the same explicitly chosen incident spatial/spectral discretization; flux/radiance densities must first be integrated with their spatial/spectral measures by the caller. optical_mean_response is a fixed positive linear map from their sum to pixel photon/s and may change shape; the caller includes needed optical throughput and pixel integration there. It describes independent routing/thinning of Poisson arrivals, not deterministic mixing of already collected charge. Its coefficients are non-amplifying routing/thinning probabilities over disjoint integrated incident photon bins: each incident bin has total destination detection probability at most one. Runtime checks on evaluated callback outputs cannot establish global positivity, linearity or this substochasticity contract. electrons_per_photon is a pixel detection probability in [0, 1], including any remaining QE/throughput exactly once. Duration is in seconds. For photons capable of generating multiple electrons, these Poisson moment assumptions do not apply.