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#[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 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}