Modernize MRCPP

.circleci/config.yml

@@ -1,9 +1,9 @@
 version: 2
 
 variables:
-  ubuntu-2004: &ubuntu-2004
+  ubuntu-2404: &ubuntu-2404
     docker:
-      - image: ghcr.io/mrchemsoft/metamr/circleci_ubuntu-20.04:sha-343e011
+      - image: ghcr.io/mrchemsoft/metamr/circleci_ubuntu-24.04:sha-2b5887e
         name: tsubame
         user: merzbow
     working_directory: ~/mrcpp
@@ -55,14 +55,14 @@ variables:
 
 jobs:
   serial-py3:
-    <<: *ubuntu-2004
+    <<: *ubuntu-2404
     steps:
       - checkout
       - *configure-serial
       - *build
       - *tests
   omp-py3:
-    <<: *ubuntu-2004
+    <<: *ubuntu-2404
     environment:
       - OMP_NUM_THREADS: '2'
     steps:
@@ -71,7 +71,7 @@ jobs:
       - *build
       - *tests
   mpi-py3:
-    <<: *ubuntu-2004
+    <<: *ubuntu-2404
     steps:
       - checkout
       - *configure-mpi

CMakeLists.txt

@@ -2,11 +2,16 @@
 # Copyright (c) 2015-2020 by Radovan Bast, Roberto Di Remigio, Jonas Juselius, and contributors.
 
 # set minimum cmake version
-cmake_minimum_required(VERSION 3.14 FATAL_ERROR)
+cmake_minimum_required(VERSION 3.22 FATAL_ERROR)
 
 # project name
 project(MRCPP LANGUAGES CXX)
 
+# Suppress warning for policy CMP0177
+if(CMP0177)
+    cmake_policy(SET CMP0177 OLD)
+endif()
+
 # do not rebuild if rules (compiler flags) change
 set(CMAKE_SKIP_RULE_DEPENDENCY TRUE)
 

cmake/compiler_flags/CXXFlags.cmake

@@ -18,24 +18,28 @@ set(CMAKE_CXX_STANDARD_REQUIRED TRUE)
 set(CMAKE_CXX_EXTENSIONS FALSE)
 set(CMAKE_EXPORT_COMPILE_COMMANDS TRUE)
 
-if(ENABLE_ARCH_FLAGS)
-  # iterate over list of flags and use the first one that is compatible with the
-  # compiler in use
-  if(CMAKE_CXX_COMPILER_ID MATCHES GNU)
-    set(_arch_flag "-march=native")
+# Enforce minimum compiler versions for C++17 support
+if(CMAKE_CXX_COMPILER_ID MATCHES GNU)
+  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "11.2")
+    message(FATAL_ERROR "GCC >= 11.2 required, found ${CMAKE_CXX_COMPILER_VERSION}")
   endif()
-  if(CMAKE_CXX_COMPILER_ID MATCHES Clang)
-    set(_arch_flag "-march=native")
+elseif(CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "14.0")
+    message(FATAL_ERROR "Clang >= 14.0 required, found ${CMAKE_CXX_COMPILER_VERSION}")
   endif()
-  if(CMAKE_CXX_COMPILER_ID MATCHES Intel)
-    set(_arch_flag "-xHost")
+elseif(CMAKE_CXX_COMPILER_ID MATCHES "IntelLLVM")
+  if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS "2022.1")
+    message(FATAL_ERROR "Intel oneAPI (icx) >= 2022.1 required, found ${CMAKE_CXX_COMPILER_VERSION}")
   endif()
+endif()
+
+if(ENABLE_ARCH_FLAGS)
+  set(_arch_flag "-march=native")
   message(STATUS "Adding architecture-specific compiler flag: ${_arch_flag}")
   set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${_arch_flag}")
 endif()
 
 include(${CMAKE_CURRENT_LIST_DIR}/GNU.CXX.cmake)
-include(${CMAKE_CURRENT_LIST_DIR}/Intel.CXX.cmake)
 include(${CMAKE_CURRENT_LIST_DIR}/Clang.CXX.cmake)
 
 string(REPLACE " " ";" _cmake_cxx_flags ${CMAKE_CXX_FLAGS})

docs/install.rst

@@ -1,42 +1,60 @@
+============
+Installation
+============
+
 ------------------
 Obtaining the code
 ------------------
 
-The latest version of MRCPP is available on `GitHub
-<http://github.com/MRChemSoft/mrcpp>`_::
+The latest development version of MRCPP can be found on the ``master``
+branch on GitHub::
 
-    $ git clone git@github.com:MRChemSoft/mrcpp.git
+    $ git clone https://github.com/MRChemSoft/mrcpp.git
 
+The released versions can be found from Git tags ``vX.Y.Z`` under the
+``release/X.Y`` branches in the same repository, or a zip file can be
+downloaded from `Zenodo <https://doi.org/10.5281/zenodo.3606670>`_.
 
------------------
-Building the code
------------------
+By default, all dependencies will be **fetched** at configure time if they are
+not already available.
 
 
-Prerequisites
--------------
+-------------------
+Build prerequisites
+-------------------
 
-* g++-5.4 or later (``std=c++14``)
-* `CMake <http://cmake.org>`_ version 3.11 or higher.
-* `Eigen <http://eigen.tuxfamily.org>`_ version 3.3 or higher.
-* BLAS (optional)
+- CMake-3.22 (or later)
+- GNU-11.2, Clang-14.0 or IntelLLVM-2022.1 (or later) compilers (C++17 standard)
 
+.. hint::
+    We have collected the recommended modules for the different Norwegian HPC
+    systems under ``tools/<machine>.env``. These files can be sourced in order
+    to get a working environment on the respective machines, and may also serve
+    as a guide for other HPC systems.
+
 
-Configuration
--------------
+C++ dependencies
+----------------
 
-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``::
+- Linear algebra: `Eigen-3.4  <https://gitlab.com/libeigen/eigen>`_
+- BLAS (optional)
 
-    $ export EIGEN3_ROOT=/path/to/eigen3
-    $ ./setup [options] [<builddir>]
+Eigen will be downloaded automatically at configure time by CMake,
+but can also be linked manually by setting the variable::
 
-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:
+    EIGEN3_DIR=<path_to_eigen3>/share/eigen3/cmake
+
+
+-----------------
+Building the code
+-----------------
+
+Configure
+---------
+
+The ``setup`` script will create a directory called ``<build-dir>`` and run
+CMake. There are several options available for the setup, the most
+important being:
 
 ``--cxx=<CXX>``
   C++ compiler [default: g++]
@@ -55,31 +73,103 @@ important are:
 ``-h --help``
   List all options
 
+The code can be built with four levels of parallelization:
 
-Compilation
------------
+ - no parallelization
+ - only shared memory (OpenMP)
+ - only distributed memory (MPI)
+ - hybrid OpenMP + MPI
 
-After successful configuration, the code is compiled using the ``make`` command
-in the *<builddir>* directory::
+.. note::
+    In practice we recommend the **shared memory version** for running on your
+    personal laptop/workstation, and the **hybrid version** for running on a
+    HPC cluster. The serial and pure MPI versions are only useful for debugging.
 
-    $ cd <builddir>
-    $ make
+The default build is *without* parallelization and using GNU compilers::
+
+    $ ./setup --prefix=<install-dir> <build-dir>
+
+To use clang compilers you need to specify the ``--cxx`` option::
+
+    $ ./setup --prefix=<install-dir> --cxx=clang++ <build-dir>
+
+To build the code with shared memory (OpenMP) parallelization,
+add the ``--omp`` option::
 
+    $ ./setup --prefix=<install-dir> --omp <build-dir>
 
--------------
-Running tests
--------------
+To build the code with distributed memory (MPI) parallelization, add the
+``--mpi`` option *and* change to the respective MPI compilers (``--cxx=mpicxx``
+for GNU)::
 
-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 --prefix=<install-dir> --omp --mpi --cxx=mpicxx <build-dir>
 
-    $ ./setup --enable-tests build
-    $ cd build
+.. note::
+    If you compile the MRCPP library manually as a separate project, the level
+    of parallelization **must be the same** for MRCPP and MRChem. Similar
+    options apply for the MRCPP setup, see
+    `mrcpp.readthedocs.io <https://mrcpp.readthedocs.io/en/latest/>`_.
+
+
+Build
+-----
+
+If the CMake configuration is successful, the code is compiled with::
+
+    $ cd <build-dir>
     $ make
+
+
+Test
+----
+
+A test suite is provided to make sure that everything compiled properly.
+To run a collection of small tests::
+
+    $ cd <build-dir>
     $ ctest
 
 
+Install
+-------
+
+After the build has been verified with the test suite, it can be installed with
+the following command::
+
+    $ cd <build-dir>
+    $ 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/
+
+Please refer to the :ref:`User's Manual` for instructions for how to run the program.
+
+.. hint::
+    We have collected scripts for configure and build of the hybrid OpenMP + MPI
+    version on the different Norwegian HPC systems under ``tools/<machine>.sh``.
+    These scripts will build the current version under ``build-${version}``,
+    run the unit tests and install under ``install-${version}``, e.g. to build
+    version v1.5.0 on Olivia::
+
+        $ cd mrcpp
+        $ git checkout v1.5.0
+        $ tools/olivia.sh
+
+    The configure step requires internet access, so the scripts must be run on
+    the login nodes, and it will run on a single core, so it might take some
+    minutes to complete. 
+
+
 ----------------
 Running examples
 ----------------
@@ -127,6 +217,7 @@ 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
 ----------
@@ -144,32 +235,6 @@ 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``:
 
 .. literalinclude:: snippets/CMakeLists.txt

external/upstream/fetch_eigen3.cmake

@@ -1,20 +1,25 @@
-find_package(Eigen3 CONFIG QUIET
-  NO_CMAKE_PATH
-  NO_CMAKE_PACKAGE_REGISTRY
-  )
-
+if(EIGEN3_FIND_BEHAVIOUR STREQUAL "default" OR EIGEN3_FIND_BEHAVIOUR STREQUAL "onlylocal")
+  find_package(Eigen3 3.4 CONFIG QUIET
+    NO_CMAKE_PATH
+    NO_CMAKE_PACKAGE_REGISTRY
+    NO_CMAKE_SYSTEM_PACKAGE_REGISTRY
+    )
+endif()
 if(TARGET Eigen3::Eigen)
-  message(STATUS "Using Eigen3: ${EIGEN3_ROOT_DIR} (version ${Eigen3_VERSION})")
-else()
+  message(STATUS "Found Eigen3: ${EIGEN3_ROOT_DIR} (version ${Eigen3_VERSION})")
+elseif(EIGEN3_FIND_BEHAVIOUR STREQUAL "default" OR EIGEN3_FIND_BEHAVIOUR STREQUAL "onlyfetch")
   message(STATUS "Suitable Eigen3 could not be located. Fetching and building!")
   include(FetchContent)
 
   FetchContent_Declare(eigen3
     QUIET
     URL
       https://gitlab.com/libeigen/eigen/-/archive/3.4.0/eigen-3.4.0.tar.gz
+    DOWNLOAD_EXTRACT_TIMESTAMP TRUE
     )
 
   set(BUILD_TESTING OFF CACHE BOOL "" FORCE)
   FetchContent_MakeAvailable(eigen3)
+else()
+  message(FATAL_ERROR "No suitable Eigen3 found or fetched. Aborting setup!")
 endif()