Skip to main content

neco_eigensolve_faer/
lib.rs

1#![forbid(unsafe_code)]
2#![doc = include_str!("../README.md")]
3
4mod complex_lu;
5mod condition;
6mod convert;
7mod nonsymmetric;
8mod refine;
9
10pub use complex_lu::ComplexLu;
11pub use condition::condition_number_2;
12pub use nonsymmetric::{solve_nonsymmetric_f64, NonsymmetricEigenDecomposition};
13
14use core::fmt;
15use faer::dyn_stack::{MemBuffer, MemStack};
16use faer::linalg::evd::{
17    self_adjoint_evd, self_adjoint_evd_scratch, ComputeEigenvectors, SelfAdjointEvdParams,
18};
19use faer::{Mat, Spec, Unbind};
20use neco_eigensolve::{EigensolveConfig, EigensolveError, EigensolveRequest, EigensolveResult};
21use neco_generalized_eigen::{
22    ConvergenceStatus, EigenShift, Eigenpair, Eigenspace, GeneralizedEigenError,
23    GeneralizedEigenProblem,
24};
25use neco_linear_dense::DenseMatrix;
26use neco_linear_types::{LinearError, Vector};
27
28#[derive(Clone, Debug, PartialEq)]
29pub enum EigensolveFaerError {
30    InvalidStiffnessMatrix {
31        reason: &'static str,
32    },
33    InvalidMassMatrix {
34        reason: &'static str,
35    },
36    NonPositiveMassMatrix,
37    InvalidMatrix {
38        operation: &'static str,
39        reason: &'static str,
40    },
41    SingularPivot {
42        operation: &'static str,
43        index: usize,
44        magnitude: f64,
45    },
46    RightHandSide {
47        operation: &'static str,
48        expected: usize,
49        actual: usize,
50    },
51    NonFiniteResult {
52        operation: &'static str,
53    },
54    EigenvectorRefinement {
55        operation: &'static str,
56        index: usize,
57        residual: f64,
58        kind: RefinementFailureKind,
59    },
60    ExternalSolver {
61        operation: &'static str,
62        reason: &'static str,
63    },
64    Core(EigensolveError),
65    Generalized(GeneralizedEigenError),
66    Linear(LinearError),
67}
68
69#[derive(Clone, Copy, Debug, PartialEq, Eq)]
70pub enum RefinementFailureKind {
71    ResidualExceeded,
72    RealEigenvalue,
73    LinearlyDependent,
74    NearRealAxis,
75    SubproblemFailed,
76}
77
78impl From<EigensolveError> for EigensolveFaerError {
79    fn from(error: EigensolveError) -> Self {
80        Self::Core(error)
81    }
82}
83
84impl From<GeneralizedEigenError> for EigensolveFaerError {
85    fn from(error: GeneralizedEigenError) -> Self {
86        Self::Generalized(error)
87    }
88}
89
90impl From<LinearError> for EigensolveFaerError {
91    fn from(error: LinearError) -> Self {
92        Self::Linear(error)
93    }
94}
95
96impl fmt::Display for EigensolveFaerError {
97    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
98        match self {
99            Self::InvalidStiffnessMatrix { reason } => {
100                write!(formatter, "invalid stiffness matrix: {reason}")
101            }
102            Self::InvalidMassMatrix { reason } => {
103                write!(formatter, "invalid mass matrix: {reason}")
104            }
105            Self::NonPositiveMassMatrix => {
106                write!(formatter, "mass matrix is not positive definite")
107            }
108            Self::InvalidMatrix { operation, reason } => {
109                write!(formatter, "invalid matrix in {operation}: {reason}")
110            }
111            Self::SingularPivot {
112                operation,
113                index,
114                magnitude,
115            } => {
116                write!(
117                    formatter,
118                    "pivot {index} in {operation} is zero or not finite (magnitude {magnitude})"
119                )
120            }
121            Self::RightHandSide {
122                operation,
123                expected,
124                actual,
125            } => {
126                write!(
127                    formatter,
128                    "right-hand side in {operation} has {actual} rows, expected {expected}"
129                )
130            }
131            Self::EigenvectorRefinement {
132                operation,
133                index,
134                residual,
135                kind,
136            } => {
137                write!(
138                    formatter,
139                    "eigenpair {index} in {operation} has residual {residual} ({kind:?})"
140                )
141            }
142            Self::NonFiniteResult { operation } => {
143                write!(formatter, "{operation} produced a non-finite result")
144            }
145            Self::ExternalSolver { operation, reason } => {
146                write!(formatter, "external solver failed in {operation}: {reason}")
147            }
148            Self::Core(error) => error.fmt(formatter),
149            Self::Generalized(error) => error.fmt(formatter),
150            Self::Linear(error) => error.fmt(formatter),
151        }
152    }
153}
154
155impl std::error::Error for EigensolveFaerError {}
156
157pub fn solve_symmetric_f64(
158    problem: &GeneralizedEigenProblem,
159    config: EigensolveConfig,
160) -> Result<EigensolveResult, EigensolveFaerError> {
161    solve_parts(problem, config, (), "solve_symmetric_f64")
162}
163
164pub fn solve_request_symmetric_f64<R>(
165    request: EigensolveRequest<R>,
166) -> Result<EigensolveResult<R>, EigensolveFaerError> {
167    let (problem, config, projection_reference) = request.into_parts();
168    solve_parts(
169        &problem,
170        config,
171        projection_reference,
172        "solve_request_symmetric_f64",
173    )
174}
175
176/// Approximate solution to the mass equation, reusing the same Cholesky path
177/// as the solver. Serves only as a correction input for an independently
178/// certified bound, never as a bound itself.
179pub fn approximate_mass_solve(
180    mass: &DenseMatrix<f64>,
181    rhs: &Vector<f64>,
182) -> Result<Vector<f64>, EigensolveFaerError> {
183    let dimension = mass.rows();
184    if rhs.len() != dimension {
185        return Err(EigensolveFaerError::Linear(
186            LinearError::StorageLengthMismatch {
187                expected: dimension,
188                actual: rhs.len(),
189            },
190        ));
191    }
192    validate_symmetric_finite(mass, "mass")?;
193    let lower = cholesky_lower(mass)?;
194    let inverse_lower = inverse_lower_triangular(&lower)?;
195
196    let mut intermediate = Vec::new();
197    intermediate
198        .try_reserve_exact(dimension)
199        .map_err(|_| allocation_error(dimension))?;
200    for row in 0..dimension {
201        let mut value = 0.0;
202        for column in 0..dimension {
203            value += inverse_lower[(row, column)] * rhs.values()[column];
204        }
205        if !value.is_finite() {
206            return Err(EigensolveFaerError::ExternalSolver {
207                operation: "approximate_mass_solve",
208                reason: "mass equation intermediate solution is not finite",
209            });
210        }
211        intermediate.push(value);
212    }
213
214    let mut solution = Vec::new();
215    solution
216        .try_reserve_exact(dimension)
217        .map_err(|_| allocation_error(dimension))?;
218    for row in 0..dimension {
219        let mut value = 0.0;
220        for column in 0..dimension {
221            value += inverse_lower[(column, row)] * intermediate[column];
222        }
223        if !value.is_finite() {
224            return Err(EigensolveFaerError::ExternalSolver {
225                operation: "approximate_mass_solve",
226                reason: "mass equation solution is not finite",
227            });
228        }
229        solution.push(value);
230    }
231    Ok(Vector::try_from_vec(solution)?)
232}
233
234/// Transforms the generalized problem into a symmetric standard problem using
235/// its positive-definite mass matrix.
236fn solve_parts<R>(
237    problem: &GeneralizedEigenProblem,
238    config: EigensolveConfig,
239    projection_reference: R,
240    operation: &'static str,
241) -> Result<EigensolveResult<R>, EigensolveFaerError> {
242    validate_symmetric_finite(problem.stiffness(), "stiffness")?;
243    validate_symmetric_finite(problem.mass(), "mass")?;
244
245    let stiffness = to_faer_matrix(problem.stiffness())?;
246    let (reduced_stiffness, inverse_lower) = if is_exact_identity(problem.mass())? {
247        (stiffness, None)
248    } else {
249        let lower_mass = cholesky_lower(problem.mass())?;
250        let inverse_lower = inverse_lower_triangular(&lower_mass)?;
251        let reduced_stiffness = congruence_transform(&inverse_lower, &stiffness, operation)?;
252        (reduced_stiffness, Some(inverse_lower))
253    };
254    let (eigenvalues, eigenvector_values) = decompose_qr(reduced_stiffness.as_ref(), operation)?;
255    let dimension = problem.dimension();
256    let eigenvectors =
257        faer::MatRef::from_column_major_slice(&eigenvector_values, dimension, dimension);
258    let mut candidates = Vec::new();
259    candidates
260        .try_reserve_exact(dimension)
261        .map_err(|_| allocation_error(dimension))?;
262    for (column, &eigenvalue) in eigenvalues.iter().enumerate() {
263        if !eigenvalue.is_finite() {
264            return Err(EigensolveFaerError::ExternalSolver {
265                operation,
266                reason: "generalized eigenvalue is not finite",
267            });
268        }
269        candidates.push((eigenvalue, column));
270    }
271    stable_sort_candidates(&mut candidates);
272
273    let selected_modes = config.requested_modes().min(dimension);
274    let eigenspaces = build_eigenspaces(
275        problem,
276        eigenvectors,
277        inverse_lower.as_ref(),
278        &candidates,
279        selected_modes,
280        operation,
281    )?;
282    let returned_modes = eigenspaces
283        .iter()
284        .map(|eigenspace| eigenspace.basis().len())
285        .sum();
286    let converged_modes = eigenspaces
287        .iter()
288        .flat_map(|eigenspace| eigenspace.basis())
289        .filter(|pair| {
290            pair.residual()
291                .meets_tolerance(config.absolute_tolerance(), config.relative_tolerance())
292        })
293        .count();
294    let convergence = if converged_modes == returned_modes {
295        ConvergenceStatus::converged(
296            1,
297            config.requested_modes(),
298            returned_modes,
299            converged_modes,
300            config.absolute_tolerance(),
301            config.relative_tolerance(),
302        )?
303    } else {
304        ConvergenceStatus::iteration_limit(
305            1,
306            config.requested_modes(),
307            returned_modes,
308            converged_modes,
309            config.absolute_tolerance(),
310            config.relative_tolerance(),
311        )?
312    };
313    let result = EigensolveResult::from_projected_parts(
314        eigenspaces,
315        convergence,
316        EigenShift::new(neco_complex::Complex::<f64>::zero())?,
317        projection_reference,
318    )?;
319    Ok(result)
320}
321
322fn decompose_qr(
323    matrix: faer::MatRef<'_, f64>,
324    operation: &'static str,
325) -> Result<(Vec<f64>, Vec<f64>), EigensolveFaerError> {
326    let dimension = matrix.nrows();
327    if matrix.ncols() != dimension {
328        return Err(LinearError::DimensionMismatch {
329            expected_rows: dimension,
330            expected_columns: dimension,
331            actual_rows: matrix.nrows(),
332            actual_columns: matrix.ncols(),
333        }
334        .into());
335    }
336    if dimension == 0 {
337        return Ok((Vec::new(), Vec::new()));
338    }
339    let recursion_threshold = dimension
340        .checked_add(1)
341        .ok_or(LinearError::CapacityOverflow {
342            requested: usize::MAX,
343        })?;
344    let vector_elements =
345        dimension
346            .checked_mul(dimension)
347            .ok_or(LinearError::CapacityOverflow {
348                requested: usize::MAX,
349            })?;
350    check_f64_capacity(dimension)?;
351    check_f64_capacity(vector_elements)?;
352    let mut eigenvalues = zeroed_factor_buffer(dimension)?;
353    let mut eigenvectors = zeroed_factor_buffer(vector_elements)?;
354    let mut params = Spec::<SelfAdjointEvdParams, f64>::default();
355    params.config.recursion_threshold = recursion_threshold;
356    let parallelism = faer::get_global_parallelism();
357    let scratch =
358        self_adjoint_evd_scratch::<f64>(dimension, ComputeEigenvectors::Yes, parallelism, params);
359    let mut workspace = try_workspace(scratch)?;
360    self_adjoint_evd(
361        matrix,
362        faer::diag::DiagMut::from_slice_mut(&mut eigenvalues),
363        Some(faer::MatMut::from_column_major_slice_mut(
364            &mut eigenvectors,
365            dimension,
366            dimension,
367        )),
368        parallelism,
369        MemStack::new(&mut workspace),
370        params,
371    )
372    .map_err(|_| EigensolveFaerError::ExternalSolver {
373        operation,
374        reason: "symmetric eigendecomposition did not converge",
375    })?;
376    Ok((eigenvalues, eigenvectors))
377}
378
379fn check_f64_capacity(elements: usize) -> Result<(), EigensolveFaerError> {
380    let bytes =
381        elements
382            .checked_mul(core::mem::size_of::<f64>())
383            .ok_or(LinearError::CapacityOverflow {
384                requested: elements,
385            })?;
386    if bytes > isize::MAX as usize {
387        return Err(LinearError::CapacityOverflow {
388            requested: elements,
389        }
390        .into());
391    }
392    Ok(())
393}
394
395fn zeroed_factor_buffer(elements: usize) -> Result<Vec<f64>, EigensolveFaerError> {
396    let mut values = Vec::new();
397    values
398        .try_reserve_exact(elements)
399        .map_err(|_| allocation_error(elements))?;
400    values.resize(elements, 0.0);
401    Ok(values)
402}
403
404fn validate_symmetric_finite(
405    matrix: &DenseMatrix<f64>,
406    matrix_name: &'static str,
407) -> Result<(), EigensolveFaerError> {
408    let shape = matrix.shape();
409    for row in 0..matrix.rows() {
410        for column in 0..matrix.columns() {
411            let value = *matrix.value(shape.row_index(row)?, shape.column_index(column)?)?;
412            if !value.is_finite() {
413                return Err(match matrix_name {
414                    "stiffness" => EigensolveFaerError::InvalidStiffnessMatrix {
415                        reason: "values must be finite",
416                    },
417                    _ => EigensolveFaerError::InvalidMassMatrix {
418                        reason: "values must be finite",
419                    },
420                });
421            }
422            let transposed = *matrix.value(shape.row_index(column)?, shape.column_index(row)?)?;
423            if value != transposed {
424                return Err(match matrix_name {
425                    "stiffness" => EigensolveFaerError::InvalidStiffnessMatrix {
426                        reason: "matrix must be symmetric",
427                    },
428                    _ => EigensolveFaerError::InvalidMassMatrix {
429                        reason: "matrix must be symmetric",
430                    },
431                });
432            }
433        }
434    }
435    Ok(())
436}
437
438fn is_exact_identity(matrix: &DenseMatrix<f64>) -> Result<bool, EigensolveFaerError> {
439    let shape = matrix.shape();
440    for row in 0..matrix.rows() {
441        for column in 0..matrix.columns() {
442            let value = *matrix.value(shape.row_index(row)?, shape.column_index(column)?)?;
443            let expected: f64 = if row == column { 1.0 } else { 0.0 };
444            if value.to_bits() != expected.to_bits() {
445                return Ok(false);
446            }
447        }
448    }
449    Ok(true)
450}
451
452fn to_faer_matrix(matrix: &DenseMatrix<f64>) -> Result<Mat<f64>, EigensolveFaerError> {
453    let rows = matrix.rows();
454    Ok(Mat::from_fn(
455        matrix.rows(),
456        matrix.columns(),
457        |row, column| matrix.values()[column.unbound() * rows + row.unbound()],
458    ))
459}
460
461fn cholesky_lower(matrix: &DenseMatrix<f64>) -> Result<Mat<f64>, EigensolveFaerError> {
462    let dimension = matrix.rows();
463    let shape = matrix.shape();
464    let mut lower = Mat::zeros(dimension, dimension);
465    for row in 0..dimension {
466        for column in 0..=row {
467            let mut value = *matrix.value(shape.row_index(row)?, shape.column_index(column)?)?;
468            for index in 0..column {
469                value -= lower[(row, index)] * lower[(column, index)];
470            }
471            if row == column {
472                if value <= 0.0 || !value.is_finite() {
473                    return Err(EigensolveFaerError::NonPositiveMassMatrix);
474                }
475                lower[(row, column)] = value.sqrt();
476            } else {
477                lower[(row, column)] = value / lower[(column, column)];
478            }
479        }
480    }
481    Ok(lower)
482}
483
484fn inverse_lower_triangular(lower: &Mat<f64>) -> Result<Mat<f64>, EigensolveFaerError> {
485    let dimension = lower.nrows();
486    let mut inverse = Mat::zeros(dimension, dimension);
487    for column in 0..dimension {
488        for row in 0..dimension {
489            let mut value = if row == column { 1.0 } else { 0.0 };
490            for index in 0..row {
491                value -= lower[(row, index)] * inverse[(index, column)];
492            }
493            let diagonal = lower[(row, row)];
494            if diagonal == 0.0 || !diagonal.is_finite() {
495                return Err(EigensolveFaerError::NonPositiveMassMatrix);
496            }
497            inverse[(row, column)] = value / diagonal;
498        }
499    }
500    Ok(inverse)
501}
502
503fn congruence_transform(
504    inverse_lower: &Mat<f64>,
505    stiffness: &Mat<f64>,
506    operation: &'static str,
507) -> Result<Mat<f64>, EigensolveFaerError> {
508    let dimension = stiffness.nrows();
509    let mut left_product = Mat::zeros(dimension, dimension);
510    faer::linalg::matmul::matmul(
511        left_product.as_mut(),
512        faer::Accum::Replace,
513        inverse_lower.as_ref(),
514        stiffness.as_ref(),
515        1.0,
516        faer::Par::Seq,
517    );
518    let mut transformed = Mat::zeros(dimension, dimension);
519    faer::linalg::matmul::matmul(
520        transformed.as_mut(),
521        faer::Accum::Replace,
522        left_product.as_ref(),
523        inverse_lower.transpose(),
524        1.0,
525        faer::Par::Seq,
526    );
527    for row in 0..dimension {
528        for column in 0..dimension {
529            if !transformed[(row, column)].is_finite() {
530                return Err(EigensolveFaerError::ExternalSolver {
531                    operation,
532                    reason: "reduced stiffness matrix is not finite",
533                });
534            }
535        }
536    }
537    Ok(transformed)
538}
539
540fn build_eigenspaces(
541    problem: &GeneralizedEigenProblem,
542    eigenvectors: faer::MatRef<'_, f64>,
543    inverse_lower: Option<&Mat<f64>>,
544    candidates: &[(f64, usize)],
545    selected_modes: usize,
546    operation: &'static str,
547) -> Result<Vec<Eigenspace>, EigensolveFaerError> {
548    let mut eigenspaces = Vec::new();
549    eigenspaces
550        .try_reserve_exact(selected_modes)
551        .map_err(|_| allocation_error(selected_modes))?;
552    let mut selected = 0;
553    while selected < selected_modes {
554        let (eigenvalue, _) = candidates[selected];
555        let mut basis = Vec::new();
556        basis
557            .try_reserve_exact(problem.dimension() - selected)
558            .map_err(|_| allocation_error(problem.dimension() - selected))?;
559        loop {
560            let (candidate, column) = candidates[selected];
561            if !same_eigenvalue(eigenvalue, candidate) {
562                break;
563            }
564            let vector =
565                canonicalized_vector(problem, eigenvectors, inverse_lower, column, operation)?;
566            basis.push(Eigenpair::new(problem, eigenvalue, vector)?);
567            selected = selected
568                .checked_add(1)
569                .ok_or(LinearError::CapacityOverflow {
570                    requested: usize::MAX,
571                })?;
572            if selected == candidates.len() {
573                break;
574            }
575        }
576        eigenspaces.push(Eigenspace::new(problem, eigenvalue, basis)?);
577    }
578    Ok(eigenspaces)
579}
580
581/// Normalizes a generalized eigenvector in the mass inner product and makes
582/// its maximum-magnitude component positive.
583fn canonicalized_vector(
584    problem: &GeneralizedEigenProblem,
585    eigenvectors: faer::MatRef<'_, f64>,
586    inverse_lower: Option<&Mat<f64>>,
587    column: usize,
588    operation: &'static str,
589) -> Result<Vector<f64>, EigensolveFaerError> {
590    let dimension = problem.dimension();
591    let mut values = Vec::new();
592    values
593        .try_reserve_exact(dimension)
594        .map_err(|_| allocation_error(dimension))?;
595    if let Some(inverse_lower) = inverse_lower {
596        for row in 0..dimension {
597            let mut value = 0.0;
598            for index in 0..dimension {
599                value += inverse_lower[(index, row)] * eigenvectors[(index, column)];
600            }
601            if !value.is_finite() {
602                return Err(EigensolveFaerError::ExternalSolver {
603                    operation,
604                    reason: "eigenvector is not finite",
605                });
606            }
607            values.push(value);
608        }
609    } else {
610        for row in 0..dimension {
611            if !eigenvectors[(row, column)].is_finite() {
612                return Err(EigensolveFaerError::ExternalSolver {
613                    operation,
614                    reason: "eigenvector is not finite",
615                });
616            }
617        }
618        for row in 0..dimension {
619            let value = eigenvectors[(row, column)];
620            values.push(if value == 0.0 { 0.0 } else { value });
621        }
622    }
623    let mass_norm_squared = if inverse_lower.is_some() {
624        mass_inner_product(problem.mass(), &values, &values)?
625    } else {
626        let mut sum = 0.0;
627        for value in &values {
628            sum += value * value;
629        }
630        sum
631    };
632    if !mass_norm_squared.is_finite() || mass_norm_squared <= 0.0 {
633        return Err(EigensolveFaerError::NonPositiveMassMatrix);
634    }
635    let mass_norm = mass_norm_squared.sqrt();
636    for value in &mut values {
637        *value /= mass_norm;
638    }
639    let maximum = values
640        .iter()
641        .enumerate()
642        .max_by(|(_, left), (_, right)| left.abs().total_cmp(&right.abs()))
643        .ok_or(EigensolveFaerError::ExternalSolver {
644            operation,
645            reason: "eigenvector is empty",
646        })?;
647    if *maximum.1 < 0.0 {
648        for value in &mut values {
649            *value = -*value;
650        }
651    }
652    Ok(Vector::try_from_vec(values)?)
653}
654
655fn mass_inner_product(
656    mass: &DenseMatrix<f64>,
657    left: &[f64],
658    right: &[f64],
659) -> Result<f64, EigensolveFaerError> {
660    let shape = mass.shape();
661    let mut sum = 0.0;
662    for (column, right_value) in right.iter().enumerate() {
663        for (row, left_value) in left.iter().enumerate() {
664            let value = *mass.value(shape.row_index(row)?, shape.column_index(column)?)?;
665            sum += left_value * value * right_value;
666        }
667    }
668    Ok(sum)
669}
670
671/// Sorts ascending while preserving input order for equal eigenvalues.
672fn stable_sort_candidates(candidates: &mut [(f64, usize)]) {
673    for sorted_end in 1..candidates.len() {
674        let candidate = candidates[sorted_end];
675        let mut position = sorted_end;
676        while position > 0 && candidates[position - 1].0 > candidate.0 {
677            candidates[position] = candidates[position - 1];
678            position -= 1;
679        }
680        candidates[position] = candidate;
681    }
682}
683
684fn same_eigenvalue(left: f64, right: f64) -> bool {
685    left == right
686}
687
688fn allocation_error(requested: usize) -> EigensolveFaerError {
689    EigensolveFaerError::Linear(LinearError::AllocationFailure { requested })
690}
691
692fn try_workspace(request: faer::dyn_stack::StackReq) -> Result<MemBuffer, EigensolveFaerError> {
693    let layout = request
694        .layout()
695        .map_err(|_| LinearError::CapacityOverflow {
696            requested: usize::MAX,
697        })?;
698    MemBuffer::try_new(request).map_err(|_| allocation_error(layout.size()))
699}
700
701fn try_filled<T: Clone>(length: usize, value: T) -> Result<Vec<T>, EigensolveFaerError> {
702    length
703        .checked_mul(core::mem::size_of::<T>())
704        .filter(|&bytes| bytes <= isize::MAX as usize)
705        .ok_or(LinearError::CapacityOverflow { requested: length })?;
706    let mut values = Vec::new();
707    values
708        .try_reserve_exact(length)
709        .map_err(|_| allocation_error(length))?;
710    values.resize(length, value);
711    Ok(values)
712}
713
714#[cfg(test)]
715mod tests {
716    use super::{solve_request_symmetric_f64, solve_symmetric_f64, EigensolveFaerError};
717    use neco_eigensolve::{solve_symmetric_f64 as solve_core, EigensolveConfig, EigensolveRequest};
718    use neco_generalized_eigen::{EigenProjector, GeneralizedEigenProblem};
719    use neco_linear_dense::DenseMatrix;
720    use neco_linear_types::{Shape, Vector};
721
722    fn dense(values: Vec<f64>) -> DenseMatrix<f64> {
723        DenseMatrix::from_row_major(Shape::new(2, 2), values).expect("matrix")
724    }
725
726    fn config() -> EigensolveConfig {
727        EigensolveConfig::new(2, 1.0e-10, 1.0e-10, 8).expect("config")
728    }
729
730    #[test]
731    fn full_mass_diagonal_problem_returns_mass_normalized_eigenpairs() {
732        let problem = GeneralizedEigenProblem::from_dense(
733            dense(vec![8.0, 0.0, 0.0, 27.0]),
734            dense(vec![4.0, 0.0, 0.0, 9.0]),
735        )
736        .expect("problem");
737        let result = solve_symmetric_f64(&problem, config()).expect("result");
738        assert_eq!(result.eigenspaces().len(), 2);
739        assert_eq!(result.eigenspaces()[0].eigenvalue(), 2.0);
740        assert_eq!(result.eigenspaces()[1].eigenvalue(), 3.0);
741        assert_eq!(
742            result.eigenspaces()[0].basis()[0].eigenvector().values(),
743            &[0.5, 0.0]
744        );
745        assert_eq!(
746            result.eigenspaces()[1].basis()[0].eigenvector().values(),
747            &[0.0, 1.0 / 3.0]
748        );
749        assert!(result
750            .eigenspaces()
751            .iter()
752            .flat_map(|eigenspace| eigenspace.basis())
753            .all(|pair| pair.residual().absolute() <= 1.0e-12));
754    }
755
756    #[test]
757    fn non_diagonal_mass_problem_has_small_residuals() {
758        let problem = GeneralizedEigenProblem::from_dense(
759            dense(vec![5.0, 1.0, 1.0, 3.0]),
760            dense(vec![2.0, 1.0, 1.0, 2.0]),
761        )
762        .expect("problem");
763        let result = solve_symmetric_f64(&problem, config()).expect("result");
764        assert!(result
765            .eigenspaces()
766            .iter()
767            .flat_map(|eigenspace| eigenspace.basis())
768            .all(|pair| pair.residual().absolute() <= 1.0e-10));
769    }
770
771    #[test]
772    fn repeated_eigenvalues_return_a_complete_eigenspace() {
773        let problem = GeneralizedEigenProblem::from_dense(
774            dense(vec![2.0, 0.0, 0.0, 2.0]),
775            dense(vec![1.0, 0.0, 0.0, 1.0]),
776        )
777        .expect("problem");
778        let requested_one = EigensolveConfig::new(1, 1.0e-10, 1.0e-10, 8).expect("config");
779        let result = solve_symmetric_f64(&problem, requested_one).expect("result");
780        assert_eq!(result.eigenspaces().len(), 1);
781        assert_eq!(result.eigenspaces()[0].basis().len(), 2);
782    }
783
784    #[test]
785    fn full_mass_projector_is_idempotent() {
786        let problem = GeneralizedEigenProblem::from_dense(
787            dense(vec![8.0, 0.0, 0.0, 27.0]),
788            dense(vec![4.0, 0.0, 0.0, 9.0]),
789        )
790        .expect("problem");
791        let result = solve_symmetric_f64(&problem, config()).expect("result");
792        let projector = EigenProjector::new(result.eigenspaces()[0].clone());
793        let input = Vector::try_from_vec(vec![2.0, -3.0]).expect("input");
794        let once = projector.apply(&input).expect("first projection");
795        let twice = projector.apply(&once).expect("second projection");
796        assert_eq!(once, twice);
797    }
798
799    #[test]
800    fn identity_mass_matches_core_eigenvalues() {
801        let problem = GeneralizedEigenProblem::from_dense(
802            dense(vec![2.0, 0.0, 0.0, 3.0]),
803            dense(vec![1.0, 0.0, 0.0, 1.0]),
804        )
805        .expect("problem");
806        let adapter = solve_symmetric_f64(&problem, config()).expect("adapter");
807        let core = solve_core(&problem, config()).expect("core");
808        assert_eq!(
809            adapter.eigenspaces()[0].eigenvalue(),
810            core.eigenspaces()[0].eigenvalue()
811        );
812        assert_eq!(
813            adapter.eigenspaces()[1].eigenvalue(),
814            core.eigenspaces()[1].eigenvalue()
815        );
816    }
817
818    #[test]
819    fn request_solver_moves_the_projection_reference_to_the_result() {
820        let problem = GeneralizedEigenProblem::from_dense(
821            dense(vec![2.0, 0.0, 0.0, 3.0]),
822            dense(vec![1.0, 0.0, 0.0, 1.0]),
823        )
824        .expect("problem");
825        let request = EigensolveRequest::new(problem, config(), std::sync::Arc::new("projection"));
826        let reference = request.projection_reference().clone();
827        let result = solve_request_symmetric_f64(request).expect("result");
828
829        assert!(std::sync::Arc::ptr_eq(
830            &reference,
831            result.projection_reference()
832        ));
833    }
834
835    #[test]
836    fn invalid_matrices_return_public_failures() {
837        let nonsymmetric = GeneralizedEigenProblem::from_dense(
838            dense(vec![1.0, 2.0, 0.0, 1.0]),
839            dense(vec![1.0, 0.0, 0.0, 1.0]),
840        )
841        .expect("problem");
842        assert!(matches!(
843            solve_symmetric_f64(&nonsymmetric, config()),
844            Err(EigensolveFaerError::InvalidStiffnessMatrix { .. })
845        ));
846
847        let nonsymmetric_mass = GeneralizedEigenProblem::from_dense(
848            dense(vec![1.0, 0.0, 0.0, 2.0]),
849            dense(vec![1.0, 2.0, 0.0, 1.0]),
850        )
851        .expect("problem");
852        assert!(matches!(
853            solve_symmetric_f64(&nonsymmetric_mass, config()),
854            Err(EigensolveFaerError::InvalidMassMatrix { .. })
855        ));
856
857        let nonfinite_stiffness = GeneralizedEigenProblem::from_dense(
858            dense(vec![f64::NAN, 0.0, 0.0, 2.0]),
859            dense(vec![1.0, 0.0, 0.0, 1.0]),
860        )
861        .expect("problem");
862        assert!(matches!(
863            solve_symmetric_f64(&nonfinite_stiffness, config()),
864            Err(EigensolveFaerError::InvalidStiffnessMatrix { .. })
865        ));
866
867        let nonpositive_mass = GeneralizedEigenProblem::from_dense(
868            dense(vec![1.0, 0.0, 0.0, 2.0]),
869            dense(vec![1.0, 0.0, 0.0, -1.0]),
870        )
871        .expect("problem");
872        assert!(matches!(
873            solve_symmetric_f64(&nonpositive_mass, config()),
874            Err(EigensolveFaerError::NonPositiveMassMatrix)
875        ));
876    }
877}