Compiled models and measurements¶
Compiled models form the boundary between physical experiment configuration and the algorithms. Measurements are nonnegative float64 intensities with a leading frame axis. See concepts and conventions for the Fourier and array conventions shared by both objects.
ImagePlaneModel
¶
Compiled pupil, Fourier crops, sampling, and frame/source weights.
Models are constructed by compile_model, not
directly. Returned arrays copy immutable compiled data. Shape tuples use
(height, width); wave vectors use radians per metre.
reconstruction_shape
property
¶
reconstruction_shape: Shape2D
Return the high-resolution complex-object shape.
is_multiplexed
property
¶
is_multiplexed: bool
Return whether any frame incoherently combines multiple sources.
pupil
property
¶
pupil: ComplexArray
Return the sampled complex pupil on the low-resolution Fourier grid.
pupil_support
property
¶
pupil_support: MaskArray
Return the uint8 aperture-support mask shaped image_shape.
frame_gains
property
¶
frame_gains: FloatArray | None
Return optional positive acquisition-frame intensity multipliers.
save_json
¶
save_json(*, path: Path) -> None
Save validated compiled sampling/crops/pupil as local float-roundtrip JSON.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path
|
File to overwrite; parent directory must exist. Releases the GIL and synchronizes contents. File/validation failures raise FpmError. |
required |
load_json
staticmethod
¶
load_json(*, path: Path) -> ImagePlaneModel
Load and validate a compiled numerical kernel entirely offline.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
Path
|
Local JSON file previously saved by a converter or save_json. |
required |
Returns:
| Type | Description |
|---|---|
ImagePlaneModel
|
Owned compiled kernel. File/validation failures raise FpmError; loading releases the GIL. |
suggest_reconstruction_shape
¶
suggest_reconstruction_shape(
optics: Optics,
illumination: Illumination,
image_shape: Shape2D,
reconstruction_shape: ReconstructionShapeSpec = "smooth",
) -> Shape2D
Resolve a reconstruction-size choice without building pupil or crop arrays.
compile_model
¶
compile_model(
optics: Optics,
illumination: Illumination,
image_shape: Shape2D,
reconstruction_shape: ReconstructionShapeSpec = "smooth",
) -> ImagePlaneModel
Compile experiment geometry into an immutable image-plane model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
optics
|
Optics
|
Valid physical microscope parameters. |
required |
illumination
|
Illumination
|
Complete geometry, calibration, and acquisition description. |
required |
image_shape
|
Shape2D
|
Low-resolution frame shape as |
required |
reconstruction_shape
|
ReconstructionShapeSpec
|
Exact high-resolution shape, or |
'smooth'
|
Returns:
| Type | Description |
|---|---|
ImagePlaneModel
|
Pupil, Fourier crops, sampling, source weights, and frame gains used by simulation and reconstruction. |
compile_camera_model
¶
compile_camera_model(
model: ImagePlaneModel, camera: CameraModel
) -> ImagePlaneModel
Compile the known uniform linear detector response into a model.
Pixel sensitivity, stochastic noise, clipping, quantization, and bad pixels remain detector effects and are not represented in the returned model.
MeasurementStack
¶
MeasurementStack(
measurements: FloatArray,
*,
frame_weights: Sequence[float] | None = None,
masks: MaskArray | None = None,
)
Resident float64 intensity stack shaped (frames, height, width).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurements
|
FloatArray
|
Nonnegative finite float64 array with shape |
required |
frame_weights
|
Sequence[float] | None
|
Optional finite nonnegative weight per frame; omitted weights are one. |
None
|
masks
|
MaskArray | None
|
Optional uint8 array matching |
None
|
frame_weights
property
¶
frame_weights: FloatArray
Return a float64 copy containing one objective weight per frame.
ReconstructionProblem
¶
ReconstructionProblem(
measurements: FloatArray | MeasurementStack,
model: ImagePlaneModel,
*,
frame_weights: Sequence[float] | None = None,
masks: MaskArray | None = None,
name: str | None = None,
)
Validated pairing of measurements and a compiled image-plane model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurements
|
FloatArray | MeasurementStack
|
Float64 |
required |
model
|
ImagePlaneModel
|
Compiled model with matching frame count and low-resolution shape. |
required |
frame_weights
|
Sequence[float] | None
|
Optional metadata used only when |
None
|
masks
|
Sequence[float] | None
|
Optional metadata used only when |
None
|
name
|
str | None
|
Optional human-readable problem identifier propagated to metadata. |
None
|
Narrowband spectral models¶
SpectralImagePlaneModel
¶
Compiled wavelength-specific kernels on one common object grid.
Created by compile_spectral_model. Algorithms use this immutable model,
without access to physical source geometry. Channel pupils and crops remain
wavelength-specific even when the complex object is explicitly shared.
wavelengths_vacuum_m
property
¶
wavelengths_vacuum_m: list[float]
Return ordered channel vacuum wavelengths in metres.
image_shape
property
¶
image_shape: Shape2D
Return the common low-resolution detector height and width.
reconstruction_shape
property
¶
reconstruction_shape: Shape2D
Return common-grid high-resolution object height and width.
object_coupling
property
¶
object_coupling: Literal['independent', 'shared_complex']
Return the explicitly selected complex transmission sharing rule.
channel_models
property
¶
channel_models: list[ImagePlaneModel]
Return copied ordinary kernels in declared channel order.
acquisition
property
¶
acquisition: SpectralAcquisitionPlan
Return a copied canonical sparse detector acquisition plan.
forward_intensities
¶
forward_intensities(
*, object_spectra: ComplexArray
) -> FloatArray
Evaluate the grayscale detector stack from centered complex spectra.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
object_spectra
|
ComplexArray
|
C-contiguous finite complex128 array of shape
|
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
Owned writable float64 |
Raises:
| Type | Description |
|---|---|
FpmError
|
If count, shape, layout, or finite-value validation fails. |
Notes
Releases the GIL while evaluating canonical channel forward operators.
from_compiled_channels
staticmethod
¶
from_compiled_channels(
*,
channel_ids: Sequence[str],
models: Sequence[ImagePlaneModel],
acquisition: SpectralAcquisitionPlan,
object_coupling: str = "independent",
) -> SpectralImagePlaneModel
Assemble stable ordered kernels without resolving physical geometry.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channel_ids
|
Sequence[str]
|
One nonempty unique stable ID per kernel. |
required |
models
|
Sequence[ImagePlaneModel]
|
Already compiled common-grid kernels with distinct positive wavelengths. |
required |
acquisition
|
SpectralAcquisitionPlan
|
Sparse scalar exposure order; every local frame must participate. |
required |
object_coupling
|
str
|
Explicit independent or shared_complex field storage. |
'independent'
|
Returns:
| Type | Description |
|---|---|
SpectralImagePlaneModel
|
Owned validated compiled channels. Invalid sampling/metadata raises FpmError; mismatched counts or invalid coupling raises ValueError. |
mixing_diagnostics
¶
mixing_diagnostics(
*, relative_tolerance: float | None = None
) -> SpectralMixingDiagnostics
Measure numerical rank/conditioning of declared exposure/channel weights.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
relative_tolerance
|
float | None
|
Finite nonnegative threshold relative to the largest singular value. Omission uses max(frames, channels) times binary64 epsilon. Rank counts singular values strictly greater than the resulting absolute threshold. |
None
|
Returns:
| Type | Description |
|---|---|
SpectralMixingDiagnostics
|
Matrix and descending singular values; deficient column rank yields condition_number=None. Array getters return independent writable copies. |
Raises:
| Type | Description |
|---|---|
FpmError
|
For invalid tolerance, overflow or Jacobi SVD nonconvergence. |
Notes
Each entry sums detector gain times spectral weight times local frame gain times incoherent local source-weight sum. Background and measurement masks/weights are excluded. Distinct crops/pupils remain separate operators; this diagnostic does not establish nonlinear recoverability. Releases the GIL.
References
NumPy, matrix_rank documentation, for the default rank threshold. LAPACK 3.12.1, DGESVJ documentation, for one-sided Jacobi SVD; the crate uses its own scaled cyclic rotations.
compile_spectral_model
¶
compile_spectral_model(
*,
channels: Sequence[SpectralChannel],
geometry: SpectralGeometry,
acquisition: SpectralAcquisitionPlan,
image_shape: Shape2D,
reconstruction_shape: ReconstructionShapeSpec = "smooth",
object_coupling: Literal[
"independent", "shared_complex"
] = "independent",
) -> SpectralImagePlaneModel
Compile narrowband kernels and size one grid from all channel crop bounds.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
channels
|
Sequence[SpectralChannel]
|
Ordered channels with unique IDs and distinct positive vacuum wavelengths. |
required |
geometry
|
SpectralGeometry
|
Explicit shared physical or channel-local geometry choice. |
required |
acquisition
|
SpectralAcquisitionPlan
|
Explicit sparse global detector exposure plan. |
required |
image_shape
|
Shape2D
|
Common detector |
required |
reconstruction_shape
|
ReconstructionShapeSpec
|
Explicit common grid or minimum, smooth, or power-of-two union sizing. |
'smooth'
|
object_coupling
|
Literal['independent', 'shared_complex']
|
Independent transmissions by default. |
'independent'
|
Returns:
| Type | Description |
|---|---|
SpectralImagePlaneModel
|
Immutable copied kernels retaining channel-specific sampling and pupils. |
Raises:
| Type | Description |
|---|---|
FpmError
|
For invalid IDs/wavelengths/references, uncovered local frames, shared direct k-vectors, unequal object-plane detector pitch, or insufficient grid. |
Notes
Compilation releases the GIL. Detector registration, resampling, finite bandwidth, and dispersive material models are outside this implementation.
SpectralReconstructionProblem
¶
SpectralReconstructionProblem(
*,
measurements: MeasurementStack | FloatArray,
model: SpectralImagePlaneModel,
frame_weights: Sequence[float] | None = None,
masks: MaskArray | None = None,
)
Scalar detector measurements paired with a compiled spectral model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurements
|
MeasurementStack | FloatArray
|
|
required |
model
|
SpectralImagePlaneModel
|
Compiled spectral model with equal detector count and shape. |
required |
frame_weights
|
Sequence[float] | None
|
Optional finite nonnegative reconstruction weights, one per detector row. |
None
|
masks
|
MaskArray | None
|
Optional C-contiguous uint8 array matching measurements; zero excludes pixels. |
None
|
Notes
Positive-weight rows must have unmasked pixels, and every channel/local row
must occur in a positive-weight detector frame. Membership comes from the
spectral plan, not FrameMetadata.illumination_index. Validation releases
the GIL after input conversion.
SpectralMixingDiagnostics
¶
Linear weight diagnostics in stable exposure/channel order.
Shapes refer to scalar detector exposures and declared channels. These describe calibration weights rather than spatial forward operators or nonlinear recovery.
channel_ids
instance-attribute
¶
channel_ids: list[str]
Stable channel IDs corresponding to the matrix columns.
matrix
instance-attribute
¶
matrix: FloatArray
Independent writable float64 copy shaped (detector frames, channels).
singular_values
instance-attribute
¶
singular_values: list[float]
Descending singular values, with min(frames, channels) entries.
rank
instance-attribute
¶
rank: int
Singular-value count strictly above the stated absolute tolerance.
relative_tolerance
instance-attribute
¶
relative_tolerance: float
Dimensionless singular-value threshold relative to the largest value.
absolute_tolerance
instance-attribute
¶
absolute_tolerance: float
Actual singular-value threshold in effective mode-weight units.
condition_number
instance-attribute
¶
condition_number: float | None
Largest/smallest ratio, or None for deficient columns or overflowing ratio.