CompilingADDA

• Quick recipes
  • Unix
  • macOS
  • Windows
• Basic explanation and dependencies
• Compilation targets
• Compilation options
• Portability

Quick recipes

In the following we provide short recipes which may work out of the box on most systems. They allow one to compile sequential (standard), MPI (for distributed-memory clusters) and OpenCL (for GPU acceleration) versions of ADDA. If these recipes do not work or you want to understand all available compilation modes and options, scroll below. Before executing the recipes, download the ADDA package (source) and position yourself in its src/ directory. For instance, this may be accomplished by (if you have git installed):

git clone https://github.com/adda-team/adda.git
cd adda/src

Each recipe consists of three parts. First two lines compile sequential ADDA, while the remaining lines are optional (for MPI and OCL parts). After the recipe is finished, compiled executables are src/seq/adda, src/mpi/adda_mpi, and src/ocl/adda_ocl, respectively. You can also combine all package installations into one command, and all ADDA compilations – into a single make all.

Unix

The following is based on apt, the default package manager for Ubuntu. You can, naturally, use apt-get instead, while many other package manager on any Unix system will require only minor modifications of the package names.

sudo apt install gcc gfortran libfftw3-dev
make seq
sudo apt install libopenmpi-dev
make mpi
sudo apt install ocl-icd-opencl-dev libclfft-dev
make ocl

macOS

The following is based on Homebrew, a popular package manager for macOS, while other managers may work similarly. Unfortunately, we are not aware of a perfect recipe for macOS, hence, describe three options, each having some drawbacks. The first option is for GCC 13.3 or later:

brew install gcc fftw 
export CPATH=`xcrun --show-sdk-path`/usr/include
export LDFLAGS=-L`xcrun --show-sdk-path`/usr/lib
make seq OPTIONS=HOMEBREW CC=gcc-13
brew install open-mpi
make mpi OPTIONS=HOMEBREW CC=gcc-13
brew install clfft
make ocl OPTIONS=HOMEBREW CC=gcc-13

The above commands use the GCC compiler instead of the default Clang for C and C++ sources. This is required for automatic linking of standard Fortran libraries (used by GFortran included in the latest gcc package), but may slightly decrease runtime performance and require changes with each major gcc update. Moreover, it is broken by a GCC bug, which should be fixed in GCC 13.3 (all earlier versions are affected).

The second option is to replace CC=gcc-13 above by FORT_LIB_PATH=/opt/homebrew/Cellar/gcc/13.2.0/lib/gcc/13 (requires changes with each minor gcc update). This employs Clang for C and C++ sources, and Gfortran from gcc package – for Fortran ones.

The third option is:

• install gfortran with a standalone installer
• replace CC=gcc-13 above by FORT_LIB_PATH=/usr/local/gfortran/lib
• after compilation, update the paths to Gfortran library in the executables (can be replaced by environment setting or additional options to linker):

install_name_tool -add_rpath /usr/local/gfortran/lib seq/adda
install_name_tool -add_rpath /usr/local/gfortran/lib mpi/adda_mpi
install_name_tool -add_rpath /usr/local/gfortran/lib ocl/adda_ocl

Another issue with all these recipes is that OpenCL part, specifically clFFT package, does not work out of the box.

Windows

Compiling ADDA on Windows is less straightforward, thus we recommend to use precompiled executables for 64-bit Windows.

If you still want to compile ADDA yourself, we provide both quick and detailed instructions for that using MinGW-w64 tools.

Alternatively, you can use:

• MSYS2. It has a built-in package manager, simplifying the procedure, but has some limitations (see our experience with it).
• Windows Subsystem for Linux (WSL). Then you will have Ubuntu inside Windows – just follow the instructions above. Importantly, if you obtain the source by git clone, this should be done inside the WSL. And the compiled binaries can be executed only inside the WSL. OpenCL support inside the WSL is also limited – try it at your own risk.

Basic explanation and dependencies

ADDA can be compiled on any system with GNU make (version 3.81 or higher) and C, Fortran, and C++ compilers installed. Core parts of ADDA are written in C, while Fortran and C++ are used for relatively small parts that are not always required (see below). make command should be run in the src/ directory of the ADDA repository (package) – possible targets are listed below. This page covers only the compilation itself; using IDEs (either for changing or exploring/debugging the source code) is mentioned in wiki section for contributors.

The Makefile is designed to work out of the box on many systems using GNU compilers (intercompatible versions of gcc and gfortran are required). However, FFTW3 package need to be installed on your system. Moreover, MPI version of ADDA requires installed MPI implementation. Using the latter, ADDA can run both on multiprocessor systems (clusters) and on multicore processors of a single PC, as well as on heterogeneous hardware.

The OpenCL version of ADDA is designed to use graphic cards (GPUs) to accelerate computations. It requires OpenCL environment and clFFT library (alternatively, slower built-in OpenCL FFT routines can be used). The future goal is to make OpenCL version capable of running on other compatible hardware, including hybrid CPU-GPUs and Cell processors.

As mentioned above, the dependencies can usually be installed with a few command lines on Unix and macOS systems. In case of problems or Windows, see the separate wiki pages. Finally, we recommend to compile and run ADDA on a 64-bit operating system to avoid any limitations on memory usage.

Compilation targets

Full list of possible targets (arguments to make) is the following:

Target	Description
all	The default target (if none is specified). Invokes seq, mpi, and ocl.
seq	Compiles sequential executable of ADDA.
mpi	Compiles parallel (MPI) executable of ADDA.
ocl	Compiles OpenCL (GPU accelerated) executable of ADDA.
cleanfull	Removes all files produced during compilation and ADDA runs. Invokes clean and cleanruns.
clean	Removes all files produced during compilation. Invokes cleanseq, cleanmpi, and cleanocl.
cleanseq	Removes files produced during compilation of sequential version (located in src/seq/).
cleanmpi	Removes files produced during compilation of MPI version (located in src/mpi/).
cleanocl	Removes files produced during compilation of OpenCL version (located in src/ocl/).
cleanruns	Removes all files produced during ADDA runs. Invokes cleanrunsseq, cleanrunsmpi, and cleanrunsocl.
cleanrunsseq	Removes files produced during run of sequential version (located in src/seq/).
cleanrunsmpi	Removes files produced during run of MPI version (located in src/mpi/).
cleanrunsocl	Removes files produced during run of OpenCL version (located in src/ocl/).

Compilation options

The details of compilation are controlled by a number of options (described in a table below), which can be specified by three different methods. First, one may change or uncomment the corresponding lines in the Makefile, starting with name = ... or override name += , where name is the option name. These lines are accompanied by a lot of descriptive comments. Second, these options may be set as environmental variables before executing make. Third, they may be given as additional command line parameters when invoking make, for example

make COMPILER=intel OPTIONS="DEBUG FFT_TEMPERTON" ...

Note that multi-word value of OPTIONS need to be enclosed in quotes.

Name	Value	Description
COMPILER	one of
	gnu	GNU compilers. The default value.
	intel	Intel classic compilers
	intelX	Intel oneAPI compilers (based on LLVM)
	compaq	Compaq compilers. Has not been recently tested, hence may need modification of compiler flags.
	ibm	IBM compilers. Has not been recently tested, hence may need modification of compiler flags.
	hpux	Specific options for HP-UX ia64 environment
	other	Use this if none of the above works. Need manual specification of compiler flags (see below).
OPTIONS	any combination of
	DEBUG	Turns on producing debug symbols (-g) and warnings by the compiler and slightly reduces optimization level. This option is irrelevant, if DEBUGFULL is used.
	DEBUGFULL	Same as DEBUG, but turns off optimization completely and turns on additional diagnostic messages in the source code.
	FFT_TEMPERTON	Uses built-in FFT routines by C. Temperton. This is recommended if you have problems installing FFTW3.
	PRECISE_TIMING	Enables precise timing routines, which give extensive timing of all the computation parts of ADDA, useful for debugging or optimization studies.
	NOT_USE_LOCK	Does not use file locking for ExpCount at all. Enable this flag if you get compilation errors due to unsupported operation system (e.g. #83) or experience permanent locks.
	ONLY_LOCKFILE	Uses lock file to lock ExpCount, but do not additionally lock this file. Use it if you get warnings when running ADDA stating that your system does not support advanced file locking. This option is irrelevant for non-POSIX systems or if NOT_USE_LOCK is used.
	NO_FORTRAN	Disables compilation of all Fortran sources. Use it only if compilation of these files causes problems. Corresponding ADDA features, namely integration of Green's tensor (-int igt), are then disabled. Also, this option is incompatible with FFT_TEMPERTON.
	NO_CPP	Disables compilation of all C++ sources. Use it only if compilation of these files causes problems. Currently, it is only relevant for OpenCL version with Apple clFFT routines.
	OVERRIDE_STDC_TEST	Disables compilation errors if compiler does not declare its C99 conformance. Use it only if you are sure that compiler supports those C99 features that are essential for ADDA.
	OCL_READ_SOURCE_RUNTIME	Enables reading of OpenCL sources from file during the runtime of ADDA. This option is recommended if the default way (incorporating it into ADDA executable) is not working. The drawback is that oclkernels.cl should be moved together with executable.
	SPARSE	Compile ADDA in SparseMode (non-FFT).
	USE_SSE3	Enable SSE3 optimizations for the gcc compiler and hardware that supports it (most hardware do nowadays). This is used for the calculation of the dipole interaction term, and may yield minor acceleration when used in conjunction with the SPARSE option (#sse). In normal mode the benefits are negligible.
	CLFFT_APPLE	Uses built-in clFFT routines by Apple for OpenCL version (requires C++ compiler). This is recommended if you have problems installing clFFT.
	OCL_BLAS	Uses clBLAS library (need to be separately installed) for iterative solver (under development, currently only works with the BiCG method)
	NO_GITHASH	Disables obtaining the current git hash of the source code during compilation. Use it only if the corresponding procedure causes any problems.
	HOMEBREW	Adds paths to libraries and headers of packages installed by Homebrew (using environmental variable HOMEBREW_PREFIX). Use this option if these paths are not set system-wide.
EXTRA_FLAGS	any	Additional flags to be passed to the compiler (for all languages). For instance, -m32 to compile 32-bit binaries in a 64-bit environment.
FFTW3_INC_PATH	path	Path to directory with FFTW3 headers. May be not needed, if FFTW3 is installed on a whole system.
FFTW3_LIB_PATH	path	Path to directory with FFTW3 library. May be not needed, if FFTW3 is installed on a whole system.
FORT_LIB_PATH	path	Path to directory with Fortran libraries. Usually not needed, except for some macOS systems.

Although Makefile contain options for several compilers, described above, the new releases are usually tested only with GNU compilers. So the options for other compilers may be outdated. If you modify these options to successfully compile the current version of ADDA, please communicate these modifications to the discussion group, so they can be incorporated in future releases.

To use COMPILER=other one should manually add definitions of corresponding compiler flags to the Makefile, according to the pattern used for predefined compilers, after the line

ifeq ($(COMPILER),other)

If you do so, please write to the discussion group, so this compiler can be incorporated in future releases. Please also write to this group if you use one of the supported compilers with OPTIONS=DEBUG and obtain any warnings.

If compilation of MPI version does not work out-of-box, you may need to modify mpi/Makefile. This may include specifying a particular compiler wrapper (setting variable MPICC) and paths to compiler headers and libraries. For the latter uncomment and adjust lines starting with CFLAGS += -I and LFLAGS += -L accordingly. Please see comments in the file for more details.

If compilation of OpenCL version does not work out-of-box, you may need to modify ocl/Makefile to explicitly specify paths to headers and libraries. For this uncomment and adjust lines starting with CFLAGS += -I and LFLAGS += -L accordingly. Please see comments in the file for more details.

When asked to repeat compilation, make automatically determines, which source files need to be recompiled. Apart from changes in the source files themselves the logic of makefiles also considers the differences in compilation options between current and previous compilation. Thus, it is not necessary to perform any cleaning between the compilations with different options.

Portability

ADDA is intended to be portable to as wide range of platforms as possible. There are only two operating-system-dependent aspects of ADDA: precise timing and file locking. Both are optional (controlled by compilation flags, see above) and should be functional on any Windows or POSIX-compliant (Unix, macOS) operating system.

If all of the above doesn't work, one may compile all source files (with maximum possible optimizations) and link them into an executable. In that case adjusting some of compilation options is possible by uncommenting defines in corresponding header files (see comments in the Makefile).