lapack icon indicating copy to clipboard operation
lapack copied to clipboard

Add NaN propagation and array initialization notes to ?GEMM docs

Open TiborGY opened this issue 10 months ago • 7 comments

Description This PR fixes and closes #1077 and:

  1. 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.
  1. 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.
  1. Adds this to the descriptions of ALPHA arguments:
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.
  1. Changes descriptions of A arguments from array 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.
  1. Changes descriptions of B arguments from array 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.
  1. Changes descriptions of BETA arguments from When 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.
  1. Changes descriptions of C arguments from array 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.

TiborGY avatar Jan 19 '25 14:01 TiborGY