Skip to main content

neco_generalized_eigen/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2#![forbid(unsafe_code)]
3#![doc = include_str!("../README.md")]
4
5extern crate alloc;
6
7use alloc::sync::Arc;
8use alloc::vec::Vec;
9use core::fmt;
10use neco_complex::Complex;
11use neco_linear_dense::DenseMatrix;
12use neco_linear_types::{LinearError, LinearOperator, Shape, Vector};
13use neco_sparse::CsrMatrix;
14
15const ORTHONORMAL_TOLERANCE: f64 = 1.0e-12;
16
17#[derive(Clone, Debug, PartialEq)]
18pub enum GeneralizedEigenError {
19    Linear(LinearError),
20    NonSquareMatrix {
21        rows: usize,
22        columns: usize,
23    },
24    DimensionMismatch {
25        stiffness_rows: usize,
26        stiffness_columns: usize,
27        mass_rows: usize,
28        mass_columns: usize,
29    },
30    InvalidEigenpair {
31        reason: &'static str,
32    },
33    InvalidProjector {
34        reason: &'static str,
35    },
36    InvalidConvergenceStatus {
37        reason: &'static str,
38    },
39}
40
41impl From<LinearError> for GeneralizedEigenError {
42    fn from(error: LinearError) -> Self {
43        Self::Linear(error)
44    }
45}
46
47impl fmt::Display for GeneralizedEigenError {
48    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
49        match self {
50            Self::Linear(error) => error.fmt(formatter),
51            Self::NonSquareMatrix { rows, columns } => {
52                write!(formatter, "matrix shape {rows}x{columns} must be square")
53            }
54            Self::DimensionMismatch {
55                stiffness_rows,
56                stiffness_columns,
57                mass_rows,
58                mass_columns,
59            } => write!(
60                formatter,
61                "stiffness shape {stiffness_rows}x{stiffness_columns} differs from mass shape {mass_rows}x{mass_columns}"
62            ),
63            Self::InvalidEigenpair { reason } => write!(formatter, "invalid eigenpair: {reason}"),
64            Self::InvalidProjector { reason } => write!(formatter, "invalid eigenprojector: {reason}"),
65            Self::InvalidConvergenceStatus { reason } => {
66                write!(formatter, "invalid convergence status: {reason}")
67            }
68        }
69    }
70}
71
72#[cfg(feature = "std")]
73impl std::error::Error for GeneralizedEigenError {}
74
75/// 一般化固有値問題 K x = λ M x です。質量の計量は問題ごとに一つ作り、問題から作る全ての固有空間で共有します。
76#[derive(Clone, Debug, PartialEq)]
77pub struct GeneralizedEigenProblem {
78    stiffness: DenseMatrix<f64>,
79    mass: DenseMatrix<f64>,
80    mass_metric: Arc<OwnedMassMetric>,
81}
82
83impl GeneralizedEigenProblem {
84    pub fn from_dense(
85        stiffness: DenseMatrix<f64>,
86        mass: DenseMatrix<f64>,
87    ) -> Result<Self, GeneralizedEigenError> {
88        validate_problem_shapes(stiffness.shape(), mass.shape())?;
89        let mass_metric = Arc::new(OwnedMassMetric::try_from_dense(&mass)?);
90        Ok(Self {
91            stiffness,
92            mass,
93            mass_metric,
94        })
95    }
96
97    pub fn from_csr(
98        stiffness: &CsrMatrix<f64>,
99        mass: &CsrMatrix<f64>,
100    ) -> Result<Self, GeneralizedEigenError> {
101        validate_problem_shapes(stiffness.shape(), mass.shape())?;
102        Self::from_dense(csr_to_dense(stiffness)?, csr_to_dense(mass)?)
103    }
104
105    pub fn dimension(&self) -> usize {
106        self.stiffness.rows()
107    }
108
109    pub fn stiffness(&self) -> &DenseMatrix<f64> {
110        &self.stiffness
111    }
112
113    pub fn mass(&self) -> &DenseMatrix<f64> {
114        &self.mass
115    }
116}
117
118#[derive(Clone, Copy, Debug, PartialEq)]
119pub struct EigenResidual {
120    absolute: f64,
121    relative: f64,
122}
123
124impl EigenResidual {
125    pub fn new(absolute: f64, relative: f64) -> Result<Self, GeneralizedEigenError> {
126        if !is_finite_nonnegative(absolute) || !is_finite_nonnegative(relative) {
127            return Err(GeneralizedEigenError::InvalidEigenpair {
128                reason: "residual values must be finite and non-negative",
129            });
130        }
131        Ok(Self { absolute, relative })
132    }
133
134    pub fn from_problem(
135        problem: &GeneralizedEigenProblem,
136        eigenvalue: f64,
137        vector: &Vector<f64>,
138    ) -> Result<Self, GeneralizedEigenError> {
139        validate_eigenvalue(eigenvalue)?;
140        validate_vector_dimension(problem.dimension(), vector)?;
141        if vector.values().iter().any(|value| !value.is_finite()) {
142            return Err(GeneralizedEigenError::InvalidEigenpair {
143                reason: "eigenvector values must be finite",
144            });
145        }
146        let stiffness_product = problem.stiffness.apply(vector)?;
147        let mass_product = problem.mass.apply(vector)?;
148        let mut residual_square = 0.0;
149        let mut stiffness_square = 0.0;
150        let mut mass_square = 0.0;
151        for (stiffness_value, mass_value) in
152            stiffness_product.values().iter().zip(mass_product.values())
153        {
154            let residual_value = *stiffness_value - eigenvalue * *mass_value;
155            residual_square += residual_value * residual_value;
156            stiffness_square += stiffness_value * stiffness_value;
157            mass_square += mass_value * mass_value;
158        }
159        let absolute = square_root(residual_square);
160        let scale = square_root(stiffness_square)
161            .max(eigenvalue.abs() * square_root(mass_square))
162            .max(f64::MIN_POSITIVE);
163        Self::new(absolute, absolute / scale)
164    }
165
166    pub fn absolute(&self) -> f64 {
167        self.absolute
168    }
169
170    pub fn relative(&self) -> f64 {
171        self.relative
172    }
173
174    /// Returns the convergence decision shared by every sibling eigensolver:
175    /// exact zero when both tolerances are zero, otherwise either tolerance
176    /// suffices.
177    pub fn meets_tolerance(&self, absolute_tolerance: f64, relative_tolerance: f64) -> bool {
178        if absolute_tolerance == 0.0 && relative_tolerance == 0.0 {
179            self.absolute == 0.0
180        } else {
181            self.absolute <= absolute_tolerance || self.relative <= relative_tolerance
182        }
183    }
184}
185
186#[derive(Clone, Debug, PartialEq)]
187pub struct Eigenpair {
188    eigenvalue: f64,
189    eigenvector: Vector<f64>,
190    residual: EigenResidual,
191}
192
193impl Eigenpair {
194    pub fn new(
195        problem: &GeneralizedEigenProblem,
196        eigenvalue: f64,
197        eigenvector: Vector<f64>,
198    ) -> Result<Self, GeneralizedEigenError> {
199        let residual = EigenResidual::from_problem(problem, eigenvalue, &eigenvector)?;
200        Ok(Self {
201            eigenvalue,
202            eigenvector,
203            residual,
204        })
205    }
206
207    pub fn eigenvalue(&self) -> f64 {
208        self.eigenvalue
209    }
210
211    pub fn eigenvector(&self) -> &Vector<f64> {
212        &self.eigenvector
213    }
214
215    pub fn residual(&self) -> EigenResidual {
216        self.residual
217    }
218}
219
220#[derive(Clone, Debug)]
221struct MassEntry {
222    position: usize,
223    bits: u64,
224}
225
226#[derive(Clone, Debug)]
227struct OwnedMassMetric {
228    shape: Shape,
229    length: usize,
230    entries: Vec<MassEntry>,
231}
232
233impl OwnedMassMetric {
234    fn try_from_dense(mass: &DenseMatrix<f64>) -> Result<Self, GeneralizedEigenError> {
235        let shape = mass.shape();
236        let length = shape.element_count()?;
237        if mass.len() != length {
238            return Err(LinearError::StorageLengthMismatch {
239                expected: length,
240                actual: mass.len(),
241            }
242            .into());
243        }
244        if length > isize::MAX as usize {
245            return Err(LinearError::InvalidStorage {
246                reason: "matrix length exceeds the representable allocation limit",
247            }
248            .into());
249        }
250        let mut count = 0usize;
251        for value in mass.values() {
252            if value.to_bits() != 0 {
253                count = count.checked_add(1).ok_or(LinearError::CapacityOverflow {
254                    requested: usize::MAX,
255                })?;
256            }
257        }
258        let capacity_bytes = count
259            .checked_mul(core::mem::size_of::<MassEntry>())
260            .ok_or(LinearError::CapacityOverflow { requested: count })?;
261        if capacity_bytes > isize::MAX as usize {
262            return Err(LinearError::CapacityOverflow { requested: count }.into());
263        }
264        let mut entries = Vec::new();
265        entries
266            .try_reserve_exact(count)
267            .map_err(|_| LinearError::AllocationFailure { requested: count })?;
268        for (position, value) in mass.values().iter().enumerate() {
269            let bits = value.to_bits();
270            if bits != 0 {
271                entries.push(MassEntry { position, bits });
272            }
273        }
274        Ok(Self {
275            shape,
276            length,
277            entries,
278        })
279    }
280
281    fn values(&self) -> impl Iterator<Item = f64> + '_ {
282        let mut cursor = 0;
283        (0..self.length).map(move |position| {
284            if let Some(entry) = self.entries.get(cursor) {
285                if entry.position == position {
286                    cursor += 1;
287                    return f64::from_bits(entry.bits);
288                }
289            }
290            f64::from_bits(0)
291        })
292    }
293}
294
295impl PartialEq for OwnedMassMetric {
296    fn eq(&self, other: &Self) -> bool {
297        self.shape == other.shape && self.values().eq(other.values())
298    }
299}
300
301#[derive(Clone, Debug, PartialEq)]
302pub struct Eigenspace {
303    eigenvalue: f64,
304    basis: Vec<Eigenpair>,
305    mass: Arc<OwnedMassMetric>,
306}
307
308impl Eigenspace {
309    pub fn new(
310        problem: &GeneralizedEigenProblem,
311        eigenvalue: f64,
312        basis: Vec<Eigenpair>,
313    ) -> Result<Self, GeneralizedEigenError> {
314        validate_eigenvalue(eigenvalue)?;
315        let first = basis
316            .first()
317            .ok_or(GeneralizedEigenError::InvalidProjector {
318                reason: "an eigenspace requires at least one basis vector",
319            })?;
320        let dimension = first.eigenvector.len();
321        if dimension != problem.dimension() {
322            return Err(GeneralizedEigenError::DimensionMismatch {
323                stiffness_rows: problem.dimension(),
324                stiffness_columns: 1,
325                mass_rows: dimension,
326                mass_columns: 1,
327            });
328        }
329        for eigenpair in &basis {
330            if eigenpair.eigenvalue != eigenvalue {
331                return Err(GeneralizedEigenError::InvalidProjector {
332                    reason: "basis eigenvalues must equal the eigenspace eigenvalue",
333                });
334            }
335            if eigenpair.eigenvector.len() != dimension {
336                return Err(GeneralizedEigenError::InvalidProjector {
337                    reason: "basis vector lengths must match",
338                });
339            }
340            if EigenResidual::from_problem(problem, eigenvalue, eigenpair.eigenvector())?
341                != eigenpair.residual()
342            {
343                return Err(GeneralizedEigenError::InvalidProjector {
344                    reason: "basis residuals must match the input problem",
345                });
346            }
347            let norm = mass_inner_product(
348                problem.mass().shape(),
349                problem.mass().values().iter().copied(),
350                eigenpair.eigenvector.values(),
351                eigenpair.eigenvector.values(),
352            )?;
353            if !norm.is_finite() || (norm - 1.0).abs() > ORTHONORMAL_TOLERANCE {
354                return Err(GeneralizedEigenError::InvalidProjector {
355                    reason: "basis vectors must have unit mass norm",
356                });
357            }
358        }
359        for (index, left) in basis.iter().enumerate() {
360            for right in basis.iter().skip(index + 1) {
361                if mass_inner_product(
362                    problem.mass().shape(),
363                    problem.mass().values().iter().copied(),
364                    left.eigenvector.values(),
365                    right.eigenvector.values(),
366                )?
367                .abs()
368                    >= ORTHONORMAL_TOLERANCE
369                {
370                    return Err(GeneralizedEigenError::InvalidProjector {
371                        reason: "basis vectors must be pairwise mass orthogonal",
372                    });
373                }
374            }
375        }
376        Ok(Self {
377            eigenvalue,
378            basis,
379            mass: Arc::clone(&problem.mass_metric),
380        })
381    }
382
383    pub fn eigenvalue(&self) -> f64 {
384        self.eigenvalue
385    }
386
387    pub fn dimension(&self) -> usize {
388        self.basis[0].eigenvector.len()
389    }
390
391    pub fn basis(&self) -> &[Eigenpair] {
392        &self.basis
393    }
394}
395
396#[derive(Clone, Debug, PartialEq)]
397pub struct EigenProjector {
398    eigenspace: Eigenspace,
399}
400
401impl EigenProjector {
402    pub fn new(eigenspace: Eigenspace) -> Self {
403        Self { eigenspace }
404    }
405
406    pub fn eigenspace(&self) -> &Eigenspace {
407        &self.eigenspace
408    }
409
410    pub fn apply(&self, input: &Vector<f64>) -> Result<Vector<f64>, GeneralizedEigenError> {
411        if input.len() != self.domain() {
412            return Err(GeneralizedEigenError::DimensionMismatch {
413                stiffness_rows: self.domain(),
414                stiffness_columns: 1,
415                mass_rows: input.len(),
416                mass_columns: 1,
417            });
418        }
419        let mut projected = Vec::new();
420        projected
421            .try_reserve_exact(self.domain())
422            .map_err(|_| LinearError::AllocationFailure {
423                requested: self.domain(),
424            })?;
425        projected.resize(self.domain(), 0.0);
426        for eigenpair in self.eigenspace.basis() {
427            let coefficient = mass_inner_product(
428                self.eigenspace.mass.shape,
429                self.eigenspace.mass.values(),
430                eigenpair.eigenvector.values(),
431                input.values(),
432            )?;
433            for (output, basis_value) in projected.iter_mut().zip(eigenpair.eigenvector.values()) {
434                *output += coefficient * *basis_value;
435            }
436        }
437        Ok(Vector::try_from_vec(projected)?)
438    }
439}
440
441impl LinearOperator<f64> for EigenProjector {
442    fn domain(&self) -> usize {
443        self.eigenspace.dimension()
444    }
445
446    fn codomain(&self) -> usize {
447        self.eigenspace.dimension()
448    }
449
450    fn apply(&self, input: &Vector<f64>) -> Result<Vector<f64>, LinearError> {
451        EigenProjector::apply(self, input).map_err(|error| match error {
452            GeneralizedEigenError::Linear(linear) => linear,
453            GeneralizedEigenError::DimensionMismatch { .. } => LinearError::StorageLengthMismatch {
454                expected: self.domain(),
455                actual: input.len(),
456            },
457            _ => LinearError::InvalidStorage {
458                reason: "validated eigenspace projection failed",
459            },
460        })
461    }
462}
463
464#[derive(Clone, Copy, Debug, PartialEq)]
465pub struct ConvergenceStatus {
466    kind: ConvergenceKind,
467    iterations: usize,
468    requested_modes: usize,
469    returned_modes: usize,
470    converged_modes: usize,
471    absolute_tolerance: f64,
472    relative_tolerance: f64,
473}
474
475#[derive(Clone, Copy, Debug, PartialEq)]
476enum ConvergenceKind {
477    Converged,
478    IterationLimit,
479}
480
481impl ConvergenceStatus {
482    pub fn converged(
483        iterations: usize,
484        requested_modes: usize,
485        returned_modes: usize,
486        converged_modes: usize,
487        absolute_tolerance: f64,
488        relative_tolerance: f64,
489    ) -> Result<Self, GeneralizedEigenError> {
490        validate_tolerances(absolute_tolerance, relative_tolerance)?;
491        if converged_modes != returned_modes {
492            return Err(GeneralizedEigenError::InvalidConvergenceStatus {
493                reason: "converged modes must equal returned modes when converged",
494            });
495        }
496        Ok(Self {
497            kind: ConvergenceKind::Converged,
498            iterations,
499            requested_modes,
500            returned_modes,
501            converged_modes,
502            absolute_tolerance,
503            relative_tolerance,
504        })
505    }
506
507    pub fn iteration_limit(
508        iterations: usize,
509        requested_modes: usize,
510        returned_modes: usize,
511        converged_modes: usize,
512        absolute_tolerance: f64,
513        relative_tolerance: f64,
514    ) -> Result<Self, GeneralizedEigenError> {
515        validate_tolerances(absolute_tolerance, relative_tolerance)?;
516        if converged_modes > returned_modes {
517            return Err(GeneralizedEigenError::InvalidConvergenceStatus {
518                reason: "converged modes must not exceed returned modes",
519            });
520        }
521        Ok(Self {
522            kind: ConvergenceKind::IterationLimit,
523            iterations,
524            requested_modes,
525            returned_modes,
526            converged_modes,
527            absolute_tolerance,
528            relative_tolerance,
529        })
530    }
531
532    pub fn is_converged(&self) -> bool {
533        self.kind == ConvergenceKind::Converged
534    }
535
536    pub fn iterations(&self) -> usize {
537        self.iterations
538    }
539
540    pub fn requested_modes(&self) -> usize {
541        self.requested_modes
542    }
543
544    pub fn returned_modes(&self) -> usize {
545        self.returned_modes
546    }
547
548    pub fn converged_modes(&self) -> usize {
549        self.converged_modes
550    }
551
552    pub fn absolute_tolerance(&self) -> f64 {
553        self.absolute_tolerance
554    }
555
556    pub fn relative_tolerance(&self) -> f64 {
557        self.relative_tolerance
558    }
559}
560
561#[derive(Clone, Copy, Debug, PartialEq)]
562pub struct EigenShift {
563    value: Complex<f64>,
564}
565
566impl EigenShift {
567    pub fn new(value: Complex<f64>) -> Result<Self, GeneralizedEigenError> {
568        if !value.real().is_finite() || !value.imaginary().is_finite() {
569            return Err(GeneralizedEigenError::InvalidEigenpair {
570                reason: "eigen shift components must be finite",
571            });
572        }
573        Ok(Self { value })
574    }
575
576    pub fn value(&self) -> Complex<f64> {
577        self.value
578    }
579
580    pub fn real(&self) -> f64 {
581        *self.value.real()
582    }
583
584    pub fn imaginary(&self) -> f64 {
585        *self.value.imaginary()
586    }
587}
588
589fn validate_problem_shapes(stiffness: Shape, mass: Shape) -> Result<(), GeneralizedEigenError> {
590    validate_square(stiffness)?;
591    validate_square(mass)?;
592    if stiffness != mass {
593        return Err(GeneralizedEigenError::DimensionMismatch {
594            stiffness_rows: stiffness.rows(),
595            stiffness_columns: stiffness.columns(),
596            mass_rows: mass.rows(),
597            mass_columns: mass.columns(),
598        });
599    }
600    Ok(())
601}
602
603fn validate_square(shape: Shape) -> Result<(), GeneralizedEigenError> {
604    if shape.rows() != shape.columns() {
605        return Err(GeneralizedEigenError::NonSquareMatrix {
606            rows: shape.rows(),
607            columns: shape.columns(),
608        });
609    }
610    Ok(())
611}
612
613fn csr_to_dense(matrix: &CsrMatrix<f64>) -> Result<DenseMatrix<f64>, GeneralizedEigenError> {
614    let shape = matrix.shape();
615    let length = shape.element_count()?;
616    let mut values = Vec::new();
617    values
618        .try_reserve_exact(length)
619        .map_err(|_| LinearError::AllocationFailure { requested: length })?;
620    values.resize(length, 0.0);
621    for row in 0..shape.rows() {
622        let row_index = shape.row_index(row)?;
623        for (column, value) in matrix.row(row_index)?.entries() {
624            let position = column
625                .checked_mul(shape.rows())
626                .and_then(|offset| offset.checked_add(row))
627                .ok_or(LinearError::CapacityOverflow {
628                    requested: usize::MAX,
629                })?;
630            values[position] = *value;
631        }
632    }
633    Ok(DenseMatrix::from_column_major(shape, values)?)
634}
635
636fn validate_eigenvalue(eigenvalue: f64) -> Result<(), GeneralizedEigenError> {
637    if eigenvalue.is_finite() {
638        Ok(())
639    } else {
640        Err(GeneralizedEigenError::InvalidEigenpair {
641            reason: "eigenvalue must be finite",
642        })
643    }
644}
645
646fn validate_vector_dimension(
647    dimension: usize,
648    vector: &Vector<f64>,
649) -> Result<(), GeneralizedEigenError> {
650    if vector.len() == dimension {
651        Ok(())
652    } else {
653        Err(GeneralizedEigenError::DimensionMismatch {
654            stiffness_rows: dimension,
655            stiffness_columns: 1,
656            mass_rows: vector.len(),
657            mass_columns: 1,
658        })
659    }
660}
661
662fn validate_tolerances(
663    absolute_tolerance: f64,
664    relative_tolerance: f64,
665) -> Result<(), GeneralizedEigenError> {
666    if is_finite_nonnegative(absolute_tolerance) && is_finite_nonnegative(relative_tolerance) {
667        Ok(())
668    } else {
669        Err(GeneralizedEigenError::InvalidEigenpair {
670            reason: "tolerances must be finite and non-negative",
671        })
672    }
673}
674
675fn is_finite_nonnegative(value: f64) -> bool {
676    value.is_finite() && value >= 0.0
677}
678
679fn mass_inner_product(
680    shape: Shape,
681    mut values: impl Iterator<Item = f64>,
682    left: &[f64],
683    right: &[f64],
684) -> Result<f64, GeneralizedEigenError> {
685    if left.len() != shape.columns() || right.len() != shape.rows() {
686        return Err(GeneralizedEigenError::DimensionMismatch {
687            stiffness_rows: shape.rows(),
688            stiffness_columns: shape.columns(),
689            mass_rows: left.len(),
690            mass_columns: right.len(),
691        });
692    }
693    let mut sum = 0.0;
694    for (column, right_value) in right.iter().enumerate() {
695        for (row, left_value) in left.iter().enumerate() {
696            let row_index = shape.row_index(row)?;
697            let column_index = shape.column_index(column)?;
698            let _position = column_index
699                .value()
700                .checked_mul(shape.rows())
701                .and_then(|offset| offset.checked_add(row_index.value()))
702                .ok_or(LinearError::CapacityOverflow {
703                    requested: usize::MAX,
704                })?;
705            let value = values.next().ok_or(LinearError::InvalidStorage {
706                reason: "matrix storage is shorter than its declared shape",
707            })?;
708            sum += left_value * value * right_value;
709        }
710    }
711    Ok(sum)
712}
713
714fn square_root(value: f64) -> f64 {
715    if value == 0.0 {
716        return 0.0;
717    }
718    let initial_exponent = ((value.to_bits() >> 52) & 0x7ff) as i32 - 1023;
719    let mut estimate = f64::from_bits(((initial_exponent / 2 + 1023) as u64) << 52);
720    for _ in 0..8 {
721        estimate = 0.5 * (estimate + value / estimate);
722    }
723    estimate
724}
725
726#[cfg(test)]
727mod tests {
728    use alloc::vec;
729    use alloc::vec::Vec;
730
731    use super::{
732        ConvergenceStatus, EigenProjector, EigenResidual, EigenShift, Eigenpair, Eigenspace,
733        GeneralizedEigenError, GeneralizedEigenProblem,
734    };
735    use neco_complex::Complex;
736    use neco_linear_dense::DenseMatrix;
737    use neco_linear_types::{LinearOperator, Shape, Vector};
738    use neco_sparse::CsrMatrix;
739
740    fn dense(values: Vec<f64>) -> DenseMatrix<f64> {
741        DenseMatrix::from_row_major(Shape::new(2, 2), values).expect("valid dense matrix")
742    }
743
744    fn problem() -> GeneralizedEigenProblem {
745        GeneralizedEigenProblem::from_dense(
746            dense(vec![2.0, 0.0, 0.0, 3.0]),
747            dense(vec![1.0, 0.0, 0.0, 1.0]),
748        )
749        .expect("valid problem")
750    }
751
752    fn vector(values: Vec<f64>) -> Vector<f64> {
753        Vector::try_from_vec(values).expect("valid vector")
754    }
755
756    fn pair(eigenvalue: f64, values: Vec<f64>) -> Eigenpair {
757        Eigenpair::new(&problem(), eigenvalue, vector(values)).expect("valid eigenpair")
758    }
759
760    #[test]
761    fn dense_problem_constructor_preserves_matrices() {
762        let eigenproblem = problem();
763        assert_eq!(eigenproblem.dimension(), 2);
764        assert_eq!(eigenproblem.stiffness().values(), &[2.0, 0.0, 0.0, 3.0]);
765        assert_eq!(eigenproblem.mass().values(), &[1.0, 0.0, 0.0, 1.0]);
766    }
767
768    #[test]
769    fn dense_and_csr_shape_mismatches_are_rejected() {
770        let rectangular = DenseMatrix::try_zeros(Shape::new(2, 3), 0.0).expect("matrix");
771        let square = DenseMatrix::try_zeros(Shape::new(2, 2), 0.0).expect("matrix");
772        assert!(matches!(
773            GeneralizedEigenProblem::from_dense(rectangular, square),
774            Err(GeneralizedEigenError::NonSquareMatrix { .. })
775        ));
776        let stiffness =
777            CsrMatrix::from_parts(Shape::new(2, 2), vec![0, 1, 2], vec![0, 1], vec![1.0, 1.0])
778                .expect("CSR matrix");
779        let mass = CsrMatrix::from_parts(
780            Shape::new(3, 3),
781            vec![0, 1, 2, 3],
782            vec![0, 1, 2],
783            vec![1.0, 1.0, 1.0],
784        )
785        .expect("CSR matrix");
786        assert!(matches!(
787            GeneralizedEigenProblem::from_csr(&stiffness, &mass),
788            Err(GeneralizedEigenError::DimensionMismatch { .. })
789        ));
790    }
791
792    #[test]
793    fn csr_conversion_preserves_column_major_values() {
794        let stiffness = CsrMatrix::from_parts(
795            Shape::new(2, 2),
796            vec![0, 2, 3],
797            vec![0, 1, 1],
798            vec![1.0, 2.0, 3.0],
799        )
800        .expect("CSR matrix");
801        let mass =
802            CsrMatrix::from_parts(Shape::new(2, 2), vec![0, 1, 2], vec![0, 1], vec![1.0, 1.0])
803                .expect("CSR matrix");
804        let eigenproblem =
805            GeneralizedEigenProblem::from_csr(&stiffness, &mass).expect("valid problem");
806        assert_eq!(eigenproblem.stiffness().values(), &[1.0, 0.0, 2.0, 3.0]);
807    }
808
809    #[test]
810    fn diagonal_problem_has_zero_eigen_residual() {
811        let residual = EigenResidual::from_problem(&problem(), 2.0, &vector(vec![1.0, 0.0]))
812            .expect("residual");
813        assert_eq!(residual.absolute(), 0.0);
814        assert_eq!(residual.relative(), 0.0);
815    }
816
817    #[test]
818    fn meets_tolerance_requires_exact_zero_residual_when_both_tolerances_are_zero() {
819        let zero_residual = EigenResidual::new(0.0, 0.0).expect("zero residual");
820        assert!(zero_residual.meets_tolerance(0.0, 0.0));
821        let tiny_residual = EigenResidual::new(1.0e-15, 1.0e-15).expect("tiny residual");
822        assert!(!tiny_residual.meets_tolerance(0.0, 0.0));
823    }
824
825    #[test]
826    fn meets_tolerance_accepts_either_absolute_or_relative_tolerance() {
827        let residual = EigenResidual::new(1.0e-6, 1.0e-2).expect("residual");
828        assert!(residual.meets_tolerance(1.0e-5, 1.0e-12));
829        assert!(residual.meets_tolerance(1.0e-12, 1.0e-1));
830        assert!(!residual.meets_tolerance(1.0e-12, 1.0e-12));
831    }
832
833    #[test]
834    fn eigen_residual_rejects_nonfinite_vector_before_arithmetic() {
835        assert!(matches!(
836            EigenResidual::from_problem(&problem(), 2.0, &vector(vec![f64::NAN, 0.0])),
837            Err(GeneralizedEigenError::InvalidEigenpair {
838                reason: "eigenvector values must be finite"
839            })
840        ));
841    }
842
843    #[test]
844    fn eigenpair_computes_positive_residual_for_non_eigenvector() {
845        let eigenpair = Eigenpair::new(&problem(), 2.0, vector(vec![0.0, 1.0])).expect("eigenpair");
846        assert!(eigenpair.residual().absolute() > 0.0);
847    }
848
849    #[test]
850    fn eigenpair_rejects_vector_length_mismatch() {
851        assert!(matches!(
852            Eigenpair::new(&problem(), 2.0, vector(vec![1.0])),
853            Err(GeneralizedEigenError::DimensionMismatch { .. })
854        ));
855    }
856
857    #[test]
858    fn two_vector_eigenspace_has_an_idempotent_projector() {
859        let eigenproblem = problem();
860        let space = Eigenspace::new(
861            &eigenproblem,
862            2.0,
863            vec![pair(2.0, vec![1.0, 0.0]), pair(2.0, vec![0.0, 1.0])],
864        )
865        .expect("orthonormal basis");
866        let projector = EigenProjector::new(space);
867        let input = vector(vec![4.0, -3.0]);
868        let once = projector.apply(&input).expect("projection");
869        let twice = projector.apply(&once).expect("projection");
870        assert_eq!(once, twice);
871        assert_eq!(
872            LinearOperator::apply(&projector, &input).expect("operator"),
873            once
874        );
875    }
876
877    #[test]
878    fn mass_orthonormal_basis_has_an_idempotent_projector() {
879        let eigenproblem = GeneralizedEigenProblem::from_dense(
880            dense(vec![2.0, 0.0, 0.0, 3.0]),
881            dense(vec![4.0, 0.0, 0.0, 9.0]),
882        )
883        .expect("valid problem");
884        let space = Eigenspace::new(
885            &eigenproblem,
886            0.5,
887            vec![Eigenpair::new(&eigenproblem, 0.5, vector(vec![0.5, 0.0])).expect("eigenpair")],
888        )
889        .expect("mass orthonormal basis");
890        let projector = EigenProjector::new(space);
891        let input = vector(vec![8.0, -3.0]);
892        assert_eq!(
893            projector.apply(&input).expect("projection").values(),
894            &[8.0, 0.0]
895        );
896    }
897
898    #[test]
899    fn non_orthonormal_basis_and_projector_input_mismatch_are_rejected() {
900        let eigenproblem = problem();
901        assert!(matches!(
902            Eigenspace::new(
903                &eigenproblem,
904                2.0,
905                vec![pair(2.0, vec![1.0, 0.0]), pair(2.0, vec![1.0, 0.0])]
906            ),
907            Err(GeneralizedEigenError::InvalidProjector { .. })
908        ));
909        let projector = EigenProjector::new(
910            Eigenspace::new(&eigenproblem, 2.0, vec![pair(2.0, vec![1.0, 0.0])]).expect("basis"),
911        );
912        assert!(matches!(
913            projector.apply(&vector(vec![1.0])),
914            Err(GeneralizedEigenError::DimensionMismatch { .. })
915        ));
916    }
917
918    #[test]
919    fn eigenspace_rejects_an_eigenpair_from_a_different_problem() {
920        let problem_a = GeneralizedEigenProblem::from_dense(
921            dense(vec![1.0, 0.0, 0.0, 2.0]),
922            dense(vec![1.0, 0.0, 0.0, 1.0]),
923        )
924        .expect("problem A");
925        let problem_b = GeneralizedEigenProblem::from_dense(
926            dense(vec![1.0, 0.0, 0.0, 3.0]),
927            dense(vec![1.0, 0.0, 0.0, 1.0]),
928        )
929        .expect("problem B");
930        let pair = Eigenpair::new(&problem_b, 3.0, vector(vec![0.0, 1.0])).expect("pair");
931        assert!(matches!(
932            Eigenspace::new(&problem_a, 3.0, vec![pair]),
933            Err(GeneralizedEigenError::InvalidProjector { .. })
934        ));
935    }
936
937    #[test]
938    fn convergence_status_validates_tolerances_and_mode_counts() {
939        assert!(matches!(
940            ConvergenceStatus::converged(4, 2, 2, 2, -1.0, 1.0e-8),
941            Err(GeneralizedEigenError::InvalidEigenpair { .. })
942        ));
943        let converged = ConvergenceStatus::converged(4, 1, 2, 2, 1.0e-8, 2.0e-8).expect("status");
944        assert!(converged.is_converged());
945        assert_eq!(converged.iterations(), 4);
946        assert_eq!(converged.requested_modes(), 1);
947        assert_eq!(converged.returned_modes(), 2);
948        assert_eq!(converged.converged_modes(), 2);
949        assert_eq!(converged.absolute_tolerance(), 1.0e-8);
950        assert_eq!(converged.relative_tolerance(), 2.0e-8);
951        assert!(matches!(
952            ConvergenceStatus::converged(4, 2, 2, 1, 1.0e-8, 1.0e-8),
953            Err(GeneralizedEigenError::InvalidConvergenceStatus { .. })
954        ));
955        let limited =
956            ConvergenceStatus::iteration_limit(4, 2, 2, 1, 1.0e-8, 1.0e-8).expect("status");
957        assert!(!limited.is_converged());
958        assert_eq!(limited.returned_modes(), 2);
959        assert_eq!(limited.converged_modes(), 1);
960        assert!(matches!(
961            ConvergenceStatus::iteration_limit(4, 2, 1, 2, 1.0e-8, 1.0e-8),
962            Err(GeneralizedEigenError::InvalidConvergenceStatus { .. })
963        ));
964    }
965
966    #[test]
967    fn complex_shift_uses_complex_f64_components() {
968        let shift = EigenShift::new(Complex::new(1.5, -0.25)).expect("finite shift");
969        assert_eq!(shift.real(), 1.5);
970        assert_eq!(shift.imaginary(), -0.25);
971        assert_eq!(shift.value(), Complex::new(1.5, -0.25));
972    }
973}