eqc-models 0.9.8__py3-none-any.whl

eqc_models-0.9.8.data/platlib/eqc_models/base/base.py

@@ -0,0 +1,150 @@
+# (C) Quantum Computing Inc., 2024.
+import os
+import logging
+from typing import (Dict, List, Tuple, Union)
+from warnings import warn
+import numpy as np
+from eqc_models.base.operators import Polynomial, QUBO, OperatorNotAvailableError
+
+log = logging.getLogger(name=__name__)
+
+# base class 
+class EqcModel:
+    """ 
+
+    EqcModel subclasses must provide these properties/methods. 
+    
+    :decode: takes a raw solution and translates it into the original problem
+      formulation 
+    :H: property which returns a Hamiltonian operator 
+    :upper_bound: Let D be an array of length n which contains the largest possible value 
+      allowed for x[i], which is the variable at index i, 0<=i<n. This means that a x[i]
+      is in the domain [0,D[i]]. If the solution type of x[i] is integer, then x[i] is
+      in the set of integers, Z, and also 0<=x[i]<=floor(D[i]).
+    :qudit_limits: maximum value permitted for each qudit 
+
+    >>> model = EqcModel()
+    >>> ub = np.array([1, 1.5, 2])
+    >>> model.upper_bound = ub # doctest: +ELLIPSIS
+    Traceback (most recent call last):
+    ...
+    ValueError: ...
+    >>> model.upper_bound = np.ones((3,))
+    >>> (model.upper_bound==np.ones((3,))).all()
+    True
+    >>> model.upper_bound = 2*np.ones((3,))
+    >>> (model.upper_bound==2).all()
+    True
+
+    """
+
+    _upper_bound = None
+    _H = None
+    _machine_slacks = 0
+    
+    def decode(self, solution : np.ndarray) -> np.ndarray:
+        """ Manipulate the solution to match the variable count """
+        
+        # ignore any slacks that may have been added during encoding
+        solution = solution[:-self.machine_slacks]
+        
+        return solution
+
+    @property
+    def upper_bound(self) -> np.array:
+        """ 
+        An array of upper bound values for every variable in the model. Must be integer.
+
+        """
+
+        return self._upper_bound
+
+    @upper_bound.setter
+    def upper_bound(self, value : np.array):
+        value = np.array(value)
+        if (value != value.astype(np.int64)).any():
+            raise ValueError("Upper bound values must be integer")
+        self._upper_bound = value.astype(np.int64)
+
+    @property
+    def domains(self) -> np.array:
+        if self._upper_bound is None:
+            raise ValueError("Variable domains are required for model definition")
+        return self._upper_bound
+
+    @domains.setter
+    def domains(self, value):
+        warn("The domains property is deprecated in favor of naming it upper_bound", DeprecationWarning)
+        self._upper_bound = value
+
+    @property
+    def n(self) -> int:
+        """ Return the number of variables """
+        return int(max(self.upper_bound.shape))
+    
+    @property
+    def H(self):
+        """ Hamiltonian operator of unknown type """
+        return self._H
+
+    @H.setter
+    def H(self, value):
+        """ The H setter ensures that the Hamiltonian is properly formatted. """
+
+        raise NotImplementedError("H property setter not implemented in subclass, can't be set directly")
+
+    @property
+    def sparse(self) -> Tuple[np.ndarray, np.ndarray]:
+        # Implement this for the particular subclasses
+        raise NotImplementedError("sparse must be implemented in a subclass")
+        
+    @property
+    def machine_slacks(self):
+        """ Number of slack qudits to add to the model """
+        return self._machine_slacks
+
+    @machine_slacks.setter
+    def machine_slacks(self, value:int):
+        assert int(value) == value, "value not integer"
+        self._machine_slacks = value
+
+    def evaluateObjective(self, solution : np.ndarray) -> float:
+        raise NotImplementedError("evaluateObjective must be implemented in a subclass")
+    
+    def createConfigElements(self) -> Dict:
+        obj = {"number_of_nonzero": None}
+        return obj
+    def createBenchmarkConfig(self, fname : str) -> None:
+        obj = self.createConfigElements()
+    
+    @property
+    def dynamic_range(self) -> float:
+        raise NotImplementedError("EqcModel does not implement dynamic_range")
+        
+    @property
+    def polynomial(self) -> Polynomial:
+        raise OperatorNotAvailableError("Polynomial operator not available")
+    
+    @property
+    def qubo(self) -> QUBO:
+        raise OperatorNotAvailableError("QUBO operator not available")
+    
+class SumConstraintMixin:
+
+    _sum_constraint = None
+
+    @property
+    def sum_constraint(self):
+        return self._sum_constraint
+    
+    @sum_constraint.setter
+    def sum_constraint(self, value : Union[float, int]):
+        assert value >= 0, "sum_constraint must be greater than or equal to one"
+        self._sum_constraint = value
+
+class ModelSolver:
+    """ Provide a common interface for solver implementations. 
+    Store a model, implement a solve method."""
+
+    def solve(self, model:EqcModel, *args, **kwargs) -> Dict:
+        raise NotImplementedError()

eqc_models-0.9.8.data/platlib/eqc_models/base/constraints.py

@@ -0,0 +1,276 @@
+# (C) Quantum Computing Inc., 2024.
+"""
+Four useful classes are provided in this module.
+
+ConstraintsMixin
+    Converts equality constraints to penalties. Depends on the value provided
+    for penalty_multiplier.
+
+InequalitiesMixin
+    Allows inequality constraints, converting to equality constraints before
+    penalties by adding slack variables.
+
+ConstraintModel
+    An example implementation of the ConstraintsMixin.
+
+InequalityConstraintModel
+    An example implementation of the InequalitiesMixin.
+
+>>> lhs = np.array([[1, 1],
+...                 [2, 2]])
+>>> rhs = np.array([1, 1])
+>>> senses = ["LE", "GE"]
+>>> model = InequalityConstraintModel()
+>>> model.constraints = lhs, rhs
+>>> model.senses = senses
+>>> A, b = model.constraints
+>>> A
+array([[ 1.,  1.,  1.,  0.],
+       [ 2.,  2.,  0., -1.]])
+>>> model.penalty_multiplier = 1.0
+>>> model.checkPenalty(np.array([1, 0, 0, 1]))
+0.0
+>>> model.checkPenalty(np.array([1, 1, 0, 0]))
+10.0
+"""
+from typing import (List, Tuple)
+import numpy as np
+from eqc_models.base.base import EqcModel
+
+
+class ConstraintsMixIn:
+    """ 
+    This mixin class contains methods and attributes which transform 
+    linear constraints into penalties.
+    
+    """
+    lhs = None
+    rhs = None
+# alpha is the internal name for the penalty multiplier
+# defaulting to 1 as a user experience enhancement
+# while forcing the user to choose a value helps to
+# remind of the need, it is not friendly to get a None 
+# type error when an attempt to use it is made.
+    alpha = 1
+    linear_objective = None
+    quad_objective = None
+
+    @property
+    def penalties(self) -> Tuple[np.ndarray, np.ndarray]:
+        """ Returns two numpy arrays, one linear and one quadratic pieces of an operator """
+        lhs, rhs = self.constraints
+        if lhs is None or rhs is None:
+            raise ValueError("Constraints lhs and/or rhs are undefined. " +
+                             "Both must be instantiated numpy arrays.")
+        Pq = lhs.T @ lhs
+        Pl = -2 * rhs.T @ lhs
+        return Pl.T, Pq
+    
+    @property
+    def penalty_multiplier(self) -> float:
+        return self.alpha
+    
+    @penalty_multiplier.setter
+    def penalty_multiplier(self, value: float):
+        self.alpha = value
+
+    @property
+    def constraints(self):
+        return self.lhs, self.rhs
+    
+    @constraints.setter
+    def constraints(self, value: Tuple[np.ndarray, np.ndarray]):
+        self.lhs, self.rhs = value
+
+    @property
+    def offset(self) -> float:
+        """ Calculate the offset due to the conversion of constraints to penalties """
+
+        lhs, rhs = self.constraints
+
+        return np.squeeze(rhs.T@rhs)
+
+    def evaluate(self, solution : np.ndarray, alpha : float = None, includeoffset:bool=False):
+        """ 
+        Compute the objective value plus penalties for the given solution. Including
+        the offset will ensure the penalty contribution is non-negative.
+
+        Parameters
+        ----------
+
+        solution : np.array
+            The solution vector for the problem.
+
+        alpha : float
+            Penalty multiplier, optional. This can be used to test different
+            multipliers for determination of sufficiently large values.
+
+        """
+        if alpha is None:
+            alpha = self.penalty_multiplier
+        penalty = self.evaluatePenalties(solution)
+        penalty *= alpha
+        if includeoffset:
+            penalty += alpha * self.offset
+        return penalty + self.evaluateObjective(solution)
+
+    def evaluatePenalties(self, solution) -> float:
+        """ 
+        Evaluate penalty function without alpha or offset 
+
+        Parameters
+        ----------
+
+        solution : np.array
+            The solution vector for the problem.
+
+        """
+
+        Pl, Pq = self.penalties
+        qpart = solution.T@Pq@solution
+        lpart = Pl.T@solution
+        ttlpart = qpart + lpart
+        return ttlpart
+
+    def checkPenalty(self, solution : np.ndarray):
+        """ 
+        Get the penalty of the solution.
+
+        Parameters
+        ----------
+
+        solution : np.array
+            The solution vector for the problem.
+
+        """
+
+        penalty = self.evaluatePenalties(solution)
+        penalty += self.penalty_multiplier * self.offset
+        assert penalty >= 0, "Inconsistent model, penalty cannot be less than 0."
+
+        return penalty
+    
+class InequalitiesMixin:
+    """ 
+    This mixin enables inequality constraints by automatically 
+    generating slack variables for each inequality 
+    
+    This mixin adds a `senses` attribute which has a value for each
+    constraint. The values are one of 'EQ', 'LE' or 'GE' for equal
+    to, less than or equal to or greater than or equal to. The effect
+    of the value is to control whether a slack is added and what
+    the sign of the slack variable in the constraint is. Negative 
+    is used for GE, positive is used for LE and all slack variables
+    get a coefficient magnitude of 1.
+
+    The constraints are modified on demand, so the class members, 
+    `lhs` and `rhs` remain unmodified.
+
+    """
+
+    _senses = None
+    @property
+    def senses(self) -> List[str]:
+        """ Comparison operator by constraint """
+
+        return self._senses
+    
+    @senses.setter
+    def senses(self, value : List[str]):
+        self._senses = value
+
+    @property
+    def num_slacks(self) -> int:
+        """ 
+        The number of slack variables. Will match the number of inequality
+        constraints. 
+
+        Returns
+        -------
+
+        number : int
+
+        """
+        G = self.lhs
+        m = G.shape[0]
+        senses = self.senses
+        num_slacks = sum([0 if senses[i] == "EQ" else 1 for i in range(m)])
+        return num_slacks
+        
+    @property
+    def constraints(self) -> Tuple[np.ndarray, np.ndarray]:
+        """ 
+        Get the general form of the constraints, add slacks where needed
+        and return a standard, equality constraint form.
+        
+        """
+        G = self.lhs
+        h = self.rhs 
+        senses = self.senses
+
+        m = G.shape[0]
+        n = G.shape[1]
+        num_slacks = self.num_slacks
+        # Adjusted dimensions for slack variables
+        slack_vars = np.zeros((m, num_slacks)) 
+        ii = 0
+        for i in range(m):
+            rule = senses[i]
+            if rule == "LE":
+                # Add slack variable for less than or equal constraint
+                slack_vars[i, ii] = 1  
+                ii += 1
+            elif rule == "GE":
+                # Add negated slack variable for greater than or equal constraint
+                slack_vars[i, ii] = -1 
+                ii += 1
+        A = np.hstack((G, slack_vars)) 
+        b = h
+
+        return A, b
+    
+    @constraints.setter
+    def constraints(self, value : Tuple[np.ndarray, np.ndarray]):
+        if len(value) != 2:
+            raise ValueError("Constraints must be specified as a 2-tuple")
+        self.lhs, self.rhs = value
+
+class ConstraintModel(ConstraintsMixIn, EqcModel):
+    """ 
+    Abstract class for representing linear constrained optimization problems as 
+    EQC models. 
+    
+    """
+
+class InequalityConstraintModel(InequalitiesMixin, ConstraintModel):
+    """
+    Abstract class for a linear constrained optimization model with inequality constraints
+
+    """
+
+# class MIPBinaryModel(ConstraintModel):
+# 
+#     binary_only_variables = None
+# 
+#     @property
+#     def binaries(self) -> List:
+#         return self.binary_only_variables
+#     
+#     @binaries.setter
+#     def binaries(self, value : List) -> None:
+#     for item in value:
+#             assert int(item) == item, "Index of binary variable must be integer"
+#         self.binary_only_variables = value
+# 
+#     @property
+#     def penalties(self) -> Tuple[np.ndarray, np.ndarray]:
+#         # get the explicit constraint penalties
+#         Pl, Pq = super(MIPBinaryModel, self).penalties
+#         if self.binary_only_variables is not None:
+#             # add penalties which enforce the selection of 0 or 1 for each binar variable
+# for idx in self.binaries:
+#                 # add the values x(x-1)^2 -> x^3-2x^2+x
+#                 indices = [[idx+1, idx+1, idx+1], [0, idx+1, idx+1], [0, 0, idx+1]]
+#                 coefficients = [1, -2, 1]
+#         
+#         return Pl, Pq

eqc_models-0.9.8.data/platlib/eqc_models/base/operators.py

@@ -0,0 +1,201 @@
+"""
+QUBO and Polynomial operators are used in EQC Models to pass the appropriate 
+format to the solver. All models must output one or both of QUBO or Polynomial
+types. Each Solver checks for the appropriate type. If a model does not provide
+the type, then it must raise OperatorNotAvailableError.
+
+>>> Q = np.array([[1, 2], [0, 1]])
+>>> qubo = QUBO(Q)
+>>> (qubo.Q == np.array([[1, 1], [1, 1]])).all()
+True
+>>> coefficients = [1, 1, 2]
+>>> indices = [(1, 1), (2, 2), (1, 2)]
+>>> poly = Polynomial(coefficients, indices)
+>>> indices = [(1, 1), (2, 2), (2, 1)]
+>>> poly = Polynomial(coefficients, indices)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in <module>
+ValueError: Input data to polynomial is not correct: index order must be monotonic
+>>> s = np.array([1, 1])
+>>> (poly.evaluate(s)==qubo.evaluate(s)).all()
+True
+"""
+from typing import List
+from dataclasses import dataclass
+import numpy as np
+# polyeval module is a Cython module useful for speeding up computation 
+# of an operator's value at a solution. If the Cython module is not 
+# available, the poly_eval variable will be set to None, triggering the
+# use of a pure Python method for evaluation
+try:
+    from .polyeval import poly_eval
+except ImportError:
+    poly_eval = None
+
+class OperatorNotAvailableError(Exception):
+    """ General error to raise when an operator type is not implemented """
+
+@dataclass
+class QUBO:
+    """ 
+    Contains a QUBO in a symmetric matrix
+    
+    If the matrix Q is not symmetric already, it will be after __post_init__
+
+    Parameters
+    ----------
+
+    qubo : np.array 
+        2d symmetric matrix of values which describe a quadratic unconstrained
+        binary optimization problem.
+    
+    """
+    Q: np.ndarray
+
+    def __post_init__(self):
+        Q2 = (self.Q + self.Q.T) / 2
+        self.Q = Q2
+
+    def evaluate(self, solution : np.ndarray):
+        return solution.T@self.Q@solution
+
+@dataclass
+class Polynomial:
+    """
+    Represents an operator and evalute the operator at a point or set of points.
+    The operator must be a polynomial, possibly multivariate, with powers of up
+    to 5, at the time of this version. The representation of a polynomial uses
+    a sparse method with two components per term. A term is described by the 
+    coefficient and a tuple of integers which indicate the variable indexes of
+    the term. The coefficients can be any value which fits in 32-bit floating
+    point representation, but the dynamic range of the coefficients should be 
+    within the limit of the hardware's sensitivity for best results. The term
+    index tuple length must be consistent across all terms. If a term does not
+    have a variable index for all positions, such as with a term which is the
+    square of a variable when other terms have third-order powers, then there
+    must be a placeholder of 0 for the unused power. The variable indexes must
+    be in the tuple in ascending order. Here are some examples (suppose the max
+    degree is 4):
+
+    - :math:`x_1^2`: :code:`(0, 0, 1, 1)`
+    - :math:`x_1 x_2 x_3`: :code:`(0, 1, 2, 3)`
+    - :math:`x_2^2 x_3^2`: :code:`(2, 2, 3, 3)`
+    
+    while it does not affect the optimiztion, a constant term can be applied to
+    the polynomial by using an index of all zeros :code:`(0, 0, 0, 0)`. When 
+    listing the coefficients, the position in the array must correspond to the
+    position in the array of indexes. Also, the indices must be ordered with
+    linear terms first, quadratic terms next and so forth. A polynomial operator
+    does not have an explicit domain. It could be evaluated on an array of any
+    real numbers.
+
+    Parameters
+    ----------
+
+    coefficients : List, np.array
+        Floating point values for the coefficients of a polynomial. Must
+        correspond to the entries in the indices array.
+    indices : List, np.array
+        List of tuples or 2d np.array with integer values describing the term
+        which the corresponding coefficient value is used for.
+
+    Examples
+    -------- 
+
+    >>> coefficients = [-1, -1, 2]
+    >>> indices = [(0, 1), (0, 2), (1, 2)]
+    >>> polynomial = Polynomial(coefficients, indices)
+    >>> test_solution = np.array([1, 1])
+    >>> polynomial.evaluate(test_solution)
+    [0]
+    >>> test_solution = np.array([1, 0])
+    >>> polynomial.evaluate(test_solution)
+    [-1]
+    >>> test_solution = np.array([5, -1])
+    >>> polynomial.evaluate(test_solution)
+    [-14]
+    >>> test_solution = np.array([2.5, -2.5])
+    >>> polynomial.evaluate(test_solution)
+    [-12.5]
+
+    """
+    coefficients : List
+    indices : List
+
+    def __post_init__(self):
+        issues = set()
+        degree_count = None
+        if len(self.coefficients)!=len(self.indices):
+            issues.add("coefficients and indices must be the same length")
+        # ensure indices are not numpy
+        self.indices = [[int(val) for val in index] for index in self.indices]
+        for i in range(len(self.coefficients)):
+            if degree_count is None:
+                degree_count = len(self.indices[i])
+            elif len(self.indices[i])!=degree_count:
+                issues.add("term rank is not consistent")
+            for j in range(1, degree_count):
+                if self.indices[i][j] < self.indices[i][j-1]:
+                    issues.add("index order must be monotonic")
+            try:
+                coeff = float(self.coefficients[i])
+            except TypeError:
+                issues.add("coefficient data types must be coercible to float type")
+            except ValueError:
+                issues.add("coefficient values must be coercible to float values")
+        if len(issues) > 0:
+            msg = "Input data to polynomial is not correct: "
+            msg += "; ".join([issue for issue in issues])
+            raise ValueError(msg)
+    
+    def pure_evaluate(self, solution : np.ndarray) -> np.ndarray:
+        """ 
+        Evaluation in pure python 
+
+        Parameters
+        ----------
+
+        solution : np.array
+            Solution to evaluate, is optionally 2-d, which results in multiple evaluations
+
+        Returns
+        -------
+
+        np.array
+
+        """
+
+        if len(solution.shape) == 1:
+            solution = solution.reshape((1, solution.shape[0]))
+        objective = [0 for k in range(solution.shape[0])]
+        for k in range(solution.shape[0]):
+            for i in range(len(self.coefficients)):
+                term = self.coefficients[i]
+                for j in self.indices[i]:
+                    if j > 0:
+                        term *= solution[k, j-1]
+                objective[k] += term
+        return objective
+    
+    def evaluate(self, solution: np.ndarray):
+        """
+        Evaluate the polynomial at the solution point. If the Cython module is available,
+        use that for speedup, otherwise evaluate with Python loops.
+
+        Parameters
+        ----------
+
+        solution : np.array
+            Solution to evaluate. Is optinoally 2-d, which results in multiple exaluations.
+
+        Returns 
+        -------
+
+        1-d array of values which match the coerced dtype of the inputs.
+
+        """
+        if poly_eval is None:
+            return self.pure_evaluate(solution)
+        else:
+            return poly_eval(np.array(self.coefficients, dtype=np.float64), 
+                             np.array(self.indices, dtype=np.int64), solution)