excitationsolve 2.2.2__tar.gz → 2.2.3__tar.gz

{excitationsolve-2.2.2/excitationsolve.egg-info → excitationsolve-2.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: excitationsolve
-Version: 2.2.2
+Version: 2.2.3
 Summary: ExcitationSolve: a fast globally-informed gradient-free optimizer for physically-motivated ansätze constructed of excitation operators
 Author-email: Jonas Jäger <jojaeger@cs.ubc.ca>, "Thierry N. Kaldenbach" <Thierry.Kaldenbach@dlr.de>, Max Haas <Max.Haas@dlr.de>, Erik Schultheis <Erik.Schultheis@dlr.de>
 License:        Copyright 2025 Jonas Jäger, Thierry N. Kaldenbach, Max Haas, Erik Schultheis,
@@ -241,7 +241,7 @@ Requires-Dist: tencirchem-ng==2024.10; extra == "test"
 Requires-Dist: pyscf==2.8.0; extra == "test"
 Dynamic: license-file
 
-# ExcitationSolve [![paper](https://img.shields.io/badge/Commun.%20Phys.-Paper-0274b5.svg)](https://www.nature.com/articles/s42005-025-02375-9) [![DOI](https://zenodo.org/badge/958004975.svg)](https://doi.org/10.5281/zenodo.17457122)
+# ExcitationSolve [![paper](https://img.shields.io/badge/Commun.%20Phys.-Paper-0274b5.svg)](https://www.nature.com/articles/s42005-025-02375-9) [![DOI](https://zenodo.org/badge/958004975.svg)](https://doi.org/10.5281/zenodo.17457122) [![PyPI](https://img.shields.io/pypi/v/excitationsolve.svg?color=0274b5&label=PyPI)](https://pypi.org/project/excitationsolve/)
 
 An optimization algorithm for ansätze consisting of excitation operators in variational quantum eigensolvers (VQEs).
 
@@ -257,6 +257,11 @@ VQE convergence for different molecules and optimizers, including ExcitationSolv
 </h1>
 
 ## Installation
+ExcitationSolve is available on [PyPI](https://pypi.org/project/excitationsolve/):
+```
+pip install excitationsolve
+```
+Alternatively, install directly from GitHub:
 ```
 pip install git+https://github.com/dlr-wf/ExcitationSolve.git
 ```
@@ -287,11 +292,17 @@ Use the `excitationsolve.ExcitationSolveScipy` class in combination with the `sc
 ```python
 excsolve_obj = ExcitationSolveScipy(maxiter=100, tol=1e-10, save_parameters=True)
 optimizer = excsolve_obj.minimize
-res = scipy.optimize.minimize(cost, params, method=optimizer)
+def callback(xk): # or callback(intermediate_result)
+    print(xk)
+options = dict(parameter_occ=parameter_occ) # optional, use if parameters occur multiple times in the ansatz
+res = scipy.optimize.minimize(cost, params, method=optimizer, callback=callback, options=options)
 energies = excsolve_obj.energies
 counts = excsolve_obj.nfevs
 ```
 
+### Optimal parameters of double excitations w.r.t. the Hartree-Fock state
+Use `exitationsolve.optimal_theta` and `excitationsolve.optimal_theta_pyscf` to calculate analytic optimal parameter values for individual double excitations when applied to the Hartree-Fock reference state. Both functions return the optimal parameter and the energy difference to the Hartree-Fock energy. The optimal parameter is defined as $\theta^*=\argmin_\theta\bra{\mathrm{HF}}U^\dagger(\theta) H U(\theta)\ket{\mathrm{HF}}$ where $H$ is the electronic structure Hamiltonian, $U(\theta)$ is **one** double excitation, and $\ket{\mathrm{HF}}$ is the Hartree-Fock state. In [Haas et al., 2026](https://doi.org/10.48550/arXiv.2602.10776) it has been shown that initializing doubles in their respective optimal parameter and appending them to the ansatz in order of energy impact is an efficient operator selection and warm-start strategy.
+
 ### Testing
 To run the tests, install the needed dependencies with
 ```bash
@@ -315,7 +326,7 @@ Feel free to contact [David Melching](mailto:David.Melching@dlr.de) if you have
 ## Citation
 If you use portions of this code please cite our [paper](https://www.nature.com/articles/s42005-025-02375-9):
 ```bibtex
-@article{Jaeger2024Fast,
+@article{Jaeger2025Fast,
     title={Fast gradient-free optimization of excitations in variational quantum eigensolvers},
     author={Jäger, Jonas and Kaldenbach, Thierry N. and Haas, Max and Schultheis, Erik},
     year={2025},
@@ -329,5 +340,18 @@ If you use portions of this code please cite our [paper](https://www.nature.com/
 }
 ```
 
+If you use the `exitationsolve.optimal_theta` or `excitationsolve.optimal_theta_pyscf` functionalities please also cite [Haas et al., 2026](https://doi.org/10.48550/arXiv.2602.10776):
+```bibtex
+@article{Haas2026Efficient,
+    title={Efficient Operator Selection and Warm-Start Strategy for Excitations in Variational Quantum Eigensolvers}, 
+    url={https://arxiv.org/abs/2602.10776},
+    DOI={10.48550/ARXIV.2602.10776},
+    publisher={arXiv},
+    author={Haas, Max and Kaldenbach, Thierry N. and Hammerschmidt, Thomas and Barragan-Yani, Daniel}, 
+    year={2026} 
+} 
+```
+
+
 ## Acknowledgment
 This project was made possible by the DLR Quantum Computing Initiative and the Federal Ministry for Economic Affairs and Climate Action; https://qci.dlr.de/quanticom.

{excitationsolve-2.2.2 → excitationsolve-2.2.3}/README.md

@@ -1,4 +1,4 @@
-# ExcitationSolve [![paper](https://img.shields.io/badge/Commun.%20Phys.-Paper-0274b5.svg)](https://www.nature.com/articles/s42005-025-02375-9) [![DOI](https://zenodo.org/badge/958004975.svg)](https://doi.org/10.5281/zenodo.17457122)
+# ExcitationSolve [![paper](https://img.shields.io/badge/Commun.%20Phys.-Paper-0274b5.svg)](https://www.nature.com/articles/s42005-025-02375-9) [![DOI](https://zenodo.org/badge/958004975.svg)](https://doi.org/10.5281/zenodo.17457122) [![PyPI](https://img.shields.io/pypi/v/excitationsolve.svg?color=0274b5&label=PyPI)](https://pypi.org/project/excitationsolve/)
 
 An optimization algorithm for ansätze consisting of excitation operators in variational quantum eigensolvers (VQEs).
 
@@ -14,6 +14,11 @@ VQE convergence for different molecules and optimizers, including ExcitationSolv
 </h1>
 
 ## Installation
+ExcitationSolve is available on [PyPI](https://pypi.org/project/excitationsolve/):
+```
+pip install excitationsolve
+```
+Alternatively, install directly from GitHub:
 ```
 pip install git+https://github.com/dlr-wf/ExcitationSolve.git
 ```
@@ -44,11 +49,17 @@ Use the `excitationsolve.ExcitationSolveScipy` class in combination with the `sc
 ```python
 excsolve_obj = ExcitationSolveScipy(maxiter=100, tol=1e-10, save_parameters=True)
 optimizer = excsolve_obj.minimize
-res = scipy.optimize.minimize(cost, params, method=optimizer)
+def callback(xk): # or callback(intermediate_result)
+    print(xk)
+options = dict(parameter_occ=parameter_occ) # optional, use if parameters occur multiple times in the ansatz
+res = scipy.optimize.minimize(cost, params, method=optimizer, callback=callback, options=options)
 energies = excsolve_obj.energies
 counts = excsolve_obj.nfevs
 ```
 
+### Optimal parameters of double excitations w.r.t. the Hartree-Fock state
+Use `exitationsolve.optimal_theta` and `excitationsolve.optimal_theta_pyscf` to calculate analytic optimal parameter values for individual double excitations when applied to the Hartree-Fock reference state. Both functions return the optimal parameter and the energy difference to the Hartree-Fock energy. The optimal parameter is defined as $\theta^*=\argmin_\theta\bra{\mathrm{HF}}U^\dagger(\theta) H U(\theta)\ket{\mathrm{HF}}$ where $H$ is the electronic structure Hamiltonian, $U(\theta)$ is **one** double excitation, and $\ket{\mathrm{HF}}$ is the Hartree-Fock state. In [Haas et al., 2026](https://doi.org/10.48550/arXiv.2602.10776) it has been shown that initializing doubles in their respective optimal parameter and appending them to the ansatz in order of energy impact is an efficient operator selection and warm-start strategy.
+
 ### Testing
 To run the tests, install the needed dependencies with
 ```bash
@@ -72,7 +83,7 @@ Feel free to contact [David Melching](mailto:David.Melching@dlr.de) if you have
 ## Citation
 If you use portions of this code please cite our [paper](https://www.nature.com/articles/s42005-025-02375-9):
 ```bibtex
-@article{Jaeger2024Fast,
+@article{Jaeger2025Fast,
     title={Fast gradient-free optimization of excitations in variational quantum eigensolvers},
     author={Jäger, Jonas and Kaldenbach, Thierry N. and Haas, Max and Schultheis, Erik},
     year={2025},
@@ -86,5 +97,18 @@ If you use portions of this code please cite our [paper](https://www.nature.com/
 }
 ```
 
+If you use the `exitationsolve.optimal_theta` or `excitationsolve.optimal_theta_pyscf` functionalities please also cite [Haas et al., 2026](https://doi.org/10.48550/arXiv.2602.10776):
+```bibtex
+@article{Haas2026Efficient,
+    title={Efficient Operator Selection and Warm-Start Strategy for Excitations in Variational Quantum Eigensolvers}, 
+    url={https://arxiv.org/abs/2602.10776},
+    DOI={10.48550/ARXIV.2602.10776},
+    publisher={arXiv},
+    author={Haas, Max and Kaldenbach, Thierry N. and Hammerschmidt, Thomas and Barragan-Yani, Daniel}, 
+    year={2026} 
+} 
+```
+
+
 ## Acknowledgment
 This project was made possible by the DLR Quantum Computing Initiative and the Federal Ministry for Economic Affairs and Climate Action; https://qci.dlr.de/quanticom.

{excitationsolve-2.2.2 → excitationsolve-2.2.3}/excitationsolve/info.py

@@ -1,3 +1,3 @@
-__version__ = "2.2.2"  # MAJOR.MINOR.PATCH, like in https://semver.org/
+__version__ = "2.2.3"  # MAJOR.MINOR.PATCH, like in https://semver.org/
 
 HOMEPAGE = "https://github.com/dlr-wf/ExcitationSolve"  # GitHub page

{excitationsolve-2.2.2 → excitationsolve-2.2.3}/excitationsolve/parameter_prediction.py

@@ -8,8 +8,7 @@ period-pi curve
 
 with a = (E_HF - E_exc) / 2 and b = <HF|H|Phi>. The minimiser of this curve has
 the closed form theta = -1/2 * arctan2(-b, -a). `optimal_theta` evaluates a
-and b from the molecular integrals and returns this exact angle together with
-its first-order (EN2 / MP2) linearisations.
+and b from the molecular integrals and returns this exact angle.
 
 The module is self-contained: it only needs a converged PySCF RHF object and the
 four excitation indices (in TCC/Qiskit-sorted spin-orbital order).
@@ -47,7 +46,7 @@ def _transform_integrals_to_mo(mf):
     return h1_mo, eri_mo, occ_indices
 
 
-def _determinant_energy(h1_mo, eri_mo, occ_indices, MP2=False):
+def _determinant_energy(h1_mo, eri_mo, occ_indices):
     """
     Compute the energy of a single Slater determinant in MO basis.
 
@@ -83,10 +82,7 @@ def _determinant_energy(h1_mo, eri_mo, occ_indices, MP2=False):
         for q in occ:
             e_two += eri_mo[p, q, q, p] - eri_mo[p, q, p, q]
 
-    if MP2:
-        return e_one
-    else:
-        return e_one + 0.5 * e_two
+    return e_one + 0.5 * e_two
 
 
 def _apply_double_excitation(occ_indices, i, j, a, b):
@@ -116,7 +112,7 @@ def _apply_double_excitation(occ_indices, i, j, a, b):
     return sorted(occ_set)
 
 
-def _compute_a_b(h1_mo, h2_mo, occ_indices, i, j, k, l, MP2=False):
+def _compute_a_b(h1_mo, h2_mo, occ_indices, i, j, k, l):
     """
     Compute the parameters a and b for the two-level effective Hamiltonian
     defined by the HF determinant and a doubly excited determinant.
@@ -153,11 +149,11 @@ def _compute_a_b(h1_mo, h2_mo, occ_indices, i, j, k, l, MP2=False):
     b : float
     """
     # HF determinant energy
-    e_hf = _determinant_energy(h1_mo, h2_mo, occ_indices, MP2)
+    e_hf = _determinant_energy(h1_mo, h2_mo, occ_indices)
 
     # Excited determinant: remove (i, j), add (k, l)
     occ_exc = _apply_double_excitation(occ_indices, k, l, i, j)
-    e_exc = _determinant_energy(h1_mo, h2_mo, occ_exc, MP2)
+    e_exc = _determinant_energy(h1_mo, h2_mo, occ_exc)
 
     a_val = 0.5 * (e_hf - e_exc)
 
@@ -254,7 +250,7 @@ def _block_to_interleaved(idx, no, nv):
     return 2 * spatial + spin
 
 
-def optimal_theta_pyscf(mf: pyscf.scf.hf.RHF, excitation_indices: list[int]):
+def optimal_theta_pyscf(mf: pyscf.scf.hf.RHF, excitation_indices: list[int]) -> tuple[float, float]:
     """
     High-level convenience function to compute the optimal VQE angle theta_opt
     for a given double excitation in an RHF reference.
@@ -283,7 +279,7 @@ def optimal_theta_pyscf(mf: pyscf.scf.hf.RHF, excitation_indices: list[int]):
     return optimal_theta(h1_mo, eri_mo, occ_spatial, excitation_indices)
 
 
-def optimal_theta(h1: np.ndarray, eri: np.ndarray, occ_spatial: list[int], excitation_indices: list[int]):
+def optimal_theta(h1: np.ndarray, eri: np.ndarray, occ_spatial: list[int], excitation_indices: list[int]) -> tuple[float, float]:
     """
     High-level convenience function to compute the optimal VQE angle theta_opt
     for a given double excitation in an RHF reference.

{excitationsolve-2.2.2 → excitationsolve-2.2.3/excitationsolve.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: excitationsolve
-Version: 2.2.2
+Version: 2.2.3
 Summary: ExcitationSolve: a fast globally-informed gradient-free optimizer for physically-motivated ansätze constructed of excitation operators
 Author-email: Jonas Jäger <jojaeger@cs.ubc.ca>, "Thierry N. Kaldenbach" <Thierry.Kaldenbach@dlr.de>, Max Haas <Max.Haas@dlr.de>, Erik Schultheis <Erik.Schultheis@dlr.de>
 License:        Copyright 2025 Jonas Jäger, Thierry N. Kaldenbach, Max Haas, Erik Schultheis,
@@ -241,7 +241,7 @@ Requires-Dist: tencirchem-ng==2024.10; extra == "test"
 Requires-Dist: pyscf==2.8.0; extra == "test"
 Dynamic: license-file
 
-# ExcitationSolve [![paper](https://img.shields.io/badge/Commun.%20Phys.-Paper-0274b5.svg)](https://www.nature.com/articles/s42005-025-02375-9) [![DOI](https://zenodo.org/badge/958004975.svg)](https://doi.org/10.5281/zenodo.17457122)
+# ExcitationSolve [![paper](https://img.shields.io/badge/Commun.%20Phys.-Paper-0274b5.svg)](https://www.nature.com/articles/s42005-025-02375-9) [![DOI](https://zenodo.org/badge/958004975.svg)](https://doi.org/10.5281/zenodo.17457122) [![PyPI](https://img.shields.io/pypi/v/excitationsolve.svg?color=0274b5&label=PyPI)](https://pypi.org/project/excitationsolve/)
 
 An optimization algorithm for ansätze consisting of excitation operators in variational quantum eigensolvers (VQEs).
 
@@ -257,6 +257,11 @@ VQE convergence for different molecules and optimizers, including ExcitationSolv
 </h1>
 
 ## Installation
+ExcitationSolve is available on [PyPI](https://pypi.org/project/excitationsolve/):
+```
+pip install excitationsolve
+```
+Alternatively, install directly from GitHub:
 ```
 pip install git+https://github.com/dlr-wf/ExcitationSolve.git
 ```
@@ -287,11 +292,17 @@ Use the `excitationsolve.ExcitationSolveScipy` class in combination with the `sc
 ```python
 excsolve_obj = ExcitationSolveScipy(maxiter=100, tol=1e-10, save_parameters=True)
 optimizer = excsolve_obj.minimize
-res = scipy.optimize.minimize(cost, params, method=optimizer)
+def callback(xk): # or callback(intermediate_result)
+    print(xk)
+options = dict(parameter_occ=parameter_occ) # optional, use if parameters occur multiple times in the ansatz
+res = scipy.optimize.minimize(cost, params, method=optimizer, callback=callback, options=options)
 energies = excsolve_obj.energies
 counts = excsolve_obj.nfevs
 ```
 
+### Optimal parameters of double excitations w.r.t. the Hartree-Fock state
+Use `exitationsolve.optimal_theta` and `excitationsolve.optimal_theta_pyscf` to calculate analytic optimal parameter values for individual double excitations when applied to the Hartree-Fock reference state. Both functions return the optimal parameter and the energy difference to the Hartree-Fock energy. The optimal parameter is defined as $\theta^*=\argmin_\theta\bra{\mathrm{HF}}U^\dagger(\theta) H U(\theta)\ket{\mathrm{HF}}$ where $H$ is the electronic structure Hamiltonian, $U(\theta)$ is **one** double excitation, and $\ket{\mathrm{HF}}$ is the Hartree-Fock state. In [Haas et al., 2026](https://doi.org/10.48550/arXiv.2602.10776) it has been shown that initializing doubles in their respective optimal parameter and appending them to the ansatz in order of energy impact is an efficient operator selection and warm-start strategy.
+
 ### Testing
 To run the tests, install the needed dependencies with
 ```bash
@@ -315,7 +326,7 @@ Feel free to contact [David Melching](mailto:David.Melching@dlr.de) if you have
 ## Citation
 If you use portions of this code please cite our [paper](https://www.nature.com/articles/s42005-025-02375-9):
 ```bibtex
-@article{Jaeger2024Fast,
+@article{Jaeger2025Fast,
     title={Fast gradient-free optimization of excitations in variational quantum eigensolvers},
     author={Jäger, Jonas and Kaldenbach, Thierry N. and Haas, Max and Schultheis, Erik},
     year={2025},
@@ -329,5 +340,18 @@ If you use portions of this code please cite our [paper](https://www.nature.com/
 }
 ```
 
+If you use the `exitationsolve.optimal_theta` or `excitationsolve.optimal_theta_pyscf` functionalities please also cite [Haas et al., 2026](https://doi.org/10.48550/arXiv.2602.10776):
+```bibtex
+@article{Haas2026Efficient,
+    title={Efficient Operator Selection and Warm-Start Strategy for Excitations in Variational Quantum Eigensolvers}, 
+    url={https://arxiv.org/abs/2602.10776},
+    DOI={10.48550/ARXIV.2602.10776},
+    publisher={arXiv},
+    author={Haas, Max and Kaldenbach, Thierry N. and Hammerschmidt, Thomas and Barragan-Yani, Daniel}, 
+    year={2026} 
+} 
+```
+
+
 ## Acknowledgment
 This project was made possible by the DLR Quantum Computing Initiative and the Federal Ministry for Economic Affairs and Climate Action; https://qci.dlr.de/quanticom.