Package: raleigh
RALEIGH: RAL EIGensolver for real symmetric and Hermitian problemsRALEIGH is a Python implementation of the block Jacobi-conjugated gradients algorithm for computing several eigenpairs (eigenvalues and corresponding eigenvectors) of large scale real symmetric and Hermitian problems.Key featuresCan be applied to both standard eigenvalue problem for a real symmetric or Hermitian matrix A and generalized eigenvalue problems for matrix pencils A - λ B or A B - λ I with positive definite real symmetric or Hermitian B.Can employ either of the two known convergence improvement techniques for large sparse problems: shift-and-invert and preconditioning.Can also compute singular values and vectors, and is actually an efficient tool for Principal Component Analysis (PCA) of dense data of large size, owing to the high efficiency of matrix multiplications on modern multicore and GPU architectures.PCA capabilities include quick update of principal components after arrival of new data and incremental computation of principal components, dealing with one chunk of data at a time.For sparse matrices of large size (~100K or larger), RALEIGH'spartial_hevpeigensolver is much faster thaneigshfrom SciPy. The table below shows the computation times in seconds for computing the smallest eigenvalue of 3 matrices from DNVS group of Suitesparse Matrix Collection and the smallest buckling load factor of 4 buckling problems on Intel(R) Xeon(R) CPU E3-1220 v3 @ 3.10GHz (the links to matrices' repositories can be found insparse_evp.pyandbuckling_evp.pyin subfolderraleigh/examples).matrixsizeeigshpartial_hevpshipsec11408742406.9shipsec51798603185.3x1041083842255.2panel_buckle_d74383261.4panel_buckle_e144823852.5panel_buckle_f2245221353.8panel_buckle_g3949623217.2Similarly, for large data (~10K samples with ~10K features or larger) that has large amount of redundancy, RALEIGH'spcafunction is considerably faster thanfit_ransformmethod of scikit-learn and uses less memory. The next table shows the computation times for PCA of images obtained by processing images from Labeled Faces in the Wild (background outside face area erased, mirror images added etc. - seeraleigh/examples/eigenimages/convert_lfw.pyfor the link to Labeled Faces in the Wild images and to Dropbox folder containing the filelfwdf_wmi_175x225_fa_12K.npywith 12K processed images used in the reported comparison).componentsscikit-learnraleigh (CPU)raleigh (GPU)80059231090065251110006827121100762913If the number of eigenvalues needed is not known in advance (as is normally the case with PCA), the computation will continue until user-specified stopping criteria are satisfied (e.g. PCA approximation to the data is satisfactory).The core solver allows user to specify the number of wanted eigenvalueson either margin of the spectrum (e.g. 5 on the left, 10 on the right)of largest magnitudeon either side of a given real valuenearest to a given real valueThe core solver is written in terms of abstract vectors, owing to which it will work on any architecture verbatim, as long as basic linear algebra operations on vectors are implemented. Currently, MKL and CUBLAS implementations are provided with the package, in the absence of these libraries NumPy algebra being used.DependenciesFor best performance, install MKL 10.3 or later. On Linux, the latest MKL can be installed bypip install --user mkl. On Windows, one can alternatively install numpy+mkl. If MKL is installed in any other way, make sure that, on Linux, the folder containinglibmkl_rt.sois listed inLD_LIBRARY_PATH, and, on Windows, the one containingmkl_rt.dllis listed inPATH. If you do not know how to do it, then putfrom raleigh.algebra import envin your script and setenv.mkl_pathto that folder. Large sparse problems can only be solved if MKL is available, PCA and other dense problems can be tackled without it.To use GPU (which must be CUDA-enabled), NVIDIA GPU Computing Toolkit needs to be installed. On Linux, the folder containinglibcudart.somust be listed inLD_LIBRARY_PATH. At present, GPU can only be used for dense (SVD-related) problems.Package structureBasic use subpackagesSubpackageinterfacescontains user-friendly SciPy-like interfaces to core solver working in terms of NumPy and SciPy data objects. Subpackageexamplescontains scripts illustrating their use, as well as a script illustrating basic capabilities of the core solver.Advanced use subpackagesSubpackagealgebracontains NumPy, MKL and CUBLAS implementations of abstract vectors algebra. These can be used as templates for user's own implementations. Subpackagecorecontains the core solver implementation and related data objects definitions.Basic usageTo compute 10 eigenvalues closest to 0.25 of a sparse real symmetric or Hermitian matrixAin SciPy format:from raleigh.interfaces.partial_hevp import partial_hevp
lmd, x, status = partial_hevp(A, which=10, sigma=0.25)
# lmd : eigenvalues
# x : eigenvectors
# status : execution statusTo compute 10 smallest eigenvalues of a sparse positive definite real symmetric or Hermitian matrixAusing its incomplete LU-factorization as the preconditioner:from raleigh.interfaces.partial_hevp import partial_hevp
from raleigh.algebra.sparse_mkl import IncompleteLU as ILU
T = ILU(A)
T.factorize()
lmd, x, status = partial_hevp(A, which=10, T=T)To compute 10 lowest buckling load factors α of the buckling problem (K + α Ks)v = 0 with stiffness matrix K and stress stiffness matrix Ks using load factor shift 1.0:from raleigh.interfaces.partial_hevp import partial_hevp
alpha, v, status = partial_hevp(K, Ks, buckling=True, sigma=-1.0, which=10)To compute 100 principal components for the dataset represented by the 2D matrixAwith data samples as rows:from raleigh.interfaces.pca import pca
mean, trans, comps = pca(A, npc=100)
# mean : the average of data samples
# trans : transformed (reduced features) data set
# comps : the matrix with principal components as rowsTo compute a number of principal components sufficient to approximateAwith 5% tolerance to the relative PCA error (the ratio of the Frobenius norm oftrans*comps - A_sto that ofA_s, where the rows ofA_sare the original data samples shifted bymean):mean, trans, comps = pca(A, tol=0.05)To quickly updatemean,transandcompstaking into account new dataA_new:mean, trans, comps = pca(A_new, have=(mean, trans, comps))To compute 5% accuracy PCA approximation incrementally by processing 1000 data samples at a time:mean, trans, comps = pca(A, tol=0.05, batch_size=1000)DocumentationDocumenting RALEIGH is stillwork in progressat the moment due to the large size of the package and other commitments of the author. Basic usage of the package is briefly described in the docstrings of modules ininterfacesandexamples. Advanced users will find the description of basic principles of RALEIGH's design incoremodulesolver.The mathematical and numerical aspects of the algorithm implemented by RALEIGH are described in the papers by E. E. Ovtchinnikov inJ. Comput. Phys. 227:9477-9497andSIAM Numer. Anal. 46:2567-2619. A Fortran90 implementation of this algorithm was used in a paper on Topology Optimization by P.D. Dunning, E. Ovtchinnikov, J. Scott and H.A. Kim inInternational Journal for Numerical Methods in Engineering 107 (12), 1029-1053(the four buckling problems mentioned above were used for the performance testing and comparisons with ARPACK). A pre-release version of RALEIGH was used in a paper by A. Liptak, G. Burca, J. Kelleher, E. Ovtchinnikov, J. Maresca and A. Horner inJournal of Physics Communications 3 (11), 113002.FeedbackPlease useGitHub issue trackeror send an e-mail to Evgueni to report bugs and request features.LicenseRALEIGH is released under 3-clause BSD licence.