Add DUCC to qdk-chemistry

.devcontainer/scripts/install_cpp_dependencies.sh

@@ -128,6 +128,11 @@ if [[ -z "$GAUXC_COMMIT" ]]; then
     echo "Error: Could not find gauxc commit hash in $CGMANIFEST"
     exit 1
 fi
+BTAS_COMMIT=$(get_commit_hash "$CGMANIFEST" "BTAS/btas")
+if [[ -z "$BTAS_COMMIT" ]]; then
+    echo "Error: Could not find BTAS commit hash in $CGMANIFEST"
+    exit 1
+fi
 
 # Read versions from macis cgmanifest
 BLASPP_COMMIT=$(get_commit_hash "$MACIS_CGMANIFEST" "icl-utk-edu/blaspp")
@@ -148,6 +153,7 @@ echo "  lapackpp: $LAPACKPP_COMMIT"
 echo "  libecpint: ${LIBECPINT_TAG:-$LIBECPINT_COMMIT}"
 echo "  libint: $LIBINT_URL"
 echo "  gauxc: $GAUXC_COMMIT"
+echo "  btas: $BTAS_COMMIT"
 
 mkdir -p "$BUILD_DIR"
 cd "$BUILD_DIR"
@@ -203,6 +209,26 @@ make install
 cd "$BUILD_DIR"
 rm -rf lapackpp
 
+# Install BTAS
+# Must follow blaspp/lapackpp and share their prefix: BTAS installs the
+# `blaspp_headers` marker beside them, where its installed config looks for it.
+echo "=== Installing BTAS ==="
+git clone https://github.com/BTAS/btas.git btas
+cd btas
+git checkout "$BTAS_COMMIT"
+mkdir -p build
+cd build
+cmake .. -DCMAKE_BUILD_TYPE="$BUILD_TYPE" \
+         -DCMAKE_INSTALL_PREFIX="$INSTALL_PREFIX" \
+         -DCMAKE_PREFIX_PATH="$INSTALL_PREFIX" \
+         -DCMAKE_POSITION_INDEPENDENT_CODE=ON \
+         -DBUILD_TESTING=OFF \
+         -DBTAS_BUILD_UNITTEST=OFF \
+         -DBUILD_SHARED_LIBS="$BUILD_SHARED_LIBS"
+make install
+cd "$BUILD_DIR"
+rm -rf btas
+
 # Install libint2
 echo "=== Installing libint2 ==="
 LIBINT_TARBALL=$(basename "$LIBINT_URL")

.github/workflows/build-and-test.yaml

@@ -625,7 +625,10 @@ jobs:
       uses: actions/cache/restore@v5
       with:
         path: vcpkg_installed
-        key: windows-vcpkg-${{ env.VCPKG_TRIPLET }}-vs${{ steps.env.outputs.toolset }}-${{ hashFiles('vcpkg.json', 'vcpkg-configuration.json', 'vcpkg-overlay/**', '.pipelines/install-scripts/install-cpp-deps-windows.ps1') }}
+        # Keyed only on what determines the vcpkg package set. The install script is
+        # deliberately excluded: editing its CMake-dependency section would otherwise
+        # force a cold vcpkg rebuild, which re-exposes flaky upstream downloads.
+        key: windows-vcpkg-${{ env.VCPKG_TRIPLET }}-vs${{ steps.env.outputs.toolset }}-${{ hashFiles('vcpkg.json', 'vcpkg-configuration.json', 'vcpkg-overlay/**') }}
 
     - name: Restore deps-install cache
       id: cache-deps
@@ -652,7 +655,7 @@ jobs:
       uses: actions/cache/save@v5
       with:
         path: vcpkg_installed
-        key: windows-vcpkg-${{ env.VCPKG_TRIPLET }}-vs${{ steps.env.outputs.toolset }}-${{ hashFiles('vcpkg.json', 'vcpkg-configuration.json', 'vcpkg-overlay/**', '.pipelines/install-scripts/install-cpp-deps-windows.ps1') }}
+        key: windows-vcpkg-${{ env.VCPKG_TRIPLET }}-vs${{ steps.env.outputs.toolset }}-${{ hashFiles('vcpkg.json', 'vcpkg-configuration.json', 'vcpkg-overlay/**') }}
 
     - name: Save deps-install cache
       if: steps.cache-deps.outputs.cache-hit != 'true'

cpp/CMakeLists.txt

@@ -139,6 +139,22 @@ else()
     endif()
 endif()
 
+# BTAS for dense tensor contraction in DUCC; must follow MACIS to reuse its BLAS and blaspp/lapackpp.
+find_package(BTAS QUIET)
+if(NOT BTAS_FOUND)
+    include(FetchContent)
+    FetchContent_Declare(BTAS
+        GIT_REPOSITORY https://github.com/BTAS/btas.git
+        GIT_TAG 287b145ead818a0332f2b7ce0b7375a83d328bae
+    )
+    # BTAS's linalg kit force-writes the BUILD_TESTING it sees back into the cache.
+    set(_qdk_build_testing "${BUILD_TESTING}")
+    set(BUILD_TESTING OFF CACHE BOOL "Build the testing tree." FORCE)
+    FetchContent_MakeAvailable(BTAS)
+    set(BUILD_TESTING "${_qdk_build_testing}" CACHE BOOL "Build the testing tree." FORCE)
+    add_library(BTAS::BTAS ALIAS BTAS)
+endif()
+
 # Enable CUDA for GPU bindings in QDK Chemistry
 if(QDK_CHEMISTRY_ENABLE_GPU)
     enable_language(CUDA)
@@ -167,6 +183,9 @@ target_link_libraries(chemistry PUBLIC
     macis::macis
 )
 
+# Header-only and absent from public headers, so keep BTAS out of the export.
+target_link_libraries(chemistry PRIVATE $<BUILD_INTERFACE:BTAS::BTAS>)
+
 # Conditionally link OpenMP
 if(QDK_ENABLE_OPENMP)
     if(TARGET OpenMP::OpenMP_CXX)

cpp/cmake/third_party.cmake

@@ -129,6 +129,9 @@ handle_dependency(gauxc
   REQUIRED
 )
 
+# Boost for BTAS
+find_package(Boost CONFIG REQUIRED)
+
 # Restore previous settings
 set(CMAKE_WARN_DEPRECATED ${_old_warn_deprecated} CACHE BOOL "" FORCE)
 set(CMAKE_SUPPRESS_DEVELOPER_WARNINGS ${_old_suppress_dev} CACHE BOOL "" FORCE)

cpp/include/qdk/chemistry.hpp

@@ -4,6 +4,7 @@
 
 #include <qdk/chemistry/algorithms/active_space.hpp>
 #include <qdk/chemistry/algorithms/dynamical_correlation_calculator.hpp>
+#include <qdk/chemistry/algorithms/effective_hamiltonian.hpp>
 #include <qdk/chemistry/algorithms/geometry_optimization.hpp>
 #include <qdk/chemistry/algorithms/hamiltonian.hpp>
 #include <qdk/chemistry/algorithms/localization.hpp>

cpp/include/qdk/chemistry/algorithms/effective_hamiltonian.hpp

@@ -0,0 +1,117 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See LICENSE.txt in the project root for
+// license information.
+
+#pragma once
+
+#include <memory>
+#include <qdk/chemistry/algorithms/algorithm.hpp>
+#include <qdk/chemistry/data/hamiltonian.hpp>
+#include <qdk/chemistry/data/symmetry/symmetry_blocked_index_set.hpp>
+#include <qdk/chemistry/data/wavefunction.hpp>
+#include <string>
+
+namespace qdk::chemistry::algorithms {
+
+/**
+ * @class EffectiveHamiltonianConstructor
+ * @brief Abstract base for constructing an effective Hamiltonian.
+ *
+ * Given a reference wavefunction and an input Hamiltonian, a concrete
+ * implementation constructs an effective Hamiltonian in an explicitly
+ * specified target P-space.
+ *
+ * Typical usage:
+ * @code
+ * auto constructor =
+ *   EffectiveHamiltonianConstructorFactory::create("algorithm_name");
+ * auto effective_hamiltonian =
+ *   constructor->run(reference, hamiltonian, p_indices);
+ * @endcode
+ *
+ * @see EffectiveHamiltonianConstructorFactory for creating instances
+ * @see data::Wavefunction for the reference wavefunction input
+ * @see data::Hamiltonian for the input and output Hamiltonians
+ * @see data::SymmetryBlockedIndexSet for the target P-space indices
+ */
+class EffectiveHamiltonianConstructor
+    : public Algorithm<EffectiveHamiltonianConstructor,
+                       std::shared_ptr<data::Hamiltonian>,
+                       std::shared_ptr<data::Wavefunction>,
+                       std::shared_ptr<data::Hamiltonian>,
+                       std::shared_ptr<const data::SymmetryBlockedIndexSet>> {
+ public:
+  /**
+   * @brief Default constructor.
+   */
+  EffectiveHamiltonianConstructor() = default;
+
+  /**
+   * @brief Virtual destructor.
+   */
+  virtual ~EffectiveHamiltonianConstructor() = default;
+
+  /**
+   * @brief Construct the effective Hamiltonian acting on the target space P.
+   *
+   * \cond DOXYGEN_SUPRESS (Doxygen warning suppression for argument packs)
+   * @param reference Reference wavefunction providing the reference state.
+   * @param hamiltonian Input Hamiltonian built over the whole window W = P u Q.
+   * @param p_indices The target space P (indices into the window's active
+   *        space W).
+   * \endcond
+   * @return The effective Hamiltonian acting on the target space P.
+   * @throws qdk::chemistry::data::SettingsAreLocked if attempting to modify
+   *         settings after run() is called.
+   * @note Settings are automatically locked when this method is called and
+   *       cannot be modified during or after execution.
+   */
+  using Algorithm::run;
+
+  /**
+   * @brief Access the algorithm's name.
+   */
+  virtual std::string name() const override = 0;
+
+  /**
+   * @brief Access the algorithm's type name.
+   */
+  std::string type_name() const override {
+    return "effective_hamiltonian_constructor";
+  }
+
+ protected:
+  /**
+   * @brief Implementation of the effective-Hamiltonian construction.
+   *
+   * Contains the actual construction logic. It is automatically called by
+   * run() after settings have been locked, and must be implemented by derived
+   * classes.
+   *
+   * @param reference Reference wavefunction providing the reference state.
+   * @param hamiltonian Input Hamiltonian built over the whole window W = P u Q.
+   * @param p_indices The target space P (indices into the window's active
+   *        space W).
+   * @return The effective Hamiltonian acting on the target space P.
+   */
+  virtual std::shared_ptr<data::Hamiltonian> _run_impl(
+      std::shared_ptr<data::Wavefunction> reference,
+      std::shared_ptr<data::Hamiltonian> hamiltonian,
+      std::shared_ptr<const data::SymmetryBlockedIndexSet> p_indices)
+      const override = 0;
+};
+
+/**
+ * @brief Factory for effective-Hamiltonian constructor instances.
+ */
+struct EffectiveHamiltonianConstructorFactory
+    : public AlgorithmFactory<EffectiveHamiltonianConstructor,
+                              EffectiveHamiltonianConstructorFactory> {
+  static std::string algorithm_type_name() {
+    return "effective_hamiltonian_constructor";
+  }
+  static void register_default_instances();
+  static std::string default_algorithm_name() { return "ducc"; }
+};
+
+}  // namespace qdk::chemistry::algorithms

cpp/manifest/qdk-chemistry/cgmanifest.json

@@ -166,6 +166,16 @@
       },
       "developmentDependency": false
     },
+    {
+      "component": {
+        "type": "git",
+        "git": {
+          "repositoryUrl": "https://github.com/BTAS/btas.git",
+          "commitHash": "287b145ead818a0332f2b7ce0b7375a83d328bae"
+        }
+      },
+      "developmentDependency": false
+    },
     {
       "component": {
         "type": "git",

cpp/src/qdk/chemistry/algorithms/CMakeLists.txt

@@ -10,6 +10,7 @@ target_sources(chemistry PRIVATE
     pmc.cpp
     qdk_nuclear_derivative.cpp
     dynamical_correlation_calculator.cpp
+    effective_hamiltonian.cpp
     geometry_optimization.cpp
     scf.cpp
     stability.cpp

cpp/src/qdk/chemistry/algorithms/algorithm_defaults.cpp

@@ -5,6 +5,7 @@
 #include <qdk/chemistry/algorithms/active_space.hpp>
 #include <qdk/chemistry/algorithms/algorithm_defaults.hpp>
 #include <qdk/chemistry/algorithms/dynamical_correlation_calculator.hpp>
+#include <qdk/chemistry/algorithms/effective_hamiltonian.hpp>
 #include <qdk/chemistry/algorithms/geometry_optimization.hpp>
 #include <qdk/chemistry/algorithms/hamiltonian.hpp>
 #include <qdk/chemistry/algorithms/localization.hpp>
@@ -42,6 +43,7 @@ std::shared_ptr<data::Settings> resolve_algorithm_defaults(
   REGISTER_FACTORY_SETTINGS_INIT(MultiConfigurationCalculatorFactory)
   REGISTER_FACTORY_SETTINGS_INIT(ProjectedMultiConfigurationCalculatorFactory)
   REGISTER_FACTORY_SETTINGS_INIT(DynamicalCorrelationCalculatorFactory)
+  REGISTER_FACTORY_SETTINGS_INIT(EffectiveHamiltonianConstructorFactory)
   REGISTER_FACTORY_SETTINGS_INIT(GeometryOptimizerFactory)
   REGISTER_FACTORY_SETTINGS_INIT(MultiConfigurationScfFactory)
   REGISTER_FACTORY_SETTINGS_INIT(NuclearDerivativeCalculatorFactory)

cpp/src/qdk/chemistry/algorithms/effective_hamiltonian.cpp

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See LICENSE.txt in the project root for
+// license information.
+
+#include <qdk/chemistry/algorithms/effective_hamiltonian.hpp>
+#include <qdk/chemistry/utils/logger.hpp>
+
+#include "microsoft/ducc/ducc.hpp"
+
+namespace qdk::chemistry::algorithms {
+
+/**
+ * @brief Factory function to create the BTAS DUCC solver.
+ */
+std::unique_ptr<EffectiveHamiltonianConstructor> make_ducc_solver() {
+  QDK_LOG_TRACE_ENTERING();
+  return std::make_unique<qdk::chemistry::algorithms::microsoft::DuccSolver>();
+}
+
+/**
+ * @brief Register default effective-Hamiltonian implementations.
+ */
+void EffectiveHamiltonianConstructorFactory::register_default_instances() {
+  QDK_LOG_TRACE_ENTERING();
+  EffectiveHamiltonianConstructorFactory::register_instance(make_ducc_solver);
+}
+
+}  // namespace qdk::chemistry::algorithms

cpp/src/qdk/chemistry/algorithms/microsoft/CMakeLists.txt

@@ -9,6 +9,7 @@ target_sources(chemistry PRIVATE
     localization/natural_orbitals.cpp
     localization/pipek_mezey.cpp
     localization/vvhv.cpp
+    ducc/ducc.cpp
     hamiltonian.cpp
     cholesky_hamiltonian.cpp
     macis_asci.cpp