Reconstruction and callbacks

Problems and results

ReconstructionProblem(measurements: FloatArray | MeasurementStack, model: ImagePlaneModel, *, frame_weights: Sequence[float] | None = None, masks: MaskArray | None = None, name: str | None = None)

Validated pairing of measurements and a compiled image-plane model.

frame_count: int property

image_shape: Shape2D property

name: str | None property

reconstruction_shape: Shape2D property

ReconstructionCheckpoint

completed_iterations: int property

format_version: int property

load(path: Path) -> ReconstructionCheckpoint staticmethod

save(path: Path) -> None

RuntimeInfo

algorithm: str instance-attribute

completed_iterations: int instance-attribute

elapsed_seconds: float instance-attribute

stopped_early: bool instance-attribute

ReconstructionResult

admm_residual_history: list[tuple[int, float, float]] instance-attribute

amplitude: FloatArray instance-attribute

calibrated_illumination: FloatArray | None instance-attribute

diagnostics: Mapping[str, float] instance-attribute

final_loss: float | None instance-attribute

history: list[tuple[int, float, float]] instance-attribute

metadata: Mapping[str, str] instance-attribute

object: ComplexArray instance-attribute

object_spectrum: ComplexArray instance-attribute

phase: FloatArray instance-attribute

pupil_support: MaskArray instance-attribute

recovered_background: FloatArray | None instance-attribute

recovered_frame_gains: FloatArray | None instance-attribute

recovered_pupil: ComplexArray instance-attribute

runtime: RuntimeInfo instance-attribute

Algorithms

AlternatingProjection(*, iterations: int = 50, object_step: float = 1.0, batch_size: int = 1, epsilon: float = 1e-10, loss_type: str = 'amplitude_mse')

Bases: _Algorithm

Alternating-projection FPM reconstruction.

Each frame selects an overlapping object-spectrum patch, propagates it through the pupil, replaces the predicted detector amplitude with the measured amplitude while retaining phase, and back-projects the correction.

Parameters: iterations: Complete passes through the acquisition schedule. object_step: Relaxation factor for object-spectrum corrections. batch_size: Measured frames supplied to each reconstruction step. epsilon: Positive numerical floor for divisions and dark fields. loss_type: Diagnostic loss; the projection always enforces amplitude.

Reference: G. Zheng, R. Horstmeyer, and C. Yang, "Wide-field, high-resolution Fourier ptychographic microscopy," Nature Photonics 7, 739-745 (2013), doi:10.1038/nphoton.2013.187.

run(problem: ReconstructionProblem, *, callbacks: Iterable[Callback] | None = None, resume_from: ReconstructionCheckpoint | None = None, schedule: str = 'sequential', schedule_seed: int = 0) -> ReconstructionResult

Fpie(*, iterations: int = 50, object_step: float = 0.8, stability: float = 0.1, batch_size: int = 1, epsilon: float = 1e-10, loss_type: str = 'amplitude_mse')

Bases: _Algorithm

Regularized ptychographic iterative engine adapted to FPM.

The amplitude-projection correction is preconditioned by a blend of local and maximum pupil power, suppressing unstable updates in weak-transfer regions.

Parameters: iterations: Complete passes through the acquisition schedule. object_step: Relaxation factor for object-spectrum corrections. stability: Blend from local (0) to maximum (1) pupil power. batch_size: Measured frames supplied to each reconstruction step. epsilon: Positive floor added to the rPIE denominator. loss_type: Diagnostic loss; the projection always enforces amplitude.

Reference: A. Maiden, D. Johnson, and P. Li, "Further improvements to the ptychographical iterative engine," Optica 4(7), 736-745 (2017), doi:10.1364/OPTICA.4.000736.

run(problem: ReconstructionProblem, *, callbacks: Iterable[Callback] | None = None, resume_from: ReconstructionCheckpoint | None = None, schedule: str = 'sequential', schedule_seed: int = 0) -> ReconstructionResult

Epry(*, iterations: int = 100, object_step: float = 0.8, pupil_step: float = 0.1, batch_size: int = 1, recover_pupil: bool = True, constrain_pupil_support: bool = True, recover_frame_gains: bool = False, gain_step: float = 0.2, gain_bounds: tuple[float, float] = (1e-06, 1000000.0), recover_background: bool = False, background_step: float = 0.2, background_bounds: tuple[float, float] = (0.0, 1000000000000.0), epsilon: float = 1e-10, loss_type: str = 'amplitude_mse')

Bases: _Algorithm

Embedded pupil-recovery reconstruction for FPM.

EPRY uses projected exit-wave errors to update the object spectrum and complex pupil together, separating specimen structure from aberrations. Per-frame gain and background recovery are fpm-rs extensions.

Parameters: iterations: Complete passes through the acquisition schedule. object_step: Relaxation factor for object corrections. pupil_step: Relaxation factor for pupil corrections. batch_size: Measured frames supplied to each step. recover_pupil: Whether to update the complex pupil. constrain_pupil_support: Zero pupil values outside the aperture. recover_frame_gains: Estimate a multiplicative gain per frame. gain_step: Fraction of each gain estimate applied per update. gain_bounds: Lower and upper bounds for recovered gains. recover_background: Estimate a uniform additive background per frame. background_step: Fraction of the mean residual applied per update. background_bounds: Bounds for recovered background intensities. epsilon: Positive numerical floor for normalized updates. loss_type: Diagnostic loss; the projection always enforces amplitude.

Reference: X. Ou, G. Zheng, and C. Yang, "Embedded pupil function recovery for Fourier ptychographic microscopy," Optics Express 22(5), 4960-4972 (2014), doi:10.1364/OE.22.004960.

run(problem: ReconstructionProblem, *, callbacks: Iterable[Callback] | None = None, resume_from: ReconstructionCheckpoint | None = None, schedule: str = 'sequential', schedule_seed: int = 0) -> ReconstructionResult

Admm(*, iterations: int = 100, object_step: float = 0.8, penalty: float = 1.0, dual_relaxation: float = 1.0, batch_size: int | None = None, epsilon: float = 1e-10)

Bases: _Algorithm

Linearized ADMM reconstruction for FPM.

Per-mode auxiliary and dual fields separate detector-amplitude fitting from object consensus. Steps alternate an amplitude proximal operation, a pupil-preconditioned object update, and a scaled-dual update.

Parameters: iterations: Complete passes through the acquisition schedule. object_step: Step size of the linearized object update. penalty: Positive augmented-Lagrangian consensus penalty. dual_relaxation: Scaled-dual relaxation in the range [0, 2]. batch_size: Frames per step; None processes all frames together. epsilon: Positive numerical floor for normalized updates.

Reference: A. Wang, Z. Zhang, S. Wang, A. Pan, C. Ma, and B. Yao, "Fourier Ptychographic Microscopy via Alternating Direction Method of Multipliers," Cells 11(9), 1512 (2022), doi:10.3390/cells11091512.

run(problem: ReconstructionProblem, *, callbacks: Iterable[Callback] | None = None, resume_from: ReconstructionCheckpoint | None = None, schedule: str = 'sequential', schedule_seed: int = 0) -> ReconstructionResult

GradientDescent(*, iterations: int = 100, object_step: float = 0.5, batch_size: int = 1, epsilon: float = 1e-10, loss_type: str = 'amplitude_mse', recover_illumination: bool = False, illumination_step: float = 0.1, illumination_finite_difference: float = 0.05, illumination_bounds: float = 1.0, recover_pupil: bool = False, pupil_step: float = 0.05, constrain_pupil_support: bool = True, object_tv: float = 0.0, object_tv_epsilon: float = 1e-06, pupil_smoothing: float = 0.0, parallel_workers: int = 0)

Bases: _Algorithm

Wirtinger-style loss-gradient reconstruction for Fourier ptychography.

The solver differentiates a selected data loss through the FPM forward model, averages mini-batch gradients, and applies a pupil-power- preconditioned object update. Pupil and illumination recovery and object or pupil regularization are optional.

Parameters: iterations: Complete passes through the acquisition schedule. object_step: Step size of the preconditioned object update. batch_size: Frame gradients averaged into one update. epsilon: Positive floor used by losses and preconditioners. loss_type: Data loss to optimize and report. recover_illumination: Estimate Fourier-grid illumination offsets. illumination_step: Step size of the scaled offset update. illumination_finite_difference: Difference spacing in grid pixels. illumination_bounds: Maximum absolute correction in grid pixels. recover_pupil: Whether to update the complex pupil. pupil_step: Step size of the normalized pupil update. constrain_pupil_support: Zero pupil values outside the aperture. object_tv: Complex-object total-variation weight; 0 disables it. object_tv_epsilon: Smoothing constant in the TV norm. pupil_smoothing: Quadratic pupil-smoothing weight. parallel_workers: Worker limit; 0 selects available CPU parallelism.

Reference: L. Bian, J. Suo, G. Zheng, K. Guo, F. Chen, and Q. Dai, "Fourier ptychographic reconstruction using Wirtinger flow optimization," Optics Express 23(4), 4856-4866 (2015), doi:10.1364/OE.23.004856.

run(problem: ReconstructionProblem, *, callbacks: Iterable[Callback] | None = None, resume_from: ReconstructionCheckpoint | None = None, schedule: str = 'sequential', schedule_seed: int = 0) -> ReconstructionResult

Callbacks and diagnostics

ProgressLogger(*, every: int = 1)

CheckpointEvery(every: int, directory: Path)

CsvLogger(path: Path)

StopOnPlateau(patience: int, *, minimum_improvement: float = 0.0)

SaveImageEvery(every: int, directory: Path)

SavePupilEvery(every: int, directory: Path)

SaveResidualsEvery(every: int, directory: Path)

IterationCallback(callable: Callable[[Mapping[str, Any]], object], *, every: int = 1)

Python iteration callback that reacquires the GIL for each invocation.

DiagnosticRecorder(mode: str = 'basic', *, every: int = 1)

every: int property

mode: str property

diagnostics() -> dict[str, Any]

to_json(path: Path) -> None