Skip to content

Commit a541801

Browse files
perazzperazz
committed
doc vector norms
1 parent f03295d commit a541801

File tree

2 files changed

+62
-24
lines changed

2 files changed

+62
-24
lines changed

‎fypp/src/la_norms.fypp‎

Lines changed: 28 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -133,8 +133,34 @@ module la_norms
133133
character, parameter :: LANGE_NORM_INF = 'I' !> maxval(sum(abs(a),2)), over rows
134134
character, parameter :: LANGE_NORM_TWO = 'E' !> "Euclidean" or "Frobenius"
135135

136-
137-
!> Vector norm: function interface
136+
!> @brief Compute the norm of a vector or matrix using LAPACK-based routines.
137+
!!
138+
!! Return one of several scalar norm metrics of a real or complex input array A, that can have any rank.
139+
!! For generic rank-n arrays, the scalar norm over the whole array is returned by default.
140+
!! If \f$ n \geq 2 \f$ and the optional input dimension `dim` is specified, a rank \f$ n-1 \f$ array is returned with dimension `dim` collapsed,
141+
!! containing all 1D array norms evaluated along dimension `dim` only.
142+
!!
143+
!! Norm type input is mandatory, and it is provided via the `order` argument. This can be provided as either an integer value or a character string.
144+
!! Allowed metrics are:
145+
!! - 1-norm \f$ \sum_i |a_i| \f$: `order = 1` or `order = "1"`
146+
!! - Euclidean norm \f$ \sqrt{\sum_i a_i^2} \f$: `order = 2` or `order = "2"`
147+
!! - p-norm \f$ \left( \sum_i |a_i|^p \right)^{1/p} \f$: integer `order >= 3`
148+
!! - Infinity norm \f$ \max_i |a_i| \f$: `order = huge(0)` or `"inf"`
149+
!! - Minus-infinity norm \f$ \min_i |a_i| \f$: `order = -huge(0)` or `"-inf"`
150+
!!
151+
!! @param[in] a The input vector or matrix. It may have rank 1 (vector) or higher.
152+
!! @param[in] order The order of the norm to compute, typically one of the allowed metrics.
153+
!! @param[in] dim (Optional) The dimension along which to compute the norm,
154+
!! applicable for array norms reducing rank.
155+
!! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided,
156+
!! the function will stop execution.
157+
!!
158+
!! @return The computed norm value. If `dim` is specified, the result is a lower-rank array;
159+
!! otherwise, it is a scalar.
160+
!!
161+
!! @note This interface utilizes LAPACK routines for efficient computation, ensuring numerical stability.
162+
!! @warning If invalid input values (such as negative norms) are provided, the behavior is undefined.
163+
!!
138164
interface norm
139165
#:for rk,rt,ri in ALL_KINDS_TYPES
140166
#:for it,ii in INPUT_OPTIONS

‎src/la_norms.f90‎

Lines changed: 34 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,9 @@
11
!> Matrix and Vector norms
22
module la_norms
33
use la_constants
4-
use la_blas,only:nrm2
5-
use la_lapack,only:lange
4+
use la_blas,only: nrm2
5+
use la_lapack,only: lange
66
use la_state_type
7-
use iso_fortran_env,only:real32,real64,real128,int8,int16,int32,int64,stderr => error_unit
87
implicit none(type,external)
98
private
109

@@ -21,14 +20,40 @@ module la_norms
2120
integer(ilp),parameter :: NORM_MINUSINF = -huge(0_ilp)
2221

2322
!> List of *LANGE norm flags
24-
character,parameter :: LANGE_NORM_MAT = 'M' ! maxval(sum(abs(a))) ! over whole matrix: unused
25-
character,parameter :: LANGE_NORM_ONE = '1' ! maxval(sum(abs(a),1)) ! over columns
26-
character,parameter :: LANGE_NORM_INF = 'I' ! maxval(sum(abs(a),2)) ! over rows
27-
character,parameter :: LANGE_NORM_TWO = 'E' ! "Euclidean" or "Frobenius"
23+
character,parameter :: LANGE_NORM_MAT = 'M' !> maxval(sum(abs(a))) over whole matrix: unused
24+
character,parameter :: LANGE_NORM_ONE = '1' !> maxval(sum(abs(a),1)) over columns
25+
character,parameter :: LANGE_NORM_INF = 'I' !> maxval(sum(abs(a),2)) over rows
26+
character,parameter :: LANGE_NORM_TWO = 'E' !> "Euclidean" or "Frobenius"
2827

29-
!> Vector norm: function interface
28+
!> @brief Compute the norm of a vector or matrix using LAPACK-based routines.
29+
!!
30+
!! Return one of several scalar norm metrics of a real or complex input array A, that can have any rank.
31+
!! For generic rank-n arrays, the scalar norm over the whole array is returned by default.
32+
!! If \f$ n \geq 2 \f$ and the optional input dimension `dim` is specified, a rank \f$ n-1 \f$ array is returned with dimension `dim` collapsed,
33+
!! containing all 1D array norms evaluated along dimension `dim` only.
34+
!!
35+
!! Norm type input is mandatory, and it is provided via the `order` argument. This can be provided as either an integer value or a character string.
36+
!! Allowed metrics are:
37+
!! - 1-norm \f$ \sum_i |a_i| \f$: `order = 1` or `order = "1"`
38+
!! - Euclidean norm \f$ \sqrt{\sum_i a_i^2} \f$: `order = 2` or `order = "2"`
39+
!! - p-norm \f$ \left( \sum_i |a_i|^p \right)^{1/p} \f$: integer `order >= 3`
40+
!! - Infinity norm \f$ \max_i |a_i| \f$: `order = huge(0)` or `"inf"`
41+
!! - Minus-infinity norm \f$ \min_i |a_i| \f$: `order = -huge(0)` or `"-inf"`
42+
!!
43+
!! @param[in] a The input vector or matrix. It may have rank 1 (vector) or higher.
44+
!! @param[in] order The order of the norm to compute, typically one of the allowed metrics.
45+
!! @param[in] dim (Optional) The dimension along which to compute the norm,
46+
!! applicable for array norms reducing rank.
47+
!! @param[out] err (Optional) A state return flag. If an error occurs and `err` is not provided,
48+
!! the function will stop execution.
49+
!!
50+
!! @return The computed norm value. If `dim` is specified, the result is a lower-rank array;
51+
!! otherwise, it is a scalar.
52+
!!
53+
!! @note This interface utilizes LAPACK routines for efficient computation, ensuring numerical stability.
54+
!! @warning If invalid input values (such as negative norms) are provided, the behavior is undefined.
55+
!!
3056
interface norm
31-
!> Scalar norms: real(sp)
3257
module procedure la_norm_1D_order_char_s
3358
module procedure la_norm_1D_order_err_char_s
3459
module procedure la_norm_2D_order_char_s
@@ -43,7 +68,6 @@ module la_norms
4368
module procedure la_norm_6D_order_err_char_s
4469
module procedure la_norm_7D_order_char_s
4570
module procedure la_norm_7D_order_err_char_s
46-
!> Array norms: real(sp)
4771
module procedure la_norm_2D_to_1D_char_s
4872
module procedure la_norm_2D_to_1D_err_char_s
4973
module procedure la_norm_3D_to_2D_char_s
@@ -56,7 +80,6 @@ module la_norms
5680
module procedure la_norm_6D_to_5D_err_char_s
5781
module procedure la_norm_7D_to_6D_char_s
5882
module procedure la_norm_7D_to_6D_err_char_s
59-
!> Scalar norms: real(sp)
6083
module procedure la_norm_1D_order_int_s
6184
module procedure la_norm_1D_order_err_int_s
6285
module procedure la_norm_2D_order_int_s
@@ -71,7 +94,6 @@ module la_norms
7194
module procedure la_norm_6D_order_err_int_s
7295
module procedure la_norm_7D_order_int_s
7396
module procedure la_norm_7D_order_err_int_s
74-
!> Array norms: real(sp)
7597
module procedure la_norm_2D_to_1D_int_s
7698
module procedure la_norm_2D_to_1D_err_int_s
7799
module procedure la_norm_3D_to_2D_int_s
@@ -84,7 +106,6 @@ module la_norms
84106
module procedure la_norm_6D_to_5D_err_int_s
85107
module procedure la_norm_7D_to_6D_int_s
86108
module procedure la_norm_7D_to_6D_err_int_s
87-
!> Scalar norms: real(dp)
88109
module procedure la_norm_1D_order_char_d
89110
module procedure la_norm_1D_order_err_char_d
90111
module procedure la_norm_2D_order_char_d
@@ -99,7 +120,6 @@ module la_norms
99120
module procedure la_norm_6D_order_err_char_d
100121
module procedure la_norm_7D_order_char_d
101122
module procedure la_norm_7D_order_err_char_d
102-
!> Array norms: real(dp)
103123
module procedure la_norm_2D_to_1D_char_d
104124
module procedure la_norm_2D_to_1D_err_char_d
105125
module procedure la_norm_3D_to_2D_char_d
@@ -112,7 +132,6 @@ module la_norms
112132
module procedure la_norm_6D_to_5D_err_char_d
113133
module procedure la_norm_7D_to_6D_char_d
114134
module procedure la_norm_7D_to_6D_err_char_d
115-
!> Scalar norms: real(dp)
116135
module procedure la_norm_1D_order_int_d
117136
module procedure la_norm_1D_order_err_int_d
118137
module procedure la_norm_2D_order_int_d
@@ -127,7 +146,6 @@ module la_norms
127146
module procedure la_norm_6D_order_err_int_d
128147
module procedure la_norm_7D_order_int_d
129148
module procedure la_norm_7D_order_err_int_d
130-
!> Array norms: real(dp)
131149
module procedure la_norm_2D_to_1D_int_d
132150
module procedure la_norm_2D_to_1D_err_int_d
133151
module procedure la_norm_3D_to_2D_int_d
@@ -140,7 +158,6 @@ module la_norms
140158
module procedure la_norm_6D_to_5D_err_int_d
141159
module procedure la_norm_7D_to_6D_int_d
142160
module procedure la_norm_7D_to_6D_err_int_d
143-
!> Scalar norms: real(qp)
144161
module procedure la_norm_1D_order_char_q
145162
module procedure la_norm_1D_order_err_char_q
146163
module procedure la_norm_2D_order_char_q
@@ -155,7 +172,6 @@ module la_norms
155172
module procedure la_norm_6D_order_err_char_q
156173
module procedure la_norm_7D_order_char_q
157174
module procedure la_norm_7D_order_err_char_q
158-
!> Array norms: real(qp)
159175
module procedure la_norm_2D_to_1D_char_q
160176
module procedure la_norm_2D_to_1D_err_char_q
161177
module procedure la_norm_3D_to_2D_char_q
@@ -168,7 +184,6 @@ module la_norms
168184
module procedure la_norm_6D_to_5D_err_char_q
169185
module procedure la_norm_7D_to_6D_char_q
170186
module procedure la_norm_7D_to_6D_err_char_q
171-
!> Scalar norms: real(qp)
172187
module procedure la_norm_1D_order_int_q
173188
module procedure la_norm_1D_order_err_int_q
174189
module procedure la_norm_2D_order_int_q
@@ -183,7 +198,6 @@ module la_norms
183198
module procedure la_norm_6D_order_err_int_q
184199
module procedure la_norm_7D_order_int_q
185200
module procedure la_norm_7D_order_err_int_q
186-
!> Array norms: real(qp)
187201
module procedure la_norm_2D_to_1D_int_q
188202
module procedure la_norm_2D_to_1D_err_int_q
189203
module procedure la_norm_3D_to_2D_int_q
@@ -196,7 +210,6 @@ module la_norms
196210
module procedure la_norm_6D_to_5D_err_int_q
197211
module procedure la_norm_7D_to_6D_int_q
198212
module procedure la_norm_7D_to_6D_err_int_q
199-
!> Scalar norms: complex(sp)
200213
module procedure la_norm_1D_order_char_c
201214
module procedure la_norm_1D_order_err_char_c
202215
module procedure la_norm_2D_order_char_c
@@ -351,7 +364,6 @@ module la_norms
351364
module procedure la_norm_6D_order_err_int_w
352365
module procedure la_norm_7D_order_int_w
353366
module procedure la_norm_7D_order_err_int_w
354-
!> Array norms: complex(qp)
355367
module procedure la_norm_2D_to_1D_int_w
356368
module procedure la_norm_2D_to_1D_err_int_w
357369
module procedure la_norm_3D_to_2D_int_w

0 commit comments

Comments
 (0)