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` ¶

load(path: Path) -> ReconstructionCheckpoint

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.

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` ¶

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.

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` ¶

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.

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_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.

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` ¶

value: ComplexArray | FloatArray | MaskArray

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` ¶

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.

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` ¶

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.

runs `instance-attribute` ¶

runs: BundleArtifact

One summary row per benchmark run.

frames `instance-attribute` ¶

frames: BundleArtifact

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` ¶

tables: BenchmarkBundleTables

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 = "",
) -> str

Add a completed result and return its deterministic run ID.

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

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.

Results and bundles¶

Results and checkpoints¶

ReconstructionCheckpoint ¶

format_version property ¶

completed_iterations property ¶

load staticmethod ¶

save ¶

RuntimeInfo ¶

elapsed_seconds instance-attribute ¶

completed_iterations instance-attribute ¶

stopped_early instance-attribute ¶

algorithm instance-attribute ¶

ReconstructionResult ¶

object instance-attribute ¶

amplitude instance-attribute ¶

phase instance-attribute ¶

object_spectrum instance-attribute ¶

recovered_pupil instance-attribute ¶

pupil_support instance-attribute ¶

calibrated_illumination instance-attribute ¶

recovered_frame_gains instance-attribute ¶

recovered_background instance-attribute ¶

physical_illumination_calibration instance-attribute ¶

calibrated_model instance-attribute ¶

trace instance-attribute ¶

algorithm_metrics instance-attribute ¶

scalar_diagnostics instance-attribute ¶

runtime instance-attribute ¶

metadata instance-attribute ¶

final_objective instance-attribute ¶

write_bundle ¶

PlanarArrayParameterValues ¶

translation_m instance-attribute ¶

rotation_rad instance-attribute ¶

pitch_m instance-attribute ¶

reference_index instance-attribute ¶

position_offsets_m instance-attribute ¶

relative_source_power instance-attribute ¶

frame_gains instance-attribute ¶

CalibrationParameterHistoryEntry ¶

outer_iteration instance-attribute ¶

optimizer_step instance-attribute ¶

accepted instance-attribute ¶

step_size instance-attribute ¶

normalized_values instance-attribute ¶

CalibrationLossHistoryEntry ¶

outer_iteration instance-attribute ¶

optimizer_step instance-attribute ¶

total_loss instance-attribute ¶

data_loss instance-attribute ¶

regularization_loss instance-attribute ¶

accepted instance-attribute ¶

CalibrationConditioning ¶

parameter_names instance-attribute ¶

scaled_sensitivities instance-attribute ¶

scaled_diagonal_curvature instance-attribute ¶

diagonal_condition_estimate instance-attribute ¶

parameters_at_bounds instance-attribute ¶

rejected_steps instance-attribute ¶

warnings instance-attribute ¶

IlluminationCalibrationState ¶

initial_illumination instance-attribute ¶

current_illumination instance-attribute ¶

initial_parameters instance-attribute ¶

current_parameters instance-attribute ¶

parameter_names instance-attribute ¶

normalized_variables instance-attribute ¶

applied_constraints instance-attribute ¶

parameter_history instance-attribute ¶

loss_history instance-attribute ¶

convergence_reason instance-attribute ¶

conditioning instance-attribute ¶

geometry_recompilations instance-attribute ¶

multiplicative_updates instance-attribute ¶

rejected_steps instance-attribute ¶

BrightfieldCircleObservation ¶

frame_index instance-attribute ¶

source_index instance-attribute ¶

nominal_k_rad_per_m instance-attribute ¶

detected_k_rad_per_m instance-attribute ¶

format_version `property` ¶

completed_iterations `property` ¶

load `staticmethod` ¶

elapsed_seconds `instance-attribute` ¶

completed_iterations `instance-attribute` ¶

stopped_early `instance-attribute` ¶

algorithm `instance-attribute` ¶

object `instance-attribute` ¶

amplitude `instance-attribute` ¶

phase `instance-attribute` ¶

object_spectrum `instance-attribute` ¶

recovered_pupil `instance-attribute` ¶

pupil_support `instance-attribute` ¶

calibrated_illumination `instance-attribute` ¶

recovered_frame_gains `instance-attribute` ¶

recovered_background `instance-attribute` ¶

physical_illumination_calibration `instance-attribute` ¶

calibrated_model `instance-attribute` ¶

trace `instance-attribute` ¶

algorithm_metrics `instance-attribute` ¶

scalar_diagnostics `instance-attribute` ¶

runtime `instance-attribute` ¶

metadata `instance-attribute` ¶

final_objective `instance-attribute` ¶

translation_m `instance-attribute` ¶

rotation_rad `instance-attribute` ¶

pitch_m `instance-attribute` ¶

reference_index `instance-attribute` ¶

position_offsets_m `instance-attribute` ¶

relative_source_power `instance-attribute` ¶

frame_gains `instance-attribute` ¶

outer_iteration `instance-attribute` ¶

optimizer_step `instance-attribute` ¶

accepted `instance-attribute` ¶

step_size `instance-attribute` ¶

normalized_values `instance-attribute` ¶

outer_iteration `instance-attribute` ¶

optimizer_step `instance-attribute` ¶

total_loss `instance-attribute` ¶

data_loss `instance-attribute` ¶

regularization_loss `instance-attribute` ¶

accepted `instance-attribute` ¶

parameter_names `instance-attribute` ¶

scaled_sensitivities `instance-attribute` ¶

scaled_diagonal_curvature `instance-attribute` ¶

diagonal_condition_estimate `instance-attribute` ¶

parameters_at_bounds `instance-attribute` ¶

rejected_steps `instance-attribute` ¶

warnings `instance-attribute` ¶

initial_illumination `instance-attribute` ¶

current_illumination `instance-attribute` ¶

initial_parameters `instance-attribute` ¶

current_parameters `instance-attribute` ¶

parameter_names `instance-attribute` ¶

normalized_variables `instance-attribute` ¶

applied_constraints `instance-attribute` ¶

parameter_history `instance-attribute` ¶

loss_history `instance-attribute` ¶

convergence_reason `instance-attribute` ¶

conditioning `instance-attribute` ¶

geometry_recompilations `instance-attribute` ¶

multiplicative_updates `instance-attribute` ¶

rejected_steps `instance-attribute` ¶

frame_index `instance-attribute` ¶

source_index `instance-attribute` ¶

nominal_k_rad_per_m `instance-attribute` ¶

detected_k_rad_per_m `instance-attribute` ¶

detected_na `instance-attribute` ¶

fourier_grid_position `instance-attribute` ¶

fitted_pupil_radius_na `instance-attribute` ¶

first_derivative_score `instance-attribute` ¶

second_derivative_score `instance-attribute` ¶

combined_score `instance-attribute` ¶

conjugate_score `instance-attribute` ¶

usable_arc_fraction `instance-attribute` ¶

confidence `instance-attribute` ¶

negative_sample_fraction `instance-attribute` ¶

rejection_reason `instance-attribute` ¶

accepted `instance-attribute` ¶

step `instance-attribute` ¶