Skip to content

Commit 7ad40db

Browse files
author
GYT
committed
add NaN propagation and array initialization notes to gemm docs
1 parent ba83427 commit 7ad40db

File tree

4 files changed

+136
-28
lines changed

4 files changed

+136
-28
lines changed

‎BLAS/SRC/cgemm.f‎

Lines changed: 31 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,19 @@
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 and beta is one, NaNs or Infs in A or B do not affect
44+
*> the result.
45+
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
46+
*> irrespective of any NaNs or Infs in A, B or C.
47+
*> 3. If alpha is zero and beta is neither zero or one, then beta*C is
48+
*> returned in C, irrespective of any NaNs or Infs in A or B.
49+
*> 4. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
50+
*> of any NaNs or Infs in C.
3851
*> \endverbatim
3952
*
4053
* Arguments:
@@ -92,7 +105,9 @@
92105
*> \param[in] ALPHA
93106
*> \verbatim
94107
*> ALPHA is COMPLEX
95-
*> On entry, ALPHA specifies the scalar alpha.
108+
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
109+
*> values in A and B do not affect the result. This also means that
110+
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
96111
*> \endverbatim
97112
*>
98113
*> \param[in] A
@@ -102,7 +117,10 @@
102117
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
103118
*> part of the array A must contain the matrix A, otherwise
104119
*> the leading k by m part of the array A must contain the
105-
*> matrix A.
120+
*> matrix A, except if ALPHA is zero.
121+
*> If ALPHA is zero, none of the values in A affect the result, even
122+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
123+
*> the matrix elements of A need not be initialized by the caller.
106124
*> \endverbatim
107125
*>
108126
*> \param[in] LDA
@@ -121,7 +139,10 @@
121139
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
122140
*> part of the array B must contain the matrix B, otherwise
123141
*> the leading n by k part of the array B must contain the
124-
*> matrix B.
142+
*> matrix B, except if ALPHA is zero.
143+
*> If ALPHA is zero, none of the values in B affect the result, even
144+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
145+
*> the matrix elements of B need not be initialized by the caller.
125146
*> \endverbatim
126147
*>
127148
*> \param[in] LDB
@@ -136,16 +157,19 @@
136157
*> \param[in] BETA
137158
*> \verbatim
138159
*> 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.
160+
*> On entry, BETA specifies the scalar beta. If BETA is zero the
161+
*> values in C do not affect the result. This also means that
162+
*> NaN/Inf propagation from C is inhibited if BETA is zero.
141163
*> \endverbatim
142164
*>
143165
*> \param[in,out] C
144166
*> \verbatim
145167
*> C is COMPLEX array, dimension ( LDC, N )
146168
*> 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.
169+
*> contain the matrix C, except if beta is zero.
170+
*> If beta is zero, none of the values in C affect the result, even
171+
*> if they are NaN/Inf. This also implies that if beta is zero,
172+
*> the matrix elements of C need not be initialized by the caller.
149173
*> On exit, the array C is overwritten by the m by n matrix
150174
*> ( alpha*op( A )*op( B ) + beta*C ).
151175
*> \endverbatim

‎BLAS/SRC/dgemm.f‎

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,19 @@
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 and beta is one, NaNs or Infs in A or B do not affect
44+
*> the result.
45+
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
46+
*> irrespective of any NaNs or Infs in A, B or C.
47+
*> 3. If alpha is zero and beta is neither zero or one, then beta*C is
48+
*> returned in C, irrespective of any NaNs or Infs in A or B.
49+
*> 4. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
50+
*> of any NaNs or Infs in C.
3851
*> \endverbatim
3952
*
4053
* Arguments:
@@ -51,6 +64,9 @@
5164
*> TRANSA = 'T' or 't', op( A ) = A**T.
5265
*>
5366
*> TRANSA = 'C' or 'c', op( A ) = A**T.
67+
*>
68+
*> Note: TRANSA = 'C' is supported for the sake of API consistency
69+
*> between all ?GEMM variants.
5470
*> \endverbatim
5571
*>
5672
*> \param[in] TRANSB
@@ -64,6 +80,9 @@
6480
*> TRANSB = 'T' or 't', op( B ) = B**T.
6581
*>
6682
*> TRANSB = 'C' or 'c', op( B ) = B**T.
83+
*>
84+
*> Note: TRANSB = 'C' is supported for the sake of API consistency
85+
*> between all ?GEMM variants.
6786
*> \endverbatim
6887
*>
6988
*> \param[in] M
@@ -92,7 +111,9 @@
92111
*> \param[in] ALPHA
93112
*> \verbatim
94113
*> ALPHA is DOUBLE PRECISION.
95-
*> On entry, ALPHA specifies the scalar alpha.
114+
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
115+
*> values in A and B do not affect the result. This also means that
116+
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
96117
*> \endverbatim
97118
*>
98119
*> \param[in] A
@@ -102,7 +123,10 @@
102123
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
103124
*> part of the array A must contain the matrix A, otherwise
104125
*> the leading k by m part of the array A must contain the
105-
*> matrix A.
126+
*> matrix A, except if ALPHA is zero.
127+
*> If ALPHA is zero, none of the values in A affect the result, even
128+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
129+
*> the matrix elements of A need not be initialized by the caller.
106130
*> \endverbatim
107131
*>
108132
*> \param[in] LDA
@@ -121,7 +145,10 @@
121145
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
122146
*> part of the array B must contain the matrix B, otherwise
123147
*> the leading n by k part of the array B must contain the
124-
*> matrix B.
148+
*> matrix B, except if ALPHA is zero.
149+
*> If ALPHA is zero, none of the values in B affect the result, even
150+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
151+
*> the matrix elements of B need not be initialized by the caller.
125152
*> \endverbatim
126153
*>
127154
*> \param[in] LDB
@@ -136,16 +163,19 @@
136163
*> \param[in] BETA
137164
*> \verbatim
138165
*> 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.
166+
*> On entry, BETA specifies the scalar beta. If BETA is zero the
167+
*> values in C do not affect the result. This also means that
168+
*> NaN/Inf propagation from C is inhibited if BETA is zero.
141169
*> \endverbatim
142170
*>
143171
*> \param[in,out] C
144172
*> \verbatim
145173
*> C is DOUBLE PRECISION array, dimension ( LDC, N )
146174
*> 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.
175+
*> contain the matrix C, except if beta is zero.
176+
*> If beta is zero, none of the values in C affect the result, even
177+
*> if they are NaN/Inf. This also implies that if beta is zero,
178+
*> the matrix elements of C need not be initialized by the caller.
149179
*> On exit, the array C is overwritten by the m by n matrix
150180
*> ( alpha*op( A )*op( B ) + beta*C ).
151181
*> \endverbatim

‎BLAS/SRC/sgemm.f‎

Lines changed: 37 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,19 @@
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 and beta is one, NaNs or Infs in A or B do not affect
44+
*> the result.
45+
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
46+
*> irrespective of any NaNs or Infs in A, B or C.
47+
*> 3. If alpha is zero and beta is neither zero or one, then beta*C is
48+
*> returned in C, irrespective of any NaNs or Infs in A or B.
49+
*> 4. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
50+
*> of any NaNs or Infs in C.
3851
*> \endverbatim
3952
*
4053
* Arguments:
@@ -51,6 +64,9 @@
5164
*> TRANSA = 'T' or 't', op( A ) = A**T.
5265
*>
5366
*> TRANSA = 'C' or 'c', op( A ) = A**T.
67+
*>
68+
*> Note: TRANSA = 'C' is supported for the sake of API consistency
69+
*> between all ?GEMM variants.
5470
*> \endverbatim
5571
*>
5672
*> \param[in] TRANSB
@@ -64,6 +80,9 @@
6480
*> TRANSB = 'T' or 't', op( B ) = B**T.
6581
*>
6682
*> TRANSB = 'C' or 'c', op( B ) = B**T.
83+
*>
84+
*> Note: TRANSB = 'C' is supported for the sake of API consistency
85+
*> between all ?GEMM variants.
6786
*> \endverbatim
6887
*>
6988
*> \param[in] M
@@ -92,7 +111,9 @@
92111
*> \param[in] ALPHA
93112
*> \verbatim
94113
*> ALPHA is REAL
95-
*> On entry, ALPHA specifies the scalar alpha.
114+
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
115+
*> values in A and B do not affect the result. This also means that
116+
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
96117
*> \endverbatim
97118
*>
98119
*> \param[in] A
@@ -102,7 +123,10 @@
102123
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
103124
*> part of the array A must contain the matrix A, otherwise
104125
*> the leading k by m part of the array A must contain the
105-
*> matrix A.
126+
*> matrix A, except if ALPHA is zero.
127+
*> If ALPHA is zero, none of the values in A affect the result, even
128+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
129+
*> the matrix elements of A need not be initialized by the caller.
106130
*> \endverbatim
107131
*>
108132
*> \param[in] LDA
@@ -121,7 +145,10 @@
121145
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
122146
*> part of the array B must contain the matrix B, otherwise
123147
*> the leading n by k part of the array B must contain the
124-
*> matrix B.
148+
*> matrix B, except if ALPHA is zero.
149+
*> If ALPHA is zero, none of the values in B affect the result, even
150+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
151+
*> the matrix elements of B need not be initialized by the caller.
125152
*> \endverbatim
126153
*>
127154
*> \param[in] LDB
@@ -136,16 +163,19 @@
136163
*> \param[in] BETA
137164
*> \verbatim
138165
*> 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.
166+
*> On entry, BETA specifies the scalar beta. If BETA is zero the
167+
*> values in C do not affect the result. This also means that
168+
*> NaN/Inf propagation from C is inhibited if BETA is zero.
141169
*> \endverbatim
142170
*>
143171
*> \param[in,out] C
144172
*> \verbatim
145173
*> C is REAL array, dimension ( LDC, N )
146174
*> 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.
175+
*> contain the matrix C, except if beta is zero.
176+
*> If beta is zero, none of the values in C affect the result, even
177+
*> if they are NaN/Inf. This also implies that if beta is zero,
178+
*> the matrix elements of C need not be initialized by the caller.
149179
*> On exit, the array C is overwritten by the m by n matrix
150180
*> ( alpha*op( A )*op( B ) + beta*C ).
151181
*> \endverbatim

‎BLAS/SRC/zgemm.f‎

Lines changed: 31 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,19 @@
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 and beta is one, NaNs or Infs in A or B do not affect
44+
*> the result.
45+
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
46+
*> irrespective of any NaNs or Infs in A, B or C.
47+
*> 3. If alpha is zero and beta is neither zero or one, then beta*C is
48+
*> returned in C, irrespective of any NaNs or Infs in A or B.
49+
*> 4. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
50+
*> of any NaNs or Infs in C.
3851
*> \endverbatim
3952
*
4053
* Arguments:
@@ -92,7 +105,9 @@
92105
*> \param[in] ALPHA
93106
*> \verbatim
94107
*> ALPHA is COMPLEX*16
95-
*> On entry, ALPHA specifies the scalar alpha.
108+
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
109+
*> values in A and B do not affect the result. This also means that
110+
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
96111
*> \endverbatim
97112
*>
98113
*> \param[in] A
@@ -102,7 +117,10 @@
102117
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
103118
*> part of the array A must contain the matrix A, otherwise
104119
*> the leading k by m part of the array A must contain the
105-
*> matrix A.
120+
*> matrix A, except if ALPHA is zero.
121+
*> If ALPHA is zero, none of the values in A affect the result, even
122+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
123+
*> the matrix elements of A need not be initialized by the caller.
106124
*> \endverbatim
107125
*>
108126
*> \param[in] LDA
@@ -121,7 +139,10 @@
121139
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
122140
*> part of the array B must contain the matrix B, otherwise
123141
*> the leading n by k part of the array B must contain the
124-
*> matrix B.
142+
*> matrix B, except if ALPHA is zero.
143+
*> If ALPHA is zero, none of the values in B affect the result, even
144+
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
145+
*> the matrix elements of B need not be initialized by the caller.
125146
*> \endverbatim
126147
*>
127148
*> \param[in] LDB
@@ -136,16 +157,19 @@
136157
*> \param[in] BETA
137158
*> \verbatim
138159
*> 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.
160+
*> On entry, BETA specifies the scalar beta. If BETA is zero the
161+
*> values in C do not affect the result. This also means that
162+
*> NaN/Inf propagation from C is inhibited if BETA is zero.
141163
*> \endverbatim
142164
*>
143165
*> \param[in,out] C
144166
*> \verbatim
145167
*> C is COMPLEX*16 array, dimension ( LDC, N )
146168
*> 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.
169+
*> contain the matrix C,, except if beta is zero.
170+
*> If beta is zero, none of the values in C affect the result, even
171+
*> if they are NaN/Inf. This also implies that if beta is zero,
172+
*> the matrix elements of C need not be initialized by the caller.
149173
*> On exit, the array C is overwritten by the m by n matrix
150174
*> ( alpha*op( A )*op( B ) + beta*C ).
151175
*> \endverbatim

0 commit comments

Comments
 (0)