1use 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#[derive(Clone, Debug)]
29pub struct MultiWavelengthSolverResult {
30 pub opd_m: Array2<f64>,
32 pub spectral: SpectralReconstructionResult,
37 pub initialization_opd: Option<OpticalPathDifferenceResult>,
39 pub initialization_trace: Option<ReconstructionTrace>,
41 pub checkpoint: SpectralReconstructionCheckpoint,
43}
44
45#[derive(Clone, Debug, Serialize, Deserialize)]
91#[serde(deny_unknown_fields)]
92pub struct MultiWavelengthGradientDescent {
93 pub iterations: usize,
95 pub initialization_iterations: usize,
97 pub amplitude_step: f64,
99 pub opd_step: f64,
101 pub max_backtracks: usize,
103 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 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 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 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 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 #[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 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 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 &litudes {
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, ¶meters, 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, ¶meters, &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, ¶meters, &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, ¶meters.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 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 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 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, ¶meters, &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}