Skip to content

torchsky.map.query

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.

Small, fixed linear queries on native Gaussian likelihood factors.

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

Top-level namespace

Small, fixed linear queries on native Gaussian likelihood factors.

Templates live in measurement space. A forced flux/blend query does not need an instantiated sky grid, a global inverse or a catalog-shaped scene. The complementary scene, response, noise and nuisance treatment are conditional inputs; changing them requires rebuilding the query.

LinearQueryResult dataclass 

LinearQueryResult(
    coefficients: Tensor,
    information: Tensor,
    data_rhs: Tensor,
    sampling_covariance: Tensor,
    mean_response: Tensor,
    penalty_precision: Tensor,
    data_rank: int,
    information_eigenvalues: Tensor,
    rank_cutoff: Tensor,
    nuisance_treatments: tuple[NuisanceTreatment, ...],
    _evidence_guard: Callable[[], None] | None = None,
)

Bases: _GuardedEvidence

Signed coefficients and fixed-model sampling covariance for real queries.

mean_response is the coefficient transfer matrix (F + P)^-1 F. A finite covariance after regularization does not identify an unsupported mode. data_rank, rank_cutoff and the transfer retain that distinction. information_eigenvalues records the spectrum before any roundoff repair. No uncertainty in the fixed templates/complement or selection is inferred.

_evidence_guard class-attribute instance-attribute 

_evidence_guard: Callable[[], None] | None = field(
    default=None, repr=False, compare=False
)

_guarded_fields class-attribute instance-attribute 

_guarded_fields = frozenset(
    {
        "coefficients",
        "information",
        "data_rhs",
        "sampling_covariance",
        "mean_response",
        "penalty_precision",
        "data_rank",
        "information_eigenvalues",
        "rank_cutoff",
    }
)

coefficients instance-attribute 

coefficients: Tensor

data_rank instance-attribute 

data_rank: int

data_rhs instance-attribute 

data_rhs: Tensor

information instance-attribute 

information: Tensor

information_eigenvalues instance-attribute 

information_eigenvalues: Tensor

mean_response instance-attribute 

mean_response: Tensor

nuisance_treatments instance-attribute 

nuisance_treatments: tuple[NuisanceTreatment, ...]

penalty_precision instance-attribute 

penalty_precision: Tensor

rank_cutoff instance-attribute 

rank_cutoff: Tensor

sampling_covariance instance-attribute 

sampling_covariance: Tensor

fit_linear_query 

fit_linear_query(
    system: GaussianLikelihoodSystem,
    templates: tuple[Tensor, ...],
    *,
    offset_predictions: tuple[Tensor, ...] | None = None,
    penalty_precision: Tensor | None = None,
    rank_rtol: float | None = None,
    rank_atol: float = 0.0,
    dependencies: EvidenceSnapshot | None = None,
) -> LinearQueryResult

Fit a small real coefficient vector against native measurements.

Each template tensor has shape (n_parameters, *factor.data.shape) and the factor's dtype/device. Complex templates are allowed for real-valued coefficients, using the factor's real-coordinate precision convention. Offsets describe the fixed complementary scene, after calibrated mean centering. The exact linear model is offset + sum_j theta_j template_j. Nonlinear Jacobians give a conditional local approximation, not an exact nonlinear confidence region.

Accumulate full F = sum J^* W J and g = sum J^* W(y-offset). With explicitly supplied PSD penalty P, solve (F+P) theta=g and report sampling covariance (F+P)^-1 F (F+P)^-1 and mean transfer. No positivity constraint, automatic ridge or diagonal substitution is introduced.

A numerically deficient solve raises; a supplied penalty may resolve the solve while leaving data_rank < n_parameters. The numerical rank cutoff is rank_atol + rank_rtol ||matrix||_2; default relative tolerance is n_parameters * eps. This is not a scientific identifiability threshold. Cholesky is used, without jitter or a matrix inverse. Symmetry/PSD validation uses an independent floating-point allowance, not the chosen rank cutoff; negative eigenvalues within that allowance alone are repaired to zero. Per factor, use p+1 precision actions and O(N p^2) contractions, then an O(p^3) small factorization. Callback costs may be superlinear in N. Supply bounded stamp/blend templates rather than dense whole-survey ones.

MPS Float32 uses CPU only for compact query-matrix spectral norms, symmetry/PSD/rank checks and roundoff repair, with differentiable Torch transfers. Reports return to the input device; measurement arrays/actions, contractions and Cholesky solves stay there. CPU/CUDA placement is unchanged. No global MPS fallback or altered tolerance/regularization is enabled.

Source tensor versions and factor dependencies guard the returned cached statistics. Declare other mutable query state through dependencies; inference tensors require its explicit revision. Refit after any change.