lapack
lapack copied to clipboard
Add NaN propagation and array initialization notes to ?GEMM docs
Description This PR fixes and closes #1077 and:
- Adds this description of NaN/Inf propagation quirks to the ?GEMM docs:
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.
- Adds notes like this to S/D GEMM about why they support complex conjugation:
Note: TRANSA = 'C' is supported for the sake of API consistency between all ?GEMM variants.
- Adds this to the descriptions of
ALPHAarguments:
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.
- Changes descriptions of
Aarguments fromarray A must contain the matrix A.to:
array A must contain the 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.
- Changes descriptions of
Barguments fromarray B must contain the matrix B.to:
array B must contain the 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.
- Changes descriptions of
BETAarguments fromWhen BETA is supplied as zero then C need not be set on input.to:
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.
- Changes descriptions of
Carguments fromarray C must contain the matrix C, except when beta is zero, in which case C need not be set on entry.to:
array C must 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.
This documents/clarifies existing behaviour without adding anything to the docs that might hypothetically clash with the behaviour of some optimized BLAS implementation. (eg. I have decided against adding no-touch-guarantees to A, B and C, so a conforming implementation might still read data from them, as long as it does not affect the output)
Checklist
- [x] The documentation has been updated.
- [x] If the PR solves a specific issue, it is set to be closed on merge.