1use std::{sync::Arc, time::Instant};
4
5use ndarray::{Array2, ArrayView2, ArrayViewMut2};
6use num_complex::Complex64;
7use rand::{SeedableRng, rngs::StdRng, seq::SliceRandom};
8use serde::{Deserialize, Serialize};
9
10use crate::{
11 Result,
12 algorithms::{AlgorithmIterationMetrics, SpectralReconstructionAlgorithm, StepOutput},
13 array_layout::{StandardArray2, checked_len_2d},
14 backend::{Backend, CpuBackend, FftDirection},
15 complex,
16 error::Error,
17 measurements::MeasurementRead,
18 model::{
19 ForwardModel, ForwardWorkspace, ObjectCoupling, Pupil, SpectralImagePlaneModel,
20 fftshift_copy, ifftshift_copy,
21 },
22};
23
24use super::{
25 Batch, IterationRecord, ReconstructionTrace, RuntimeInfo, SpectralCheckpointOptions,
26 SpectralReconstructionCheckpoint,
27 spectral_checkpoint::{StoredSolver, fingerprints},
28};
29
30#[derive(Clone, Debug)]
35pub struct SpectralReconstructionProblem<M> {
36 pub measurements: M,
38 pub model: SpectralImagePlaneModel,
40}
41
42impl<M: MeasurementRead> SpectralReconstructionProblem<M> {
43 pub fn new(measurements: M, model: SpectralImagePlaneModel) -> Result<Self> {
45 let problem = Self {
46 measurements,
47 model,
48 };
49 problem.validate()?;
50 Ok(problem)
51 }
52
53 pub fn validate(&self) -> Result<()> {
55 self.model.validate()?;
56 self.measurements.validate()?;
57 if self.measurements.frame_count() != self.model.frame_count()
58 || self.measurements.image_shape() != self.model.image_shape()
59 {
60 return Err(Error::InvalidMeasurements(
61 "spectral detector frame count and shape must match the compiled model".into(),
62 ));
63 }
64 let mut coverage: Vec<Vec<bool>> = self
65 .model
66 .channels()
67 .iter()
68 .map(|channel| vec![false; channel.model.frame_count()])
69 .collect();
70 for (frame, row) in self.model.acquisition().frames().iter().enumerate() {
71 if self.measurements.frame_weight(frame)? == 0.0 {
72 continue;
73 }
74 if self
75 .measurements
76 .frame_mask(frame)?
77 .is_some_and(|mask| mask.iter().all(|&value| value == 0))
78 {
79 return Err(Error::InvalidMeasurements(format!(
80 "positive-weight frame {frame} has no unmasked pixels"
81 )));
82 }
83 for contribution in &row.contributions {
84 coverage[contribution.channel][contribution.local_frame] = true;
85 }
86 }
87 if coverage.iter().flatten().any(|&covered| !covered) {
88 return Err(Error::InvalidMeasurements("every spectral channel and local frame must participate in a positive-weight detector frame".into()));
89 }
90 Ok(())
91 }
92}
93
94pub(crate) struct SpectralMode {
95 pub(crate) channel: usize,
96 pub(crate) source: usize,
97 pub(crate) weight: f64,
98 pub(crate) field: Vec<Complex64>,
99 pub(crate) exit: Vec<Complex64>,
100}
101
102pub struct SpectralReconstructionState {
107 pub(crate) spectra: Vec<StandardArray2<Complex64>>,
108 pub(crate) backend: Arc<dyn Backend>,
109 pub(crate) workspace: ForwardWorkspace,
110 pub(crate) modes: Vec<SpectralMode>,
111 pub(crate) predicted: Vec<f64>,
112 pub(crate) projection: Vec<Complex64>,
113 pub(crate) field: Vec<Complex64>,
114 pub(crate) centered: Vec<Complex64>,
115 pub(crate) update: Vec<Complex64>,
116 pub(crate) column: Vec<Complex64>,
117 pub(crate) effective_gain: f64,
118}
119
120impl SpectralReconstructionState {
121 pub fn initialize<M: MeasurementRead>(
128 problem: &SpectralReconstructionProblem<M>,
129 ) -> Result<Self> {
130 problem.validate()?;
131 let low_shape = problem.model.image_shape();
132 let high_shape = problem.model.reconstruction_shape();
133 let low_len = checked_len_2d(low_shape)?;
134 let mut objects = Vec::new();
135 for object_index in 0..problem.model.object_count() {
136 let mut amplitude = vec![0.0; low_len];
137 let mut weights = vec![0.0; low_len];
138 let mut total_amplitude = 0.0;
139 let mut total_weight = 0.0;
140 for (frame, row) in problem.model.acquisition().frames().iter().enumerate() {
141 if !row
142 .contributions
143 .iter()
144 .any(|c| problem.model.object_index(c.channel).ok() == Some(object_index))
145 {
146 continue;
147 }
148 let frame_weight = problem.measurements.frame_weight(frame)?;
149 if frame_weight == 0.0 {
150 continue;
151 }
152 let gain = row
153 .contributions
154 .iter()
155 .map(|c| {
156 Ok(c.spectral_weight
157 * problem.model.channels()[c.channel]
158 .model
159 .frame_gain(c.local_frame)?)
160 })
161 .collect::<Result<Vec<_>>>()?
162 .iter()
163 .sum::<f64>()
164 * row.gain;
165 if !gain.is_finite() || gain <= 0.0 {
166 return Err(Error::Numerical(
167 "spectral initialization gain must be finite and positive".into(),
168 ));
169 }
170 let measured = problem.measurements.frame(frame)?;
171 let mask = problem.measurements.frame_mask(frame)?;
172 for pixel in 0..low_len {
173 if mask.is_some_and(|values| values[pixel] == 0) {
174 continue;
175 }
176 let value = ((measured[pixel] - row.background) / gain).max(0.0).sqrt();
177 amplitude[pixel] += frame_weight * value;
178 weights[pixel] += frame_weight;
179 total_amplitude += frame_weight * value;
180 total_weight += frame_weight;
181 }
182 }
183 let fallback = total_amplitude / total_weight;
184 for (value, &weight) in amplitude.iter_mut().zip(&weights) {
185 *value = if weight > 0.0 {
186 *value / weight
187 } else {
188 fallback
189 };
190 }
191 let object = Array2::from_shape_fn(high_shape, |(row, column)| {
192 Complex64::new(
193 amplitude[(row * low_shape.0 / high_shape.0) * low_shape.1
194 + column * low_shape.1 / high_shape.1],
195 0.0,
196 )
197 });
198 objects.push(object);
199 }
200 Self::from_objects(problem, objects)
201 }
202
203 pub fn from_objects<M: MeasurementRead>(
208 problem: &SpectralReconstructionProblem<M>,
209 objects: Vec<Array2<Complex64>>,
210 ) -> Result<Self> {
211 problem.validate()?;
212 let views: Vec<_> = objects.iter().map(|object| object.view()).collect();
213 problem.model.validate_spectra(&views)?;
214 let low_shape = problem.model.image_shape();
215 let high_shape = problem.model.reconstruction_shape();
216 let backend: Arc<dyn Backend> = Arc::new(CpuBackend::new(low_shape, high_shape)?);
217 let mut column = vec![Complex64::default(); low_shape.0.max(high_shape.0)];
218 let mut spectra = Vec::new();
219 for object in objects {
220 let mut object = StandardArray2::try_from(object)?;
221 backend.fft2(
222 object.as_slice_mut(),
223 high_shape,
224 FftDirection::Forward,
225 &mut column,
226 )?;
227 let mut centered = vec![Complex64::default(); object.len()];
228 fftshift_copy(object.as_slice(), &mut centered, high_shape);
229 spectra.push(StandardArray2::from_shape_vec(high_shape, centered)?);
230 }
231 let workspace =
232 ForwardModel::with_backend(&problem.model.channels()[0].model, backend.clone())?
233 .workspace()?;
234 let len = checked_len_2d(low_shape)?;
235 Ok(Self {
236 spectra,
237 backend,
238 workspace,
239 modes: Vec::new(),
240 predicted: vec![0.0; len],
241 projection: vec![Complex64::default(); len],
242 field: vec![Complex64::default(); len],
243 centered: vec![Complex64::default(); len],
244 update: vec![Complex64::default(); len],
245 column,
246 effective_gain: 1.0,
247 })
248 }
249
250 pub fn object_spectra(&self) -> Vec<ArrayView2<'_, Complex64>> {
252 self.spectra
253 .iter()
254 .map(|array| array.ndarray_view())
255 .collect()
256 }
257
258 pub fn object_spectrum_mut(&mut self, index: usize) -> Result<ArrayViewMut2<'_, Complex64>> {
261 self.spectra
262 .get_mut(index)
263 .map(|spectrum| spectrum.ndarray_view_mut())
264 .ok_or(Error::InvalidParameter {
265 name: "object_index",
266 reason: "stored object index is out of range".into(),
267 })
268 }
269
270 pub(crate) fn evaluate_frame(
272 &mut self,
273 model: &SpectralImagePlaneModel,
274 frame: usize,
275 ) -> Result<()> {
276 let row = &model.acquisition().frames()[frame];
277 self.modes.clear();
278 self.predicted.fill(0.0);
279 self.effective_gain = row.gain;
280 let separate = row.contributions.len() == 1;
281 if separate {
282 let contribution = row.contributions[0];
283 self.effective_gain *= contribution.spectral_weight
284 * model.channels()[contribution.channel]
285 .model
286 .frame_gain(contribution.local_frame)?;
287 }
288 for contribution in &row.contributions {
289 let kernel = &model.channels()[contribution.channel].model;
290 let object = self.spectra[model.object_index(contribution.channel)?].view();
291 let single = [(contribution.local_frame, 1.0)];
292 let sources = kernel
293 .multiplexing_matrix()
294 .map_or(single.as_slice(), |matrix| {
295 matrix[contribution.local_frame].as_slice()
296 });
297 let forward = ForwardModel::with_backend(kernel, self.backend.clone())?;
298 for &(source, source_weight) in sources {
299 let weight = if separate {
300 source_weight
301 } else {
302 contribution.spectral_weight
303 * kernel.frame_gain(contribution.local_frame)?
304 * source_weight
305 };
306 forward.forward_source_field_standard_into(
307 object,
308 kernel.pupil(),
309 source,
310 &mut self.workspace,
311 )?;
312 let field = self.workspace.field().to_vec();
313 for (prediction, value) in self.predicted.iter_mut().zip(&field) {
314 *prediction += weight * value.norm_sqr();
315 }
316 let mut exit = vec![Complex64::default(); field.len()];
317 kernel.extract_patch_standard(object, source, &mut exit)?;
318 for (value, pupil) in exit.iter_mut().zip(kernel.pupil().values()) {
319 *value *= pupil;
320 }
321 self.modes.push(SpectralMode {
322 channel: contribution.channel,
323 source,
324 weight,
325 field,
326 exit,
327 });
328 }
329 }
330 Ok(())
331 }
332}
333
334#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
336#[serde(rename_all = "snake_case")]
337pub enum SpectralFrameSchedule {
338 #[default]
340 Sequential,
341 RandomShuffle {
343 seed: u64,
345 },
346 Explicit(Vec<usize>),
348}
349
350impl SpectralFrameSchedule {
351 pub fn order(&self, frame_count: usize, iteration: usize) -> Result<Vec<usize>> {
353 let mut order: Vec<_> = (0..frame_count).collect();
354 match self {
355 Self::Sequential => {}
356 Self::RandomShuffle { seed } => order.shuffle(&mut StdRng::seed_from_u64(
357 seed.wrapping_add((iteration as u64).wrapping_mul(0x9e3779b97f4a7c15)),
358 )),
359 Self::Explicit(values) => {
360 let mut sorted = values.clone();
361 sorted.sort_unstable();
362 if sorted != order {
363 return Err(Error::InvalidParameter {
364 name: "spectral_schedule",
365 reason: "explicit order must be a permutation of all detector frames"
366 .into(),
367 });
368 }
369 order.clone_from(values);
370 }
371 }
372 Ok(order)
373 }
374}
375
376#[derive(Clone, Debug)]
378pub struct SpectralChannelResult {
379 pub channel_id: String,
381 pub wavelength_vacuum_m: f64,
383 pub object: Array2<Complex64>,
385 pub amplitude: Array2<f64>,
387 pub phase: Array2<f64>,
389 pub object_spectrum: Array2<Complex64>,
391 pub pupil: Pupil,
393}
394
395#[derive(Clone, Debug)]
403pub struct SpectralReconstructionResult {
404 pub channels: Vec<SpectralChannelResult>,
406 pub object_coupling: ObjectCoupling,
408 pub trace: ReconstructionTrace,
412 pub runtime: RuntimeInfo,
414 pub checkpoint: Option<SpectralReconstructionCheckpoint>,
417}
418
419pub struct SpectralRunner<A> {
425 algorithm: A,
426 schedule: SpectralFrameSchedule,
427 initial_objects: Option<Vec<Array2<Complex64>>>,
428 checkpoint: Option<SpectralReconstructionCheckpoint>,
429 checkpoint_options: SpectralCheckpointOptions,
430 explicit_schedule: bool,
431}
432
433impl<A: SpectralReconstructionAlgorithm> SpectralRunner<A> {
434 pub fn run_opd<M: MeasurementRead>(
441 self,
442 problem: &SpectralReconstructionProblem<M>,
443 unwrapper: &super::SyntheticWavelengthUnwrapper,
444 reference: &super::PhaseReference,
445 mask: Option<ArrayView2<'_, u8>>,
446 ) -> Result<super::MultiWavelengthReconstructionResult> {
447 if problem.model.object_coupling() != ObjectCoupling::Independent {
448 return Err(Error::InvalidParameter {
449 name: "object_coupling",
450 reason: "OPD phase mixing requires independent wavelength fields".into(),
451 });
452 }
453 unwrapper.validate()?;
454 let spectral = self.run(problem)?;
455 let opd = spectral.unwrap_opd(unwrapper, reference, mask)?;
456 Ok(super::MultiWavelengthReconstructionResult { spectral, opd })
457 }
458
459 pub fn new(algorithm: A) -> Self {
461 Self {
462 algorithm,
463 schedule: SpectralFrameSchedule::default(),
464 initial_objects: None,
465 checkpoint: None,
466 checkpoint_options: SpectralCheckpointOptions::default(),
467 explicit_schedule: false,
468 }
469 }
470
471 pub fn with_schedule(mut self, schedule: SpectralFrameSchedule) -> Self {
473 self.schedule = schedule;
474 self.explicit_schedule = true;
475 self
476 }
477
478 pub fn with_initial_objects(mut self, objects: Vec<Array2<Complex64>>) -> Self {
480 self.initial_objects = Some(objects);
481 self
482 }
483
484 pub fn with_checkpoint(mut self, checkpoint: SpectralReconstructionCheckpoint) -> Self {
488 self.checkpoint = Some(checkpoint);
489 self
490 }
491
492 pub fn with_checkpoint_options(mut self, options: SpectralCheckpointOptions) -> Self {
494 self.checkpoint_options = options;
495 self
496 }
497
498 pub fn run<M: MeasurementRead>(
500 mut self,
501 problem: &SpectralReconstructionProblem<M>,
502 ) -> Result<SpectralReconstructionResult> {
503 self.algorithm.validate()?;
504 problem.validate()?;
505 self.algorithm.validate_problem(problem)?;
506 if self.algorithm.iterations() == 0 || self.algorithm.batch_size() == 0 {
507 return Err(Error::InvalidParameter {
508 name: "iterations/batch_size",
509 reason: "must be positive".into(),
510 });
511 }
512 self.checkpoint_options.validate()?;
513 let configuration = self.algorithm.checkpoint_configuration();
514 let started = Instant::now();
515 let algorithm_name = std::any::type_name::<A>().to_string();
516 let (mut state, mut trace, completed, elapsed_offset, signature) = match self.checkpoint {
517 Some(checkpoint) => {
518 if self.initial_objects.is_some() {
519 return Err(Error::InvalidParameter {
520 name: "initial_objects",
521 reason: "cannot combine initial objects with a checkpoint".into(),
522 });
523 }
524 checkpoint.validate_for_problem(problem)?;
525 let signature = checkpoint.fingerprints();
526 let StoredSolver::Spectral {
527 algorithm,
528 configuration: stored_configuration,
529 spectra,
530 schedule,
531 } = checkpoint.state
532 else {
533 return Err(Error::InvalidParameter {
534 name: "resume_from",
535 reason: "joint OPD state cannot resume spectral AP".into(),
536 });
537 };
538 if algorithm != algorithm_name
539 || configuration.as_ref() != Some(&stored_configuration)
540 || (self.explicit_schedule && self.schedule != schedule)
541 {
542 return Err(Error::InvalidParameter {
543 name: "resume_from",
544 reason: "solver stepping options or schedule changed".into(),
545 });
546 }
547 if self.algorithm.iterations() < checkpoint.completed_iterations {
548 return Err(Error::InvalidParameter {
549 name: "iterations",
550 reason: "total target cannot precede checkpoint iterations".into(),
551 });
552 }
553 self.schedule = schedule;
554 let objects = (0..problem.model.object_count())
555 .map(|_| Array2::zeros(problem.model.reconstruction_shape()))
556 .collect();
557 let mut state = SpectralReconstructionState::from_objects(problem, objects)?;
558 for (target, stored) in state.spectra.iter_mut().zip(spectra) {
559 *target = StandardArray2::try_from(stored.into_array()?)?;
560 }
561 (
562 state,
563 checkpoint.trace,
564 checkpoint.completed_iterations,
565 checkpoint.elapsed_seconds,
566 Some(signature),
567 )
568 }
569 None => {
570 let signature = configuration
571 .as_ref()
572 .map(|_| fingerprints(problem))
573 .transpose()?;
574 let state = match self.initial_objects {
575 Some(objects) => SpectralReconstructionState::from_objects(problem, objects)?,
576 None => self.algorithm.initialize(problem)?,
577 };
578 (state, ReconstructionTrace::default(), 0, 0.0, signature)
579 }
580 };
581 if self.checkpoint_options.directory.is_some() && configuration.is_none() {
582 return Err(Error::InvalidParameter {
583 name: "checkpoint_options",
584 reason: "this custom spectral algorithm has not opted into stateless checkpointing"
585 .into(),
586 });
587 }
588 self.schedule
589 .order(problem.model.frame_count(), completed)?;
590 for iteration in completed..self.algorithm.iterations() {
591 let order = self
592 .schedule
593 .order(problem.model.frame_count(), iteration)?;
594 let mut output = StepOutput::<A::IterationMetrics>::default();
595 for (batch_index, indices) in order.chunks(self.algorithm.batch_size()).enumerate() {
596 output.merge(self.algorithm.step(
597 problem,
598 &mut state,
599 &Batch {
600 indices: indices.to_vec(),
601 batch_index,
602 },
603 iteration,
604 )?);
605 }
606 let objective = output.summary.mean_objective().ok_or_else(|| {
607 Error::Numerical("spectral iteration has no positive frame weight".into())
608 })?;
609 if !objective.is_finite() {
610 return Err(Error::Numerical(
611 "spectral iteration objective is non-finite".into(),
612 ));
613 }
614 trace.iterations.push(IterationRecord {
615 iteration: iteration + 1,
616 objective,
617 elapsed_seconds: elapsed_offset + started.elapsed().as_secs_f64(),
618 });
619 output
620 .metrics
621 .append_records(iteration + 1, &mut trace.algorithm_metrics);
622 if self.checkpoint_options.directory.is_some()
623 && (iteration + 1).is_multiple_of(self.checkpoint_options.every)
624 {
625 let checkpoint = SpectralReconstructionCheckpoint::capture(
626 problem.model.clone(),
627 signature.as_ref().unwrap(),
628 iteration + 1,
629 elapsed_offset + started.elapsed().as_secs_f64(),
630 trace.clone(),
631 StoredSolver::Spectral {
632 algorithm: algorithm_name.clone(),
633 configuration: configuration.clone().unwrap(),
634 spectra: state
635 .spectra
636 .iter()
637 .map(|a| crate::array_serde::Array2Data::from_view(a.ndarray_view()))
638 .collect(),
639 schedule: self.schedule.clone(),
640 },
641 );
642 self.checkpoint_options.write(&checkpoint, false)?;
643 }
644 }
645 let high_shape = problem.model.reconstruction_shape();
646 let mut objects = Vec::new();
647 for spectrum in &state.spectra {
648 let mut object = vec![Complex64::default(); spectrum.len()];
649 ifftshift_copy(spectrum.as_slice(), &mut object, high_shape);
650 state.backend.fft2(
651 &mut object,
652 high_shape,
653 FftDirection::Inverse,
654 &mut state.column,
655 )?;
656 objects.push(Array2::from_shape_vec(high_shape, object)?);
657 }
658 let channels = problem
659 .model
660 .channels()
661 .iter()
662 .enumerate()
663 .map(|(index, channel)| {
664 let object_index = problem.model.object_index(index)?;
665 let object = objects[object_index].clone();
666 Ok(SpectralChannelResult {
667 channel_id: channel.channel_id.clone(),
668 wavelength_vacuum_m: channel.model.sampling().wavelength.unwrap(),
669 amplitude: complex::amplitude(object.view()),
670 phase: complex::phase(object.view()),
671 object,
672 object_spectrum: state.spectra[object_index].clone().into_inner(),
673 pupil: channel.model.pupil().clone(),
674 })
675 })
676 .collect::<Result<Vec<_>>>()?;
677 let elapsed_seconds = elapsed_offset + started.elapsed().as_secs_f64();
678 let checkpoint = configuration.map(|configuration| {
679 SpectralReconstructionCheckpoint::capture(
680 problem.model.clone(),
681 signature.as_ref().unwrap(),
682 self.algorithm.iterations(),
683 elapsed_seconds,
684 trace.clone(),
685 StoredSolver::Spectral {
686 algorithm: algorithm_name,
687 configuration,
688 spectra: state
689 .spectra
690 .iter()
691 .map(|a| crate::array_serde::Array2Data::from_view(a.ndarray_view()))
692 .collect(),
693 schedule: self.schedule,
694 },
695 )
696 });
697 if let Some(checkpoint) = &checkpoint {
698 self.checkpoint_options.write(checkpoint, true)?;
699 }
700 Ok(SpectralReconstructionResult {
701 channels,
702 checkpoint,
703 object_coupling: problem.model.object_coupling(),
704 trace,
705 runtime: RuntimeInfo {
706 elapsed_seconds,
707 completed_iterations: self.algorithm.iterations(),
708 stopped_early: false,
709 algorithm: std::any::type_name::<A>()
710 .rsplit("::")
711 .next()
712 .unwrap_or("spectral algorithm")
713 .into(),
714 },
715 })
716 }
717}