Skip to content

Commit 9582df2

Browse files
loiseaujcloiseaujc
committed
In-code documentation.
1 parent fc54644 commit 9582df2

File tree

2 files changed

+119
-23
lines changed

2 files changed

+119
-23
lines changed

‎src/stdlib_linalg.fypp‎

Lines changed: 59 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -582,12 +582,29 @@ module stdlib_linalg
582582
! Equality-constrained least-squares, i.e. minimize the sum of squares
583583
! cost || Ax - b ||^2 subject to the equality constraint Cx = d.
584584
interface constrained_lstsq
585+
!! version: experimental
586+
!!
587+
!! Computes the solution of the equality constrained least-squares problem
588+
!!
589+
!! minimize || Ax - b ||²
590+
!! subject to Cx = d
591+
!!
592+
!! where A is of size `m x n` and C of size `p x n`.
593+
!! ([Specification]())
594+
!!
595+
!! ### Description
596+
!!
597+
!! This interface provides methods for computing the solution of an equality-constrained
598+
!! least-squares problem using a function. Supported data types include `real` and
599+
!! `complex`.
600+
!!
601+
!! @note The solution is based on LAPACK's `*GLLSE` methods.
585602
#:for rk, rt, ri in RC_KINDS_TYPES
586603
module function stdlib_linalg_${ri}$_constrained_lstsq(A, b, C, d, overwrite_matrices, err) result(x)
587-
!> Input matrices.
588-
${rt}$, intent(inout), target :: A(:, :), C(:, :)
589-
!> Right-hand side vectors.
590-
${rt}$, intent(inout), target :: b(:), d(:)
604+
!> Least-squares cost
605+
${rt}$, intent(inout), target :: A(:, :), b(:)
606+
!> Equality constraints.
607+
${rt}$, intent(inout), target :: C(:, :), d(:)
591608
!> [optional] Can A and C be overwritten?
592609
logical(lk), optional, intent(in) :: overwrite_matrices
593610
!> [optional] State return flag.
@@ -601,12 +618,30 @@ module stdlib_linalg
601618
! Equality-constrained least-squares, i.e. minimize the sum of squares
602619
! cost || Ax - b ||^2 subject to the equality constraint Cx = d.
603620
interface solve_constrained_lstsq
621+
!! version: experimental
622+
!!
623+
!! Computes the solution of the equality constrained least-squares problem
624+
!!
625+
!! minimize || Ax - b ||²
626+
!! subject to Cx = d
627+
!!
628+
!! where A is of size `m x n` and C of size `p x n`.
629+
!! ([Specification]())
630+
!!
631+
!! ### Description
632+
!!
633+
!! This interface provides methods for computing the solution of an equality-constrained
634+
!! least-squares problem using a subroutine. Supported data types include `real` and
635+
!! `complex`. If a pre-allocated workspace is provided, no internal memory allocation takes
636+
!! place.
637+
!!
638+
!! @note The solution is based on LAPACK's `*GLLSE` methods.
604639
#:for rk, rt, ri in RC_KINDS_TYPES
605640
module subroutine stdlib_linalg_${ri}$_solve_constrained_lstsq(A, b, C, d, x, storage, overwrite_matrices, err)
606-
!> Input matrices.
607-
${rt}$, intent(inout), target :: A(:, :), C(:, :)
608-
!> Right-hand side vectors.
609-
${rt}$, intent(inout), target :: b(:), d(:)
641+
!> Least-squares cost.
642+
${rt}$, intent(inout), target :: A(:, :), b(:)
643+
!> Equality constraints.
644+
${rt}$, intent(inout), target :: C(:, :), d(:)
610645
!> Solution vector.
611646
${rt}$, intent(out) :: x(:)
612647
!> [optional] Storage.
@@ -620,10 +655,24 @@ module stdlib_linalg
620655
end interface
621656

622657
interface constrained_lstsq_space
658+
!! version: experimental
659+
!!
660+
!! Computes the size of the workspace required by the constrained least-squares solver.
661+
!! ([Specification]())
662+
!!
663+
!! ### Description
664+
!!
665+
!! This interface provides the size of the workspace array required by the constrained
666+
!! least-squares solver. It can be used to pre-allocate the working array in
667+
!! case several repeated solutions to a same system are sought. If pre-allocated,
668+
!! working arrays are provided, no internal allocation will take place.
669+
!!
623670
#:for rk, rt, ri in RC_KINDS_TYPES
624671
module subroutine stdlib_linalg_${ri}$_constrained_lstsq_space(A, b, C, d, lwork, err)
625-
${rt}$, intent(in), target :: A(:, :), C(:, :)
626-
${rt}$, intent(in), target :: b(:), d(:)
672+
!> Least-squares cost.
673+
${rt}$, intent(in) :: A(:, :), b(:)
674+
!> Equality constraints.
675+
${rt}$, intent(in) :: C(:, :), d(:)
627676
integer(ilp), intent(out) :: lwork
628677
type(linalg_state_type), optional, intent(out) :: err
629678
end subroutine stdlib_linalg_${ri}$_constrained_lstsq_space

‎src/stdlib_linalg_least_squares.fypp‎

Lines changed: 60 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,7 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
6060
#:for nd,ndsuf,nde in ALL_RHS
6161
#:for rk,rt,ri in RC_KINDS_TYPES
6262

63-
! Compute the integer, real, [complex] working space requested byu the least squares procedure
63+
! Compute the integer, real, [complex] working space requested by the least squares procedure
6464
pure module subroutine stdlib_linalg_${ri}$_lstsq_space_${ndsuf}$(a,b,lrwork,liwork#{if rt.startswith('c')}#,lcwork#{endif}#)
6565
!> Input matrix a[m,n]
6666
${rt}$, intent(in), target :: a(:,:)
@@ -376,7 +376,7 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
376376
err = linalg_state_type(this, LINALG_VALUE_ERROR, 'Invalid matrix size a(m, n) =', [ma, na])
377377
return
378378
else if (mc < 1 .or. nc < 1) then
379-
err = linalg_state_type(this, LINALG_VALUE_ERROR, 'Invalid matrix size c(m, n) =', [mc, nc])
379+
err = linalg_state_type(this, LINALG_VALUE_ERROR, 'Invalid matrix size c(p, n) =', [mc, nc])
380380
else if (na /= nc) then
381381
err = linalg_state_type(this, LINALG_VALUE_ERROR, 'Matrix A and matrix C have inconsistent number of columns.')
382382
else if (mb /= ma) then
@@ -389,10 +389,15 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
389389
end subroutine check_problem_size
390390

391391
#:for rk, rt, ri in RC_KINDS_TYPES
392+
! Compute the size of the workspace requested by the constrained least-squares procedure.
392393
module subroutine stdlib_linalg_${ri}$_constrained_lstsq_space(A, b, C, d, lwork, err)
393-
${rt}$, intent(in), target :: A(:, :), C(:, :)
394-
${rt}$, intent(in), target :: b(:), d(:)
394+
!> Least-squares cost.
395+
${rt}$, intent(in) :: A(:, :), b(:)
396+
!> Equality constraints.
397+
${rt}$, intent(in) :: C(:, :), d(:)
398+
!> Size of the workspace array.
395399
integer(ilp), intent(out) :: lwork
400+
!> [optional] State return flag.
396401
type(linalg_state_type), optional, intent(out) :: err
397402
!> Local variables.
398403
integer(ilp) :: m, n, p, info
@@ -402,18 +407,40 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
402407
!> Problem dimensions.
403408
m = size(A, 1) ; n = size(A, 2) ; p = size(C, 1)
404409
lwork = -1_ilp
405-
!> Compute constrained lstsq solution.
410+
!> Workspace query.
406411
call gglse(m, n, p, a_dummy, m, c_dummy, p, b_dummy, d_dummy, x, work, lwork, info)
407412
call handle_gglse_info(this, info, m, n, p, err)
408413
!> Optimal workspace size.
409414
lwork = ceiling(real(work(1), kind=${rk}$), kind=ilp)
410415
end subroutine stdlib_linalg_${ri}$_constrained_lstsq_space
411416

417+
! Constrained least-squares solver.
412418
module subroutine stdlib_linalg_${ri}$_solve_constrained_lstsq(A, b, C, d, x, storage, overwrite_matrices, err)
413-
!> Input matrices.
414-
${rt}$, intent(inout), target :: A(:, :), C(:, :)
415-
!> Right-hand side vectors.
416-
${rt}$, intent(inout), target :: b(:), d(:)
419+
!! ### Summary
420+
!! Compute the solution of the equality constrained least-squares problem
421+
!!
422+
!! minimize || Ax - b ||²
423+
!! subject to Cx = d
424+
!!
425+
!! ### Description
426+
!!
427+
!! This function computes the solution of an equality constrained linear least-squares
428+
!! problem.
429+
!!
430+
!! param: a Input matrix of size [m, n] (with m > n).
431+
!! param: b Right-hand side vector of size [m] in the least-squares cost.
432+
!! param: c Input matrix of size [p, n] (with p < n) defining the equality constraints.
433+
!! param: d Right-hand side vector of size [p] in the equality constraints.
434+
!! param: x Vector of size [n] solution to the problem.
435+
!! param: storage [optional] Working array.
436+
!! param: overwrite_matrices [optional] Boolean flag indicating whether the matrices
437+
!! and vectors can be overwritten.
438+
!! param: err [optional] State return flag.
439+
!!
440+
!> Least-squares cost.
441+
${rt}$, intent(inout), target :: A(:, :), b(:)
442+
!> Equality constraints.
443+
${rt}$, intent(inout), target :: C(:, :), d(:)
417444
!> Solution vector.
418445
${rt}$, intent(out) :: x(:)
419446
!> [optional] Storage.
@@ -494,10 +521,30 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
494521
end subroutine stdlib_linalg_${ri}$_solve_constrained_lstsq
495522

496523
module function stdlib_linalg_${ri}$_constrained_lstsq(A, b, C, d, overwrite_matrices, err) result(x)
497-
!> Input matrices.
498-
${rt}$, intent(inout), target :: A(:, :), C(:, :)
499-
!> Right-hand side vectors.
500-
${rt}$, intent(inout), target :: b(:), d(:)
524+
!! ### Summary
525+
!! Compute the solution of the equality constrained least-squares problem
526+
!!
527+
!! minimize || Ax - b ||²
528+
!! subject to Cx = d
529+
!!
530+
!! ### Description
531+
!!
532+
!! This function computes the solution of an equality constrained linear least-squares
533+
!! problem.
534+
!!
535+
!! param: a Input matrix of size [m, n] (with m > n).
536+
!! param: b Right-hand side vector of size [m] in the least-squares cost.
537+
!! param: c Input matrix of size [p, n] (with p < n) defining the equality constraints.
538+
!! param: d Right-hand side vector of size [p] in the equality constraints.
539+
!! param: x Vector of size [n] solution to the problem.
540+
!! param: overwrite_matrices [optional] Boolean flag indicating whether the matrices
541+
!! and vectors can be overwritten.
542+
!! param: err [optional] State return flag.
543+
!!
544+
!> Least-squares cost.
545+
${rt}$, intent(inout), target :: A(:, :), b(:)
546+
!> Equality constraints.
547+
${rt}$, intent(inout), target :: C(:, :), d(:)
501548
!> [optional] Can A, b, C, d be overwritten?
502549
logical(lk), optional, intent(in) :: overwrite_matrices
503550
!> [optional] State return flag.

0 commit comments

Comments
 (0)