QuadraticProgram#

class QuadraticProgram(name='')[source]#

Bases: object

Quadratically Constrained Quadratic Program representation.

This representation supports inequality and equality constraints, as well as continuous, binary, and integer variables.

Parameters:

name (str) – The name of the quadratic program.

Attributes

linear_constraints#

Returns the list of linear constraints of the quadratic program.

Returns:

List of linear constraints.

linear_constraints_index#

Returns the dictionary that maps the name of a linear constraint to its index.

Returns:

The linear constraint index dictionary.

name#

Returns the name of the quadratic program.

Returns:

The name of the quadratic program.

objective#

Returns the quadratic objective.

Returns:

The quadratic objective.

quadratic_constraints#

Returns the list of quadratic constraints of the quadratic program.

Returns:

List of quadratic constraints.

quadratic_constraints_index#

Returns the dictionary that maps the name of a quadratic constraint to its index.

Returns:

The quadratic constraint index dictionary.

status#

Status of the quadratic program. It can be infeasible due to variable substitution.

Returns:

The status of the quadratic program

variables#

Returns the list of variables of the quadratic program.

Returns:

List of variables.

variables_index#

Returns the dictionary that maps the name of a variable to its index.

Returns:

The variable index dictionary.

Methods

binary_var(name=None)[source]#

Adds a binary variable to the quadratic program.

Parameters:

name (str | None) – The name of the variable. If it’s None or empty "", the default name, e.g., x0, is used.

Returns:

The added variable.

Raises:

QiskitOptimizationError – if the variable name is already occupied.

Return type:

Variable

binary_var_dict(keys, name=None, key_format='{}')[source]#

Uses ‘var_dict’ to construct a dictionary of binary variables

Parameters:

  • name (str | None) – The name(s) of the variable(s). If it’s None or empty "", the default name, e.g., x0, is used.

  • key_format (str) – The format used to name/index the variable(s).

  • keys (int | Sequence) – If keys: int, it is interpreted as the number of variables to construct. Otherwise, the elements of the sequence are converted to strings via ‘str’ and substituted into key_format.

Returns:

A dictionary mapping the variable names to variable instances.

Raises:
Return type:

Dict[str, Variable]

binary_var_list(keys, name=None, key_format='{}')[source]#

Uses ‘var_list’ to construct a list of binary variables

Parameters:

  • name (str | None) – The name(s) of the variable(s). If it’s None or empty "", the default name, e.g., x0, is used.

  • key_format (str) – The format used to name/index the variable(s).

  • keys (int | Sequence) – If keys: int, it is interpreted as the number of variables to construct. Otherwise, the elements of the sequence are converted to strings via ‘str’ and substituted into key_format.

Returns:

A list of variable instances.

Raises:
Return type:

List[Variable]

clear()[source]#

Clears the quadratic program, i.e., deletes all variables, constraints, the objective function as well as the name.

continuous_var(lowerbound=0, upperbound=1e+20, name=None)[source]#

Adds a continuous variable to the quadratic program.

Parameters:

  • lowerbound (float | int) – The lowerbound of the variable.

  • upperbound (float | int) – The upperbound of the variable.

  • name (str | None) – The name of the variable. If it’s None or empty "", the default name, e.g., x0, is used.

Returns:

The added variable.

Raises:

QiskitOptimizationError – if the variable name is already occupied.

Return type:

Variable

continuous_var_dict(keys, lowerbound=0, upperbound=1e+20, name=None, key_format='{}')[source]#

Uses ‘var_dict’ to construct a dictionary of continuous variables

Parameters:

  • lowerbound (float | int) – The lower bound of the variable(s).

  • upperbound (float | int) – The upper bound of the variable(s).

  • name (str | None) – The name(s) of the variable(s). If it’s None or empty "", the default name, e.g., x0, is used.

  • key_format (str) – The format used to name/index the variable(s).

  • keys (int | Sequence) – If keys: int, it is interpreted as the number of variables to construct. Otherwise, the elements of the sequence are converted to strings via ‘str’ and substituted into key_format.

Returns:

A dictionary mapping the variable names to variable instances.

Raises:
Return type:

Dict[str, Variable]

continuous_var_list(keys, lowerbound=0, upperbound=1e+20, name=None, key_format='{}')[source]#

Uses ‘var_list’ to construct a list of continuous variables

Parameters:

  • lowerbound (float | int) – The lower bound of the variable(s).

  • upperbound (float | int) – The upper bound of the variable(s).

  • name (str | None) – The name(s) of the variable(s). If it’s None or empty "", the default name, e.g., x0, is used.

  • key_format (str) – The format used to name/index the variable(s).

  • keys (int | Sequence) – If keys: int, it is interpreted as the number of variables to construct. Otherwise, the elements of the sequence are converted to strings via ‘str’ and substituted into key_format.

Returns:

A list of variable instances.

Raises:
Return type:

List[Variable]

export_as_lp_string()[source]#

Returns the quadratic program as a string of LP format.

Returns:

A string representing the quadratic program.

Return type:

str

from_ising(qubit_op, offset=0.0, linear=False)[source]#

Create a quadratic program from a qubit operator and a shift value.

Variables are mapped to qubits in the same order, i.e., i-th variable is mapped to i-th qubit. See https://github.com/Qiskit/qiskit-terra/issues/1148 for details.

Parameters:

  • qubit_op (BaseOperator) – The qubit operator of the problem.

  • offset (float) – The constant value in the Ising Hamiltonian.

  • linear (bool) – If linear is True, \(x^2\) is treated as a linear term since \(x^2 = x\) for \(x \in \{0,1\}\). Else, \(x^2\) is treated as a quadratic term. The default value is False.

Raises:
get_feasibility_info(x)[source]#

Returns whether a solution is feasible or not along with the violations. :param x: a solution value, such as returned in an optimizer result.

Returns:

Whether the solution provided is feasible or not. List[Variable]: List of variables which are violated. List[Constraint]: List of constraints which are violated.

Return type:

feasible

Raises:

QiskitOptimizationError – If the input x is not same len as total vars

get_linear_constraint(i)[source]#

Returns a linear constraint for a given name or index.

Parameters:

i (int | str) – the index or name of the constraint.

Returns:

The corresponding constraint.

Raises:

  • IndexError – if the index is out of the list size

  • KeyError – if the name does not exist

Return type:

LinearConstraint

get_num_binary_vars()[source]#

Returns the total number of binary variables.

Returns:

The total number of binary variables.

Return type:

int

get_num_continuous_vars()[source]#

Returns the total number of continuous variables.

Returns:

The total number of continuous variables.

Return type:

int

get_num_integer_vars()[source]#

Returns the total number of integer variables.

Returns:

The total number of integer variables.

Return type:

int

get_num_linear_constraints()[source]#

Returns the number of linear constraints.

Returns:

The number of linear constraints.

Return type:

int

get_num_quadratic_constraints()[source]#

Returns the number of quadratic constraints.

Returns:

The number of quadratic constraints.

Return type:

int

get_num_vars(vartype=None)[source]#

Returns the total number of variables or the number of variables of the specified type.

Parameters:

vartype (VarType | None) – The type to be filtered on. All variables are counted if None.

Returns:

The total number of variables.

Return type:

int

get_quadratic_constraint(i)[source]#

Returns a quadratic constraint for a given name or index.

Parameters:

i (int | str) – the index or name of the constraint.

Returns:

The corresponding constraint.

Raises:

  • IndexError – if the index is out of the list size

  • KeyError – if the name does not exist

Return type:

QuadraticConstraint

get_variable(i)[source]#

Returns a variable for a given name or index.

Parameters:

i (int | str) – the index or name of the variable.

Returns:

The corresponding variable.

Return type:

Variable

integer_var(lowerbound=0, upperbound=1e+20, name=None)[source]#

Adds an integer variable to the quadratic program.

Parameters:

  • lowerbound (float | int) – The lowerbound of the variable.

  • upperbound (float | int) – The upperbound of the variable.

  • name (str | None) – The name of the variable. If it’s None or empty "", the default name, e.g., x0, is used.

Returns:

The added variable.

Raises:

QiskitOptimizationError – if the variable name is already occupied.

Return type:

Variable

integer_var_dict(keys, lowerbound=0, upperbound=1e+20, name=None, key_format='{}')[source]#

Uses ‘var_dict’ to construct a dictionary of integer variables

Parameters:

  • lowerbound (float | int) – The lower bound of the variable(s).

  • upperbound (float | int) – The upper bound of the variable(s).

  • name (str | None) – The name(s) of the variable(s). If it’s None or empty "", the default name, e.g., x0, is used.

  • key_format (str) – The format used to name/index the variable(s).

  • keys (int | Sequence) – If keys: int, it is interpreted as the number of variables to construct. Otherwise, the elements of the sequence are converted to strings via ‘str’ and substituted into key_format.

Returns:

A dictionary mapping the variable names to variable instances.

Raises:
Return type:

Dict[str, Variable]

integer_var_list(keys, lowerbound=0, upperbound=1e+20, name=None, key_format='{}')[source]#

Uses ‘var_list’ to construct a list of integer variables

Parameters:

  • lowerbound (float | int) – The lower bound of the variable(s).

  • upperbound (float | int) – The upper bound of the variable(s).

  • name (str | None) – The name(s) of the variable(s). If it’s None or empty "", the default name, e.g., x0, is used.

  • key_format (str) – The format used to name/index the variable(s).

  • keys (int | Sequence) – If keys: int, it is interpreted as the number of variables to construct. Otherwise, the elements of the sequence are converted to strings via ‘str’ and substituted into key_format.

Returns:

A list of variable instances.

Raises:
Return type:

List[Variable]

is_feasible(x)[source]#

Returns whether a solution is feasible or not.

Parameters:

x (List[float] | ndarray) – a solution value, such as returned in an optimizer result.

Returns:

True if the solution provided is feasible otherwise False.

Return type:

bool

linear_constraint(linear=None, sense='<=', rhs=0.0, name=None)[source]#
Adds a linear equality constraint to the quadratic program of the form:

(linear * x) sense rhs.

Parameters:

  • linear (ndarray | spmatrix | List[float] | Dict[int | str, float] | None) – The linear coefficients of the left-hand side of the constraint.

  • sense (str | ConstraintSense) –

    The sense of the constraint,

    • ==, =, E, and EQ denote ‘equal to’.

    • >=, >, G, and GE denote ‘greater-than-or-equal-to’.

    • <=, <, L, and LE denote ‘less-than-or-equal-to’.

  • rhs (float) – The right-hand side of the constraint.

  • name (str | None) – The name of the constraint. If it’s None or empty "", the default name, e.g., c0, is used.

Returns:

The added constraint.

Raises:

QiskitOptimizationError – if the constraint name already exists or the sense is not valid.

Return type:

LinearConstraint

maximize(constant=0.0, linear=None, quadratic=None)[source]#

Sets a quadratic objective to be maximized.

Parameters:
Returns:

The created quadratic objective.

Return type:

None

minimize(constant=0.0, linear=None, quadratic=None)[source]#

Sets a quadratic objective to be minimized.

Parameters:
Returns:

The created quadratic objective.

Return type:

None

prettyprint(wrap=80)[source]#

Returns a pretty printed string of this problem.

Parameters:

wrap (int) – The text width to wrap the output strings. It is disabled by setting 0. Note that some strings might exceed this value, for example, a long variable name won’t be wrapped. The default value is 80.

Returns:

A pretty printed string representing the problem.

Raises:

QiskitOptimizationError – if there is a non-printable name.

Return type:

str

quadratic_constraint(linear=None, quadratic=None, sense='<=', rhs=0.0, name=None)[source]#
Adds a quadratic equality constraint to the quadratic program of the form:

(x * quadratic * x + linear * x) sense rhs.

Parameters:

  • linear (ndarray | spmatrix | List[float] | Dict[int | str, float] | None) – The linear coefficients of the constraint.

  • quadratic (ndarray | spmatrix | List[List[float]] | Dict[Tuple[int | str, int | str], float] | None) – The quadratic coefficients of the constraint.

  • sense (str | ConstraintSense) –

    The sense of the constraint,

    • ==, =, E, and EQ denote ‘equal to’.

    • >=, >, G, and GE denote ‘greater-than-or-equal-to’.

    • <=, <, L, and LE denote ‘less-than-or-equal-to’.

  • rhs (float) – The right-hand side of the constraint.

  • name (str | None) – The name of the constraint. If it’s None or empty "", the default name, e.g., q0, is used.

Returns:

The added constraint.

Raises:

QiskitOptimizationError – if the constraint name already exists.

Return type:

QuadraticConstraint

read_from_lp_file(filename)[source]#

Loads the quadratic program from a LP file.

Parameters:

filename (str) – The filename of the file to be loaded.

Raises:

FileNotFoundError – If the file does not exist.

Note

This method requires CPLEX to be installed and present in PYTHONPATH.

remove_linear_constraint(i)[source]#

Remove a linear constraint

Parameters:

i (str | int) – an index or a name of a linear constraint

Raises:
remove_quadratic_constraint(i)[source]#

Remove a quadratic constraint

Parameters:

i (str | int) – an index or a name of a quadratic constraint

Raises:
substitute_variables(constants=None, variables=None)[source]#

Substitutes variables with constants or other variables.

Parameters:

  • constants (Dict[int | str, float] | None) – replace variable by constant e.g., {'x': 2} means x is substituted with 2

  • variables (Dict[str | int, Tuple[str | int, float]] | None) – replace variables by weighted other variable need to copy everything using name reference to make sure that indices are matched correctly. The lower and upper bounds are updated accordingly. e.g., {'x': ('y', 2)} means x is substituted with y * 2

Returns:

An optimization problem by substituting variables with constants or other variables. If the substitution is valid, QuadraticProgram.status is still QuadraticProgram.Status.VALID. Otherwise, it gets QuadraticProgram.Status.INFEASIBLE.

Raises:

QiskitOptimizationError – if the substitution is invalid as follows. - Same variable is substituted multiple times. - Coefficient of variable substitution is zero.

Return type:

QuadraticProgram

to_ising()[source]#

Return the Ising Hamiltonian of this problem.

Variables are mapped to qubits in the same order, i.e., i-th variable is mapped to i-th qubit. See https://github.com/Qiskit/qiskit-terra/issues/1148 for details.

Returns:

The qubit operator for the problem offset: The constant value in the Ising Hamiltonian.

Return type:

qubit_op

Raises:
write_to_lp_file(filename)[source]#

Writes the quadratic program to an LP file.

Parameters:

filename (str) – The filename of the file the model is written to. If filename is a directory, file name ‘my_problem.lp’ is appended. If filename does not end with ‘.lp’, suffix ‘.lp’ is appended.

Raises:

  • OSError – If this cannot open a file.

  • DOcplexException – If filename is an empty string