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
176pub 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
234fn 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
581fn 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
671fn 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}