la_least_squares::lstsq Interface Reference

Compute a least squares solution to system \( A \cdot x = b \), i.e. such that the 2-norm \( \|b - A \cdot x\| \) is minimized. More...

Public Member Functions
real(sp) function, dimension(:), allocatable, target	la_slstsq_one (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a real(sp) system of linear equations Ax = B.
real(dp) function, dimension(:), allocatable, target	la_dlstsq_one (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a real(dp) system of linear equations Ax = B.
real(qp) function, dimension(:), allocatable, target	la_qlstsq_one (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a real(qp) system of linear equations Ax = B.
complex(sp) function, dimension(:), allocatable, target	la_clstsq_one (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a complex(sp) system of linear equations Ax = B.
complex(dp) function, dimension(:), allocatable, target	la_zlstsq_one (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a complex(dp) system of linear equations Ax = B.
complex(qp) function, dimension(:), allocatable, target	la_wlstsq_one (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a complex(qp) system of linear equations Ax = B.
real(sp) function, dimension(:,:), allocatable, target	la_slstsq_multiple (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a real(sp) system of linear equations Ax = B.
real(dp) function, dimension(:,:), allocatable, target	la_dlstsq_multiple (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a real(dp) system of linear equations Ax = B.
real(qp) function, dimension(:,:), allocatable, target	la_qlstsq_multiple (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a real(qp) system of linear equations Ax = B.
complex(sp) function, dimension(:,:), allocatable, target	la_clstsq_multiple (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a complex(sp) system of linear equations Ax = B.
complex(dp) function, dimension(:,:), allocatable, target	la_zlstsq_multiple (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a complex(dp) system of linear equations Ax = B.
complex(qp) function, dimension(:,:), allocatable, target	la_wlstsq_multiple (a, b, cond, overwrite_a, rank, err)
	Compute the least-squares solution to a complex(qp) system of linear equations Ax = B.

Detailed Description

Compute a least squares solution to system \( A \cdot x = b \), i.e. such that the 2-norm \( \|b - A \cdot x\| \) is minimized.

This function computes the least-squares solution to a real system of linear equations:

\( A \cdot x = b \)

where A is an n x n matrix and b is either a vector (n) or a matrix (n x nrhs). The solution x is returned as an allocatable array.

Parameters

[in,out]	a	The input matrix of size n x n. If overwrite_a is true, the contents of A may be modified during computation.
[in]	b	The right-hand side vector (n) or matrix (n x nrhs).
[in]	cond	(Optional) A cutoff for rank evaluation: singular values \( s(i) \) such that \( s(i) \leq \text{cond} \cdot \max(s) \) are considered zero.
[in]	overwrite_a	(Optional) If true, A and B may be overwritten and destroyed. Default is false.
[out]	rank	(Optional) The rank of the matrix A.
[out]	err	(Optional) A state return flag. If an error occurs and err is not provided, the function will stop execution.

Returns

Solution matrix x of size n (for a single right-hand side) or n x nrhs.

Note

This function relies on LAPACK least-squares solvers such as [*GELSS](@ref la_lapack::gelss).

Warning

If overwrite_a is enabled, the original contents of A and B may be lost.

Compute the working space needed by a least squares solution of \( A \cdot x = b \).

This subroutine returns the sizes of the real, integer and (for complex data) complex working arrays that solve_lstsq needs for the given problem, so that a repeated solve of problems of the same size performs no allocation.

Parameters

[in]	a	The input matrix of size \( [m,n] \). Only its shape is used.
[in]	b	The right-hand side vector ( \(m\)) or matrix ( \(m \times nrhs\)). Only its shape is used.
[out]	lrwork	The size of the real working array.
[out]	liwork	The size of the integer working array.
[out]	lcwork	The size of the complex working array. Present for complex data only.

Compute a least squares solution of \( A \cdot x = b \) into a pre-allocated array.

This subroutine computes the least-squares solution of a linear matrix problem and writes it into the caller's array, so that neither the solution nor the working space needs to be allocated internally.

Parameters

[in,out]	a	The input matrix of size \( [m,n] \). If overwrite_a is true, the contents of a may be modified during computation.
[in]	b	The right-hand side vector ( \(m\)) or matrix ( \(m \times nrhs\)).
[in,out]	x	The solution vector ( \(\ge n\)) or matrix ( \(\ge n \times nrhs\)).
[in,out]	real_storage	(Optional) Pre-allocated real working space. Its size is checked with lstsq_space.
[in,out]	int_storage	(Optional) Pre-allocated integer working space.
[in,out]	cmpl_storage	(Optional) Pre-allocated complex working space. Complex data only.
[in]	cond	(Optional) A cutoff for rank evaluation: singular values \( s(i) \) such that \( s(i) \leq \text{cond} \cdot \max(s) \) are considered zero.
[out]	singvals	(Optional) The \( \min(m,n) \) singular values, in decreasing order.
[in]	overwrite_a	(Optional) If true, a may be overwritten and destroyed. Default is false.
[out]	rank	(Optional) The rank of the matrix a.
[out]	err	(Optional) A state return flag. If an error occurs and err is not provided, the function will stop execution.

Compute a weighted least squares solution of \( A \cdot x = b \).

This function minimizes \( \|D (b - A \cdot x)\| \) with \( D = \mathrm{diag}(\sqrt{w}) \), that is, it gives the \(i\)-th equation the weight \( w_i \).

Parameters

[in]	w	The weight vector of size \(m\). It is always real, and every entry must be positive.
[in,out]	a	The input matrix of size \( [m,n] \). If overwrite_a is true, the contents of a may be modified during computation.
[in]	b	The right-hand side vector of size \(m\).
[in]	cond	(Optional) A cutoff for rank evaluation.
[in]	overwrite_a	(Optional) If true, a may be overwritten and destroyed. Default is false.
[out]	rank	(Optional) The rank of the matrix a.
[out]	err	(Optional) A state return flag. If an error occurs and err is not provided, the function will stop execution.

Returns

Solution vector x of size \(n\).

Compute a weighted least squares solution into a pre-allocated array.

This subroutine is the subroutine form of weighted_lstsq: it writes the solution into the caller's array.

Parameters

[in]	w	The weight vector of size \(m\). It is always real, and every entry must be positive.
[in,out]	a	The input matrix of size \( [m,n] \). If overwrite_a is true, the contents of a may be modified during computation.
[in]	b	The right-hand side vector of size \(m\).
[in,out]	x	The solution vector of size \(n\).
[in]	cond	(Optional) A cutoff for rank evaluation.
[in]	overwrite_a	(Optional) If true, a may be overwritten and destroyed. Default is false.
[out]	rank	(Optional) The rank of the matrix a.
[out]	err	(Optional) A state return flag. If an error occurs and err is not provided, the function will stop execution.

Compute the solution of an equality-constrained least squares problem.

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] \), \( p \le n \le m+p \).

Parameters

[in,out]	A	The least-squares matrix of size \( [m,n] \).
[in,out]	b	The least-squares right-hand side vector of size \(m\).
[in,out]	C	The constraint matrix of size \( [p,n] \).
[in,out]	d	The constraint right-hand side vector of size \(p\).
[in]	overwrite_matrices	(Optional) If true, A, b, C and d may be overwritten and destroyed. Default is false.
[out]	err	(Optional) A state return flag. If an error occurs and err is not provided, the function will stop execution.

Returns

Solution vector x of size \(n\).

Note

This function relies on LAPACK's GGLSE driver.

Compute the solution of an equality-constrained least squares problem into a pre-allocated array.

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.

Parameters

[in,out]	A	The least-squares matrix of size \( [m,n] \).
[in,out]	b	The least-squares right-hand side vector of size \(m\).
[in,out]	C	The constraint matrix of size \( [p,n] \).
[in,out]	d	The constraint right-hand side vector of size \(p\).
[out]	x	The solution vector of size \(n\).
[out]	storage	(Optional) Pre-allocated workspace. Its size is checked with constrained_lstsq_space.
[in]	overwrite_matrices	(Optional) If true, A, b, C and d may be overwritten and destroyed. Default is false.
[out]	err	(Optional) A state return flag. If an error occurs and err is not provided, the function will stop execution.

Compute the working space needed by the equality-constrained least squares solver.

This subroutine queries LAPACK for the optimal size of the workspace array that solve_constrained_lstsq needs.

Parameters

[in]	A	The least-squares matrix of size \( [m,n] \). Only its shape is used.
[in]	C	The constraint matrix of size \( [p,n] \). Only its shape is used.
[out]	lwork	The size of the workspace array.
[out]	err	(Optional) A state return flag. If an error occurs and err is not provided, the function will stop execution.

Member Function/Subroutine Documentation

la_clstsq_multiple()

complex(sp) function, dimension(:,:), allocatable, target la_least_squares::lstsq::la_clstsq_multiple	(	complex(sp), dimension(:,:), intent(inout), target	a,
		complex(sp), dimension(:,:), intent(in)	b,
		real(sp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a complex(sp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_clstsq_one()

complex(sp) function, dimension(:), allocatable, target la_least_squares::lstsq::la_clstsq_one	(	complex(sp), dimension(:,:), intent(inout), target	a,
		complex(sp), dimension(:), intent(in)	b,
		real(sp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a complex(sp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_dlstsq_multiple()

real(dp) function, dimension(:,:), allocatable, target la_least_squares::lstsq::la_dlstsq_multiple	(	real(dp), dimension(:,:), intent(inout), target	a,
		real(dp), dimension(:,:), intent(in)	b,
		real(dp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a real(dp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_dlstsq_one()

real(dp) function, dimension(:), allocatable, target la_least_squares::lstsq::la_dlstsq_one	(	real(dp), dimension(:,:), intent(inout), target	a,
		real(dp), dimension(:), intent(in)	b,
		real(dp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a real(dp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_qlstsq_multiple()

real(qp) function, dimension(:,:), allocatable, target la_least_squares::lstsq::la_qlstsq_multiple	(	real(qp), dimension(:,:), intent(inout), target	a,
		real(qp), dimension(:,:), intent(in)	b,
		real(qp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a real(qp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_qlstsq_one()

real(qp) function, dimension(:), allocatable, target la_least_squares::lstsq::la_qlstsq_one	(	real(qp), dimension(:,:), intent(inout), target	a,
		real(qp), dimension(:), intent(in)	b,
		real(qp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a real(qp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_slstsq_multiple()

real(sp) function, dimension(:,:), allocatable, target la_least_squares::lstsq::la_slstsq_multiple	(	real(sp), dimension(:,:), intent(inout), target	a,
		real(sp), dimension(:,:), intent(in)	b,
		real(sp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a real(sp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_slstsq_one()

real(sp) function, dimension(:), allocatable, target la_least_squares::lstsq::la_slstsq_one	(	real(sp), dimension(:,:), intent(inout), target	a,
		real(sp), dimension(:), intent(in)	b,
		real(sp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a real(sp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_wlstsq_multiple()

complex(qp) function, dimension(:,:), allocatable, target la_least_squares::lstsq::la_wlstsq_multiple	(	complex(qp), dimension(:,:), intent(inout), target	a,
		complex(qp), dimension(:,:), intent(in)	b,
		real(qp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a complex(qp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_wlstsq_one()

complex(qp) function, dimension(:), allocatable, target la_least_squares::lstsq::la_wlstsq_one	(	complex(qp), dimension(:,:), intent(inout), target	a,
		complex(qp), dimension(:), intent(in)	b,
		real(qp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a complex(qp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_zlstsq_multiple()

complex(dp) function, dimension(:,:), allocatable, target la_least_squares::lstsq::la_zlstsq_multiple	(	complex(dp), dimension(:,:), intent(inout), target	a,
		complex(dp), dimension(:,:), intent(in)	b,
		real(dp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a complex(dp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

la_zlstsq_one()

complex(dp) function, dimension(:), allocatable, target la_least_squares::lstsq::la_zlstsq_one	(	complex(dp), dimension(:,:), intent(inout), target	a,
		complex(dp), dimension(:), intent(in)	b,
		real(dp), intent(in), optional	cond,
		logical(lk), intent(in), optional	overwrite_a,
		integer(ilp), intent(out), optional	rank,
		type(la_state), intent(out), optional	err )

Compute the least-squares solution to a complex(dp) system of linear equations Ax = B.

Parameters

[in,out]	a	Input matrix a[n,n]
[in]	b	Right hand side vector or array, b[n] or b[n,nrhs]
[in]	cond	[optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
[in]	overwrite_a	[optional] Can A,b data be overwritten and destroyed?
[out]	rank	[optional] Return rank of A
[out]	err	[optional] state return flag. On error if not requested, the code will stop

Returns

Result array/matrix x[n] or x[n,nrhs]

---

The documentation for this interface was generated from the following file:

• la_least_squares.f90