QuadraticProgram

QuadraticProgram.binary_var(name=None)

Adds a binary variable to the quadratic program.

Parameters

name (Optional[str]) – The name of the variable.

Return type

Variable

Returns

The added variable.

Raises

QiskitOptimizationError – if the variable name is already occupied.

QuadraticProgram.binary_var_dict(keys, name=None, key_format='{}')

Uses ‘var_dict’ to construct a dictionary of binary variables

Parameters

• name (Optional[str]) – The name(s) of the variable(s).
• key_format (str) – The format used to name/index the variable(s).
• keys (Union[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.

Return type

Dict[str, Variable]

Returns

A dictionary mapping the variable names to variable instances.

Raises

• QiskitOptimizationError – if the variable name is already taken.
• QiskitOptimizationError – if less than one variable instantiation is attempted.
• QiskitOptimizationError – if key_format has more than one substitution or a nested substitution.

QuadraticProgram.binary_var_list(keys, name=None, key_format='{}')

Uses ‘var_list’ to construct a list of binary variables

Parameters

• name (Optional[str]) – The name(s) of the variable(s).
• key_format (str) – The format used to name/index the variable(s).
• keys (Union[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.

Return type

List[Variable]

Returns

A list of variable instances.

Raises

• QiskitOptimizationError – if the variable name is already taken.
• QiskitOptimizationError – if less than one variable instantiation is attempted.
• QiskitOptimizationError – if key_format has more than one substitution or a nested substitution.

QuadraticProgram.clear()

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

Return type

None

QuadraticProgram.continuous_var(lowerbound=0, upperbound=1e+20, name=None)

Adds a continuous variable to the quadratic program.

Parameters

• lowerbound (Union[float, int]) – The lowerbound of the variable.
• upperbound (Union[float, int]) – The upperbound of the variable.
• name (Optional[str]) – The name of the variable.

Return type

Variable

Returns

The added variable.

Raises

QiskitOptimizationError – if the variable name is already occupied.

QuadraticProgram.continuous_var_dict(keys, lowerbound=0, upperbound=1e+20, name=None, key_format='{}')

Uses ‘var_dict’ to construct a dictionary of continuous variables

Parameters

• lowerbound (Union[float, int]) – The lower bound of the variable(s).
• upperbound (Union[float, int]) – The upper bound of the variable(s).
• name (Optional[str]) – The name(s) of the variable(s).
• key_format (str) – The format used to name/index the variable(s).
• keys (Union[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.

Return type

Dict[str, Variable]

Returns

A dictionary mapping the variable names to variable instances.

Raises

• QiskitOptimizationError – if the variable name is already taken.
• QiskitOptimizationError – if less than one variable instantiation is attempted.
• QiskitOptimizationError – if key_format has more than one substitution or a nested substitution.

QuadraticProgram.continuous_var_list(keys, lowerbound=0, upperbound=1e+20, name=None, key_format='{}')

Uses ‘var_list’ to construct a list of continuous variables

Parameters

• lowerbound (Union[float, int]) – The lower bound of the variable(s).
• upperbound (Union[float, int]) – The upper bound of the variable(s).
• name (Optional[str]) – The name(s) of the variable(s).
• key_format (str) – The format used to name/index the variable(s).
• keys (Union[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.

Return type

List[Variable]

Returns

A list of variable instances.

Raises

• QiskitOptimizationError – if the variable name is already taken.
• QiskitOptimizationError – if less than one variable instantiation is attempted.
• QiskitOptimizationError – if key_format has more than one substitution or a nested substitution.

QuadraticProgram.export_as_lp_string()

Returns the quadratic program as a string of LP format.

Return type

str

Returns

A string representing the quadratic program.

QuadraticProgram.from_docplex(model)

Loads this quadratic program from a docplex model.

Note that this supports only basic functions of docplex as follows: - quadratic objective function - linear / quadratic constraints - binary / integer / continuous variables

Parameters

model (Model) – The docplex model to be loaded.

Raises

QiskitOptimizationError – if the model contains unsupported elements.

Return type

None

QuadraticProgram.from_ising(qubit_op, offset=0.0, linear=False)

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

Parameters

• qubit_op (Union[OperatorBase, WeightedPauliOperator]) – 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 treat as a quadratic term. The default value is False.

Raises

• QiskitOptimizationError – If there are Pauli Xs in any Pauli term
• QiskitOptimizationError – If there are more than 2 Pauli Zs in any Pauli term
• NotImplementedError – If the input operator is a ListOp

Return type

None

QuadraticProgram.get_feasibility_info(x)

Returns whether a solution is feasible or not along with the violations. :type x: Union[List[float], ndarray] :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

QuadraticProgram.get_linear_constraint(i)

Returns a linear constraint for a given name or index.

Parameters

i (Union[int, str]) – the index or name of the constraint.

Return type

LinearConstraint

Returns

The corresponding constraint.

Raises

• IndexError – if the index is out of the list size
• KeyError – if the name does not exist

QuadraticProgram.get_num_binary_vars()

Returns the total number of binary variables.

Return type

int

Returns

The total number of binary variables.

QuadraticProgram.get_num_continuous_vars()

Returns the total number of continuous variables.

Return type

int

Returns

The total number of continuous variables.

QuadraticProgram.get_num_integer_vars()

Returns the total number of integer variables.

Return type

int

Returns

The total number of integer variables.

QuadraticProgram.get_num_linear_constraints()

Returns the number of linear constraints.

Return type

int

Returns

The number of linear constraints.

QuadraticProgram.get_num_quadratic_constraints()

Returns the number of quadratic constraints.

Return type

int

Returns

The number of quadratic constraints.

QuadraticProgram.get_num_vars(vartype=None)

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

Parameters

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

Return type

int

Returns

The total number of variables.

QuadraticProgram.get_quadratic_constraint(i)

Returns a quadratic constraint for a given name or index.

Parameters

i (Union[int, str]) – the index or name of the constraint.

Return type

QuadraticConstraint

Returns

The corresponding constraint.

Raises

• IndexError – if the index is out of the list size
• KeyError – if the name does not exist

QuadraticProgram.get_variable(i)

Returns a variable for a given name or index.

Parameters

i (Union[int, str]) – the index or name of the variable.

Return type

Variable

Returns

The corresponding variable.

QuadraticProgram.integer_var(lowerbound=0, upperbound=1e+20, name=None)

Adds an integer variable to the quadratic program.

Parameters

• lowerbound (Union[float, int]) – The lowerbound of the variable.
• upperbound (Union[float, int]) – The upperbound of the variable.
• name (Optional[str]) – The name of the variable.

Return type

Variable

Returns

The added variable.

Raises

QiskitOptimizationError – if the variable name is already occupied.

QuadraticProgram.integer_var_dict(keys, lowerbound=0, upperbound=1e+20, name=None, key_format='{}')

Uses ‘var_dict’ to construct a dictionary of integer variables

Parameters

• lowerbound (Union[float, int]) – The lower bound of the variable(s).
• upperbound (Union[float, int]) – The upper bound of the variable(s).
• name (Optional[str]) – The name(s) of the variable(s).
• key_format (str) – The format used to name/index the variable(s).
• keys (Union[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.

Return type

Dict[str, Variable]

Returns

A dictionary mapping the variable names to variable instances.

Raises

• QiskitOptimizationError – if the variable name is already taken.
• QiskitOptimizationError – if less than one variable instantiation is attempted.
• QiskitOptimizationError – if key_format has more than one substitution or a nested substitution.

QuadraticProgram.integer_var_list(keys, lowerbound=0, upperbound=1e+20, name=None, key_format='{}')

Uses ‘var_list’ to construct a dictionary of integer variables

Parameters

• lowerbound (Union[float, int]) – The lower bound of the variable(s).
• upperbound (Union[float, int]) – The upper bound of the variable(s).
• name (Optional[str]) – The name(s) of the variable(s).
• key_format (str) – The format used to name/index the variable(s).
• keys (Union[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.

Return type

List[Variable]

Returns

A list of variable instances.

Raises

• QiskitOptimizationError – if the variable name is already taken.
• QiskitOptimizationError – if less than one variable instantiation is attempted.
• QiskitOptimizationError – if key_format has more than one substitution or a nested substitution.

QuadraticProgram.is_feasible(x)

Returns whether a solution is feasible or not.

Parameters

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

Return type

bool

Returns

True if the solution provided is feasible otherwise False.

QuadraticProgram.linear_constraint(linear=None, sense='<=', rhs=0.0, name=None)

Adds a linear equality constraint to the quadratic program of the form:

linear * x sense rhs.

Parameters

• linear (Union[ndarray, spmatrix, List[float], Dict[Union[int, str], float], None]) – The linear coefficients of the left-hand-side of the constraint.
• sense (Union[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 (Optional[str]) – The name of the constraint.

Return type

LinearConstraint

Returns

The added constraint.

Raises

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

QuadraticProgram.maximize(constant=0.0, linear=None, quadratic=None)

Sets a quadratic objective to be maximized.

Parameters

• constant (float) – the constant offset of the objective.
• linear (Union[ndarray, spmatrix, List[float], Dict[Union[int, str], float], None]) – the coefficients of the linear part of the objective.
• quadratic (Union[ndarray, spmatrix, List[List[float]], Dict[Tuple[Union[int, str], Union[int, str]], float], None]) – the coefficients of the quadratic part of the objective.

Return type

None

Returns

The created quadratic objective.

QuadraticProgram.minimize(constant=0.0, linear=None, quadratic=None)

Sets a quadratic objective to be minimized.

Parameters

• constant (float) – the constant offset of the objective.
• linear (Union[ndarray, spmatrix, List[float], Dict[Union[int, str], float], None]) – the coefficients of the linear part of the objective.
• quadratic (Union[ndarray, spmatrix, List[List[float]], Dict[Tuple[Union[int, str], Union[int, str]], float], None]) – the coefficients of the quadratic part of the objective.

Return type

None

Returns

The created quadratic objective.

QuadraticProgram.pprint_as_string()

DEPRECATED Returns the quadratic program as a string in Docplex’s pretty print format. :rtype: str :returns: A string representing the quadratic program.

QuadraticProgram.prettyprint(out=None)

DEPRECATED Pretty prints the quadratic program to a given output stream (None = default).

Parameters

out (Optional[str]) – The output stream or file name to print to. if you specify a file name, the output file name is has ‘.mod’ as suffix.

Return type

None

QuadraticProgram.quadratic_constraint(linear=None, quadratic=None, sense='<=', rhs=0.0, name=None)

Adds a quadratic equality constraint to the quadratic program of the form:

x * Q * x <= rhs.

Parameters

• linear (Union[ndarray, spmatrix, List[float], Dict[Union[int, str], float], None]) – The linear coefficients of the constraint.
• quadratic (Union[ndarray, spmatrix, List[List[float]], Dict[Tuple[Union[int, str], Union[int, str]], float], None]) – The quadratic coefficients of the constraint.
• sense (Union[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 (Optional[str]) – The name of the constraint.

Return type

QuadraticConstraint

Returns

The added constraint.

Raises

QiskitOptimizationError – if the constraint name already exists.

QuadraticProgram.read_from_lp_file(filename)

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.
• MissingOptionalLibraryError – If CPLEX is not installed.

Return type

None

QuadraticProgram.remove_linear_constraint(i)

Remove a linear constraint

Parameters

i (Union[str, int]) – an index or a name of a linear constraint

Raises

• KeyError – if name does not exist
• IndexError – if index is out of range

Return type

None

QuadraticProgram.remove_quadratic_constraint(i)

Remove a quadratic constraint

Parameters

i (Union[str, int]) – an index or a name of a quadratic constraint

Raises

• KeyError – if name does not exist
• IndexError – if index is out of range

Return type

None

QuadraticProgram.substitute_variables(constants=None, variables=None)

Substitutes variables with constants or other variables.

Parameters

• constants (Optional[Dict[Union[int, str], float]]) – replace variable by constant e.g., {‘x’: 2} means ‘x’ is substituted with 2
• variables (Optional[Dict[Union[str, int], Tuple[Union[str, int], float]]]) – 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

Return type

QuadraticProgram

Returns

An optimization problem by substituting variables with constants or other variables. If the substitution is valid, QuadraticProgram.status is still QuadraticProgram.Status.VALIAD. 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.

QuadraticProgram.to_docplex()

Returns a docplex model corresponding to this quadratic program.

Return type

Model

Returns

The docplex model corresponding to this quadratic program.

Raises

QiskitOptimizationError – if non-supported elements (should never happen).

QuadraticProgram.to_ising()

Return the Ising Hamiltonian of this problem.

Returns

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

Return type

qubit_op

Raises

• QiskitOptimizationError – If a variable type is not binary.
• QiskitOptimizationError – If constraints exist in the problem.

QuadraticProgram.write_to_lp_file(filename)

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

Return type

None

Returns the list of linear constraints of the quadratic program.

Return type

List[LinearConstraint]

Returns

List of linear constraints.

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

Return type

Dict[str, int]

Returns

The linear constraint index dictionary.

Returns the name of the quadratic program.

Return type

str

Returns

The name of the quadratic program.

Returns the quadratic objective.

Return type

QuadraticObjective

Returns

The quadratic objective.

Returns the list of quadratic constraints of the quadratic program.

Return type

List[QuadraticConstraint]

Returns

List of quadratic constraints.

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

Return type

Dict[str, int]

Returns

The quadratic constraint index dictionary.

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

Return type

QuadraticProgramStatus

Returns

The status of the quadratic program

Returns the list of variables of the quadratic program.

Return type

List[Variable]

Returns

List of variables.

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

Return type

Dict[str, int]

Returns

The variable index dictionary.