A quick reference to ATLAS programming resources

ATLAS has a quite a bit of programming infrastructure which can be used. The routines in ATLAS/src/auxil represent low-level routines which can be called from anywhere in the ATLAS code (other than the Level 1 kernel routines), and are prototyped by including either atlas_misc.h or atlas_aux.h.

ATLAS makes fairly heavy use of macros in order to achieve something approaching precision (and in some cases type) independent code. Any routine can include the general macro file atlas_misc.h in order to get access to these macros. Low level routines are compiled multiple times with differing makefile-controlled cpp macros (call these index macros) in order to produce differing implementations. The index macros used in ATLAS presently include:

• Type/precision selection macros, choices are:
  1. SREAL: single precision real is expected
  2. DREAL: double precision real is expected
  3. SCPLX: single precision complex is expected
  4. DCPLX: double precision complex is expected
• Scalar alpha case selection macros, choices are:
  1. ALPHA1: scalar $\alpha$ should be assumed to be 1
  2. ALPHAXI0: only valid for complex types; real component is unknown, but imaginary component is zero
  3. ALPHAX: scalar alpha is unknown, and must be applied as a variable
• Scalar $\beta$ case selection macros, choices are:
  1. BETA0: scalar beta should be assumed to be 0
  2. BETA1: scalar beta should be assumed to be 1
  3. BETAXI0: only valid for complex types; real component is unknown, but imaginary component is zero
  4. BETAX: scalar beta is unknown, and must be applied as a variable
• For complex types only, ATLAS defines the index variable Conj_ when the conjugation of the transpose setting is needed

Each of these index macros define a number of helper macros that go with them. atlas_misc.h should be examined for full details. For instance, if SREAL or DREAL are defined, the type-determinant macro TREAL is defined. Similarly, if SCPLX or DCPLX are defined, the type-determinant macro TCPLX is defined. For a simpler example, the precision macro defines ATL_rone, which corresponds to 1.0f in single precision, and 1.0 in double. A great many of these helper macros are designed to be used to help in resolving names independant of type. In order to use these naming macros, we use the macro-joining function Mjoin(Mac1, Mac2), which results in the joining of the Mac1 and Mac2.

You can examine the GEMV kernel implementations for examples of how this works. In particular, ATLAS uses the same implementation for single and double precision by using these macros, and recompiling the same source with differing index macros. Just to give a quick example, the index macro controlling $\beta$ defines a helper macro BNM which corresponds to the correct beta name for the gemv and ger kernels. Using this trick, we can reduce:

#ifdef BETA0
   #ifdef Conj_
      void ATL_dgemvNc_a1_x1_b0_y1
   #else
      void ATL_dgemvN_a1_x1_b0_y1
   #endif
#elif defined (BETA1)
   #ifdef Conj_
      void ATL_dgemvNc_a1_x1_b1_y1
   #else
      void ATL_dgemvN_a1_x1_b1_y1
   #endif
#elif defined (BETAXI0)
   #ifdef Conj_
      void ATL_dgemvNc_a1_x1_bXi0_y1
   #else
      void ATL_dgemvN_a1_x1_bXi0_y1
   #endif
#else
   #ifdef Conj_
      void ATL_dgemvNc_a1_x1_bX_y1
   #else
      void ATL_dgemvN_a1_x1_bX_y1
   #endif
#endif

to:

#include "atlas_misc.h"

#ifdef Conj_
   void Mjoin(Mjoin(ATL_dgemvNc_a1_x1,BNM),_y1)
#else
   void Mjoin(Mjoin(ATL_dgemvN_a1_x1,BNM),_y1)
#endif