v4-CMake

CMakeLists.txt

@@ -0,0 +1,330 @@
+# author : Ania Brown
+# author : Jacob Wilkins
+# author : Balint Koczor (Windows compatibility)
+# author : Tyson Jones (testing)
+# author : Oliver Thomson Brown (v4)
+
+cmake_minimum_required(VERSION 3.21)
+
+project(QuEST
+  VERSION 4.0.0
+  DESCRIPTION "Quantum Exact Simulation Toolkit"
+  LANGUAGES CXX C
+)
+
+## Dependencies
+
+# GNUInstallDirs to provide sensible default install directory names
+include(GNUInstallDirs)
+
+# Maths
+if (NOT MSVC)
+  find_library(MATH_LIBRARY m REQUIRED)
+endif()
+
+## Configuration options
+
+# Build type
+# Default to "Release"
+# Using recipe from Kitware Blog post
+# https://www.kitware.com/cmake-and-the-default-build-type/
+set(default_build_type "Release")
+if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  message(STATUS "Setting build type to '${default_build_type}' as none was specified.")
+  set(CMAKE_BUILD_TYPE "${default_build_type}" CACHE
+      STRING "Choose the type of build." FORCE)
+  # Set the possible values of build type for cmake-gui
+  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS
+    "Debug" "Release" "MinSizeRel" "RelWithDebInfo")
+endif()
+
+# Library type
+# Shared library by default
+option(BUILD_SHARED_LIBS "Build shared library. Turned ON by default." ON)
+message(STATUS "Shared library is turned ${BUILD_SHARED_LIBS}. Set BUILD_SHARED_LIBS to modify.")
+
+# Library naming
+set(LIB_NAME QuEST 
+  CACHE 
+  STRING
+  "Change library name. LIB_NAME is QuEST by default."
+)
+message(STATUS "Library will be named lib${LIB_NAME}. Set LIB_NAME to modify.")
+
+option(VERBOSE_LIB_NAME "Modify library name based on compilation configuration. Turned OFF by default." OFF)
+message(STATUS "Verbose library naming is turned ${VERBOSE_LIB_NAME}. Set VERBOSE_LIB_NAME to modify.")
+
+# Precision
+set(FLOAT_PRECISION 2 
+  CACHE 
+  STRING 
+  "Whether to use single, double, or quad floating point precision in the state vector. {1,2,4}"
+)
+set_property(CACHE FLOAT_PRECISION PROPERTY STRINGS
+  1
+  2
+  4
+)
+message(STATUS "Precision set to ${FLOAT_PRECISION}. Set FLOAT_PRECISION to modify.")
+
+if (VERBOSE_LIB_NAME)
+  string(CONCAT LIB_NAME ${LIB_NAME} "-fp${FLOAT_PRECISION}")
+endif()
+
+# Examples
+option(
+  BUILD_EXAMPLES
+  "Whether the example programs will be built alongside the QuEST library. Turned ON by default."
+  ON
+)
+message(STATUS "Examples are turned ${BUILD_EXAMPLES}. Set BUILD_EXAMPLES to modify.")
+
+# Testing
+option(
+  ENABLE_TESTING
+  "Whether the test suite will be built alongside the QuEST library. Turned ON by default."
+  ON
+)
+message(STATUS "Testing is turned ${ENABLE_TESTING}. Set ENABLE_TESTING to modify.")
+
+# Multithreading
+option(
+  ENABLE_MULTITHREADING 
+  "Whether QuEST will be built with shared-memory parallelism support using OpenMP. Turned ON by default." 
+  ON
+)
+message(STATUS "Multithreading is turned ${ENABLE_MULTITHREADING}. Set ENABLE_MULTITHREADING to modify.")
+
+# Distribution
+option(
+  ENABLE_DISTRIBUTION 
+  "Whether QuEST will be built with distributed parallelism support using MPI. Turned OFF by default." 
+  OFF
+)
+message(STATUS "Distribution is turned ${ENABLE_DISTRIBUTION}. Set ENABLE_DISTRIBUTION to modify.")
+
+# GPU Acceleration
+option(
+  ENABLE_CUDA
+  "Whether QuEST will be built with support for NVIDIA GPU acceleration. Turned OFF by default."
+  OFF
+)
+message(STATUS "NVIDIA GPU acceleration is turned ${ENABLE_CUDA}. Set ENABLE_CUDA to modify.")
+
+if (ENABLE_CUDA)
+  option(
+    ENABLE_CUQUANTUM
+    "Whether QuEST will be built with support for NVIDIA CuQuantum. Turned OFF by default."
+    OFF
+  )
+  message(STATUS "CuQuantum support is turned ${ENABLE_CUQUANTUM}. Set ENABLE_CUQUANTUM to modify.")
+endif()
+
+option(
+  ENABLE_HIP
+  "Whether QuEST will be built with support for AMD GPU acceleration. Turned OFF by default."
+)
+message(STATUS "AMD GPU acceleration is turned ${ENABLE_HIP}. Set ENABLE_HIP to modify.")
+
+# Throw on disallowed combinations
+if (ENABLE_CUDA AND ENABLE_HIP)
+  message(FATAL_ERROR "QuEST cannot support CUDA and HIP simultaneously.")
+endif()
+
+if ((ENABLE_CUDA OR ENABLE_HIP) AND FLOAT_PRECISION STREQUAL 4)
+  message(FATAL_ERROR "Quad precision is not supported on GPU. Please disable GPU acceleration or lower precision.")
+endif()
+
+# Deprecated API
+option(
+  ENABLE_DEPRECATED
+  "Whether QuEST will be built with deprecated API support. Turned OFF by default."
+  OFF
+)
+message(STATUS "Deprecated API support is turned ${ENABLE_DEPRECATED}. Set ENABLE_DEPRECATED to modify.")
+
+## Library
+
+add_library(QuEST)
+
+# Add namespaced alias to support inclusion of QuEST as a subproject
+add_library(QuEST::QuEST ALIAS QuEST)
+
+# Set include directories
+target_include_directories(QuEST 
+  PUBLIC 
+  $<BUILD_INTERFACE:
+    ${CMAKE_CURRENT_SOURCE_DIR};
+    ${CMAKE_CURRENT_SOURCE_DIR}/quest/include
+  >
+  $<INSTALL_INTERFACE:quest/include>
+)
+
+# Add required C and C++ standards
+target_compile_features(QuEST
+  PUBLIC
+  c_std_11
+  cxx_std_17
+)
+
+# Turn on all compiler warnings
+if (MSVC)
+  target_compile_options(QuEST PRIVATE /W4)
+else()
+  target_compile_options(QuEST PRIVATE -Wall)
+endif()
+
+# Set user options
+target_compile_definitions(QuEST PUBLIC FLOAT_PRECISION=${FLOAT_PRECISION})
+
+if (ENABLE_MULTITHREADING)
+  find_package(OpenMP REQUIRED)
+  target_compile_definitions(QuEST PUBLIC COMPILE_OPENMP=1)
+  target_link_libraries(QuEST
+    PUBLIC
+    OpenMP::OpenMP_CXX
+    OpenMP::OpenMP_C
+  )
+  if (VERBOSE_LIB_NAME)
+    string(CONCAT LIB_NAME ${LIB_NAME} "+mt")
+  endif()
+else()
+  target_compile_definitions(QuEST PUBLIC COMPILE_OPENMP=0)
+endif()
+
+if (ENABLE_DISTRIBUTION)
+  find_package(MPI REQUIRED
+    COMPONENTS CXX
+  )
+  target_compile_definitions(QuEST PUBLIC COMPILE_MPI=1)
+  target_link_libraries(QuEST
+    PUBLIC
+    MPI::MPI_CXX
+  )
+  if (VERBOSE_LIB_NAME)
+    string(CONCAT LIB_NAME ${LIB_NAME} "+mpi")
+  endif()
+else()
+  target_compile_definitions(QuEST PUBLIC COMPILE_MPI=0)
+endif()
+
+if (ENABLE_CUDA)
+  enable_language(CUDA)
+  set(CMAKE_CUDA_STANDARD_REQUIRED ON)
+  set_property(TARGET QuEST PROPERTY CUDA_STANDARD 17)
+
+  target_compile_definitions(QuEST PUBLIC COMPILE_CUDA=1)
+
+  if (VERBOSE_LIB_NAME)
+    string(CONCAT LIB_NAME ${LIB_NAME} "+cuda")
+  endif()
+else()
+  target_compile_definitions(QuEST PUBLIC COMPILE_CUDA=0)
+endif()
+
+if (ENABLE_CUQUANTUM)
+  target_compile_definitions(QuEST PUBLIC COMPILE_CUQUANTUM=1)
+  if (VERBOSE_LIB_NAME)
+    string(CONCAT LIB_NAME ${LIB_NAME} "+cuquantum")
+  endif()
+else()
+  target_compile_definitions(QuEST PUBLIC COMPILE_CUQUANTUM=0)
+endif()
+
+if (ENABLE_HIP)
+  enable_language(HIP)
+  set(CMAKE_HIP_STANDARD_REQUIRED ON)
+  set_property(TARGET QuEST PROPERTY HIP_STANDARD 17)
+
+  target_compile_definitions(QuEST
+    PUBLIC COMPILE_CUDA=1
+    PUBLIC COMPILE_CUQUANTUM=0
+    PUBLIC COMPILE_HIP=1
+    PUBLIC __HIP_PLATFORM_AMD__
+  )
+
+  if (VERBOSE_LIB_NAME)
+    string(CONCAT LIB_NAME ${LIB_NAME} "+hip")
+  endif()
+endif()
+
+if (ENABLE_DEPRECATED)
+  target_compile_definitions(QuEST PUBLIC INCLUDE_DEPRECATED_FUNCTIONS=1)
+
+  if (VERBOSE_LIB_NAME)
+    string(CONCAT LIB_NAME ${LIB_NAME} "+depr")
+  endif()
+endif()
+
+# add math library
+if (NOT MSVC)
+  target_link_libraries(QuEST PUBLIC ${MATH_LIBRARY})
+endif()
+
+# Set output name
+set_target_properties(QuEST PROPERTIES OUTPUT_NAME ${LIB_NAME})
+
+# Add source files
+add_subdirectory(quest)
+
+## Examples
+
+if (BUILD_EXAMPLES)
+  add_subdirectory(examples)
+endif()
+
+## User Source
+
+if (USER_SOURCE AND NOT OUTPUT_EXE)
+    message(SEND_ERROR "USER_SOURCE specified, but not OUTPUT_EXE.")
+endif()
+if (OUTPUT_EXE AND NOT USER_SOURCE)
+    message(SEND_ERROR "OUTPUT_EXE specified, but not USER_SOURCE.")
+endif()
+if (USER_SOURCE AND OUTPUT_EXE)
+  message(STATUS "Compiling ${USER_SOURCE} to executable ${OUTPUT_EXE}.")
+
+  add_executable(${OUTPUT_EXE} ${USER_SOURCE})
+  target_link_libraries(${OUTPUT_EXE} PUBLIC QuEST)
+  install(TARGETS ${OUTPUT_EXE} RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
+  set_target_properties(${OUTPUT_EXE} PROPERTIES INSTALL_RPATH "${CMAKE_INSTALL_PREFIX}/quest/${CMAKE_INSTALL_LIBDIR}")  
+endif()
+
+## Tests
+
+if (ENABLE_TESTING)
+  add_subdirectory(tests)
+endif()
+
+## Install
+
+install(TARGETS QuEST
+  EXPORT QuESTTargets
+  LIBRARY DESTINATION quest/${CMAKE_INSTALL_LIBDIR}
+  ARCHIVE DESTINATION quest/${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION quest/${CMAKE_INSTALL_BINDIR}
+)
+
+install(EXPORT QuESTTargets
+  FILE QuESTTargets.cmake
+  NAMESPACE QuEST::
+  DESTINATION "cmake/QuEST"
+)
+
+## Export
+
+# Write CMake version file for QuEST
+include(CMakePackageConfigHelpers)
+write_basic_package_version_file(
+  QuESTConfigVersion.cmake
+  VERSION ${PACKAGE_VERSION}
+  COMPATIBILITY AnyNewerVersion
+)
+
+export(TARGETS QuEST
+  NAMESPACE QuEST::
+  FILE QuESTTargets.cmake
+)
+
+set(CMAKE_EXPORT_PACKAGE_REGISTRY ON)
+export(PACKAGE QuEST)

docs/cmake.md

@@ -0,0 +1,36 @@
+# CMake Configuration Options in QuEST
+
+Version 4 of QuEST includes reworked CMake to support library builds, CMake export, and installation. Here we detail useful variables to configure the compilation of QuEST. Any of these variables can be set using the `-D` flag when invoking CMake, for example:
+
+```
+cmake -Bbuild -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/opt/QuEST -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DENABLE_MULTITHREADING=ON -DENABLE_DISTRIBUTION=OFF ./
+```
+
+## QuEST CMake variables
+
+| Variable | (Default) Values | Notes |
+| -------- | ---------------- | ----- |
+| `LIB_NAME` | (`QuEST`), String | The QuEST library will be named `lib${LIB_NAME}.so`. Can be used to differentiate multiple versions of QuEST which have been compiled. |
+| `VERBOSE_LIB_NAME` | (`OFF`), `ON` | When turned on `LIB_NAME` will be modified according to the other configuration options chosen. For example compiling QuEST with multithreading, distribution, and double precision with `VERBOSE_LIB_NAME` turned on creates `libQuEST-fp2+mt+mpi.so`. |
+| `FLOAT_PRECISION` | (`2`), `1`, `4` | Determines which floating-point precision QuEST will use: double, single, or quad. *Note: Quad precision is not supported when also compiling for GPU.* |
+| `BUILD_EXAMPLES` | (`ON`), `OFF` | Determines whether the example programs will be built alongside QuEST. |
+| `ENABLE_TESTING` | (`ON`), `OFF` | Determines whether Catch2 tests will be built alongisde QuEST. If built, tests can be run from the build directory with `make test`. |
+| `ENABLE_MULTITHREADING` | (`ON`), OFF | Determines whether QuEST will be built with support for parallelisation with OpenMP. |
+| `ENABLE_DISTRIBUTION` | (`OFF`), ON | Determines whether QuEST will be built with support for parallelisation with MPI. |
+| `ENABLE_CUDA` | (`OFF`), `ON` | Determines whether QuEST will be built with support for NVIDIA GPU acceleration. If turned on, `CMAKE_CUDA_ARCHITECTURES` should probably also be set. |
+| `ENABLE_CUQUANTUM` | (`OFF`), `ON` | Determines whether QuEST will make use of the NVIDIA CuQuantum library. Cannot be turned on if `ENABLE_CUDA` is off. |
+| `ENABLE_HIP` | (`OFF`), `ON` | Determines whether QuEST will be built with support for AMD GPU acceleration. If turned on, `CMAKE_HIP_ARCHITECTURES` should probably also be set. |
+| `ENABLE_DEPRECATION` | (`OFF`), `ON` | Determines whether QuEST will be built with support for the deprecated (v3) API. *Note: will generate compiler warnings, and not supported by GCC.` |
+| `USER_SOURCE` | (Undefined), String | The source file for a user program which will be compiled alongside QuEST. `OUTPUT_EXE` *must* also be defined. |
+| `OUTPUT_EXE` | (Undefined), String | The name of the executable which will be created from the provided `USER_SOURCE`. `USER_SOURCE` *must* also be defined. |
+
+## Standard CMake variables
+
+| Variable | Description | CMake Doc Page |
+| -------- | ----------- | ----- |
+| `CMAKE_BUILD_TYPE` | Whether QuEST will be built with or without optimisations and debugging info. QuEST defaults to a `Release` build which is with optimisation and without debugging info. | [CMAKE_BUILD_TYPE](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html) |
+| `CMAKE_CXX_COMPILER` | The C++ compiler that will be used to compile QuEST. | [CMAKE_\<LANG\>_COMPILER](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html) |
+| `CMAKE_C_COMPILER` | The C compiler that will be used to compile QuEST. | [CMAKE_\<LANG\>_COMPILER](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html) |
+| `CMAKE_INSTALL_PREFIX` | The directory to which QuEST will be installed when `make install` is invoked. A standard GNU directory structure (lib, bin, include) will be used inside the prefix directory. | [CMAKE_INSTALL_PREFIX](https://cmake.org/cmake/help/latest/variable/CMAKE_INSTALL_PREFIX.html) <br> [GNUInstallDirs](https://cmake.org/cmake/help/latest/module/GNUInstallDirs.html) |
+| `CMAKE_CUDA_ARCHITECTURES` | Used to set the value of `arch` when compiling for NVIDIA GPU. | [CMAKE_CUDA_ARCHITECTURES](https://cmake.org/cmake/help/latest/variable/CMAKE_CUDA_ARCHITECTURES.html) |
+| `CMAKE_HIP_ARCHITECTURES` | Used to set the HIP platform which QuEST is compiled for when compiling for AMD GPU. | [CMAKE_HIP_ARCHITECTURES](https://cmake.org/cmake/help/latest/variable/CMAKE_HIP_ARCHITECTURES.html) |

examples/CMakeLists.txt

@@ -0,0 +1,6 @@
+add_subdirectory(krausmaps)
+add_subdirectory(matrices)
+add_subdirectory(numbers)
+add_subdirectory(paulis)
+add_subdirectory(reporters)
+add_subdirectory(superoperators)