Skip to content

Commit 5ce7a26

Browse files
langoulangou
authored
Merge pull request #1098 from TiborGY/gemm_docs
Add NaN propagation and array initialization notes to ?GEMM docs
2 parents bfbef59 + 5f79137 commit 5ce7a26

File tree

4 files changed

+124
-28
lines changed

4 files changed

+124
-28
lines changed

‎BLAS/SRC/cgemm.f‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,16 @@
3535
*>
3636
*> alpha and beta are scalars, and A, B and C are matrices, with op( A )
3737
*> an m by k matrix, op( B ) a k by n matrix and C an m by n matrix.
38+
*>
39+
*> Note: if alpha and/or beta is zero, some parts of the matrix-matrix
40+
*> operations are not performed. This results in the following NaN/Inf
41+
*> propagation quirks:
42+
*>
43+
*> 1. If alpha is zero, NaNs or Infs in A or B do not affect the result.
44+
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
45+
*> irrespective of any NaNs or Infs in A, B or C.
46+
*> 3. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
47+
*> of any NaNs or Infs in C.
3848
*> \endverbatim
3949
*
4050
* Arguments:
@@ -92,7 +102,9 @@
92102
*> \param[in] ALPHA
93103
*> \verbatim
94104
*> ALPHA is COMPLEX
95-
*> On entry, ALPHA specifies the scalar alpha.
105+
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
106+
*> values in A and B do not affect the result. This also means that
107+
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
96108
*> \endverbatim
97109
*>
98110
*> \param[in] A
@@ -102,7 +114,10 @@
102114
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
103115
*> part of the array A must contain the matrix A, otherwise
104116
*> the leading k by m part of the array A must contain the
105-
*> matrix A.
117+
*> matrix A, except if ALPHA is zero.
118+
*> If ALPHA is zero, none of the values in A affect the result, even
119+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
120+
*> the matrix elements of A need not be initialized by the caller.
106121
*> \endverbatim
107122
*>
108123
*> \param[in] LDA
@@ -121,7 +136,10 @@
121136
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
122137
*> part of the array B must contain the matrix B, otherwise
123138
*> the leading n by k part of the array B must contain the
124-
*> matrix B.
139+
*> matrix B, except if ALPHA is zero.
140+
*> If ALPHA is zero, none of the values in B affect the result, even
141+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
142+
*> the matrix elements of B need not be initialized by the caller.
125143
*> \endverbatim
126144
*>
127145
*> \param[in] LDB
@@ -136,16 +154,19 @@
136154
*> \param[in] BETA
137155
*> \verbatim
138156
*> BETA is COMPLEX
139-
*> On entry, BETA specifies the scalar beta. When BETA is
140-
*> supplied as zero then C need not be set on input.
157+
*> On entry, BETA specifies the scalar beta. If BETA is zero the
158+
*> values in C do not affect the result. This also means that
159+
*> NaN/Inf propagation from C is inhibited if BETA is zero.
141160
*> \endverbatim
142161
*>
143162
*> \param[in,out] C
144163
*> \verbatim
145164
*> C is COMPLEX array, dimension ( LDC, N )
146165
*> Before entry, the leading m by n part of the array C must
147-
*> contain the matrix C, except when beta is zero, in which
148-
*> case C need not be set on entry.
166+
*> contain the matrix C, except if beta is zero.
167+
*> If beta is zero, none of the values in C affect the result, even
168+
*> if they are NaN/Inf. This also implies that if beta is zero,
169+
*> the matrix elements of C need not be initialized by the caller.
149170
*> On exit, the array C is overwritten by the m by n matrix
150171
*> ( alpha*op( A )*op( B ) + beta*C ).
151172
*> \endverbatim

‎BLAS/SRC/dgemm.f‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,16 @@
3535
*>
3636
*> alpha and beta are scalars, and A, B and C are matrices, with op( A )
3737
*> an m by k matrix, op( B ) a k by n matrix and C an m by n matrix.
38+
*>
39+
*> Note: if alpha and/or beta is zero, some parts of the matrix-matrix
40+
*> operations are not performed. This results in the following NaN/Inf
41+
*> propagation quirks:
42+
*>
43+
*> 1. If alpha is zero, NaNs or Infs in A or B do not affect the result.
44+
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
45+
*> irrespective of any NaNs or Infs in A, B or C.
46+
*> 3. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
47+
*> of any NaNs or Infs in C.
3848
*> \endverbatim
3949
*
4050
* Arguments:
@@ -51,6 +61,9 @@
5161
*> TRANSA = 'T' or 't', op( A ) = A**T.
5262
*>
5363
*> TRANSA = 'C' or 'c', op( A ) = A**T.
64+
*>
65+
*> Note: TRANSA = 'C' is supported for the sake of API consistency
66+
*> between all ?GEMM variants.
5467
*> \endverbatim
5568
*>
5669
*> \param[in] TRANSB
@@ -64,6 +77,9 @@
6477
*> TRANSB = 'T' or 't', op( B ) = B**T.
6578
*>
6679
*> TRANSB = 'C' or 'c', op( B ) = B**T.
80+
*>
81+
*> Note: TRANSB = 'C' is supported for the sake of API consistency
82+
*> between all ?GEMM variants.
6783
*> \endverbatim
6884
*>
6985
*> \param[in] M
@@ -92,7 +108,9 @@
92108
*> \param[in] ALPHA
93109
*> \verbatim
94110
*> ALPHA is DOUBLE PRECISION.
95-
*> On entry, ALPHA specifies the scalar alpha.
111+
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
112+
*> values in A and B do not affect the result. This also means that
113+
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
96114
*> \endverbatim
97115
*>
98116
*> \param[in] A
@@ -102,7 +120,10 @@
102120
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
103121
*> part of the array A must contain the matrix A, otherwise
104122
*> the leading k by m part of the array A must contain the
105-
*> matrix A.
123+
*> matrix A, except if ALPHA is zero.
124+
*> If ALPHA is zero, none of the values in A affect the result, even
125+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
126+
*> the matrix elements of A need not be initialized by the caller.
106127
*> \endverbatim
107128
*>
108129
*> \param[in] LDA
@@ -121,7 +142,10 @@
121142
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
122143
*> part of the array B must contain the matrix B, otherwise
123144
*> the leading n by k part of the array B must contain the
124-
*> matrix B.
145+
*> matrix B, except if ALPHA is zero.
146+
*> If ALPHA is zero, none of the values in B affect the result, even
147+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
148+
*> the matrix elements of B need not be initialized by the caller.
125149
*> \endverbatim
126150
*>
127151
*> \param[in] LDB
@@ -136,16 +160,19 @@
136160
*> \param[in] BETA
137161
*> \verbatim
138162
*> BETA is DOUBLE PRECISION.
139-
*> On entry, BETA specifies the scalar beta. When BETA is
140-
*> supplied as zero then C need not be set on input.
163+
*> On entry, BETA specifies the scalar beta. If BETA is zero the
164+
*> values in C do not affect the result. This also means that
165+
*> NaN/Inf propagation from C is inhibited if BETA is zero.
141166
*> \endverbatim
142167
*>
143168
*> \param[in,out] C
144169
*> \verbatim
145170
*> C is DOUBLE PRECISION array, dimension ( LDC, N )
146171
*> Before entry, the leading m by n part of the array C must
147-
*> contain the matrix C, except when beta is zero, in which
148-
*> case C need not be set on entry.
172+
*> contain the matrix C, except if beta is zero.
173+
*> If beta is zero, none of the values in C affect the result, even
174+
*> if they are NaN/Inf. This also implies that if beta is zero,
175+
*> the matrix elements of C need not be initialized by the caller.
149176
*> On exit, the array C is overwritten by the m by n matrix
150177
*> ( alpha*op( A )*op( B ) + beta*C ).
151178
*> \endverbatim

‎BLAS/SRC/sgemm.f‎

Lines changed: 34 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,16 @@
3535
*>
3636
*> alpha and beta are scalars, and A, B and C are matrices, with op( A )
3737
*> an m by k matrix, op( B ) a k by n matrix and C an m by n matrix.
38+
*>
39+
*> Note: if alpha and/or beta is zero, some parts of the matrix-matrix
40+
*> operations are not performed. This results in the following NaN/Inf
41+
*> propagation quirks:
42+
*>
43+
*> 1. If alpha is zero, NaNs or Infs in A or B do not affect the result.
44+
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
45+
*> irrespective of any NaNs or Infs in A, B or C.
46+
*> 3. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
47+
*> of any NaNs or Infs in C.
3848
*> \endverbatim
3949
*
4050
* Arguments:
@@ -51,6 +61,9 @@
5161
*> TRANSA = 'T' or 't', op( A ) = A**T.
5262
*>
5363
*> TRANSA = 'C' or 'c', op( A ) = A**T.
64+
*>
65+
*> Note: TRANSA = 'C' is supported for the sake of API consistency
66+
*> between all ?GEMM variants.
5467
*> \endverbatim
5568
*>
5669
*> \param[in] TRANSB
@@ -64,6 +77,9 @@
6477
*> TRANSB = 'T' or 't', op( B ) = B**T.
6578
*>
6679
*> TRANSB = 'C' or 'c', op( B ) = B**T.
80+
*>
81+
*> Note: TRANSB = 'C' is supported for the sake of API consistency
82+
*> between all ?GEMM variants.
6783
*> \endverbatim
6884
*>
6985
*> \param[in] M
@@ -92,7 +108,9 @@
92108
*> \param[in] ALPHA
93109
*> \verbatim
94110
*> ALPHA is REAL
95-
*> On entry, ALPHA specifies the scalar alpha.
111+
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
112+
*> values in A and B do not affect the result. This also means that
113+
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
96114
*> \endverbatim
97115
*>
98116
*> \param[in] A
@@ -102,7 +120,10 @@
102120
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
103121
*> part of the array A must contain the matrix A, otherwise
104122
*> the leading k by m part of the array A must contain the
105-
*> matrix A.
123+
*> matrix A, except if ALPHA is zero.
124+
*> If ALPHA is zero, none of the values in A affect the result, even
125+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
126+
*> the matrix elements of A need not be initialized by the caller.
106127
*> \endverbatim
107128
*>
108129
*> \param[in] LDA
@@ -121,7 +142,10 @@
121142
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
122143
*> part of the array B must contain the matrix B, otherwise
123144
*> the leading n by k part of the array B must contain the
124-
*> matrix B.
145+
*> matrix B, except if ALPHA is zero.
146+
*> If ALPHA is zero, none of the values in B affect the result, even
147+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
148+
*> the matrix elements of B need not be initialized by the caller.
125149
*> \endverbatim
126150
*>
127151
*> \param[in] LDB
@@ -136,16 +160,19 @@
136160
*> \param[in] BETA
137161
*> \verbatim
138162
*> BETA is REAL
139-
*> On entry, BETA specifies the scalar beta. When BETA is
140-
*> supplied as zero then C need not be set on input.
163+
*> On entry, BETA specifies the scalar beta. If BETA is zero the
164+
*> values in C do not affect the result. This also means that
165+
*> NaN/Inf propagation from C is inhibited if BETA is zero.
141166
*> \endverbatim
142167
*>
143168
*> \param[in,out] C
144169
*> \verbatim
145170
*> C is REAL array, dimension ( LDC, N )
146171
*> Before entry, the leading m by n part of the array C must
147-
*> contain the matrix C, except when beta is zero, in which
148-
*> case C need not be set on entry.
172+
*> contain the matrix C, except if beta is zero.
173+
*> If beta is zero, none of the values in C affect the result, even
174+
*> if they are NaN/Inf. This also implies that if beta is zero,
175+
*> the matrix elements of C need not be initialized by the caller.
149176
*> On exit, the array C is overwritten by the m by n matrix
150177
*> ( alpha*op( A )*op( B ) + beta*C ).
151178
*> \endverbatim

‎BLAS/SRC/zgemm.f‎

Lines changed: 28 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,16 @@
3535
*>
3636
*> alpha and beta are scalars, and A, B and C are matrices, with op( A )
3737
*> an m by k matrix, op( B ) a k by n matrix and C an m by n matrix.
38+
*>
39+
*> Note: if alpha and/or beta is zero, some parts of the matrix-matrix
40+
*> operations are not performed. This results in the following NaN/Inf
41+
*> propagation quirks:
42+
*>
43+
*> 1. If alpha is zero, NaNs or Infs in A or B do not affect the result.
44+
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
45+
*> irrespective of any NaNs or Infs in A, B or C.
46+
*> 3. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
47+
*> of any NaNs or Infs in C.
3848
*> \endverbatim
3949
*
4050
* Arguments:
@@ -92,7 +102,9 @@
92102
*> \param[in] ALPHA
93103
*> \verbatim
94104
*> ALPHA is COMPLEX*16
95-
*> On entry, ALPHA specifies the scalar alpha.
105+
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
106+
*> values in A and B do not affect the result. This also means that
107+
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
96108
*> \endverbatim
97109
*>
98110
*> \param[in] A
@@ -102,7 +114,10 @@
102114
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
103115
*> part of the array A must contain the matrix A, otherwise
104116
*> the leading k by m part of the array A must contain the
105-
*> matrix A.
117+
*> matrix A, except if ALPHA is zero.
118+
*> If ALPHA is zero, none of the values in A affect the result, even
119+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
120+
*> the matrix elements of A need not be initialized by the caller.
106121
*> \endverbatim
107122
*>
108123
*> \param[in] LDA
@@ -121,7 +136,10 @@
121136
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
122137
*> part of the array B must contain the matrix B, otherwise
123138
*> the leading n by k part of the array B must contain the
124-
*> matrix B.
139+
*> matrix B, except if ALPHA is zero.
140+
*> If ALPHA is zero, none of the values in B affect the result, even
141+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
142+
*> the matrix elements of B need not be initialized by the caller.
125143
*> \endverbatim
126144
*>
127145
*> \param[in] LDB
@@ -136,16 +154,19 @@
136154
*> \param[in] BETA
137155
*> \verbatim
138156
*> BETA is COMPLEX*16
139-
*> On entry, BETA specifies the scalar beta. When BETA is
140-
*> supplied as zero then C need not be set on input.
157+
*> On entry, BETA specifies the scalar beta. If BETA is zero the
158+
*> values in C do not affect the result. This also means that
159+
*> NaN/Inf propagation from C is inhibited if BETA is zero.
141160
*> \endverbatim
142161
*>
143162
*> \param[in,out] C
144163
*> \verbatim
145164
*> C is COMPLEX*16 array, dimension ( LDC, N )
146165
*> Before entry, the leading m by n part of the array C must
147-
*> contain the matrix C, except when beta is zero, in which
148-
*> case C need not be set on entry.
166+
*> contain the matrix C,, except if beta is zero.
167+
*> If beta is zero, none of the values in C affect the result, even
168+
*> if they are NaN/Inf. This also implies that if beta is zero,
169+
*> the matrix elements of C need not be initialized by the caller.
149170
*> On exit, the array C is overwritten by the m by n matrix
150171
*> ( alpha*op( A )*op( B ) + beta*C ).
151172
*> \endverbatim

0 commit comments

Comments
 (0)