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.

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.