Skip to content

torchsky.map.field.native_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.

Opt-in native source-quadrature rendering and fixed Gaussian evidence.

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

Top-level namespace

Opt-in native source-quadrature rendering and fixed Gaussian evidence.

This route uses caller-supplied source nodes and a calibrated response. It does not sample the field at detector centers and convolve, infer quadrature rules, or reuse the legacy normalized bandpass renderer.

NativeFieldResponse dataclass 

NativeFieldResponse(
    *,
    quadrature: NativeQuadratureResponseOp,
    calibration: PixelCalibrationOp,
    source_ra_deg: Tensor,
    source_dec_deg: Tensor,
    source_value_unit: str,
    quadrature_output_unit: str,
    source_measure_kind: Literal[
        "point_flux", "solid_angle_sr"
    ],
    spectral_measure_kind: Literal[
        "density_per_angstrom", "integrated_bins"
    ],
    band_name: str,
    geometry_id: str,
    response_id: str,
    dependencies: EvidenceSnapshot,
)

Fixed source-node response, sky registration and product calibration.

source_ra_deg/dec_deg[N] register the quadrature's source nodes on the sky. geometry_id declares their relation to its common response chart; detector rows must already be in the image's row-major order. No transform or row reordering is inferred or certified. The field's monochromatic output has source_value_unit. quadrature_output_unit declares the units after source/spectral measures and response factors, and must match calibration input units. Labels never trigger conversions.

Radiance uses source_measure_kind='solid_angle_sr'; point spectral flux uses 'point_flux' and source measures one. Density per Angstrom uses spectral_measure_kind='density_per_angstrom'; already integrated bins use 'integrated_bins' and wavelength measures one. Throughput/QE/area belong in the response or its explicit source weights; scalar commuting conversions can be in calibration. Include each factor exactly once.

dependencies must explicitly declare response parameters and hidden state. Geometry/measure tensors and response bindings are tracked here; arbitrary callable internals are not inspected. Rebuild after changes. Field parameters are evaluated afresh and are not fixed response evidence. Signed field values are supported; physical photon/count laws impose their own nonnegative support. This is finite quadrature, not an accuracy or physical-optics certificate, exposure-time integral or default renderer.

_binding class-attribute instance-attribute 

_binding: tuple[object, ...] = field(
    init=False, repr=False, compare=False
)

_snapshot class-attribute instance-attribute 

_snapshot: EvidenceSnapshot = field(
    init=False, repr=False, compare=False
)

band_name instance-attribute 

band_name: str

calibration instance-attribute 

calibration: PixelCalibrationOp

dependencies instance-attribute 

dependencies: EvidenceSnapshot

geometry_id instance-attribute 

geometry_id: str

quadrature instance-attribute 

quadrature: NativeQuadratureResponseOp

quadrature_output_unit instance-attribute 

quadrature_output_unit: str

response_id instance-attribute 

response_id: str

source_dec_deg instance-attribute 

source_dec_deg: Tensor

source_measure_kind instance-attribute 

source_measure_kind: Literal["point_flux", "solid_angle_sr"]

source_ra_deg instance-attribute 

source_ra_deg: Tensor

source_value_unit instance-attribute 

source_value_unit: str

spectral_measure_kind instance-attribute 

spectral_measure_kind: Literal[
    "density_per_angstrom", "integrated_bins"
]

state_shape property 

state_shape: tuple[int, int]

__post_init__ 

__post_init__() -> None

_bindings 

_bindings() -> tuple[object, ...]

adjoint 

adjoint(values: Tensor) -> Tensor

Exact transpose into sampled [N,L] coordinates, including measures.

forward 

forward(values: Tensor) -> Tensor

Map sampled monochromatic node values [N,L] to product pixels [P].

sample_field 

sample_field(
    model: Module,
    *,
    forward_context: ForwardContext | None = None,
    source_chunk_size: int = 4096,
) -> Tensor

Evaluate source nodes at each scalar wavelength, with no bandpass call.

Each model call contains at most source_chunk_size coordinates. The resulting [N,L] state and autograd graphs are resident; this is not a bounded total training-memory claim. Context can supply a scalar epoch to a time-aware field, but does not integrate within the exposure.

validate_evidence 

validate_evidence() -> None

bind_native_field_likelihood 

bind_native_field_likelihood(
    observation: FieldObservation,
    response: NativeFieldResponse,
    *,
    measurement_ids: tuple[str, ...],
    provenance_id: str,
    revision: Callable[[], object] | None = None,
) -> GaussianLikelihoodFactor

Bind sampled [N,L] values to conditional native Gaussian evidence.

No nn.Module or global field is required. Precision is fixed diagonal inverse variance in observed product units, restricted to observation support intersected with the response mask. Density normalization counts that same support. Output means are centered once. Shared uncertain calibration/nuisances are NOT inferred here; use explicit joint treatment, never independently split their uncertainty or use photon moments as fixed precision. UQ conditions on the declared response/calibration.

Original measurement dependencies and metadata are tracked. Explicit caller revisions are required for inference-mode evidence and alias writes.

render_native_field_observation 

render_native_field_observation(
    model: Module,
    observation: FieldObservation,
    response: NativeFieldResponse,
    *,
    forward_context: ForwardContext | None = None,
    source_chunk_size: int = 4096,
) -> Tensor

Opt-in source-node field rendering, calibration and output means.

Observation bandpass/area/time/gain metadata is provenance, never applied again: the declared response/calibration owns those factors. Existing render/training defaults are unchanged. This route has no physical raw detector likelihood, stochastic additive process or nonlinear history.