excitationsolve 2.1.2__tar.gz → 2.2.0__tar.gz

excitationsolve-2.2.0/CITATION.bib

@@ -0,0 +1,12 @@
+@article{Jaeger2024Fast,
+    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},
+    volume={8},
+    number={1},
+    journal={Communications Physics},
+    publisher={Springer Science and Business Media LLC},
+    language={en},
+    url={http://dx.doi.org/10.1038/s42005-025-02375-9},
+    DOI={10.1038/s42005-025-02375-9},
+}

{excitationsolve-2.1.2/excitationsolve.egg-info → excitationsolve-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: excitationsolve
-Version: 2.1.2
+Version: 2.2.0
 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,
@@ -234,9 +234,14 @@ Requires-Dist: openfermionpyscf==0.5; extra == "examples"
 Requires-Dist: aiohttp==3.11.15; extra == "examples"
 Requires-Dist: fsspec==2025.2.0; extra == "examples"
 Requires-Dist: h5py==3.13.0; extra == "examples"
+Provides-Extra: test
+Requires-Dist: pytest>=9.0; extra == "test"
+Requires-Dist: matplotlib; extra == "test"
+Requires-Dist: tencirchem-ng==2024.10; extra == "test"
+Requires-Dist: pyscf==2.8.0; extra == "test"
 Dynamic: license-file
 
-# ExcitationSolve [![arXiv](https://img.shields.io/badge/arXiv-2409.05939-blue.svg?logo=arxiv&logoColor=white.svg)](https://arxiv.org/abs/2409.05939) [![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)
 
 An optimization algorithm for ansätze consisting of excitation operators in variational quantum eigensolvers (VQEs).
 
@@ -298,17 +303,19 @@ counts = excsolve_obj.nfevs
 Feel free to contact [David Melching](mailto:David.Melching@dlr.de) if you have any questions.
 
 ## Citation
-If you use portions of this code please cite our [paper](https://arxiv.org/abs/2409.05939):
+If you use portions of this code please cite our [paper](https://www.nature.com/articles/s42005-025-02375-9):
 ```bibtex
-@misc{Jaeger2024Fast,
-      title={Fast gradient-free optimization of excitations in variational quantum eigensolvers}, 
-      author={Jonas Jäger and Thierry Nicolas Kaldenbach and Max Haas and Erik Schultheis},
-      year={2024},
-      eprint={2409.05939},
-      archivePrefix={arXiv},
-      primaryClass={quant-ph},
-      url={https://arxiv.org/abs/2409.05939}, 
-      doi={10.48550/arXiv.2409.05939}
+@article{Jaeger2024Fast,
+    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},
+    volume={8},
+    number={1},
+    journal={Communications Physics},
+    publisher={Springer Science and Business Media LLC},
+    language={en},
+    url={http://dx.doi.org/10.1038/s42005-025-02375-9},
+    DOI={10.1038/s42005-025-02375-9},
 }
 ```
 

{excitationsolve-2.1.2 → excitationsolve-2.2.0}/README.md

@@ -1,4 +1,4 @@
-# ExcitationSolve [![arXiv](https://img.shields.io/badge/arXiv-2409.05939-blue.svg?logo=arxiv&logoColor=white.svg)](https://arxiv.org/abs/2409.05939) [![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)
 
 An optimization algorithm for ansätze consisting of excitation operators in variational quantum eigensolvers (VQEs).
 
@@ -60,17 +60,19 @@ counts = excsolve_obj.nfevs
 Feel free to contact [David Melching](mailto:David.Melching@dlr.de) if you have any questions.
 
 ## Citation
-If you use portions of this code please cite our [paper](https://arxiv.org/abs/2409.05939):
+If you use portions of this code please cite our [paper](https://www.nature.com/articles/s42005-025-02375-9):
 ```bibtex
-@misc{Jaeger2024Fast,
-      title={Fast gradient-free optimization of excitations in variational quantum eigensolvers}, 
-      author={Jonas Jäger and Thierry Nicolas Kaldenbach and Max Haas and Erik Schultheis},
-      year={2024},
-      eprint={2409.05939},
-      archivePrefix={arXiv},
-      primaryClass={quant-ph},
-      url={https://arxiv.org/abs/2409.05939}, 
-      doi={10.48550/arXiv.2409.05939}
+@article{Jaeger2024Fast,
+    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},
+    volume={8},
+    number={1},
+    journal={Communications Physics},
+    publisher={Springer Science and Business Media LLC},
+    language={en},
+    url={http://dx.doi.org/10.1038/s42005-025-02375-9},
+    DOI={10.1038/s42005-025-02375-9},
 }
 ```
 

{excitationsolve-2.1.2 → excitationsolve-2.2.0}/excitationsolve/__init__.py

@@ -1,3 +1,3 @@
 from excitationsolve.info import __version__, HOMEPAGE
-from excitationsolve.excitation_solve import excitation_solve_step
+from excitationsolve.excitation_solve import excitation_solve_step, excitation_solve_step_shared_param
 from excitationsolve.excitation_solve_scipy import ExcitationSolveScipy

excitationsolve-2.2.0/excitationsolve/excitation_solve.py

@@ -0,0 +1,189 @@
+import logging
+import numpy as np
+from excitationsolve.trig_poly_utils import fourier_series_minimum
+
+
+def excitation_solve_step(
+    parameter_variations: list | np.ndarray,
+    energy_samples: list | np.ndarray,
+    return_coeffs=False,
+    non_exact=False,
+) -> tuple[float, float] | tuple[float, float, np.ndarray]:
+    """
+    Optimizes a single excitation parameter globally given the energies for five shifts of this parameters.
+    Recommended to use in a loop for all excitation parameters and perform multiple sweeps through the parameters (potentially shuffled) until convergence.
+
+    Args:
+        parameter_variations: list or np.ndarray
+            Five variations/shifts of a single excitation parameter.
+        energy_samples: list or np.ndarray
+            Five energy samples for a single excitation parameter varied.
+    Returns:
+        float, float
+            The optimized excitation parameter and the corresponding energy.
+    """
+
+    parameter_variations = np.array(parameter_variations).flatten()
+    energy_samples = np.array(energy_samples).flatten()
+    assert len(parameter_variations) >= 5, f"The number of parameter variations must be at least 5. Got {len(parameter_variations)}."
+    assert len(energy_samples) >= 5, f"The number of energy samples must be at least 5. Got {len(energy_samples)}."
+    assert len(parameter_variations) == len(energy_samples), (
+        f"The number of parameter variations and energy samples must match. Got {len(parameter_variations)} and {len(energy_samples)}."
+    )
+    assert parameter_variations.max() - parameter_variations.min() <= 4 * np.pi, (
+        "The parameter variations must be within one period of the excitation operator (4*pi)."
+    )
+
+    # ### Fit second-order Fourier series / trigonometric polynomial to the energy samples: ###
+    # Determine linear equation system with N equations and 5 unknowns (N number of samples):
+    c1 = np.cos(parameter_variations / 2)
+    s1 = np.sin(parameter_variations / 2)
+    c2 = np.cos(parameter_variations)
+    s2 = np.sin(parameter_variations)
+    A = np.array([np.ones(len(energy_samples)), c1, s1, c2, s2]).T
+    b = np.array(energy_samples)
+    logging.debug("Linear equation system: \nA: \n%s \n b: %s", np.around(A, 3), b)
+
+    if len(parameter_variations) == 5:
+        # ## Exact reconstruction: ##
+        # solve the equation system:
+        coeffs = np.linalg.solve(A, b)
+    else:
+        # ## Fitted reconstruction (least squares fit) for potentially noisy energy values: ##
+        logging.debug(
+            "More than 5 parameter variations or energy samples provided. A least squares fit will be performed instead of an exact reconstruction."
+        )
+        coeffs, residuals, rank_A, s = np.linalg.lstsq(A, b)
+        logging.debug(
+            "Least-squares fit info:\n\tResiduals: %s \n\tRank of A: %i \n\tSingular values of A: %s",
+            residuals,
+            rank_A,
+            s,
+        )
+
+    logging.debug("Solved coefficients: %s", coeffs)
+
+    if non_exact:
+        # reconstructed energy function:
+        def energy_function(xs):
+            c1 = np.cos(xs / 2)
+            s1 = np.sin(xs / 2)
+            c2 = np.cos(xs)
+            s2 = np.sin(xs)
+            return coeffs[0] + coeffs[1] * c1 + coeffs[2] * s1 + coeffs[3] * c2 + coeffs[4] * s2
+
+        ### Brute-force optimization of reconstruction
+        n_samples = int(1e3)
+        x_min, x_max = -2 * np.pi, 2 * np.pi
+        x = np.linspace(x_min, x_max, n_samples)
+        y = energy_function(x)  # Note, vectorized evaluation must be supported!
+        min_idx = np.argmin(y)
+        return x[min_idx], y[min_idx]
+
+    # ### Optimize parameter globally in reconstruction (companion matrix method)
+    a = [coeffs[0], *coeffs[1::2]]  # cosine coefficients
+    b = coeffs[2::2]  # sine coefficients
+    assert len(a) == len(b) + 1, (
+        f"The number of cosine coefficients must be one more than the number of sine coefficients. Got {len(a)} and {len(b)}."
+    )
+    min_x, min_y = fourier_series_minimum(a, b, return_y=True)
+    # rescale to original parameter range since the optimization was performed on the interval [pi, pi] with doubled frequencies instead of [-2*pi, 2*pi]:
+    min_x *= 2
+
+    if return_coeffs:
+        return min_x, min_y, coeffs
+    return min_x, min_y
+
+
+def excitation_solve_step_shared_param(
+    parameter_occ: int,
+    parameter_variations: list | np.ndarray,
+    energy_samples: list | np.ndarray,
+    return_coeffs=False,
+) -> tuple[float, float] | tuple[float, float, np.ndarray]:
+    """
+    Optimizes a single excitation parameter globally given the energies for 4S+1 shifts of this parameters.
+    Recommended to use in a loop for all excitation parameters and perform multiple sweeps through the parameters (potentially shuffled) until convergence.
+
+    Args:
+        parameter_occ: int
+            Number of times S the parameter occures in different excitations, i.e., how many excitations share this parameter.
+        parameter_variations: list or np.ndarray
+            4S+1 variations/shifts of a single excitation parameter.
+        energy_samples: list or np.ndarray
+            4S+1 energy samples for a single excitation parameter varied.
+    Returns:
+        float, float
+            The optimized excitation parameter and the corresponding energy.
+    """
+    assert parameter_occ >= 1, f"The number of parameter occurences S must be at least 1. Got {parameter_occ}."
+    parameter_variations = np.array(parameter_variations).flatten()
+    energy_samples = np.array(energy_samples).flatten()
+    assert len(parameter_variations) >= 4 * parameter_occ + 1, (
+        f"The number of parameter variations must be at least 4S+1={4 * parameter_occ + 1}. Got {len(parameter_variations)}."
+    )
+    assert len(parameter_variations) == len(energy_samples), (
+        f"The number of parameter variations and energy samples must match. Got {len(parameter_variations)} and {len(energy_samples)}."
+    )
+    assert parameter_variations.max() - parameter_variations.min() <= 4 * np.pi, (
+        "The parameter variations must be within one period of the excitation operator (4*pi)."
+    )
+
+    # ### Fit Fourier series / trigonometric polynomial of order 2S to the energy samples: ###
+    # Determine linear equation system with N equations and 2S+1 unknowns (N number of samples):
+    c_lst = []
+    s_lst = []
+    for s in range(2 * parameter_occ):
+        s += 1  # to start at 1
+        c_lst.append(np.cos(parameter_variations / 2 * s))
+        s_lst.append(np.sin(parameter_variations / 2 * s))
+    c_s_lst = [val for pair in zip(c_lst, s_lst) for val in pair]  # interleave c_lst and s_lst
+
+    A = np.array([np.ones(len(energy_samples)), *c_s_lst]).T
+    b = np.array(energy_samples)
+    logging.debug("Linear equation system: \nA: \n%s \n b: %s", np.around(A, 3), b)
+
+    if len(parameter_variations) == 4 * parameter_occ + 1:
+        # ## Exact reconstruction: ##
+        # solve the equation system:
+        coeffs = np.linalg.solve(A, b)
+    else:
+        # ## Fitted reconstruction (least squares fit) for potentially noisy energy values: ##
+        logging.debug(
+            "More than 4S+1 parameter variations or energy samples provided. A least squares fit will be performed instead of an exact reconstruction."
+        )
+        coeffs, residuals, rank_A, s = np.linalg.lstsq(A, b)
+        logging.debug(
+            "Least-squares fit info:\n\tResiduals: %s \n\tRank of A: %i \n\tSingular values of A: %s",
+            residuals,
+            rank_A,
+            s,
+        )
+
+    logging.debug("Solved coefficients: %s", coeffs)
+
+    # ### Optimize parameter globally in reconstruction (companion matrix method)
+    a = [coeffs[0], *coeffs[1::2]]  # cosine coefficients
+    b = coeffs[2::2]  # sine coefficients
+    assert len(a) == len(b) + 1, (
+        f"The number of cosine coefficients must be one more than the number of sine coefficients. Got {len(a)} and {len(b)}."
+    )
+    min_x, min_y = fourier_series_minimum(a, b, return_y=True)
+    # rescale to original parameter range since the optimization was performed on the interval [pi, pi] with doubled frequencies instead of [-2*pi, 2*pi]:
+    min_x *= 2
+
+    if return_coeffs:
+        return min_x, min_y, coeffs
+    return min_x, min_y
+
+
+### Demo: ###
+if __name__ == "__main__":
+    np.random.seed(42)  # For reproducibility and because 42 is the answer to everything
+    logging.basicConfig(level=logging.INFO)  # Enable logging
+    # Example data:
+    parameter_variations_test = np.array([0, np.pi / 2, -np.pi / 2, np.pi, -np.pi])
+    energy_samples_test = np.random.rand(5)  # random energies for demonstration
+    # Optimize excitation parameter:
+    optimized_parameter, optimized_energy = excitation_solve_step(parameter_variations_test, energy_samples_test)
+    print(f"Optimized excitation parameter: {optimized_parameter} \nOptimized energy: {optimized_energy}")

{excitationsolve-2.1.2 → excitationsolve-2.2.0}/excitationsolve/excitation_solve_scipy.py

@@ -3,7 +3,7 @@ import logging
 from collections.abc import Callable
 import numpy as np
 from scipy.optimize import OptimizeResult
-from excitationsolve import excitation_solve_step
+from excitationsolve import excitation_solve_step, excitation_solve_step_shared_param
 
 
 class ExcitationSolveScipy:
@@ -55,19 +55,39 @@ class ExcitationSolveScipy:
         self.save_parameters = save_parameters
         self.param_scaling = param_scaling
 
-        self.energies = []
-        self.energies_after_it = []
-        self.nfevs = []
-        self.nfevs_after_it = []
-        self.params = []
+        self.energies = np.array([])
+        self.energies_after_it = np.array([])
+        self.nfevs = np.array([])
+        self.nfevs_after_it = np.array([])
+        self.params = np.array([])
 
     def minimize(self, fun: Callable[[np.ndarray], float], x0: np.ndarray, args=(), **kwargs) -> OptimizeResult:
-        param_dist = 4 * np.pi / self.num_samples
-        shifts = (np.arange(self.num_samples) - self.num_samples // 2) * param_dist
+        """Minimize energy function using the ExcitationSolve optimizer
 
+        Args:
+            fun (Callable[[np.ndarray], float]): Function that evaluates the energy given a set of parameters
+            x0 (np.ndarray): Initial starting point of the optimizer
+            parameter_occ (np.ndarray, optional):  Number of times S the parameters occur in different excitations, i.e.,
+                                                   how many excitations share each parameter.
+                                                   parameter_occ[i] is the number of times the i-th parameter occurs in different excitations.
+                                                   Defaults to [1, 1, ...] (all set to 1).
+
+        Returns:
+            OptimizeResult: Scipy OptimizeResult object
+        """
         params_excsolve = np.array(x0.copy())
         num_params = len(params_excsolve)
 
+        parameter_occ = kwargs.get("parameter_occ")
+        if parameter_occ is None:
+            parameter_occ = np.ones((num_params,))
+        if len(parameter_occ) != num_params:
+            raise ValueError(f"Length of parameter_occ ({len(parameter_occ)}) does not equal number of parameters ({num_params})!")
+        parameter_occ = parameter_occ.astype(int)
+        logging.info(f"{parameter_occ=}")
+        for i, val in enumerate(parameter_occ):
+            logging.info(f"\t{i}-th parameter appears {val} times")
+
         energy_at_zero = None
         if self.hf_energy is not None:
             energy_at_zero = self.hf_energy
@@ -76,6 +96,10 @@ class ExcitationSolveScipy:
         for n_iter in range(self.maxiter):
             for param_to_vary in range(num_params):
                 e_shifted = []
+
+                num_samples_tmp = max(self.num_samples, 4 * parameter_occ[param_to_vary] + 1)
+                param_dist = 4 * np.pi / num_samples_tmp
+                shifts = (np.arange(num_samples_tmp) - num_samples_tmp // 2) * param_dist
                 for shift in shifts:
                     if shift == 0.0 and energy_at_zero is not None:
                         e_shifted.append(energy_at_zero)
@@ -92,7 +116,9 @@ class ExcitationSolveScipy:
                     )
                     nfev += 1
 
-                params_excsolve[param_to_vary], current_energy_excsolve = excitation_solve_step(
+                logging.debug("Now optimizing parameter number %s which occurs %s times", param_to_vary, parameter_occ[param_to_vary])
+                params_excsolve[param_to_vary], current_energy_excsolve = excitation_solve_step_shared_param(
+                    parameter_occ[param_to_vary],
                     (shifts * self.param_scaling + params_excsolve[param_to_vary]) / self.param_scaling,
                     e_shifted,
                 )
@@ -106,14 +132,14 @@ class ExcitationSolveScipy:
                 # about the optimization progress/convergence
                 # fun(params_excsolve * param_scaling)
 
-                self.energies.append(current_energy_excsolve)
-                self.nfevs.append(nfev)
+                self.energies = np.append(self.energies, current_energy_excsolve)
+                self.nfevs = np.append(self.nfevs, nfev)
                 if self.save_parameters:
-                    self.params.append(params_excsolve.copy())
+                    self.params = np.append(self.params, params_excsolve.copy())
                 logging.debug("Current ExcitationSolve optimum energy: %s", current_energy_excsolve)
 
-            self.energies_after_it.append(current_energy_excsolve)
-            self.nfevs_after_it.append(nfev)
+            self.energies_after_it = np.append(self.energies_after_it, current_energy_excsolve)
+            self.nfevs_after_it = np.append(self.nfevs_after_it, nfev)
             if n_iter > 0:
                 msg = "Current ExcitationSolve optimum energy after %s iterations: %s | Diff. to prev.: %s" % (
                     n_iter + 1,

{excitationsolve-2.1.2 → excitationsolve-2.2.0}/excitationsolve/info.py

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