Tools

class titanq.tools.BipolarToBinary(*, weights: ndarray | None = None, bias: ndarray, inplace: bool)

ℹ️ This feature is experimental and may change.

Convert a bipolar problem to be solved as binary.

TitanQ doesn’t support bipolar problems directly, but these can be converted to binary problems instead.

The following steps are involved:

Convert the weight matrix and bias vector.
Create a titanq.Model object with binary variables, using the converted weight matrix and bias vector.
Optimize the model.
Reuse the object created in step 1 to convert the optimization result (result vector and objective value).

This class assists with steps 1 and 4.

⚠️ Warning

Ensure you convert the result back to bipolar after solving the problem. See convert_result().

Example

>>> # Step 1: Convert the bipolar problem.
>>> # Let weights and bias define a BIPOLAR problem.
>>> converter = BipolarToBinary(weights=weights, bias=bias, inplace=False)
>>>
>>> # Step 2: Create the binary model.
>>> model = Model()
>>> model.add_variable_vector('x', size, Vtype.BINARY)  # Notice "Vtype.BINARY"
>>> model.set_objective_matrices(
>>>     converter.converted_weights(),  # Notice usage of CONVERTED weights
>>>     converter.converted_bias(),  # Notice usage of CONVERTED bias
>>>     Target.MINIMIZE)
>>>
>>> # Step 3: Optimize the binary problem.
>>> response = model.optimize()  # Add your usual arguments here.
>>>
>>> # Step 4: Convert the result back to bipolar.
>>> for objective_value, result_vector in response.result_items():
>>>     objective_value, result_vector = converter.convert_result(
>>>         objective_value,
>>>         result_vector,
>>>         inplace=False)

__init__(*, weights: ndarray | None = None, bias: ndarray, inplace: bool) → None

Convert a bipolar problem definition to binary and construct a converter for its solution (back from binary into bipolar).

Parameters

weights: Weight matrix defining the bipolar problem. Refer to titanq.Model.set_objective_matrices() for the format. If None, an all-zero matrix is assumed.
bias: Bias vector defining the bipolar problem. Refer to titanq.Model.set_objective_matrices() for the format.
inplace: If True, modifies the weights and bias in-place, meaning the original object is modified and no copy is created. This is useful when dealing with very large objects.

⚠️ Warning

The created object can only convert a solution corresponding to the inputs used to construct it. If used with any other problem, the conversion will be incorrect.

convert_result(objective_value: float, result_vector: ndarray, *, inplace: bool) → Tuple[float, ndarray]

Take a result from a binary computation and convert it back to be as if it was optimized as a bipolar problem.

⚠️ Warning

The conversion uses values computed from the original weights and bias. Do not use this object to convert a solution from a different problem than the one used to construct it.

Parameters

objective_value: The objective value returned from the binary optimization response.
result_vector: The result vector returned from the binary optimization response.
inplace: If True, modifies the result vector in-place, meaning the original object is modified and no copy is created. This is useful when dealing with very large objects.

Returns

The objective value and result vector that would have been obtained if the problem had been optimized as bipolar.

The objective value is converted to match the original weights and bias, before they were converted.

The result vector is converted to bipolar values ({-1, 1}) instead of binary values ({0, 1}).

converted_bias() → ndarray

Return the bias converted from a bipolar problem to a binary one. Only the values change. The shape and types remain the same.

If the bias was converted in-place, then the returned object is the modified one, not a copy.

converted_weights() → ndarray | None

Return the weights converted from a bipolar problem to a binary one. Only the values change. The shape and types remain the same.

Return None if no weights were passed in. See __init__().

If the weights were converted in-place, then the returned object is the modified one, not a copy.

titanq.tools.configure_model_from_mps_file(model: Model, file_path: Path) → None

Configure a model with an MPS file. Set the variable vector, the objective matrices and the constraints.

Parameters

model: The instance of the model to configure.
file_path: The path to the MPS file.