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.
completed_iterations
property
¶
completed_iterations: int
Return the number of complete iterations represented by the state.
load
staticmethod
¶
load(path: Path) -> ReconstructionCheckpoint
Read and validate a checkpoint file without holding the Python GIL.
RuntimeInfo
¶
Execution summary attached to a reconstruction result.
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.
amplitude
instance-attribute
¶
amplitude: FloatArray
Magnitude of the reconstructed complex object field.
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
¶
checkpoint: SpectralReconstructionCheckpoint | None
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 |
None
|
reference_mask
|
MaskArray | None
|
Alternative C-contiguous uint8 |
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.
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
¶
spectral: SpectralReconstructionResult
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.
spectral
property
¶
spectral: SpectralReconstructionResult
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
¶
checkpoint: SpectralReconstructionCheckpoint
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.
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.
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.
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
¶
conditioning: CalibrationConditioning
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.
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.
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.
PlanarArrayInitializationFitRecord
¶
One accepted or rejected bounded physical-fit 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.
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.
PlanarArrayInitializationRuntime
¶
Timing and evaluation counts for one initialization.
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
¶
parameters: PlanarArrayCalibrationParameters
Physical parameter selection and bounds used by the fit.
options
instance-attribute
¶
options: BrightfieldCircleOptions
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
¶
fit_history: list[PlanarArrayInitializationFitRecord]
Accepted and rejected bounded physical-fit records.
diagnostics
instance-attribute
¶
diagnostics: PlanarArrayInitializationDiagnostics
Detection, rank, and residual summary.
runtime
instance-attribute
¶
runtime: PlanarArrayInitializationRuntime
Timing and evaluation counts.
write_bundle
¶
write_bundle(path: Path) -> InitializationBundle
Atomically write and reopen a verified initialization bundle.
load_json
staticmethod
¶
load_json(path: Path) -> PlanarArrayInitializationResult
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
¶
conditioning: CalibrationConditioning
Final practical finite-difference conditioning diagnostics.
diagnostics
instance-attribute
¶
diagnostics: IlluminationCalibrationState
Complete checkpointable physical-calibration state and counters.
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.
BundleArray
¶
Lazily loaded NPY array artifact.
Accessing value validates and caches a
read-only NumPy array.
value
instance-attribute
¶
value: ComplexArray | FloatArray | MaskArray
Read-only array, loaded and cached on first access.
BundleTables
¶
Parquet table artifacts present in a result bundle.
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.
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
¶
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.
result
instance-attribute
¶
result: ReconstructionResult
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() -> BundleVerificationResult
Verify sizes and SHA-256 digests for every manifest artifact.
InitializationBundleArtifact
¶
Manifest-verified file inside an initialization bundle.
InitializationBundleVerificationResult
¶
InitializationBundle
¶
Verified initialization result plus normalized CSV table handles.
path
instance-attribute
¶
path: Path
Root directory containing the verified initialization artifacts.
result_artifact
instance-attribute
¶
result_artifact: InitializationBundleArtifact
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
¶
result: PlanarArrayInitializationResult
Validated authoritative physical initialization result.
verify
¶
verify() -> InitializationBundleVerificationResult
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.
artifacts
instance-attribute
¶
artifacts: BundleArtifact
Inventory linking run IDs to nested result bundles.
BenchmarkBundle
¶
Opened benchmark suite and its nested result bundles.
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
|
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
¶
model: SpectralImagePlaneModel
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(*, path: Path) -> SpectralReconstructionCheckpoint
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.
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
¶
result: SpectralReconstructionResult
Verified channel arrays and trace; getters yield independent writable copies.
checkpoint
instance-attribute
¶
checkpoint: SpectralReconstructionCheckpoint
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
¶
verify() -> BundleVerificationResult
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. |