pyquiche 0.1.0__tar.gz

pyquiche-0.1.0/.clang-format

@@ -0,0 +1,41 @@
+BasedOnStyle: LLVM
+
+UseTab: Never
+IndentWidth: 4
+ContinuationIndentWidth: 4
+
+ColumnLimit: 120
+
+AllowAllArgumentsOnNextLine: false
+AllowAllParametersOfDeclarationOnNextLine: false
+AlignAfterOpenBracket: Align
+AlwaysBreakTemplateDeclarations: Yes
+
+PenaltyBreakBeforeFirstCallParameter: 100
+
+FixNamespaceComments: true
+ReflowComments: true
+
+SortIncludes: true
+IncludeBlocks: Regroup
+IncludeCategories:
+  - Regex: '^<nanobind'
+    Priority: 3
+
+  - Regex: '^<catch2'
+    Priority: 4
+
+  - Regex: '^<quest'
+    Priority: 5
+
+  # QUICHE project headers
+  - Regex: '^"quiche/'
+    Priority: 6
+
+  # C headers
+  - Regex: '^<.*\.h>$'
+    Priority: 1
+
+  # C++ headers
+  - Regex: '^<.*>$'
+    Priority: 2

pyquiche-0.1.0/.clang-tidy

@@ -0,0 +1,35 @@
+Checks: >
+  bugprone-*,
+  -bugprone-easily-swappable-parameters,
+
+  clang-analyzer-*,
+  concurrency-*,
+
+  cppcoreguidelines-*,
+  -cppcoreguidelines-pro-bounds-pointer-arithmetic,
+  -cppcoreguidelines-avoid-magic-numbers,
+  -cppcoreguidelines-non-private-member-variables-in-classes,
+
+  misc-*,
+  -misc-non-private-member-variables-in-classes,
+  -misc-no-recursion,
+
+  modernize-*,
+  -modernize-use-trailing-return-type,
+
+  performance-*,
+  portability-*,
+
+  readability-*,
+  -readability-braces-around-statements,
+  -readability-identifier-length,
+  -readability-implicit-bool-conversion,
+  -readability-magic-numbers,
+  -readability-math-missing-parentheses,
+
+  mpi-*,
+  openmp-*,
+
+WarningsAsErrors: ''
+HeaderFilterRegex: '.*'
+FormatStyle: file

pyquiche-0.1.0/.github/workflows/build-wheels.yml

@@ -0,0 +1,66 @@
+name: Build wheels and sdist
+
+on:
+  workflow_call:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+
+jobs:
+
+  build-wheels:
+    name: Build wheels (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+
+    permissions:
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, ubuntu-24.04-arm, macos-15, windows-latest]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Run cibuildwheel
+        run: uvx cibuildwheel~=4.2.0 --output-dir dist
+
+      - name: Upload wheels
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist-wheels-${{ matrix.os }}
+          path: dist/*.whl
+          if-no-files-found: error
+
+  build-sdist:
+    name: Build sdist
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v10.0.1
+
+      - name: Build sdist
+        run: uv build --sdist --out-dir dist
+
+      - name: Upload sdist
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+

pyquiche-0.1.0/.github/workflows/cpp-lint.yml

@@ -0,0 +1,38 @@
+name: C++ lint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  format:
+    name: clang-format
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install lint dependencies
+        run: uv sync --locked --only-group lint
+
+      - name: Run clang-format
+        run: |
+            find cpp bindings \( -name '*.cpp' -o -name '*.hpp' \) \
+            -exec uv run --no-sync clang-format --dry-run --Werror --verbose {} +

pyquiche-0.1.0/.github/workflows/cpp-tests.yml

@@ -0,0 +1,33 @@
+name: C++ tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: C++ tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Configure CMake project
+        run: cmake -B build -D QUICHE_BUILD_TESTS=ON
+
+      - name: Build CMake project
+        run: cmake --build build --parallel
+
+      - name: Run tests
+        run: ctest --test-dir build --output-on-failure --no-tests=error

pyquiche-0.1.0/.github/workflows/publish-wheels.yml

@@ -0,0 +1,38 @@
+name: Publish wheels and sdist to PyPI
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+
+  build:
+    uses: ./.github/workflows/build-wheels.yml
+
+    permissions:
+      contents: read
+
+  pypi-publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    environment:
+      name: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download wheel and sdist artifacts
+        uses: actions/download-artifact@v8
+        with:
+          pattern: "dist-{wheels-*,sdist}"
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pyquiche-0.1.0/.github/workflows/python-lint.yml

@@ -0,0 +1,40 @@
+name: Python lint
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Ruff
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install lint dependencies
+        run: uv sync --locked --only-group lint
+
+      - name: Run ruff check
+        run: uv run --no-sync ruff check --output-format=github
+
+      - name: Run ruff format
+        if: ${{ !cancelled() }}
+        run: uv run --no-sync ruff format --check --output-format=github

pyquiche-0.1.0/.github/workflows/python-tests.yml

@@ -0,0 +1,49 @@
+name: Python tests
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+# PR runs cancel older runs for the same branch. Non-PR runs group by the
+# unique run_id, so pushes to main don't cancel each other.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Python tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      # Cache QuEST and nanobind sources and their compiled objects.
+      - name: Cache CMake build directory
+        uses: actions/cache@v6
+        with:
+          path: build
+          key: ${{ runner.os }}-cmake-build-${{ hashFiles('CMakeLists.txt', 'cpp/**/CMakeLists.txt', 'bindings/CMakeLists.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-cmake-build-
+
+      - name: Install uv and Python
+        uses: astral-sh/setup-uv@v10.0.1
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Install quiche with dev dependencies
+        working-directory: python
+        run: uv sync --locked --group dev
+
+      - name: Run pytest
+        working-directory: python
+        run: uv run --no-sync pytest

pyquiche-0.1.0/.gitignore

@@ -0,0 +1,19 @@
+# Python
+__pycache__
+.ipynb_checkpoints
+.venv
+*.egg-info
+dist
+
+# C++
+compile_commands.json
+.cache
+build
+
+# Libs
+*.so
+*.dylib
+*.dll
+
+# Other
+.DS_Store

pyquiche-0.1.0/CHANGELOG.md

@@ -0,0 +1,88 @@
+# Changelog
+
+Changelog format based on [Keep a Changelog](https://keepachangelog.com/).
+Versioning based on [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Deprecated
+
+### Removed
+
+### Fixed
+
+### Security
+
+
+## [0.1.0] - 2026-09-13
+
+### Added
+- Added `py.typed` marker for type checkers.
+- Added `qpe::getEnergyFromTrotterPhase` and `qpe::getEnergyFromQubitisationPhase` functions for converting a QPE phase to an energy.
+- Added `logical_rotations_to_tgates` to `quiche.resources` exports.
+- Added `PauliSum.has_identity`, `PauliSum.n_terms_with_identity`, `PauliSum.without_identity()` and `PauliSum.split_identity()`.
+- Added `SecondQuantisedHamiltonian` to `quiche.core` for electronic integrals.
+- Added `quiche.io.fcidump` for reading FCIDUMP integral files.
+- Added `openfermion` as a dependency.
+- Added `pyquiche` package to PyPI, with prebuilt, multithreaded wheels for Linux, macOS and Windows (GPU, MPI and single/quad precision builds still require building from source).
+
+### Changed
+- Renamed `applyMultiStateControlledPhaseShift` to `applyMultiQubitStatePhaseShift` and `applyMultiStateControlledQubitPhaseFlip` to `applyMultiQubitStatePhaseFlip`.
+- Changed `quiche` submodule imports to lazy imports.
+- Deferred `cirq` import in `quiche.core` to `PauliWord.to_cirq()`.
+- Enabled bytecode compilation for `uv` installs.
+- Raised minimum build requirements to CMake 3.26, scikit-build-core 1.0, and nanobind 2.10.
+- Pinned fetched C++ dependencies (QuEST, Catch2, nanobind) using checksummed release archives where applicable.
+- Exposed namespaced C++ library target `quiche::quiche`.
+- Moved `pyproject.toml` to the repository root.
+- Improved Windows build compatibility.
+- `.controlled()` on `PauliWordRotation`, `QDRIFT` and `Trotterisation` now constructs the same bloq but with `is_controlled=True` rather than a separate class.
+- `PauliWordRotation` now validates its target qubit range on construction rather than on decomposition.
+- Tightened `PauliWord` validation to reject repeated target qubits.
+- Tightened `PauliSum` validation to require at least one term.
+- Added electron and qubit count validation to `getHartreeFockStateJW`, `getHartreeFockStateBK` and `getHartreeFockStateParity`.
+- Made `cloneWithoutIdentity` reject `PauliStrSum`s containing only identity terms.
+- Renamed the `QuESTEnv` binding methods `syncQuESTEnv` and `isQuESTEnvInit` to `sync` and `isInit`.
+- Added missing `const` qualifiers to the control arguments of `applyMultiControlledCoeffsPrep` and `applyMultiControlledPauliStrSumPrep`.
+- `PauliSum.identity_coefficient` now defaults to `0.0`.
+- `PauliSum.lam` is now the 1-norm of the whole operator (including the identity coefficient).
+- `PauliSum.to_quest()` now includes the identity term rather than dropping it. Call `PauliSum.without_identity()` first to recover the previous behaviour.
+- Changed `QDRIFT` sampling to use its own `numpy` generator, requiring an explicit integer `seed` (sampled terms will differ for a given seed from previous sampling).
+- `QPESpec` now takes `seed` as a field rather than an `extras` entry (required when simulating with `QDRIFT`).
+- `PrepareFromStatePrep` now exposes the phase gradient as a junk register, adding a `phase_gradient` register to the block encoding signature.
+- `QDRIFT` and `Trotterisation` now reject a zero evolution time.
+- Moved `quiche.hamlib` into the new `quiche.io` subpackage.
+- Renamed `hamlib.get_dataset` and `hamlib.parse_hamiltonian` to `hamlib.read_dataset` and `hamlib.parse`.
+- Renamed the package from `quiche` to `pyquiche` to avoid PyPI clash (the import name `quiche` is unchanged).
+
+### Removed
+- Removed the C++ Hamlib module (keeping just the Python one), along with the corresponding example and unit tests.
+- Removed the `QUICHE_BUILD_HAMLIB` build flag and the HDF5 dependency for the C++ backend.
+- Removed `CTRLPauliWordRotation`, `CTRLQDRIFT` and `CTRLTrotterisation` (use `.controlled()` on the corresponding bloq instead).
+- Removed the (empty) `quiche.dispatch.budget.state_prep` module.
+- Removed the dangling `StatePrep` entry from `quiche.core.__all__`.
+- Removed `QDRIFT.sample_term_indices()` (use the `sampled_indices` property instead).
+
+### Fixed
+- Removed zero-count sub-bloqs from call graphs.
+- Fixed `QDRIFT` incorrectly ignoring a `0` seed.
+- Fixed Python stable-ABI wheel builds (added missing `Development.SABIModule` component).
+- Fixed `get_bk_state` raising `IndexError` for single-orbital systems.
+- Fixed `get_jw_state` returning its input rather than an integer array as its signature declares.
+- Fixed incorrectly bound `QuESTEnv.sync` and `QuESTEnv.isInit`.
+- Rebound `PauliStrSum.fromFile`, `PauliStrSum.fromReversedFile` and the `Qureg` creation methods (`createDensityQureg`, `createForcedQureg`, `createForcedDensityQureg` and `createCustomQureg`) as static methods.
+- Fixed `QDRIFT` dropping the evolution time from the identity term's global phase.
+- Fixed `QDRIFT` sampling from the global `random` state.
+- Fixed `LCUBlockEncodingWrapper` discarding the signs of negative coefficients.
+- Fixed `LCUBlockEncodingWrapper` including the phase gradient qubits in the index register for SELECT.
+
+
+## [0.0.1] - 2026-06-30
+
+### Added
+
+- Initial public release

pyquiche-0.1.0/CMakeLists.txt

@@ -0,0 +1,220 @@
+cmake_minimum_required(VERSION 3.26)
+
+project(QuicheProject
+    VERSION 0.1.0
+    DESCRIPTION "QUantum Integrated CHEmistry toolkit"
+    LANGUAGES CXX C # QUICHE itself only uses C++ but QuEST requires C
+)
+
+include(FetchContent)
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
+
+if(PROJECT_IS_TOP_LEVEL AND NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
+  set(CMAKE_BUILD_TYPE Release CACHE STRING "Choose the type of build." FORCE)
+  set_property(CACHE CMAKE_BUILD_TYPE PROPERTY STRINGS "Debug" "Release" "MinSizeRel" "RelWithDebInfo")
+endif()
+
+if(PROJECT_IS_TOP_LEVEL)
+    set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+endif()
+
+# --------------------------------------------------------------------------------
+# Quiche config
+
+message("
+    ==================
+    QUICHE config
+    ==================
+    ")
+
+option(QUICHE_BUILD_EXAMPLES "Build the QUICHE example scripts." OFF)
+message(STATUS "Build QUICHE examples: ${QUICHE_BUILD_EXAMPLES}")
+
+option(QUICHE_BUILD_TESTS "Build the QUICHE test suite." OFF)
+message(STATUS "Build QUICHE tests: ${QUICHE_BUILD_TESTS}")
+
+option(QUICHE_BUILD_BINDINGS "Build the QUICHE Python bindings." OFF)
+message(STATUS "Build QUICHE bindings: ${QUICHE_BUILD_BINDINGS}")
+
+option(QUICHE_INSTALL "Install the QUICHE C++ library." ${PROJECT_IS_TOP_LEVEL})
+message(STATUS "Install QUICHE C++ library: ${QUICHE_INSTALL}")
+
+if(PROJECT_IS_TOP_LEVEL)
+    option(BUILD_SHARED_LIBS "Build shared libraries." ON)
+    message(STATUS "Build with shared libraries: ${BUILD_SHARED_LIBS}")
+endif()
+
+if(QUICHE_BUILD_BINDINGS AND NOT BUILD_SHARED_LIBS)
+    message(FATAL_ERROR "QUICHE_BUILD_BINDINGS requires BUILD_SHARED_LIBS=ON.")
+endif()
+
+# --------------------------------------------------------------------------------
+# Define dependencies
+
+# QUICHE requires private QuEST headers, which are only exposed via the build
+# interface and are not installed, so QuEST must come from FetchContent.
+# Do not add FIND_PACKAGE_ARGS here.
+FetchContent_Declare(
+    QuEST
+    URL https://github.com/QuEST-Kit/QuEST/archive/refs/tags/v4.2.0.tar.gz
+    URL_HASH SHA256=2c812a7ec4d727e0947ffd0daf05452963c3f1c10e428c8bc30c35164921fcba
+    OVERRIDE_FIND_PACKAGE
+)
+
+# Use git source to preserve required submodules
+FetchContent_Declare(
+    nanobind
+    GIT_REPOSITORY https://github.com/wjakob/nanobind
+    GIT_TAG 11087dd7707c80ef85802c661ad459ace5bef671    # v2.10.0
+    GIT_PROGRESS TRUE
+    FIND_PACKAGE_ARGS 2.10
+)
+
+FetchContent_Declare(
+    Catch2
+    URL https://github.com/catchorg/Catch2/archive/refs/tags/v3.13.0.tar.gz
+    URL_HASH SHA256=650795f6501af514f806e78c554729847b98db6935e69076f36bb03ed2e985ef
+    FIND_PACKAGE_ARGS 3.13
+)
+
+# --------------------------------------------------------------------------------
+# Fetch dependencies
+
+message("
+    ==================
+    QuEST config
+    ==================
+    ")
+
+FetchContent_MakeAvailable(QuEST)
+
+
+if(QUICHE_BUILD_BINDINGS)
+    find_package(Python 3.12
+        COMPONENTS
+        Interpreter
+        Development.Module
+        Development.SABIModule
+        REQUIRED
+    )
+    FetchContent_MakeAvailable(nanobind)
+endif()
+
+if(QUICHE_BUILD_TESTS)
+    FetchContent_MakeAvailable(Catch2)
+
+    if(catch2_SOURCE_DIR)
+        list(APPEND CMAKE_MODULE_PATH "${catch2_SOURCE_DIR}/extras")
+    endif()
+
+    include(CTest)
+    include(Catch)
+endif()
+
+# --------------------------------------------------------------------------------
+
+add_library(quiche)
+add_library(quiche::quiche ALIAS quiche)
+
+target_sources(quiche PUBLIC
+    FILE_SET HEADERS
+    BASE_DIRS ${PROJECT_SOURCE_DIR}/cpp/include
+    FILES
+        ${PROJECT_SOURCE_DIR}/cpp/include/quiche/mappings.hpp
+        ${PROJECT_SOURCE_DIR}/cpp/include/quiche/qdrift.hpp
+        ${PROJECT_SOURCE_DIR}/cpp/include/quiche/qpe.hpp
+        ${PROJECT_SOURCE_DIR}/cpp/include/quiche/qubitisation.hpp
+        ${PROJECT_SOURCE_DIR}/cpp/include/quiche/quest-patches.hpp
+        ${PROJECT_SOURCE_DIR}/cpp/include/quiche/utils.hpp
+)
+
+target_compile_features(quiche PUBLIC cxx_std_17)
+target_link_libraries(quiche PUBLIC QuEST::QuEST)
+set_target_properties(quiche PROPERTIES WINDOWS_EXPORT_ALL_SYMBOLS ON)
+
+add_subdirectory(cpp)
+
+if(QUICHE_BUILD_BINDINGS)
+    add_subdirectory(bindings)
+endif()
+
+# --------------------------------------------------------------------------------
+# Install and package setup
+
+if(APPLE)
+    set(RPATH_ORIGIN "@loader_path")
+else()
+    set(RPATH_ORIGIN "$ORIGIN")
+endif()
+
+set_target_properties(quiche PROPERTIES INSTALL_RPATH "${RPATH_ORIGIN}")
+
+if(QUICHE_INSTALL)
+    # Install library and public headers
+    install(TARGETS quiche
+        EXPORT quicheTargets
+        FILE_SET HEADERS
+        RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+        LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+        ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+    )
+
+    # Install CMake target metadata
+    install(EXPORT quicheTargets
+        FILE quicheTargets.cmake
+        NAMESPACE quiche::
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/quiche
+    )
+
+    # Generate package config file
+    configure_package_config_file(
+        ${PROJECT_SOURCE_DIR}/cmake/quicheConfig.cmake.in
+        ${CMAKE_CURRENT_BINARY_DIR}/quicheConfig.cmake
+        INSTALL_DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/quiche
+    )
+
+    # Generate package version file
+    write_basic_package_version_file(
+        ${CMAKE_CURRENT_BINARY_DIR}/quicheConfigVersion.cmake
+        COMPATIBILITY SameMinorVersion # update to SameMajorVersion post-1.0
+    )
+
+    # Install package files
+    install(FILES
+        ${CMAKE_CURRENT_BINARY_DIR}/quicheConfig.cmake
+        ${CMAKE_CURRENT_BINARY_DIR}/quicheConfigVersion.cmake
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/quiche
+    )
+
+endif()
+
+if(QUICHE_BUILD_BINDINGS)
+
+    # For Linux and Mac can place in libs and locate via INSTALL_RPATH,
+    # for Windows simply place beside bindings since don't have RPATH
+    set_target_properties(bindings PROPERTIES INSTALL_RPATH "${RPATH_ORIGIN}/libs")
+    install(TARGETS QuEST quiche
+        LIBRARY DESTINATION quiche/libs COMPONENT quiche_wheel EXCLUDE_FROM_ALL
+        RUNTIME DESTINATION quiche COMPONENT quiche_wheel EXCLUDE_FROM_ALL
+    )
+
+    install(TARGETS bindings
+        LIBRARY DESTINATION quiche COMPONENT quiche_wheel EXCLUDE_FROM_ALL
+    )
+
+    # Generate stubs into the source tree for development builds
+    nanobind_add_stub(bindings_stub
+        INSTALL_TIME
+        COMPONENT quiche_wheel
+        MODULE quiche.bindings
+        PYTHON_PATH $<TARGET_FILE_DIR:bindings>
+        RECURSIVE
+        OUTPUT_PATH "${PROJECT_SOURCE_DIR}/python/src/quiche"
+        OUTPUT
+            bindings/__init__.pyi
+            bindings/quest_bindings.pyi
+            bindings/quiche_bindings.pyi
+    )
+
+endif()