====== Compile CP2K on macOS ======

This page describes how CP2K can be installed under [[https://en.wikipedia.org/wiki/MacOS|macOS]] ([[https://en.wikipedia.org/wiki/MacOS_Monterey|Monterey]], [[https://en.wikipedia.org/wiki/MacOS_Ventura|Ventura]], and [[https://en.wikipedia.org/wiki/MacOS_Sonoma|Sonoma]]
). This howto has last been tested on an Apple M1 under macOS Sonoma 14.3 (Darwin Kernel Version 23.3.0, Homebrew 4.2.5). For further details check the corresponding Darwin-gnu-arm64 [[https://github.com/cp2k/cp2k/blob/master/arch/Darwin-gnu-arm64.psmp|arch file]] and [[https://dashboard.cp2k.org/archive/darwin-gnu-arm64-psmp/index.html|regression tester]]. This howto assumes that your default shell is ''bash''.

==== 1. Install Homebrew ====

Open a Terminal and run the command
<code>
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
</code>
which will install the latest Homebrew version. This howto was tested with Homebrew 3.6.11 as well as with newer versions up to 4.2.5.

=== a) The easy way ===

If you are only interested in testing CP2K under macOS, then you can install a pre-compiled CP2K binary providing all basic features via
<code>
brew install cp2k
</code>
using this [[https://formulae.brew.sh/formula/cp2k|Homebrew formula]]. You can ignore the rest of this how-to, in case you are already happy with that CP2K installation.

=== b) Compile CP2K under macOS from scratch ===

For best performance or code development, it is recommended to install CP2K from scratch. If you installed already CP2K with ''brew'' as described in the previous section, then make sure that you first uninstall ''cp2k'' and unlink its dependencies ''open-mpi'' and ''scalapack'',
e.g. with
<code>
brew uninstall cp2k
brew unlink open-mpi scalapack 
</code>
before you continue to avoid any interference with these Homebrew packages during the installation of the CP2K toolchain.

Create the following links
<code>
ln -s /opt/homebrew/bin/gcc-13 /opt/homebrew/bin/gcc
ln -s /opt/homebrew/bin/g++-13 /opt/homebrew/bin/g++
ln -s /opt/homebrew/bin/gfortran-13 /opt/homebrew/bin/gfortran
</code>
to make Homebrew's latest ''gcc'' and ''g++'' compilers the default instead of the clang versions in ''/usr/bin''. Check with
<code>
gcc -v
</code>
if that is the case.

==== 2. Obtain CP2K ====

Checkout the latest CP2K version available from the [[https://github.com/cp2k/cp2k/|CP2K GitHub repository]] using
<code>
git clone --recursive https://github.com/cp2k/cp2k.git cp2k
</code>

==== 3. Build the CP2K toolchain ====

Change to the new folder ''cp2k''
<code>
cd cp2k
</code>
and run the command
<code>
source arch/Darwin-gnu-arm64.ssmp
</code>
to build the toolchain for a serial CP2K binary.
Alternatively, you can build the toolchain for an MPI/OpenMP parallel CP2K binary with
<code>
source arch/Darwin-gnu-arm64.psmp
</code>

==== 4. Compile CP2K ====

Check the output from the toolchain build in the previous step and if there is no error, run
<code>
make -j ARCH=Darwin-gnu-arm64 VERSION=ssmp
</code>
or
<code>
make -j ARCH=Darwin-gnu-arm64 VERSION=psmp
</code>
as suggested depending on the selected toolchain build.

==== 5. Test the CP2K binary ====

As a final check, you can run a CP2K regression test with
<code>
make -j ARCH=Darwin-arm64 VERSION=psmp test
</code>
to validate the generated CP2K binary. This will run more than 4000 test cases. At the end of that test, a summary is printed which should indicate that there are no ''FAILED'' or ''WRONG'' tests. Instead or running all tests, you can also restrict the testing to certain test folders in ''tests'' by passing ''TESTOPTS'' with the ''make'' command like
<code>
make -j ARCH=Darwin-arm64 VERSION=psmp TESTOPTS="--restrictdir QS/regtest-gpw-1" test
</code>
which will only run the test cases in the folder ''tests/QS/regtest-1''. You can list all available ''TESTOPTS'' with
<code>
tests/do_regtest.py -h
</code>
All data generated by ''test'' can be removed with
<code>
make ARCH=Darwin-arm64 VERSION=psmp testclean
</code>
whereas
<code>
make ARCH=Darwin-arm64 VERSION=psmp realclean
</code>
and
<code>
make distclean
</code>
will remove all data from ''make ARCH=local VERSION=ssmp'' and from any ''make'', respectively.

==== Last but not least ====

Before using CP2K, do not forget to ''source'' always the ''setup'' file with
<code>
source tools/toolchain/install/setup
</code>

It is also suggested to increase the ''OMP_STACKSIZE'' to at least 16 MB
<code>
export OMP_STACKSIZE=16M
ulimit -s 65000
</code>
and the ''stacksize'' to 65 MB (check with ''ulimit -a'').
 
Adding the ''cp2k/exe/local'' folder to your binary search ''PATH''
<code>
export PATH=$PATH:$HOME/github/cp2k/cp2k/exe/local
</code>
will allow for running CP2K just with 
<code>
cp2k.ssmp
</code>
and likewise with ''cp2k.sopt''.

CP2K MPI/OpenMP parallel runs are launched with ''mpirun'' or ''mpiexec'', e.g.
<code>
mpiexec -n 4 -genv OMP_NUM_THREADS=2 cp2k.psmp H2O-32.inp
</code>
will use 4 MPI ranks with 2 OpenMP threads each (i.e. it will consume 8 CPU cores) to run the input file ''H2O-32.inp'' which can be found in  the cp2k folder ''benchmarks/QS''.

The ''cp2k.popt'' binary is only MPI parallel and will run just one thread per MPI rank automatically (like ''cp2k.sopt'') which is usually the most efficient usage of CP2K performance-wise if no memory limitation per MPI rank come into play. Therefore, the following commands
<code>
mpiexec -n 4 -genv OMP_NUM_THREADS=1 cp2k.psmp H2O-32.inp
mpiexec -n 4                         cp2k.popt H2O-32.inp
</code>
are basically equivalent.

**Enjoy CP2K under macOS!**