qhyper 0.2.1__tar.gz → 0.3.0__tar.gz

{qhyper-0.2.1 → qhyper-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: qhyper
-Version: 0.2.1
+Version: 0.3.0
 Summary: Quantum and classical problem solvers
 Author: ACK Cyfronet AGH
 Author-email: tomasz.lamza@cyfronet.pl
@@ -14,13 +14,22 @@ Classifier: Operating System :: MacOS :: MacOS X
 Classifier: Operating System :: Microsoft :: Windows
 Description-Content-Type: text/markdown
 License-File: LICENSE.txt
-Requires-Dist: numpy
-Requires-Dist: PennyLane
+Requires-Dist: numpy~=1.26.4
+Requires-Dist: PennyLane~=0.38
 Requires-Dist: tdqm
-Requires-Dist: sympy
+Requires-Dist: sympy==1.13.1
 Requires-Dist: dwave-system
 Requires-Dist: gurobipy
 Requires-Dist: pandas
 Requires-Dist: wfcommons
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: requires-dist
+Dynamic: summary
 
 A package that allows to build and solve quantum and classical problems using predefined solvers and problems.

{qhyper-0.2.1/QHyper/solvers/vqa/eval_funcs → qhyper-0.3.0/QHyper}/__init__.py

@@ -2,4 +2,6 @@
 # Smart Growth Operational Programme (2014-2020), Measure 4.2
 # under the grant agreement no. POIR.04.02.00-00-D014/20-00
 
-
+"""
+API reference documentation for QHyper.
+"""

{qhyper-0.2.1 → qhyper-0.3.0}/QHyper/constraint.py

@@ -1,10 +1,42 @@
+"""This module contains the Constraint class which is used to represent a, well, 
+constraint. It is used in the QUBO formulation to define the left and right
+hand sides of the constraints, and the operator.
+
+.. rubric:: Main class
+
+.. autosummary::
+    :toctree: generated
+
+    Constraint  -- implementation of the constraint.
+
+.. rubric:: Enum Classes
+
+.. autoclass:: MethodsForInequalities
+
+
+.. rubric:: Functions
+
+.. autofunction:: get_number_of_constraints
+
+"""
+
 import uuid
 from enum import Enum
 
-from QHyper.polynomial import Polynomial
+from QHyper.polynomial import Polynomial, PolynomialType
 
 
 class MethodsForInequalities(Enum):
+    """Enum class with different methods for handling inequalities.
+
+    There are two available methods for handling inequalities:
+    .. list-table::
+
+        * - SLACKS_LOG_2
+          - UNBALANCED_PENALIZATION 
+        * - the method uses slack variables in number of log2(n)
+          - the method uses unbalanced penalization
+    """
     SLACKS_LOG_2 = 0
     UNBALANCED_PENALIZATION = 1
 
@@ -14,6 +46,8 @@ UNBALANCED_PENALIZATION = MethodsForInequalities.UNBALANCED_PENALIZATION
 
 
 class Operator(Enum):
+    """Enum class with different operators.
+    """
     EQ = "=="
     GE = ">="
     LE = "<="
@@ -21,13 +55,13 @@ class Operator(Enum):
 
 class Constraint:
     """
-    A class to represent a constraint.
+    A class representing the constraint.
 
     Attributes
     ----------
-    lhs : Polynomial
+    lhs : PolynomialType
         The left-hand side of the constraint.
-    rhs : Polynomial, default Polynomial(0)
+    rhs : PolynomialType, default 0
         The right-hand side of the constraint.
     operator : Operator, default Operator.EQ
         The operator of the constraint. It can be ==, >=, <=.
@@ -42,17 +76,18 @@ class Constraint:
         Example use is assigning same weight to the constraints with the same
         group when creating qubo.
     """
+
     def __init__(
         self,
-        lhs: Polynomial,
-        rhs: Polynomial = Polynomial(0),
+        lhs: PolynomialType,
+        rhs: PolynomialType = 0,
         operator: Operator = Operator.EQ,
         method_for_inequalities: MethodsForInequalities | None = None,
         label: str = "",
         group: int = -1,
     ) -> None:
-        self.lhs: Polynomial = lhs
-        self.rhs: Polynomial = rhs
+        self.lhs = lhs if isinstance(lhs, Polynomial) else Polynomial(lhs)
+        self.rhs = rhs if isinstance(rhs, Polynomial) else Polynomial(rhs)
         self.operator: Operator = operator
 
         if operator != Operator.EQ and method_for_inequalities is None:

{qhyper-0.2.1 → qhyper-0.3.0}/QHyper/converter.py

@@ -3,6 +3,20 @@
 # under the grant agreement no. POIR.04.02.00-00-D014/20-00
 
 
+"""This module contains the Converter class with static methods for converting Problem objects to different formats.
+
+To use different solvers, but with the same Problem representation, some form 
+of conversion is needed. This module provides methods for converting Problem
+objects to ConstrainedQuadraticModel, DiscreteQuadraticModel, and QUBO formats.
+
+.. autosummary:: 
+    :toctree: generated
+    
+    Converter
+
+"""
+
+
 from typing import cast
 
 import dimod
@@ -63,7 +77,7 @@ class Converter:
         return weight[0]*lhs + weight[1]*lhs**2
 
     @staticmethod
-    def assign_weights_to_constraints(
+    def assign_penalty_weights_to_constraints(
         constraints_weights: list[float], constraints: list[Constraint]
     ) -> list[tuple[list[float], Constraint]]:
         weights_constraints_list = []
@@ -98,13 +112,13 @@ class Converter:
         return weights_constraints_list
 
     @staticmethod
-    def create_qubo(problem: Problem, weights: list[float]) -> Polynomial:
-        of_weight = weights[0] if len(weights) else 1
+    def create_qubo(problem: Problem, penalty_weights: list[float]) -> Polynomial:
+        of_weight = penalty_weights[0] if len(penalty_weights) else 1
         result = float(of_weight) * problem.objective_function
 
-        constraints_weights = weights[1:]
-        for weight, constraint in Converter.assign_weights_to_constraints(
-            constraints_weights, problem.constraints
+        constraints_penalty_weights = penalty_weights[1:]
+        for weight, constraint in Converter.assign_penalty_weights_to_constraints(
+            constraints_penalty_weights, problem.constraints
         ):
             if constraint.operator == Operator.EQ:
                 result += float(weight[0]) * (

qhyper-0.3.0/QHyper/optimizers/__init__.py

@@ -0,0 +1,111 @@
+# This work was supported by the EuroHPC PL infrastructure funded at the
+# Smart Growth Operational Programme (2014-2020), Measure 4.2
+# under the grant agreement no. POIR.04.02.00-00-D014/20-00
+
+"""
+This module contains implementations of different optimizers.
+Some of the optimizers are written from scratch based on popular algorithms,
+while others are just a wrapper for existing solutions.
+No optimizer is imported by deafult to reduce number of dependencies.
+To use any optimizer you can import it directly like
+
+.. code-block:: python
+
+    from QHyper.optimizers.random import Random
+
+or use function :py:func:`Optimizers.get` with the name of the optimizer.
+Any optimizer that is in directory 'QHyper/custom' or 'custom' will be
+also available in this function.
+
+.. rubric:: Optimization result dataclass
+
+.. autosummary::
+    :toctree: generated
+
+    OptimizationResult
+    OptimizationParameter
+
+.. rubric:: Interface
+
+.. autosummary::
+    :toctree: generated
+
+    Optimizer
+
+.. rubric:: Available optimizers
+
+.. autosummary::
+    :toctree: generated
+
+    scipy_minimizer.ScipyOptimizer -- Wrapper for the scipy.optimize.minimize function.
+    qml_gradient_descent.QmlGradientDescent -- Wrapper for the PennyLane gradient descent optimizers.
+    cem.CEM -- Cross-entropy method optimizer.
+    random.Random -- Random search optimizer.
+    grid_search.GridSearch -- Grid search optimizer.
+    dummy.Dummy -- Dummy optimizer.
+
+.. rubric:: Additional functions
+
+.. autoclass:: Optimizers
+    :members:
+
+"""
+import copy
+from typing import Type, Any
+
+from QHyper.util import search_for
+
+from QHyper.optimizers.base import (                # noqa: F401
+    Optimizer, OptimizationResult, OptimizerError, OptimizationParameter)  # noqa: F401
+
+from .dummy import Dummy
+
+
+class Optimizers:
+    custom_optimizers: None | dict[str, type] = None
+
+    @staticmethod
+    def get(name: str) -> Type[Optimizer]:
+        """
+        Get Optimizer class by name.
+
+        The optimizer will be available by the 'name' attribute if defined or
+        by the class name. Letters case doesn't matter.
+        """
+
+        if Optimizers.custom_optimizers is None:
+            Optimizers.custom_optimizers = (
+                search_for(Optimizer, 'QHyper/custom')
+                | search_for(Optimizer, 'custom'))
+
+        name_ = name.lower()
+
+        if name_ in Optimizers.custom_optimizers:
+            return Optimizers.custom_optimizers[name_]
+        elif name_ in ["scipy", "scipyminimizer"]:
+            from .scipy_minimizer import ScipyOptimizer
+            return ScipyOptimizer
+        elif name_ in ["random", "randomsearch"]:
+            from .random import Random
+            return Random
+        elif name_ in ["qml", "qmlgradientdescent"]:
+            from .qml_gradient_descent import QmlGradientDescent
+            return QmlGradientDescent
+        elif name_ in ["cem", "crossentropymethod"]:
+            from .cem import CEM
+            return CEM
+        elif name_ in ["grid", "gridsearch"]:
+            from .grid_search import GridSearch
+            return GridSearch
+        elif name_ in ["dummy"]:
+            return Dummy
+        else:
+            raise OptimizerError(f"Optimizer {name} not found")
+
+
+def create_optimizer(config: dict[str, Any]) -> Optimizer:
+    config_ = copy.deepcopy(config)
+    opt_type = config_.pop('type')
+
+    optimizer_class = Optimizers.get(opt_type)
+    return optimizer_class(**config_)

qhyper-0.3.0/QHyper/optimizers/base.py

@@ -0,0 +1,181 @@
+# This work was supported by the EuroHPC PL infrastructure funded at the
+# Smart Growth Operational Programme (2014-2020), Measure 4.2
+# under the grant agreement no. POIR.04.02.00-00-D014/20-00
+
+
+import abc
+import dataclasses
+
+from abc import abstractmethod
+
+from typing import Callable, Self
+
+
+@dataclasses.dataclass
+class OptimizationParameter:
+    """
+    Dataclass for storing bounds, steps and init values for parameters
+    that might be optimized. Most of the time some of this values are not
+    required, but it depends on the chosen optimization algorithm.
+    Check the documentation of the chosen algorithm to see which values are
+    required.
+
+    Attributes
+    ----------
+    min : list[float]
+        List of minimum values for each parameter.
+    max : list[float]
+        List of maximum values for each parameter.
+    step : list[float]
+        List of step values for each parameter. Used for example in the grid
+        search algorithm. For 0-th parameter the following values will be
+        generated: min[0], min[0] + step[0], min[0] + 2*step[0], ...
+    init : list[float]
+        List of initial values for each parameter. Some algorithms require
+        starting point to be set.
+    """
+
+    min: list[float] = dataclasses.field(default_factory=list)
+    max: list[float] = dataclasses.field(default_factory=list)
+    step: list[float] = dataclasses.field(default_factory=list)
+    init: list[float] = dataclasses.field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        self.min = list(self.min)
+        self.max = list(self.max)
+        self.step = list(self.step)
+        self.init = list(self.init)
+
+    def assert_bounds(self) -> None:
+        """Check if bounds are correctly set.
+        """
+
+        if not self.min:
+            raise ValueError("Min bounds are required")
+        if not self.max:
+            raise ValueError("Max bounds are required")
+        if len(self.min) != len(self.max):
+            raise ValueError("Min and Max bounds must have the same length")
+
+    def assert_step(self) -> None:
+        """Check if steps are correctly set.
+        """
+        self.assert_bounds()
+        if len(self.step) == 0:
+            raise ValueError("Steps are required")
+        if len(self.min) != len(self.step):
+            raise ValueError("Steps must have the same length as bounds")
+
+    def assert_init(self) -> None:
+        """Check if init values are correctly set.
+        """
+        if len(self.init) == 0:
+            raise ValueError("Init are required")
+
+    def assert_bounds_init(self) -> None:
+        """Check if bounds and init values are correctly set.
+        """
+        self.assert_bounds()
+        self.assert_init()
+        if len(self.min) != len(self.init):
+            raise ValueError("Init must have the same length as bounds")
+
+    def __add__(self, other: Self) -> 'OptimizationParameter':
+        min_ = self.min + other.min
+        max_ = self.max + other.max
+        step_ = self.step + other.step
+        init_ = self.init + other.init
+        return OptimizationParameter(min_, max_, step_, init_)
+
+    def __len__(self) -> int:
+        if self.min:
+            return len(self.min)
+        if self.max:
+            return len(self.max)
+        if self.init:
+            return len(self.init)
+        return 0
+
+    def update(self,
+               min: list[float] | None = None,
+               max: list[float] | None = None,
+               step: list[float] | None = None,
+               init: list[float] | None = None) -> 'OptimizationParameter':
+        if min is None:
+            min = self.min.copy()
+        if max is None:
+            max = self.max.copy()
+        if step is None:
+            step = self.step.copy()
+        if init is None:
+            init = self.init.copy()
+        return OptimizationParameter(min, max, step, init)
+
+    @property
+    def bounds(self) -> list[tuple[float, float]]:
+        return list(zip(self.min, self.max))
+
+
+class OptimizerError(Exception):
+    """
+    Base class for exceptions in this module.
+    """
+    ...
+
+
+@dataclasses.dataclass
+class OptimizationResult:
+    """
+    Dataclass for storing the results of an optimization run.
+
+    Attributes
+    ----------
+    value : float
+        The minimum function value found by the optimization algorithm.
+    params : list[float]
+        The optimal point (function arguments) found by the optimization
+        algorithm.
+    history : list[list[OptimizationResult]]
+        The history of the optimization algorithm. Each element of the list
+        represents the results of the objective function at each
+        iteration - there can be multiple results per each iteration (epoch).
+    """
+
+    value: float
+    params: list[float]
+    history: list[list['OptimizationResult']] = dataclasses.field(
+        default_factory=list)
+
+
+class Optimizer(abc.ABC):
+    """
+    Base class for Optimizer.
+
+    """
+
+    @abstractmethod
+    def minimize(
+        self,
+        func: Callable[[list[float]], OptimizationResult],
+        init: OptimizationParameter
+    ) -> OptimizationResult:
+        """
+        Method that minimizes the given function using the
+        implemented optimization algorithm.
+        This method has to be implemented by the subclass.
+
+        Parameters
+        ----------
+        func : Callable[[list[float]], OptimizationResult]
+            The objective function to be minimized.
+        init : OptimizationParameter
+            The initial parameter for the optimization algorithm.
+            The required fields are defined by subclass.
+
+        Returns
+        -------
+        OptimizationResult
+            Result contains the minimum function value, the
+            corresponding optimal point, and the history of
+            the optimization.
+        """

{qhyper-0.2.1 → qhyper-0.3.0}/QHyper/optimizers/cem.py

@@ -11,18 +11,23 @@ from numpy.typing import NDArray
 from QHyper.optimizers.util import run_parallel
 
 from QHyper.optimizers.base import (
-    Optimizer, OptimizationResult, OptimizerError)
+    Optimizer, OptimizationResult, OptimizerError, OptimizationParameter)
 
 
 class CEM(Optimizer):
     """Implementation of the Cross Entropy Method for hyperparameter tuning
 
+    The Cross Entropy Method is a stochastic optimization algorithm that
+    iteratively samples candidate solutions from a multivariate normal
+    distribution. The mean and covariance of the distribution are updated
+    based on the best samples from the previous iteration.
+    This alogrithm requries the following parameters to be set:
+    - `min` and `max` bounds for each parameter
+    - `init` initial values for each parameter
+
+
     Attributes
     ----------
-    bounds : numpy.ndarray, optional
-        The bounds for the optimization algorithm. Not all optimizers
-        support bounds. The shape of the array should be (n, 2), where
-        n is the number of parameters (`init` in method :meth:`minimize`).
     verbose : bool, default False
         Whether to print the optimization progress.
     disable_tqdm : bool, default True
@@ -41,7 +46,6 @@ class CEM(Optimizer):
         `samples_per_epoch * elite_frac`.
     """
 
-    bounds: NDArray
     verbose: bool
     disable_tqdm: bool
     epochs: int
@@ -52,7 +56,6 @@ class CEM(Optimizer):
 
     def __init__(
         self,
-        bounds: NDArray,
         verbose: bool = False,
         disable_tqdm: bool = True,
         epochs: int = 5,
@@ -73,7 +76,6 @@ class CEM(Optimizer):
         processes : int, default 1
         """
 
-        self.bounds = bounds
         self.verbose = verbose
         self.disable_tqdm = disable_tqdm
         self.epochs = epochs
@@ -85,44 +87,40 @@ class CEM(Optimizer):
             int(self.samples_per_epoch * self.elite_frac), 1)
 
     def _get_points(
-        self, mean: NDArray, cov: NDArray
+        self, mean: NDArray, cov: NDArray, init: OptimizationParameter
     ) -> NDArray:
-        if self.bounds is None:
-            raise OptimizerError('This optimizer requires bounds')
-
         # TODO
         hyperparams: list[NDArray] = []
+        bounds = np.array(init.bounds)
+
         while len(hyperparams) < self.samples_per_epoch:
             point = np.random.multivariate_normal(mean, cov)
             if (
-                    (self.bounds[:, 0] <= point).all()
-                    and (point < self.bounds[:, 1]).all()
+                    (bounds[:, 0] <= point).all()
+                    and (point < bounds[:, 1]).all()
             ):
                 hyperparams.append(point)
 
         return np.vstack(hyperparams)
 
-    def minimize_(
+    def minimize(
         self,
-        func: Callable[[NDArray], OptimizationResult],
-        init: NDArray | None,
+        func: Callable[[list[float]], OptimizationResult],
+        init: OptimizationParameter,
     ) -> OptimizationResult:
-        if init is None:
-            raise OptimizerError("Initial point must be provided.")
-
-        self.check_bounds(init)
+        init.assert_bounds_init()
 
-        mean = init.flatten()
+        mean = np.array(init.init)
         cov = np.identity(len(mean))
-        best_hyperparams = init
-        best_result = OptimizationResult(np.inf, init, [])
+        best_hyperparams = init.init
+        best_result = OptimizationResult(np.inf, init.init, [])
         history: list[list[OptimizationResult]] = []
 
         for i in range(self.epochs):
             if self.verbose:
                 print(f'Epoch {i+1}/{self.epochs}')
 
-            hyperparams = self._get_points(mean, cov)
+            hyperparams = self._get_points(mean, cov, init)
             results = run_parallel(func, hyperparams, self.processes,
                                    self.disable_tqdm)
 

{qhyper-0.2.1 → qhyper-0.3.0}/QHyper/optimizers/dummy.py

@@ -5,10 +5,8 @@
 
 from typing import Callable
 
-from numpy.typing import NDArray
-
 from QHyper.optimizers.base import (
-    Optimizer, OptimizationResult, OptimizerError)
+    Optimizer, OptimizationResult, OptimizerError, OptimizationParameter)
 
 
 class Dummy(Optimizer):
@@ -16,16 +14,19 @@ class Dummy(Optimizer):
     Dummy optimizer.
 
     This optimizer is used as a default optimizer in the case
-    when no optimizer is selected.
+    when no optimizer is selected. It simply evaluates the function.
+    It requires the initial point to be provided.
+
     """
 
-    def minimize_(
+    def minimize(
         self,
-        func: Callable[[NDArray], OptimizationResult],
-        init: NDArray | None,
+        func: Callable[[list[float]], OptimizationResult],
+        init: OptimizationParameter | None,
     ) -> OptimizationResult:
         if init is None:
             raise OptimizerError("Initial point must be provided.")
+        init.assert_init()
 
-        result = func(init)
+        result = func(init.init)
         return OptimizationResult(result.value, result.params, [[result]])