Struct GradientDescent 

pub struct GradientDescent {

    pub iterations: usize,
    pub object_step: f64,
    pub batch_size: usize,
    pub epsilon: f64,
    pub loss_type: LossType,
    pub poisson_truncation_threshold: Option<f64>,
    pub recover_illumination: bool,
    pub illumination_step: f64,
    pub illumination_finite_difference: f64,
    pub maximum_illumination_correction: f64,
    pub recover_pupil: bool,
    pub pupil_step: f64,
    pub constrain_pupil_support: bool,
    pub object_tv_weight: f64,
    pub object_tv_epsilon: f64,
    pub pupil_smoothing_weight: f64,
    pub parallel_workers: usize,
}

Wirtinger-style loss-gradient reconstruction for Fourier ptychography.

Method

The solver differentiates a selected real-valued data loss through the complex FPM forward model, accumulates gradients from a mini-batch, and applies a pupil-power-preconditioned update to the shared object spectrum. This is the Fourier-ptychographic Wirtinger-flow viewpoint: phase retrieval is treated as direct optimization rather than alternating hard projections. Losses are evaluated after accounting for known linear gain and background, so detector count scaling does not change the intrinsic update scale. With poisson_truncation_threshold enabled, a pre-update mini-batch pass rejects signal-dependent intensity outliers from the gradient while the reported Poisson objective continues to include every valid pixel.

Optional extensions recover the pupil with an analogous normalized gradient, estimate illumination offsets with finite-difference derivatives and diagonal Gauss–Newton scaling, and regularize the complex object or pupil. Incoherent multiplexing, these calibration updates, and the selectable losses extend the reference formulation.

Poisson truncation

For each mini-batch, the implementation computes the frame-weighted mean absolute residual R over unmasked pixels in positive-weight frames. A pixel with intrinsic target y, total predicted intensity p, and object RMS amplitude z_rms contributes exactly when |y - p| <= alpha * R * sqrt(p) / max(z_rms, sqrt(epsilon)). Known gain and background are removed before this test. One gate is shared by every mode of an incoherently multiplexed pixel and by object, pupil, and illumination gradients. The statistic is mini-batch-local rather than full-data, the object step is fixed rather than scheduled, and pupil and illumination recovery are implementation extensions beyond the cited object-only method.

Gauge convention

With pupil recovery enabled, the compiled pupil fixes the reported joint object/pupil gauge at iteration boundaries. The projection matches supported pupil energy and piston, fixes the remaining object piston, and removes an affine pupil phase ramp only on axes with zero effective subpixel offsets. Reciprocal object corrections preserve predicted intensities. Fractional axes retain their affine phase because bilinear crop interpolation does not commute exactly with a discrete phase ramp. Canonicalization runs before iteration callbacks, checkpoints, and final results, including after resume.

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.

The blind object/pupil ambiguities follow A. Fannjiang and P. Chen, “Blind ptychography: uniqueness and ambiguities” (2020), Inverse Problems 36, 045005; this implementation uses a Fourier-domain object and retains affine phase on fractionally interpolated axes.

Fields

iterations: usize

Number of complete passes through the acquisition schedule.

object_step: f64

Step size of the pupil-power-preconditioned object update.

batch_size: usize

Number of frame gradients averaged into one update.

epsilon: f64

Positive numerical floor used by losses and preconditioners.

loss_type: LossType

Data-fidelity objective to differentiate and report.

poisson_truncation_threshold: Option<f64>

Optional positive signal-dependent Poisson truncation coefficient.

None uses the ordinary untruncated gradient. The cited TPWFP work used 25; truncation requires LossType::PoissonNegativeLogLikelihood.

recover_illumination: bool

Whether to estimate a Fourier-grid offset for every illumination source.

illumination_step: f64

Step size of the diagonally scaled illumination-offset update.

illumination_finite_difference: f64

Central finite-difference spacing in Fourier-grid pixels.

maximum_illumination_correction: f64

Maximum absolute row or column correction, in Fourier-grid pixels.

recover_pupil: bool

Whether to update the complex pupil alongside the object.

pupil_step: f64

Step size of the normalized pupil update.

constrain_pupil_support: bool

Whether to zero recovered pupil values outside the compiled aperture.

object_tv_weight: f64

Weight of the isotropic total-variation step on the complex object; 0 disables it.

object_tv_epsilon: f64

Positive smoothing constant in the differentiable TV norm.

pupil_smoothing_weight: f64

Weight of quadratic nearest-neighbor pupil smoothing; 0 disables it and positive values require pupil recovery.

parallel_workers: usize

Maximum number of frame-gradient worker threads.

Implementations

impl GradientDescent

pub fn iterations(self, iterations: usize) -> Self

Sets the number of complete acquisition-schedule passes; validation requires non-zero.

pub fn object_step(self, step: f64) -> Self

Sets the finite positive step size of the preconditioned object update.

pub fn batch_size(self, batch_size: usize) -> Self

Sets the positive number of frame gradients averaged into one update.

pub fn loss_type(self, loss_type: LossType) -> Self

Selects the differentiable data-fidelity objective used for updates and reporting.

pub fn poisson_truncation_threshold(self, threshold: f64) -> Self

Enables signal-dependent Poisson-gradient truncation with threshold.

The cited TPWFP experiments selected 25. Validation requires a finite positive value and Poisson negative log likelihood.

pub fn recover_illumination(self, recover: bool) -> Self

Enables or disables per-source Fourier-grid offset recovery.

pub fn illumination_step(self, step: f64) -> Self

Sets the finite positive illumination-offset step size.

pub fn illumination_finite_difference(self, distance: f64) -> Self

Sets positive central finite-difference spacing in Fourier-grid pixels.

pub fn illumination_bounds(self, maximum_absolute_correction: f64) -> Self

Sets the non-negative maximum absolute row or column correction in grid pixels.

pub fn recover_pupil(self, recover: bool) -> Self

Enables or disables simultaneous complex-pupil recovery.

pub fn pupil_step(self, step: f64) -> Self

Sets the finite positive normalized pupil-update step size.

pub fn constrain_pupil_support(self, constrain: bool) -> Self

Selects whether pupil values outside the compiled binary support are forced to zero.

pub fn object_tv(self, weight: f64) -> Self

Sets a non-negative complex-object isotropic total-variation weight.

pub fn object_tv_epsilon(self, epsilon: f64) -> Self

Sets the finite positive smoothing constant in the differentiable TV norm.

pub fn pupil_smoothing(self, weight: f64) -> Self

Sets a non-negative quadratic nearest-neighbor pupil-smoothing weight.

pub fn parallel_workers(self, workers: usize) -> Self

Sets the maximum number of frame-gradient workers. Object, pupil, and illumination-calibration contributions are reduced deterministically.

Trait Implementations

impl Clone for GradientDescent

fn clone(&self) -> GradientDescent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for GradientDescent

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GradientDescent

fn default() -> Self

Returns the “default value” for a type.

impl ReconstructionAlgorithm for GradientDescent

type IterationMetrics = GradientDescentIterationMetrics

Algorithm-specific metrics emitted by each step and appended to the trace.

fn validate(&self) -> Result<()>

Validates solver parameters independently of a reconstruction problem.

fn canonicalize_state<M: MeasurementRead>( &self, problem: &ReconstructionProblem<M>, state: &mut ReconstructionState, ) -> Result<()>

Projects algorithm-owned ambiguities into a stable reported convention.

fn step<M: MeasurementRead>( &mut self, problem: &ReconstructionProblem<M>, state: &mut ReconstructionState, batch: &Batch, iteration: usize, ) -> Result<StepOutput<Self::IterationMetrics>>

Updates state for one scheduled batch in zero-based iteration.

fn iterations(&self) -> usize

Returns the requested number of complete schedule passes.

fn batch_size(&self) -> usize

Returns the number of measured frames combined into one step.

fn validate_problem<M: MeasurementRead>( &self, _problem: &ReconstructionProblem<M>, ) -> Result<()>

Validates solver requirements that depend on problem.

fn initialize<M: MeasurementRead>( &self, problem: &ReconstructionProblem<M>, ) -> Result<ReconstructionState>

Creates the default CPU-backed state for problem.

fn initialize_with_backend<M: MeasurementRead>( &self, problem: &ReconstructionProblem<M>, backend: Arc<dyn Backend>, ) -> Result<ReconstructionState>

Creates reconstruction state using the supplied execution backend.

fn supports_joint_reconstruction(&self) -> bool

Reports whether the algorithm may run inside physical joint calibration.

fn run<M: MeasurementRead>( self, problem: &ReconstructionProblem<M>, ) -> Result<ReconstructionResult>

where Self: Sized,

Runs the algorithm with default sequential scheduling and no callbacks.

fn run_with_callbacks<M: MeasurementRead>( self, problem: &ReconstructionProblem<M>, callbacks: Vec<Box<dyn Callback>>, ) -> Result<ReconstructionResult>

where Self: Sized,

Runs the algorithm and invokes callbacks at their declared hooks.

fn run_from_checkpoint<M: MeasurementRead>( self, problem: &ReconstructionProblem<M>, checkpoint: ReconstructionCheckpoint, ) -> Result<ReconstructionResult>

where Self: Sized,

Resumes a run from a checkpoint after validating it against problem.