qilisdk.core.model

Classes

SlackCounter	A singleton class to generate a slack counter id that increments continuously within the user's active session.
ObjectiveSense	An Enumeration of the Objective sense options.
Constraint	Represent a symbolic constraint inside a Model.
Objective	Represent the scalar objective function optimized by a Model.
Model	Aggregate an objective and constraints into an optimization problem.
QUBO	Specialized Model constrained to Quadratic Unconstrained Binary Optimization form.

Module Contents

class SlackCounter

A singleton class to generate a slack counter id that increments continuously within the user’s active session.

next() → int

Return the next counter value and increment the counter.

reset_counter() → None

class ObjectiveSense

Bases: str, enum.Enum

An Enumeration of the Objective sense options.

Initialize self. See help(type(self)) for accurate signature.

MINIMIZE = 'minimize'

MAXIMIZE = 'maximize'

classmethod to_yaml(representer: ruamel.yaml.representer.RoundTripRepresenter, node: ObjectiveSense) → ruamel.yaml.nodes.ScalarNode

Method to be called automatically during YAML serialization.

Returns:

The YAML scalar node representing the ObjectiveSense.

Return type:

ScalarNode

classmethod from_yaml(_, node: ruamel.yaml.nodes.ScalarNode) → ObjectiveSense

Method to be called automatically during YAML deserialization.

Returns:

The ObjectiveSense instance created from the YAML node value.

Return type:

ObjectiveSense

class Constraint(label: str, term: qilisdk.core.variables.ComparisonTerm)

Represent a symbolic constraint inside a Model.

Example

from qilisdk.core.model import Constraint
from qilisdk.core.variables import BinaryVariable, LEQ

x = BinaryVariable("x")
constraint = Constraint("limit", LEQ(x, 1))

Build a constraint defined by a comparison term such as x + y <= 2.

Parameters:

• label (str) – The constraint’s label.

• term (ComparisonTerm) – The comparison term that defines the constraint.

Raises:

ValueError – if the term provided is not a ConstraintTerm.

property label: str

Returns: str: The label of the constraint object.

property term: qilisdk.core.variables.ComparisonTerm

Returns: ComparisonTerm: The comparison term of the constraint object.

variables() → list[qilisdk.core.variables.BaseVariable]

Returns the list of variables in the constraint term.

Return type:

list[BaseVariable]

Returns:

the list of variables in the constraint term.

Return type:

list[BaseVariable]

property lhs: qilisdk.core.variables.Term

Returns: Term: The left hand side of the constraint term.

property rhs: qilisdk.core.variables.Term

Returns: Term: The right hand side of the constraint term.

property degree: int

Returns: int: The degree of the constraint term.

class Objective(label: str, term: qilisdk.core.variables.BaseVariable | qilisdk.core.variables.Term, sense: ObjectiveSense = ObjectiveSense.MINIMIZE)

Represent the scalar objective function optimized by a Model.

Example

from qilisdk.core.model import Objective, ObjectiveSense
from qilisdk.core.variables import BinaryVariable

x = BinaryVariable("x")
obj = Objective("profit", 3 * x, sense=ObjectiveSense.MAXIMIZE)

Build a new objective function.

Parameters:

• label (str) – Objective label.

• term (BaseVariable | Term) – Expression to minimize or maximize.

• sense (ObjectiveSense, optional) – Optimization sense. Defaults to ObjectiveSense.MINIMIZE.

Raises:

• ValueError – if the term provided is not a Term Object.

• ValueError – if the optimization sense provided is not one that is defined by the ObjectiveSense Enum.

property label: str

Returns: str: the label of the objective.

property term: qilisdk.core.variables.Term

Returns: Term: the objective term.

property sense: ObjectiveSense

Returns: ObjectiveSense: the objective optimization sense.

variables() → list[qilisdk.core.variables.BaseVariable]

Gathers a list of all the variables in the objective term.

Returns:

the list of variables in the objective term.

Return type:

list[BaseVariable]

class Model(label: str)

Aggregate an objective and constraints into an optimization problem.

Example

from qilisdk.core import BinaryVariable, LEQ, Model

num_items = 4
values = [1, 3, 5, 2]
weights = [3, 2, 4, 5]
max_weight = 6
bin_vars = [BinaryVariable(f"b{i}") for i in range(num_items)]
model = Model("Knapsack")
objective = sum(values[i] * bin_vars[i] for i in range(num_items))
model.set_objective(objective)
constraint = LEQ(sum(weights[i] * bin_vars[i] for i in range(num_items)), max_weight)
model.add_constraint("maximum weight", constraint)

print(model)

Parameters:

label (str) – Model label.

property lagrange_multipliers: dict[str, float]

set_lagrange_multiplier(constraint_label: str, lagrange_multiplier: float) → None

Sets the lagrange multiplier value for a given constraint.

Parameters:

• constraint_label (str) – the constraint to which the lagrange multiplier value corresponds.

• lagrange_multiplier (float) – the lagrange multiplier value.

Raises:

ValueError – if the constraint provided is not in the model.

property label: str

Returns: str: The model label.

property constraints: list[Constraint]

Returns: list[Constraint]: a list of all the constraints in the model.

property encoding_constraints: list[Constraint]

Returns: list[Constraint]: a list of all variable encoding constraints in the model.

property objective: Objective

Returns: Objective: The objective of the model.

variables() → list[qilisdk.core.variables.BaseVariable]

Returns:

a list of variables that are used in the model whether that is in the constraints or the objective.

Return type:

list[BaseVariable]

add_constraint(label: str, term: qilisdk.core.variables.ComparisonTerm, lagrange_multiplier: float = 100) → None

Add a constraint to the model.

Parameters:

• label (str) – constraint label.

• term (ComparisonTerm) – The constraint’s comparison term.

Raises:

ValueError – if the constraint label is already used in the model.

set_objective(term: qilisdk.core.variables.Term, label: str = 'obj', sense: ObjectiveSense = ObjectiveSense.MINIMIZE) → None

Sets the model’s objective.

Parameters:

• term (Term) – the objective term.

• label (str, optional) – the objective’s label. Defaults to “obj”.

• sense (ObjectiveSense, optional) – The optimization sense of the model’s objective. Defaults to ObjectiveSense.MINIMIZE.

evaluate(sample: Mapping[qilisdk.core.variables.BaseVariable, qilisdk.core.variables.RealNumber | list[int]]) → dict[str, qilisdk.core.variables.Number]

Evaluates the objective and the constraints of the model given a set of values for the variables.

Parameters:

sample (Mapping[BaseVariable, Number  |  list[int]]) – The dictionary maps the variable to the value to be used during the evaluation. In case the variable is continuous (Not Binary or Spin) then the value could either be a number or a list of binary bits that correspond to the encoding of the variable. Note: All the model’s variables must be provided for the model to be evaluated.

Returns:

a dictionary that maps the name of the objective/constraint to it’s evaluated value.

Note: For constraints, the value is equal to lagrange multiplier of that constraint if the constraint is not satisfied or 0 otherwise.

Return type:

dict[str, float]

to_qubo(lagrange_multiplier_dict: dict[str, float] | None = None, penalization: Literal['unbalanced', 'slack'] = 'slack', parameters: list[float] | None = None) → QUBO

Export the model to a qubo model. :param lagrange_multiplier_dict: A dictionary with lagrange multiplier values to scale the model’s constraints. Defaults to None. :type lagrange_multiplier_dict: dict[str, float] | None, optional :param penalization: the penalization used to handel inequality constraints. Defaults to “slack”. :type penalization: Literal["unbalanced", "slack"], optional :param parameters: the parameters used for the unbalanced penalization method. Defaults to None. :type parameters: list[float] | None, optional

Note

this exportation only works if the model doesn’t violate the QUBO format. Automatic constraint and objective linearization will be added in the future.

Returns:

A QUBO model that is generate from the model object.

Return type:

QUBO

class QUBO(label: str)

Bases: Model

Specialized Model constrained to Quadratic Unconstrained Binary Optimization form.

Example

from qilisdk.core.model import QUBO
from qilisdk.core.variables import BinaryVariable

x0, x1 = BinaryVariable("x0"), BinaryVariable("x1")
qubo = QUBO("Example")
qubo.set_objective((x0 + x1) ** 2)

Parameters:

label (str) – QUBO model label.

property qubo_objective: Objective | None

Returns: Objective | None: The QUBO objective (factoring in the constraints and objective of the model). If the objective and constraints are not defined in the model, this property returns None.

add_constraint(label: str, term: qilisdk.core.variables.ComparisonTerm, lagrange_multiplier: float = 100, penalization: Literal['unbalanced', 'slack'] = 'slack', parameters: list[float] | None = None, transform_to_qubo: bool = True) → None

Adds a constraint to the QUBO model.

Parameters:

• label (str) – the constraint label.

• term (ComparisonTerm) – the constraint’s comparison term.

• lagrange_multiplier (float, optional) – the lagrange multiplier used to scale this constraint. Defaults to 100.

• penalization (Literal["unbalanced", "slack"], optional) – the penalization used to handel inequality constraints. Defaults to “slack”.

• parameters (list[float] | None, optional) – the parameters used for the unbalanced penalization method. Defaults to None.

• transform_to_qubo (bool, optional) – Automatically transform a given constraint to QUBO format. Defaults to True.

Raises:

• ValueError – if constraint label already exists in the model.

• ValueError – if a penalization method is provided that is not ("unbalanced", "slack")

• ValueError – if unbalanced penalization method is used and not enough parameters are provided.

• ValueError – if the degree of the provided term is larger than 2.

• ValueError – if the constraint term contains variables that are not from Positive Integers or Binary domains.

• ValueError – if the constraint term contains variable that do not have 0 as their lower bound.

set_objective(term: qilisdk.core.variables.Term, label: str = 'obj', sense: ObjectiveSense = ObjectiveSense.MINIMIZE) → None

Set the QUBO objective.

Parameters:

• term (Term) – The objective’s term.

• label (str, optional) – the objective’s label. Defaults to “obj”.

• sense (ObjectiveSense, optional) – The optimization sense of the model’s objective. Defaults to ObjectiveSense.MINIMIZE.

evaluate(sample: Mapping[qilisdk.core.variables.BaseVariable, qilisdk.core.variables.RealNumber | list[int]]) → dict[str, qilisdk.core.variables.Number]

Evaluates the objective and the constraints of the model given a set of values for the variables.

Parameters:

sample (Mapping[BaseVariable, RealNumber  |  list[int]]) – The dictionary maps the variable to the value to be used during the evaluation. In case the variable is continuous (Not Binary or Spin) then the value could either be a number or a list of binary bits that correspond to the encoding of the variable. Note: All the model’s variables must be provided for the model to be evaluated.

Returns:

a dictionary that maps the name of the objective/constraint to it’s evaluated value.

Note: For constraints, the value is equal to the value of the evaluated constraint term multiplied by the lagrange multiplier of that constraint.

Return type:

dict[str, float]

classmethod from_model(model: Model, lagrange_multiplier_dict: dict[str, float] | None = None, penalization: Literal['unbalanced', 'slack'] = 'slack', parameters: list[float] | None = None) → QUBO

A class method that constructs a QUBO model from a regular model if possible.

Parameters:

• model (Model) – the model to be used to construct the QUBO model.

• lagrange_multiplier_dict (dict[str, float] | None, optional) – A dictionary with lagrange multiplier values to scale the model’s constraints. Defaults to None.

• penalization (Literal["unbalanced", "slack"], optional) – the penalization used to handel inequality constraints. Defaults to “slack”.

• parameters (list[float] | None, optional) – the parameters used for the unbalanced penalization method. Defaults to None.

Returns:

_description_

Return type:

QUBO

to_hamiltonian() → qilisdk.analog.hamiltonian.Hamiltonian

Construct an ising hamiltonian from the current QUBO model.

Raises:

• ValueError – if the QUBO model is empty (doesn’t have an objective nor constraints.)

• ValueError – if the QUBO model uses operations that are not addition or multiplications.

Returns:

An ising hamiltonian that represents the QUBO model.

Return type:

Hamiltonian

to_qubo(lagrange_multiplier_dict: dict[str, float] | None = None, penalization: Literal['unbalanced', 'slack'] = 'slack', parameters: list[float] | None = None) → QUBO

Export the model to a qubo model. :param lagrange_multiplier_dict: A dictionary with lagrange multiplier values to scale the model’s constraints. Defaults to None. :type lagrange_multiplier_dict: dict[str, float] | None, optional :param penalization: the penalization used to handel inequality constraints. Defaults to “slack”. :type penalization: Literal["unbalanced", "slack"], optional :param parameters: the parameters used for the unbalanced penalization method. Defaults to None. :type parameters: list[float] | None, optional

Note

this exportation only works if the model doesn’t violate the QUBO format. Automatic constraint and objective linearization will be added in the future.

Returns:

A QUBO model that is generate from the model object.

Return type:

QUBO