Reconstruction algorithms¶
Ordinary solvers share a run interface; the spectral solver accepts a separate
spectral problem with keyword-only arguments. Both release the Python GIL while
executing Rust reconstruction code. The choice of solver controls its update
rule, recoverable quantities, and algorithm-specific parameters.
AlternatingProjection
¶
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:
| Name | Type | Description | Default |
|---|---|---|---|
iterations
|
int
|
Complete passes through the acquisition schedule. |
50
|
object_step
|
float
|
Relaxation factor for object-spectrum corrections. |
1.0
|
batch_size
|
int
|
Measured frames supplied to each reconstruction step. |
1
|
epsilon
|
float
|
Positive numerical floor for divisions and dark fields. |
1e-10
|
loss_type
|
str
|
Diagnostic loss; the projection itself always enforces amplitude. |
'amplitude_mse'
|
References
Zheng, Horstmeyer, and Yang, Wide-field, high-resolution Fourier ptychographic microscopy (2013).
run
¶
run(
problem: ReconstructionProblem,
*,
callbacks: Iterable[Callback] | None = None,
resume_from: ReconstructionCheckpoint | None = None,
schedule: str = "sequential",
schedule_seed: int = 0,
) -> ReconstructionResult
Run reconstruction without holding the Python GIL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
ReconstructionProblem
|
Validated measurements and compiled model. |
required |
callbacks
|
Iterable[Callback] | None
|
Optional callbacks invoked in their listed order. |
None
|
resume_from
|
ReconstructionCheckpoint | None
|
Compatible checkpoint whose algorithm state and completed progress should be restored. |
None
|
schedule
|
str
|
Frame order: |
'sequential'
|
schedule_seed
|
int
|
Deterministic seed used only by the shuffled schedule. |
0
|
AdaptiveAlternatingProjection
¶
AdaptiveAlternatingProjection(
*,
iterations: int = 50,
initial_object_step: float = 1.0,
progress_threshold: float = 0.01,
reduction_factor: float = 0.5,
minimum_object_step: float = 0.001,
batch_size: int = 1,
epsilon: float = 1e-10,
)
Bases: _Algorithm
Noise-robust alternating projection with a pass-adaptive object step.
One object step is shared by every frame in a complete acquisition pass. The method retains that step while the accumulated amplitude-MSE objective makes sufficient relative progress and otherwise reduces it to a positive floor. Feedback reuses the objective evaluated by the projections, so it requires no extra forward pass. Batching does not change adaptation cadence or the numerical path; changing the frame schedule intentionally can.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iterations
|
int
|
Complete passes through the acquisition schedule. |
50
|
initial_object_step
|
float
|
Positive object relaxation used before the first reduction. |
1.0
|
progress_threshold
|
float
|
Relative pass-objective decrease required to retain the current step. |
0.01
|
reduction_factor
|
float
|
Factor in |
0.5
|
minimum_object_step
|
float
|
Positive step floor no greater than |
0.001
|
batch_size
|
int
|
Measured frames supplied to each reconstruction step. |
1
|
epsilon
|
float
|
Positive numerical floor used in projection and relative progress. |
1e-10
|
Notes
Feedback is the frame-weighted mean of per-frame, mask-aware amplitude MSE after configured gains and background. The implementation uses the paper's inexpensive accumulated-objective approximation, recovers only the object, and keeps the compiled pupil fixed. The cited convergence proof assumes convex component objectives; FPM phase retrieval is non-convex.
Checkpoints preserve the current step, preceding objective, active pass
sums, and controller parameters. Resume requires matching parameters. A
checkpoint without adaptive auxiliary state is treated as a warm start and
establishes a new feedback baseline. Physical JointReconstruction is
unsupported because model recompilation invalidates the objective history.
run
¶
run(
problem: ReconstructionProblem,
*,
callbacks: Iterable[Callback] | None = None,
resume_from: ReconstructionCheckpoint | None = None,
schedule: str = "sequential",
schedule_seed: int = 0,
) -> ReconstructionResult
Run reconstruction without holding the Python GIL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
ReconstructionProblem
|
Validated measurements and compiled model. |
required |
callbacks
|
Iterable[Callback] | None
|
Optional callbacks invoked in their listed order. |
None
|
resume_from
|
ReconstructionCheckpoint | None
|
Compatible checkpoint whose algorithm state and completed progress should be restored. |
None
|
schedule
|
str
|
Frame order: |
'sequential'
|
schedule_seed
|
int
|
Deterministic seed used only by the shuffled schedule. |
0
|
Fpie
¶
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:
| Name | Type | Description | Default |
|---|---|---|---|
iterations
|
int
|
Complete passes through the acquisition schedule. |
50
|
object_step
|
float
|
Relaxation factor for object-spectrum corrections. |
0.8
|
stability
|
float
|
Blend from local (0) to maximum (1) pupil power in the denominator. |
0.1
|
batch_size
|
int
|
Measured frames supplied to each reconstruction step. |
1
|
epsilon
|
float
|
Positive floor added to the rPIE denominator. |
1e-10
|
loss_type
|
str
|
Diagnostic loss; the projection itself always enforces amplitude. |
'amplitude_mse'
|
References
Maiden, Johnson, and Li, Further improvements to the ptychographical iterative engine (2017).
run
¶
run(
problem: ReconstructionProblem,
*,
callbacks: Iterable[Callback] | None = None,
resume_from: ReconstructionCheckpoint | None = None,
schedule: str = "sequential",
schedule_seed: int = 0,
) -> ReconstructionResult
Run reconstruction without holding the Python GIL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
ReconstructionProblem
|
Validated measurements and compiled model. |
required |
callbacks
|
Iterable[Callback] | None
|
Optional callbacks invoked in their listed order. |
None
|
resume_from
|
ReconstructionCheckpoint | None
|
Compatible checkpoint whose algorithm state and completed progress should be restored. |
None
|
schedule
|
str
|
Frame order: |
'sequential'
|
schedule_seed
|
int
|
Deterministic seed used only by the shuffled schedule. |
0
|
Mpie
¶
Mpie(
*,
iterations: int = 50,
object_step: float = 0.2,
stability: float = 0.05,
momentum_interval: int = 30,
momentum_friction: float = 0.9,
momentum_feedback: float = 0.9,
batch_size: int = 1,
epsilon: float = 1e-10,
loss_type: str = "amplitude_mse",
)
Bases: _Algorithm
Momentum-accelerated regularized PIE adapted to image-plane FPM.
The algorithm applies the object-only rPIE projection used by Fpie and
periodically accelerates the centered complex object spectrum. A
multiplexed measurement counts once after all source modes are inserted,
zero-weight frames do not advance the interval, and batching does not
change momentum cadence. Velocity, anchor, and a partial interval are
preserved in checkpoints.
The cited method was tested for scanned ptychography and accelerates both object and probe. This implementation keeps the FPM pupil fixed and exposes separate friction and feedback controls. Equal values reproduce the paper's single object momentum coefficient.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iterations
|
int
|
Complete passes through the acquisition schedule. |
50
|
object_step
|
float
|
Positive scale applied to each rPIE object-spectrum correction. |
0.2
|
stability
|
float
|
Blend from local (0) to maximum (1) pupil power in the denominator. |
0.05
|
momentum_interval
|
int
|
Positive-weight measured-frame updates between momentum events. |
30
|
momentum_friction
|
float
|
Previous-velocity fraction in the half-open interval |
0.9
|
momentum_feedback
|
float
|
Updated-velocity fraction added to the object, in |
0.9
|
batch_size
|
int
|
Measured frames supplied to each reconstruction step. This does not change momentum cadence. |
1
|
epsilon
|
float
|
Positive floor added to the rPIE denominator. |
1e-10
|
loss_type
|
str
|
Diagnostic loss; the projection itself always enforces amplitude. |
'amplitude_mse'
|
References
A. Maiden, D. Johnson, and P. Li, Further improvements to the ptychographical iterative engine (2017), Optica 4(7), 736–745.
run
¶
run(
problem: ReconstructionProblem,
*,
callbacks: Iterable[Callback] | None = None,
resume_from: ReconstructionCheckpoint | None = None,
schedule: str = "sequential",
schedule_seed: int = 0,
) -> ReconstructionResult
Run reconstruction without holding the Python GIL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
ReconstructionProblem
|
Validated measurements and compiled model. |
required |
callbacks
|
Iterable[Callback] | None
|
Optional callbacks invoked in their listed order. |
None
|
resume_from
|
ReconstructionCheckpoint | None
|
Compatible checkpoint whose algorithm state and completed progress should be restored. |
None
|
schedule
|
str
|
Frame order: |
'sequential'
|
schedule_seed
|
int
|
Deterministic seed used only by the shuffled schedule. |
0
|
Epry
¶
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.
With pupil recovery enabled, iteration-boundary results match the compiled pupil's supported energy and phase reference and fix the remaining object piston. Affine pupil phase is removed on axes with zero effective subpixel offsets. It remains on fractional axes because bilinear crop interpolation does not preserve that ambiguity exactly. Canonicalization precedes iteration callbacks, checkpoints, final results, and resumed work.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iterations
|
int
|
Complete passes through the acquisition schedule. |
100
|
object_step
|
float
|
Relaxation factors for object and pupil corrections. |
0.8
|
pupil_step
|
float
|
Relaxation factors for object and pupil corrections. |
0.8
|
batch_size
|
int
|
Measured frames supplied to each step. |
1
|
recover_pupil
|
bool
|
Whether to update the complex pupil. |
True
|
constrain_pupil_support
|
bool
|
Whether to zero pupil values outside the compiled aperture. |
True
|
recover_frame_gains
|
bool
|
Whether to estimate multiplicative gains or uniform additive backgrounds. |
False
|
recover_background
|
bool
|
Whether to estimate multiplicative gains or uniform additive backgrounds. |
False
|
gain_step
|
float
|
Fractions of each calibration estimate applied per update. |
0.2
|
background_step
|
float
|
Fractions of each calibration estimate applied per update. |
0.2
|
gain_bounds
|
tuple[float, float]
|
Inclusive lower and upper limits for recovered calibration values. |
(1e-06, 1000000.0)
|
background_bounds
|
tuple[float, float]
|
Inclusive lower and upper limits for recovered calibration values. |
(1e-06, 1000000.0)
|
epsilon
|
float
|
Positive numerical floor for normalized updates. |
1e-10
|
loss_type
|
str
|
Diagnostic loss; the projection itself always enforces amplitude. |
'amplitude_mse'
|
References
A. Fannjiang and P. Chen, Blind ptychography: uniqueness and ambiguities (2020), Inverse Problems 36, 045005. fpm-rs uses a Fourier-domain object and retains affine phase on fractionally interpolated axes.
run
¶
run(
problem: ReconstructionProblem,
*,
callbacks: Iterable[Callback] | None = None,
resume_from: ReconstructionCheckpoint | None = None,
schedule: str = "sequential",
schedule_seed: int = 0,
) -> ReconstructionResult
Run reconstruction without holding the Python GIL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
ReconstructionProblem
|
Validated measurements and compiled model. |
required |
callbacks
|
Iterable[Callback] | None
|
Optional callbacks invoked in their listed order. |
None
|
resume_from
|
ReconstructionCheckpoint | None
|
Compatible checkpoint whose algorithm state and completed progress should be restored. |
None
|
schedule
|
str
|
Frame order: |
'sequential'
|
schedule_seed
|
int
|
Deterministic seed used only by the shuffled schedule. |
0
|
Admm
¶
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:
| Name | Type | Description | Default |
|---|---|---|---|
iterations
|
int
|
Complete passes through the acquisition schedule. |
100
|
object_step
|
float
|
Step size of the linearized object update. |
0.8
|
penalty
|
float
|
Positive augmented-Lagrangian consensus penalty. |
1.0
|
dual_relaxation
|
float
|
Scaled-dual relaxation in the inclusive range |
1.0
|
batch_size
|
int | None
|
Frames per step; |
None
|
epsilon
|
float
|
Positive numerical floor for normalized updates. |
1e-10
|
References
Wang et al., Fourier Ptychographic Microscopy via Alternating Direction Method of Multipliers (2022).
run
¶
run(
problem: ReconstructionProblem,
*,
callbacks: Iterable[Callback] | None = None,
resume_from: ReconstructionCheckpoint | None = None,
schedule: str = "sequential",
schedule_seed: int = 0,
) -> ReconstructionResult
Run reconstruction without holding the Python GIL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
ReconstructionProblem
|
Validated measurements and compiled model. |
required |
callbacks
|
Iterable[Callback] | None
|
Optional callbacks invoked in their listed order. |
None
|
resume_from
|
ReconstructionCheckpoint | None
|
Compatible checkpoint whose algorithm state and completed progress should be restored. |
None
|
schedule
|
str
|
Frame order: |
'sequential'
|
schedule_seed
|
int
|
Deterministic seed used only by the shuffled schedule. |
0
|
GradientDescent
¶
GradientDescent(
*,
iterations: int = 100,
object_step: float = 0.5,
batch_size: int = 1,
epsilon: float = 1e-10,
loss_type: str = "amplitude_mse",
poisson_truncation_threshold: float | None = None,
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.
With pupil recovery enabled, iteration-boundary results match the compiled pupil's supported energy and phase reference and fix the remaining object piston. Affine pupil phase is removed on axes with zero effective subpixel offsets. It remains on fractional axes because bilinear crop interpolation does not preserve that ambiguity exactly. Canonicalization precedes iteration callbacks, checkpoints, final results, and resumed work.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iterations
|
int
|
Complete passes through the acquisition schedule. |
100
|
object_step
|
float
|
Step size of the preconditioned object update. |
0.5
|
batch_size
|
int
|
Frame gradients averaged into one update. |
1
|
epsilon
|
float
|
Positive floor used by losses and preconditioners. |
1e-10
|
loss_type
|
str
|
Data loss to optimize and report. |
'amplitude_mse'
|
poisson_truncation_threshold
|
float | None
|
Positive signal-dependent Poisson outlier coefficient. |
None
|
recover_illumination
|
bool
|
Whether to estimate source offsets on the Fourier grid. |
False
|
illumination_step
|
float
|
Offset-update step, finite-difference spacing, and maximum absolute correction, all expressed in Fourier-grid pixels where applicable. |
0.1
|
illumination_finite_difference
|
float
|
Offset-update step, finite-difference spacing, and maximum absolute correction, all expressed in Fourier-grid pixels where applicable. |
0.1
|
illumination_bounds
|
float
|
Offset-update step, finite-difference spacing, and maximum absolute correction, all expressed in Fourier-grid pixels where applicable. |
0.1
|
recover_pupil
|
bool
|
Whether and how to update the complex pupil within its aperture. |
False
|
pupil_step
|
bool
|
Whether and how to update the complex pupil within its aperture. |
False
|
constrain_pupil_support
|
bool
|
Whether and how to update the complex pupil within its aperture. |
False
|
object_tv
|
float
|
Complex-object total-variation weight and smoothing constant; a zero weight disables the regularizer. |
0.0
|
object_tv_epsilon
|
float
|
Complex-object total-variation weight and smoothing constant; a zero weight disables the regularizer. |
0.0
|
pupil_smoothing
|
float
|
Nonnegative quadratic pupil-smoothing weight. |
0.0
|
parallel_workers
|
int
|
Worker limit; zero selects available CPU parallelism. |
0
|
References
L. Bian, J. Suo, J. Chung, X. Ou, C. Yang, F. Chen, and Q. Dai, Fourier ptychographic reconstruction using Poisson maximum likelihood and truncated Wirtinger gradient (2016), Scientific Reports 6, 27384. fpm-rs uses a mini-batch statistic and fixed object step; optional pupil and illumination recovery extend the paper's object-only presentation.
A. Fannjiang and P. Chen, Blind ptychography: uniqueness and ambiguities (2020), Inverse Problems 36, 045005. fpm-rs uses a Fourier-domain object and retains affine phase on fractionally interpolated axes.
run
¶
run(
problem: ReconstructionProblem,
*,
callbacks: Iterable[Callback] | None = None,
resume_from: ReconstructionCheckpoint | None = None,
schedule: str = "sequential",
schedule_seed: int = 0,
) -> ReconstructionResult
Run reconstruction without holding the Python GIL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
ReconstructionProblem
|
Validated measurements and compiled model. |
required |
callbacks
|
Iterable[Callback] | None
|
Optional callbacks invoked in their listed order. |
None
|
resume_from
|
ReconstructionCheckpoint | None
|
Compatible checkpoint whose algorithm state and completed progress should be restored. |
None
|
schedule
|
str
|
Frame order: |
'sequential'
|
schedule_seed
|
int
|
Deterministic seed used only by the shuffled schedule. |
0
|
Narrowband spectral reconstruction¶
SpectralAlternatingProjection
¶
SpectralAlternatingProjection(
*,
iterations: int = 50,
object_step: float = 1.0,
batch_size: int = 1,
epsilon: float = 1e-10,
)
Object-only narrowband amplitude projection with fixed channel pupils.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iterations
|
int
|
Positive number of complete global acquisition passes. |
50
|
object_step
|
float
|
Finite positive object correction relaxation. |
1.0
|
batch_size
|
int
|
Positive exposures per step; does not alter per-frame update order. |
1
|
epsilon
|
float
|
Finite positive division floor and dark-prediction threshold. |
1e-10
|
Notes
All coherent modes of one detector exposure are evaluated before updates. One measured-to-predicted amplitude ratio corrects all modes, with weighted canonical adjoints accumulated into independent or shared objects. Only current-exposure fields are retained. Source powers, gains, backgrounds, and per-channel pupils stay fixed. Single-channel and separate independent acquisitions reduce to ordinary alternating projection.
This typed channel/local-frame implementation generalizes narrowband state decomposition; finite spectral bandwidth and mixed-state coherence are excluded.
References
S. Dong, R. Shiradkar, P. Nanda, and G. Zheng, “Spectral multiplexing and coherent-state decomposition in Fourier ptychographic imaging”, Biomedical Optics Express 5(6), 1757–1767 (2014).
run_opd
¶
run_opd(
*,
problem: SpectralReconstructionProblem,
unwrapper: SyntheticWavelengthUnwrapper,
phase_offsets_rad: Sequence[float] | None = None,
reference_mask: MaskArray | None = None,
reference_opd_m: float = 0.0,
mask: MaskArray | None = None,
initial_objects: ComplexArray | None = None,
frame_order: Sequence[int] | None = None,
seed: int | None = None,
resume: SpectralReconstructionCheckpoint | None = None,
checkpoint_directory: Path | None = None,
checkpoint_every: int = 1,
) -> MultiWavelengthReconstructionResult
Reconstruct independent wavelength fields and mix their phases into OPD.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
SpectralReconstructionProblem
|
Scalar detector measurements with an independent-object spectral model. |
required |
unwrapper
|
SyntheticWavelengthUnwrapper
|
Explicit OPD interval, amplitude floor, and optional residual tolerance. |
required |
phase_offsets_rad
|
Sequence[float] | None
|
Optional channel pistons in radians, as in |
None
|
reference_mask
|
MaskArray | None
|
Alternative copied C-contiguous uint8 constant-OPD reference region. |
None
|
reference_opd_m
|
float
|
Known reference-region OPD in metres, as in |
0.0
|
mask
|
MaskArray | None
|
Optional copied C-contiguous uint8 common-grid validity mask. |
None
|
initial_objects
|
ComplexArray | None
|
Optional copied complex128 channel fields, as in |
None
|
frame_order
|
Sequence[int] | None
|
Optional global detector permutation, as in |
None
|
seed
|
int | None
|
Optional deterministic shuffle seed, mutually exclusive with frame_order. |
None
|
resume
|
SpectralReconstructionCheckpoint | None
|
Optional saved spectral AP state. Rejects simultaneous initial objects, changed data/model/options or an explicitly different schedule. When ordering is omitted, resumes the saved schedule. Iterations is the total target including completed passes, which may increase. |
None
|
checkpoint_directory
|
Path | None
|
Optional local directory for atomic iteration-boundary JSON snapshots. Final state is always returned; fingerprinting streams the data once. |
None
|
checkpoint_every
|
int
|
Positive complete-pass interval. The final checkpoint is also written. |
1
|
Returns:
| Type | Description |
|---|---|
MultiWavelengthReconstructionResult
|
Both the wavelength-field reconstruction and referenced OPD diagnostics. |
Raises:
| Type | Description |
|---|---|
FpmError
|
For invalid reconstruction inputs, shared-complex coupling, or OPD inputs. |
ValueError
|
For conflicting ordering options or a missing/conflicting phase reference. |
Notes
Performs run followed by SpectralReconstructionResult.unwrap_opd;
both computations release the GIL. Assumes registered fields with matched
spatial resolution and nondispersive OPD; does not jointly optimize OPD
against detector intensities. Exactly one phase reference is required.
run
¶
run(
*,
problem: SpectralReconstructionProblem,
initial_objects: ComplexArray | None = None,
frame_order: Sequence[int] | None = None,
seed: int | None = None,
resume: SpectralReconstructionCheckpoint | None = None,
checkpoint_directory: Path | None = None,
checkpoint_every: int = 1,
) -> SpectralReconstructionResult
Reconstruct channel fields while releasing the Python GIL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
SpectralReconstructionProblem
|
Validated scalar detector data and compiled spectral kernels. |
required |
initial_objects
|
ComplexArray | None
|
Optional finite C-contiguous complex128 |
None
|
frame_order
|
Sequence[int] | None
|
Optional explicit permutation of all detector rows, reused each pass. |
None
|
seed
|
int | None
|
Optional deterministic per-iteration shuffle seed; mutually exclusive
with |
None
|
resume
|
SpectralReconstructionCheckpoint | None
|
Optional saved spectral AP state. Rejects simultaneous initial objects, changed data/model/options or an explicitly different schedule. When ordering is omitted, resumes the saved schedule. Iterations is the total target including completed passes, which may increase. |
None
|
checkpoint_directory
|
Path | None
|
Optional local directory for atomic iteration-boundary JSON snapshots. Final state is always returned; fingerprinting streams the data once. |
None
|
checkpoint_every
|
int
|
Positive complete-pass interval. The final checkpoint is also written. |
1
|
Returns:
| Type | Description |
|---|---|
SpectralReconstructionResult
|
Owned channel fields and global trace; array access returns copies. |
Raises:
| Type | Description |
|---|---|
FpmError
|
For invalid parameters, object layout/count/shape, or detector ordering. |
SyntheticWavelengthUnwrapper
¶
SyntheticWavelengthUnwrapper(
*,
opd_range_m: tuple[float, float],
minimum_amplitude: float = 0.0,
max_phase_residual_rad: float | None = None,
)
Recover nondispersive OPD by mixing registered wavelength phases.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
opd_range_m
|
tuple[float, float]
|
Finite increasing half-open |
required |
minimum_amplitude
|
float
|
Finite nonnegative floor; every channel must strictly exceed it per pixel. |
0.0
|
max_phase_residual_rad
|
float | None
|
Optional maximum RMS principal phase residual in |
None
|
Notes
Requires at least two distinct positive vacuum wavelengths and finite,
registered, resolution-matched complex transmission fields on a common grid.
The shared quantity is OPD: phase_i = wrap(2*pi*OPD/lambda_i). This
assumes negligible OPD dispersion; it does not impose identical complex fields.
A reference region or explicit channel phase pistons fixes FPM's phase gauges.
Subtract shorter/longer channel phases to form difference periods
Lambda = lambda_short*lambda_long/(lambda_long-lambda_short). The longest
beat selects a branch inside the explicit interval; descending shorter beat
and original periods refine integer orders by rounding. A final least-squares
fit of the unwrapped original phases uses equal phase weights across channels.
Spatial continuity is unnecessary, but noise in each coarse estimate must be
below half the next period for correct rounding. Residuals cannot guarantee
fringe uniqueness. This adaptation uses an interval instead of spatially
unwrapping the longest beat, and omits phase-sum wavelengths and holographic optics.
References
S. K. Mirsky and N. T. Shaked, “Six-pack holography for dynamic profiling of thick and extended objects by simultaneous three-wavelength phase unwrapping with doubled field of view”, Scientific Reports 13, article 19293 (2023), synthetic-wavelength and hierarchical phase-unwrapping sections.
opd_range_m
property
¶
opd_range_m: tuple[float, float]
Return the half-open absolute OPD interval in metres.
minimum_amplitude
property
¶
minimum_amplitude: float
Return the strict per-channel amplitude validity floor.
max_phase_residual_rad
property
¶
max_phase_residual_rad: float | None
Return the optional RMS phase residual cutoff in radians.
unwrap_fields
¶
unwrap_fields(
*,
fields: ComplexArray,
wavelengths_vacuum_m: Sequence[float],
phase_offsets_rad: Sequence[float] | None = None,
reference_mask: MaskArray | None = None,
reference_opd_m: float = 0.0,
mask: MaskArray | None = None,
) -> OpticalPathDifferenceResult
Mix phases from copied complex128 (channels, rows, columns) fields.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fields
|
ComplexArray
|
Finite C-contiguous complex128 registered transmission fields. |
required |
wavelengths_vacuum_m
|
Sequence[float]
|
At least two distinct finite positive vacuum wavelengths in metres, ordered like the channel axis of fields. |
required |
phase_offsets_rad
|
Sequence[float] | None
|
One finite channel piston in radians to subtract. Exactly one of this option and reference_mask is required. Explicit zero offsets are appropriate only for fields already referenced to zero OPD. |
None
|
reference_mask
|
MaskArray | None
|
Alternative copied C-contiguous uint8 |
None
|
reference_opd_m
|
float
|
Known constant OPD in metres of that region. Applies only to a mask. |
0.0
|
mask
|
MaskArray | None
|
Optional copied C-contiguous uint8 validity mask; zero excludes pixels. |
None
|
Returns:
| Type | Description |
|---|---|
OpticalPathDifferenceResult
|
Owned OPD and diagnostics; NumPy getters return writable copies. Zero/below-floor channel amplitudes, out-of-interval estimates, and residual failures have valid_mask=0, NaN OPD/residual, and zero orders. |
Raises:
| Type | Description |
|---|---|
FpmError
|
For invalid/ill-conditioned wavelengths, interval width, shapes/layout, nonfinite fields, unusable reference means, or no usable amplitudes in all channels. |
ValueError
|
For missing/conflicting reference choices or reference_opd_m with offsets. |
Notes
Copies inputs before releasing the GIL for computation. No registration, resolution matching, dispersion correction, or spatial unwrap is performed. Input masks do not permit nonfinite field values. Individual failed pixels are reported by the output mask, including an entirely invalid result.
MultiWavelengthGradientDescent
¶
MultiWavelengthGradientDescent(
*,
iterations: int = 100,
initialization_iterations: int = 50,
amplitude_step: float = 1.0,
opd_step: float = 1.0,
max_backtracks: int = 30,
epsilon: float = 1e-10,
)
Jointly fit one nondispersive OPD map and wavelength-specific amplitudes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
iterations
|
int
|
Positive maximum accepted full-data joint updates. |
100
|
initialization_iterations
|
int
|
Spectral AP passes for automatic initialization; must be positive unless an explicit OPD/amplitude start is supplied. |
50
|
amplitude_step
|
float
|
Finite positive multiplier for the pixel-count-scaled amplitude gradient. |
1.0
|
opd_step
|
float
|
Finite positive multiplier for the pixel-count-scaled phase-coordinate
gradient, with |
1.0
|
max_backtracks
|
int
|
Positive maximum trials per update; the common step multiplier is halved. |
30
|
epsilon
|
float
|
Finite positive intensity smoothing and squared minimum object amplitude. |
1e-10
|
Notes
Every channel field is A_c * exp(2j*pi*OPD/lambda_c) on the same grid.
Amplitudes vary by wavelength; phases always derive from one shared OPD in
metres. Requires an independent-storage spectral model with at least two
wavelengths. Fixed pupils, source powers, gains, backgrounds, and all sparse
source/spectral intensity mixtures use the canonical compiled forward model.
Minimizes the frame-weighted mean of valid-pixel
(sqrt(prediction+epsilon)-sqrt(max(measurement,0)+epsilon))**2. Full-data
analytic adjoints differentiate amplitudes and OPD together. Both gradients
are scaled by the common-grid pixel count before their separate step factors.
Backtracking accepts only non-increasing full-data objective values; amplitudes
are projected to at least sqrt(epsilon) and OPD to explicit half-open bounds.
Failure to find a step stops cleanly with stopped_early=True. The solver is
nonconvex and cannot guarantee recovery of an incorrectly initialized branch.
Automatic initialization uses independent AP then referenced synthetic phase mixing. A known constant-OPD reference region stays fixed pixelwise during joint optimization. Explicit piston offsets instead retain the initialized spatial mean OPD. Assumes nondispersive OPD, registered common grids, matched effective resolution, and a justified absolute reference. Does not estimate dispersion, pupil, or physical calibration; does not use ordinary checkpoints.
References
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), for FPM loss-gradient optimization. Shared OPD, the smoothed amplitude loss, box/gauge projections, and monotone backtracking are implementation extensions. See SyntheticWavelengthUnwrapper for the initialization hierarchy and reference.
run
¶
run(
*,
problem: SpectralReconstructionProblem,
unwrapper: SyntheticWavelengthUnwrapper,
phase_offsets_rad: Sequence[float] | None = None,
reference_mask: MaskArray | None = None,
reference_opd_m: float = 0.0,
initial_opd_m: FloatArray | None = None,
initial_amplitudes: FloatArray | None = None,
checkpoint_directory: Path | None = None,
checkpoint_every: int = 1,
) -> MultiWavelengthSolverResult
Fit detector measurements with shared OPD while releasing the GIL.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
SpectralReconstructionProblem
|
Scalar detector stack and independent-storage compiled spectral model. Existing measurement masks and frame weights enter the joint objective. |
required |
unwrapper
|
SyntheticWavelengthUnwrapper
|
OPD branch and phase-fusion configuration. Used for automatic initialization; explicit starts use only its opd_range_m bounds. |
required |
phase_offsets_rad
|
Sequence[float] | None
|
One finite channel piston in radians for automatic phase fusion. Mutually exclusive with reference_mask. Joint fitting preserves the initial OPD mean. With explicit OPD, offsets validate the gauge choice but do not subtract phase from an already unwrapped start. |
None
|
reference_mask
|
MaskArray | None
|
Alternative copied C-contiguous uint8 common-grid constant-OPD region. Nonzero pixels are fixed to reference_opd_m during every joint update. |
None
|
reference_opd_m
|
float
|
Finite known reference-region OPD in metres, inside the half-open bounds. Applies only to a reference mask. |
0.0
|
initial_opd_m
|
FloatArray | None
|
Optional copied finite C-contiguous float64 |
None
|
initial_amplitudes
|
FloatArray | None
|
Optional copied finite nonnegative C-contiguous float64
|
None
|
checkpoint_directory
|
Path | None
|
Optional local directory for accepted-update JSON snapshots. The final state is always returned; fingerprinting streams measurements once. |
None
|
checkpoint_every
|
int
|
Positive accepted-update interval, with a final snapshot also written. |
1
|
Returns:
| Type | Description |
|---|---|
MultiWavelengthSolverResult
|
Shared OPD, derived channel fields and joint loss trace, and optional pre-fit phase-fusion/AP diagnostics. Array getters return writable copies. |
Raises:
| Type | Description |
|---|---|
FpmError
|
For invalid scientific values, layouts, shapes, coupling, references, or any invalid automatically unwrapped initialization pixel. |
ValueError
|
For missing/conflicting phase references or only one explicit start array. |
Notes
Explicit starts bypass AP/unwrapping, so their interval can exceed the longest synthetic wavelength; the caller supplies the correct branch. Inputs are copied before releasing the GIL. Full-data gradients stream detector frames in acquisition order. Ordinary batching and scheduling contracts do not apply; spectral checkpoints preserve the fixed OPD gauge. Runtime elapsed time covers joint refinement; initialization_trace separately records the AP passes when used.
run_from_checkpoint
¶
run_from_checkpoint(
*,
problem: SpectralReconstructionProblem,
checkpoint: SpectralReconstructionCheckpoint,
checkpoint_directory: Path | None = None,
checkpoint_every: int = 1,
) -> MultiWavelengthSolverResult
Resume joint refinement without unwrapping or projecting its saved gauge.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
problem
|
SpectralReconstructionProblem
|
Identical compiled channels and detector values/masks/weights. |
required |
checkpoint
|
SpectralReconstructionCheckpoint
|
Joint OPD snapshot from a result or file. Stepping parameters must match; iterations is the total target and may increase. |
required |
checkpoint_directory
|
Path | None
|
Optional accepted-update snapshot directory. |
None
|
checkpoint_every
|
int
|
Positive update interval; final state is also written. |
1
|
Returns:
| Type | Description |
|---|---|
MultiWavelengthSolverResult
|
Continued fields and authoritative OPD, with accumulated trace/timing. |
Raises:
| Type | Description |
|---|---|
FpmError
|
For mismatched solver/model/data/options or invalid state. Spectral AP checkpoints cannot be consumed here. Computation releases the GIL. |
Physical planar-array calibration¶
Bright-field initialization¶
BrightfieldCircleOptions
¶
BrightfieldCircleOptions(
*,
frame_indices: Sequence[int] | None = None,
center_search_radius_na: float = 0.02,
brightfield_margin_na: float = 0.002,
pupil_radius_search_na: float = 0.01,
gaussian_sigma_pixels: float = 2.0,
angular_samples: int = 180,
radial_derivative_step_pixels: float = 1.0,
minimum_arc_fraction: float = 0.2,
minimum_edge_contrast: float = 0.01,
mean_spectrum_floor: float = 1e-08,
robust_residual_scale_na: float = 0.002,
maximum_fit_steps: int = 100,
fit_relative_tolerance: float = 1e-08,
fit_initial_step_size: float = 0.5,
fit_minimum_step_size: float = 1e-06,
fit_step_reduction: float = 0.5,
rank_tolerance: float = 1e-08,
pupil_radius_tolerance_na: float = 0.02,
)
Controls for bright-field circle detection and bounded physical fitting.
All center and pupil-radius quantities use dimensionless numerical-aperture
units. Pixel quantities refer to the low-resolution Fourier grid. An
explicit frame_indices sequence contains acquisition-frame indices, not
physical source indices.
frame_indices
instance-attribute
¶
frame_indices: list[int] | None
Explicit acquisition-frame subset, or None for safe automatic selection.
center_search_radius_na
instance-attribute
¶
center_search_radius_na: float
Maximum center displacement from each nominal source in NA.
brightfield_margin_na
instance-attribute
¶
brightfield_margin_na: float
Positive margin retained inside the objective-NA boundary.
pupil_radius_search_na
instance-attribute
¶
pupil_radius_search_na: float
Half-width of the pupil-radius search in NA.
gaussian_sigma_pixels
instance-attribute
¶
gaussian_sigma_pixels: float
Fourier-magnitude smoothing standard deviation in pixels.
angular_samples
instance-attribute
¶
angular_samples: int
Uniform angular samples used for every circular score.
radial_derivative_step_pixels
instance-attribute
¶
radial_derivative_step_pixels: float
Radial finite-difference displacement in Fourier-grid pixels.
minimum_arc_fraction
instance-attribute
¶
minimum_arc_fraction: float
Minimum usable fraction of the requested circumference.
minimum_edge_contrast
instance-attribute
¶
minimum_edge_contrast: float
Minimum normalized first-derivative score for acceptance.
mean_spectrum_floor
instance-attribute
¶
mean_spectrum_floor: float
Relative positive floor applied during mean-spectrum division.
robust_residual_scale_na
instance-attribute
¶
robust_residual_scale_na: float
Huber transition scale for physical-fit residual components in NA.
fit_relative_tolerance
instance-attribute
¶
fit_relative_tolerance: float
Relative objective improvement required to continue fitting.
fit_initial_step_size
instance-attribute
¶
fit_initial_step_size: float
Initial line-search step in normalized parameter coordinates.
fit_minimum_step_size
instance-attribute
¶
fit_minimum_step_size: float
Smallest normalized line-search step attempted.
fit_step_reduction
instance-attribute
¶
fit_step_reduction: float
Multiplicative backtracking factor in (0, 1).
rank_tolerance
instance-attribute
¶
rank_tolerance: float
Relative pivot threshold for the data-Jacobian rank test.
pupil_radius_tolerance_na
instance-attribute
¶
pupil_radius_tolerance_na: float
Maximum accepted pupil-radius mismatch from configured objective NA.
PlanarArrayInitializationCallback
¶
PlanarArrayInitializationCallback(
callable: Callable[[dict[str, object]], bool | None],
)
Wrap a callable receiving initializer-specific progress dictionaries.
The callable receives stage, completed, total, and optional
frame_index entries. Return False to cancel or None/True to
continue. The initializer releases the GIL while working and reacquires it
only for these callbacks.
BrightfieldCircleInitializer
¶
BrightfieldCircleInitializer(
parameters: PlanarArrayCalibrationParameters,
*,
options: BrightfieldCircleOptions | None = None,
)
Detect bright-field pupil circles and fit a physical planar-array warm start.
The method assumes monochromatic coherent image-plane measurements, a thin
specimen with enough texture/reference interference, and a shift-invariant
circular pupil. It accepts only single-source, all-valid, strictly
bright-field frames. It does not reconstruct an object, alter Optics,
or estimate independent source shifts, powers, gains, or backgrounds.
Use the returned illumination/model directly or pass them to
JointReconstruction for canonical
measurement-loss refinement. The call blocks, releases the GIL during both
streaming measurement passes and physical fitting, and reacquires it only
for an optional progress callback.
References
J. Sun, Q. Chen, Y. Zhang, and C. Zuo, “Efficient positional misalignment correction method for Fourier ptychographic microscopy,” Biomedical Optics Express 7(4), 1336–1350 (2016). Unlike that reconstruction-time independent aperture search, this initializer directly fits detected centers to the bounded physical geometry.
R. Eckert, Z. F. Phillips, and L. Waller, “Efficient illumination angle self-calibration in Fourier ptychography,” Applied Optics 57(19), 5434–5442 (2018). This implementation adopts the bright-field circular-edge initialization concept, not the iterative spectral-correlation stage or three-dimensional variants.
parameters
instance-attribute
¶
parameters: PlanarArrayCalibrationParameters
Selected global translation, rotation, pitch, or reference-index variables.
options
instance-attribute
¶
options: BrightfieldCircleOptions
Circle-detection and bounded-fit controls.
initialize
¶
initialize(
measurements: FloatArray | MeasurementStack,
optics: Optics,
nominal_illumination: Illumination,
model: ImagePlaneModel,
*,
frame_weights: Sequence[float] | None = None,
masks: MaskArray | None = None,
callback: PlanarArrayInitializationCallback
| None = None,
) -> PlanarArrayInitializationResult
Run two streaming spectral passes and a bounded physical fit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurements
|
FloatArray | MeasurementStack
|
Float64 |
required |
optics
|
Optics
|
Physical optics used to compile |
required |
nominal_illumination
|
Illumination
|
Physical planar-array illumination used to compile |
required |
model
|
ImagePlaneModel
|
Matching image-plane model. Updated complex pupil values and known background are retained unchanged. |
required |
frame_weights
|
Sequence[float] | None
|
Optional metadata for raw NumPy input. Masks must be uint8 with the same shape; selected frames must be all-valid. |
None
|
masks
|
Sequence[float] | None
|
Optional metadata for raw NumPy input. Masks must be uint8 with the same shape; selected frames must be all-valid. |
None
|
callback
|
PlanarArrayInitializationCallback | None
|
Optional initializer progress callback. |
None
|
Raises:
| Type | Description |
|---|---|
InvalidMeasurementsError
|
If candidate frames, spectra, or detected circles are unusable. |
InvalidParameterError
|
If the selected physical variables are unidentifiable or violate the calibration gauge constraints. |
UnsupportedError
|
If geometry or selected variables are outside the supported scope. |
Measurement-loss calibration¶
CalibrationParameterSpec
¶
CalibrationParameterSpec(
lower_bound: float,
upper_bound: float,
*,
scale: float = 1.0,
finite_difference_step: float | None = None,
prior_center: float | None = None,
regularization_strength: float = 0.0,
)
Numerical controls for one bounded physical parameter.
Bounds, finite-difference steps, prior centers, and scales use the physical unit of the selected parameter: metres for translations, pitches, and offsets; radians for rotations; and dimensionless values otherwise.
lower_bound
instance-attribute
¶
lower_bound: float
Inclusive lower bound in the parameter's physical unit.
upper_bound
instance-attribute
¶
upper_bound: float
Inclusive upper bound in the parameter's physical unit.
scale
instance-attribute
¶
scale: float
Positive physical increment represented by one normalized unit.
finite_difference_step
instance-attribute
¶
finite_difference_step: float
Positive perturbation used for central or one-sided differences.
prior_center
instance-attribute
¶
prior_center: float | None
Optional center of the quadratic prior in physical units.
regularization_strength
instance-attribute
¶
regularization_strength: float
Nonnegative coefficient of the quadratic prior.
PlanarArrayCalibrationParameters
¶
PlanarArrayCalibrationParameters(
*,
translation: tuple[bool, bool, bool] = (
False,
False,
False,
),
rotation: tuple[bool, bool, bool] = (
False,
False,
False,
),
pitch: tuple[bool, bool] = (False, False),
reference_index: tuple[bool, bool] = (False, False),
position_offsets: Sequence[int] = (),
relative_source_power: bool = False,
frame_gains: bool = False,
translation_spec: CalibrationParameterSpec
| None = None,
rotation_spec: CalibrationParameterSpec | None = None,
pitch_spec: CalibrationParameterSpec | None = None,
reference_index_spec: CalibrationParameterSpec
| None = None,
position_offset_spec: CalibrationParameterSpec
| None = None,
relative_source_power_spec: CalibrationParameterSpec
| None = None,
frame_gain_spec: CalibrationParameterSpec | None = None,
)
Explicit physical parameters selected for planar LED-array calibration.
Unselected groups remain fixed. position_offsets contains stable
row-major source indices; each selected source exposes local XYZ offsets.
Lateral translation cannot be combined with the corresponding reference
index, and source powers cannot be combined with frame gains because those
choices contain unresolved gauges.
translation
instance-attribute
¶
translation: tuple[bool, bool, bool]
Active (tx, ty, tz) pose components in metres.
rotation
instance-attribute
¶
rotation: tuple[bool, bool, bool]
Active extrinsic (rx, ry, rz) components in radians.
pitch
instance-attribute
¶
pitch: tuple[bool, bool]
Active (pitch_x, pitch_y) lattice spacings in metres.
reference_index
instance-attribute
¶
reference_index: tuple[bool, bool]
Active fractional (column, row) reference-index coordinates.
position_offsets
instance-attribute
¶
position_offsets: list[int]
Sorted row-major source indices whose XYZ offsets are active.
relative_source_power
instance-attribute
¶
relative_source_power: bool
Whether mean-one per-source relative intensities are active.
frame_gains
instance-attribute
¶
frame_gains: bool
Whether mean-one per-frame intensity gains are active.
translation_specs
instance-attribute
¶
translation_specs: tuple[
CalibrationParameterSpec | None,
CalibrationParameterSpec | None,
CalibrationParameterSpec | None,
]
Inspectable per-component (tx, ty, tz) numerical specifications.
rotation_specs
instance-attribute
¶
rotation_specs: tuple[
CalibrationParameterSpec | None,
CalibrationParameterSpec | None,
CalibrationParameterSpec | None,
]
Inspectable per-component (rx, ry, rz) numerical specifications.
pitch_specs
instance-attribute
¶
pitch_specs: tuple[
CalibrationParameterSpec | None,
CalibrationParameterSpec | None,
]
Inspectable per-component (pitch_x, pitch_y) specifications.
reference_index_specs
instance-attribute
¶
reference_index_specs: tuple[
CalibrationParameterSpec | None,
CalibrationParameterSpec | None,
]
Inspectable reference-column and reference-row specifications.
position_offset_specs
instance-attribute
¶
position_offset_specs: dict[
int,
tuple[
CalibrationParameterSpec,
CalibrationParameterSpec,
CalibrationParameterSpec,
],
]
Inspectable source-indexed XYZ offset specifications.
relative_source_power_spec
instance-attribute
¶
relative_source_power_spec: CalibrationParameterSpec | None
Common numerical specification for active source powers.
frame_gain_spec
instance-attribute
¶
frame_gain_spec: CalibrationParameterSpec | None
Common numerical specification for active frame gains.
BoundedFiniteDifferenceOptimizer
¶
BoundedFiniteDifferenceOptimizer(
*,
max_steps: int = 2,
relative_tolerance: float = 1e-06,
initial_step_size: float = 0.25,
minimum_step_size: float = 1e-06,
step_reduction: float = 0.5,
)
Deterministic scaled finite differences with bounded backtracking.
max_steps
instance-attribute
¶
max_steps: int
Maximum bounded gradient steps per illumination-update phase.
relative_tolerance
instance-attribute
¶
relative_tolerance: float
Relative objective-improvement threshold for convergence.
initial_step_size
instance-attribute
¶
initial_step_size: float
Initial step length in normalized parameter coordinates.
minimum_step_size
instance-attribute
¶
minimum_step_size: float
Smallest normalized step attempted by backtracking.
step_reduction
instance-attribute
¶
step_reduction: float
Factor in (0, 1) applied after a rejected trial.
IlluminationCalibration
¶
IlluminationCalibration(
parameters: PlanarArrayCalibrationParameters,
*,
optimizer: BoundedFiniteDifferenceOptimizer
| None = None,
loss_type: str = "amplitude_mse",
)
Physical parameter selection, bounded optimizer, and canonical data loss.
The default amplitude_mse is the same measurement-domain objective used
by reconstruction diagnostics. Masks and frame weights are honored.
parameters
instance-attribute
¶
parameters: PlanarArrayCalibrationParameters
Explicit planar-array parameter selection and numerical specifications.
optimizer
instance-attribute
¶
optimizer: BoundedFiniteDifferenceOptimizer
Bounded deterministic optimizer settings.
JointReconstruction
¶
JointReconstruction(
object_algorithm: Fpie | Epry,
optics: Optics,
initial_illumination: Illumination,
illumination_calibration: IlluminationCalibration,
*,
outer_iterations: int = 10,
object_iterations_per_outer: int = 1,
illumination_steps_per_outer: int = 1,
)
Alternate analytic object/pupil updates with bounded physical LED calibration.
The initial model in problem must have been compiled from optics and
initial_illumination. Rotations are active right-handed extrinsic XYZ
radians, positions and pitches are metres, and multiplicative groups are
normalized to mean one. This implementation uses the canonical forward
model; unlike generic k-vector correction it always returns a realizable
PlanarLEDArray illumination.
object_algorithm accepts Fpie or Epry. EPRY may update the pupil
between physical phases.
References
Sun et al., Efficient positional misalignment correction method for Fourier ptychographic microscopy (2016). The implementation differs by using deterministic bounded finite differences rather than simulated annealing.
run
¶
run(
problem: ReconstructionProblem,
*,
callbacks: Iterable[Callback] | None = None,
resume_from: ReconstructionCheckpoint | None = None,
schedule: str = "sequential",
schedule_seed: int = 0,
) -> JointReconstructionResult
Run or resume alternating reconstruction without holding the Python GIL.
Callbacks receive the standard iteration context plus namespaced object
metrics and physical_illumination data, regularization, update-count,
and rejection metrics.