Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add NaN propagation and array initialization notes to ?GEMM docs #1098

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+124 −28
Open

Add NaN propagation and array initialization notes to ?GEMM docs #1098

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7ad40db
add NaN propagation and array initialization notes to gemm docs
Jan 19, 2025
5f79137
simplify nan propagation quirks in the purpose section
Jan 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 28 additions & 7 deletions BLAS/SRC/cgemm.f
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,16 @@
*>
*> alpha and beta are scalars, and A, B and C are matrices, with op( A )
*> an m by k matrix, op( B ) a k by n matrix and C an m by n matrix.
*>
*> Note: if alpha and/or beta is zero, some parts of the matrix-matrix
*> operations are not performed. This results in the following NaN/Inf
*> propagation quirks:
*>
*> 1. If alpha is zero, NaNs or Infs in A or B do not affect the result.
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
*> irrespective of any NaNs or Infs in A, B or C.
*> 3. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
*> of any NaNs or Infs in C.
*> \endverbatim
*
* Arguments:
Expand Down Expand Up @@ -92,7 +102,9 @@
*> \param[in] ALPHA
*> \verbatim
*> ALPHA is COMPLEX
*> On entry, ALPHA specifies the scalar alpha.
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
*> values in A and B do not affect the result. This also means that
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
*> \endverbatim
*>
*> \param[in] A
Expand All @@ -102,7 +114,10 @@
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
*> part of the array A must contain the matrix A, otherwise
*> the leading k by m part of the array A must contain the
*> matrix A.
*> matrix A, except if ALPHA is zero.
*> If ALPHA is zero, none of the values in A affect the result, even
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
*> the matrix elements of A need not be initialized by the caller.
*> \endverbatim
*>
*> \param[in] LDA
Expand All @@ -121,7 +136,10 @@
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
*> part of the array B must contain the matrix B, otherwise
*> the leading n by k part of the array B must contain the
*> matrix B.
*> matrix B, except if ALPHA is zero.
*> If ALPHA is zero, none of the values in B affect the result, even
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
*> the matrix elements of B need not be initialized by the caller.
*> \endverbatim
*>
*> \param[in] LDB
Expand All @@ -136,16 +154,19 @@
*> \param[in] BETA
*> \verbatim
*> BETA is COMPLEX
*> On entry, BETA specifies the scalar beta. When BETA is
*> supplied as zero then C need not be set on input.
*> On entry, BETA specifies the scalar beta. If BETA is zero the
*> values in C do not affect the result. This also means that
*> NaN/Inf propagation from C is inhibited if BETA is zero.
*> \endverbatim
*>
*> \param[in,out] C
*> \verbatim
*> C is COMPLEX array, dimension ( LDC, N )
*> Before entry, the leading m by n part of the array C must
*> contain the matrix C, except when beta is zero, in which
*> case C need not be set on entry.
*> contain the matrix C, except if beta is zero.
*> If beta is zero, none of the values in C affect the result, even
*> if they are NaN/Inf. This also implies that if beta is zero,
*> the matrix elements of C need not be initialized by the caller.
*> On exit, the array C is overwritten by the m by n matrix
*> ( alpha*op( A )*op( B ) + beta*C ).
*> \endverbatim
Expand Down
41 changes: 34 additions & 7 deletions BLAS/SRC/dgemm.f
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,16 @@
*>
*> alpha and beta are scalars, and A, B and C are matrices, with op( A )
*> an m by k matrix, op( B ) a k by n matrix and C an m by n matrix.
*>
*> Note: if alpha and/or beta is zero, some parts of the matrix-matrix
*> operations are not performed. This results in the following NaN/Inf
*> propagation quirks:
*>
*> 1. If alpha is zero, NaNs or Infs in A or B do not affect the result.
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
*> irrespective of any NaNs or Infs in A, B or C.
*> 3. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
*> of any NaNs or Infs in C.
*> \endverbatim
*
* Arguments:
Expand All @@ -51,6 +61,9 @@
*> TRANSA = 'T' or 't', op( A ) = A**T.
*>
*> TRANSA = 'C' or 'c', op( A ) = A**T.
*>
*> Note: TRANSA = 'C' is supported for the sake of API consistency
*> between all ?GEMM variants.
*> \endverbatim
*>
*> \param[in] TRANSB
Expand All @@ -64,6 +77,9 @@
*> TRANSB = 'T' or 't', op( B ) = B**T.
*>
*> TRANSB = 'C' or 'c', op( B ) = B**T.
*>
*> Note: TRANSB = 'C' is supported for the sake of API consistency
*> between all ?GEMM variants.
*> \endverbatim
*>
*> \param[in] M
Expand Down Expand Up @@ -92,7 +108,9 @@
*> \param[in] ALPHA
*> \verbatim
*> ALPHA is DOUBLE PRECISION.
*> On entry, ALPHA specifies the scalar alpha.
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
*> values in A and B do not affect the result. This also means that
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
*> \endverbatim
*>
*> \param[in] A
Expand All @@ -102,7 +120,10 @@
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
*> part of the array A must contain the matrix A, otherwise
*> the leading k by m part of the array A must contain the
*> matrix A.
*> matrix A, except if ALPHA is zero.
*> If ALPHA is zero, none of the values in A affect the result, even
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
*> the matrix elements of A need not be initialized by the caller.
*> \endverbatim
*>
*> \param[in] LDA
Expand All @@ -121,7 +142,10 @@
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
*> part of the array B must contain the matrix B, otherwise
*> the leading n by k part of the array B must contain the
*> matrix B.
*> matrix B, except if ALPHA is zero.
*> If ALPHA is zero, none of the values in B affect the result, even
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
*> the matrix elements of B need not be initialized by the caller.
*> \endverbatim
*>
*> \param[in] LDB
Expand All @@ -136,16 +160,19 @@
*> \param[in] BETA
*> \verbatim
*> BETA is DOUBLE PRECISION.
*> On entry, BETA specifies the scalar beta. When BETA is
*> supplied as zero then C need not be set on input.
*> On entry, BETA specifies the scalar beta. If BETA is zero the
*> values in C do not affect the result. This also means that
*> NaN/Inf propagation from C is inhibited if BETA is zero.
*> \endverbatim
*>
*> \param[in,out] C
*> \verbatim
*> C is DOUBLE PRECISION array, dimension ( LDC, N )
*> Before entry, the leading m by n part of the array C must
*> contain the matrix C, except when beta is zero, in which
*> case C need not be set on entry.
*> contain the matrix C, except if beta is zero.
*> If beta is zero, none of the values in C affect the result, even
*> if they are NaN/Inf. This also implies that if beta is zero,
*> the matrix elements of C need not be initialized by the caller.
*> On exit, the array C is overwritten by the m by n matrix
*> ( alpha*op( A )*op( B ) + beta*C ).
*> \endverbatim
Expand Down
41 changes: 34 additions & 7 deletions BLAS/SRC/sgemm.f
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,16 @@
*>
*> alpha and beta are scalars, and A, B and C are matrices, with op( A )
*> an m by k matrix, op( B ) a k by n matrix and C an m by n matrix.
*>
*> Note: if alpha and/or beta is zero, some parts of the matrix-matrix
*> operations are not performed. This results in the following NaN/Inf
*> propagation quirks:
*>
*> 1. If alpha is zero, NaNs or Infs in A or B do not affect the result.
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
*> irrespective of any NaNs or Infs in A, B or C.
*> 3. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
*> of any NaNs or Infs in C.
*> \endverbatim
*
* Arguments:
Expand All @@ -51,6 +61,9 @@
*> TRANSA = 'T' or 't', op( A ) = A**T.
*>
*> TRANSA = 'C' or 'c', op( A ) = A**T.
*>
*> Note: TRANSA = 'C' is supported for the sake of API consistency
*> between all ?GEMM variants.
*> \endverbatim
*>
*> \param[in] TRANSB
Expand All @@ -64,6 +77,9 @@
*> TRANSB = 'T' or 't', op( B ) = B**T.
*>
*> TRANSB = 'C' or 'c', op( B ) = B**T.
*>
*> Note: TRANSB = 'C' is supported for the sake of API consistency
*> between all ?GEMM variants.
*> \endverbatim
*>
*> \param[in] M
Expand Down Expand Up @@ -92,7 +108,9 @@
*> \param[in] ALPHA
*> \verbatim
*> ALPHA is REAL
*> On entry, ALPHA specifies the scalar alpha.
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
*> values in A and B do not affect the result. This also means that
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
*> \endverbatim
*>
*> \param[in] A
Expand All @@ -102,7 +120,10 @@
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
*> part of the array A must contain the matrix A, otherwise
*> the leading k by m part of the array A must contain the
*> matrix A.
*> matrix A, except if ALPHA is zero.
*> If ALPHA is zero, none of the values in A affect the result, even
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
*> the matrix elements of A need not be initialized by the caller.
*> \endverbatim
*>
*> \param[in] LDA
Expand All @@ -121,7 +142,10 @@
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
*> part of the array B must contain the matrix B, otherwise
*> the leading n by k part of the array B must contain the
*> matrix B.
*> matrix B, except if ALPHA is zero.
*> If ALPHA is zero, none of the values in B affect the result, even
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
*> the matrix elements of B need not be initialized by the caller.
*> \endverbatim
*>
*> \param[in] LDB
Expand All @@ -136,16 +160,19 @@
*> \param[in] BETA
*> \verbatim
*> BETA is REAL
*> On entry, BETA specifies the scalar beta. When BETA is
*> supplied as zero then C need not be set on input.
*> On entry, BETA specifies the scalar beta. If BETA is zero the
*> values in C do not affect the result. This also means that
*> NaN/Inf propagation from C is inhibited if BETA is zero.
*> \endverbatim
*>
*> \param[in,out] C
*> \verbatim
*> C is REAL array, dimension ( LDC, N )
*> Before entry, the leading m by n part of the array C must
*> contain the matrix C, except when beta is zero, in which
*> case C need not be set on entry.
*> contain the matrix C, except if beta is zero.
*> If beta is zero, none of the values in C affect the result, even
*> if they are NaN/Inf. This also implies that if beta is zero,
*> the matrix elements of C need not be initialized by the caller.
*> On exit, the array C is overwritten by the m by n matrix
*> ( alpha*op( A )*op( B ) + beta*C ).
*> \endverbatim
Expand Down
35 changes: 28 additions & 7 deletions BLAS/SRC/zgemm.f
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,16 @@
*>
*> alpha and beta are scalars, and A, B and C are matrices, with op( A )
*> an m by k matrix, op( B ) a k by n matrix and C an m by n matrix.
*>
*> Note: if alpha and/or beta is zero, some parts of the matrix-matrix
*> operations are not performed. This results in the following NaN/Inf
*> propagation quirks:
*>
*> 1. If alpha is zero, NaNs or Infs in A or B do not affect the result.
*> 2. If both alpha and beta are zero, then a zero matrix is returned in C,
*> irrespective of any NaNs or Infs in A, B or C.
*> 3. If only beta is zero, alpha*op( A )*op( B ) is returned, irrespective
*> of any NaNs or Infs in C.
*> \endverbatim
*
* Arguments:
Expand Down Expand Up @@ -92,7 +102,9 @@
*> \param[in] ALPHA
*> \verbatim
*> ALPHA is COMPLEX*16
*> On entry, ALPHA specifies the scalar alpha.
*> On entry, ALPHA specifies the scalar alpha. If ALPHA is zero the
*> values in A and B do not affect the result. This also means that
*> NaN/Inf propagation from A and B is inhibited if ALPHA is zero.
*> \endverbatim
*>
*> \param[in] A
Expand All @@ -102,7 +114,10 @@
*> Before entry with TRANSA = 'N' or 'n', the leading m by k
*> part of the array A must contain the matrix A, otherwise
*> the leading k by m part of the array A must contain the
*> matrix A.
*> matrix A, except if ALPHA is zero.
*> If ALPHA is zero, none of the values in A affect the result, even
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
*> the matrix elements of A need not be initialized by the caller.
*> \endverbatim
*>
*> \param[in] LDA
Expand All @@ -121,7 +136,10 @@
*> Before entry with TRANSB = 'N' or 'n', the leading k by n
*> part of the array B must contain the matrix B, otherwise
*> the leading n by k part of the array B must contain the
*> matrix B.
*> matrix B, except if ALPHA is zero.
*> If ALPHA is zero, none of the values in B affect the result, even
*> if they are NaN/Inf. This also implies that if ALPHA is zero,
*> the matrix elements of B need not be initialized by the caller.
*> \endverbatim
*>
*> \param[in] LDB
Expand All @@ -136,16 +154,19 @@
*> \param[in] BETA
*> \verbatim
*> BETA is COMPLEX*16
*> On entry, BETA specifies the scalar beta. When BETA is
*> supplied as zero then C need not be set on input.
*> On entry, BETA specifies the scalar beta. If BETA is zero the
*> values in C do not affect the result. This also means that
*> NaN/Inf propagation from C is inhibited if BETA is zero.
*> \endverbatim
*>
*> \param[in,out] C
*> \verbatim
*> C is COMPLEX*16 array, dimension ( LDC, N )
*> Before entry, the leading m by n part of the array C must
*> contain the matrix C, except when beta is zero, in which
*> case C need not be set on entry.
*> contain the matrix C,, except if beta is zero.
*> If beta is zero, none of the values in C affect the result, even
*> if they are NaN/Inf. This also implies that if beta is zero,
*> the matrix elements of C need not be initialized by the caller.
*> On exit, the array C is overwritten by the m by n matrix
*> ( alpha*op( A )*op( B ) + beta*C ).
*> \endverbatim
Expand Down
Loading