pub mod information;
pub mod multi_params;
pub(crate) mod reference;
use crate::common::vec_f64::mean_and_stdev;
use parry3d_f64::na::Isometry;
pub use levenberg_marquardt::TerminationReason;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SolveQuality {
Converged,
Unconverged,
Failed,
}
impl SolveQuality {
pub fn from_termination(termination: &TerminationReason) -> Self {
match termination {
TerminationReason::Converged { .. }
| TerminationReason::ResidualsZero
| TerminationReason::Orthogonal => SolveQuality::Converged,
TerminationReason::LostPatience => SolveQuality::Unconverged,
TerminationReason::User(_)
| TerminationReason::Numerical(_)
| TerminationReason::NoImprovementPossible(_)
| TerminationReason::NoParameters
| TerminationReason::NoResiduals
| TerminationReason::WrongDimensions(_) => SolveQuality::Failed,
}
}
pub fn is_usable(&self) -> bool {
!matches!(self, SolveQuality::Failed)
}
pub(crate) fn worse_of(self, other: Self) -> Self {
match (self, other) {
(SolveQuality::Failed, _) | (_, SolveQuality::Failed) => SolveQuality::Failed,
(SolveQuality::Unconverged, _) | (_, SolveQuality::Unconverged) => {
SolveQuality::Unconverged
}
_ => SolveQuality::Converged,
}
}
}
#[derive(Debug, PartialEq, Eq)]
pub enum RefinementHalt {
NoNoiseEstimate,
Underdetermined {
weighted: usize,
params: usize,
},
SolveFailed(TerminationReason),
}
#[derive(Debug)]
pub struct AlignOutcome<R, const D: usize> {
alignment: Alignment<R, D>,
solves: Vec<TerminationReason>,
halt: Option<RefinementHalt>,
}
impl<R, const D: usize> AlignOutcome<R, D> {
pub(crate) fn new(
alignment: Alignment<R, D>,
solves: Vec<TerminationReason>,
halt: Option<RefinementHalt>,
) -> Self {
Self {
alignment,
solves,
halt,
}
}
pub fn alignment(&self) -> &Alignment<R, D> {
&self.alignment
}
pub fn into_alignment(self) -> Alignment<R, D> {
self.alignment
}
pub fn solves(&self) -> &[TerminationReason] {
&self.solves
}
pub fn refinement_rounds(&self) -> usize {
self.solves.len().saturating_sub(1)
}
pub fn quality(&self) -> SolveQuality {
self.solves
.iter()
.map(SolveQuality::from_termination)
.fold(SolveQuality::Converged, SolveQuality::worse_of)
}
pub fn converged(&self) -> bool {
self.quality() == SolveQuality::Converged
}
pub fn halt(&self) -> Option<&RefinementHalt> {
self.halt.as_ref()
}
}
#[derive(Debug)]
pub struct MultiOutcome<R, const D: usize> {
alignments: Vec<Alignment<R, D>>,
solves: Vec<TerminationReason>,
halt: Option<RefinementHalt>,
}
impl<R, const D: usize> MultiOutcome<R, D> {
pub(crate) fn new(
alignments: Vec<Alignment<R, D>>,
solves: Vec<TerminationReason>,
halt: Option<RefinementHalt>,
) -> Self {
Self {
alignments,
solves,
halt,
}
}
pub fn alignments(&self) -> &[Alignment<R, D>] {
&self.alignments
}
pub fn alignment(&self, body: usize) -> &Alignment<R, D> {
&self.alignments[body]
}
pub fn len(&self) -> usize {
self.alignments.len()
}
pub fn is_empty(&self) -> bool {
self.alignments.is_empty()
}
pub fn solves(&self) -> &[TerminationReason] {
&self.solves
}
pub fn refinement_rounds(&self) -> usize {
self.solves.len().saturating_sub(1)
}
pub fn quality(&self) -> SolveQuality {
self.solves
.iter()
.map(SolveQuality::from_termination)
.fold(SolveQuality::Converged, SolveQuality::worse_of)
}
pub fn converged(&self) -> bool {
self.quality() == SolveQuality::Converged
}
pub fn halt(&self) -> Option<&RefinementHalt> {
self.halt.as_ref()
}
}
#[derive(Debug, Clone)]
pub struct Alignment<R, const D: usize> {
full: Isometry<f64, R, D>,
alignment: Isometry<f64, R, D>,
local_origin: Isometry<f64, R, D>,
offset: Isometry<f64, R, D>,
residuals: Vec<f64>,
}
impl<R, const D: usize> Alignment<R, D> {
pub(crate) fn new(
full: Isometry<f64, R, D>,
alignment: Isometry<f64, R, D>,
local_origin: Isometry<f64, R, D>,
offset: Isometry<f64, R, D>,
residuals: Vec<f64>,
) -> Self {
Self {
full,
alignment,
local_origin,
offset,
residuals,
}
}
pub fn full_transform(&self) -> &Isometry<f64, R, D> {
&self.full
}
pub fn local_transform(&self) -> &Isometry<f64, R, D> {
&self.alignment
}
pub fn local_origin(&self) -> &Isometry<f64, R, D> {
&self.local_origin
}
pub fn offset(&self) -> &Isometry<f64, R, D> {
&self.offset
}
pub fn residuals(&self) -> &[f64] {
&self.residuals
}
pub fn residual_mean(&self) -> f64 {
self.residuals.iter().sum::<f64>() / self.residuals.len() as f64
}
pub fn residual_mean_std_dev(&self) -> (f64, f64) {
mean_and_stdev(&self.residuals).unwrap()
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DistMode {
ToPoint,
ToPlane,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn converged_terminations_are_classified() {
for t in [
TerminationReason::Converged {
ftol: true,
xtol: false,
},
TerminationReason::Converged {
ftol: false,
xtol: true,
},
TerminationReason::ResidualsZero,
TerminationReason::Orthogonal,
] {
assert_eq!(SolveQuality::from_termination(&t), SolveQuality::Converged);
assert!(SolveQuality::from_termination(&t).is_usable());
}
}
#[test]
fn exhausted_budget_is_usable_but_unconverged() {
let q = SolveQuality::from_termination(&TerminationReason::LostPatience);
assert_eq!(q, SolveQuality::Unconverged);
assert!(q.is_usable());
}
#[test]
fn broken_terminations_are_not_usable() {
for t in [
TerminationReason::User("residuals"),
TerminationReason::Numerical("jacobian"),
TerminationReason::NoImprovementPossible("ftol"),
TerminationReason::NoParameters,
TerminationReason::NoResiduals,
TerminationReason::WrongDimensions("jacobian"),
] {
assert_eq!(SolveQuality::from_termination(&t), SolveQuality::Failed);
assert!(!SolveQuality::from_termination(&t).is_usable());
}
}
#[test]
fn worse_of_orders_the_qualities() {
use SolveQuality::{Converged, Failed, Unconverged};
assert_eq!(Converged.worse_of(Converged), Converged);
assert_eq!(Converged.worse_of(Unconverged), Unconverged);
assert_eq!(Unconverged.worse_of(Converged), Unconverged);
assert_eq!(Unconverged.worse_of(Failed), Failed);
assert_eq!(Failed.worse_of(Converged), Failed);
}
}