torchsky.scene¶
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.
Experimental scene representation and operator facade.
Guides: scenes, 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.scene unless the group text says otherwise.
Top-level namespace¶
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
field_observation ¶
field_observation(
*args: Any, **kwargs: Any
) -> FieldObservation
Construct a tensor-backed field observation for differentiable rendering.
image_observation ¶
image_observation(
*args: Any, **kwargs: Any
) -> ImageObservation
Construct an image-plane observation for classical map products.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
*args
|
Any
|
Positional |
()
|
**kwargs
|
Any
|
Image data, WCS, calibration, mask, and weight metadata. |
{}
|
Returns:
| Type | Description |
|---|---|
ImageObservation
|
Validated image-observation metadata. |
Examples:
>>> import torch
>>> from torchsky.scene import image_observation
>>> observation = image_observation(data=torch.ones(2, 2), header={})
>>> tuple(observation.data.shape)
(2, 2)
predict ¶
predict(
model: Module,
observation: FieldObservation,
**kwargs: Any,
) -> Tensor
Predict one field observation using the deterministic operator path.
product_spec ¶
product_spec(
*,
target_header: dict[str, Any],
bands: tuple[BandpassSpec, ...],
value_semantics: MapValueSemantics = "surface_brightness",
footprint_order: int | None = None,
) -> ProductSpec
Construct a map product specification using scene vocabulary.
render ¶
render(
scene: SceneRepresentation | Module | Tensor,
target: TargetRenderSpec,
**kwargs: Any,
) -> Tensor
Render any supported scene representation to a target grid.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scene
|
SceneRepresentation | Module | Tensor
|
Scene representation, field module, or target-aligned tensor. |
required |
target
|
TargetRenderSpec
|
Output grid and observing metadata. |
required |
**kwargs
|
Any
|
Scene-specific rendering controls. |
{}
|
Returns:
| Type | Description |
|---|---|
Tensor
|
Rendered tensor on the scene's execution device. |
Examples:
>>> from torchsky.scene import render
>>> callable(render)
True
target_from_header ¶
target_from_header(
header: dict[str, Any],
*,
value_semantics: str = "surface_brightness",
**kwargs: Any,
) -> TargetRenderSpec
Build a render target from a FITS-like WCS header.
target_from_product ¶
target_from_product(
product: ProductSpec,
*,
band_index: int = 0,
psf_spec: object | None = None,
) -> TargetRenderSpec
Build a render target from one band of a map product specification.
Bundle¶
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
ObservationOperatorBundle
dataclass
¶
ObservationOperatorBundle(
geometry: GeometryOp | None = None,
spectral_response: SpectralResponseOp | None = None,
psf: PSFOp | None = None,
radiometry: RadiometryOp | None = None,
background: BackgroundOp | None = None,
mask_weight: MaskWeightOp | None = None,
noise: NoiseOp | None = None,
)
Composable observation-law bundle used internally by map and INR paths.
spectral_response
class-attribute
instance-attribute
¶
spectral_response: SpectralResponseOp | None = None
Observations and targets¶
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
ImageObservation
dataclass
¶
ImageObservation(
path: str | None = None,
hdu: int | str | None = None,
weight: float = 1.0,
photometric_scale: float = 1.0,
background_offset: float = 0.0,
wavelength: float | None = None,
wavelength_map: Tensor | None = None,
ifu_wcs: Any | None = None,
spectral_min: float | None = None,
spectral_max: float | None = None,
transmission_center: float | None = None,
transmission_sigma: float | None = None,
band_name: str | None = None,
weight_path: str | None = None,
weight_hdu: int | str | None = 0,
mask_path: str | None = None,
mask_hdu: int | str | None = 0,
primary_beam_path: str | None = None,
primary_beam_hdu: int | str | None = None,
weight_is_inverse_variance: bool = False,
data: Tensor | None = None,
header: dict[str, Any] | None = None,
wcs: WCS | dict[str, Any] | Any | None = None,
weight_map: Tensor | None = None,
mask: Tensor | None = None,
dq_path: str | None = None,
dq_hdu: int | str | None = "DQ",
dq: Tensor | None = None,
dq_policy: DQPolicy | None = None,
primary_beam: Tensor | None = None,
weight_type: str = "weight",
weight_thresh: float | None = None,
good_bits: int | None = None,
var_poisson: Tensor | None = None,
var_rnoise: Tensor | None = None,
var_flat: Tensor | None = None,
flux_scale_keyword: str | None = None,
exposure_time_keyword: str | None = None,
gain_keyword: str | None = None,
exposure_time: float | None = None,
head_path: str | None = None,
use_sidecar_head: bool = False,
dcr_zenith_deg: float | None = None,
dcr_parallactic_deg: float = 0.0,
dcr_ref_wavelength: float = 5000.0,
dcr_pressure_hpa: float = 600.0,
dcr_temperature_c: float = 7.0,
tracking_rate: tuple[float, float] | None = None,
mjd_obs: float | None = None,
reference_mjd: float | None = None,
)
Describe one image exposure and its calibration metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str | None
|
Optional input path consumed through the torchfits boundary. |
None
|
data
|
Tensor | None
|
Optional in-memory image tensor, used instead of |
None
|
header
|
dict[str, Any] | None
|
FITS-style header mapping for in-memory data. |
None
|
wcs
|
WCS | dict[str, Any] | Any | None
|
Explicit WCS object or header mapping. |
None
|
weight
|
float
|
Scalar exposure weight. |
1.0
|
photometric_scale
|
float
|
Multiplicative flux calibration. |
1.0
|
background_offset
|
float
|
Additive background removed before resampling. |
0.0
|
weight_map
|
Tensor | None
|
Optional per-pixel relative weight tensor (an inverse
variance only when |
None
|
mask
|
Tensor | None
|
Optional Boolean valid-pixel mask. |
None
|
Examples:
>>> import torch
>>> from torchsky.map import Observation
>>> observation = Observation(data=torch.ones(2, 2), header={})
>>> tuple(observation.data.shape)
(2, 2)
weight_is_inverse_variance
class-attribute
instance-attribute
¶
weight_is_inverse_variance: bool = False
Observation operators¶
ObservationOperatorBundleProtocol
<class 'torchsky.scene.operators.ObservationOperatorBundleProtocol'>
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
ObservationOperatorAdapter
dataclass
¶
ObservationOperatorAdapter(
bundle: ObservationOperatorBundle,
observation: FieldObservation
| ImageObservation
| None = None,
resampling_kernel: str | None = None,
)
Executable adapter over the existing map observation-operator bundle.
observation
class-attribute
instance-attribute
¶
observation: FieldObservation | ImageObservation | None = (
None
)
bind_image_plane_target ¶
bind_image_plane_target(
scene_target: TargetRenderSpec,
*,
observation_header: dict[str, Any] | None = None,
resampling_kernel: str | None = None,
value_semantics: str | None = None,
drizzle_pixfrac: float = 1.0,
chunk_pixels: int = 262144,
) -> BoundObservationOperator
Bind an image-plane observation to a latent target-grid scene.
The returned operator maps a scene tensor on scene_target into the
observation image grid. Its adjoint is the exact vector-Jacobian product
of that same differentiable projection, so normal-equation probes and CG
solves exercise one shared forward model.
bind_target ¶
bind_target(
target: TargetRenderSpec,
*,
apply_operator: ApplyOperatorFn | None = None,
apply_adjoint: AdjointOperatorFn | None = None,
apply_noise: ApplyNoiseFn | None = None,
bind_target_fn: BindTargetFn | None = None,
) -> BoundObservationOperator
Bind this observation law to one target render grid.
bind_targets ¶
bind_targets(
targets: Sequence[TargetRenderSpec],
*,
apply_operator: ApplyOperatorFn | None = None,
apply_adjoint: AdjointOperatorFn | None = None,
apply_noise: ApplyNoiseFn | None = None,
bind_target_fn: BindTargetFn | None = None,
exposure_chunk_size: int = 1,
) -> BoundObservationOperatorSet
Bind this observation law to several target render grids.
from_field_observation
classmethod
¶
from_field_observation(
observation: FieldObservation,
*,
geometry: GeometryOp | None = None,
) -> "ObservationOperatorAdapter"
from_image_observation
classmethod
¶
from_image_observation(
observation: ImageObservation, *, resampling_kernel: str
) -> "ObservationOperatorAdapter"
from_observation
classmethod
¶
from_observation(
observation: FieldObservation | ImageObservation,
*,
resampling_kernel: str = "bilinear",
geometry: GeometryOp | None = None,
) -> "ObservationOperatorAdapter"
normal_equation_probe ¶
normal_equation_probe(
scene: Any,
target: TargetRenderSpec,
data: Tensor,
*,
apply_operator: ApplyOperatorFn | None = None,
apply_adjoint: AdjointOperatorFn | None = None,
apply_noise: ApplyNoiseFn | None = None,
bind_target_fn: BindTargetFn | None = None,
) -> NormalEquationProbe
Assemble A^T N^-1 A and A^T N^-1 y probes for one target.
predict_observation_mean ¶
predict_observation_mean(
model: Module,
observation: FieldObservation,
**render_kw: Any,
) -> Tensor
Execute the current deterministic field-observation prediction path.
solver_hooks ¶
solver_hooks(
*,
apply_operator: ApplyOperatorFn | None = None,
apply_adjoint: AdjointOperatorFn | None = None,
apply_noise: ApplyNoiseFn | None = None,
bind_target_fn: BindTargetFn | None = None,
) -> SolverHooks
Build executable solver hooks backed by this observation bundle.
bind_image_plane_observations_to_target ¶
bind_image_plane_observations_to_target(
observations: Sequence[ImageObservation],
scene_target: TargetRenderSpec,
*,
observation_headers: Sequence[dict[str, Any] | None]
| None = None,
resampling_kernel: str = "bilinear",
value_semantics: str | None = None,
drizzle_pixfrac: float = 1.0,
chunk_pixels: int = 262144,
exposure_chunk_size: int = 1,
) -> BoundObservationOperatorSet
Bind several image-plane observations to one latent target-grid scene.
operator_adapter_for_observation ¶
operator_adapter_for_observation(
observation: FieldObservation | ImageObservation,
*,
resampling_kernel: str = "bilinear",
geometry: GeometryOp | None = None,
) -> ObservationOperatorAdapter
Return the promoted scene adapter for an existing observation object.
operator_bundle_for_observation ¶
operator_bundle_for_observation(
observation: FieldObservation | ImageObservation,
*,
resampling_kernel: str = "bilinear",
geometry: GeometryOp | None = None,
) -> ObservationOperatorBundle
Return the underlying current map operator bundle for one observation.
operator_bundles_for_observations ¶
operator_bundles_for_observations(
observations: Sequence[
FieldObservation | ImageObservation
],
*,
resampling_kernel: str = "bilinear",
geometry: GeometryOp | None = None,
) -> tuple[ObservationOperatorBundle, ...]
Return one observation-operator bundle per observation, preserving order.
Products and stacking¶
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
BandpassSpec
dataclass
¶
BandpassSpec(
label: str | None = None,
spectral_min: float | None = None,
spectral_max: float | None = None,
transmission_center: float | None = None,
transmission_sigma: float | None = None,
spectral_unit: str = "Angstrom",
passband: Passband | None = None,
)
ProductSpec
dataclass
¶
ProductSpec(
target_header: dict[str, Any],
bands: tuple[BandpassSpec, ...],
value_semantics: MapValueSemantics = "surface_brightness",
footprint_order: int | None = None,
)
value_semantics
class-attribute
instance-attribute
¶
value_semantics: MapValueSemantics = 'surface_brightness'
target_render_spec ¶
target_render_spec(
*, band_index: int = 0, psf_spec: object | None = None
) -> TargetRenderSpec
target_render_specs ¶
target_render_specs(
*, psf_specs: Sequence[object | None] | None = None
) -> tuple[TargetRenderSpec, ...]
Scenes¶
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
ContinuousFieldModel
dataclass
¶
ContinuousFieldModel(model: Module)
Bases: SceneRepresentation
render_distribution_to_target ¶
render_distribution_to_target(
target: TargetRenderSpec, **kwargs
) -> tuple[Tensor, Tensor]
DiscreteTargetImage
dataclass
¶
DiscreteTargetImage(
data: Tensor,
header: dict[str, Any] | None = None,
value_semantics: str = "surface_brightness",
)
Bases: SceneRepresentation
HarmonicAlmScene
dataclass
¶
HarmonicAlmScene(
data: Tensor,
lmax: int | None = None,
mmax: int | None = None,
band_labels: tuple[str | None, ...] | None = None,
)
Bases: SceneRepresentation
HealpixMapScene
dataclass
¶
HealpixMapScene(
data: Tensor,
nside: int | None = None,
nest: bool = False,
band_labels: tuple[str | None, ...] | None = None,
lmax: int | None = None,
target_nside: int | None = None,
fwhm_rad: float | None = None,
beam_window: Tensor | None = None,
iter: int = 0,
mode: str | None = None,
)
Bases: SceneRepresentation
_project_single_map ¶
_project_single_map(
healpix_map: Tensor,
target: TargetRenderSpec,
*,
mode: str,
) -> Tensor
SceneRepresentation ¶
Bases: ABC
SpinHarmonicAlmScene
dataclass
¶
SpinHarmonicAlmScene(
alm_e: Tensor,
alm_b: Tensor,
spin: int,
lmax: int | None = None,
mmax: int | None = None,
)
Bases: SceneRepresentation
as_scene_representation ¶
as_scene_representation(
scene: SceneRepresentation | Module | Tensor,
) -> SceneRepresentation
Adapt a scene object, module, or tensor to SceneRepresentation.
target_to_field_observation ¶
target_to_field_observation(
target: TargetRenderSpec,
*,
device: device | None = None,
)
Create an empty field observation carrying a target's metadata.
Sources¶
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
SourceCatalogScene ¶
SourceCatalogScene(
lon: Tensor | None = None,
lat: Tensor | None = None,
*,
positions: Tensor | None = None,
component_ids: Tensor | None = None,
morphology: str | Sequence[str] | Tensor = "point",
gaussian_parameters: Tensor | None = None,
sersic_parameters: Tensor | None = None,
fixed_templates: Tensor | None = None,
template_data: Tensor | None = None,
template_slices: Tensor | None = None,
template_shapes: Tensor | None = None,
template_pixel_scale_arcsec: Tensor
| float
| None = None,
coefficients: Tensor | None = None,
band_labels: Sequence[str] | None = None,
spectral_basis: Tensor | None = None,
parameter_slices: Tensor | None = None,
support_footprints: Sequence[MOC] | None = None,
support_uniq: Tensor | None = None,
support_slices: Tensor | None = None,
support_radius_arcsec: Tensor | float | None = None,
footprint_order: int = 16,
)
Bases: SceneRepresentation
A caller-defined fixed-morphology source catalog with linear coefficients.
component_ids
instance-attribute
¶
component_ids = (
arange(count, dtype=int64, device=device)
if component_ids is None
else _integer_rows(
component_ids, name="component_ids", device=device
)
)
morphology_codes
instance-attribute
¶
morphology_codes = _normalize_morphology(
morphology, count, device=device
)
parameter_slices
instance-attribute
¶
parameter_slices = (
default_slices
if parameter_slices is None
else _as_tensor(
parameter_slices, dtype=int64, device=device
)
)
support_slices
instance-attribute
¶
support_slices = (
None
if support_slices is None
else _as_tensor(
support_slices, dtype=int64, device=device
)
)
template_data
instance-attribute
¶
template_data = (
new_empty((0,))
if template_data is None
else reshape(-1)
)
template_shapes
instance-attribute
¶
template_shapes = (
zeros((count, 2), dtype=int64, device=device)
if template_shapes is None
else _as_tensor(
template_shapes, dtype=int64, device=device
)
)
template_slices
instance-attribute
¶
template_slices = (
zeros((count, 2), dtype=int64, device=device)
if template_slices is None
else _as_tensor(
template_slices, dtype=int64, device=device
)
)
_gaussian_stamp ¶
_gaussian_stamp(
index: int, wcs: WCS, bounds: tuple[int, int, int, int]
) -> Tensor
_tangent_world ¶
_tangent_world(
index: int, east_arcsec: Tensor, north_arcsec: Tensor
) -> tuple[Tensor, Tensor]
_template_stamp ¶
_template_stamp(
index: int,
wcs: WCS,
bounds: tuple[int, int, int, int],
*,
chunk_size: int | None,
) -> Tensor
component_flux ¶
component_flux(
index: int,
band_name: str | None,
values: Tensor | None = None,
) -> Tensor
render_component ¶
render_component(
index: int,
observation: FieldObservation,
*,
chunk_size: int | None = None,
) -> SourceStamp | None
render_observation ¶
render_observation(
observation: FieldObservation,
*,
parameter_values: Tensor | None = None,
source_indices: Tensor | Sequence[int] | None = None,
chunk_size: int | None = None,
) -> Tensor
Splatting¶
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
SplatDiagnostics
dataclass
¶
SplatDiagnostics(
retained_weight: Tensor,
input_flux: Tensor,
deposited_flux: Tensor,
lost_flux: Tensor,
)
Render targets¶
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
TargetRenderSpec
dataclass
¶
TargetRenderSpec(
header: dict[str, Any],
shape: tuple[int, int],
value_semantics: str = "surface_brightness",
band_label: str | None = None,
spectral_min: float | None = None,
spectral_max: float | None = None,
transmission_center: float | None = None,
transmission_sigma: float | None = None,
psf_spec: object | None = None,
spectral_unit: str = "Angstrom",
passband: Passband | None = None,
)
Types¶
Experimental scene representation and operator facade.
This namespace is additive over the map/field implementation: it gives users
scene-level vocabulary for representations, target specifications, and operator
adapters. Production map verbs live in :mod:torchsky.map; field models and
fit/render/sample verbs live in :mod:torchsky.field.
FieldObservation
dataclass
¶
FieldObservation(
image: Tensor,
header: dict,
weight: Tensor | None = None,
mask: Tensor | None = None,
err: Tensor | None = None,
var_poisson: Tensor | None = None,
var_rnoise: Tensor | None = None,
var_flat: Tensor | None = None,
contamination_prior: Tensor | None = None,
amplifier_index: Tensor | None = None,
wavelength: float | None = None,
spectral_min: float | None = None,
spectral_max: float | None = None,
transmission_center: float | None = None,
transmission_sigma: float | None = None,
transmission_wavelength: Tensor | None = None,
transmission_throughput: Tensor | None = None,
psf_sigma_pix: float = 0.0,
psf_spec: PSFSpec | None = None,
sky_background: Tensor | None = None,
instrument_background: Tensor | None = None,
detector_background: Tensor | None = None,
background_offset: float = 0.0,
band_name: str | None = None,
spectral_quantity: FieldSpectralQuantity | None = None,
detector_x0_pix: float = 0.0,
detector_y0_pix: float = 0.0,
detector_to_sky: DetectorToSkyTransform | None = None,
passband: Passband | None = None,
value_unit: str | None = None,
value_semantics: str | None = None,
spectral_unit: str | None = None,
detector_law: DetectorLaw | None = None,
gain_electrons_per_adu: Tensor | float | None = None,
gain_provenance_id: str | None = None,
exposure_time_s: float | None = None,
collecting_area_m2: float | None = None,
additive_components: tuple[AdditiveComponent, ...] = (),
processing_state: AdditiveProcessingState | None = None,
)
One band-limited 2D map plus spectral metadata for field fitting.
Use :mod:torchsky.map.field.observation_builders to turn binned 1D spectra,
IFU channel cubes, or X-ray-style center/width summaries into observation lists.
Set spectral_quantity when the axis is energy (e.g. keV) rather than wavelength.
Optional transmission_wavelength / transmission_throughput give a tabulated
throughput curve (same units as the spectral axis, dimensionless throughput).
When both are set, bandpass quadrature integrates against this curve (trapezoid
rule on the quadrature grid, with linear interpolation of throughput) instead of
the uniform-in-band or Gaussian fallbacks from transmission_sigma.
_cached_coordinate_signature
class-attribute
instance-attribute
¶
_cached_coordinate_signature: tuple[Any, ...] | None = (
field(default=None, init=False, repr=False)
)
_cached_dec_deg
class-attribute
instance-attribute
¶
_cached_dec_deg: Tensor | None = field(
default=None, init=False, repr=False
)
_cached_ra_deg
class-attribute
instance-attribute
¶
_cached_ra_deg: Tensor | None = field(
default=None, init=False, repr=False
)
additive_components
class-attribute
instance-attribute
¶
additive_components: tuple[AdditiveComponent, ...] = ()
detector_to_sky
class-attribute
instance-attribute
¶
detector_to_sky: DetectorToSkyTransform | None = None
gain_electrons_per_adu
class-attribute
instance-attribute
¶
gain_electrons_per_adu: Tensor | float | None = None
instrument_background
class-attribute
instance-attribute
¶
instrument_background: Tensor | None = None
processing_state
class-attribute
instance-attribute
¶
processing_state: AdditiveProcessingState | None = None
spectral_quantity
class-attribute
instance-attribute
¶
spectral_quantity: FieldSpectralQuantity | None = None
transmission_throughput
class-attribute
instance-attribute
¶
transmission_throughput: Tensor | None = None
transmission_wavelength
class-attribute
instance-attribute
¶
transmission_wavelength: Tensor | None = None
clear_coordinate_cache ¶
clear_coordinate_cache() -> None
Drop cached WCS coordinate grids after mutating image shape or header.
coordinate_cache_signature ¶
coordinate_cache_signature(
shape: tuple[int, int],
) -> tuple[Any, ...]
Return a lightweight signature for cached WCS coordinate grids.
to ¶
to(
device: device | str | None = None,
dtype: dtype | None = None,
) -> "FieldObservation"
Return an independently moved observation with semantic dtypes preserved.
Floating detector planes follow dtype. Boolean masks and integer
amplifier indices retain their semantic dtype. Nested modules are copied
before moving, so the source observation is not mutated. Coordinate caches
are intentionally dropped by :func:dataclasses.replace.
validate_certified ¶
validate_certified(
forward_context: ForwardContext,
) -> "FieldObservation"
Validate the strict native-observation contract used for claims.
Legacy and exploratory observations remain valid without these fields; production adapters opt into this fail-closed check explicitly.
ForwardContext
dataclass
¶
ForwardContext(
survey: str | None = None,
instrument: str | None = None,
detector: str | None = None,
exposure_id: str | None = None,
time_mjd: float | None = None,
extra: dict[str, Any] = dict(),
time_scale: TimeScale | None = None,
calibration_id: str | None = None,
provenance_id: str | None = None,
)
Exposure / instrument context c (see docs/models/fields.md).
Rendering passes this to nn.Module.forward or render_bandpass only when
the model declares a forward_context keyword parameter. Otherwise it is ignored
so existing field models stay valid without changes.
validate_certified ¶
validate_certified() -> 'ForwardContext'
Fail closed unless the context identifies one calibrated exposure.
PSFSpec
dataclass
¶
PSFSpec(
mode: FieldPSFMode = "none",
sigma_pix: float = 0.0,
kernel2d: Tensor | None = None,
model: Module | None = None,
cell_u_pix: Tensor | None = None,
cell_lam_norm: float = 0.5,
frozen: bool = True,
pixel_response_included: bool | None = None,
)
Public PSF description for field observations and target products.
kernel2d is an odd-sized, image-shaped unit-source response: its center
indexes zero displacement and increasing columns/rows are positive detector
x/y offsets. Rendering normalizes its sum and retains zero-padding losses
at detector boundaries. It is not a PyTorch cross-correlation weight array.
Learned PSFs are calibration products and are frozen while rendering a sky
scene. frozen=False is reserved for a future calibration-only execution
path; the scene renderer rejects it instead of silently dropping gradients.
pixel_response_included
class-attribute
instance-attribute
¶
pixel_response_included: bool | None = None
Whether the calibrated kernel already includes detector pixel response.
True requires center sampling; another pixel quadrature would integrate twice. False records an optical-only kernel; None leaves legacy calibration unknown. This metadata does not certify the accuracy of discrete detector-grid convolution.
learned
classmethod
¶
learned(
model: Module,
*,
base_sigma_pix: float,
cell_u_pix: Tensor | None = None,
cell_lam_norm: float = 0.5,
frozen: bool = True,
) -> "PSFSpec"
to ¶
to(
device: device | str | None = None,
dtype: dtype | None = None,
) -> "PSFSpec"
Return an independently moved PSF without mutating the source model.