Skip to main content

fpm_rs/algorithms/
multi_wavelength.rs

1//! Joint real-parameter optimization of nondispersive OPD and channel amplitudes.
2
3use std::{f64::consts::TAU, time::Instant};
4
5use ndarray::Array2;
6use num_complex::Complex64;
7use serde::{Deserialize, Serialize};
8
9use crate::{
10    Error, Result,
11    array_layout::StandardView2,
12    array_serde::Array2Data,
13    backend::FftDirection,
14    measurements::MeasurementRead,
15    model::{ObjectCoupling, fftshift_copy, ifftshift_copy},
16    reconstruction::{
17        IterationRecord, OpticalPathDifferenceResult, PhaseReference, ReconstructionTrace,
18        RuntimeInfo, SpectralChannelResult, SpectralCheckpointOptions,
19        SpectralReconstructionCheckpoint, SpectralReconstructionProblem,
20        SpectralReconstructionResult, SpectralReconstructionState, SyntheticWavelengthUnwrapper,
21        spectral_checkpoint::{StoredOpd, StoredSolver, fingerprints},
22    },
23};
24
25use super::{SpectralAlternatingProjection, SpectralReconstructionAlgorithm};
26
27/// Joint OPD fit, derived wavelength fields, and optional initialization diagnostics.
28#[derive(Clone, Debug)]
29pub struct MultiWavelengthSolverResult {
30    /// Optimized nondispersive OPD in metres on the common `(row, column)` grid.
31    pub opd_m: Array2<f64>,
32    /// Derived channel fields and fixed pupils, with the joint objective trace.
33    /// The model uses independent field storage; this solver couples their phases
34    /// through `opd_m`. Trace iteration zero is the constrained initial objective,
35    /// followed by post-update smoothed amplitude objectives.
36    pub spectral: SpectralReconstructionResult,
37    /// Phase-mixing diagnostics before joint optimization, absent for explicit OPD starts.
38    pub initialization_opd: Option<OpticalPathDifferenceResult>,
39    /// Independent-field AP trace used by automatic initialization, otherwise absent.
40    pub initialization_trace: Option<ReconstructionTrace>,
41    /// Final accepted OPD/amplitude state, fixed gauge, and initialization records for exact resume.
42    pub checkpoint: SpectralReconstructionCheckpoint,
43}
44
45/// Fits one shared nondispersive OPD and a positive amplitude for each wavelength.
46///
47/// Every forward evaluation uses `O_c = A_c exp(i 2π d / λ_c)`, with vacuum
48/// wavelengths in metres. All fixed channel kernels and sparse intensity mixtures
49/// come from the compiled spectral model. The objective is the frame-weighted
50/// mean of valid-pixel `(sqrt(prediction + epsilon) - sqrt(max(measurement, 0) + epsilon))²`,
51/// including known detector gain/background. Analytic adjoints differentiate the
52/// objective into amplitudes and the real shared OPD; there is no independent
53/// channel phase update. A full-data backtracking step projects amplitudes to
54/// at least `sqrt(epsilon)` and OPD to its explicit half-open interval.
55///
56/// The phase coordinate for descent is `q = 2π d / min(λ)`. Both real gradients
57/// are multiplied by the common-grid pixel count before applying their separate
58/// step multipliers. Backtracking halves one common multiplier until the full
59/// objective is non-increasing. Failure to find such a step stops cleanly and is
60/// reported by `runtime.stopped_early`; this nonconvex solver cannot guarantee
61/// recovery of a branch missed by initialization.
62///
63/// Automatic initialization reconstructs independent fields with spectral AP,
64/// then uses referenced synthetic-wavelength unwrapping. Every initial OPD pixel
65/// must be valid. An explicit OPD/amplitude start can bypass that initializer.
66/// A reference region is fixed pixelwise at its known OPD throughout optimization;
67/// explicit piston offsets instead fix the initial spatial mean OPD. Absolute
68/// reference, nondispersive OPD, registered grids, and matched effective resolution
69/// remain assumptions. Pupils, source powers, geometry, gain, and background are fixed.
70///
71/// # Example
72/// ```
73/// use fpm_rs::{Result, algorithms::{MultiWavelengthGradientDescent, MultiWavelengthSolverResult},
74///     measurements::MeasurementRead, reconstruction::{PhaseReference,
75///     SpectralReconstructionProblem, SyntheticWavelengthUnwrapper}};
76/// fn solve<M: MeasurementRead>(problem: &SpectralReconstructionProblem<M>,
77///     reference: &PhaseReference) -> Result<MultiWavelengthSolverResult> {
78///     let unwrapper = SyntheticWavelengthUnwrapper::new((-1e-6, 2e-6))?;
79///     MultiWavelengthGradientDescent::default().run(problem, &unwrapper, reference)
80/// }
81/// ```
82///
83/// # References
84/// L. Bian, J. Suo, G. Zheng, K. Guo, F. Chen, and Q. Dai,
85/// [“Fourier ptychographic reconstruction using Wirtinger flow optimization”](https://doi.org/10.1364/OE.23.004856),
86/// *Optics Express* **23**(4), 4856–4866 (2015), for FPM loss-gradient optimization.
87/// The shared-OPD chain rule, smoothed amplitude loss, box/gauge projections, and
88/// monotone full-data backtracking are implementation extensions, not that paper's solver.
89/// See [`SyntheticWavelengthUnwrapper`] for the initialization method and reference.
90#[derive(Clone, Debug, Serialize, Deserialize)]
91#[serde(deny_unknown_fields)]
92pub struct MultiWavelengthGradientDescent {
93    /// Positive maximum number of accepted full-data joint updates.
94    pub iterations: usize,
95    /// Positive number of spectral AP passes when automatic initialization is used.
96    pub initialization_iterations: usize,
97    /// Finite positive multiplier for the pixel-count-scaled real amplitude gradient.
98    pub amplitude_step: f64,
99    /// Finite positive multiplier for the pixel-count-scaled phase-coordinate gradient.
100    pub opd_step: f64,
101    /// Positive maximum number of step trials per update, halving the common multiplier.
102    pub max_backtracks: usize,
103    /// Finite positive intensity smoothing and squared minimum amplitude.
104    pub epsilon: f64,
105}
106
107impl Default for MultiWavelengthGradientDescent {
108    fn default() -> Self {
109        Self {
110            iterations: 100,
111            initialization_iterations: 50,
112            amplitude_step: 1.0,
113            opd_step: 1.0,
114            max_backtracks: 30,
115            epsilon: 1e-10,
116        }
117    }
118}
119
120struct Parameters {
121    opd: Array2<f64>,
122    amplitudes: Vec<Array2<f64>>,
123}
124
125#[derive(Clone, Debug, Serialize, Deserialize)]
126#[serde(rename_all = "snake_case", deny_unknown_fields)]
127pub(crate) enum Gauge {
128    Region { pixels: Vec<usize>, opd_m: f64 },
129    Mean(f64),
130}
131
132struct Execution {
133    parameters: Parameters,
134    gauge: Gauge,
135    opd_range_m: (f64, f64),
136    trace: ReconstructionTrace,
137    completed: usize,
138    elapsed_offset: f64,
139    signature: (String, String),
140    initialization_opd: Option<OpticalPathDifferenceResult>,
141    initialization_trace: Option<ReconstructionTrace>,
142}
143
144struct Gradient {
145    amplitude: Vec<Array2<f64>>,
146    phase: Array2<f64>,
147}
148
149fn invalid(name: &'static str, reason: impl Into<String>) -> Error {
150    Error::InvalidParameter {
151        name,
152        reason: reason.into(),
153    }
154}
155
156impl MultiWavelengthGradientDescent {
157    /// Checks positive iteration/trial counts, step multipliers, and numerical smoothing.
158    /// `initialization_iterations` is checked only by the automatic `run` path.
159    pub fn validate(&self) -> Result<()> {
160        if self.iterations == 0 || self.max_backtracks == 0 {
161            return Err(invalid("iterations/max_backtracks", "must be positive"));
162        }
163        for (name, value) in [
164            ("amplitude_step", self.amplitude_step),
165            ("opd_step", self.opd_step),
166            ("epsilon", self.epsilon),
167        ] {
168            if !value.is_finite() || value <= 0.0 {
169                return Err(invalid(name, "must be finite and positive"));
170            }
171        }
172        Ok(())
173    }
174
175    /// Reconstructs independent fields, unwraps their phases, then jointly refines OPD/amplitudes.
176    ///
177    /// Requires independent model storage and at least two wavelengths. Rejects
178    /// any invalid phase-unwrapped initialization pixel; use `run_from_opd` for
179    /// an externally supplied finite branch when phase fusion cannot initialize it.
180    /// The result retains the pre-fit unwrapping diagnostics and independent AP trace.
181    pub fn run<M: MeasurementRead>(
182        &self,
183        problem: &SpectralReconstructionProblem<M>,
184        unwrapper: &SyntheticWavelengthUnwrapper,
185        reference: &PhaseReference,
186    ) -> Result<MultiWavelengthSolverResult> {
187        self.run_with_options(
188            problem,
189            unwrapper,
190            reference,
191            &SpectralCheckpointOptions::default(),
192        )
193    }
194
195    /// Runs automatic AP/phase initialization with optional accepted-update checkpoint files.
196    /// The final checkpoint retains initialization records and never repeats them on resume.
197    pub fn run_with_options<M: MeasurementRead>(
198        &self,
199        problem: &SpectralReconstructionProblem<M>,
200        unwrapper: &SyntheticWavelengthUnwrapper,
201        reference: &PhaseReference,
202        options: &SpectralCheckpointOptions,
203    ) -> Result<MultiWavelengthSolverResult> {
204        options.validate()?;
205        self.validate_problem(problem, unwrapper.opd_range_m)?;
206        if self.initialization_iterations == 0 {
207            return Err(invalid(
208                "initialization_iterations",
209                "must be positive for automatic initialization",
210            ));
211        }
212        let initial = SpectralAlternatingProjection::default()
213            .iterations(self.initialization_iterations)
214            .run(problem)?;
215        let opd = initial.unwrap_opd(unwrapper, reference, None)?;
216        if opd.valid_mask.iter().any(|&v| v == 0) {
217            return Err(invalid(
218                "initialization_opd",
219                "phase unwrapping left invalid pixels; supply an explicit finite OPD/amplitude start or improve the reference/acquisition",
220            ));
221        }
222        let amplitudes = initial
223            .channels
224            .iter()
225            .map(|c| c.amplitude.clone())
226            .collect();
227        self.start_from_opd(
228            problem,
229            unwrapper.opd_range_m,
230            reference,
231            opd.opd_m.clone(),
232            amplitudes,
233            Some(opd),
234            Some(initial.trace),
235            options,
236        )
237    }
238
239    /// Jointly refines owned finite C-contiguous OPD and channel amplitudes on the common grid.
240    ///
241    /// OPD is in metres and must be inside `opd_range_m = [lower, upper)`.
242    /// Amplitudes must be finite and nonnegative, one array per channel, and are
243    /// floored at `sqrt(epsilon)`. This bypasses phase unwrapping, so the interval
244    /// may exceed a synthetic period; the caller supplies the correct fringe branch.
245    /// A region reference fixes selected pixels to its known in-range OPD. Offsets
246    /// must contain one finite piston per channel, and retain the initial OPD mean;
247    /// no phase is subtracted from the already unwrapped explicit start.
248    pub fn run_from_opd<M: MeasurementRead>(
249        &self,
250        problem: &SpectralReconstructionProblem<M>,
251        opd_range_m: (f64, f64),
252        reference: &PhaseReference,
253        opd_m: Array2<f64>,
254        amplitudes: Vec<Array2<f64>>,
255    ) -> Result<MultiWavelengthSolverResult> {
256        self.run_from_opd_with_options(
257            problem,
258            opd_range_m,
259            reference,
260            opd_m,
261            amplitudes,
262            &SpectralCheckpointOptions::default(),
263        )
264    }
265
266    /// Fits explicit OPD/amplitude starts while saving periodic accepted-state checkpoints.
267    /// Scientific input and gauge contracts are identical to `run_from_opd`.
268    #[allow(clippy::too_many_arguments)]
269    pub fn run_from_opd_with_options<M: MeasurementRead>(
270        &self,
271        problem: &SpectralReconstructionProblem<M>,
272        opd_range_m: (f64, f64),
273        reference: &PhaseReference,
274        opd_m: Array2<f64>,
275        amplitudes: Vec<Array2<f64>>,
276        options: &SpectralCheckpointOptions,
277    ) -> Result<MultiWavelengthSolverResult> {
278        self.start_from_opd(
279            problem,
280            opd_range_m,
281            reference,
282            opd_m,
283            amplitudes,
284            None,
285            None,
286            options,
287        )
288    }
289
290    /// Resumes the saved joint OPD state without initialization or another gauge projection.
291    /// `iterations` is the total target; all other solver options, detector values,
292    /// masks/weights, and ordered compiled model metadata must match the checkpoint.
293    pub fn run_from_checkpoint<M: MeasurementRead>(
294        &self,
295        problem: &SpectralReconstructionProblem<M>,
296        checkpoint: SpectralReconstructionCheckpoint,
297    ) -> Result<MultiWavelengthSolverResult> {
298        self.run_from_checkpoint_with_options(
299            problem,
300            checkpoint,
301            &SpectralCheckpointOptions::default(),
302        )
303    }
304
305    /// Resumes joint state and optionally continues periodic accepted-update checkpoint output.
306    pub fn run_from_checkpoint_with_options<M: MeasurementRead>(
307        &self,
308        problem: &SpectralReconstructionProblem<M>,
309        checkpoint: SpectralReconstructionCheckpoint,
310        options: &SpectralCheckpointOptions,
311    ) -> Result<MultiWavelengthSolverResult> {
312        self.validate()?;
313        options.validate()?;
314        checkpoint.validate_for_problem(problem)?;
315        let signature = checkpoint.fingerprints();
316        let StoredSolver::JointOpd {
317            configuration,
318            opd,
319            amplitudes,
320            opd_range_m,
321            gauge,
322            initialization_opd,
323            initialization_trace,
324        } = checkpoint.state
325        else {
326            return Err(invalid(
327                "resume_from",
328                "spectral AP state cannot resume joint OPD descent",
329            ));
330        };
331        if configuration != self.configuration()?
332            || self.iterations < checkpoint.completed_iterations
333        {
334            return Err(invalid(
335                "resume_from",
336                "stepping options changed or total target precedes the saved iteration",
337            ));
338        }
339        self.validate_problem(problem, opd_range_m)?;
340        let execution = Execution {
341            parameters: Parameters {
342                opd: opd.into_array()?,
343                amplitudes: amplitudes
344                    .into_iter()
345                    .map(Array2Data::into_array)
346                    .collect::<Result<_>>()?,
347            },
348            gauge,
349            opd_range_m,
350            trace: checkpoint.trace,
351            completed: checkpoint.completed_iterations,
352            elapsed_offset: checkpoint.elapsed_seconds,
353            signature,
354            initialization_opd: initialization_opd.map(|o| (*o).into_result()).transpose()?,
355            initialization_trace,
356        };
357        self.execute(problem, execution, options)
358    }
359
360    #[allow(clippy::too_many_arguments)]
361    fn start_from_opd<M: MeasurementRead>(
362        &self,
363        problem: &SpectralReconstructionProblem<M>,
364        opd_range_m: (f64, f64),
365        reference: &PhaseReference,
366        opd_m: Array2<f64>,
367        amplitudes: Vec<Array2<f64>>,
368        initialization_opd: Option<OpticalPathDifferenceResult>,
369        initialization_trace: Option<ReconstructionTrace>,
370        options: &SpectralCheckpointOptions,
371    ) -> Result<MultiWavelengthSolverResult> {
372        options.validate()?;
373        self.validate_problem(problem, opd_range_m)?;
374        let started = Instant::now();
375        let shape = problem.model.reconstruction_shape();
376        if opd_m.dim() != shape || amplitudes.len() != problem.model.channels().len() {
377            return Err(Error::InvalidShape(
378                "joint OPD/amplitudes must match the common grid and channel count".into(),
379            ));
380        }
381        StandardView2::try_from(opd_m.view())?;
382        if opd_m
383            .iter()
384            .any(|&d| !d.is_finite() || d < opd_range_m.0 || d >= opd_range_m.1)
385        {
386            return Err(invalid(
387                "initial_opd_m",
388                "must be finite and inside the half-open OPD interval",
389            ));
390        }
391        for amplitude in &amplitudes {
392            if amplitude.dim() != shape {
393                return Err(Error::InvalidShape(
394                    "every amplitude must match the common grid".into(),
395                ));
396            }
397            StandardView2::try_from(amplitude.view())?;
398            if amplitude.iter().any(|&v| !v.is_finite() || v < 0.0) {
399                return Err(invalid(
400                    "initial_amplitudes",
401                    "must be finite and nonnegative",
402                ));
403            }
404        }
405        let mut parameters = Parameters {
406            opd: opd_m,
407            amplitudes,
408        };
409        for amplitude in &mut parameters.amplitudes {
410            amplitude.mapv_inplace(|v| v.max(self.epsilon.sqrt()));
411        }
412        let gauge = Gauge::new(reference, &parameters, opd_range_m)?;
413        gauge.project(&mut parameters.opd, opd_range_m)?;
414        let signature = fingerprints(problem)?;
415        let execution = Execution {
416            parameters,
417            gauge,
418            opd_range_m,
419            trace: ReconstructionTrace::default(),
420            completed: 0,
421            elapsed_offset: started.elapsed().as_secs_f64(),
422            signature,
423            initialization_opd,
424            initialization_trace,
425        };
426        self.execute(problem, execution, options)
427    }
428
429    fn execute<M: MeasurementRead>(
430        &self,
431        problem: &SpectralReconstructionProblem<M>,
432        execution: Execution,
433        options: &SpectralCheckpointOptions,
434    ) -> Result<MultiWavelengthSolverResult> {
435        let started = Instant::now();
436        let Execution {
437            mut parameters,
438            gauge,
439            opd_range_m,
440            mut trace,
441            mut completed,
442            elapsed_offset,
443            signature,
444            initialization_opd,
445            initialization_trace,
446        } = execution;
447        let configuration = self.configuration()?;
448        let wavelengths: Vec<_> = problem
449            .model
450            .channels()
451            .iter()
452            .map(|c| c.model.sampling().wavelength.unwrap())
453            .collect();
454        let shortest = wavelengths.iter().copied().reduce(f64::min).unwrap();
455        let mut state =
456            SpectralReconstructionState::from_objects(problem, parameters.objects(&wavelengths))?;
457        let (mut objective, _) =
458            self.evaluate(problem, &mut state, &parameters, &wavelengths, false)?;
459        if trace.iterations.is_empty() {
460            trace.iterations.push(IterationRecord {
461                iteration: 0,
462                objective,
463                elapsed_seconds: elapsed_offset + started.elapsed().as_secs_f64(),
464            });
465        } else if (trace.iterations.last().unwrap().objective - objective).abs()
466            > 64.0 * f64::EPSILON * objective.abs().max(1.0)
467        {
468            return Err(invalid(
469                "resume_from",
470                "saved objective does not match the joint numerical state",
471            ));
472        }
473        for iteration in (completed + 1)..=self.iterations {
474            let (_, gradient) =
475                self.evaluate(problem, &mut state, &parameters, &wavelengths, true)?;
476            let gradient = gradient.unwrap();
477            let mut step = 1.0;
478            let mut accepted = None;
479            for _ in 0..self.max_backtracks {
480                let mut candidate = parameters.updated(&gradient, step, self, shortest);
481                if !candidate.is_finite() {
482                    step *= 0.5;
483                    continue;
484                }
485                gauge.project(&mut candidate.opd, opd_range_m)?;
486                set_fields(&mut state, &candidate.objects(&wavelengths))?;
487                match self.evaluate(problem, &mut state, &candidate, &wavelengths, false) {
488                    Ok((value, _)) if value <= objective => {
489                        accepted = Some((candidate, value));
490                        break;
491                    }
492                    Ok(_) | Err(Error::Numerical(_)) => step *= 0.5,
493                    Err(error) => return Err(error),
494                }
495            }
496            let Some((candidate, value)) = accepted else {
497                set_fields(&mut state, &parameters.objects(&wavelengths))?;
498                break;
499            };
500            parameters = candidate;
501            objective = value;
502            completed = iteration;
503            trace.iterations.push(IterationRecord {
504                iteration,
505                objective,
506                elapsed_seconds: elapsed_offset + started.elapsed().as_secs_f64(),
507            });
508            if options.directory.is_some() && iteration.is_multiple_of(options.every) {
509                let checkpoint = SpectralReconstructionCheckpoint::capture(
510                    problem.model.clone(),
511                    &signature,
512                    completed,
513                    elapsed_offset + started.elapsed().as_secs_f64(),
514                    trace.clone(),
515                    StoredSolver::JointOpd {
516                        configuration: configuration.clone(),
517                        opd: Array2Data::from_view(parameters.opd.view()),
518                        amplitudes: parameters
519                            .amplitudes
520                            .iter()
521                            .map(|a| Array2Data::from_view(a.view()))
522                            .collect(),
523                        opd_range_m,
524                        gauge: gauge.clone(),
525                        initialization_opd: initialization_opd
526                            .as_ref()
527                            .map(|o| Box::new(StoredOpd::from_result(o))),
528                        initialization_trace: initialization_trace.clone(),
529                    },
530                );
531                options.write(&checkpoint, false)?;
532            }
533        }
534        let objects = parameters.objects(&wavelengths);
535        let channels = problem
536            .model
537            .channels()
538            .iter()
539            .enumerate()
540            .map(|(i, c)| {
541                let object = objects[i].clone();
542                SpectralChannelResult {
543                    channel_id: c.channel_id.clone(),
544                    wavelength_vacuum_m: wavelengths[i],
545                    phase: crate::complex::phase(object.view()),
546                    amplitude: parameters.amplitudes[i].clone(),
547                    object,
548                    object_spectrum: state.spectra[i].clone().into_inner(),
549                    pupil: c.model.pupil().clone(),
550                }
551            })
552            .collect();
553        let elapsed_seconds = elapsed_offset + started.elapsed().as_secs_f64();
554        let checkpoint = SpectralReconstructionCheckpoint::capture(
555            problem.model.clone(),
556            &signature,
557            completed,
558            elapsed_seconds,
559            trace.clone(),
560            StoredSolver::JointOpd {
561                configuration,
562                opd: Array2Data::from_view(parameters.opd.view()),
563                amplitudes: parameters
564                    .amplitudes
565                    .iter()
566                    .map(|a| Array2Data::from_view(a.view()))
567                    .collect(),
568                opd_range_m,
569                gauge,
570                initialization_opd: initialization_opd
571                    .as_ref()
572                    .map(|o| Box::new(StoredOpd::from_result(o))),
573                initialization_trace: initialization_trace.clone(),
574            },
575        );
576        options.write(&checkpoint, true)?;
577        Ok(MultiWavelengthSolverResult {
578            checkpoint,
579            opd_m: parameters.opd,
580            spectral: SpectralReconstructionResult {
581                channels,
582                object_coupling: ObjectCoupling::Independent,
583                trace,
584                checkpoint: None,
585                runtime: RuntimeInfo {
586                    elapsed_seconds,
587                    completed_iterations: completed,
588                    stopped_early: completed < self.iterations,
589                    algorithm: "MultiWavelengthGradientDescent".into(),
590                },
591            },
592            initialization_opd,
593            initialization_trace,
594        })
595    }
596
597    fn configuration(&self) -> Result<String> {
598        let mut configuration = self.clone();
599        configuration.iterations = 1;
600        Ok(serde_json::to_string(&configuration)?)
601    }
602
603    fn validate_problem<M: MeasurementRead>(
604        &self,
605        problem: &SpectralReconstructionProblem<M>,
606        range: (f64, f64),
607    ) -> Result<()> {
608        self.validate()?;
609        problem.validate()?;
610        SyntheticWavelengthUnwrapper::new(range)?;
611        if problem.model.object_coupling() != ObjectCoupling::Independent
612            || problem.model.channels().len() < 2
613        {
614            return Err(invalid(
615                "object_coupling/channels",
616                "joint OPD requires independent field storage and at least two wavelengths",
617            ));
618        }
619        let shortest = problem
620            .model
621            .channels()
622            .iter()
623            .map(|c| c.model.sampling().wavelength.unwrap())
624            .reduce(f64::min)
625            .unwrap();
626        if range.0.abs().max(range.1.abs()) / shortest >= (1_u64 << 52) as f64 {
627            return Err(invalid(
628                "opd_range_m",
629                "bounds exceed exact floating-point fringe-order precision",
630            ));
631        }
632        Ok(())
633    }
634
635    fn evaluate<M: MeasurementRead>(
636        &self,
637        problem: &SpectralReconstructionProblem<M>,
638        state: &mut SpectralReconstructionState,
639        parameters: &Parameters,
640        wavelengths: &[f64],
641        with_gradient: bool,
642    ) -> Result<(f64, Option<Gradient>)> {
643        let high_shape = problem.model.reconstruction_shape();
644        let low_shape = problem.model.image_shape();
645        let mut spectra: Vec<_> = (0..wavelengths.len())
646            .map(|_| Array2::zeros(high_shape))
647            .collect();
648        let total_weight = (0..problem.model.frame_count())
649            .map(|f| problem.measurements.frame_weight(f))
650            .collect::<Result<Vec<_>>>()?
651            .iter()
652            .sum::<f64>();
653        if !total_weight.is_finite() || total_weight <= 0.0 {
654            return Err(Error::InvalidMeasurements(
655                "joint OPD total frame weight must be finite and positive".into(),
656            ));
657        }
658        let mut objective = 0.0;
659        for frame in 0..problem.model.frame_count() {
660            let weight = problem.measurements.frame_weight(frame)?;
661            if weight == 0.0 {
662                continue;
663            }
664            state.evaluate_frame(&problem.model, frame)?;
665            let row = &problem.model.acquisition().frames()[frame];
666            let measured = problem.measurements.frame(frame)?;
667            let mask = problem.measurements.frame_mask(frame)?;
668            let valid = (0..measured.len())
669                .filter(|&p| mask.is_none_or(|m| m[p] != 0))
670                .count();
671            let normalization = weight / total_weight / valid as f64;
672            for pixel in 0..measured.len() {
673                if mask.is_some_and(|m| m[pixel] == 0) {
674                    state.projection[pixel] = Complex64::default();
675                    continue;
676                }
677                let prediction = state.effective_gain * state.predicted[pixel] + row.background;
678                if !prediction.is_finite() || prediction < 0.0 {
679                    return Err(Error::Numerical(
680                        "joint OPD prediction is not finite/nonnegative".into(),
681                    ));
682                }
683                let root = (prediction + self.epsilon).sqrt();
684                let target = (measured[pixel].max(0.0) + self.epsilon).sqrt();
685                objective += normalization * (root - target).powi(2);
686                state.projection[pixel] = Complex64::new(
687                    normalization * state.effective_gain * (1.0 - target / root),
688                    0.0,
689                );
690            }
691            if with_gradient {
692                for mode in &state.modes {
693                    let kernel = &problem.model.channels()[mode.channel].model;
694                    for p in 0..measured.len() {
695                        state.field[p] = mode.field[p] * (mode.weight * state.projection[p].re);
696                    }
697                    state.backend.fft2(
698                        &mut state.field,
699                        low_shape,
700                        FftDirection::Forward,
701                        &mut state.column,
702                    )?;
703                    fftshift_copy(&state.field, &mut state.centered, low_shape);
704                    for (p, &pupil) in kernel.pupil().values().iter().enumerate() {
705                        state.update[p] = pupil.conj() * state.centered[p];
706                    }
707                    kernel.insert_patch_adjoint(
708                        spectra[mode.channel].view_mut(),
709                        mode.source,
710                        &state.update,
711                        1.0,
712                    )?;
713                }
714            }
715            state.modes.clear();
716        }
717        if !objective.is_finite() {
718            return Err(Error::Numerical("joint OPD objective is nonfinite".into()));
719        }
720        if !with_gradient {
721            return Ok((objective, None));
722        }
723        let shortest = wavelengths.iter().copied().reduce(f64::min).unwrap();
724        let mut gradient = Gradient {
725            amplitude: Vec::new(),
726            phase: Array2::zeros(high_shape),
727        };
728        // FFT_norm^* = IFFT / N_high, IFFT^* = N_low FFT_norm.
729        // Preserve both normalization factors before the real-parameter chain rule.
730        let adjoint_scale =
731            (low_shape.0 * low_shape.1) as f64 / (high_shape.0 * high_shape.1) as f64;
732        for (channel, spectrum) in spectra.iter().enumerate() {
733            let mut field = vec![Complex64::default(); spectrum.len()];
734            ifftshift_copy(spectrum.as_slice().unwrap(), &mut field, high_shape);
735            state.backend.fft2(
736                &mut field,
737                high_shape,
738                FftDirection::Inverse,
739                &mut state.column,
740            )?;
741            let mut amplitude_gradient = Array2::zeros(high_shape);
742            for (p, &value) in field.iter().enumerate() {
743                let index = (p / high_shape.1, p % high_shape.1);
744                let unit = Complex64::from_polar(
745                    1.0,
746                    TAU * (parameters.opd[index] / wavelengths[channel]).rem_euclid(1.0),
747                );
748                let rotated = unit.conj() * value * adjoint_scale;
749                amplitude_gradient[index] = 2.0 * rotated.re;
750                gradient.phase[index] += 2.0
751                    * (shortest / wavelengths[channel])
752                    * parameters.amplitudes[channel][index]
753                    * rotated.im;
754            }
755            gradient.amplitude.push(amplitude_gradient);
756        }
757        if gradient
758            .phase
759            .iter()
760            .chain(gradient.amplitude.iter().flat_map(|a| a.iter()))
761            .any(|v| !v.is_finite())
762        {
763            return Err(Error::Numerical("joint OPD gradient is nonfinite".into()));
764        }
765        Ok((objective, Some(gradient)))
766    }
767}
768
769impl Parameters {
770    fn objects(&self, wavelengths: &[f64]) -> Vec<Array2<Complex64>> {
771        self.amplitudes
772            .iter()
773            .zip(wavelengths)
774            .map(|(a, &w)| {
775                Array2::from_shape_fn(self.opd.dim(), |i| {
776                    Complex64::from_polar(a[i], TAU * (self.opd[i] / w).rem_euclid(1.0))
777                })
778            })
779            .collect()
780    }
781    fn is_finite(&self) -> bool {
782        self.opd
783            .iter()
784            .chain(self.amplitudes.iter().flat_map(|a| a.iter()))
785            .all(|v| v.is_finite())
786    }
787    fn updated(
788        &self,
789        gradient: &Gradient,
790        step: f64,
791        solver: &MultiWavelengthGradientDescent,
792        shortest: f64,
793    ) -> Self {
794        let scale = step * self.opd.len() as f64;
795        let opd = Array2::from_shape_fn(self.opd.dim(), |i| {
796            self.opd[i] - scale * solver.opd_step * gradient.phase[i] * shortest / TAU
797        });
798        let amplitudes = self
799            .amplitudes
800            .iter()
801            .zip(&gradient.amplitude)
802            .map(|(a, g)| {
803                Array2::from_shape_fn(a.dim(), |i| {
804                    (a[i] - scale * solver.amplitude_step * g[i]).max(solver.epsilon.sqrt())
805                })
806            })
807            .collect();
808        Self { opd, amplitudes }
809    }
810}
811
812impl Gauge {
813    pub(crate) fn validate(&self, opd: &Array2Data<f64>, range: (f64, f64)) -> Result<()> {
814        match self {
815            Self::Region { pixels, opd_m } => {
816                if pixels.is_empty()
817                    || pixels.windows(2).any(|w| w[0] >= w[1])
818                    || !opd_m.is_finite()
819                    || *opd_m < range.0
820                    || *opd_m >= range.1
821                    || pixels
822                        .iter()
823                        .any(|&p| p >= opd.data.len() || opd.data[p] != *opd_m)
824                {
825                    return Err(invalid(
826                        "checkpoint_gauge",
827                        "reference pixels must be sorted, nonempty, in range, and fixed at the known OPD",
828                    ));
829                }
830            }
831            Self::Mean(target) => {
832                let mean: f64 = opd.data.iter().map(|v| v / opd.data.len() as f64).sum();
833                let tolerance = 64.0 * f64::EPSILON * range.0.abs().max(range.1.abs());
834                if !target.is_finite()
835                    || *target < range.0
836                    || *target >= range.1
837                    || (mean - target).abs() > tolerance
838                {
839                    return Err(invalid(
840                        "checkpoint_gauge",
841                        "stored mean OPD disagrees with the fixed gauge",
842                    ));
843                }
844            }
845        }
846        Ok(())
847    }
848    fn new(reference: &PhaseReference, parameters: &Parameters, range: (f64, f64)) -> Result<Self> {
849        match reference {
850            PhaseReference::Offsets(offsets) => {
851                if offsets.len() != parameters.amplitudes.len()
852                    || offsets.iter().any(|v| !v.is_finite())
853                {
854                    return Err(invalid(
855                        "phase_offsets_rad",
856                        "requires one finite piston per channel",
857                    ));
858                }
859                // Sum after dividing to avoid overflow in a finite in-range map.
860                Ok(Self::Mean(
861                    parameters
862                        .opd
863                        .iter()
864                        .map(|d| d / parameters.opd.len() as f64)
865                        .sum(),
866                ))
867            }
868            PhaseReference::Region { mask, opd_m } => {
869                if mask.dim() != parameters.opd.dim() {
870                    return Err(Error::InvalidShape(
871                        "OPD reference mask must match the common grid".into(),
872                    ));
873                }
874                let mask = StandardView2::try_from(mask.view())?;
875                if !opd_m.is_finite() || *opd_m < range.0 || *opd_m >= range.1 {
876                    return Err(invalid(
877                        "reference_opd_m",
878                        "must be finite and inside the OPD interval",
879                    ));
880                }
881                let pixels = mask
882                    .as_slice()
883                    .iter()
884                    .enumerate()
885                    .filter_map(|(i, &v)| (v != 0).then_some(i))
886                    .collect::<Vec<_>>();
887                if pixels.is_empty() {
888                    return Err(invalid(
889                        "reference_mask",
890                        "reference region must be nonempty",
891                    ));
892                }
893                Ok(Self::Region {
894                    pixels,
895                    opd_m: *opd_m,
896                })
897            }
898        }
899    }
900    fn project(&self, opd: &mut Array2<f64>, range: (f64, f64)) -> Result<()> {
901        let upper = range.1.next_down();
902        let data = opd.as_slice_mut().unwrap();
903        match self {
904            Self::Region { pixels, opd_m } => {
905                for d in data.iter_mut() {
906                    *d = d.clamp(range.0, upper);
907                }
908                for &p in pixels {
909                    data[p] = *opd_m;
910                }
911            }
912            Self::Mean(target) => {
913                // Euclidean projection onto the box with a fixed mean: a common
914                // shift followed by clipping, solved by monotone bisection.
915                let min = data.iter().copied().reduce(f64::min).unwrap();
916                let max = data.iter().copied().reduce(f64::max).unwrap();
917                let mut lower = range.0 - max;
918                let mut higher = upper - min;
919                if !lower.is_finite() || !higher.is_finite() {
920                    return Err(Error::Numerical("OPD mean projection overflow".into()));
921                }
922                for _ in 0..64 {
923                    let shift = lower * 0.5 + higher * 0.5;
924                    let mean = data
925                        .iter()
926                        .map(|d| (d + shift).clamp(range.0, upper) / data.len() as f64)
927                        .sum::<f64>();
928                    if mean < *target {
929                        lower = shift;
930                    } else {
931                        higher = shift;
932                    }
933                }
934                let shift = lower * 0.5 + higher * 0.5;
935                for d in data.iter_mut() {
936                    *d = (*d + shift).clamp(range.0, upper);
937                }
938            }
939        }
940        Ok(())
941    }
942}
943
944fn set_fields(
945    state: &mut SpectralReconstructionState,
946    objects: &[Array2<Complex64>],
947) -> Result<()> {
948    let shape = objects[0].dim();
949    for (spectrum, object) in state.spectra.iter_mut().zip(objects) {
950        let mut field = object.as_slice().unwrap().to_vec();
951        state
952            .backend
953            .fft2(&mut field, shape, FftDirection::Forward, &mut state.column)?;
954        fftshift_copy(&field, spectrum.as_slice_mut(), shape);
955    }
956    Ok(())
957}
958
959#[cfg(test)]
960mod tests {
961    use super::*;
962    use crate::{
963        experiment::{
964            AcquisitionPlan, DirectionList, IlluminationFrame, Optics, SourceCalibration,
965            SourceContribution, SpectralAcquisitionPlan, SpectralChannel, SpectralContribution,
966            SpectralFrame, SpectralGeometry,
967        },
968        measurements::MeasurementStack,
969        model::{ReconstructionShape, SpectralImagePlaneModel},
970    };
971
972    #[test]
973    fn amplitude_and_shared_opd_gradients_match_finite_differences_of_detector_loss() {
974        let channels: Vec<_> = [500e-9, 550e-9]
975            .into_iter()
976            .enumerate()
977            .map(|(i, w)| SpectralChannel {
978                channel_id: format!("channel{i}"),
979                optics: Optics {
980                    wavelength_vacuum_m: w,
981                    objective_na: 0.12,
982                    magnification: 4.0,
983                    camera_pixel_size: 6.5e-6,
984                    illumination_refractive_index: 1.0,
985                    objective_medium_refractive_index: 1.0,
986                    defocus_distance: Some(2e-6),
987                    pupil_aberration: None,
988                },
989                calibration: SourceCalibration::new(Some(vec![0.7, 1.3, 0.9])),
990                acquisition: AcquisitionPlan::from_sparse(vec![
991                    IlluminationFrame::new(
992                        vec![SourceContribution {
993                            source: 0,
994                            intensity_weight: 1.0,
995                        }],
996                        1.3,
997                    ),
998                    IlluminationFrame::new(
999                        vec![
1000                            SourceContribution {
1001                                source: 1,
1002                                intensity_weight: 0.4,
1003                            },
1004                            SourceContribution {
1005                                source: 2,
1006                                intensity_weight: 0.6,
1007                            },
1008                        ],
1009                        0.8,
1010                    ),
1011                ])
1012                .unwrap(),
1013            })
1014            .collect();
1015        let model = SpectralImagePlaneModel::from_experiment(
1016            &channels,
1017            &SpectralGeometry::Shared(
1018                DirectionList::from_direction_cosines(vec![
1019                    [0.0, 0.0],
1020                    [0.047, 0.031],
1021                    [-0.063, 0.042],
1022                ])
1023                .unwrap()
1024                .into(),
1025            ),
1026            SpectralAcquisitionPlan::multiplexed(
1027                (0..2)
1028                    .map(|local_frame| SpectralFrame {
1029                        contributions: (0..2)
1030                            .map(|channel| SpectralContribution {
1031                                channel,
1032                                local_frame,
1033                                spectral_weight: 0.6 + 0.2 * channel as f64,
1034                            })
1035                            .collect(),
1036                        gain: 1.7,
1037                        background: 0.12,
1038                    })
1039                    .collect(),
1040            )
1041            .unwrap(),
1042            (6, 8),
1043            ReconstructionShape::Smooth,
1044            ObjectCoupling::Independent,
1045        )
1046        .unwrap();
1047        let shape = model.reconstruction_shape();
1048        let parameters = Parameters {
1049            opd: Array2::from_shape_fn(shape, |(r, c)| 1.2e-6 + 5e-9 * (r + c) as f64),
1050            amplitudes: (0..2)
1051                .map(|i| {
1052                    Array2::from_shape_fn(shape, |(r, c)| {
1053                        0.8 + 0.02 * i as f64 + 0.03 * ((r + c) as f64).sin()
1054                    })
1055                })
1056                .collect(),
1057        };
1058        let wavelengths = [500e-9, 550e-9];
1059        let mut frames = Vec::new();
1060        let temporary = SpectralReconstructionProblem::new(
1061            MeasurementStack::from_frames(&[vec![1.0; 48], vec![1.0; 48]], (6, 8)).unwrap(),
1062            model.clone(),
1063        )
1064        .unwrap();
1065        let state =
1066            SpectralReconstructionState::from_objects(&temporary, parameters.objects(&wavelengths))
1067                .unwrap();
1068        for f in 0..2 {
1069            frames.push(
1070                model
1071                    .forward_intensity(&state.object_spectra(), f)
1072                    .unwrap()
1073                    .mapv(|v| 0.86 * v + 0.02)
1074                    .into_raw_vec_and_offset()
1075                    .0,
1076            );
1077        }
1078        let mut measurements = MeasurementStack::from_frames(&frames, (6, 8))
1079            .unwrap()
1080            .with_masks(Array2::from_shape_fn((6, 8), |(r, c)| {
1081                u8::from((r + c) % 4 != 0)
1082            }))
1083            .unwrap();
1084        measurements.set_frame_weight(0, 0.4).unwrap();
1085        measurements.set_frame_weight(1, 1.7).unwrap();
1086        let problem = SpectralReconstructionProblem::new(measurements, model).unwrap();
1087        let mut state =
1088            SpectralReconstructionState::from_objects(&problem, parameters.objects(&wavelengths))
1089                .unwrap();
1090        let solver = MultiWavelengthGradientDescent::default();
1091        let (_, gradient) = solver
1092            .evaluate(&problem, &mut state, &parameters, &wavelengths, true)
1093            .unwrap();
1094        let gradient = gradient.unwrap();
1095        let h = 1e-5;
1096        for index in [(0, 0), (2, 3), (shape.0 - 1, shape.1 - 2)] {
1097            for channel in 0..2 {
1098                let mut plus = Parameters {
1099                    opd: parameters.opd.clone(),
1100                    amplitudes: parameters.amplitudes.clone(),
1101                };
1102                plus.amplitudes[channel][index] += h;
1103                set_fields(&mut state, &plus.objects(&wavelengths)).unwrap();
1104                let high = solver
1105                    .evaluate(&problem, &mut state, &plus, &wavelengths, false)
1106                    .unwrap()
1107                    .0;
1108                plus.amplitudes[channel][index] -= 2.0 * h;
1109                set_fields(&mut state, &plus.objects(&wavelengths)).unwrap();
1110                let low = solver
1111                    .evaluate(&problem, &mut state, &plus, &wavelengths, false)
1112                    .unwrap()
1113                    .0;
1114                let numerical = (high - low) / (2.0 * h);
1115                assert!(
1116                    (gradient.amplitude[channel][index] - numerical).abs()
1117                        < 1e-8 * (1.0 + numerical.abs()),
1118                    "amplitude {index:?}: analytic {}, numerical {numerical}",
1119                    gradient.amplitude[channel][index]
1120                );
1121            }
1122            let mut plus = Parameters {
1123                opd: parameters.opd.clone(),
1124                amplitudes: parameters.amplitudes.clone(),
1125            };
1126            plus.opd[index] += h * wavelengths[0] / TAU;
1127            set_fields(&mut state, &plus.objects(&wavelengths)).unwrap();
1128            let high = solver
1129                .evaluate(&problem, &mut state, &plus, &wavelengths, false)
1130                .unwrap()
1131                .0;
1132            plus.opd[index] -= 2.0 * h * wavelengths[0] / TAU;
1133            set_fields(&mut state, &plus.objects(&wavelengths)).unwrap();
1134            let low = solver
1135                .evaluate(&problem, &mut state, &plus, &wavelengths, false)
1136                .unwrap()
1137                .0;
1138            let numerical = (high - low) / (2.0 * h);
1139            assert!(
1140                (gradient.phase[index] - numerical).abs() < 1e-8 * (1.0 + numerical.abs()),
1141                "OPD {index:?}: analytic {}, numerical {numerical}",
1142                gradient.phase[index]
1143            );
1144        }
1145    }
1146}