Skip to content

torchsky.map.field.joint_native_likelihood

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.

Joint native-field Gaussian evidence with shared additive nuisance modes.

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

Top-level namespace

Joint native-field Gaussian evidence with shared additive nuisance modes.

bind_joint_native_likelihood 

bind_joint_native_likelihood(
    observations: tuple[FieldObservation, ...],
    responses: tuple[NativeFieldResponse, ...],
    *,
    measurement_ids: tuple[tuple[str, ...], ...],
    nuisance_bases: tuple[Tensor, ...],
    nuisance_basis_units: tuple[str, ...],
    nuisance_ids: tuple[str, ...],
    nuisance_treatment: Literal["profiled", "calibrated"],
    calibration_id: str,
    provenance_id: str,
    calibrated_mean: Tensor | None = None,
    covariance_factor: Tensor | None = None,
    rank_rtol: float | None = None,
    rank_atol: float = 0.0,
    dependencies: EvidenceSnapshot | None = None,
    revision: Callable[[], object] | None = None,
) -> GaussianLikelihoodFactor

Eliminate shared nuisance coordinates once across native observations.

Each observation is first bound by bind_native_field_likelihood as conditional diagonal Gaussian evidence. These conditional noise terms must be independent across observations; shared covariance is introduced only through the declared nuisance basis. Other cross-instrument correlated read noise requires a different joint base precision. Native detector vectors/actions are packed, without building a dense pixel covariance or homogenizing PSFs, sampling grids, coordinate charts or product units.

All responses must use the same ordered source RA/Dec and Angstrom nodes, source value units, spatial/spectral measure kinds, shape, dtype and device. Source chart coordinates, integration weights and response products may differ as declared by the caller. Equality is exact; no coordinate tolerance, reordering, interpolation or unit conversion is inferred.

nuisance_ids orders shared, standardized dimensionless coefficient coordinates. Each nuisance_bases[e] is explicitly [P_e,K], in native row-major pixel order, and carries observation e's product units per coefficient. nuisance_basis_units[e] must equal its observed units. The shared coefficient calibrated_mean[K] and covariance factor covariance_factor[K,R] use those same ordered coefficient coordinates; physical conversions between products belong in their supplied bases. An omitted mean in calibrated mode means an explicitly zero mean.

Calibrated mode centers the additive mean once and uses one Woodbury action and its determinant correction, including cross-exposure terms. Calibration must be independent of conditional measurement noise. Profiled mode projects the single joint nuisance span; it does not supply a normalized predictive density or restore a removed gauge. Rank thresholds are numerical policies from ProfiledNuisancePrecision; deficient bases and rank changes do not certify scientific identifiability. Gradients are supported on a fixed-rank stratum. The Gaussian factor's data is centered and masked; its response stays linear in sampled [N,L] states.

Original parent evidence, response/calibration bindings, bases, mean and covariance factor guard both calls and cached normal/query reads. Declare hidden dependencies with dependencies; supply revision for inference-mode inputs and for NumPy/.data alias writes or other state not covered by tensor mutation versions. Identifiers alone cannot verify independence or lineage. Rebuild after changes and for a new autograd graph. A previously retrieved plain tensor cannot intercept later use.

Packed vectors/bases remain resident. Construction/storage and rank-space costs follow the reused nuisance primitive; this is not a bounded total training-memory claim or a performance measurement.