Skip to content

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", "reverse", or "shuffled".

'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, 1) applied when progress is insufficient.

0.5
minimum_object_step float

Positive step floor no greater than initial_object_step.

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.

References

Zuo, Sun, and Chen, Adaptive step-size strategy for noise-robust Fourier ptychographic microscopy, Optics Express 24(18), 20724-20744 (2016).

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", "reverse", or "shuffled".

'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", "reverse", or "shuffled".

'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, 1).

0.9
momentum_feedback float

Updated-velocity fraction added to the object, in [0, 1].

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", "reverse", or "shuffled".

'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

X. Ou, G. Zheng, and C. Yang, Embedded pupil function recovery for Fourier ptychographic microscopy (2014), Optics Express 22(5), 4960-4972.

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", "reverse", or "shuffled".

'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 [0, 2].

1.0
batch_size int | None

Frames per step; None processes all frames together.

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", "reverse", or "shuffled".

'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 keeps the ordinary untruncated gradient; the cited TPWFP work used 25. The gate uses intrinsic intensities and mini-batch residual statistics, and one decision is shared by all modes of a multiplexed pixel.

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, G. Zheng, K. Guo, F. Chen, and Q. Dai, Fourier ptychographic reconstruction using Wirtinger flow optimization (2015), Optics Express 23(4), 4856-4866.

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", "reverse", or "shuffled".

'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 unwrap_opd.

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

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

None
frame_order Sequence[int] | None

Optional global detector permutation, as in run.

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 (objects, height, width) common-grid transmissions copied into Rust. Independent coupling requires one per channel; shared coupling requires exactly one. Omission uses weighted measured-amplitude initialization, which splits mixed signal per unit spectral/local-gain weight as a heuristic.

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 frame_order. Fresh runs default to acquisition order; resumes inherit the saved schedule when both options are omitted.

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 (minimum, maximum) OPD bounds in metres. Width must not exceed the longest phase-difference synthetic wavelength.

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 (0, pi] radians. None retains all otherwise valid pixels while reporting residuals.

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 (rows, columns) mask of a constant-known-OPD region. Nonzero selects pixels valid in all channels. Pistons are estimated from equal-weight circular means of unit phasors.

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 q = 2*pi*OPD/min(wavelengths).

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 (rows, columns) OPD map in metres, inside the half-open interval. Requires initial_amplitudes.

None
initial_amplitudes FloatArray | None

Optional copied finite nonnegative C-contiguous float64 (channels, rows, columns) amplitudes in model channel order. Requires initial_opd_m; values are floored at sqrt(epsilon).

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.

maximum_fit_steps instance-attribute

maximum_fit_steps: int

Maximum bounded physical-fit steps.

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

Selected global translation, rotation, pitch, or reference-index variables.

options instance-attribute

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 (frames, height, width) intensities or an existing MeasurementStack. Inputs are copied when constructing a stack.

required
optics Optics

Physical optics used to compile model.

required
nominal_illumination Illumination

Physical planar-array illumination used to compile model.

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

Explicit planar-array parameter selection and numerical specifications.

optimizer instance-attribute

Bounded deterministic optimizer settings.

loss_type instance-attribute

loss_type: str

Canonical measurement-domain loss name.

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.