Package: pygensvd
pygensvd.pyAn updated version of the original pygsvd package by Benjamin Naecker. This version
uses cmake for compilation rather than distutils, but only supports openblas as a backend (for now).A Python wrapper to the LAPACK generalized singular value decomposition.(C) 2017 Benjamin Naeckerbnaecker@fastmail.comOverviewThepygsvdmodule exports a single functiongsvd, which computes the
generalized singular value decomposition (GSVD) of a pair of matrices,AandB. TheGSVDis a joint decomposition useful for computing regularized solutions
to ill-posed least-squares problems, as well as dimensionality reduction
and clustering.Thepygsvdmodule is very simple: it just wraps the underlying LAPACK
routineggsvd3, both the double-precision (dggsvd3) and complex-double
precision versions (zggsvd3).BuildingBecause thepygsvdmodule wraps a LAPACK routine itself, it is provided
as a Python and NumPy extension module. The module must be compiled,
and doing so requires a LAPACK header and a shared library. The module
currently supports both the standard C bindings to LAPACK (calledLAPACKE),
and those provided by Intel's Math Kernel Library. Notably it doesnotsupport Apple's Accelerate framework, which seems to be outdated and
differs in several subtle and annoying ways.You can build against either of the supported implementations, by editing
thesetup.cfgfile. Set thedefine=line in the file to be one ofUSE_LAPACK(the default) orUSE_MKL.You must also add the include and library directories for these. The
build process already searches/usr/local/{include,lib}, but if these
don't contain the header and library, add the directory containing these
to theinclude_dirs=andlibrary_dirs=line. Multiple directories are
separated by a:. You can also set these on the command line when building.For example, to use the LAPACK library, with a header in/some/dir/and the library in/some/libdir/, you could run:$ python3 setup.py build_ext --include-dirs="/some/dir" --library-dirs="/some/libdir"Then you can install the module either as usual or in develop mode as:$ python3 setup.py {install,develop}Or viapipas:$ pip3 install .UsageThe GSVD of a pair of NumPy ndarraysaandbcan be computed as:>>> c, s, x = pygsvd.gsvd(a, b)This returns the generalized singular values, in arrayscands, and the
right generalized singular vectors inx. Optionally, the transformation matricesuandv` may also be computed. E.g.:>>> c, s, x, u = pygsvd.gsvd(a, b, extras='u')also returns the left generalized singular vectors ofa.By default, the matricesuandv, if returned, are of shape(m, n)and(p, n). Using the optional argumentfull_matricesis set toTrue, then
the matrices are square, of shape(m, m)and(p, p).The generalized singular value decompositionThe GSVD is a joint decomposition of a pair of matrices. Given matricesAwith shape(m, n)andBwith shape(p, n), it computes:A = U*C*X.T
    B = V*S*X.TwhereUandVare unitary matrices, with shapes(m, m)and(p, p),
andXis shaped as(n, n), respectively.CandSare diagonal (possibly non-square)
matrices containing the generalized singular value pairs.This decomposition has many uses, including least-squares fitting of ill-posed
problems. For example, lettingBbe the "second derivative" operator one can
solve the equationmin_x ||Ax - b||^2 + \lambda ||Bx||^2using the GSVD, which achieves a smoother solution as\lambdais increased.
Similarly, settingBto the identity matrix, this becomes the standard
ridge regression problem. These are both versions of the Tichonov regularization
problem, for which the GSVD provides a useful and efficient solution.