Skip to content

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.

image_shape property

image_shape: Shape2D

Return the low-resolution detector-frame shape.

reconstruction_shape property

reconstruction_shape: Shape2D

Return the high-resolution complex-object shape.

source_count property

source_count: int

Return the number of individual illumination sources.

frame_count property

frame_count: int

Return the number of acquisition frames.

is_multiplexed property

is_multiplexed: bool

Return whether any frame incoherently combines multiple sources.

k_vectors property

k_vectors: FloatArray

Return a float64 (sources, 2) array of (kx, ky) rad/m.

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 (height, width).

required
reconstruction_shape ReconstructionShapeSpec

Exact high-resolution shape, or "minimum", "smooth", or "power_of_two" automatic sizing. The default chooses efficient small-prime FFT dimensions no smaller than the required Fourier extent.

'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 (frames, height, width). Python-owned data is copied during construction.

required
frame_weights Sequence[float] | None

Optional finite nonnegative weight per frame; omitted weights are one.

None
masks MaskArray | None

Optional uint8 array matching measurements. Zero excludes a pixel and nonzero includes it in reconstruction objectives.

None

shape property

shape: tuple[int, int, int]

Return (frames, height, width).

frame_count property

frame_count: int

Return the number of measured acquisition frames.

image_shape property

image_shape: Shape2D

Return the detector-frame shape as (height, width).

array property

array: FloatArray

Return a float64 copy shaped (frames, height, width).

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 (frames, height, width) array or an existing MeasurementStack.

required
model ImagePlaneModel

Compiled model with matching frame count and low-resolution shape.

required
frame_weights Sequence[float] | None

Optional metadata used only when measurements is a NumPy array.

None
masks Sequence[float] | None

Optional metadata used only when measurements is a NumPy array.

None
name str | None

Optional human-readable problem identifier propagated to metadata.

None

name property

name: str | None

Return the optional problem identifier.

frame_count property

frame_count: int

Return the validated acquisition-frame count.

image_shape property

image_shape: Shape2D

Return the low-resolution measurement shape.

reconstruction_shape property

reconstruction_shape: Shape2D

Return the high-resolution object shape.

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.

channel_ids property

channel_ids: list[str]

Return stable identifiers in numerical channel order.

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.

frame_count property

frame_count: int

Return the physical detector acquisition frame count.

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

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 (objects, height, width) on the common reconstruction grid. Spectra follow the core's forward FFT normalization by 1/(H*W). Independent coupling requires one object per channel; shared coupling requires exactly one object. The input is copied.

required

Returns:

Type Description
ndarray

Owned writable float64 (frames, image_height, image_width) intensities. Gains/background apply after the incoherent sum.

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 (height, width).

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. shared_complex stores one transmission and assumes wavelength independence of that complex field.

'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

MeasurementStack or C-contiguous float64 (frames, image_height, image_width) array copied into Rust storage.

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.

frame_count property

frame_count: int

Return the number of physical detector exposures.

image_shape property

image_shape: Shape2D

Return the common low-resolution detector height and width.

reconstruction_shape property

reconstruction_shape: Shape2D

Return the common high-resolution object height and width.

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.