Model
Root object to define a problem to be optimized
- titanq.Model.add_cardinality_constraint(self, constraint_mask: ndarray, cardinality: int)
Adds cardinality constraint vector to the model.
Parameters
- constraint_mask
A NumPy 1-D dense ndarray (must be binary). The constraint_mask vector of shape (N,) where N is the number of variables.
- cardinality
The constraint_rhs cardinality. This value has to be a non-zero unsigned integer.
Raises
- MissingVariableError
If no variable have been added to the model.
- MaximumConstraintLimitError
If the number of constraints exceed the limit.
- ConstraintSizeError
If the constraint_mask shape or the constraint_rhs shape does not fit the expected shape of this model.
- ValueError
If the constraint_mask is not in binary or the cardinality is not an unsigned integer.
Examples
>>> constraint_mask = np.array([1, 1, 1, 0, 1]) >>> cardinality = 3 >>> model.add_cardinality_constraint(constraint_mask, cardinality)
- titanq.Model.add_cardinality_constraints_matrix(self, constraint_mask: ndarray, cardinalities: ndarray)
Adds cardinality constraints in matrix format to the model.
Parameters
- constraint_mask
A NumPy 2-D dense ndarray (must be binary). The constraint_mask matrix of shape (M, N) where M the number of constraints and N is the number of variables.
- cardinalities
A NumPy 1-D ndarray (must be non-zero unsigned integer). The constraint_rhs vector of shape (M,) where M is the number of constraints.
Raises
- MissingVariableError
If no variable have been added to the model.
- MaximumConstraintLimitError
The number of constraint exceed the limit.
- ConstraintSizeError
If the constraint_mask shape or the constraint_rhs shape does not fit the expected shape of this model.
- ValueError
If the constraint_mask is not binary or cardinalities data type are not unsigned integers.
Examples
>>> constraint_mask = np.array([[1, 1, 1, 0, 1], [1, 1, 1, 1, 0]]) >>> cardinalities = np.array([3, 2]) >>> model.add_cardinality_constraints_matrix(constraint_mask, cardinalities)
- titanq.Model.add_equality_constraint(self, constraint_mask: ndarray, limit: float32) None
Adds an equality constraint vector to the model.
Parameters
- constraint_mask
A NumPy 1-D dense ndarray (float32). The constraint_mask vector of shape (N,) where N is the number of variables.
- limit
Limit value to the constraint mask.
Raises
- MissingVariableError
If no variable have been added to the model.
- MaximumConstraintLimitError
The number of constraint exceed the limit.
- ValueError
If the constraint_mask shape does not fit the expected shape of this model. If the constraint_mask or limit contains irregular format (‘NaN’ or ‘inf’).
Examples
>>> constraint_mask = np.array([1.05, -1.1], dtype=np.float32) >>> limit = -3.45 >>> model.add_equality_constraint(constraint_mask, limit)
- titanq.Model.add_equality_constraints_matrix(self, constraint_mask: ndarray, limit: ndarray) None
Adds an equality constraint matrix to the model.
Parameters
- constraint_mask
A NumPy 2-D dense ndarray (float32). The constraint_mask vector of shape (M, N) where M the number of constraints and N is the number of variables.
- limit
A NumPy 1-D array (float32). The limit vector of shape (M,) where M is the number of constraints.
Raises
- MissingVariableError
If no variable have been added to the model.
- MaximumConstraintLimitError
The number of constraint exceed the limit.
- ValueError
If the constraint_mask shape does not fit the expected shape of this model. If the constraint_mask or limit contains irregular format (‘NaN’ or ‘inf’).
Examples
>>> constraint_mask = np.array([[-3.51, 0, 0, 0], [10, 0, 0, 0]], dtype=np.float32) >>> limit = np.array([2, 10], dtype=np.float32) >>> model.add_equality_constraints_matrix(constraint_mask, limit)
- titanq.Model.add_inequality_constraint(self, constraint_mask: ndarray, constraint_bounds: ndarray)
Adds inequality constraint vector to the model. At least one bound must be set.
Parameters
- constraint_mask
A NumPy 1-D dense ndarray (float32). The constraint_mask vector of shape (N,) where N is the number of variables.
- constraint_bounds
A NumPy 1-D ndarray (float32). Vector of shape (2,)
Raises
- MissingVariableError
If no variable have been added to the model.
- MaximumConstraintLimitError
The number of constraint exceed the limit.
- ValueError
If the constraint_mask shape does not fit the expected shape of this model. If the constraint_mask contains irregular format (‘NaN’ or ‘inf’). If the lowerbound is equal or higher than the upperbound.
Examples
>>> constraint_mask = np.array([1.05, -1.1], dtype=np.float32) >>> constraint_bounds = np.array([1.0, np.nan], dtype=np.float32) >>> model.add_inequality_constraint(constraint_mask, constraint_bounds)
- titanq.Model.add_inequality_constraints_matrix(self, constraint_mask: ndarray, constraint_bounds: ndarray)
Adds inequality constraint matrix to the model.
Parameters
- constraint_mask
A NumPy 2-D dense ndarray (float32). The constraint_mask vector of shape (M, N) where N is the number of variables.
- constraint_bounds
A NumPy 2-D ndarray (float32). Vector of shape (M, 2) where M is the number of constraints.
Raises
- MissingVariableError
If no variable have been added to the model.
- MaximumConstraintLimitError
The number of constraint exceed the limit.
- ValueError
If the constraint_mask shape does not fit the expected shape of this model. If the constraint_mask contains irregular format (‘NaN’ or ‘inf’). If the lowerbound is equal or higher than its given upperbound.
Examples
>>> constraint_mask = np.array([[-3.51, 0], [10, 0]], dtype=np.float32) >>> constraint_bounds = np.array([[8, 9], [np.nan, 100_000]], dtype=np.float32) >>> model.add_inequality_constraints_matrix(constraint_mask, constraint_bounds)
- titanq.Model.add_set_partitioning_constraint(self, constraint_mask: ndarray)
Adds set partitioning constraint vector to the model.
Parameters
- constraint_mask
A NumPy 1-D dense ndarray (must be binary). The constraint_mask vector of shape (N,) where N is the number of variables.
Raises
- MissingVariableError
If no variable have been added to the model.
- MaximumConstraintLimitError
The number of constraint exceed the limit.
- ConstraintSizeError
If the constraint_mask shape does not fit the expected shape of this model.
- ValueError
If the constraint_mask data type is not binary.
Examples
>>> constraint_mask = np.array([1, 1, 1, 0, 1]) >>> model.add_set_partitioning_constraint(constraint_mask)
- titanq.Model.add_set_partitioning_constraints_matrix(self, constraint_mask: ndarray)
Adds set partitioning constraints in matrix format to the model.
Parameters
- constraint_mask
A NumPy 2-D dense ndarray (must be binary). The constraint_mask matrix of shape (M, N) where M the number of constraints and N is the number of variables.
Raises
- MissingVariableError
If no variable have been added to the model.
- MaximumConstraintLimitError
The number of constraints exceed the limit.
- ConstraintSizeError
If the constraint_mask shape does not fit the expected shape of this model.
- ValueError
If the constraint_mask data type is not binary.
Examples
>>> constraint_mask = np.array([[1, 1, 1, 0, 1], [1, 1, 1, 1, 0]]) >>> model.add_set_partitioning_constraints_matrix(constraint_mask)
- titanq.Model.add_variable_vector(self, name: str = '', size: int = 1, vtype: Vtype = Vtype.BINARY, variable_bounds: List[Tuple[int, int]] | List[Tuple[float, float]] = [])
Add a vector of variable to the model. Multiple variables vector can be added but with different names.
Notes
If Vtype is set to
Vtype.INTEGER
orVtype.CONTINUOUS
, variable_bounds need to be set.Parameters
- name
The name given to this variable vector.
- size
The size of the vector.
- vtype
Type of the variables inside the vector.
- variable_bounds
Lower and upper bounds for the variable vector. A list of tuples (can be either integers or continuous)
Raises
- MaximumVariableLimitError
If the total size of variables exceed the limit.
- ValueError
If the size of the vector is < 1
Examples
>>> from titanq import Model, Vtype >>> model.add_variable_vector('x', 3, Vtype.BINARY) >>> model.add_variable_vector('y', 3, Vtype.INTEGER, [[0, 5], [1, 6]]) >>> model.add_variable_vector('z', 3, Vtype.CONTINUOUS, [[2.3, 4.6], [3.1, 5.3], [1.1, 4]])
- titanq.Model.optimize(self, *, beta: List[float] = [0.1], coupling_mult: float = 0.5, timeout_in_secs: float = 10.0, num_chains: int = 8, num_engines: int = 1, normalized: bool = False) OptimizeResponse
Optimize this model.
Notes
All of the files used during this computation will be cleaned at the end. For more information on how to tunes those parameters, visit the API doc at TitanQ API.
Parameters
- beta
beta
hyper parameter used by the solver.- coupling_mult
coupling_mult
hyper parameter used by the solver.- timeout_in_secs
Maximum time (in seconds) the solver can take to solve this problem.
- num_chains
num_chains
hyper parameter used by the solver.- num_engines
num_engines
parameter used by the solver.- normalized
DEPRECATED since version 0.9.1.
normalized
should only be used when the model is only using binary or bipolar variables and does not contain any constraints.
Returns
- OptimizeResponse
Optimized response data object
Raises
- MissingVariableError
If no variable have been added to the model.
- MissingObjectiveError
If no objective matrices have been added to the model.
Examples
- basic solve
>>> response = model.optimize(timeout_in_secs=60)
- multiple engine
>>> response = model.optimize(timeout_in_secs=60, num_engines=2)
- custom values
>>> response = model.optimize(beta=[0.1], coupling_mult=0.75, num_chains=8)
- print values
>>> print("-" * 15, "+", "-" * 26, sep="") >>> print("Ising energy | Result vector") >>> print("-" * 15, "+", "-" * 26, sep="") >>> for ising_energy, result_vector in response.result_items(): >>> print(f"{ising_energy: <14f} | {result_vector}")
- titanq.Model.set_objective_matrices(self, weights: ndarray, bias: ndarray, target=Target.MINIMIZE)
Set the objective matrices for the model.
Parameters
- weights
The quadratic objective matrix, this matrix needs to be symmetrical. A NumPy 2-D dense ndarray (must be float32).
- bias
The linear constraint vector. A NumPy 1-D ndarray.
- target
The target of this objective matrix.
Raises
- MissingVariableError
If no variable have been added to the model.
- ObjectiveAlreadySetError
If an objective has already been set in this model.
- ValueError
If the weights shape or the bias shape does not fit the variables in the model. If the weights or bias data type is not float32.
Examples
>>> from titanq import Model, Target >>> edges = {0:[4,5,6,7], 1:[4,5,6,7], 2:[4,5,6,7], 3:[4,5,6,7], 4:[0,1,2,3], 5:[0,1,2,3], 6:[0,1,2,3], 7:[0,1,2,3]} >>> size = len(edges) >>> weights = np.zeros((size, size), dtype=np.float32) >>> for root, connections in edges.items(): >>> for c in connections: >>> weights[root][c] = 1 >>> # construct the bias vector (Uniform weighting across all nodes) >>> bias = np.asarray([0]*size, dtype=np.float32) >>> model.set_objective_matrices(weights, bias, Target.MINIMIZE)