API Reference

minimize(Q::Matrix[, l::Vector[, c::Number ; device, cutoff, kwargs...)

Solve the Quadratic Unconstrained Binary Optimization (QUBO) problem

min  b'Qb + l'b + c
s.t. b_i in {0, 1}

Return the optimal value E and a probability distribution ψ over optimal solutions. You can use sample to get an actual bitstring from ψ.

There are multiple backends available, selected through the keyword backend. By default, it uses DMRG to calculate the optimal solution.

Keyword arguments:

• iterations :: Int - Maximum iterations the solver should run. Defaults to 10.

• cutoff :: Float64 - Any absolute value below this threshold is considered zero. Defaults to 1e-8. You can use this keyword to control the solver's accuracy vs resources trade-off.

• time_limit :: Float64 - If specified, determines the maximum running time in seconds. It only determines whether a new iteration should start or not, thus the solver may run for longer if the threshold happens during an iteration.

• device = cpu - Accelerator device used during computation. See the section below for how to run on GPUs.

• preprocess :: Bool - Defaults to false. If true, permute QUBO variables before constructing the MPS Hamiltonian so coupled variables are closer in the one-dimensional tensor order. Samples are returned in the caller's original variable order. This is an experimental feature and may be subject to changes.

• on_iteration :: Function - Called after each recorded iteration as f(psi::MPS; iteration, objective, bond_dim, elapsed_time). objective is the expected objective function ⟨ψ|H|ψ⟩ at this iteration. Use to collect statistics or serialize intermediate states. psi is the MPS for that iteration. Default: nothing (no callback).

• callback_every :: Int - Invoke the callback every N iterations. Must be >= 1. Default: 1.

• backend - Solver backend. Defaults to the current DMRG implementation. Use backend = :dmrg or backend = DMRGBackend() to select it explicitly. Other backends are reserved for optional extensions.

  Other keywords might be available depending on the chosen backend. See the documentation for each backend for comprehensive lists.

The returned Solution carries per-iteration stats in the fields energies, bond_dims, and elapsed_times.

Running on GPU:

The optional keyword device controls whether the solver should run on CPU or GPU. For using a GPU, you can import the respective package, e.g. CUDA.jl, and pass its accelerator as argument.

import CUDA
minimize(Q; device = CUDA.cu)

import Metal
minimize(Q; device = Metal.mtl)

See also maximize.

maximize(Q::Matrix[, l::Vector[, c::Number; kwargs...)

Solve the Quadratic Unconstrained Binary Optimization problem for maximization.

max  b'Qb + l'b + c
s.t. b_i in {0, 1}

See also minimize.

AbstractTenSolverBackend

Abstract solver backend marker for TenSolver implementations.

Backends must provide backend-specific minimize methods for the normalized optimization inputs they support. Matrix backends implement minimize(::MyBackend, Q::AbstractMatrix, l, c; kwargs...); polynomial backends implement minimize(::MyBackend, p::AbstractPolynomial; kwargs...). Extensions that support symbolic selection must also define normalize_backend(::Val{:my_backend}) = MyBackend(...).

See also

DMRGBackend, normalize_backend

DMRGBackend()

Select TenSolver's default ITensorMPS DMRG backend.

normalize_backend(backend)

Normalize a user-facing backend selector into a backend object.

Backends can support backend = :my_backend by defining normalize_backend(::Val{:my_backend}) = MyBackend(...).

Solution

The result of running minimize or maximize: an MPS wave function over the optimal solution space, together with per-iteration convergence stats.

Use sample to draw bitstrings from it.

Fields

• tensor: the underlying MPS.
• energies: expected objective value of the problem recorded at each iteration of the solver.
• bond_dims: maximum MPS bond dimension at each iteration.
• elapsed_times: wall-clock time in seconds from the start of the solve at each iteration.
• permutation: original variable index represented by each tensor site.

The three stats vectors are parallel — energies[i], bond_dims[i], and elapsed_times[i] all correspond to iteration i.

sample(psi)

Sample a bitstring from a (quantum) probability distribution.

bool_to_spin(x)

Convert a Boolean bit vector x_i in {0, 1} to Ising spins s_i in {-1, +1} using QUBOTools' BoolDomain => SpinDomain cast.

spin_to_bool(s)

Convert an Ising spin vector s_i in {-1, +1} to Boolean bits x_i in {0, 1} using QUBOTools' SpinDomain => BoolDomain cast.

qubo_to_ising(Q[, l[, c]]; convention = :spin)
qubo_to_ising(form; convention = :spin)

Convert TenSolver's Boolean QUBO objective

dot(x, Q, x) + dot(l, x) + c

with x_i in {0, 1} into a sparse QUBOTools form in SpinDomain. For non-symmetric matrices, the QUBOTools form constructor preserves TenSolver's dot(x, Q, x) convention by storing the effective pair coefficient Q[i, j] + Q[j, i] once in the upper triangle.

The Boolean-to-spin conversion introduces halves and quarters. Integer coefficient inputs therefore return floating-point forms, while rational inputs preserve exact rational arithmetic.

The returned form includes the constant offset, so

dot(x, Q, x) + dot(l, x) + c == QUBOTools.value(bool_to_spin(x), qubo_to_ising(Q, l, c))

for every Boolean vector x.

ising_to_qubo(form)
ising_to_qubo(J, h[, offset])

Convert a QUBOTools spin-domain Ising form back to a sparse Boolean-domain QUBOTools form. The matrix/vector method first builds a QUBOTools spin form from

dot(s, J, s) + dot(h, s) + offset

with s_i in {-1, +1}. QUBOTools folds diagonal quadratic spin terms into the constant offset and stores each off-diagonal unordered pair once in the upper triangle.

As with qubo_to_ising, integer coefficient inputs return floating-point forms when the conversion introduces fractional coefficients, while rational inputs preserve exact rational arithmetic.

in(xs, psi::Solution [; cutoff)

Whether the vector xs has a positive probability of being sampleable from psi. When setting cutoff, it will be used as the minimum probability considered positive.

tensorize(p)

Turn a polynomial function action on bitstrings into an equivalent MPO Hamiltonian acting on Qudit sites. The conversion consists of exchanging each integer variable x_i for a matrix P_i whose eigenvalues represent its feasible set K_i.

∑ Q_ij x_i x_j + ∑ l_i x_i --> H = Σ Q_ij D_i D_j + ∑ l_i D_i

qmatrix_permutation(Q; cutoff=0)

Return a deterministic permutation that places coupled QUBO variables closer together in the one-dimensional MPS ordering.

cutoff controls which quadratic couplings are included in the ordering graph: an undirected edge between variables i and j is used when abs(Q[i, j] + Q[j, i]) > cutoff. The default cutoff = 0 preserves every nonzero coupling for callers that only want the ordering.

The returned permutation maps each tensor site to its original variable index: entry k is the original QUBO variable represented by tensor site k.

Examples

Q = [0.0 0.0 1.0;
     0.0 0.0 0.0;
     1.0 0.0 0.0]

permutation = qmatrix_permutation(Q)
Q[permutation, permutation]

preprocess_qubo(Q, l, cutoff)

Permute QUBO variables before Hamiltonian construction so coupled variables are closer in the one-dimensional tensor order.

Returns (Qp, lp, permutation), where Qp and lp are reordered for tensor-site order and permutation[k] is the caller's original variable index represented by tensor site k.

Standalone qmatrix_permutation uses cutoff = 0 by default so direct callers keep every nonzero coupling. The solve path passes the solver cutoff, which defaults to 1e-8, so numerically tiny couplings are ignored during preprocessing.