API Reference

This page documents the public API of TenSolver.jl.

Optimization Functions

TenSolver.minimize — Function

minimize([Q::Matrix], [l::Vector], [c::Number] ; domain, kwargs...)
minimize(p::AbstractPolynomial ; domain, kwargs...)

Solve a polynomial discrete optimization problem

min  p(x)
s.t. x_i in domain
     constraints

In the matrix version, the objective is limited to quadratic forms x -> x'Qx + l'x + c. Missing arguments (quadratic, linear or constant term) are allowed and taken to be zero.

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

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

Keyword arguments:

constraints :: AbstractVector{<:AbstractConstraint} - Experimental native Julia hard constraints. Defaults to AbstractConstraint[]. In constrained DMRG solves, TenSolver lowers each constraint to a projection MPO, solves the projected Hamiltonian, and returns a feasible sampled assignment. For polynomial objectives, constraints are expressed in the same order as their effective_variables. If the constraints admit no solution at all, the solve does not error: it logs a warning and returns +Inf together with an infeasible Solution (see is_feasible).
domain - Allowed values per variable. Can be either a vector of per-variable domains or a single uniform domain valid for all variables. Defaults to [0, 1]. Unconstrained DMRG optimization accepts any finite collection of real values; individual constraint types can impose narrower requirements. Use [-1, 1] for Ising spins. Domains are sorted and deduplicated before solving.
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.
check_variance_every_iteration :: Int - Calculate and record the Hamiltonian variance every N iterations. Must be >= 1. Defaults to 10.
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.
Some keywords, such as constraints and domain, may have limited support depending on the backend.

The returned Solution carries per-iteration convergence data in solution.stats.

Provably infeasible constrained models are reported as a status: minimize logs a warning and returns +Inf (the minimum over an empty feasible set) together with an infeasible Solution, which cannot be sampled. Check it with is_feasible.

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)

Solver Backends

TenSolver.AbstractTenSolverBackend — Type

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