.. _release-v1.1.0: ========================== What's New in Version 1.1 ========================== Version 1.1 introduces Q#-native circuits, model Hamiltonians, higher-order Trotter-Suzuki formulas, native :term:`ROHF`, Cholesky-based integral transformations, and an OpenFermion plugin. Highlights ========== - **Q#-native circuit architecture** — circuits are now built and composed as native Q# operations, eliminating intermediate format conversions for faster circuit construction and lower memory overhead, and enabling a streamlined end-to-end :term:`QPE` code path with lazy :term:`QIR` compilation. - **Model Hamiltonians** — native construction of fermionic and spin lattice Hamiltonians (Hückel, Fermi-Hubbard, :term:`PPP`, Ising, Heisenberg) on arbitrary lattice geometries. - **Arbitrary-order Trotter-Suzuki** — product formulas of any even order with accuracy-aware step sizing and commutator-based error bounds. - **Native ROHF** — :term:`DIIS`-accelerated restricted open-shell Hartree-Fock in the :term:`QDK` :term:`SCF` solver. - **Cholesky AO→MO transformation** — pivoted Cholesky decomposition for two-electron integrals, reducing memory from :math:`O(N^4)` to :math:`O(N^2 N_\text{chol})` and enabling treatment of larger molecular systems with significant speedup over full four-center :term:`ERI` evaluation. - **OpenFermion plugin** — Jordan-Wigner, Bravyi-Kitaev, and symmetry-conserving Bravyi-Kitaev mappings via OpenFermion. Model Hamiltonians ================== Running quantum phase estimation on a full *ab initio* molecular Hamiltonian is general and accurate, but the number of qubits and gates grows with the orbital basis set, making even modest molecules expensive to simulate. An alternative is to **map the essential physics onto a simpler model Hamiltonian** that captures the key interactions with far fewer degrees of freedom. New model-Hamiltonian constructors make it possible to build these Hamiltonians directly, without quantum-chemistry input files or external electronic-structure codes. **Fermionic models** — Hückel, Hubbard, and Pariser-Parr-Pople (:term:`PPP`) — return a second-quantized ``Hamiltonian``: .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-model-fermionic :end-before: # end-cell-model-fermionic All parameters (``epsilon``, ``t``, ``U``, ``V``, ``z``) accept either a scalar or per-site/per-bond arrays for inhomogeneous lattices. **Spin models** — Ising and Heisenberg — return a ``QubitHamiltonian`` directly: .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-model-spin :end-before: # end-cell-model-spin **Lattice geometries.** All constructors take a ``LatticeGraph`` that defines the site connectivity. Common topologies are built in: .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-lattice :end-before: # end-cell-lattice See `examples/extended_hubbard.ipynb `_ for a complete walkthrough that models cyclobutadiene with the extended Hubbard (:term:`PPP`) model and runs :term:`QPE` on it. The interoperability examples under ``examples/interoperability/`` also demonstrate constructing model Hamiltonians directly without relying on the built-in infrastructure. Q#-Native Circuit Architecture =============================== The ``Circuit`` class now composes quantum operations as native Q# callables (exposed in `qdk>=1.27.0`). By removing intermediate format conversions (e.g., QASM-to-QIR round-trips), circuit construction is faster and uses less memory, especially for large active spaces. This enables: - End-to-end :term:`QPE` without intermediate format conversions — faster pipeline execution - Lazy compilation to :term:`QIR` only at execution time — construction cost is deferred until the circuit is actually run - Direct access to Q#'s resource estimator on any ``Circuit`` - A leaner default install with framework-specific dependencies as optional extras ``Circuit`` can hold any combination of: - ``qsharp_op`` — a callable Q# operation - ``qsharp_factory`` — a lazy ``QsharpFactoryData(program, parameter)`` that compiles on demand - ``qasm`` / ``qir`` — for interoperability with external tools The :term:`QPE` pipeline composes Q# callables end-to-end — state preparation, controlled time evolution, and phase estimation are all native Q# operations: .. code-block:: python from qdk_chemistry.algorithms import create state_prep = create("state_prep", "sparse_isometry_gf2x") circuit = state_prep.run(wavefunction) # Inspect the Q# circuit circuit.get_qsharp_circuit(prune_classical_qubits=True) # Compile to QIR for external use qir = circuit.get_qir() # Use Q#'s resource estimator directly import qsharp qsharp.estimate( circuit._qsharp_factory.program, None, *circuit._qsharp_factory.parameter.values(), ) **Lightweight core dependencies.** Framework-specific dependencies are now isolated as optional extras, keeping the core install lean: .. code-block:: bash pip install qdk-chemistry # core (Q#-native) pip install 'qdk-chemistry[qiskit-extras]' # + Qiskit interop pip install 'qdk-chemistry[openfermion-extras]' # + OpenFermion interop See `examples/qpe_stretched_n2.ipynb `_ and `examples/state_prep_energy.ipynb `_ for worked end-to-end :term:`QPE` notebooks. Arbitrary-Order Trotter-Suzuki ============================== Time-evolution builders now support product formulas of any even order via recursive Suzuki composition :cite:`Suzuki1992`. .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-trotter :end-before: # end-cell-trotter When both ``num_divisions`` and ``target_accuracy`` are specified, the builder uses whichever requires more Trotter steps. The ``error_bound`` parameter selects between two bounds: - ``"naive"`` — triangle-inequality bound: :math:`N = \lceil (\sum_j |\alpha_j|)^2 t^2 / \epsilon \rceil` - ``"commutator"`` — tighter commutator-scaling bound from :cite:`Childs2021`: :math:`N = \lceil \frac{t^2}{2\epsilon} \sum_{j 1. The :term:`DIIS` extrapolation works with the :term:`ROHF`-effective Fock matrix and total density matrix. .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-rohf :end-before: # end-cell-rohf Cholesky-Based AO-to-MO Transformation ======================================= A new Hamiltonian constructor uses pivoted Cholesky decomposition of the :term:`AO` electron-repulsion integrals (:term:`ERI`), reducing memory from :math:`O(N^4)` to :math:`O(N^2 N_\text{chol})` and significantly accelerating the :term:`AO`-to-:term:`MO` integral transformation compared to full four-center :term:`ERI` evaluation. This enables treatment of active-space methods for larger molecular systems that would be impractical with the conventional approach. .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-cholesky :end-before: # end-cell-cholesky The implementation includes Schwarz-based shell-quartet screening, stability guards for near-singular decompositions, and diagnostic logging for convergence monitoring. OpenFermion Plugin ================== A new plugin provides qubit mappings backed by `OpenFermion `_: .. code-block:: bash pip install 'qdk-chemistry[openfermion-extras]' .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-openfermion :end-before: # end-cell-openfermion Available encodings: ``jordan-wigner``, ``bravyi-kitaev``, ``bravyi-kitaev-tree``, ``symmetry-conserving-bravyi-kitaev``. Please see the OpenFermion documentation for more information. See `examples/interoperability/openFermion/molecular_hamiltonian_jordan_wigner.py `_ for a worked example. MACIS Improvements ================== - **Expanded orbital limits.** The selected-:term:`CI` dispatch now supports active spaces up to **2048 orbitals** (up from 127 in v1.0). The internal :term:`SCI` bit-string representation was widened to 255 orbitals. - **Single-orbital entropies and mutual information.** :term:`MACIS` calculators can now compute S1 entropies and two-orbital mutual information for active-space analysis: .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-macis-entropies :end-before: # end-cell-macis-entropies - **ASCI refinement stability.** The :term:`ASCI` refinement loop now detects sign-flipping energy oscillations and terminates gracefully instead of looping indefinitely. - **Unrestricted-orbital guard.** :term:`MACIS` calculators (:term:`CAS`, :term:`ASCI`, :term:`PMC`) now raise a clear error if passed an unrestricted Hamiltonian, which is not supported by the :term:`MACIS` backend. Orbital Localization ==================== - **One-shot VVHV localization.** The valence-virtual hard-virtual (:term:`VVHV`) localizer was rewritten to use a proper one-shot localization for proto hard-virtuals, replacing the previous canonicalization-based approach. This improves numerical stability with better weighted orthogonalization and singular-value diagnostics. - **Bug fix** in the proto-HV construction that could produce incorrect localized orbitals in certain basis sets. Other Improvements ================== - **Refactored energy estimator.** ``QdkEnergyEstimator`` now takes a single ``QubitHamiltonian``, groups commuting terms internally via ``group_commuting(qubit_wise=True)``, and delegates execution to a ``CircuitExecutor``: .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-energy-estimator :end-before: # end-cell-energy-estimator - **CI coefficients for CC and MP2.** Coupled-cluster and :term:`MP2` wavefunctions now expose a CI-like expansion with ``get_coefficients()``, ``get_coefficient(...)``, and ``get_active_determinants()`` methods, enabling determinant-level analysis of post-:term:`HF` wavefunctions. - **Configurable ERI threshold.** The ``eri_threshold`` setting (default ``1e-12``) controls shell-quartet screening in Hamiltonian construction. A separate ``shell_pair_threshold`` is available for :term:`SCF` pre-screening. - **Wavefunction file I/O with** ``pathlib.Path``. Python bindings for ``to_file`` / ``from_file``, ``to_json_file`` / ``from_json_file``, and ``to_hdf5_file`` / ``from_hdf5_file`` now accept ``pathlib.Path`` objects in addition to strings. - **Dedicated** ``[jupyter]`` **install extra.** Notebook dependencies are now isolated from the core install: ``pip install 'qdk-chemistry[jupyter]'``. - **``Symmetries`` data class.** A new immutable container for active-space quantum numbers, used by qubit mappers that exploit particle-number or spin symmetries (e.g., symmetry-conserving Bravyi-Kitaev): .. literalinclude:: ../_static/examples/python/release_notes_v1_1.py :language: python :start-after: # start-cell-symmetries :end-before: # end-cell-symmetries Bug Fixes ========= - Fixed inactive Fock matrix dimension validation — matrices are now checked for full NMO × NMO shape before Hamiltonian construction, preventing silent size mismatches. - Fixed active-space :term:`MP2` orbital energies — denominators now use active-space orbital energies rather than full-system indices for both restricted and unrestricted :term:`MP2`. - Fixed JSON serialization of ``TimeEvolutionContainer`` — Pauli-term keys are now correctly serialized as strings and deserialized back to integer qubit indices. - Fixed :term:`SCF` logging suppression — the solver no longer silences the global logger during execution, which was hiding unrelated log messages. - Aligned logger flush policy with the configured log level. Infrastructure and Packaging ============================= - **macOS ARM64 wheels.** Pre-built wheels are now published for macOS Apple Silicon alongside Linux x86_64 and Linux aarch64. - **Modular install extras.** Framework-specific dependencies are now optional extras (``qiskit-extras``, ``openfermion-extras``, ``jupyter``), keeping the default install lightweight. - **Telemetry sanitization.** Tests and CI builds now force telemetry off (``QSHARP_PYTHON_TELEMETRY=false``) to prevent accidental data collection during development. - **Centralized** ``VERSION`` **file.** A single ``VERSION`` file at the repo root is the source of truth for CMake, Python packaging, and CI. Format: ``X.Y.Z`` or ``X.Y.Z.T``. - Broadened CI/CD coverage and release pipeline hardening. - Documentation restructured with clearer navigation and a layered quick-reference style. - Added `qdk-chemistry-data `_ companion repo references for curated datasets and benchmark materials.