Address review: use Fortran notation in comments, merge example files

Author: aamrindersingh

doc/specs/stdlib_linalg.md

@@ -1067,7 +1067,7 @@ Exceptions trigger an `error stop`.
 ### Example
 
 ```fortran
-{!example/linalg/example_solve_weighted_lstsq.f90!}
+{!example/linalg/example_weighted_lstsq.f90!}
 ```
 
 ## `det` - Computes the determinant of a square matrix

example/linalg/CMakeLists.txt

@@ -38,7 +38,6 @@ ADD_EXAMPLE(lstsq2)
 ADD_EXAMPLE(constrained_lstsq1)
 ADD_EXAMPLE(constrained_lstsq2)
 ADD_EXAMPLE(weighted_lstsq)
-ADD_EXAMPLE(solve_weighted_lstsq)
 ADD_EXAMPLE(norm)
 ADD_EXAMPLE(mnorm)
 ADD_EXAMPLE(get_norm)

example/linalg/example_solve_weighted_lstsq.f90

@@ -1,10 +1,10 @@
-! Weighted least-squares solver
+! Weighted least-squares solver: function and subroutine interfaces
 program example_weighted_lstsq
   use stdlib_linalg_constants, only: dp
-  use stdlib_linalg, only: weighted_lstsq
+  use stdlib_linalg, only: weighted_lstsq, solve_weighted_lstsq
   implicit none
 
-  real(dp) :: A(4,2), b(4), w(4)
+  real(dp) :: A(4,2), b(4), w(4), x_sub(2)
   real(dp), allocatable :: x(:)
 
   ! Design matrix: intercept + slope
@@ -17,10 +17,16 @@ program example_weighted_lstsq
   ! Weights: downweight the outlier
   w = [1.0_dp, 1.0_dp, 0.1_dp, 1.0_dp]
 
-  ! Solve weighted least-squares
+  ! Solve weighted least-squares (function interface)
   x = weighted_lstsq(w, A, b)
 
-  print '("Weighted fit: intercept = ",f8.4,", slope = ",f8.4)', x(1), x(2)
-  ! Weighted fit: intercept =   0.1500, slope =   1.9911
+  print '("Function interface:  intercept = ",f8.4,", slope = ",f8.4)', x(1), x(2)
+  ! Function interface:  intercept =   0.1500, slope =   1.9911
+
+  ! Solve weighted least-squares (subroutine interface)
+  call solve_weighted_lstsq(w, A, b, x_sub)
+
+  print '("Subroutine interface: intercept = ",f8.4,", slope = ",f8.4)', x_sub(1), x_sub(2)
+  ! Subroutine interface: intercept =   0.1500, slope =   1.9911
 
 end program example_weighted_lstsq

example/linalg/example_weighted_lstsq.f90

@@ -705,9 +705,9 @@ module stdlib_linalg
     module function stdlib_linalg_${ri}$_weighted_lstsq(w,a,b,cond,overwrite_a,rank,err) result(x)
         !> Weight vector (must be positive, always real)
         real(${rk}$), intent(in) :: w(:)
-        !> Input matrix a[m,n]
+        !> Input matrix a(m,n)
         ${rt}$, intent(inout), target :: a(:,:)
-        !> Right hand side vector b[m]
+        !> Right hand side vector b(m)
         ${rt}$, intent(in) :: b(:)
         !> [optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
         real(${rk}$), optional, intent(in) :: cond
@@ -717,7 +717,7 @@ module stdlib_linalg
         integer(ilp), optional, intent(out) :: rank
         !> [optional] state return flag. On error if not requested, the code will stop
         type(linalg_state_type), optional, intent(out) :: err
-        !> Result array x[n]
+        !> Result array x(n)
         ${rt}$, allocatable :: x(:)
     end function stdlib_linalg_${ri}$_weighted_lstsq
     #:endfor
@@ -747,11 +747,11 @@ module stdlib_linalg
     module subroutine stdlib_linalg_${ri}$_solve_weighted_lstsq(w,a,b,x,cond,overwrite_a,rank,err)
         !> Weight vector (must be positive, always real)
         real(${rk}$), intent(in) :: w(:)
-        !> Input matrix a[m,n]
+        !> Input matrix a(m,n)
         ${rt}$, intent(inout), target :: a(:,:)
-        !> Right hand side vector b[m]
+        !> Right hand side vector b(m)
         ${rt}$, intent(in) :: b(:)
-        !> Result array x[n]
+        !> Result array x(n)
         ${rt}$, intent(inout), contiguous, target :: x(:)
         !> [optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
         real(${rk}$), optional, intent(in) :: cond

src/linalg/stdlib_linalg.fypp

@@ -573,9 +573,9 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
     module function stdlib_linalg_${ri}$_weighted_lstsq(w,a,b,cond,overwrite_a,rank,err) result(x)
         !> Weight vector (must be positive, always real)
         real(${rk}$), intent(in) :: w(:)
-        !> Input matrix a[m,n]
+        !> Input matrix a(m,n)
         ${rt}$, intent(inout), target :: a(:,:)
-        !> Right hand side vector b[m]
+        !> Right hand side vector b(m)
         ${rt}$, intent(in) :: b(:)
         !> [optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
         real(${rk}$), optional, intent(in) :: cond
@@ -585,7 +585,7 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
         integer(ilp), optional, intent(out) :: rank
         !> [optional] state return flag. On error if not requested, the code will stop
         type(linalg_state_type), optional, intent(out) :: err
-        !> Result array x[n]
+        !> Result array x(n)
         ${rt}$, allocatable :: x(:)
 
         integer(ilp) :: n
@@ -609,10 +609,10 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
     !!
     !! This subroutine computes the weighted least-squares solution of a linear matrix problem.
     !!
-    !! param: w Weight vector of size [m] (must be positive, always real).
-    !! param: a Input matrix of size [m,n].
-    !! param: b Right-hand-side vector of size [m].
-    !! param: x Solution vector of size [n].
+    !! param: w Weight vector of size (m) (must be positive, always real).
+    !! param: a Input matrix of size (m,n).
+    !! param: b Right-hand-side vector of size (m).
+    !! param: x Solution vector of size (n).
     !! param: cond [optional] Real input threshold indicating that singular values `s_i <= cond*maxval(s)`
     !!        do not contribute to the matrix rank.
     !! param: overwrite_a [optional] Flag indicating if the input matrix can be overwritten.
@@ -621,11 +621,11 @@ submodule (stdlib_linalg) stdlib_linalg_least_squares
     !!
         !> Weight vector (must be positive, always real)
         real(${rk}$), intent(in) :: w(:)
-        !> Input matrix a[m,n]
+        !> Input matrix a(m,n)
         ${rt}$, intent(inout), target :: a(:,:)
-        !> Right hand side vector b[m]
+        !> Right hand side vector b(m)
         ${rt}$, intent(in) :: b(:)
-        !> Result array x[n]
+        !> Result array x(n)
         ${rt}$, intent(inout), contiguous, target :: x(:)
         !> [optional] cutoff for rank evaluation: singular values s(i)<=cond*maxval(s) are considered 0.
         real(${rk}$), optional, intent(in) :: cond