Consolidate build configuration under cmake/

.gitignore

@@ -1,8 +1,21 @@
-# Build directories
-*build*/
-
-# IDE directories
-.idea/*
+# Build and generated directories
+/build/
+/_build/
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+compile_commands.json
+
+# Editors and operating systems
+.idea/
+.vscode/
+.DS_Store
+
+# Python tooling
+.pytest_cache/
+.ruff_cache/
+__pycache__/
+*.py[cod]
 
 # Prerequisites
 *.d
@@ -36,5 +49,3 @@
 *.exe
 *.out
 *.app
-
-__pycache__

ALPS_VERSION.txt

@@ -0,0 +1 @@
+2.3.4

CITATION.md

@@ -0,0 +1,29 @@
+# Citing ALPS
+
+If ALPS contributes to published research, please cite the framework papers below and any method-specific paper relevant to the application you used. Citation is requested as scholarly acknowledgement; it is not a condition of the MIT license in [`LICENSE.txt`](LICENSE.txt).
+
+## Framework papers
+
+Please cite both ALPS framework papers:
+
+1. A. F. Albuquerque *et al.*, “The ALPS project release 1.3: Open-source software for strongly correlated systems,” *Journal of Magnetism and Magnetic Materials* **310**, 1187–1193 (2007). [doi:10.1016/j.jmmm.2006.10.304](https://doi.org/10.1016/j.jmmm.2006.10.304)
+2. B. Bauer *et al.*, “The ALPS project release 2.0: Open source software for strongly correlated systems,” *Journal of Statistical Mechanics: Theory and Experiment* **2011**, P05001 (2011). [doi:10.1088/1742-5468/2011/05/P05001](https://doi.org/10.1088/1742-5468/2011/05/P05001)
+
+## Method-specific papers
+
+Add the applicable paper from this table. Application names match directories or executables in this repository.
+
+| Application or component | Additional citation |
+| --- | --- |
+| `applications/qmc/looper` (`loop`, `loop_mpi`) | S. Todo and K. Kato, “Cluster Algorithms for General-S Quantum Spin Systems,” *Physical Review Letters* **87**, 047203 (2001). [doi:10.1103/PhysRevLett.87.047203](https://doi.org/10.1103/PhysRevLett.87.047203) |
+| `applications/qmc/qwl` | M. Troyer, S. Wessel, and F. Alet, “Flat Histogram Methods for Quantum Systems,” *Physical Review Letters* **90**, 120201 (2003). [doi:10.1103/PhysRevLett.90.120201](https://doi.org/10.1103/PhysRevLett.90.120201) |
+| Continuous-time QMC impurity solvers and the DMFT framework | E. Gull, P. Werner, S. Fuchs, B. Surer, T. Pruschke, and M. Troyer, “Continuous-time quantum Monte Carlo impurity solvers,” *Computer Physics Communications* **182**, 1078–1082 (2011). [doi:10.1016/j.cpc.2010.12.050](https://doi.org/10.1016/j.cpc.2010.12.050) |
+| DMRG/MPS applications | M. Dolfi *et al.*, “Matrix product state applications for the ALPS project,” *Computer Physics Communications* **185**, 3430–3440 (2014). [doi:10.1016/j.cpc.2014.08.019](https://doi.org/10.1016/j.cpc.2014.08.019) |
+
+The framework papers are sufficient for `sse`, `spinmc`, `fulldiag`, `sparsediag`, and `worm` unless a publication describes a more specific algorithmic reference. For specialized models or algorithms, also cite the primary scientific source on which the calculation is based.
+
+## Citation metadata
+
+Use the DOI links above to obtain current BibTeX, RIS, or other citation metadata from the publishers. This avoids maintaining duplicate hand-written records that can drift from the authoritative metadata.
+
+When describing reproducibility, also record the ALPS release or Git commit used in the calculation.

CMakeLists.txt

@@ -70,13 +70,17 @@ if(ALPS_BUILD_LIBS_ONLY)
   set(ALPS_BUILD_APPLICATIONS OFF)
 endif()
 
+# Sets ALPS_VERSION_CORE from ALPS_VERSION.txt. Included by full path because
+# CMAKE_MODULE_PATH is not set up until after project().
+include(${CMAKE_CURRENT_SOURCE_DIR}/cmake/ALPSVersion.cmake)
+
 if(ALPS_BUILD_FORTRAN)
-  project(alps C CXX Fortran)
+  project(alps VERSION ${ALPS_VERSION_CORE} LANGUAGES C CXX Fortran)
   if (APPLE)
    set (CMAKE_Fortran_RUNTIME_LIBRARIES "-lgcc_s.1")
   endif(APPLE)
 else(ALPS_BUILD_FORTRAN)
-  project(alps C CXX)
+  project(alps VERSION ${ALPS_VERSION_CORE} LANGUAGES C CXX)
 endif(ALPS_BUILD_FORTRAN)
 
 set(CMAKE_CXX_STANDARD 14)
@@ -109,7 +113,7 @@ message(STATUS "Build type: " ${CMAKE_BUILD_TYPE})
 ######################################################################
 # CMAKE_MODULE_PATH
 ######################################################################
-list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/config)
+list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/cmake)
 
 ######################################################################
 # set default CMAKE_INSTALL_PREFIX
@@ -118,25 +122,35 @@ list(APPEND CMAKE_MODULE_PATH ${PROJECT_SOURCE_DIR}/config)
 ######################################################################
 # Version information
 ######################################################################
-set(ALPS_YEAR 2026)
-set(ALPS_VERSION_MAJOR 2)
-set(ALPS_VERSION_MINOR 3)
-set(ALPS_VERSION_PATCH 3)
-set(ALPS_VERSION_BUILD "")
-
-if(ALPS_VERSION_BUILD)
-  set(ALPS_VERSION "${ALPS_VERSION_MAJOR}.${ALPS_VERSION_MINOR}.${ALPS_VERSION_PATCH}-${ALPS_VERSION_BUILD}")
-else(ALPS_VERSION_BUILD)
-  set(ALPS_VERSION "${ALPS_VERSION_MAJOR}.${ALPS_VERSION_MINOR}.${ALPS_VERSION_PATCH}")
-endif(ALPS_VERSION_BUILD)
+# The numeric components come from project() above, which took its version from
+# ALPS_VERSION.txt. Do not hardcode them here.
+set(ALPS_VERSION_MAJOR ${PROJECT_VERSION_MAJOR})
+set(ALPS_VERSION_MINOR ${PROJECT_VERSION_MINOR})
+set(ALPS_VERSION_PATCH ${PROJECT_VERSION_PATCH})
+
+# Prerelease label, e.g. "beta.2" for the v2.3.4-beta.2 tag. Display only: it is
+# deliberately kept out of the numeric version that drives SOVERSION and
+# find_package() matching. Set by the release process, not checked in.
+set(ALPS_VERSION_PRERELEASE "" CACHE STRING
+    "Prerelease label for this build, e.g. beta.2 (affects version strings only)")
+mark_as_advanced(ALPS_VERSION_PRERELEASE)
+
+if(ALPS_VERSION_PRERELEASE)
+  set(ALPS_VERSION "${ALPS_VERSION_CORE}-${ALPS_VERSION_PRERELEASE}")
+else()
+  set(ALPS_VERSION "${ALPS_VERSION_CORE}")
+endif()
 set(ALPS_VERSION_STRING "ALPS Libraries version ${ALPS_VERSION}")
-MESSAGE(STATUS "ALPS version: ${ALPS_VERSION}") 
+message(STATUS "ALPS version: ${ALPS_VERSION}")
+
+# Derived, never hardcoded. string(TIMESTAMP) honours SOURCE_DATE_EPOCH, so
+# distro and conda reproducible builds still get a stable year.
+string(TIMESTAMP ALPS_YEAR "%Y" UTC)
 
 set(ALPS_CONFIG_HOST unknown)
 set(ALPS_CONFIG_USER unknown)
 
 set(ALPS_PREFIX "${CMAKE_INSTALL_PREFIX}")
-set(ALPS_SRCDIR "${CMAKE_SOURCE_DIR}")
 set(libdir "${CMAKE_INSTALL_PREFIX}/lib")
 set(bindir "${CMAKE_INSTALL_PREFIX}/bin")
 
@@ -393,8 +407,16 @@ endif(LAPACK_LIBRARIES)
 if(HDF5_LIBRARIES)
   list(APPEND ALPS_EXTRA_LIBRARIES ${HDF5_LIBRARIES})
 endif(HDF5_LIBRARIES)
-configure_file(config/ALPSConfig.cmake.in ${PROJECT_BINARY_DIR}/config/ALPSConfig.cmake @ONLY)
-configure_file(config/include.mk.in ${PROJECT_BINARY_DIR}/config/include.mk)
+configure_file(cmake/ALPSConfig.cmake.in ${PROJECT_BINARY_DIR}/cmake/ALPSConfig.cmake @ONLY)
+configure_file(cmake/include.mk.in ${PROJECT_BINARY_DIR}/cmake/include.mk)
+
+# Without this file find_package(ALPS <version>) accepts any version it finds
+# and silently discards the constraint. SameMinorVersion: patch releases within
+# a minor series are drop-in, a minor bump is not guaranteed to be.
+include(CMakePackageConfigHelpers)
+write_basic_package_version_file(
+  ${PROJECT_BINARY_DIR}/cmake/ALPSConfigVersion.cmake
+  COMPATIBILITY SameMinorVersion)
 
 
 # installation
@@ -425,17 +447,18 @@ install(DIRECTORY lib/xml DESTINATION ${ALPS_XML_PATH} COMPONENT xml
 
 install(DIRECTORY ${PROJECT_BINARY_DIR}/lib/xml DESTINATION ${ALPS_XML_PATH} COMPONENT xml)
 
-add_subdirectory(config)
+add_subdirectory(cmake)
 
-install(FILES config/UseALPS.cmake
-        ${PROJECT_BINARY_DIR}/config/ALPSConfig.cmake
-        ${PROJECT_BINARY_DIR}/config/include.mk
-        config/run_test.cmake
-        config/run_test_mpi.cmake
-        config/add_alps_test.cmake
+install(FILES cmake/UseALPS.cmake
+        ${PROJECT_BINARY_DIR}/cmake/ALPSConfig.cmake
+        ${PROJECT_BINARY_DIR}/cmake/ALPSConfigVersion.cmake
+        ${PROJECT_BINARY_DIR}/cmake/include.mk
+        cmake/run_test.cmake
+        cmake/run_test_mpi.cmake
+        cmake/add_alps_test.cmake
         DESTINATION share/alps COMPONENT build)
 
-install(FILES LICENSE.txt README.md
+install(FILES CITATION.md LICENSE.txt README.md
         DESTINATION share/alps COMPONENT libraries)
 ######################################################################
 # libraries

CMakePresets.json

@@ -0,0 +1,33 @@
+{
+  "version": 3,
+  "cmakeMinimumRequired": {
+    "major": 3,
+    "minor": 21,
+    "patch": 0
+  },
+  "configurePresets": [
+    {
+      "name": "default",
+      "displayName": "Default release build",
+      "binaryDir": "${sourceDir}/_build/default",
+      "cacheVariables": {
+        "CMAKE_BUILD_TYPE": "Release"
+      }
+    }
+  ],
+  "buildPresets": [
+    {
+      "name": "default",
+      "configurePreset": "default"
+    }
+  ],
+  "testPresets": [
+    {
+      "name": "default",
+      "configurePreset": "default",
+      "output": {
+        "outputOnFailure": true
+      }
+    }
+  ]
+}

CONTRIBUTING.md

@@ -50,11 +50,11 @@ Before opening a new issue, please search existing issues to avoid duplicates.
 
 ### Prerequisites
 
-- CMake ≥ 3.18
+- CMake ≥ 3.18 for normal configuration; CMake ≥ 3.21 for presets
 - A C++17-capable compiler (GCC, Clang, Intel, or Fujitsu)
-- Boost (bundled copy included; or provide your own with `-DALPS_USE_SYSTEM_BOOST=ON`)
+- Boost (downloaded automatically during configuration; or use a system install with `-DALPS_USE_SYSTEM_BOOST=ON`)
 - For Fortran bindings: gfortran (or compatible Fortran compiler)
-- For Python bindings: Python ≥ 3.9, plus `numpy` and `scipy`
+- For Python bindings: Python ≥ 3.10, plus `numpy` and `scipy`
 
 See the [installation page](https://alps.comp-phys.org/documentation/install/) for full platform-specific instructions.
 
@@ -79,12 +79,16 @@ cmake .. -DCMAKE_BUILD_TYPE=Release
 make -j$(nproc)
 ```
 
-To build with Python bindings:
+Alternatively, use the bundled CMake preset (requires CMake ≥ 3.21):
 ```bash
-pip install scikit-build-core numpy scipy
-pip install --no-build-isolation -e .
+cmake --preset default
+cmake --build --preset default
 ```
 
+The Python bindings are a separate `scikit-build-core` project that builds
+against an installed ALPS C++ SDK; see the
+[`pyalps` build instructions](bindings/python/pyalps/README.md).
+
 ### Run the tests
 
 From the build directory:
@@ -173,7 +177,8 @@ If you are contributing a new simulation application or library, the Governing C
 
 ### CMake
 
-- CMake ≥ 3.18 features are acceptable.
+- CMake ≥ 3.18 features are acceptable. Preset files may use features available
+  in CMake ≥ 3.21.
 - Use target-based linking (`target_link_libraries`, `target_include_directories`) rather than directory-level commands.
 
 ---