qubosolver.transforms
qubosolver.transforms
Transforms for QUBO instances.
Provides preprocessing transforms such as variable fixing to reduce problem size before solving.
Modules:
-
negative_bitflip–Bit-flip preprocessing transforms for QUBO instances with negative interactions.
-
variable_fixing–Variable-fixing transforms for QUBO problem reduction.
-
zeroing–Zeroing fallback for QUBO negative off-diagonal coefficients.
qubosolver.transforms.negative_bitflip
Bit-flip preprocessing transforms for QUBO instances with negative interactions.
Quantum (Rydberg) solvers cannot encode attractive interactions, so a QUBO must
have non-negative off-diagonal coefficients to be embeddable. A change of
variable x_i -> 1 - y_i on a subset of variables flips the sign of the
interactions incident to it; choosing the subset that removes as much negative
weight as possible is itself a QUBO, f^T Q_f f with Q_f = diag(C 1) - C,
solved here by local search or tabu search.
apply finds the bit flips (by default with a local search on Q_f) and
applies them to the matrix, returning a wrapper Instance that
records the flip vector so the solution can later be mapped back with
lift. When bit flips
cannot remove every negative off-diagonal coefficient, the remaining ones can
be dropped with transforms.zeroing.apply.
Typical usage:
from qubosolver.transforms import negative_bitflip
from qubosolver.solving import brute_force
flipped_instance = negative_bitflip.apply(instance, time_limit_s=60.0)
flipped_solution = brute_force.solve(flipped_instance)
solution = negative_bitflip.lift(flipped_solution, flipped_instance)
Classes:
-
Instance–A QUBO instance carrying bit-flip preprocessing history.
Functions:
-
apply–Find the bit flips minimizing negative weight and apply them to the QUBO matrix.
-
lift–Map a solution of the bit-flipped QUBO instance back onto the original variables.
Instance
Instance(parent_instance: qubosolver.Instance)
A QUBO instance carrying bit-flip preprocessing history.
Wraps a parent qubosolver.Instance whose off-diagonal coefficients may
contain negative interactions. Applying apply solves the bit-flip problem,
stores the flip vector here, and exposes the transformed matrix so it can be
embedded and solved. lift uses the stored state to map a solution
back onto the original variables.
Parameters:
-
parent_instance(qubosolver.Instance) –The original QUBO instance (before bit flips). A deep copy is kept internally for later reconstruction.
Methods:
-
__init_subclass__–Register
clsunder its_tagsoloadcan dispatch to it. -
__len__–Number of binary variables in the QUBO problem (same as
size). -
cost–Compute the QUBO objective \(x^T Q x\) for a candidate solution \(x\).
-
load– -
save–Serialize this instance to
file_like, tagged with its type.
Attributes:
-
flips(Bitstring) –Flip vector applied to the parent matrix, all-zero until
applypopulates it. -
matrix(Matrix) –The QUBO symmetric matrix.
-
negative_bitflip(negative_bitflip.Instance) –View of this instance as a negative-bitflip instance.
-
size(int) –Number of binary variables in the QUBO problem.
-
variable_fixing(variable_fixing.Instance) –View of this instance as a variable-fixing instance.
-
zeroing(zeroing.Instance) –View of this instance as a zeroing instance.
Source code in qubosolver/transforms/negative_bitflip.py
flips
instance-attribute
Flip vector applied to the parent matrix, all-zero until apply populates it.
matrix
property
matrix: Matrix
The QUBO symmetric matrix.
Returns:
-
Matrix–QUBO symmetric matrix of shape
(size, size).
Raises:
-
AssertionError–If the internal tensor is not 2-D or not square.
negative_bitflip
property
negative_bitflip: negative_bitflip.Instance
View of this instance as a negative-bitflip instance.
Convenience property to avoid the boilerplate of
assert isinstance(instance, negative_bitflip.Instance) before calling
a method specific to that subclass. It exists purely to satisfy static
type checkers (mypy) and enable IDE code completion — the runtime
isinstance check and the TypeError below just mirror the guarantee that
the assert
would otherwise provide.
Returns:
-
negative_bitflip.Instance–This instance, narrowed to the negative-bitflip subclass.
Raises:
-
TypeError–If this instance is not a
negative_bitflip.Instance.
variable_fixing
property
variable_fixing: variable_fixing.Instance
View of this instance as a variable-fixing instance.
Convenience property to avoid the boilerplate of
assert isinstance(instance, variable_fixing.Instance) before calling
a method specific to that subclass. It exists purely to satisfy static
type checkers (mypy) and enable IDE code completion — the runtime
isinstance check and the TypeError below just mirror the guarantee that
the assert
would otherwise provide.
Returns:
-
variable_fixing.Instance–This instance, narrowed to the variable-fixing subclass.
Raises:
-
TypeError–If this instance is not a
variable_fixing.Instance.
zeroing
property
zeroing: zeroing.Instance
View of this instance as a zeroing instance.
Convenience property to avoid the boilerplate of
assert isinstance(instance, zeroing.Instance) before calling
a method specific to that subclass. It exists purely to satisfy static
type checkers (mypy) and enable IDE code completion — the runtime
isinstance check and the TypeError below just mirror the guarantee that
the assert
would otherwise provide.
Returns:
-
zeroing.Instance–This instance, narrowed to the zeroing subclass.
Raises:
-
TypeError–If this instance is not a
zeroing.Instance.
__init_subclass__
__init_subclass__(**kwargs: object) -> None
Register cls under its _tag so load can dispatch to it.
Automatic, so a new Instance subclass never needs to be added to a
separate registry by hand.
Source code in qubosolver/types/instance.py
__len__
__len__() -> int
cost
Compute the QUBO objective \(x^T Q x\) for a candidate solution \(x\).
Parameters:
-
solution(Bitstring) –Binary vector \(x\) of shape
(size,).
Returns:
-
float–Scalar cost value.
Source code in qubosolver/types/instance.py
load
classmethod
Deserialize an Instance previously saved with save.
Called on the base class qubosolver.Instance, it loads any instance with
automatic dispatch.
Called on a subclass (e.g.
variable_fixing.Instance.load(f)),
it additionally requires the loaded Instance to be an instance of that subclass
(raising TypeError otherwise).
Parameters:
-
file_like(FileLike[bytes]) –Source file path or readable binary file object, as produced by
save.
Returns:
-
Self–A new instance of whichever concrete type wrote the tag.
Raises:
-
ValueError–If the stream is not a qubosolver file, or if its type tag is missing or unrecognized.
-
TypeError–If the loaded instance's type is not
clsor a subclass thereof.
Example
from pathlib import Path
from qubosolver import Instance
from qubosolver.transforms import variable_fixing
file = Path("instance.bin")
instance = variable_fixing.Instance(Instance())
with file.open("wb") as f:
instance.save(f)
# Three ways to load it back, from least to most strict:
with file.open("rb") as f:
loaded = Instance.load(f) # accepts any Instance subtype
# loads, then narrows (fails after loading)
loaded = Instance.load(f).variable_fixing
loaded = variable_fixing.Instance.load(f) # narrows first (fails before loading)
Source code in qubosolver/types/instance.py
save
save(file_like: FileLike[bytes]) -> None
Serialize this instance to file_like, tagged with its type.
Parameters:
-
file_like(FileLike[bytes]) –Destination — a file path (
stroros.PathLike), or a binary-writabletyping.IOstream.
Source code in qubosolver/types/instance.py
apply
apply(instance: qubosolver.Instance, *, method: Literal['local_search', 'tabu_search'] = 'local_search', time_limit_s: float = 60.0, eps: float = 0.0, rng: torch.Generator | None = None) -> Instance
Find the bit flips minimizing negative weight and apply them to the QUBO matrix.
Wraps instance in a bit-flip Instance, finds the flips with method,
and replaces the matrix with its flipped counterpart. When
instance has no negative off-diagonal coefficient, the wrapper is returned
unchanged (flips stays all-zero).
Parameters:
-
instance(qubosolver.Instance) –The QUBO instance to preprocess.
-
method(Literal['local_search', 'tabu_search'], default:'local_search') –"local_search"(solving.iterative_bitflip_local_search.solveonQ_f, from random starts plus the no-flip start),"tabu_search"(the same local search, refined withsolving.tabu_search.solve). -
time_limit_s(float, default:60.0) –Time limit in seconds. For
"tabu_search", it is shared by the local search and the tabu search. -
eps(float, default:0.0) –Tolerance below which a coefficient is treated as zero.
-
rng(torch.Generator | None, default:None) –PyTorch random number generator controlling the random starts of the local search.
Returns:
-
Instance–A bit-flip instance carrying the flip vector and metrics.
Raises:
-
ValueError–If
methodis unknown.
Source code in qubosolver/transforms/negative_bitflip.py
lift
Map a solution of the bit-flipped QUBO instance back onto the original variables.
Undoes the flips recorded on flipped_instance (y_i -> x_i) and recomputes
costs against the original (unflipped) matrix. When no bit flip was applied,
returns a deep copy of flipped_solution unchanged.
Parameters:
-
flipped_solution(Solution) –Solution obtained on the bit-flipped instance.
-
flipped_instance(Instance) –The bit-flipped instance produced by
apply.
Returns:
-
Solution–A new solution over the original variables.
Source code in qubosolver/transforms/negative_bitflip.py
qubosolver.transforms.variable_fixing
Variable-fixing transforms for QUBO problem reduction.
Variable fixing eliminates variables from a QUBO instance before solving by proving, from the structure of the objective matrix alone, that certain variables must be 0 or 1 in any optimal solution. Reducing the problem size this way can significantly cut the resources required by the solver.
Typical usage:
from qubosolver.transforms import variable_fixing
from qubosolver.solving import brute_force
reduced_instance = variable_fixing.apply_recursively(instance)
reduced_solution = brute_force.solve(reduced_instance)
solution = variable_fixing.lift(reduced_solution, reduced_instance)
Classes:
-
Instance–A QUBO instance with variable-fixing history.
Functions:
-
apply–Apply each fixation rule once and reduce the QUBO matrix accordingly.
-
apply_recursively–Apply fixation rules repeatedly until no further variables can be fixed.
-
hansen_fixing–Identify variables that can be fixed using Hansen's bounding criterion.
-
lift–Reconstruct the full solution by reinserting fixed variables.
Attributes:
-
Rule–A function that inspects a QUBO instance and returns the variables it can fix,
Rule
module-attribute
A function that inspects a QUBO instance and returns the variables it can fix, as a mapping from variable index to the value (0 or 1) it is fixed to.
Instance
Instance(parent_instance: qubosolver.Instance)
A QUBO instance with variable-fixing history.
Wraps a parent qubosolver.Instance and
tracks which variables were fixed (and to which value) so the original
solution can be reconstructed via lift.
Parameters:
-
parent_instance(qubosolver.Instance) –The original (unreduced) QUBO instance. A deep copy is kept internally for later reconstruction.
Methods:
-
__init_subclass__–Register
clsunder its_tagsoloadcan dispatch to it. -
__len__–Number of binary variables in the QUBO problem (same as
size). -
cost–Compute the QUBO objective \(x^T Q x\) for a candidate solution \(x\).
-
load– -
save–Serialize this instance to
file_like, tagged with its type.
Attributes:
-
fixed_indices(list[dict[int, int]]) –Fixation history: one dict per
applycall, mapping index → fixed value. -
matrix(Matrix) –The QUBO symmetric matrix.
-
n_fixed_indices(int) –Total number of variables fixed across all fixation rounds.
-
negative_bitflip(negative_bitflip.Instance) –View of this instance as a negative-bitflip instance.
-
size(int) –Number of binary variables in the QUBO problem.
-
variable_fixing(variable_fixing.Instance) –View of this instance as a variable-fixing instance.
-
zeroing(zeroing.Instance) –View of this instance as a zeroing instance.
Source code in qubosolver/transforms/variable_fixing.py
fixed_indices
property
Fixation history: one dict per apply call, mapping index → fixed value.
matrix
property
matrix: Matrix
The QUBO symmetric matrix.
Returns:
-
Matrix–QUBO symmetric matrix of shape
(size, size).
Raises:
-
AssertionError–If the internal tensor is not 2-D or not square.
n_fixed_indices
property
n_fixed_indices: int
Total number of variables fixed across all fixation rounds.
negative_bitflip
property
negative_bitflip: negative_bitflip.Instance
View of this instance as a negative-bitflip instance.
Convenience property to avoid the boilerplate of
assert isinstance(instance, negative_bitflip.Instance) before calling
a method specific to that subclass. It exists purely to satisfy static
type checkers (mypy) and enable IDE code completion — the runtime
isinstance check and the TypeError below just mirror the guarantee that
the assert
would otherwise provide.
Returns:
-
negative_bitflip.Instance–This instance, narrowed to the negative-bitflip subclass.
Raises:
-
TypeError–If this instance is not a
negative_bitflip.Instance.
variable_fixing
property
variable_fixing: variable_fixing.Instance
View of this instance as a variable-fixing instance.
Convenience property to avoid the boilerplate of
assert isinstance(instance, variable_fixing.Instance) before calling
a method specific to that subclass. It exists purely to satisfy static
type checkers (mypy) and enable IDE code completion — the runtime
isinstance check and the TypeError below just mirror the guarantee that
the assert
would otherwise provide.
Returns:
-
variable_fixing.Instance–This instance, narrowed to the variable-fixing subclass.
Raises:
-
TypeError–If this instance is not a
variable_fixing.Instance.
zeroing
property
zeroing: zeroing.Instance
View of this instance as a zeroing instance.
Convenience property to avoid the boilerplate of
assert isinstance(instance, zeroing.Instance) before calling
a method specific to that subclass. It exists purely to satisfy static
type checkers (mypy) and enable IDE code completion — the runtime
isinstance check and the TypeError below just mirror the guarantee that
the assert
would otherwise provide.
Returns:
-
zeroing.Instance–This instance, narrowed to the zeroing subclass.
Raises:
-
TypeError–If this instance is not a
zeroing.Instance.
__init_subclass__
__init_subclass__(**kwargs: object) -> None
Register cls under its _tag so load can dispatch to it.
Automatic, so a new Instance subclass never needs to be added to a
separate registry by hand.
Source code in qubosolver/types/instance.py
__len__
__len__() -> int
cost
Compute the QUBO objective \(x^T Q x\) for a candidate solution \(x\).
Parameters:
-
solution(Bitstring) –Binary vector \(x\) of shape
(size,).
Returns:
-
float–Scalar cost value.
Source code in qubosolver/types/instance.py
load
classmethod
Deserialize an Instance previously saved with save.
Called on the base class qubosolver.Instance, it loads any instance with
automatic dispatch.
Called on a subclass (e.g.
variable_fixing.Instance.load(f)),
it additionally requires the loaded Instance to be an instance of that subclass
(raising TypeError otherwise).
Parameters:
-
file_like(FileLike[bytes]) –Source file path or readable binary file object, as produced by
save.
Returns:
-
Self–A new instance of whichever concrete type wrote the tag.
Raises:
-
ValueError–If the stream is not a qubosolver file, or if its type tag is missing or unrecognized.
-
TypeError–If the loaded instance's type is not
clsor a subclass thereof.
Example
from pathlib import Path
from qubosolver import Instance
from qubosolver.transforms import variable_fixing
file = Path("instance.bin")
instance = variable_fixing.Instance(Instance())
with file.open("wb") as f:
instance.save(f)
# Three ways to load it back, from least to most strict:
with file.open("rb") as f:
loaded = Instance.load(f) # accepts any Instance subtype
# loads, then narrows (fails after loading)
loaded = Instance.load(f).variable_fixing
loaded = variable_fixing.Instance.load(f) # narrows first (fails before loading)
Source code in qubosolver/types/instance.py
save
save(file_like: FileLike[bytes]) -> None
Serialize this instance to file_like, tagged with its type.
Parameters:
-
file_like(FileLike[bytes]) –Destination — a file path (
stroros.PathLike), or a binary-writabletyping.IOstream.
Source code in qubosolver/types/instance.py
apply
apply(instance: qubosolver.Instance, fixation_rules: Sequence[Rule] = (hansen_fixing,), *, inplace: bool = False) -> Instance
Apply each fixation rule once and reduce the QUBO matrix accordingly.
Each rule in fixation_rules is called in order; variables it identifies
are immediately fixed and the matrix is reduced before the next rule runs.
Parameters:
-
instance(qubosolver.Instance) –The QUBO instance to reduce.
-
fixation_rules(Sequence[Rule], default:(hansen_fixing,)) –Ordered sequence of
Rulecallables. -
inplace(bool, default:False) –If
False(default), wrapsinstancein a new variable-fixingInstancebefore modifying it.
Returns:
-
Instance–The reduced instance with updated fixation history.
Source code in qubosolver/transforms/variable_fixing.py
apply_recursively
apply_recursively(instance: qubosolver.Instance, fixation_rules: Sequence[Rule] = (hansen_fixing,), *, inplace: bool = False) -> Instance
Apply fixation rules repeatedly until no further variables can be fixed.
Calls apply in a loop; stops when a full pass over all rules
fixes no additional variables.
Parameters:
-
instance(qubosolver.Instance) –The QUBO instance to reduce.
-
fixation_rules(Sequence[Rule], default:(hansen_fixing,)) –Ordered sequence of [
Rule] callables. -
inplace(bool, default:False) –If
False(default), wrapsinstancein a new variable-fixingInstancebefore modifying it.
Returns:
-
Instance–The fully reduced instance.
Source code in qubosolver/transforms/variable_fixing.py
hansen_fixing
hansen_fixing(instance: qubosolver.Instance) -> dict[int, int]
Identify variables that can be fixed using Hansen's bounding criterion.
For each variable i, computes a lower bound
c_i + 2 * sum(min(0, Q_ij)) and an upper bound
c_i + 2 * sum(max(0, Q_ij)) from the diagonal and off-diagonal
elements of the QUBO matrix. A variable is fixed to 0 when its lower
bound is non-negative (it cannot improve the objective by being 1) and
to 1 when its upper bound is non-positive (it can only improve it).
Parameters:
-
instance(qubosolver.Instance) –The QUBO instance to analyze.
Returns:
-
dict[int, int]–Mapping of variable index to fixed value (
0or1). Variables that cannot be fixed are omitted.
Source code in qubosolver/transforms/variable_fixing.py
lift
Reconstruct the full solution by reinserting fixed variables.
Reverses the fixation history stored in reduced_instance: fixed variables
are reinserted at their original positions in each bitstring, and costs
are recomputed against the original (unreduced) QUBO matrix.
If no variables were fixed, returns a deep copy of reduced_solution
unchanged.
Parameters:
-
reduced_solution(Solution) –Solution obtained from solving the reduced QUBO.
-
reduced_instance(Instance) –The reduced instance carrying the fixation history and a reference to the original instance.
Returns:
-
Solution–A new solution with full-length bitstrings and costs evaluated against the original QUBO matrix. Counts and probabilities are carried over from
reduced_solution.
Source code in qubosolver/transforms/variable_fixing.py
qubosolver.transforms.zeroing
Zeroing fallback for QUBO negative off-diagonal coefficients.
Bit-flip preprocessing (see
transforms.negative_bitflip) removes as much negative
off-diagonal weight as possible, but some negative coefficients may remain when
the problem is not fully bipartisable. Quantum (Rydberg) solvers cannot embed
such coefficients, so this module offers a last-resort approximation:
apply sets every remaining negative
off-diagonal coefficient to zero and records which positions were zeroed in a
zeroing Instance.
from qubosolver.transforms import negative_bitflip, zeroing
reduced_instance = negative_bitflip.apply(instance, time_limit_s=60.0)
# drop any negative coefficient bit flips could not remove
zeroed_instance = zeroing.apply(reduced_instance)
print(zeroed_instance.zeroed_edges) # (N, 2) tensor of zeroed (i, j) index pairs
Classes:
Functions:
-
apply–Set remaining negative off-diagonal coefficients to zero.
-
lift–Map a solution of the zeroed QUBO back onto the pre-zeroing problem.
Instance
Instance(parent_instance: qubosolver.Instance)
A QUBO Instance recording zeroing history.
Records which off-diagonal coefficients were set to zero by
apply by keeping the matrix of the
removed negative coefficients (negative_matrix) rather than a single
flag. Because the QUBO matrix is symmetric, each zeroed interaction appears
twice in negative_matrix but once in
zeroed_edges.
Parameters:
-
parent_instance(qubosolver.Instance) –The QUBO instance to extend with zeroing state.
Methods:
-
__init_subclass__–Register
clsunder its_tagsoloadcan dispatch to it. -
__len__–Number of binary variables in the QUBO problem (same as
size). -
cost–Compute the QUBO objective \(x^T Q x\) for a candidate solution \(x\).
-
load– -
save–Serialize this instance to
file_like, tagged with its type.
Attributes:
-
matrix(Matrix) –The QUBO symmetric matrix.
-
negative_bitflip(negative_bitflip.Instance) –View of this instance as a negative-bitflip instance.
-
negative_matrix(Matrix) –Matrix of removed negative coefficients: same (symmetric) shape as the
-
size(int) –Number of binary variables in the QUBO problem.
-
variable_fixing(variable_fixing.Instance) –View of this instance as a variable-fixing instance.
-
zeroed_edges(torch.Tensor) –The zeroed interactions as an
(N, 2)tensor of(i, j)index pairs. -
zeroing(zeroing.Instance) –View of this instance as a zeroing instance.
Source code in qubosolver/transforms/zeroing.py
matrix
property
matrix: Matrix
The QUBO symmetric matrix.
Returns:
-
Matrix–QUBO symmetric matrix of shape
(size, size).
Raises:
-
AssertionError–If the internal tensor is not 2-D or not square.
negative_bitflip
property
negative_bitflip: negative_bitflip.Instance
View of this instance as a negative-bitflip instance.
Convenience property to avoid the boilerplate of
assert isinstance(instance, negative_bitflip.Instance) before calling
a method specific to that subclass. It exists purely to satisfy static
type checkers (mypy) and enable IDE code completion — the runtime
isinstance check and the TypeError below just mirror the guarantee that
the assert
would otherwise provide.
Returns:
-
negative_bitflip.Instance–This instance, narrowed to the negative-bitflip subclass.
Raises:
-
TypeError–If this instance is not a
negative_bitflip.Instance.
negative_matrix
instance-attribute
negative_matrix: Matrix = torch.zeros_like(self._matrix)
Matrix of removed negative coefficients: same (symmetric) shape as the QUBO matrix, holding the original values at zeroed positions and 0 elsewhere.
variable_fixing
property
variable_fixing: variable_fixing.Instance
View of this instance as a variable-fixing instance.
Convenience property to avoid the boilerplate of
assert isinstance(instance, variable_fixing.Instance) before calling
a method specific to that subclass. It exists purely to satisfy static
type checkers (mypy) and enable IDE code completion — the runtime
isinstance check and the TypeError below just mirror the guarantee that
the assert
would otherwise provide.
Returns:
-
variable_fixing.Instance–This instance, narrowed to the variable-fixing subclass.
Raises:
-
TypeError–If this instance is not a
variable_fixing.Instance.
zeroed_edges
property
The zeroed interactions as an (N, 2) tensor of (i, j) index pairs.
Each symmetric pair is reported once (i < j); N is the number of
zeroed off-diagonal interactions.
zeroing
property
zeroing: zeroing.Instance
View of this instance as a zeroing instance.
Convenience property to avoid the boilerplate of
assert isinstance(instance, zeroing.Instance) before calling
a method specific to that subclass. It exists purely to satisfy static
type checkers (mypy) and enable IDE code completion — the runtime
isinstance check and the TypeError below just mirror the guarantee that
the assert
would otherwise provide.
Returns:
-
zeroing.Instance–This instance, narrowed to the zeroing subclass.
Raises:
-
TypeError–If this instance is not a
zeroing.Instance.
__init_subclass__
__init_subclass__(**kwargs: object) -> None
Register cls under its _tag so load can dispatch to it.
Automatic, so a new Instance subclass never needs to be added to a
separate registry by hand.
Source code in qubosolver/types/instance.py
__len__
__len__() -> int
cost
Compute the QUBO objective \(x^T Q x\) for a candidate solution \(x\).
Parameters:
-
solution(Bitstring) –Binary vector \(x\) of shape
(size,).
Returns:
-
float–Scalar cost value.
Source code in qubosolver/types/instance.py
load
classmethod
Deserialize an Instance previously saved with save.
Called on the base class qubosolver.Instance, it loads any instance with
automatic dispatch.
Called on a subclass (e.g.
variable_fixing.Instance.load(f)),
it additionally requires the loaded Instance to be an instance of that subclass
(raising TypeError otherwise).
Parameters:
-
file_like(FileLike[bytes]) –Source file path or readable binary file object, as produced by
save.
Returns:
-
Self–A new instance of whichever concrete type wrote the tag.
Raises:
-
ValueError–If the stream is not a qubosolver file, or if its type tag is missing or unrecognized.
-
TypeError–If the loaded instance's type is not
clsor a subclass thereof.
Example
from pathlib import Path
from qubosolver import Instance
from qubosolver.transforms import variable_fixing
file = Path("instance.bin")
instance = variable_fixing.Instance(Instance())
with file.open("wb") as f:
instance.save(f)
# Three ways to load it back, from least to most strict:
with file.open("rb") as f:
loaded = Instance.load(f) # accepts any Instance subtype
# loads, then narrows (fails after loading)
loaded = Instance.load(f).variable_fixing
loaded = variable_fixing.Instance.load(f) # narrows first (fails before loading)
Source code in qubosolver/types/instance.py
save
save(file_like: FileLike[bytes]) -> None
Serialize this instance to file_like, tagged with its type.
Parameters:
-
file_like(FileLike[bytes]) –Destination — a file path (
stroros.PathLike), or a binary-writabletyping.IOstream.
Source code in qubosolver/types/instance.py
apply
apply(instance: qubosolver.Instance) -> Instance
Set remaining negative off-diagonal coefficients to zero.
Approximates the QUBO by dropping any negative off-diagonal coefficient that
bit flips could not remove, so a quantum solver can embed it. Returns a
Instance whose
negative_matrix
holds the removed coefficients (an all-zero matrix when nothing was zeroed).
Parameters:
-
instance(qubosolver.Instance) –The QUBO instance to zero.
Returns:
-
Instance–A zeroing instance.
Source code in qubosolver/transforms/zeroing.py
lift
Map a solution of the zeroed QUBO back onto the pre-zeroing problem.
Zeroing only drops coefficients; it does not rename or remove variables, so
the bitstrings themselves are kept. Costs are recomputed against the
pre-zeroing matrix (_parent_instance) so they reflect the true, non-
approximated objective rather than the zeroed one, and the candidates are
re-sorted by that cost, since the order on the zeroed matrix may differ.
When nothing was zeroed, returns a deep copy of zeroed_solution unchanged.
Parameters:
-
zeroed_solution(Solution) –Solution obtained on the zeroed QUBO.
-
zeroed_instance(Instance) –The zeroed instance produced by
apply.
Returns:
-
Solution–A new solution with costs evaluated against the pre-zeroing matrix, sorted by ascending cost.