The linalg library package is a set of selected functions and
subroutines from BLAS and
LAPACK as they are used by and bundled
with the LAMMPS MD code. While the original
BLAS/LAPACK reference implementation from the Netlib servers are written
in a portable Fortran dialect, this library uses the f2c
tool tools to convert them to C++ while
maintaining the expected binary interface from the most common Fortran
compilers on Linux, macOS, Windows platforms. This allows to use it
as a drop-in replacement in case there is no compatible BLAS/LAPACK
binary library package or no Fortran compiler anavailable. It can be
compiled with the same C++ compiler (minimum C++-11 standard) as the
LAMMPS code itself.
There are two exceptions to that binary interface, where the conventions of f2c apply: ZDOTC, ZDOTU,
and ZLADIV return their DOUBLE COMPLEX value through a pointer in an additional first argument,
and the symbol name of DROUNDUP_LWORK has two trailing underscores, since its name contains an
underscore. Fortran code calling those functions needs to be compiled with the -ff2c flag of
gfortran, which applies the same conventions.
The purpose of this package is to provide the source for the translated C++ files bundled with LAMMPS and easily allow to create updated versions for new LAPACK releases or add new functionality if required by added LAMMPS functionality through updating or adding to the Fortran sources and re-running the translation to C++.
Most of the original Fortran code can be translated without change.
Those are placed into the fortran folder. A few other Fortran files
need some small modifications to make them compatible with the f2c
translator. In addition a few BLAS/LAPACK support functions
(e.g. DLAMCH or XERBLA) have been directly implemented in C++. Finally,
a few functions from the f2c runtime library are required as well.
Those have been adapted to C++ and for typical platforms this library is
supposed to be used on.
The included Fortran files correspond to LAPACK version 3.12.1 released
on January 8th, 2025. The exceptions are older Fortran 77 versions of a few functions,
which are listed in static/README.md.
The files in the fortran folder are unmodified copies from LAPACK and should not be edited,
otherwise the changes are lost with the next update. What f2c needs to have changed is done by
the script tools/translate.py during the translation, and a file with the same name in the
static folder has priority over a file in the fortran folder (see static/README.md).
To update to a new LAPACK release or to add functions, use the folder with the LAPACK sources:
tools/update_fortran.py /path/to/lapack [names of new functions]
This copies the current version of all files, the new functions, and all functions that those
call. It also reports functions where LAPACK only has a Fortran 90 version, which then need a
Fortran 77 version in the static folder, and files where the version in the static folder
may need the same change as LAPACK. A Fortran feature that f2c cannot translate stops the
translation with an error.
After updating to a new LAPACK release, please also change the version and checksum of the
download in tests/upstream.cmake, so that its tests use the same release.
Since the bulk of the code is an automated translation of the BLAS/LAPACK
sources, the same licensing terms apply. Additional or replacement code
is copyright (c) 2022, 2023, 2024, 2025 by Axel Kohlmeyer <akohlmey@gmail.com>.
This package uses CMake to set up the translation, and compilation plus a few tests. CMake version 3.20 or later is required. Also required are f2c, a C++ compiler, clang-format, and Python 3. This has only been tested on a Linux machine.
The script tools/translate.py does all the steps of translating one
Fortran file. When importing additional files from LAPACK, new option
strings where only the first letter matters (e.g. 'Upper' or
'No transpose') can be added to the list of words at the top of that
script; forgetting a word is harmless.
Running the command:
cmake -S . -B build
Will set up a build folder and
cmake --build build
will do the translation and also try to compile the generated C++ files into a library as well as create a compressed tar file with the translated sources in the build folder.
If a suitable Fortran compiler was found, also a couple of tests for BLAS and LAPACK functions are configured and can be run with ctest.
ctest --test-dir build
A much more thorough check is the test suite of LAPACK itself. It is not used by default, since it needs to download and compile LAPACK twice and requires gfortran on Linux:
cmake -S . -B build -D ENABLE_UPSTREAM_TESTS=on
cmake --build build
ctest --test-dir build -R UPSTREAM -j 4
Each test runs the same input with the translated and with the reference code and fails if the
translated code does worse. The output is in the upstream-results folder in the build folder.
Those tests are compiled with the -ff2c flag, because the translated ZDOTC, ZDOTU, and ZLADIV
functions return their values like f2c does, which is different from what gfortran does by default.