This file is outdated and not very comprehensive. ATLAS installation is covered in detail in ATLAS/doc/atlas_install.pdf. Before doing anything, scope the ATLAS errata file for known errors/problems: http://math-atlas.sourceforge.net/errata.html and apply any bug fixes/workarounds you find there. Note that the documentation on the website will repeat most of this information, and will be much more current. The docs in this tarfile are here mainly for convenience and for users not connected to the net. Others should scope the website for the most current documentation: http://math-atlas.sourceforge.net/faq.html#doc If you are a Windows user please read ATLAS/doc/Windows.txt before proceeding. There are two mandatory steps to ATLAS installation (config & build), as well as three optional steps (test, time, install) and these steps are described in detail below. For the impatient, here is the basic outline: ************************************************** mkdir my_build_dir ; cd my_build_dir /path/to/ATLAS/configure [flags] make ! tune and compile library make check ! perform sanity tests make ptcheck ! checks of threaded code for multiprocessor systems make time ! provide performance summary as % of clock rate make install ! Copy library and include files to other directories ************************************************** If you want to build a dynamic/shared library, see below at header: BUILDING DYNAMIC/SHARED LIBRARIES If you want to build a full LAPACK library (i.e. all of the lapack library, including those lapack routines not natively provided by ATLAS), see: NOTE ON BUILDING A FULL LAPACK LIBRARY ********** Important Install Information: CPU THROTTLING *********** Most OSes (including Linux) now turn on CPU throttling for power management **even if you are using a desktop**. CPU throttling makes pretty much all timings completely random, and so any ATLAS install will be junk. Therefore, before installing ATLAS, turn off CPU throttling. For most PCs, you can switch it off in the BIOS (eg., on my Athlon-64 machine, I can say "No" to "Cool and Quiet" under "Power Management"). Most OSes also provide a way to switch off CPU throttling, but that varies from OS to OS. Under Fedora, at any rate, the following command seemed to work: /usr/bin/cpufreq-selector -g performance On my Core2Duo, cpufreq-selector only changes the parameters of the first CPU, regardless if which cpu you specify. I suspect this is a bug, because on earlier systems, the remaining CPUs were controlled via a logical link to /sys/devices/system/cpu/cpu0/. In this case, the only way I found to force the second processor to also run at its peak frequency was to issue the following as root after setting CPU0 to performance: cp /sys/devices/system/cpu/cpu0/cpufreq/scaling_governor \ /sys/devices/system/cpu/cpu1/cpufreq/scaling_governor More modern and non-broken systems use cpufreq-set, with -c <#> appended to change the performance of each core in turn. For example, to speedup both processors of a dual system you would issue: /usr/bin/cpufreq-set -g performance -c 0 /usr/bin/cpufreq-set -g performance -c 1 On Kubuntu, I had problems with this not working because scaling_max_freq was set to the minimal speed. To fix, I had to first increase the max scaling frequency, which you can do (as root) by (where <#> below is replaced by each processor number eg., 0 and 1 for dual processor system): cd /sys/devices/system/cpu/cpu<#>/cpufreq cp cpuinfo_max_freq scaling_max_freq In Kubuntu 9.10, the only fix I found was to issue: sudo echo "performance" > \ /sys/devices/system/cpu/cpuX/cpufreq/scaling_governor Where 'X' is replaced by each of your cpu numbers in turn (eg., if you have a quad processor, you would issue this command four times, using X=[0,1,2,3]). Under MacOS or Windows, you may be able to change this under the power settings. I have reports that issuing "powercfg /q" in cmd.exe under windows will tell you whether windows is throttling or not. ATLAS config tries to detect if CPU throttling is enabled, but it may not always detect it, and sometimes may detect it after you have disabled it. In the latter case, to force the configure to continue regardless of the results of the CPU throttling probe, read the error message you get when ATLAS's configure dies upon detecting throttling. ********************************** CONFIG ************************************* First, create a directory where you will build ATLAS. It can be anywhere in your filesystem, and does not need to be under the ATLAS/ subdirectory (though it can be if you like). In general, giving it a descriptive name is good, for instance: mkdir ATLAS_Linux_P4E ; cd ATLAS_Linux_P4E From this directory, configure the new directory to build atlas with the command: /path/to/ATLAS/configure [flags] Obviously, "/path/to/ATLAS" is the full or relative path from where you are to the directory created by the ATLAS tarfile. To see a list of available flags to configure type "path/to/ATLAS/configure --help". In general, no flags are required, but there are many useful flags for helping with various problems, in particular changing compilers, setting 32 or 64 bit libraries, etc. To ensure building 32 bit libraries, add the flag -b 32, and -b 64 to force 64 bit libraries (must be using a 64 bit-capable compiler on a 64-bit Operating System). If the machine you are using is not heavily loaded, then you can vastly improve the accuracy of ATLAS's timings by using the wall timer rather than the CPU timer. If you are on a x86, you can get cycle accurate timings by throwing the flag: -D c -DPentiumCPS= So, for my 2.4Ghz machine, I would specify: -D c -DPentiumCPS=2400 Under Linux, you can find a decent estimate of your clock rate by cat /proc/cpuinfo If you can't use the cycle-accurate wall timer, the normal WALL timer is still much more accurate than the CPU timer, and you can use it by adding this to configure: -D c -DWALL ************ Important Compiler Advice ************** For most systems, ATLAS defaults to using the Gnu compiler collection for its ATLAS install. This means configure will automatically search for either g77/gcc or gfortran/gcc. If it can't find them, it will typically stop with an error message. For some platforms, ATLAS knows good flags to use for multiple compilers, and so you may get good flags by simply changing the compiler name. If this doesn't work, you'll need to specify both the compiler name and the flags to use. For the fortran compiler, you can switch the fortran compiler without performance or install penalty on all platforms. To do so, simply add the flags: -C if -F if 'fortran flags' to the configure command. If you need to install ATLAS on a platform that doesn't have a working fortran compiler, you can do so by adding the flag: --nof77 instead. Note that the fortran interface to BLAS and LAPACK cannot be built without a fortran compiler. Note that all compilers used in an ATLAS install must be able to interoperate. For more compiler-controlling flags, add --help to the configure command. *********** Important CLANG Compiler Advice *********** I have never succesfully built ATLAS with clang. Clang produces the wrong answer on many kernels, and poorer performance than gcc on every kernel I've timed. I strongly recommend GNU gcc over Clang/LLVM. ********************************** BUILD ************************************** If config finishes without error, start the build/tuning process by: make build (or just "make") Install times vary widely, depending on whether ATLAS has architectural defaults for your platform, and the speed of your compiler and computer. Under gcc/linux, an install may take as little as 15 minutes for all four types/precisions. On a slow machine lacking architectural defaults, it However, the user is not required to enter any input during the build phase, and all operations are logged, so it is safe to start the install and ignore it until completion. If you experience problems, read the TROUBLESHOOTING section in ATLAS/doc/TroubleShoot.txt. ATLAS/README provides an index of all included ATLAS documentation files. You should then read ATLAS/doc/TestTime.txt for instructions on testing and timing your installation. ******************************* SANITY TEST *********************************** This optional step merely verifies that the built ATLAS libraries are able to pass basic correctness tests. The standard BLAS testers (i.e. those that go with the API, as opposed to those written by the ATLAS group) are written in Fortran77, and so you will need a Fortran compiler installed to run them. If you have no Fortran77, you can amend the directions below by prepending "C_" to all target names (eg., "make C_test") to run only those testers that require a C compiler, but note that in so doing you will get a less rigorously tested library. you can run all the sequential sanity tests by: make check If you have elected to build the threaded library, you can run the same tests with the threaded library with: make ptcheck A successful sanity test will dump a lot of compilation to the window, followed with something like: =========================================================================== DONE BUILDING TESTERS, RUNNING: SCOPING FOR FAILURES IN BIN TESTS: fgrep -e fault -e FAULT -e error -e ERROR -e fail -e FAIL \ bin/Linux_PIIISSE1/sanity.out 8 cases: 8 passed, 0 skipped, 0 failed 4 cases: 4 passed, 0 skipped, 0 failed 8 cases: 8 passed, 0 skipped, 0 failed 4 cases: 4 passed, 0 skipped, 0 failed 8 cases: 8 passed, 0 skipped, 0 failed 4 cases: 4 passed, 0 skipped, 0 failed 8 cases: 8 passed, 0 skipped, 0 failed 4 cases: 4 passed, 0 skipped, 0 failed DONE SCOPING FOR FAILURES IN CBLAS TESTS: fgrep -e fault -e FAULT -e error -e ERROR -e fail -e FAIL \ interfaces/blas/C/testing/Linux_PIIISSE1/sanity.out | \ fgrep -v PASSED make[1]: [sanity_test] Error 1 (ignored) DONE SCOPING FOR FAILURES IN F77BLAS TESTS: fgrep -e fault -e FAULT -e error -e ERROR -e fail -e FAIL \ interfaces/blas/F77/testing/Linux_PIIISSE1/sanity.out | \ fgrep -v PASSED make[1]: [sanity_test] Error 1 (ignored) DONE make[1]: Leaving directory `/home/rwhaley/TEST/TEST/ATLAS3.3.15' =========================================================================== Note that the "Error 1 (ignored)" is coming from grepping for failure, and grep is saying it doesn't find any . . . Assuming you have a fortran compiler, you can also run the full ATLAS testing scripts, which may take over a day to run. If you have installed a full LAPACK library, you can also run the standard LAPACK testers. Please see "EXTENDED ATLAS TESTING" below for more information. ******************* INSTALLING ATLAS FOR MULTIPLE ARCHITECTURES *************** You can install ATLAS from the same source tree on multiple machines at once by simply creating different build directories for each architecture. ********************** BUILDING DYNAMIC/SHARED LIBRARIES ********************** ATLAS natively builds to a static library (i.e. libs that usually end in ".a" under unix and ".lib" under windows). ATLAS always builds such a library, but it can also optionally be requested to build a dynamic/shared library (typically ending in .so for unix or .dll windows and .dylib for OS X). To do this for GNU compilers, you typically just need to add --shared flag to your configure line. If you use non-gnu compilers, you'll need to use -Fa to pass the correct flag(s) to append to force position independent code for each compiler (don't forget the gcc compiler used in the index files). NOTE: Since gcc uses one less int register when compiling with this flag, this could potentially impact performance of the architectural defaults, but we have not seen it so far. ****************** NOTE ON BUILDING A FULL LAPACK LIBRARY ********************* To build lapack, first download the lapack tarfile from www.netlib.org/lapack Then, pass the flag to configure: --with-netlib-lapack-tarfile=/path/to/downloaded/tarfile ***************************** EXTENDED ATLAS TESTING ************************** ATLAS has two extended testers beyond the sanity checks that can be automatically invoked from the BLDdir. These tests are longer running and more complex to interpret than the sanity tests, and so not every user will want to run them. They are particularly recommended for installers who wish to use a developer release for production code. --------------------------------- full_test ----------------------------------- The first is a set of testing scripts written by Antoine Petitet, that randomly generate testcases for a host of ATLAS's testers. This testing phase may take as long as two days to complete (and almost always takes at least 4 hours). To perform this long-running test, simply issue: make full_test If you are logged into the host machine remotely, chances are good your connection will go down before the install completes. Therefore, you should consider running the above command with nohup. At the completion of the tests, the extensive output files will be searched for errors (much as with the sanity tests), and the output sent to the screen. If you have lost this screen of data, you can regenerate it with the command: make scope_full_test Running these tests will create a directory BLDdir/bin/AtlasTest where the tester resides, and your output files will be stored a $(ARCH) subdir. If you want to rerun the testers from scratch (rather than just searching old output), you can simply delete the entire BLDdir/bin/AtlasTest directory tree, and do "make full_test" again. ----------------------------- lapack_test ------------------------------------- If you have installed the full LAPACK library, then you can run the standard lapack testers as well. The command you give is: make lapack_test_[a,s,f]l_[ab,sb,fb,pt] The first choice (choose one of three) controls which LAPACK library macro is used in the link for testing: _l LINK FOR LAPACK Make.inc MACRO == =================== ============== a ATLAS's LAPACK $(LAPACKlib) s system LAPACK $(SLAPACKlib) f F77 reference LAPACK $(FLAPACKlib) The second choice (choose one of three) controls which BLAS macros are used in the link for testing: _b/pt LINK FOR BLAS Make.inc MACRO ==== ===================== ========================================= ab ATLAS BLAS $(F77BLASlib) $(CBLASlib) $(ATLASlib) sb system BLAS $(BLASlib) fb F77 reference BLAS $(FBLASlib) pt ATLAS' threaded BLAS $(PTF77BLASlib) $(PTCBLASlib) $(ATLASlib) Not all of these combinations will work without user modification of Make.inc. You will need to fill in values for $(BLASlib) $(SLAPACKlib) $(FLAPACKlib) if you want to run the lapack tester against these libraries. Usually, you will want to test your newly install ATLAS LAPACK & BLAS: make lapack_test_al_ab As before, once the testing is complete, you will get the output of a search for errors though all output files, and you can search them again with: make scope_lapack_test_al_ab Unfortunately, the lapack testers always show errors on almost all platforms. So, how do you know if you have a real error? Real errors will usually have residuals in the 10^6 range, rather than O(1) (smaller residuals mean less error). If you are unsure, the best way is to contrast ATLAS with an all-F77 install: make lapack_test_fl_fb (To run this test, you will have to build a stock netlib LAPACK library, and fill out Make.inc's FLAPACKlib macro appropriately.) You can then see how the errors reported by ATLAS stack up against the all-F77 version: if they are roughly the same, then you are usually OK. All the lapack testers create a directory BLDdir/bin/LAPACK_TEST. For each test you run there will be a subdirectory LAOUT_[A,S,F]L_[AB,SB,FB,PT] where all your output files will be located. Additionally, the results of the scope (search for error) will be stored in BLDdir/bin/LAPACK_TEST/SUMMARY__ Therefore, a typical round of testing might be: make lapack_test_al_ab make lapack_test_fl_fb # compare SUMMARY_al_ab with SUMMARY_fl_fb to check for error make lapack_test_al_pt # compare SUMMARY_al_pt with SUMMARY_fl_fb to check for error in parallel lib If you had an error, you might want to be sure the error was in ATLAS's BLAS and not lapack, so you could do "make lapack_test_fl_ab", and see if the error went away. If you filled in the GotoBLAS for the SLAPACKlib & BLASlib macros, you could scope the error properties of Goto's BLAS and LAPACK. Many system/vendor LAPACK/BLAS do not provide all of the routines required to run the LAPACK testers, and some ATLAS testers call ATLAS internal routines. Therefore, the safest thing if you have missing symbol errors when building system/vendor tests, is to use ATLAS to pick up any missing symbols. For instance, here is an example Make.inc output that makes all of ATLAS testers work with the GotoBLAS on my Athlon-64 workstation: BLASlib = /opt/lib/libgoto_opteronp-r1.26.a \ $(F77BLASlib) $(CBLASlib) $(ATLASlib) SLAPACKlib = /opt/lib/libgoto_opteronp-r1.26.a $(FLAPACKlib)