Obtaining the code¶
The latest version of MRCPP is available on GitHub:
$ git clone git@github.com:MRChemSoft/mrcpp.git
Building the code¶
Prerequisites¶
Configuration¶
The configuration and build process is managed through CMake, and a setup
script is provided for the configuration step. MRCPP’s only dependency is
Eigen3, which will be downloaded at configure time unless it is already
available on the system. If you have a local version not under the system
path, you can point to it before running setup
:
$ export EIGEN3_ROOT=/path/to/eigen3
$ ./setup [options] [<builddir>]
The setup script will create a directory called <builddir> (default build
)
and run CMake. There are several options available for the setup, and the most
important are:
--cxx=<CXX>
C++ compiler [default: g++]
--omp
Enable OpenMP parallelization [default: False]
--mpi
Enable MPI parallelization [default: False]
--enable-tests
Enable tests [default: True]
--enable-examples
Enable tests [default: False]
--type=<TYPE>
Set the CMake build type (debug, release, relwithdebinfo, minsizerel) [default: release]
--prefix=<PATH>
Set the install path for make install
-h --help
List all options
Compilation¶
After successful configuration, the code is compiled using the make
command
in the <builddir> directory:
$ cd <builddir>
$ make
Running tests¶
A set of tests is provided with the code to verify that the code compiled
properly. To compile the test suite, add the --enable-tests
option to
setup, then run the tests with ctest
:
$ ./setup --enable-tests build
$ cd build
$ make
$ ctest
Running examples¶
In addition to the test suite, the code comes with a number of small code
snippets that demonstrate the features and the API of the library. These are
located in the examples
directory. To compile the example codes, add the
enable-examples
option to setup, and the example executables can be found
under <build-dir>/bin/
. E.g. to compile and run the MW projection example:
$ ./setup --enable-examples build-serial
$ cd build-serial
$ make
$ bin/projection
The shared memory parallelization (OpenMP) is controlled by the environment
variable OMP_NUM_THREADS
(make sure you have compiled with the --omp
option to setup). E.g. to compile and run the Poisson solver example using 10
CPU cores:
$ ./setup --enable-examples --omp build-omp
$ cd build-omp
$ make
$ OMP_NUM_THREADS=10 bin/poisson
To run in MPI parallel, use the mpirun
(or equivalent) command (make sure
you have compiled with the --mpi
option to setup, and used MPI compatible
compilers, e.g. --cxx=mpicxx
). Only examples with an mpi prefix will be
affected by running in MPI:
$ ./setup --cxx=mpicxx --enable-examples --mpi build-mpi
$ cd build-mpi
$ make
$ mpirun -np 4 bin/mpi_send_tree
To run in hybrid OpenMP/MPI parallel, simply combine the two above:
$ ./setup --cxx=mpicxx --enable-examples --omp --mpi build-hybrid
$ cd build-hybrid
$ make
$ export OMP_NUM_THREADS=5
$ mpirun -np 4 bin/mpi_send_tree
Note that the core of MRCPP is only OpenMP parallelized. All MPI data or work distribution must be done manually in the application program, using the tools provided by MRCPP (see the Parallel section of the API).
Pilot code¶
Finally, MRCPP comes with a personal sandbox where you can experiment and test
new ideas, without messing around in the git repository. In the pilot/
directory you will find a skeleton code called mrcpp.cpp.sample
. To trigger
a build, re-name (copy) this file to mrcpp.cpp
:
$ cd pilot
$ cp mrcpp.cpp.sample mrcpp.cpp
Now a corresponding executable will be build in <builddir>/bin/mrcpp-pilot/
.
Feel free to do whatever you like in your own pilot code, but please don’t add
this file to git. Also, please don’t commit any changes to the existing examples
(unless you know what you’re doing).
MRCPP as a dependency¶
Building MRCPP provides CMake configuration files exporting the libraries and headers as targets to be consumed by third-party projects also using CMake:
$ ./setup --prefix=$HOME/Software/mrcpp
$ cd build
$ make
$ ctest
$ make install
Now libraries, headers and CMake configuration files can be found under the given prefix:
mrcpp/
├── include/
│ └── MRCPP/
├── lib64/
│ ├── libmrcpp.a
│ ├── libmrcpp.so -> libmrcpp.so.1*
│ └── libmrcpp.so.1*
└── share/
└── cmake/
As an example, the pilot
sample can be built with the following CMakeLists.txt
:
cmake_minimum_required(VERSION 3.11 FATAL_ERROR)
project(UseMRCPP LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 14)
set(CMAKE_CXX_EXTENSIONS OFF)
set(CMAKE_CXX_STANDARD_REQUIRED ON)
include(GNUInstallDirs)
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_LIBDIR})
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${PROJECT_BINARY_DIR}/${CMAKE_INSTALL_BINDIR})
find_package(MRCPP CONFIG REQUIRED)
get_property(_loc TARGET MRCPP::mrcpp PROPERTY LOCATION)
message(STATUS "Found MRCPP: ${_loc} (found version ${MRCPP_VERSION})")
add_executable(mrcpp mrcpp.cpp)
target_link_libraries(mrcpp
PUBLIC
MRCPP::mrcpp
)
set_target_properties(mrcpp
PROPERTIES
MACOSX_RPATH ON
SKIP_BUILD_RPATH OFF
BUILD_WITH_INSTALL_RPATH OFF
INSTALL_RPATH "$ORIGIN/../${CMAKE_INSTALL_LIBDIR}"
INSTALL_RPATH_USE_LINK_PATH ON
)
This will set up the include paths and library paths correctly. During configuration you will have to specify where the CMake configuration file for MRCPP is located:
$ cmake -H. -Bbuild -DMRCPP_DIR=$HOME/Software/share/cmake/MRCPP