Skip to main content

Rustb/
ndarray_lapack.rs

1//! Partial eigensolver bindings to LAPACK routines (zheevx, zheevr, zheev).
2//!
3//! This module provides functions for solving Hermitian eigenvalue problems
4//! in a specified energy window, using LAPACK's `zheevx` (expert driver with
5//! eigenvalue range selection), `zheevr` (relative robust representation),
6//! and `zheev` (full diagonalization).
7//!
8//! # Backend selection
9//!
10//! The LAPACK backend is chosen via Cargo features:
11//! - `intel-mkl-static` / `intel-mkl-system`: Intel MKL.
12//! - `openblas-static` / `openblas-system`: OpenBLAS.
13//! - `netlib-static` / `netlib-system`: reference netlib LAPACK.
14
15#[cfg(any(feature = "intel-mkl-system", feature = "intel-mkl-static"))]
16extern crate intel_mkl_src as _src;
17
18#[cfg(any(feature = "openblas-system", feature = "openblas-static"))]
19extern crate openblas_src as _src;
20
21#[cfg(any(feature = "netlib-system", feature = "netlib-static"))]
22extern crate netlib_src as _src;
23
24use lapack::{zheev, zheevr, zheevx};
25use ndarray::{Array1, Array2, ArrayBase, Data, Ix2};
26use ndarray_linalg::UPLO;
27use num_complex::Complex;
28
29/// Safe wrapper around BLAS `zaxpy`: `y += alpha * x` for `Complex<f64>` slices.
30///
31/// # Panics
32///
33/// Panics if `x.len() != y.len()`.
34#[inline]
35pub fn zaxpy(alpha: Complex<f64>, x: &[Complex<f64>], y: &mut [Complex<f64>]) {
36    assert_eq!(x.len(), y.len(), "zaxpy: x and y must have the same length");
37    let n = x.len() as i32;
38    unsafe { blas::zaxpy(n, alpha, x, 1, y, 1) };
39}
40
41/// Compute selected eigenvalues and eigenvectors of a complex Hermitian matrix
42/// using LAPACK's `zheevx` (expert driver).
43///
44/// # Parameters
45///
46/// - `x`: the input Hermitian matrix.
47/// - `range`: `(v_low, v_high)` -- eigenvalue range to search.
48/// - `epsilon`: absolute tolerance for eigenvalue convergence.
49/// - `uplo`: whether the upper or lower triangle of `x` is stored.
50///
51/// # Returns
52///
53/// `(eigenvalues, eigenvectors)` where eigenvalues is `Array1<f64>` and
54/// eigenvectors is `Array2<Complex<f64>>` of shape `(n_found, n)`.
55/// Each row of the eigenvector matrix is an eigenvector.
56///
57/// # Panics
58///
59/// Panics if `zheevx` returns a non-zero info code.
60pub fn eigh_x<S>(
61    x: &ArrayBase<S, Ix2>,
62    range: (f64, f64),
63    epsilon: f64,
64    uplo: UPLO,
65) -> (Array1<f64>, Array2<Complex<f64>>)
66where
67    S: Data<Elem = Complex<f64>>,
68{
69    let n = x.shape()[0] as i32;
70    let mut a: Vec<_> = x.iter().cloned().collect();
71    let mut w = vec![0.0; n as usize];
72    let mut z = vec![Complex::new(0.0, 0.0); (n * n) as usize];
73    let mut m = 0;
74    let mut info = 0;
75    let mut ifail = vec![0; n as usize];
76    let mut work = vec![Complex::new(0.0, 0.0); (2 * n) as usize];
77    let mut rwork = vec![0.0; (7 * n) as usize];
78    let mut iwork = vec![0; (5 * n) as usize];
79    let job1 = b'V'; // compute eigenvectors
80    let job2 = b'V'; // eigenvalues in range
81    let job3 = match uplo {
82        UPLO::Upper => b'U',
83        UPLO::Lower => b'L',
84    };
85
86    unsafe {
87        zheevx(
88            job1,
89            job2,
90            job3,
91            n,
92            &mut a,
93            n,
94            range.0,
95            range.1,
96            0,
97            n,
98            epsilon,
99            &mut m,
100            &mut w,
101            &mut z,
102            n,
103            &mut work,
104            2 * n,
105            &mut rwork,
106            &mut iwork,
107            &mut ifail,
108            &mut info,
109        );
110    }
111    if info == 0 {
112        (
113            Array1::<f64>::from_vec(w.into_iter().take(m as usize).collect()),
114            Array2::<Complex<f64>>::from_shape_vec(
115                [m as usize, n as usize],
116                z.into_iter().take((n * m) as usize).collect(),
117            )
118            .unwrap(),
119        )
120    } else {
121        panic!("zheevx failed with info = {}", info);
122    }
123}
124
125/// Compute selected eigenvalues only (no eigenvectors) of a complex Hermitian
126/// matrix using LAPACK's `zheevx`.
127///
128/// # Parameters
129///
130/// - `x`: the input Hermitian matrix.
131/// - `range`: `(v_low, v_high)` -- eigenvalue range to search.
132/// - `epsilon`: absolute tolerance for eigenvalue convergence.
133/// - `uplo`: whether the upper or lower triangle of `x` is stored.
134///
135/// # Returns
136///
137/// `Array1<f64>` of eigenvalues in the specified range.
138///
139/// # Panics
140///
141/// Panics if `zheevx` returns a non-zero info code.
142pub fn eigvalsh_x<S>(
143    x: &ArrayBase<S, Ix2>,
144    range: (f64, f64),
145    epsilon: f64,
146    uplo: UPLO,
147) -> Array1<f64>
148where
149    S: Data<Elem = Complex<f64>>,
150{
151    let n = x.shape()[0] as i32;
152    let mut a: Vec<_> = x.iter().cloned().collect();
153    let mut w = vec![0.0; n as usize];
154    let mut z = vec![Complex::new(0.0, 0.0); (n * n) as usize];
155    let mut m = 0;
156    let mut info = 0;
157    let mut ifail = vec![0; n as usize];
158    let mut work = vec![Complex::new(0.0, 0.0); (2 * n) as usize];
159    let mut rwork = vec![0.0; (7 * n) as usize];
160    let mut iwork = vec![0; (5 * n) as usize];
161    let job1 = b'N'; // eigenvalues only
162    let job2 = b'V'; // eigenvalues in range
163    let job3 = match uplo {
164        UPLO::Upper => b'U',
165        UPLO::Lower => b'L',
166    };
167
168    unsafe {
169        zheevx(
170            job1,
171            job2,
172            job3,
173            n,
174            &mut a,
175            n,
176            range.0,
177            range.1,
178            0,
179            n,
180            epsilon,
181            &mut m,
182            &mut w,
183            &mut z,
184            n,
185            &mut work,
186            2 * n,
187            &mut rwork,
188            &mut iwork,
189            &mut ifail,
190            &mut info,
191        );
192    }
193    if info == 0 {
194        Array1::<f64>::from_vec(w.into_iter().take(m as usize).collect())
195    } else {
196        panic!("zheevx failed with info = {}", info);
197    }
198}
199
200/// Compute selected eigenvalues and eigenvectors of a complex Hermitian matrix
201/// using LAPACK's `zheevr` (relative robust representation).
202///
203/// This is generally faster than `zheevx` for large matrices when only a subset
204/// of eigenvalues is needed.
205///
206/// # Parameters
207///
208/// - `x`: the input Hermitian matrix.
209/// - `range`: `(v_low, v_high)` -- eigenvalue range to search.
210/// - `epsilon`: absolute tolerance for eigenvalue convergence.
211/// - `uplo`: whether the upper or lower triangle of `x` is stored.
212///
213/// # Returns
214///
215/// `(eigenvalues, eigenvectors)` where eigenvalues is `Array1<f64>` and
216/// eigenvectors is `Array2<Complex<f64>>` of shape `(n_found, n)`.
217pub fn eigh_r<S>(
218    x: &ArrayBase<S, Ix2>,
219    range: (f64, f64),
220    epsilon: f64,
221    uplo: UPLO,
222) -> (Array1<f64>, Array2<Complex<f64>>)
223where
224    S: Data<Elem = Complex<f64>>,
225{
226    let job1 = b'V'; // compute eigenvectors
227    let job2 = b'V'; // eigenvalues in range
228    let job3 = match uplo {
229        UPLO::Upper => b'U',
230        UPLO::Lower => b'L',
231    };
232    let n = x.shape()[0] as i32;
233    let mut a: Vec<_> = x.iter().cloned().collect();
234    let mut w = vec![0.0; n as usize];
235    let mut z = vec![Complex::new(0.0, 0.0); (n * n) as usize];
236    let mut isuppz = vec![0; 2 * n as usize];
237    let mut m = 0;
238    let mut info = 0;
239    let lwork = n * 33 as i32;
240    let liwork = n * 10 as i32;
241    let lrwork = n * 24 as i32;
242    let mut work = vec![Complex::new(0.0, 0.0); lwork as usize];
243    let mut rwork = vec![0.0; lrwork as usize];
244    let mut iwork = vec![0; liwork as usize];
245
246    unsafe {
247        zheevr(
248            job1,
249            job2,
250            job3,
251            n,
252            &mut a,
253            n,
254            range.0,
255            range.1,
256            0,
257            n,
258            epsilon,
259            &mut m,
260            &mut w,
261            &mut z,
262            n,
263            &mut isuppz,
264            &mut work,
265            lwork,
266            &mut rwork,
267            lrwork,
268            &mut iwork,
269            liwork,
270            &mut info,
271        );
272    }
273
274    if info == 0 {
275        (
276            Array1::<f64>::from_vec(w.into_iter().take(m as usize).collect()),
277            Array2::<Complex<f64>>::from_shape_vec(
278                [m as usize, n as usize],
279                z.into_iter().take((n * m) as usize).collect(),
280            )
281            .unwrap(),
282        )
283    } else {
284        panic!("zheevr failed with info = {}", info);
285    }
286}
287
288/// Compute selected eigenvalues only (no eigenvectors) of a complex Hermitian
289/// matrix using LAPACK's `zheevr`.
290///
291/// # Parameters
292///
293/// - `x`: the input Hermitian matrix.
294/// - `range`: `(v_low, v_high)` -- eigenvalue range to search.
295/// - `epsilon`: absolute tolerance for eigenvalue convergence.
296/// - `uplo`: whether the upper or lower triangle of `x` is stored.
297///
298/// # Returns
299///
300/// `Array1<f64>` of eigenvalues in the specified range.
301pub fn eigvalsh_r<S>(
302    x: &ArrayBase<S, Ix2>,
303    range: (f64, f64),
304    epsilon: f64,
305    uplo: UPLO,
306) -> Array1<f64>
307where
308    S: Data<Elem = Complex<f64>>,
309{
310    let n = x.shape()[0] as i32;
311    let mut a: Vec<_> = x.iter().cloned().collect();
312    let mut w = vec![0.0; n as usize];
313    let mut z = vec![Complex::new(0.0, 0.0); (n * n) as usize];
314    let mut isuppz = vec![0; 2 * n as usize];
315    let mut m = 0;
316    let mut info = 0;
317    // Workspace query
318    let mut work = vec![Complex::new(0.0, 0.0); 1 as usize];
319    let mut rwork = vec![0.0; 1 as usize];
320    let mut iwork = vec![0; 1 as usize];
321    let job1 = b'N'; // eigenvalues only
322    let job2 = b'V'; // eigenvalues in range
323    let job3 = match uplo {
324        UPLO::Upper => b'U',
325        UPLO::Lower => b'L',
326    };
327
328    unsafe {
329        zheevr(
330            job1,
331            job2,
332            job3,
333            n,
334            &mut a,
335            n,
336            range.0,
337            range.1,
338            0,
339            n,
340            epsilon,
341            &mut m,
342            &mut w,
343            &mut z,
344            n,
345            &mut isuppz,
346            &mut work,
347            -1,
348            &mut rwork,
349            -1,
350            &mut iwork,
351            -1,
352            &mut info,
353        );
354    }
355
356    let lwork = work[0].re as i32;
357    let liwork = iwork[0] as i32;
358    let lrwork = rwork[0] as i32;
359    let mut work = vec![Complex::new(0.0, 0.0); lwork as usize];
360    let mut rwork = vec![0.0; lrwork as usize];
361    let mut iwork = vec![0; liwork as usize];
362
363    unsafe {
364        zheevr(
365            job1,
366            job2,
367            job3,
368            n,
369            &mut a,
370            n,
371            range.0,
372            range.1,
373            0,
374            n,
375            epsilon,
376            &mut m,
377            &mut w,
378            &mut z,
379            n,
380            &mut isuppz,
381            &mut work,
382            lwork,
383            &mut rwork,
384            lrwork,
385            &mut iwork,
386            liwork,
387            &mut info,
388        );
389    }
390    if info == 0 {
391        Array1::<f64>::from_vec(w.into_iter().take(m as usize).collect())
392    } else {
393        panic!("zheevr failed with info = {}", info);
394    }
395}
396
397/// Compute all eigenvalues of a complex Hermitian matrix using LAPACK's `zheev`
398/// (simple driver for full diagonalization).
399///
400/// # Parameters
401///
402/// - `x`: the input Hermitian matrix.
403/// - `uplo`: whether the upper or lower triangle of `x` is stored.
404///
405/// # Returns
406///
407/// `Array1<f64>` of all eigenvalues.
408///
409/// # Panics
410///
411/// Panics if `zheev` returns a non-zero info code.
412pub fn eigvalsh_v<S>(x: &ArrayBase<S, Ix2>, uplo: UPLO) -> Array1<f64>
413where
414    S: Data<Elem = Complex<f64>>,
415{
416    let n = x.shape()[0] as i32;
417    let mut a: Vec<_> = x.iter().cloned().collect();
418    let mut w = vec![0.0; n as usize];
419    let _m = 0;
420    let mut info = 0;
421    // Workspace query
422    let mut work = vec![Complex::new(0.0, 0.0); 1 as usize];
423    let mut rwork = vec![0.0; (3 * n - 2) as usize];
424    let job1 = b'N'; // eigenvalues only
425    let job2 = match uplo {
426        UPLO::Upper => b'U',
427        UPLO::Lower => b'L',
428    };
429
430    unsafe {
431        zheev(
432            job1, job2, n, &mut a, n, &mut w, &mut work, -1, &mut rwork, &mut info,
433        );
434    }
435    let lwork = work[0].re as i32;
436    work = vec![Complex::new(0.0, 0.0); lwork as usize];
437
438    unsafe {
439        zheev(
440            job1, job2, n, &mut a, n, &mut w, &mut work, lwork, &mut rwork, &mut info,
441        );
442    }
443    if info == 0 {
444        Array1::<f64>::from_vec(w.into_iter().collect())
445    } else {
446        panic!("zheev failed with info = {}", info);
447    }
448}