Skip to content

Results and bundles

Reconstruction results live in memory. Result bundles persist numerical arrays as NPY files, structured records as Parquet, and provenance in a JSON manifest. Opened bundles load large arrays on first access and cache them until cleared. Planar-array initialization bundles are smaller verified directories: their authoritative result is JSON and their per-frame observations and physical-fit history are normalized CSV tables.

Results and checkpoints

ReconstructionCheckpoint

Serializable algorithm state for resuming a compatible run.

Problem-aware restoration requires the stored pupil support to match the compiled model support exactly. Pupil-recovering algorithms canonicalize a restored object/pupil pair before start callbacks and continued work.

format_version property

format_version: int

Return the checkpoint format version.

completed_iterations property

completed_iterations: int

Return the number of complete iterations represented by the state.

load staticmethod

Read and validate a checkpoint file without holding the Python GIL.

save

save(path: Path) -> None

Atomically serialize this checkpoint without holding the Python GIL.

RuntimeInfo

Execution summary attached to a reconstruction result.

elapsed_seconds instance-attribute

elapsed_seconds: float

Wall-clock run duration in seconds.

completed_iterations instance-attribute

completed_iterations: int

Number of complete iterations executed, including resumed progress.

stopped_early instance-attribute

stopped_early: bool

Whether a callback requested termination before the configured limit.

algorithm instance-attribute

algorithm: str

Stable algorithm name recorded by the runner.

ReconstructionResult

Owned reconstruction products, histories, diagnostics, and metadata.

Object-space arrays use reconstruction_shape. Pupil arrays use the model's low-resolution image_shape. Calibration arrays are present only when the selected algorithm recovered those quantities.

object instance-attribute

object: ComplexArray

Reconstructed complex128 object field.

amplitude instance-attribute

amplitude: FloatArray

Magnitude of the reconstructed complex object field.

phase instance-attribute

phase: FloatArray

Wrapped argument of object in radians.

object_spectrum instance-attribute

object_spectrum: ComplexArray

Centered complex Fourier spectrum corresponding to object.

recovered_pupil instance-attribute

recovered_pupil: ComplexArray

Final sampled pupil, canonicalized for built-in blind recovery.

Canonicalization matches the compiled pupil's supported energy and phase reference. The returned object fields contain the reciprocal correction.

pupil_support instance-attribute

pupil_support: MaskArray

Uint8 aperture-support mask for recovered_pupil.

calibrated_illumination instance-attribute

calibrated_illumination: FloatArray | None

Optional (sources, 2) recovered Fourier-grid offsets in pixels.

recovered_frame_gains instance-attribute

recovered_frame_gains: FloatArray | None

Optional recovered positive multiplicative gain per frame.

recovered_background instance-attribute

recovered_background: FloatArray | None

Optional recovered nonnegative uniform background per frame.

physical_illumination_calibration instance-attribute

physical_illumination_calibration: (
    IlluminationCalibrationState | None
)

Physical planar-array state for a joint run, distinct from k-vector offsets.

calibrated_model instance-attribute

calibrated_model: ImagePlaneModel | None

Reusable model refreshed from the final physical illumination.

trace instance-attribute

trace: list[tuple[int, float, float]]

(iteration, objective, elapsed_seconds) records.

algorithm_metrics instance-attribute

algorithm_metrics: list[tuple[int, str, str, float]]

(iteration, namespace, metric, value) algorithm-specific records.

scalar_diagnostics instance-attribute

scalar_diagnostics: Mapping[str, float]

Named final scalar diagnostics.

runtime instance-attribute

runtime: RuntimeInfo

Execution duration, progress, stopping state, and algorithm name.

metadata instance-attribute

metadata: Mapping[str, str]

Stable string metadata carried by the result.

final_objective instance-attribute

final_objective: float | None

Objective from the last trace record, or None for an empty trace.

write_bundle

write_bundle(
    path: Path,
    *,
    run_id: str | None = None,
    label: str | None = None,
    include_previews: bool = True,
) -> ResultBundle

Write a self-describing Parquet/NPY result bundle and reopen it.

path is the destination directory. run_id defaults to a generated identifier, label is optional display metadata, and disabling include_previews omits derived PNG images. Existing nonempty targets are rejected.

SpectralReconstructionResult

Owned channel-ordered spectral fields and the global acquisition trace.

Array properties return writable copies with channel as the first axis. Shared-object output repeats the identical field in every channel plane. Unconstrained AP has independent unobservable phase pistons for independent objects, or one for shared-complex coupling. Joint OPD descent imposes a further referenced phase constraint; object_coupling describes the compiled model's field storage/reuse, not its real-parameter coupling.

channel_ids property

channel_ids: list[str]

Return stable identifiers aligned with stacked channel arrays.

wavelengths_vacuum_m property

wavelengths_vacuum_m: list[float]

Return channel vacuum wavelengths in metres, in output order.

object_coupling property

object_coupling: Literal['independent', 'shared_complex']

Return the compiled model's complex-field storage/reuse rule.

object property

object: ComplexArray

Return complex128 transmission copies shaped (channels, height, width).

object_spectrum property

object_spectrum: ComplexArray

Return centered complex128 spectra shaped (channels, height, width).

amplitude property

amplitude: FloatArray

Return nonnegative float64 object magnitudes with channel first.

phase property

phase: FloatArray

Return float64 wrapped object phases in radians with channel first.

pupils property

pupils: ComplexArray

Return fixed complex128 pupils shaped (channels, image_height, image_width).

trace property

trace: list[tuple[int, float, float]]

Return iteration, weighted objective, and elapsed seconds.

Spectral AP reports pre-update pass objectives starting at one. Joint OPD descent reports the constrained initial objective at zero followed by post-update full-data smoothed amplitude objectives.

completed_iterations property

completed_iterations: int

Return the number of complete global acquisition passes.

checkpoint property

Return resumable AP state; joint state lives in its enclosing result.

unwrap_opd

unwrap_opd(
    *,
    unwrapper: SyntheticWavelengthUnwrapper,
    phase_offsets_rad: Sequence[float] | None = None,
    reference_mask: MaskArray | None = None,
    reference_opd_m: float = 0.0,
    mask: MaskArray | None = None,
) -> OpticalPathDifferenceResult

Combine independent wavelength phases into referenced common OPD.

Parameters:

Name Type Description Default
unwrapper SyntheticWavelengthUnwrapper

Nondispersive phase-mixing configuration with an explicit OPD interval.

required
phase_offsets_rad Sequence[float] | None

One constant phase piston per channel in radians, subtracted before mixing. Requires omission of reference_mask and zero reference_opd_m. Zero offsets require already referenced fields.

None
reference_mask MaskArray | None

Alternative C-contiguous uint8 (height, width) constant-OPD reference region. Nonzero selects pixels, intersected with validity.

None
reference_opd_m float

Known constant reference-region OPD in metres; only applies to a mask.

0.0
mask MaskArray | None

Optional matching C-contiguous uint8 validity mask; zero excludes pixels.

None

Returns:

Type Description
OpticalPathDifferenceResult

Common-grid OPD in metres and phase consistency/order diagnostics.

Raises:

Type Description
FpmError

For shared-complex coupling, invalid references, shapes, or values.

ValueError

Unless exactly one reference choice is supplied.

Notes

Masks are copied; computation releases the GIL. Uses channel metadata for wavelengths and ordering. Fields must be registered with matched spatial resolution and negligible OPD dispersion. See SyntheticWavelengthUnwrapper for the hierarchy and its reference.

write_bundle

write_bundle(
    *,
    path: Path,
    run_id: str | None = None,
    label: str | None = None,
) -> SpectralResultBundle

Persist lossless arrays, trace and spectral solver state; release the GIL.

Parameters:

Name Type Description Default
path Path

Requested local directory; existing destinations get numbered siblings.

required
run_id str | None

Optional unique table/manifest identity; omission generates a UUID.

None
label str | None

Optional human-readable label retained in the manifest.

None

Returns:

Type Description
SpectralResultBundle

Published manifest-last bundle with NPY arrays and Parquet tables.

Raises:

Type Description
FpmError

For invalid/inconsistent state or file failures. Failed publication leaves an in-progress directory. Joint state requires the enclosing MultiWavelengthSolverResult rather than its spectral child.

OpticalPathDifferenceResult

Owned common-grid nondispersive OPD and input-channel-ordered diagnostics.

Every array property returns a writable copy. Invalid pixels have NaN OPD and residual, zero fringe orders, and zero valid_mask. Phase residuals assess consistency but cannot certify correct fringe orders under large noise.

opd_m property

opd_m: FloatArray

Return float64 OPD in metres shaped (rows, columns).

valid_mask property

valid_mask: MaskArray

Return uint8 common-grid validity with one usable and zero invalid.

phase_residual_rad property

phase_residual_rad: FloatArray

Return float64 RMS original-channel wrapped phase residual in radians.

fringe_orders property

fringe_orders: NDArray[int64]

Return integer added cycles shaped (channels, rows, columns).

phase_offsets_rad property

phase_offsets_rad: list[float]

Return applied principal phase pistons in input-channel order.

wavelengths_vacuum_m property

wavelengths_vacuum_m: list[float]

Return vacuum wavelengths in metres in input-channel order.

wavelength_ladder_m property

wavelength_ladder_m: list[float]

Return descending synthetic/original refinement periods in metres.

MultiWavelengthReconstructionResult

Wavelength reconstruction together with its phase-mixed common OPD map.

Returned wrappers retain immutable Rust ownership; their scientific NumPy array getters return independent writable copies.

spectral property

Return wavelength fields, pupils, metadata, and the intensity-fit trace.

opd property

Return the referenced OPD map and phase-mixing diagnostics.

write_bundle

write_bundle(
    *,
    path: Path,
    run_id: str | None = None,
    label: str | None = None,
) -> SpectralResultBundle

Persist lossless arrays, trace and spectral solver state; release the GIL.

Parameters:

Name Type Description Default
path Path

Requested local directory; existing destinations get numbered siblings.

required
run_id str | None

Optional unique table/manifest identity; omission generates a UUID.

None
label str | None

Optional human-readable label retained in the manifest.

None

Returns:

Type Description
SpectralResultBundle

Published manifest-last bundle with NPY arrays and Parquet tables.

Raises:

Type Description
FpmError

For invalid/inconsistent state or file failures. Failed publication leaves an in-progress directory. Joint state requires the enclosing MultiWavelengthSolverResult rather than its spectral child.

MultiWavelengthSolverResult

Joint OPD fit and derived wavelength fields with optional initialization records.

Scientific arrays are independent writable copies. The joint trace starts at iteration zero's constrained initial loss and records post-update full-data smoothed amplitude loss thereafter. Pre-fit phase diagnostics, when present, describe automatic initialization rather than the coupled final fields.

opd_m property

opd_m: FloatArray

Return the optimized float64 common-grid OPD in metres.

spectral property

Return derived fields, channel amplitudes/pupils, and the joint objective trace.

initialization_opd property

initialization_opd: OpticalPathDifferenceResult | None

Return pre-fit phase-mixing diagnostics, or None for explicit OPD starts.

initialization_trace property

initialization_trace: list[tuple[int, float, float]] | None

Return independent AP iteration/objective/time records, or None for explicit starts.

completed_iterations property

completed_iterations: int

Return the number of accepted full-data joint updates.

stopped_early property

stopped_early: bool

Return whether backtracking stopped before the requested update count.

checkpoint property

Return authoritative OPD, amplitudes, bounds, gauge and initialization state.

write_bundle

write_bundle(
    *,
    path: Path,
    run_id: str | None = None,
    label: str | None = None,
) -> SpectralResultBundle

Persist lossless arrays, trace and spectral solver state; release the GIL.

Parameters:

Name Type Description Default
path Path

Requested local directory; existing destinations get numbered siblings.

required
run_id str | None

Optional unique table/manifest identity; omission generates a UUID.

None
label str | None

Optional human-readable label retained in the manifest.

None

Returns:

Type Description
SpectralResultBundle

Published manifest-last bundle with NPY arrays and Parquet tables.

Raises:

Type Description
FpmError

For invalid/inconsistent state or file failures. Failed publication leaves an in-progress directory. Joint state requires the enclosing MultiWavelengthSolverResult rather than its spectral child.

PlanarArrayParameterValues

Absolute inspectable planar-array, power, and frame-gain values.

translation_m instance-attribute

translation_m: tuple[float, float, float]

Absolute array-pose translation (tx, ty, tz) in metres.

rotation_rad instance-attribute

rotation_rad: tuple[float, float, float]

Absolute active extrinsic XYZ rotation angles in radians.

pitch_m instance-attribute

pitch_m: tuple[float, float]

Absolute column and row pitch in metres.

reference_index instance-attribute

reference_index: tuple[float, float]

Absolute fractional reference column and row.

position_offsets_m instance-attribute

position_offsets_m: list[tuple[float, float, float]]

Row-major per-source XYZ offsets in metres.

relative_source_power instance-attribute

relative_source_power: list[float]

Mean-one relative intensity for every source.

frame_gains instance-attribute

frame_gains: list[float]

Mean-one intensity gain for every acquisition frame.

CalibrationParameterHistoryEntry

One accepted or rejected bounded parameter trial.

outer_iteration instance-attribute

outer_iteration: int

One-based alternating-reconstruction iteration.

optimizer_step instance-attribute

optimizer_step: int

One-based physical optimizer step within the phase.

accepted instance-attribute

accepted: bool

Whether this trial reduced the regularized objective.

step_size instance-attribute

step_size: float

Attempted line-search step in normalized coordinates.

normalized_values instance-attribute

normalized_values: list[float]

Parameter values relative to their initial values and scales.

CalibrationLossHistoryEntry

Data, regularization, and total loss for one physical trial.

outer_iteration instance-attribute

outer_iteration: int

One-based alternating-reconstruction iteration.

optimizer_step instance-attribute

optimizer_step: int

One-based physical optimizer step within the phase.

total_loss instance-attribute

total_loss: float

Sum of the canonical data loss and all configured priors.

data_loss instance-attribute

data_loss: float

Masked and frame-weighted measurement-domain loss.

regularization_loss instance-attribute

regularization_loss: float

Sum of configured quadratic prior and regularization contributions.

accepted instance-attribute

accepted: bool

Whether the corresponding parameter trial was accepted.

CalibrationConditioning

Practical scaled sensitivity and curvature diagnostics, not uncertainty.

parameter_names instance-attribute

parameter_names: list[str]

Stable names corresponding to every diagnostic vector entry.

scaled_sensitivities instance-attribute

scaled_sensitivities: list[float]

Absolute finite-difference derivatives in normalized coordinates.

scaled_diagonal_curvature instance-attribute

scaled_diagonal_curvature: list[float]

Finite-difference diagonal curvature estimates in normalized coordinates.

diagonal_condition_estimate instance-attribute

diagonal_condition_estimate: float | None

Largest-to-smallest useful diagonal-curvature ratio, when defined.

parameters_at_bounds instance-attribute

parameters_at_bounds: list[str]

Names whose final physical values meet a configured bound.

rejected_steps instance-attribute

rejected_steps: int

Cumulative number of rejected line-search trials.

warnings instance-attribute

warnings: list[str]

Human-readable weak-identifiability and numerical warnings.

IlluminationCalibrationState

Checkpointable physical values, gauges, histories, and update counters.

initial_illumination instance-attribute

initial_illumination: Illumination

Serializable illumination supplied before gauge normalization.

current_illumination instance-attribute

current_illumination: Illumination

Current normal serializable calibrated illumination.

initial_parameters instance-attribute

initial_parameters: PlanarArrayParameterValues

Immutable absolute values at initialization.

current_parameters instance-attribute

current_parameters: PlanarArrayParameterValues

Current absolute physical and multiplicative values.

parameter_names instance-attribute

parameter_names: list[str]

Stable ordered names of active scalar optimization variables.

normalized_variables instance-attribute

normalized_variables: list[float]

Current values relative to initial values and configured scales.

applied_constraints instance-attribute

applied_constraints: list[str]

Inspectable gauge constraints imposed by the calibrator.

parameter_history instance-attribute

parameter_history: list[CalibrationParameterHistoryEntry]

Accepted and rejected bounded optimizer trials.

loss_history instance-attribute

loss_history: list[CalibrationLossHistoryEntry]

Canonical data, regularization, and total objective history.

convergence_reason instance-attribute

convergence_reason: str | None

Most recent physical optimizer termination reason.

conditioning instance-attribute

Practical finite-difference conditioning summary.

geometry_recompilations instance-attribute

geometry_recompilations: int

Cumulative accepted and trial geometry-dependent model updates.

multiplicative_updates instance-attribute

multiplicative_updates: int

Cumulative accepted and trial intensity-only model updates.

rejected_steps instance-attribute

rejected_steps: int

Cumulative rejected physical optimizer trials.

BrightfieldCircleObservation

Circle-localization diagnostics for one acquisition frame.

Fourier-grid coordinates are (row, column) floating-point indices. Wave-vector coordinates are (kx, ky) in radians per metre, while NA coordinates are the corresponding dimensionless transverse components.

frame_index instance-attribute

frame_index: int

Zero-based acquisition-frame index.

source_index instance-attribute

source_index: int

Stable row-major physical source index.

nominal_k_rad_per_m instance-attribute

nominal_k_rad_per_m: FloatArray

Owned float64 (2,) nominal (kx, ky) in radians per metre.

detected_k_rad_per_m instance-attribute

detected_k_rad_per_m: FloatArray | None

Owned float64 (2,) detected (kx, ky), if accepted.

detected_na instance-attribute

detected_na: FloatArray | None

Owned float64 (2,) dimensionless (NA_x, NA_y), if accepted.

fourier_grid_position instance-attribute

fourier_grid_position: FloatArray | None

Owned float64 (2,) centered (row, column) position.

fitted_pupil_radius_na instance-attribute

fitted_pupil_radius_na: float

Best pupil radius for this frame in NA.

first_derivative_score instance-attribute

first_derivative_score: float

Normalized first-radial-derivative score.

second_derivative_score instance-attribute

second_derivative_score: float

Normalized second-radial-derivative score.

combined_score instance-attribute

combined_score: float

Combined deterministic circle score.

conjugate_score instance-attribute

conjugate_score: float

Score at the centrosymmetric branch corresponding to -k.

usable_arc_fraction instance-attribute

usable_arc_fraction: float

Fraction of angular samples used by the score.

confidence instance-attribute

confidence: float

Fixed confidence weight supplied to the physical fit.

negative_sample_fraction instance-attribute

negative_sample_fraction: float

Fraction of background-corrected spatial samples below zero.

rejection_reason instance-attribute

rejection_reason: str | None

Human-readable rejection reason, or None when accepted.

accepted instance-attribute

accepted: bool

Whether this center contributes to the physical fit.

PlanarArrayInitializationFitRecord

One accepted or rejected bounded physical-fit step.

step instance-attribute

step: int

One-based optimizer step.

accepted instance-attribute

accepted: bool

Whether a bounded line-search candidate reduced the objective.

step_size instance-attribute

step_size: float

Accepted normalized step size, or zero after exhaustion.

data_loss instance-attribute

data_loss: float

Confidence-weighted robust Huber loss over accepted NA-center residuals.

regularization_loss instance-attribute

regularization_loss: float

Sum of configured quadratic physical-parameter prior contributions.

total_loss instance-attribute

total_loss: float

Sum of data and regularization losses.

normalized_values instance-attribute

normalized_values: list[float]

Current normalized values in result parameter_names order.

PlanarArrayInitializationDiagnostics

Detection, rank, and residual summary for one initialization.

candidate_frames instance-attribute

candidate_frames: int

Number of acquisition frames considered.

accepted_observations instance-attribute

accepted_observations: int

Number of centers used by the physical fit.

rejected_observations instance-attribute

rejected_observations: int

Number of rejected center observations.

configured_pupil_radius_na instance-attribute

configured_pupil_radius_na: float

Objective pupil radius configured in Optics.

fitted_pupil_radius_na instance-attribute

fitted_pupil_radius_na: float

Confidence-weighted detected pupil radius in NA.

jacobian_rank instance-attribute

jacobian_rank: int

Rank of the observation Jacobian before priors.

active_parameter_count instance-attribute

active_parameter_count: int

Number of active scalar physical parameters.

jacobian_condition_estimate instance-attribute

jacobian_condition_estimate: float | None

Pivot-based squared condition estimate when defined.

initial_residual_rms_na instance-attribute

initial_residual_rms_na: float

Initial confidence-weighted center residual RMS in NA.

final_residual_rms_na instance-attribute

final_residual_rms_na: float

Final confidence-weighted center residual RMS in NA.

warnings instance-attribute

warnings: list[str]

Nonfatal data-quality and conditioning warnings.

PlanarArrayInitializationRuntime

Timing and evaluation counts for one initialization.

elapsed_seconds instance-attribute

elapsed_seconds: float

Wall-clock duration in seconds.

measurement_passes instance-attribute

measurement_passes: int

Number of complete measurement passes; currently two.

physical_objective_evaluations instance-attribute

physical_objective_evaluations: int

Number of bounded physical-objective evaluations.

PlanarArrayInitializationResult

Versioned, fully serializable physical initialization result.

format_version instance-attribute

format_version: int

Version of the complete initialization-result JSON representation.

nominal_illumination instance-attribute

nominal_illumination: Illumination

Nominal illumination supplied to the initializer.

initialized_illumination instance-attribute

initialized_illumination: Illumination

Reusable illumination containing the fitted physical geometry.

initialized_model instance-attribute

initialized_model: ImagePlaneModel

Reusable model atomically refreshed from the initialized illumination.

parameters instance-attribute

Physical parameter selection and bounds used by the fit.

options instance-attribute

Detector and optimizer controls used by this run.

initial_parameters instance-attribute

initial_parameters: PlanarArrayParameterValues

Absolute nominal physical and multiplicative values.

initialized_parameters instance-attribute

initialized_parameters: PlanarArrayParameterValues

Absolute initialized physical and unchanged multiplicative values.

parameter_names instance-attribute

parameter_names: list[str]

Stable active physical parameter names.

observations instance-attribute

observations: list[BrightfieldCircleObservation]

Detector result for every considered acquisition frame.

fit_history instance-attribute

Accepted and rejected bounded physical-fit records.

diagnostics instance-attribute

Detection, rank, and residual summary.

runtime instance-attribute

Timing and evaluation counts.

save_json

save_json(path: Path) -> None

Validate and write the complete result as UTF-8 JSON.

write_bundle

write_bundle(path: Path) -> InitializationBundle

Atomically write and reopen a verified initialization bundle.

load_json staticmethod

Load and validate a complete initialization result.

JointReconstructionResult

Structured reconstruction, reusable illumination/model, and calibration history.

reconstruction instance-attribute

reconstruction: ReconstructionResult

Canonical reconstruction result including physical calibration state.

initial_illumination instance-attribute

initial_illumination: Illumination

Serializable illumination supplied to the joint algorithm.

calibrated_illumination instance-attribute

calibrated_illumination: Illumination

Final reusable planar-array illumination.

calibrated_model instance-attribute

calibrated_model: ImagePlaneModel

Compiled final model suitable for continued reconstruction.

initial_parameters instance-attribute

initial_parameters: PlanarArrayParameterValues

Immutable absolute physical and multiplicative starting values.

final_parameters instance-attribute

final_parameters: PlanarArrayParameterValues

Final absolute physical and multiplicative parameter values.

parameter_history instance-attribute

parameter_history: list[CalibrationParameterHistoryEntry]

Accepted and rejected optimizer-trial history.

loss_history instance-attribute

loss_history: list[CalibrationLossHistoryEntry]

Data, prior, and total physical objective history.

convergence_reason instance-attribute

convergence_reason: str | None

Final physical optimizer termination reason.

conditioning instance-attribute

Final practical finite-difference conditioning diagnostics.

diagnostics instance-attribute

Complete checkpointable physical-calibration state and counters.

save_json

save_json(path: Path) -> None

Serialize the complete structured joint result to path.

load_json staticmethod

load_json(path: Path) -> JointReconstructionResult

Load and validate a complete structured joint JSON result.

write_bundle

write_bundle(
    path: Path,
    *,
    run_id: str | None = None,
    label: str | None = None,
    include_previews: bool = True,
) -> ResultBundle

Write a verified result bundle including physical calibration state.

Result bundles

BundleArtifact

Manifest metadata for one file in a result or benchmark bundle.

path instance-attribute

path: Path

Absolute path to the artifact in the opened bundle.

media_type instance-attribute

media_type: str

Declared MIME media type.

byte_size instance-attribute

byte_size: int

Expected file size in bytes.

sha256 instance-attribute

sha256: str

Expected lowercase SHA-256 digest.

role instance-attribute

role: str

Stable semantic role recorded in the manifest.

BundleArray

Lazily loaded NPY array artifact.

Accessing value validates and caches a read-only NumPy array.

path instance-attribute

path: Path

Absolute path to the NPY file.

media_type instance-attribute

media_type: str

Declared MIME media type.

byte_size instance-attribute

byte_size: int

Expected file size in bytes.

sha256 instance-attribute

sha256: str

Expected lowercase SHA-256 digest.

role instance-attribute

role: str

Stable semantic array role.

value instance-attribute

Read-only array, loaded and cached on first access.

BundleTables

Parquet table artifacts present in a result bundle.

summary instance-attribute

summary: BundleArtifact

One-row run summary table.

history instance-attribute

history: BundleArtifact

Per-iteration objective and timing history.

algorithm_metrics instance-attribute

algorithm_metrics: BundleArtifact | None

Optional algorithm-specific metric records.

iteration_diagnostics instance-attribute

iteration_diagnostics: BundleArtifact | None

Optional per-iteration diagnostic records.

frame_diagnostics instance-attribute

frame_diagnostics: BundleArtifact | None

Optional per-frame residual summaries.

raw_frame_statistics instance-attribute

raw_frame_statistics: BundleArtifact | None

Optional raw measurement-frame statistics.

frame_evaluation instance-attribute

frame_evaluation: BundleArtifact | None

Optional per-frame ground-truth evaluation records.

illumination_calibration instance-attribute

illumination_calibration: BundleArtifact | None

Optional recovered illumination-calibration table.

frame_calibration instance-attribute

frame_calibration: BundleArtifact | None

Optional recovered frame-gain and background table.

scalar_diagnostics instance-attribute

scalar_diagnostics: BundleArtifact | None

Optional named scalar-diagnostic table.

metadata instance-attribute

metadata: BundleArtifact | None

Optional key-value result metadata table.

BundleArrays

Lazy numerical-array artifacts in a result bundle.

object instance-attribute

object: BundleArray

Reconstructed complex object field.

object_spectrum instance-attribute

object_spectrum: BundleArray

Centered complex object spectrum.

pupil instance-attribute

pupil: BundleArray

Final recovered complex pupil array.

pupil_support instance-attribute

pupil_support: BundleArray

Uint8 pupil-support mask.

illumination_calibration instance-attribute

illumination_calibration: BundleArray | None

Optional recovered source-offset array.

frame_gains instance-attribute

frame_gains: BundleArray | None

Optional recovered frame-gain array.

background instance-attribute

background: BundleArray | None

Optional recovered frame-background array.

BundlePreviews

Optional PNG preview artifacts derived during bundle export.

object_amplitude instance-attribute

object_amplitude: BundleArtifact | None

Object-amplitude preview, if requested.

object_phase instance-attribute

object_phase: BundleArtifact | None

Object-phase preview, if requested.

pupil_amplitude instance-attribute

pupil_amplitude: BundleArtifact | None

Pupil-amplitude preview, if requested.

pupil_phase instance-attribute

pupil_phase: BundleArtifact | None

Pupil-phase preview, if requested.

fourier_coverage instance-attribute

fourier_coverage: BundleArtifact | None

Fourier-coverage preview when coverage diagnostics are available.

BundleVerificationResult

Summary returned after all manifest artifacts pass verification.

artifact_count instance-attribute

artifact_count: int

Number of files whose size and digest were verified.

total_bytes instance-attribute

total_bytes: int

Total verified payload size in bytes.

ResultBundle

Opened result bundle with eager metadata and lazy arrays.

read_bundle validates the manifest and file layout. Individual file sizes and hashes are checked when artifacts are loaded, or all at once by verify.

path instance-attribute

path: Path

Absolute path to the opened bundle directory.

manifest_path instance-attribute

manifest_path: Path

Absolute JSON manifest path.

run_id instance-attribute

run_id: str

Stable run identifier from the manifest.

label instance-attribute

label: str | None

Optional human-readable bundle label.

tables instance-attribute

tables: BundleTables

Parquet table artifact descriptors in this bundle.

arrays instance-attribute

arrays: BundleArrays

Lazy NPY artifact descriptors.

previews instance-attribute

previews: BundlePreviews

Optional image-preview descriptors.

result instance-attribute

Lazily reconstructed result backed by cached read-only arrays.

diagnostics instance-attribute

diagnostics: dict[str, Any] | None

Structured reconstruction diagnostics, if stored.

evaluation instance-attribute

evaluation: dict[str, Any] | None

Structured ground-truth evaluation, if stored.

verify

Verify sizes and SHA-256 digests for every manifest artifact.

clear_cache

clear_cache() -> None

Release cached arrays and reconstructed result values.

InitializationBundleArtifact

Manifest-verified file inside an initialization bundle.

role instance-attribute

role: str

Stable semantic artifact role.

path instance-attribute

path: Path

Resolved local artifact path.

media_type instance-attribute

media_type: str

Declared MIME media type.

byte_size instance-attribute

byte_size: int

Exact artifact size in bytes.

sha256 instance-attribute

sha256: str

Lowercase hexadecimal SHA-256 digest.

InitializationBundleVerificationResult

Aggregate result of verifying every bundle artifact.

artifact_count instance-attribute

artifact_count: int

Number of artifacts verified.

total_bytes instance-attribute

total_bytes: int

Sum of verified artifact sizes in bytes.

InitializationBundle

Verified initialization result plus normalized CSV table handles.

path instance-attribute

path: Path

Root directory containing the verified initialization artifacts.

manifest_path instance-attribute

manifest_path: Path

Bundle manifest JSON path.

result_artifact instance-attribute

Authoritative complete-result JSON artifact.

observations_artifact instance-attribute

observations_artifact: InitializationBundleArtifact

Per-frame circle-observation CSV artifact.

fit_history_artifact instance-attribute

fit_history_artifact: InitializationBundleArtifact

Bounded physical-fit history CSV artifact.

result instance-attribute

Validated authoritative physical initialization result.

verify

Recompute every artifact size and SHA-256 digest.

read_initialization_bundle

read_initialization_bundle(
    path: Path,
) -> InitializationBundle

Open and verify a planar-array initialization bundle.

read_bundle

read_bundle(path: Path) -> ResultBundle

Validate a result-bundle manifest and open its artifacts lazily.

Benchmark bundles

BenchmarkBundleTables

Parquet artifact descriptors in a benchmark bundle.

runs instance-attribute

One summary row per benchmark run.

frames instance-attribute

Per-frame benchmark records.

artifacts instance-attribute

artifacts: BundleArtifact

Inventory linking run IDs to nested result bundles.

metadata instance-attribute

metadata: BundleArtifact

Benchmark-suite key-value metadata.

BenchmarkBundle

Opened benchmark suite and its nested result bundles.

path instance-attribute

path: Path

Absolute benchmark-bundle directory.

manifest_path instance-attribute

manifest_path: Path

Absolute JSON manifest path.

name instance-attribute

name: str

Stable benchmark-suite name from the manifest.

label instance-attribute

label: str | None

Optional human-readable suite label.

tables instance-attribute

Benchmark-level Parquet artifacts.

results instance-attribute

results: Mapping[str, ResultBundle]

Nested result bundles keyed by run ID.

BenchmarkSuite

BenchmarkSuite(name: str)

Mutable collection used to export comparable reconstruction runs.

name must be nonempty and identifies the suite in the bundle manifest.

add_result

add_result(
    result: ReconstructionResult,
    *,
    case_id: str,
    dataset_name: str,
    algorithm_configuration: str = "",
    dataset_subset: DatasetSubset | None = None,
) -> str

Add a completed result and return its fresh, unique run ID.

case_id and dataset_name must be nonempty. The optional configuration string distinguishes algorithm settings for reporting.

Parameters:

Name Type Description Default
dataset_subset DatasetSubset | None

Resolved subset used for this result. Records original acquisition frame indices, optional illumination identifiers, detector crop, dataset version, provenance, and units. Frame count and low/high resolution shapes must match the result; otherwise InvalidParameterError. Residual metrics are not recomputed. Omit to retain the existing result-only, sequential-frame record.

None

write_bundle

write_bundle(
    path: Path, *, label: str | None = None
) -> BenchmarkBundle

Write the suite and nested result bundles, then reopen it lazily.

read_benchmark_bundle

read_benchmark_bundle(path: Path) -> BenchmarkBundle

Validate and lazily open a benchmark bundle directory.

SpectralReconstructionCheckpoint

Separately versioned spectral AP or joint OPD iteration-boundary snapshot.

Preserves exact ordered compiled channels and a streaming SHA-256 of detector values, masks and frame weights. Joint state retains bounds, fixed gauge and initialization diagnostics. Scientific state/objectives resume exactly; elapsed times accumulate. Stepping options must match, but the total target may grow. Ordinary reconstruction checkpoints are rejected. Getters return writable copies.

format_version instance-attribute

format_version: int

Independent spectral checkpoint schema version, currently one.

completed_iterations instance-attribute

completed_iterations: int

Completed spectral passes or accepted joint updates, including earlier runs.

algorithm instance-attribute

algorithm: str

Solver name determining the compatible resume entry point.

model instance-attribute

Owned compiled channels, sparse detector plan and fixed calibration metadata.

trace instance-attribute

trace: list[tuple[int, float, float]]

Accumulated iteration, objective and elapsed-second records.

opd_m instance-attribute

opd_m: FloatArray | None

Copied float64 common-grid joint OPD in metres; None for AP.

load staticmethod

Load and validate local spectral JSON while releasing the GIL.

Parameters:

Name Type Description Default
path Path

Existing spectral checkpoint file; malformed or ordinary state raises FpmError. The solver additionally verifies its problem fingerprint.

required

Returns:

Type Description
SpectralReconstructionCheckpoint

Validated solver snapshot with owned numerical state.

save

save(*, path: Path) -> None

Atomically replace local JSON with lossless validated iteration state.

Parameters:

Name Type Description Default
path Path

Destination file with an existing parent directory. File work releases the GIL; failures raise FpmError and leave an existing destination intact.

required

SpectralResultBundle

Separately tagged spectral persistence with lazy verified numerical loading.

Contains channel NPY arrays, Parquet trace/metadata, and resumable JSON state. Optional records preserve joint OPD or phase-mixing diagnostics. Result array getters return independent writable copies; the Rust result cache is immutable. File loading and verification release the GIL. Ordinary bundles are rejected.

path instance-attribute

path: Path

Canonical local published directory containing manifest.json.

run_id instance-attribute

run_id: str

Stable table and manifest identity supplied on export.

label instance-attribute

label: str | None

Optional human-readable export label retained in the manifest.

artifacts instance-attribute

artifacts: dict[str, BundleArtifact]

NPY, Parquet and checkpoint descriptors indexed by semantic role.

result instance-attribute

Verified channel arrays and trace; getters yield independent writable copies.

checkpoint instance-attribute

Verified final resumable solver state, preserving exact metadata and gauge.

joint_result instance-attribute

joint_result: MultiWavelengthSolverResult | None

Authoritative joint OPD result and initialization records, or None for AP.

unwrapped_opd instance-attribute

unwrapped_opd: OpticalPathDifferenceResult | None

Optional post-AP phase-mixing diagnostics, preserving invalid NaN pixels.

verify

Check every artifact hash/size, numerical state and table consistency.

clear_cache

clear_cache() -> None

Release cached channel arrays so the next read reloads and verifies them.

read_spectral_bundle

read_spectral_bundle(path: Path) -> SpectralResultBundle

Open a spectral manifest without loading scientific arrays; release the GIL.

Parameters:

Name Type Description Default
path Path

Existing spectral directory. Unsafe paths, invalid descriptors, wrong kind/version or missing artifacts raise FpmError; ordinary bundles fail.

required

Returns:

Type Description
SpectralResultBundle

Lazy verified channel fields, checkpoint and optional OPD records.