|
fortran-lapack
|
This package provides precision-agnostic, high-level linear algebra APIs for real and complex arguments in Modern Fortran. The APIs are similar to NumPy/SciPy operations, and leverage a Modern Fortran implementation of the Reference-LAPACK library.
A full and standardized implementation of the present library has been integrated into the Fortran Standard Library, and as such, most users should seek to access the functionality from stdlib. The present library is kept in place for those who seek a compact implementation of it.
sp (32-bit) and dp (64-bit) are always built. The wider kinds are fpm features, so a build pays only for the precisions it asks for:
| feature | kind | BLAS/LAPACK initials | in the default profile |
|---|---|---|---|
quad | qp, 128-bit | q real, w complex | yes |
xdp | xdp, 80-bit extended | x real, y complex | no |
quad is part of the default profile, so fpm build, --profile debug and --profile release carry sp, dp and qp, as every earlier release did. The named profiles select the other combinations:
80-bit extended precision is a property of x86 hardware rather than of the language: on aarch64 selected_real_kind(18) returns the 128-bit kind, so a build that asks for xdp there stops in la_constants instead of compiling a second copy of the quadruple-precision code.
From a consumer's manifest:
features = [...] replaces the default set instead of adding to it, so a consumer that wants xdp as well as qp lists both.
la_constants declares sp, dp, xdp and qp whether or not the build carries them: a kind left out is -1, so use la_constants, only: qp keeps compiling. The logical parameters la_with_qp and la_with_xdp say which of the two are real.
Outside fpm, the same choice is made with the preprocessor: the generated sources under src/ are .F90, the tests under test/ carry cpp directives too, so the whole tree wants -cpp, with -DLA_WITH_QP for quadruple precision and -DLA_WITH_XDP for extended precision.
All procedures work with all types (real, complex) and kinds (32, 64, 128-bit floats, and the 80-bit extended floats of the xdp feature).
The subroutines are pure and take an optional err argument: without it, an error stops execution. A function that can fail has two forms: without err it is pure, takes its matrices as intent(in), and stops with error stop on an error; with err it returns the error state instead, and is not pure, since a pure function cannot have an intent(out) argument. An err that is itself an absent optional argument cannot be passed to the second form. The operators .inv., .det. and .pinv. are pure forms, and stop on an error.
c = chol(a [, lower] [, other_zeroed]) c = chol(a [, lower] [, other_zeroed], err)
This function computes the Cholesky factorization of a real symmetric or complex Hermitian matrix \( A \):
\[A = L L^T = U^T U \]
where \( L \) is a lower triangular matrix and \( U \) is an upper triangular matrix. The function returns the factorized matrix as a new allocation, without modifying the input matrix. Without err it is pure; with err it returns errors instead of stopping, and is not pure.
a: A real or complex matrix of size \( [n,n] \), representing the symmetric/Hermitian input matrix.lower (optional): A logical flag indicating whether the lower ( \( L \)) or upper ( \( U \)) triangular factor should be computed. Defaults to lower = .true..other_zeroed (optional): A logical flag determining whether the unused half of the returned matrix should be explicitly zeroed. Defaults to other_zeroed = .true..err (optional): A type(la_state) variable that receives the error state.c: A real or complex matrix of size \( [n,n] \), containing the Cholesky factors. The returned matrix is triangular (upper or lower, as selected).err is not present, exceptions trigger an error stop.call cholesky(a [, c] [, lower] [, other_zeroed])
This subroutine computes the Cholesky factorization of a real symmetric or complex Hermitian matrix \( A \):
\[A = L L^T = U^T U \]
where \( L \) is a lower triangular matrix and \( U \) is an upper triangular matrix. The factorization is performed in-place, modifying the input matrix a, or on a pre-allocated matrix c with the same type and kind as a.
a: A real or complex matrix of size \( [n,n] \), representing the symmetric/Hermitian input matrix. if c is not provided, on return it contains the Cholesky factorization.c (optional): A matrix of size \( [n,n] \), of the same type and kind as a, containing the Cholesky factorization. If provided, a is unchanged.lower (optional): A logical flag indicating whether the lower ( \( L \)) or upper ( \( U \)) triangular factor should be computed. Defaults to lower = .true..other_zeroed (optional): A logical flag determining whether the unused half of the matrix should be explicitly zeroed. Defaults to other_zeroed = .true..error stop.call eig(a [, b] [, lambda] [, right] [, left] [, overwrite_a] [, overwrite_b] [, err])
This interface provides methods for computing the eigenvalues and eigenvectors of a real or complex matrix. It supports both standard and generalized eigenvalue problems, allowing for the decomposition of a matrix A alone or a pair of matrices (A, B) in the generalized case.
Given a square matrix \( A \), this routine computes its eigenvalues \( \lambda \) and, optionally, its right or left eigenvectors:
\[A v = \lambda v \]
where \( v \) represents an eigenvector corresponding to eigenvalue \( \lambda \).
In the generalized eigenvalue problem case, the routine solves:
\[A v = \lambda B v \]
The computation supports both real and complex matrices. If requested, eigenvectors are returned as additional output arguments. The function provides options to allow in-place modification of A and B for performance optimization.
Note: The solution is based on LAPACK's GEEV and GGEV routines.
a: A real or complex matrix of size \([n,n]\), representing the input matrix to be decomposed.b (optional): A real or complex matrix of size \([n,n]\), same type and kind as a, representing the second matrix in the generalized eigenvalue problem.lambda: A complex or real array of length \( n \), containing the computed eigenvalues.right (optional): A complex matrix of size \([n,n]\) containing the right eigenvectors as columns.left (optional): A complex matrix of size \([n,n]\) containing the left eigenvectors as columns.overwrite_a (optional): A logical flag indicating whether A can be overwritten for performance optimization.overwrite_b (optional): A logical flag indicating whether B can be overwritten (only in the generalized case).err (optional): A type(la_state) variable to handle errors. If not provided, execution will stop on errors.err is not provided, exceptions will trigger an error stop.A or B can improve performance but destroys the original matrix data.pure.call eigh(a, lambda [, vectors] [, upper_a] [, overwrite_a] [, err])
This interface provides methods for computing the eigenvalues and optionally the eigenvectors of a real symmetric or complex Hermitian matrix.
Given a real symmetric or complex Hermitian matrix \( A \), this routine computes its eigenvalues \( \lambda \) and, optionally, its right eigenvectors:
\[A v = \lambda v \]
where \( v \) represents an eigenvector corresponding to eigenvalue \( \lambda \).
The computation supports both real and complex matrices, and the eigenvectors, if requested, are returned as orthonormal vectors.
Note: The solution is based on LAPACK's SYEVD and HEEVD routines.
a: A real or complex matrix of size \([n,n]\), representing the input matrix to be decomposed. The matrix is overwritten with the eigenvalues on output.lambda: A real array of length \( n \), with the same kind as a, containing the computed eigenvalues.vectors (optional): A matrix of size \([n,n]\), with the same type and kind as a, containing the right eigenvectors stored as columns.overwrite_a (optional): A logical flag indicating whether the matrix A can be overwritten for performance optimization.upper_a (optional): A logical flag indicating whether the upper half of matrix A should be used for computation (default is the lower half).err (optional): A type(la_state) variable to handle errors. If not provided, execution will stop on errors.err is not provided, exceptions will trigger an error stop.A can improve performance but destroys the original matrix data.pure.lambda = eigvals(a [, b] [, err])
This interface provides methods for computing the eigenvalues of a real or complex square matrix. It supports both standard and generalized eigenvalue problems.
In the standard eigenvalue problem, the function computes the eigenvalues \(\lambda\) of the matrix \(A\) such that:
\[A v = \lambda v \]
where \(v\) is the eigenvector corresponding to eigenvalue \(\lambda\).
In the generalized eigenvalue problem, the function solves:
\[A v = \lambda B v \]
where \(A\) and \(B\) are the input matrices and \(\lambda\) is the eigenvalue.
The function returns an array of eigenvalues computed for the input matrix \(A\), and optionally the matrix \(B\) for the generalized case.
Note: The solution is based on LAPACK's GEEV and GGEV routines.
a: A real or complex matrix of size \([n,n]\), representing the input matrix to be decomposed.b (optional, generalized case): A matrix of size \([n,n]\) and same type and kind as a, representing the second matrix in the generalized eigenvalue problem.err (optional): A type(la_state) variable to handle errors. If not provided, execution will stop on errors.lambda: A complex array of eigenvalues, computed from the input matrix \(A\) (and \(B\) if in the generalized case).err is not provided, exceptions will trigger an error stop.err is pure, so it can be used inside pure procedures and do concurrent blocks.lambda = eigvalsh(a [, upper_a] [, err])
This interface provides methods for computing the eigenvalues of a real symmetric or complex Hermitian matrix. The function computes the eigenvalues of the matrix \(A\), and returns them in an array. The user can specify whether to use the upper or lower half of the matrix for computation.
The function solves the eigenvalue problem:
\[A v = \lambda v \]
where \(v\) is the eigenvector corresponding to eigenvalue \(\lambda\).
real values.The user can specify whether to use the upper or lower half of the matrix \(A\) for the computation (default: lower half).
Note: The solution is based on LAPACK's SYEV and HEEV routines.
a: A real or complex matrix of size \([n,n]\), representing the real symmetric or complex Hermitian matrix to be decomposed.upper_a (optional): A logical flag indicating whether to use the upper half (.true.) or the lower half (.false.) of \(A\) for the computation. The default is lower.err (optional): A type(la_state) variable to handle errors. If not provided, execution will stop on errors.lambda: A real array containing the computed eigenvalues of the matrix \(A\).err is not provided, execution will stop on errors.real array, with the same kind as the input matrix a.err is pure, so it can be used inside pure procedures and do concurrent blocks.x = solve(a, b)
x = solve(a, b [, overwrite_a], err)
Solve linear systems - one (b(:)) or many (b(:,:)).
Without err the function is pure and takes a as intent(in); with err it returns errors instead of stopping, is not pure, and can overwrite a.
a: A real or complex coefficient matrix. If overwrite_a=.true., it is destroyed by the call.b: A rank-1 (one system) or rank-2 (many systems) array of the same kind as a, containing the right-hand-side vector(s).overwrite_a (optional, default = .false., with err only): If .true., input matrix a will be used as temporary storage and overwritten, to avoid internal data allocation.err (optional): A type(la_state) variable that receives the error state.For a full-rank matrix, returns an array value that represents the solution to the linear system of equations. With err, a failed solve returns an empty array.
err is not present, exceptions trigger an error stop.call solve_lu(a, b, x [, pivot] [, overwrite_a] [, err])
Solve linear systems - one (b(:)) or many (b(:,:)) - writing the result into the caller's array x instead of returning a new one. Storage for the pivot indices may be supplied as well: when x and pivot are both provided and overwrite_a=.true., the call performs no internal allocation, which makes it suited to a loop over many systems of the same size. The routine is pure.
a: A real or complex coefficient matrix of size \( [n,n] \). If overwrite_a=.true., it is destroyed by the call.b: A rank-1 (one system) or rank-2 (many systems) array of the same kind as a, containing the right-hand-side vector(s).x: An array of the same shape and kind as b. On output it holds the solution.pivot (optional): An integer(ilp) array of size n that receives the diagonal pivot indices of the LU factorization.overwrite_a (optional, default = .false.): If .true., input matrix a will be used as temporary storage and overwritten, to avoid internal data allocation.err (optional): A type(la_state) variable.a, b, x or pivot have invalid/incompatible sizes.err is not present, exceptions trigger an error stop.x.call solve_chol(a, b, x [, lower] [, overwrite_a] [, err])
Factorize a real symmetric or complex Hermitian positive definite matrix and solve \( A x = b \) in one call, for one (b(:)) or many (b(:,:)) right-hand sides. Only the triangle lower selects is read. The result is written into the caller's array x. The routine is pure.
a: A real symmetric or complex Hermitian positive definite matrix of size \( [n,n] \). If overwrite_a=.true., it is overwritten with its Cholesky factor.b: A rank-1 (one system) or rank-2 (many systems) array of the same kind as a, containing the right-hand-side vector(s).x: An array of the same shape and kind as b. On output it holds the solution.lower (optional, default = .true.): If .true., the lower triangle of a is read and the factorization is \( A = L L^H \); otherwise the upper triangle is read and the factorization is \( A = U^H U \).overwrite_a (optional, default = .false.): If .true., input matrix a will be used as temporary storage and overwritten, to avoid internal data allocation.err (optional): A type(la_state) variable.a is not positive definite.a, b or x have invalid/incompatible sizes.err is not present, exceptions trigger an error stop.call solve_lower_chol(l, b, x [, err])
call solve_upper_chol(u, b, x [, err])
Solve \( A x = b \) for one or many right-hand sides from a Cholesky factor computed earlier, without factorizing again. Each call costs two triangular solves. Both routines are pure.
l / u: The lower or upper Cholesky factor of size \( [n,n] \), as returned by cholesky with lower=.true. or lower=.false..b: A rank-1 (one system) or rank-2 (many systems) array of the same kind as the factor, containing the right-hand-side vector(s).x: An array of the same shape and kind as b. On output it holds the solution.err (optional): A type(la_state) variable.b or x have invalid/incompatible sizes.err is not present, exceptions trigger an error stop.x = lstsq(a, b [, cond])
x = lstsq(a, b [, cond] [, overwrite_a] [, rank], err)
Solves the least-squares problem for the system \( A \cdot x = b \), where \( A \) is a square matrix of size \( n \times n \) and \( b \) is either a vector of size \( n \) or a matrix of size \( n \times nrhs \). The function minimizes the 2-norm \( \|b - A \cdot x\| \) by solving for \( x \).
The result \( x \) is returned as an allocatable array, and it is either a vector (for a single right-hand side) or a matrix (for multiple right-hand sides).
Without err the function is pure and takes a as intent(in); with err it returns errors instead of stopping, is not pure, can overwrite a, and can return the rank.
a: A real matrix of size \( n \times n \) representing the coefficient matrix. If overwrite_a = .true., the contents of a may be modified during the computation.b: A real vector or matrix representing the right-hand side. The size should be \( n \) (for a single right-hand side) or \( n \times nrhs \) (for multiple right-hand sides).cond (optional): A cutoff for rank evaluation. Singular values \( s(i) \) such that \( s(i) \leq \text{cond} \cdot \max(s) \) are considered zero.overwrite_a (optional, default = .false., with err only): If .true., both a and b may be overwritten and destroyed during computation.rank (optional, with err only): An integer variable that returns the rank of the matrix \( A \).err (optional): A type(la_state) variable that returns the error state. If err is not provided, the function will stop execution on error.Returns the solution array \( x \) with size \( n \) (for a single right-hand side) or \( n \times nrhs \) (for multiple right-hand sides). With err, an invalid problem returns an empty array.
a and the right-hand side b have incompatible sizes.err is not provided, the function stops execution on error.overwrite_a is enabled, the original contents of a and b may be lost.call lstsq_space(a, b, lrwork, liwork) for real data call lstsq_space(a, b, lrwork, liwork, lcwork) for complex data
This subroutine returns the sizes of the working arrays that solve_lstsq needs for a problem of the shape of a and b, so that a repeated solve of problems of the same size performs no internal allocation.
a: A real or complex matrix of size \( [m,n] \). Only its shape is read.b: A right-hand-side vector of size \(m\) or matrix of size \( [m,nrhs] \). Only its shape is read.lrwork: An integer returning the size of the real working array.liwork: An integer returning the size of the integer working array.lcwork: An integer returning the size of the complex working array. Complex data only.The three (two, for real data) workspace sizes are returned in the output arguments.
pure and cannot fail: it reads the shapes of its inputs and nothing else.call solve_lstsq(a, b, x [, real_storage] [, int_storage] [, cmpl_storage] [, cond] [, singvals] [, overwrite_a] [, rank] [, err])
This subroutine computes the least-squares solution of \( A \cdot x = b \) and writes it into the caller's array. Given the optional working arrays, it allocates nothing, so a repeated solve of problems of the same size runs without any memory traffic.
a: A real or complex matrix of size \( [m,n] \). It is an intent(inout) argument, and is destroyed if overwrite_a is true.b: The right-hand-side vector of size \(m\) or matrix of size \( [m,nrhs] \). It is an intent(in) argument.x: The solution vector of size \( \ge n \) or matrix of size \( [\ge n,nrhs] \). It is an intent(inout) contiguous argument.real_storage (optional): A real working array of size at least the lrwork returned by lstsq_space.int_storage (optional): An integer working array of size at least liwork.cmpl_storage (optional): A complex working array of size at least lcwork. Complex data only.cond (optional): The cutoff for rank evaluation: singular values \( s_i \le \text{cond} \cdot \max(s) \) are treated as zero.singvals (optional): A real array of size at least \( \min(m,n) \) returning the singular values in decreasing order.overwrite_a (optional): If true, a may be overwritten and destroyed. Default is false.rank (optional): An integer returning the rank of a.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the subroutine will stop execution.The solution is written into x.
x is too small, or if a working array is too small.err is not provided, the subroutine will stop execution on errors.lstsq is this subroutine with the solution allocated for the caller.pure.x = weighted_lstsq(w, a, b [, cond])
x = weighted_lstsq(w, a, b [, cond] [, overwrite_a] [, rank], err)
This function minimizes \( \|D (b - A \cdot x)\| \) with \( D = \mathrm{diag}(\sqrt{w}) \): the \(i\)-th equation carries the weight \( w_i \). Both sides are scaled and the resulting ordinary least-squares problem is solved with GELSD. Without err the function is pure and takes a as intent(in); with err it returns errors instead of stopping, is not pure, can overwrite a, and can return the rank.
w: A real vector of size \(m\). The weights are always real and must all be positive.a: A real or complex matrix of size \( [m,n] \). With err it is an intent(inout) argument, and is destroyed if overwrite_a is true; without err it is intent(in).b: The right-hand-side vector of size \(m\). It is an intent(in) argument.cond (optional): The cutoff for rank evaluation.overwrite_a (optional, with err only): If true, a may be overwritten and destroyed. Default is false.rank (optional, with err only): An integer returning the rank of a.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the function will stop execution.The function returns the solution vector of size \(n\).
w or b does not have one entry per row of a, or if any weight is not positive.err is not provided, the function will stop execution on errors.lstsq.call solve_weighted_lstsq(w, a, b, x [, cond] [, overwrite_a] [, rank] [, err])
This subroutine is the subroutine form of weighted_lstsq: it writes the solution into the caller's array instead of allocating it.
w: A real vector of size \(m\) of positive weights.a: A real or complex matrix of size \( [m,n] \). It is an intent(inout) argument, and is destroyed if overwrite_a is true.b: The right-hand-side vector of size \(m\). It is an intent(in) argument.x: The solution vector of size \(n\). It is an intent(inout) contiguous argument.cond (optional): The cutoff for rank evaluation.overwrite_a (optional): If true, a may be overwritten and destroyed. Default is false.rank (optional): An integer returning the rank of a.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the subroutine will stop execution.The solution is written into x.
w or b does not have one entry per row of a, or if any weight is not positive.err is not provided, the subroutine will stop execution on errors.a unless overwrite_a is set, so a is unchanged by default.pure.x = constrained_lstsq(a, b, c, d)
x = constrained_lstsq(a, b, c, d [, overwrite_matrices], err)
This function minimizes \( \|b - A \cdot x\| \) subject to \( C \cdot x = d \), with \( A \) of size \( [m,n] \) and \( C \) of size \( [p,n] \). The problem has a unique solution when \( p \le n \le m+p \), \( \mathrm{rank}(C) = p \) and the stacked matrix has rank \( n \). Without err the function is pure and takes a, b, c and d as intent(in); with err it returns errors instead of stopping, is not pure, and can overwrite them.
a: A real or complex matrix of size \( [m,n] \), the least-squares cost. With err it is an intent(inout) argument, and is destroyed if overwrite_matrices is true; without err, a, b, c and d are intent(in).b: The least-squares right-hand-side vector of size \(m\). It is an intent(inout) argument with err.c: The constraint matrix of size \( [p,n] \). It is an intent(inout) argument with err.d: The constraint right-hand-side vector of size \(p\). It is an intent(inout) argument with err.overwrite_matrices (optional, with err only): If true, a, b, c and d may be overwritten and destroyed. Default is false.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the function will stop execution.The function returns the solution vector of size \(n\).
c is rank deficient or if the stacked matrix is.err is not provided, the function will stop execution on errors.call solve_constrained_lstsq(a, b, c, d, x [, storage] [, overwrite_matrices] [, err])
This subroutine is the subroutine form of constrained_lstsq: it writes the solution into the caller's array and can reuse a caller-provided workspace.
a: A real or complex matrix of size \( [m,n] \), the least-squares cost. It is an intent(inout) argument.b: The least-squares right-hand-side vector of size \(m\). It is an intent(inout) argument.c: The constraint matrix of size \( [p,n] \). It is an intent(inout) argument.d: The constraint right-hand-side vector of size \(p\). It is an intent(inout) argument.x: The solution vector of size \(n\). It is an intent(out) argument.storage (optional): A working array of size at least the lwork returned by constrained_lstsq_space.overwrite_matrices (optional): If true, a, b, c and d may be overwritten and destroyed. Default is false.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the subroutine will stop execution.The solution is written into x.
storage is too small.c is rank deficient or if the stacked matrix is.err is not provided, the subroutine will stop execution on errors.overwrite_matrices, all four inputs are copied, so none of them is changed.pure.call constrained_lstsq_space(a, c, lwork [, err])
This subroutine asks LAPACK for the optimal size of the workspace array that solve_constrained_lstsq needs for a problem of the shape of a and c.
a: A real or complex matrix of size \( [m,n] \). Only its shape is read.c: The constraint matrix of size \( [p,n] \). Only its shape is read.lwork: An integer returning the size of the workspace array.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the subroutine will stop execution.err is not provided, the subroutine will stop execution on errors.pure.x = generalized_lstsq(w, a, b [, prefactored_w])
x = generalized_lstsq(w, a, b [, prefactored_w], err)
This function minimizes \( (b - A \cdot x)^H W^{-1} (b - A \cdot x) \), the least-squares cost of observations whose errors are correlated, with the symmetric (Hermitian) positive definite covariance matrix \( W \). Without err it is pure; with err it returns errors instead of stopping, and is not pure.
w: The covariance matrix of size \( [m,m] \), of the same type and kind as a. If prefactored_w is true, it is instead a square root \( B \) of the covariance matrix, \( W = B B^H \), which need not be triangular. It is not modified.a: A real or complex matrix of size \( [m,n] \), with \( m \ge n \). It is not modified.b: The right-hand-side vector of size \(m\). It is not modified.prefactored_w (optional): If true, w is a square root of the covariance matrix, for example its Cholesky factor. Default is false.err (optional): A type(la_state) variable that receives the error state.The function returns the solution vector of size \(n\). With err, a failed solve returns an empty vector.
a is empty or has fewer rows than columns, or if w or b does not match the rows of a.w is not positive definite, if its square root is singular, or if a does not have full column rank.err is not present, exceptions trigger an error stop.prefactored_w, \( B \) is the Cholesky factor of w.lstsq.call solve_generalized_lstsq(w, a, b, x [, storage] [, prefactored_w] [, overwrite_a] [, overwrite_w] [, err])
This subroutine is the subroutine form of generalized_lstsq: it writes the solution into the caller's array, can reuse a caller-provided workspace, and can work on w and a in place.
w: The covariance matrix of size \( [m,m] \), or a square root of it if prefactored_w is true. It is an intent(inout) argument, and is destroyed if overwrite_w is true.a: A real or complex matrix of size \( [m,n] \), with \( m \ge n \). It is an intent(inout) argument, and is destroyed if overwrite_a is true.b: The right-hand-side vector of size \(m\). It is an intent(in) argument.x: The solution vector of size \(n\). It is an intent(out) argument.storage (optional): A working array of size at least the lwork returned by generalized_lstsq_space.prefactored_w (optional): If true, w is a square root of the covariance matrix. Default is false.overwrite_a (optional): If true, a may be overwritten and destroyed. Default is false.overwrite_w (optional): If true, w may be overwritten and destroyed. Default is false.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the subroutine will stop execution.The solution is written into x.
storage is too small.w is not positive definite, if its square root is singular, or if a does not have full column rank.err is not provided, the subroutine will stop execution on errors.overwrite_a and overwrite_w, both matrices are copied, so neither is changed. With both, and with storage, the subroutine allocates nothing.pure.call generalized_lstsq_space(a, lwork [, err])
This subroutine returns the size of the workspace array that solve_generalized_lstsq needs for a problem of the shape of a: the optimal workspace of LAPACK's GGGLM, plus two vectors of size \(m\).
a: A real or complex matrix of size \( [m,n] \). Only its shape is read.lwork: An integer returning the size of the workspace array.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the subroutine will stop execution.a has fewer rows than columns.err is not provided, the subroutine will stop execution on errors.pure.d = det(a)
d = det(a [, overwrite_a], err)
This function computes the determinant of a square matrix \( A \). The matrix must be a real matrix of size \( [m, n] \), and the determinant is computed using an efficient factorization method (e.g., LU decomposition). Without err the function is pure, takes a as intent(in), and is the function behind la_determinant::operator(.det.) "operator(.det.)"; with err it returns errors instead of stopping, is not pure, and can overwrite a.
a: A real matrix of size \( [m, n] \), representing the rectangular matrix for which the determinant is calculated. With err, it is an inout argument and may be modified during computation if overwrite_a is set.overwrite_a (optional, default = .false., with err only): A logical flag that determines whether the input matrix a can be overwritten. If .true., the matrix a may be destroyed and modified in place to save memory.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the function will stop execution.The function returns a real scalar value representing the determinant of the input matrix \( A \), with the same kind as \( A \).
a is not square.err is not provided, the function will stop execution on errors.overwrite_a is enabled, the input matrix a will be destroyed during the computation process.This operator computes the determinant of a square real or complex matrix \( A \) from its LU factorization: it is det(A) without err. It is pure, so it can be used inside pure procedures and do concurrent blocks; it takes no overwrite_a flag and never modifies its operand, which is copied internally.
A: A real or complex square matrix of size \( [n,n] \).A scalar of the same type and kind as A, holding its determinant.
err argument, so a non-square matrix triggers an error stop. A singular matrix is not an error: it returns 0.err argument instead.call slogdet(a, sign, logabsdet [, overwrite_a] [, err])
This subroutine computes the determinant of a real or complex square matrix as \( \det(A) = sign \cdot e^{logabsdet} \), from its LU factorization. The logarithm stays representable where the determinant itself would overflow or underflow, as it does for large matrices or for products of many small pivots.
a: A real or complex square matrix of size \( [n,n] \). It is an intent(inout) argument, and is overwritten by its LU factorization if overwrite_a is true.sign: A scalar of the same type and kind as a, returning the sign of the determinant: \( \pm 1 \) for a real matrix, a complex number of unit modulus for a complex one, and 0 for a singular matrix. It is an intent(out) argument.logabsdet: A real scalar of the kind of a, returning the natural logarithm of \( |\det(A)| \), and \( -\infty \) for a singular matrix. It is an intent(out) argument.overwrite_a (optional, default = .false.): If .true., a may be overwritten and destroyed.err (optional): A type(la_state) variable that returns the error state. If not provided, the subroutine will stop execution on error.a is not square.sign = 0 and logabsdet \( = -\infty \).err is not provided, exceptions trigger an error stop.pure.inv_a = inv(a)
inv_a = inv(a, err)
This function computes the inverse \( A^{-1} \) of a real or complex square matrix \( A \), provided that \( A \) is non-singular. Without err it is pure, and is the function behind la_inverse::operator(.inv.) "operator(.inv.)"; with err it returns errors instead of stopping, and is not pure. The inverse of a matrix is defined as:
\[A A^{-1} = A^{-1} A = I \]
where \( I \) is the identity matrix of the same size as \( A \). The inverse exists only if \( A \) is square and has full rank (i.e., all its singular values are nonzero).
The computation is performed using LU decomposition.
a: A real or complex square matrix of size \( [n,n] \), representing the matrix to be inverted.err (optional): A type(la_state) variable that returns the error state. If not provided, the function will stop execution on error.inv_a: A real or complex square matrix of size \( [n,n] \), representing the inverse of a. With err, an error returns an empty \( [0,0] \) matrix.a is singular.a has invalid size.err is not provided, exceptions will trigger an error stop.call invert(a [, pivot] [, err])
call invert(a, inva [, pivot] [, err])
This subroutine computes the inverse \( A^{-1} \) of a real or complex square matrix \( A \). The first form works in-place, modifying a directly; the second writes the inverse into a second matrix inva of the same shape and leaves a untouched. Both use the LU decomposition method via LAPACK's GETRF and GETRI routines.
Given a square matrix \( A \), the LU decomposition factorizes it as:
\[A = P L U \]
where:
The inverse is then obtained by solving \( A X = I \) using the LU factors.
a: A real or complex square matrix of size \( [n,n] \). In the in-place form it is replaced with its inverse \( A^{-1} \) on output; in the split form it is read only.inva (split form only): A matrix of the same shape and kind as a, which receives the inverse \( A^{-1} \).pivot (optional): An integer(ilp) array of size at least n that receives the diagonal pivot indices of the LU factorization. Supplying it avoids the internal allocation of the pivot array.err (optional): A type(la_state) variable that returns the error state. If not provided, the function will stop execution on error.a has invalid size, if inva does not match the shape of a, or if pivot is shorter than n.err is not provided, exceptions will trigger an error stop.a. If the original matrix needs to be preserved, use the split form or inv instead.a can be computed before inversion using det to check for singularity.pure.This operator computes the inverse \( A^{-1} \) of a square, non-singular real or complex matrix \( A \) using an LU decomposition. The inversion satisfies:
\[A A^{-1} = I \]
where \( I \) is the identity matrix of appropriate size.
This operator is inv(A) without err, with a more convenient syntax. It supports operator chaining, allowing multiple inversions within expressions.
A: A real or complex square matrix of size \( [n,n] \), representing the input matrix to be inverted.invA: A real or complex square matrix of size \( [n,n] \), and same kind as A representing its inverse. err, this operator does not provide explicit error handling.A is singular or an error occurs during inversion, execution stops.err argument instead.pure, so it can be used inside pure procedures and do concurrent blocks.pinva = pinv(a [, rtol])
pinva = pinv(a [, rtol], err)
This function computes the Moore-Penrose pseudo-inverse \( A^+ \) of a real or complex matrix \( A \) using Singular Value Decomposition (SVD). The pseudo-inverse provides a generalization of the inverse for non-square and singular matrices, making it useful for solving least-squares problems and underdetermined systems. Without err it is pure; with err it returns errors instead of stopping, and is not pure.
The computation is based on the singular value decomposition (SVD):
\[A = U \Sigma V^T \]
where \( U \) and \( V \) are orthogonal matrices, and \( \Sigma \) is a diagonal matrix containing the singular values. The pseudo-inverse is computed as:
\[A^+ = V \Sigma^+ U^T \]
where \( \Sigma^+ \) is obtained by inverting the nonzero singular values.
a: A real or complex matrix of size \( [m,n] \), representing the input matrix to be inverted.rtol (optional): A real scalar specifying the relative tolerance for singular value truncation. Singular values smaller than rtol * max(singular_values(A)) are set to zero. If not provided, a default machine-precision-based tolerance is used.err (optional): A type(la_state) variable that returns the error state. If not provided, the function will stop execution on error.pinva: A real or complex matrix of size \( [n,m] \), representing the pseudo-inverse of a.err is not provided, exceptions will trigger an error stop.*GESVD.rtol affects numerical stability and rank estimation: setting it too high may result in an inaccurate inverse, while setting it too low may amplify numerical noise.pseudoinvert.pinva = .pinv. a
This operator computes the Moore-Penrose pseudo-inverse \( A^+ \) of a real or complex matrix \( A \) using Singular Value Decomposition (SVD). The pseudo-inverse is useful for solving least-squares problems and handling singular or underdetermined systems.
Given the singular value decomposition (SVD):
\[A = U \Sigma V^T \]
the pseudo-inverse is computed as:
\[A^+ = V \Sigma^+ U^T \]
where \( \Sigma^+ \) is the inverse of the nonzero singular values in \( \Sigma \).
a: A real or complex matrix of size \( [m,n] \), representing the input matrix to be inverted.pinva: A real or complex matrix of size \( [n,m] \), representing the pseudo-inverse of a.rtol and err.pinv(a).pure, so it can be used inside pure procedures and do concurrent blocks.call svd(a, s [, u] [, vt] [, overwrite_a] [, full_matrices] [, err])
This subroutine computes the Singular Value Decomposition (SVD) of a matrix \( A \):
\[A = U \cdot S \cdot V^T \]
where:
The singular values are returned in the array \( S \), and optionally, the matrices \( U \) and \( V^T \) are computed and returned.
a: A real matrix of size \( [m,n] \) representing the input matrix \( A \). If overwrite_a = .true., this matrix may be modified during computation. This is an inout argument.s: A real array of size \( k = \min(m,n) \), containing the singular values of \( A \). This is an output argument.u: An optional real matrix of the same type and kind as a, representing the left singular vectors of \( A \). This has shape \( [m,m] \) for the full problem or \( [m,k] \) for the reduced problem. This is an output argument.vt: An optional real matrix of the same type and kind as a, representing the right singular vectors of \( A^T \). This has shape \( [n,n] \) for the full problem or \( [k,n] \) for the reduced problem. This is an output argument.overwrite_a: (Optional, default = .false.) A logical flag indicating whether the input matrix a may be overwritten during computation. If .true., a is overwritten to avoid additional memory allocation.full_matrices: (Optional, default = .true.) A logical flag that determines whether to compute full-sized matrices \( U \) and \( V^T \) (shape \( [m,m] \) and \( [n,n] \)). If .false., computes reduced matrices of shape \( [m,k] \) and \( [k,n] \).err: (Optional) A type(la_state) variable to capture the error state. If not provided, the function will stop execution on error.The SVD of matrix \( A \) is returned in the corresponding output arguments, with the singular values in s, and optionally, the matrices \( U \) and \( V^T \).
err is not provided, exceptions will trigger an error stop.overwrite_a is enabled, the input matrix a may be overwritten during computation.pure.s = svdvals(a)
s = svdvals(a, err)
This function computes the singular values of a real or complex matrix \( A \) and returns them in a vector \( s \), where \( s \) is an array of size \( k = \min(m, n) \). Without err it is pure; with err it returns errors instead of stopping, and is not pure. Singular values are non-negative values that provide important insights into the properties of the matrix, such as its rank and conditioning.
This function does not compute the full Singular Value Decomposition (SVD); instead, it directly calculates and returns only the singular values of matrix \( A \).
The Singular Value Decomposition of a matrix \( A \) is expressed as:
\[A = U \cdot S \cdot V^T \]
where:
a: A real or complex matrix of size \( [m,n] \), representing the input matrix whose singular values are to be computed.err (optional): A type(la_state) variable that returns the error state. If not provided, the function will stop execution on error.s: A real array containing the singular values of the matrix \( A \), with the same type and kind as the input matrix. The size of the array is \( k = \min(m, n) \).err is not provided, exceptions will trigger an error stop.r = matrix_rank(a [, rtol] [, atol])
r = matrix_rank(a [, rtol] [, atol], err)
This function returns the rank of a real or complex matrix: the number of its singular values larger than \( \max(atol, rtol \cdot \sigma_{max}) \), where \( \sigma_{max} \) is the largest one. Without err it is pure; with err it returns errors instead of stopping, and is not pure.
a: A real or complex matrix of size \( [m,n] \). It is not modified.rtol (optional, default = \( \max(m,n) \cdot \epsilon \)): The relative tolerance, a real of the kind of a, as NumPy's default.atol (optional, default = 0): The absolute tolerance, a real of the kind of a.err (optional): A type(la_state) variable that receives the error state.The rank, an integer(ilp). An empty matrix has rank 0; with err, a failed computation returns 0.
rtol or atol is negative.err is not present, exceptions trigger an error stop.a.c = cond(a [, order])
c = cond(a [, order], err)
This function returns the condition number \( \kappa(A) = \|A\| \cdot \|A^{-1}\| \) of a real or complex matrix, in the norm that order selects:
order = 2 or "2": \( \sigma_{max} / \sigma_{min} \), from the singular values. a may be rectangular.order = 1 or "1", and infinity norm, order = huge(0) or "inf": LAPACK's estimate from the LU factorization of the square matrix a, which is \( O(n^2) \) after the factorization.order = "fro": from the explicit inverse of the square matrix a.Without err the function is pure; with err it returns errors instead of stopping, and is not pure.
a: A real or complex matrix of size \( [m,n] \). It is not modified.order (optional, default = 2): An integer(ilp) or a character string, spelled as for norm.err (optional): A type(la_state) variable that receives the error state.The condition number, a real scalar of the kind of a. A singular matrix has an infinite condition number; with err, a failed computation returns 0.
a is empty, if order is not one of the norms above, or if a is not square for the 1-, infinity- or Frobenius norm.err is not present, exceptions trigger an error stop.order = 2 is the spectral norm here, as in NumPy, while mnorm reads order = 2 as the Frobenius norm.e = expm(a [, order])
e = expm(a [, order], err)
This function computes the exponential \( e^{A} \) of a real or complex square matrix by scaling and squaring with a Padé approximant. Without err it is pure, so it can be called from do concurrent and from other pure procedures; with err it returns errors instead of stopping, and is not pure.
a: A real or complex square matrix of size \( [n,n] \). It is not modified.order (optional, default = 10): The order of the Padé approximant. It must not be negative.err (optional): A type(la_state) variable that receives the error state.The matrix exponential, of the same kind and size as a. The exponential of an empty matrix is an empty matrix.
a is not square or order is negative.err is not present, exceptions trigger an error stop.call matrix_exp(a [, order] [, work] [, iwork] [, err])
call matrix_exp(a, e [, order] [, work] [, iwork] [, err])
The subroutine form of expm. The first form overwrites a with its exponential; the second writes the exponential into e and leaves a unchanged. Both forms are pure. With work and iwork present they allocate no work arrays, so repeated calls on matrices of the same size can reuse the same storage.
a: A real or complex square matrix of size \( [n,n] \). In the first form it is an intent(inout) argument, overwritten with \( e^{A} \).e (second form): A matrix of the same kind and size as a, which receives \( e^{A} \).order (optional, default = 10): The order of the Padé approximant. It must not be negative.work (optional): A contiguous rank-1 array of the same type and kind as a, of size at least the lwork returned by expm_space, \( 4n^2 \). It holds the four \( [n,n] \) work matrices. This is an intent(inout) argument.iwork (optional): A contiguous rank-1 integer(ilp) array of size at least the liwork returned by expm_space, \( n \). It holds the pivots of the Padé solve. This is an intent(inout) argument.err (optional): A type(la_state) variable.a or e is not square, if their sizes differ, if order is negative, or if work or iwork is too small.err is not present, exceptions trigger an error stop.call expm_space(a, lwork, liwork)
This subroutine returns the sizes of the working arrays that matrix_exp needs for a matrix of the size of a, so that it performs no internal allocation.
a: A real or complex square matrix of size \( [n,n] \). Only its size is read.lwork: An integer returning the minimum size of work, \( 4n^2 \).liwork: An integer returning the minimum size of iwork, \( n \).pure and cannot fail: it reads the size of a and nothing else.an = matrix_power(a, n)
an = matrix_power(a, n, err)
This function computes \( A^n \) for a real or complex square matrix and an integer power \( n \), by repeated squaring: about \( 2 \log_2 |n| \) matrix products. \( A^0 \) is the identity, also for a singular matrix, and a negative power is the power \( (A^{-1})^{|n|} \) of the inverse. Without err it is pure; with err it returns errors instead of stopping, and is not pure.
a: A real or complex square matrix of size \( [m,m] \). It is not modified.n: The power, an integer(ilp).err (optional): A type(la_state) variable that receives the error state.The matrix \( A^n \), of the same type, kind and size as a. With err, an error returns an empty matrix.
a is not square.n is negative and a is singular.err is not present, exceptions trigger an error stop.d = diag(n, source [, err]) for scalar input d = diag(source(:) [, err]) for array input d = diag(source(:), k) for array input placed on the k-th diagonal v = diag(a(:,:) [, k]) to extract a diagonal of a matrix
This function generates a square diagonal matrix where the diagonal elements are populated either by a scalar value or an array of values. The size of the matrix is determined by the input parameter \(n\) or the size of the input array. If a scalar is provided, the diagonal elements are all set to the same value. If an array is provided, its length determines the size of the matrix, and its elements are placed along the diagonal. Given the offset k, the array is placed on the k-th superdiagonal ( \(k>0\)) or subdiagonal ( \(k<0\)) instead, and the matrix grows to \((n+|k|) \times (n+|k|)\). Given a matrix instead of a vector, the function extracts the requested diagonal and returns it as a vector.
n: The size of the square matrix (only used if a scalar is provided for the diagonal).source:a: A matrix whose k-th diagonal is returned as a vector.k (optional): The index of the diagonal: 0 is the main diagonal, \(k>0\) the k-th superdiagonal, \(k<0\) the k-th subdiagonal.err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the function will stop execution.The function returns a matrix of size \(n \times n\), where the diagonal elements are either all equal to the scalar source or populated by the values from the input array. With the offset k, the matrix is of size \((n+|k|) \times (n+|k|)\). Given a matrix, the function returns the requested diagonal as a vector; the vector has size zero when the requested diagonal lies outside the matrix.
err is not provided, the function will stop execution on errors.err parameter is provided, the error state of the function will be returned.eye = eye(m [, n] [, mold] [, err])
This function constructs an identity matrix of size \(m \times n\), where the diagonal elements are set to 1 and all off-diagonal elements are set to 0. If only the number of rows \(m\) is provided, a square matrix of size \(m \times m\) is returned. The matrix is populated with a real data type, by default real(real64), or a type specified by the user.
m: The number of rows of the identity matrix.n (optional): The number of columns of the identity matrix. If omitted, the matrix is square ( \(m \times m\)).mold (optional): The data type to define the return type. Defaults to real(real64).err (optional): A state return flag of type(la_state). If an error occurs and err is not provided, the function will stop execution.The function returns a matrix of size \(m \times n\) (or \(m \times m\) if \(n\) is omitted) with diagonal elements set to 1 and all other elements set to 0.
err is not provided, the function will stop execution on errors.real(real64) if no type is specified.mold scalar is used to provide a function return type.err parameter is provided, the error state of the function will be returned.t = trace(a)
This function returns the sum of the main diagonal elements of a matrix. The matrix does not need to be square: for a \( m \times n \) matrix, the first \( \min(m,n) \) diagonal elements are summed.
a: A real or complex matrix of size \( [m,n] \). It is an intent(in) argument.The function returns a scalar of the same type and kind as a, equal to \( \sum_i a_{ii} \).
pure and cannot fail: an empty matrix returns zero.trace(a) is equivalent to sum(diag(a)), computed without building the intermediate vector.c = outer_product(u, v)
This function returns the outer product \( u \otimes v \) of two vectors, the matrix whose \((i,j)\) element is \( u_i v_j \).
u: A real or complex vector of size \(m\). It is an intent(in) argument.v: A vector of the same type and kind as u, of size \(n\). It is an intent(in) argument.The function returns the \( m \times n \) matrix \( u \otimes v \), of the same type and kind as the inputs.
pure and cannot fail: the two vectors may have any lengths.v. For the Hermitian outer product, pass conjg(v).c = cross_product(a, b)
This function returns the cross product \( a \times b \) of two vectors of size 3, the vector orthogonal to both inputs.
a: A real or complex vector of size 3. It is an intent(in) argument.b: A vector of size 3, of the same type and kind as a. It is an intent(in) argument.The function returns a vector of size 3, of the same type and kind as the inputs.
pure and cannot fail: both arguments are declared of fixed size 3, so a wrong length is a compile-time error.c = kronecker_product(a, b)
This function returns the Kronecker product \( A \otimes B \): given \( A \) of size \( m_1 \times n_1 \) and \( B \) of size \( m_2 \times n_2 \), the result is the \( (m_1 m_2) \times (n_1 n_2) \) block matrix whose \((i,j)\) block is \( A_{ij} B \).
a: A real or complex matrix of size \( [m_1,n_1] \). It is an intent(in) argument.b: A matrix of size \( [m_2,n_2] \), of the same type and kind as a. It is an intent(in) argument.The function returns the \( (m_1 m_2) \times (n_1 n_2) \) Kronecker product matrix, of the same type and kind as the inputs.
pure and cannot fail: the two matrices may have any shapes.kronecker_product(a, b) and kronecker_product(b, a) differ by a permutation of rows and columns.ah = hermitian(a)
This function returns the Hermitian transpose of a matrix: conjg(transpose(a)) for a complex matrix, transpose(a) for a real one.
a: A real or complex matrix of size \( [m,n] \). It is an intent(in) argument.The function returns the \( n \times m \) matrix \( a^H \), of the same type and kind as a.
pure and cannot fail.l = is_square(a)
This function returns .true. if the input matrix has as many rows as columns.
a: A real or complex matrix of size \( [m,n] \). It is an intent(in) argument.The function returns a logical flag, .true. if \( m = n \).
pure and cannot fail.l = is_diagonal(a)
This function returns .true. if every entry of the input matrix outside the main diagonal is exactly zero. The matrix does not need to be square.
a: A real or complex matrix of size \( [m,n] \). It is an intent(in) argument.The function returns a logical flag, .true. if \( a_{ij} = 0 \) for all \( i \neq j \).
pure and cannot fail.l = is_symmetric(a)
This function returns .true. if the input matrix equals its own transpose.
a: A real or complex matrix of size \( [m,n] \). It is an intent(in) argument.The function returns a logical flag, .true. if \( a = a^T \). A non-square matrix returns .false..
pure and cannot fail.complex matrix this is the transpose without conjugation. Use is_hermitian for the conjugate test.l = is_skew_symmetric(a)
This function returns .true. if the input matrix equals the negative of its own transpose.
a: A real or complex matrix of size \( [m,n] \). It is an intent(in) argument.The function returns a logical flag, .true. if \( a = -a^T \). A non-square matrix returns .false..
pure and cannot fail.l = is_hermitian(a)
This function returns .true. if the input matrix equals its own conjugate transpose.
a: A real or complex matrix of size \( [m,n] \). It is an intent(in) argument.The function returns a logical flag, .true. if \( a = a^H \). A non-square matrix returns .false..
pure and cannot fail.real matrix this is the same test as is_symmetric.l = is_triangular(a, uplo [, err])
This function returns .true. if every entry of the input matrix below (‘uplo = 'U’) or above (uplo = 'L'`) the main diagonal is exactly zero. The matrix does not need to be square.
a: A real or complex matrix of size \( [m,n] \). It is an intent(in) argument.uplo: A character flag selecting the triangle to test, ‘'U’for upper or'L'for lower. It is anintent(in)argument. -err<tt>(optional): A state return flag of [type(la_state)](@ref la_state_type::la_state). If an error occurs anderr` is not provided, the function will stop execution.
The function returns a logical flag, .true. if a is triangular of the requested type.
uplo is neither ‘'U’nor'L', and returns.false..Iferr` is not provided, the function will stop execution on errors.err is pure.l = is_hessenberg(a, uplo [, err])
This function returns .true. if every entry of the input matrix more than one row below (‘uplo = 'U’) or more than one row above (uplo = 'L'`) the main diagonal is exactly zero. The matrix does not need to be square.
a: A real or complex matrix of size \( [m,n] \). It is an intent(in) argument.uplo: A character flag selecting the Hessenberg form to test, ‘'U’for upper or'L'for lower. It is anintent(in)argument. -err<tt>(optional): A state return flag of [type(la_state)](@ref la_state_type::la_state). If an error occurs anderr` is not provided, the function will stop execution.
The function returns a logical flag, .true. if a is Hessenberg of the requested type.
uplo is neither ‘'U’nor'L', and returns.false..Iferr` is not provided, the function will stop execution on errors.call qr(a, q, r [, overwrite_a] [, storage] [, err])
call qr(a, q, r, pivots [, overwrite_a] [, storage] [, err])
This subroutine computes the QR factorization of a real or complex matrix \( A = Q \cdot R \), where \( Q \) is orthonormal and \( R \) is upper-triangular. The matrix \( A \) has size \( [m,n] \) with \( m \ge n \). The result is returned in the output matrices \( Q \) and \( R \), which have the same type and kind as \( A \).
With the pivots argument, the factorization uses column pivoting, \( A P = Q \cdot R \), where the permutation \( P \) is chosen so that the diagonal of \( R \) has non-increasing magnitude: a(:, pivots) = matmul(q, r). A rank-deficient matrix of rank \( r \) then ends its diagonal with \( k - r \) entries that are zero up to roundoff.
Given \( k = \min(m, n) \), the matrix \( A \) can be written as:
\[A = \left( \begin{array}{cc} Q_1 & Q_2 \end{array} \right) \cdot \left( \begin{array}{cc} R_1 & 0 \end{array} \right) \]
Because the lower rows of \( R \) are zeros, a reduced problem \( A = Q_1 R_1 \) can be solved. The size of the input matrices determines which problem is solved:
shape(Q) == [m,m], shape(R) == [m,n]), the full problem is solved.shape(Q) == [m,k], shape(R) == [k,n]), the reduced problem is solved.a: A real or complex matrix of size \( [m,n] \), representing the coefficient matrix. If overwrite_a = .false., this is an input argument. If overwrite_a = .true., it is an inout argument and is overwritten upon return.q: A rank-2 array of the same type and kind as a, representing the orthonormal matrix \( Q \). This is an output argument with shape \( [m,m] \) (for the full problem) or \( [m,k] \) (for the reduced problem).r: A rank-2 array of the same type and kind as a, representing the upper-triangular matrix \( R \). This is an output argument with shape \( [m,n] \) (for the full problem) or \( [k,n] \) (for the reduced problem).pivots: An integer(ilp) array of size \( n \), returning the column permutation: column j of \( Q \cdot R \) is column pivots(j) of \( A \). This is an output argument, and its presence selects the factorization with column pivoting.storage (optional): A rank-1 array of the same type and kind as a, providing working storage for the solver. Its minimum size can be determined by a call to qr_space, with pivoting=.true. for the pivoted factorization. This is an output argument.overwrite_a (optional, default = .false.): A logical flag that determines whether the input matrix a can be overwritten. If .true., the matrix a is used as temporary storage and overwritten to avoid internal memory allocation. This is an input argument.err (optional): A type(la_state) variable that returns the error state. If not provided, the function will stop execution on error.The QR factorization matrices \( Q \) and \( R \) are returned in the corresponding arguments.
pivots does not have \( n \) elements.err is not provided, exceptions will trigger an error stop.*GEQRF, or *GEQP3 for the factorization with column pivoting.overwrite_a is enabled, the input matrix a will be modified during computation.pure.call qr_space(a, lwork [, err])
call qr_space(a, lwork, pivoting [, err])
This subroutine computes the minimum workspace size required for performing QR factorization. The size of the workspace array needed for both QR factorization and solving the reduced problem is determined based on the input matrix \( A \). With pivoting=.true., the size is the one of the QR factorization with column pivoting.
The input matrix \( A \) has size \( [m,n] \), and the output value \( lwork \) represents the minimum size of the workspace array that should be allocated for QR operations.
a: A real or complex matrix of size \( [m,n] \), representing the input matrix used to determine the required workspace size.lwork: An integer variable that will return the minimum workspace size required for QR factorization.pivoting: A logical input. If .true., lwork is sized for the factorization with column pivoting, call qr(a, q, r, pivots, storage=work); if .false., for the factorization without pivoting.err (optional): A type(la_state) variable that returns the error state. If not provided, the function will stop execution on error.The workspace size \( lwork \) that should be allocated before calling the QR factorization routine is returned.
err is not provided, exceptions will trigger an error stop.call schur(a, t, z [, eigvals] [, overwrite_a] [, storage] [, err])
This subroutine computes the Schur decomposition of a real or complex matrix \( A = Z T Z^H \), where \( Z \) is an orthonormal/unitary matrix, and \( T \) is an upper-triangular or quasi-upper-triangular matrix. The matrix \( A \) has size \( [m,m] \).
The decomposition produces:
complex matrices and quasi-upper-triangular for real matrices (with possible \( 2 \times 2 \) blocks on the diagonal).If a pre-allocated workspace is provided, no internal memory allocations take place.
a: A real or complex matrix of size \( [m,m] \). If overwrite_a = .false., this is an input argument. If overwrite_a = .true., it is an inout argument and is overwritten upon return.t: A rank-2 array of the same type and kind as a, representing the Schur form of a. This is an output argument with shape \( [m,m] \).z (optional): A rank-2 array of the same type and kind as a, representing the unitary/orthonormal transformation matrix \( Z \). This is an output argument with shape \( [m,m] \).eigvals (optional): A complex array of size \( [m] \), representing the eigenvalues that appear on the diagonal of \( T \). This is an output argument.storage (optional): A rank-1 array of the same type and kind as a, providing working storage for the solver. Its minimum size can be determined by a call to schur_space. This is an input argument.overwrite_a (optional, default = .false.): A logical flag that determines whether the input matrix a can be overwritten. If .true., the matrix a is used as temporary storage and overwritten to avoid internal memory allocation. This is an input argument.err (optional): A type(la_state) variable that returns the error state. If not provided, the function will stop execution on error.The Schur decomposition matrices \( T \) and optionally \( Z \) are returned in the corresponding arguments.
err is not provided, exceptions will trigger an error stop.overwrite_a is enabled, the input matrix a will be modified during computation.pure.call schur_space(a, lwork [, err])
This subroutine computes the minimum workspace size required for performing Schur decomposition. The size of the workspace array needed is determined based on the input matrix \( A \).
The input matrix \( A \) has size \( [m,m] \), and the output value \( lwork \) represents the minimum size of the workspace array that should be allocated for Schur decomposition operations.
a: A real or complex matrix of size \( [m,m] \), representing the input matrix used to determine the required workspace size.lwork: An integer variable that will return the minimum workspace size required for Schur decomposition.err (optional): A type(la_state) variable that returns the error state. If not provided, the function will stop execution on error.The workspace size \( lwork \) that should be allocated before calling the Schur decomposition routine is returned.
err is not provided, exceptions will trigger an error stop.pure.Modern Fortran modules with full explicit typing features are available as modules la_blas and la_lapack. The reference Fortran-77 library, forked from Release 3.10.1, was automatically processed and modernized. The following refactorings are applied:
stdlib-compatible names)implicit none(type, external) everywherepure procedures where possibleintent added to all procedure argumentsDO 10 .... 10 CONTINUE, replaced with do..end do loops or labelled loop_10: do ... cycle loop_10 ... end do loop_10 in case control statements are presentstdlib_, currently).parameters removed, and numeric constants moved to the top of each module.0.0, 0.d0, (1.0,0.0)) removedGrouping every precision of a topic in one module hopefully allows for cross-procedural inlining which is otherwise impossible without link-time optimization.
The library needs a Fortran 2018 compiler: its pure procedures stop on an error with error stop, which a pure procedure may contain from Fortran 2018 on.
An automated build is currently available via the Fortran Package Manager. To add fortran-lapack to your project, simply add it as a dependency:
fortran-lapack is compatible with the LAPACK API. If high-performance external BLAS/LAPACK libraries are available, it is sufficient to define macros
Generic interfaces to most BLAS/LAPACK functions are exposed to modules la_blas and la_lapack. These interfaces drop the initial letter to wrap a precision-agnostic version. For example, axpy is a precision-agnostic interface to saxpy, daxpy, caxpy, zaxpy, qaxpy, waxpy. The naming convention is:
| Type | 32-bit | 64-bit | 128-bit |
|---|---|---|---|
| real | s | d | q |
| complex | c | z | w |
All public interfaces in la_blas and la_lapack allow seamless linking against external libraries via a simple pre-processor flag. When an external library is available, just define macros LA_EXTERNAL_BLAS and LA_EXTERNAL_LAPACK. The kind-agnostic interface will just point to the external function. All such interfaces follow this template:
The Fortran under src/ and test/ is generated from the kind-templated fypp sources under fypp/src/ and fypp/test/, with the shared kind algebra in include/. The generated files are committed, so building or installing the package never needs fypp. After editing a template, regenerate with
The cpp fences that keep the optional precisions out of a build that did not ask for them are written into the templates by a script of their own, so a new template gets them for free:
The script fences kind loops only. Code that names qp or xdp outside a loop, such as a test written out once per kind, goes inside #ifdef LA_WITH_QP or #ifdef LA_WITH_XDP by hand; the lean continuous-integration cell is what fails when one is missing.
--check is what continuous integration runs; it prints the templates it does not own yet and the reason for each. la_blas and la_lapack are umbrella modules that re-export 57 topic modules, ten for BLAS and 47 for LAPACK; the generic interfaces they publish are data tables under include/, regenerated with python3 scripts/templatize.py --blas-interfaces and python3 scripts/templatize.py --lapack-interfaces. Two further scripts support that layout: scripts/templatize.py converts per-kind Fortran into one template per topic, driven by scripts/la_modules.tsv, and scripts/check_generated.py compares the regenerated tree against a git reference routine by routine.
LAPACK is a freely-available software package. It is available from netlib via anonymous ftp and the World Wide Web. Thus, it can be included in commercial software packages (and has been). Credit for the library should be given to the LAPACK authors. The license used for the software is the modified BSD license. According to the original license, we changed the name of the routines and commented the changes made to the original.
Part of this work was supported by the Sovereign Tech Fund.