From f49c7df6bb60758371554fce6dfb3562860a8efb Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Wed, 25 Oct 2023 19:51:28 +0000 Subject: [PATCH] build based on f71c4c2 --- previews/PR44/.documenter-siteinfo.json | 2 +- previews/PR44/api/index.html | 42 +++--- previews/PR44/assets/README/index.html | 2 +- previews/PR44/formats/BQPJSON/index.html | 4 +- previews/PR44/formats/MiniZinc/index.html | 2 +- previews/PR44/formats/QUBO/index.html | 2 +- previews/PR44/formats/QUBin/index.html | 2 +- previews/PR44/formats/Qubist/index.html | 4 +- previews/PR44/index.html | 2 +- previews/PR44/manual/1-start/index.html | 2 +- previews/PR44/manual/2-math/index.html | 2 +- previews/PR44/manual/3-usage/index.html | 2 +- previews/PR44/manual/4-models/index.html | 2 +- previews/PR44/manual/5-formats/index.html | 2 +- previews/PR44/manual/6-solutions/index.html | 2 +- .../7-analysis/{92704c96.svg => 18fe07b8.svg} | 132 +++++++++--------- .../7-analysis/{c50ed3f0.svg => cb34c784.svg} | 86 ++++++------ .../7-analysis/{218ddfe9.svg => e53627cf.svg} | 116 +++++++-------- previews/PR44/manual/7-analysis/index.html | 4 +- 19 files changed, 206 insertions(+), 206 deletions(-) rename previews/PR44/manual/7-analysis/{92704c96.svg => 18fe07b8.svg} (83%) rename previews/PR44/manual/7-analysis/{c50ed3f0.svg => cb34c784.svg} (88%) rename previews/PR44/manual/7-analysis/{218ddfe9.svg => e53627cf.svg} (82%) diff --git a/previews/PR44/.documenter-siteinfo.json b/previews/PR44/.documenter-siteinfo.json index 04d6680..131e93e 100644 --- a/previews/PR44/.documenter-siteinfo.json +++ b/previews/PR44/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-18T21:16:11","documenter_version":"1.1.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-25T19:51:23","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/previews/PR44/api/index.html b/previews/PR44/api/index.html index 185f1d5..d184816 100644 --- a/previews/PR44/api/index.html +++ b/previews/PR44/api/index.html @@ -1,16 +1,16 @@ API Reference · QUBOTools.jl
GitHub

API Reference

Fallback dispatch

When extending QUBOTools, one might want to implement a method for QUBOTools.backend.

QUBOTools.backend — Function
backend(model)::AbstractModel
-backend(model::AbstractModel)::AbstractModel

Accesses the model's backend. Implementing this function allows one to profit from fallback implementations of other methods.

source

Variable System

QUBOTools.index — Function
index(model::AbstractModel{V}, v::V) where {V}

Given a variable, returns the corresponding index.

source
QUBOTools.indices — Function
indices(model)

Returns a sorted vector $[1, \dots, n]$ that matches the variable indices, where $n$ is the model's dimension.

source
QUBOTools.hasindex — Function
hasindex(model::AbstractModel, i::Integer)::Bool

Given an index, returns whether it is valid for rhe model.

source
QUBOTools.variable — Function
variable(model::AbstractModel, i::Integer)

Given an index, returns the corresponding variable.

source
QUBOTools.hasvariable — Function
hasvariable(model::AbstractModel{V}, v::V)::Bool where {V}

Given a variable, tells if it belongs to the model.

source
PseudoBooleanOptimization.varlt — Function
varlt(u::V, v::V) where {V}

Compares two variables, $u$ and $v$, with respect to their length-lexicographic order.

Rationale

This function exists to define an arbitrary ordering for a given type and was created to address [MOI]. There is no predefined comparison between instances MOI's VariableIndex type.

[^MOI]: MathOptInterface Issue [#1985](https://github.com/jump-dev/MathOptInterface.jl/issues/1985)
source

Objective & Domain Frames

QUBOTools.BoolDomain — Constant
BoolDomain

Represents the boolean domain $\mathbb{B} = \lbrace{0, 1}\rbrace$.

Properties

\[x \in \mathbb{B}, n \in \mathbb{N} \implies x^{n} = x\]

source
QUBOTools.SpinDomain — Constant
SpinDomain

Represents the spin domain $\mathbb{S} = \lbrace{-1, 1}\rbrace$.

Properties

\[s \in \mathbb{S}, n \in \mathbb{Z} \implies s^{2n} = 1, s^{2n + 1} = s\]

source
QUBOTools.Sense — Type
Sense

Enum representing the minimization and maximization objective senses, Min and Max.

source
QUBOTools.cast — Function

Recasting the sense of a model preserves its meaning but the linear terms, quadratic terms and constant offset of a model will have its signs reversed, so does the overall objective function.

\[\begin{array}{ll} +backend(model::AbstractModel)::AbstractModel

Accesses the model's backend. Implementing this function allows one to profit from fallback implementations of other methods.

source

Variable System

QUBOTools.index — Function
index(model::AbstractModel{V}, v::V) where {V}

Given a variable, returns the corresponding index.

source
QUBOTools.indices — Function
indices(model)

Returns a sorted vector $[1, \dots, n]$ that matches the variable indices, where $n$ is the model's dimension.

source
QUBOTools.hasindex — Function
hasindex(model::AbstractModel, i::Integer)::Bool

Given an index, returns whether it is valid for rhe model.

source
QUBOTools.variable — Function
variable(model::AbstractModel, i::Integer)

Given an index, returns the corresponding variable.

source
QUBOTools.hasvariable — Function
hasvariable(model::AbstractModel{V}, v::V)::Bool where {V}

Given a variable, tells if it belongs to the model.

source
PseudoBooleanOptimization.varlt — Function
varlt(u::V, v::V) where {V}

Compares two variables, $u$ and $v$, with respect to their length-lexicographic order.

Rationale

This function exists to define an arbitrary ordering for a given type and was created to address [MOI]. There is no predefined comparison between instances MOI's VariableIndex type.

[^MOI]: MathOptInterface Issue [#1985](https://github.com/jump-dev/MathOptInterface.jl/issues/1985)
source

Objective & Domain Frames

QUBOTools.BoolDomain — Constant
BoolDomain

Represents the boolean domain $\mathbb{B} = \lbrace{0, 1}\rbrace$.

Properties

\[x \in \mathbb{B}, n \in \mathbb{N} \implies x^{n} = x\]

source
QUBOTools.SpinDomain — Constant
SpinDomain

Represents the spin domain $\mathbb{S} = \lbrace{-1, 1}\rbrace$.

Properties

\[s \in \mathbb{S}, n \in \mathbb{Z} \implies s^{2n} = 1, s^{2n + 1} = s\]

source
QUBOTools.Sense — Type
Sense

Enum representing the minimization and maximization objective senses, Min and Max.

source
QUBOTools.cast — Function

Recasting the sense of a model preserves its meaning but the linear terms, quadratic terms and constant offset of a model will have its signs reversed, so does the overall objective function.

\[\begin{array}{ll} \min_{s} \alpha [f(s) + \beta] &\equiv \max_{s} -\alpha [f(s) + \beta] \\ &\equiv \max_{s} \alpha [-f(s) - \beta] \\ -\end{array}\]

Warn

Casting to the same (sense, domain) frame is a no-op. That means that no copying will take place automatically, and therefore copy should be called explicitly when necessary.

source

Errors

Models

QUBOTools.Model — Type
Model{V,T,U,F<:AbstractForm{T}} <: AbstractModel{V,T,U}

Reference AbstractModel implementation. It is intended to be the stardard in-memory representation for QUBO models.

MathOptInterface/JuMP Integration

Both V and T parameters exist to support MathOptInterface/JuMP integration. This is made possible by choosing V to match MOI.VariableIndex and T as in Optimizer{T}.

source

Model Forms

QUBOTools.AbstractForm — Type
AbstractForm{T}

A form is a $7$-tuple $(n, \ell, Q, \alpha, \beta) \times (\textrm{sense}, \textrm{domain})$ representing a QUBO / Ising model.

  • $n$, the dimension, is the number of variables.
  • $\mathbf{\ell}$, the linear form, represents a vector storing the linear terms.
  • $\mathbf{Q}$, the quadratic form, represents an upper triangular matrix containing the quadratic interactions.
  • $\alpha$ is the scale factor, defaults to $1$.
  • $\beta$ is the offset factor, defaults to $0$.

The inner data structures used to represent each of these elements may vary.

source
QUBOTools.AbstractLinearForm — Type
AbstractLinearForm{T}

Linear form subtypes will create a wrapper around data structures for representing the linear terms $\mathbf{\ell}'\mathbf{x}$ of the QUBO model.

source
QUBOTools.AbstractQuadraticForm — Type
AbstractQuadraticForm{T}

Quadratic form subtypes will create a wrapper around data structures for representing the quadratic terms $\mathbf{x}'\mathbf{Q}\,\mathbf{x}$ of the QUBO model.

source
QUBOTools.form — Function
form(src [, formtype::Type{<:AbstractForm{T}}]; sense, domain) where {T}
-form(src [, formtype::Union{Symbol,Type}, T::Type = Float64]; sense, domain)

Returns the QUBO form stored within src, casting it to the corresponding (sense, domain) frame and, if necessary, converting the coefficients to type T.

The underlying data structure is given by formtype. Current options include :dict, :dense and :sparse.

For more informaion, see QUBOTools.Form and QUBOTools.AbstractForm.

source

Underlying Data Structures

QUBOTools.formtype — Function
formtype(spec::Type)
-formtype(spec::Symbol)

Returns a form type according to the given specification.

formtype(src)

Returns the form type of a form or model.

source
QUBOTools.DictForm — Type
DictForm{T}

This QUBO form is built using dictionaries for both the linear and quadratic terms.

source
QUBOTools.DenseForm — Type
DenseForm{T}

This QUBO form is built using a vector for the linear terms and a matrix for storing the quadratic terms.

source
QUBOTools.SparseForm — Type
SparseForm{T}

This QUBO form is built using a sparse vector for the linear terms and a sparse matrix for the quadratic ones.

source

Solutions

QUBOTools.AbstractSample — Type
AbstractSample

A sample is a triple $(\psi, \lambda, r)$ where $\psi \in \mathbb{U}^{n} \sim \mathbb{B}^{n}$ is the sampled vector, $\lambda \in \mathbb{R}$ is the associated energy value and $r \in \mathbb{N}$ is the number of reads, i. e., the multiplicity of the sample.

source
QUBOTools.sample — Function
sample(model, i::Integer)

Returns the $i$-th sample on the model's current solution, if available.

source
QUBOTools.hassample — Function
hassample(solution::AbstractSolution, i::Integer)

Tells if the $i$-th sample is available on the solution.

source
QUBOTools.SampleSet — Type
SampleSet{T,U}(
+\end{array}\]
Warn
Casting to the same (sense, domain) frame is a no-op. That means that no copying will take place automatically, and therefore copy should be called explicitly when necessary.
source

Errors

Models

QUBOTools.Model — Type
Model{V,T,U,F<:AbstractForm{T}} <: AbstractModel{V,T,U}

Reference AbstractModel implementation. It is intended to be the stardard in-memory representation for QUBO models.

MathOptInterface/JuMP Integration

Both V and T parameters exist to support MathOptInterface/JuMP integration. This is made possible by choosing V to match MOI.VariableIndex and T as in Optimizer{T}.

source

Model Forms

QUBOTools.AbstractForm — Type
AbstractForm{T}

A form is a $7$-tuple $(n, \ell, Q, \alpha, \beta) \times (\textrm{sense}, \textrm{domain})$ representing a QUBO / Ising model.

  • $n$, the dimension, is the number of variables.
  • $\mathbf{\ell}$, the linear form, represents a vector storing the linear terms.
  • $\mathbf{Q}$, the quadratic form, represents an upper triangular matrix containing the quadratic interactions.
  • $\alpha$ is the scale factor, defaults to $1$.
  • $\beta$ is the offset factor, defaults to $0$.

The inner data structures used to represent each of these elements may vary.

source
QUBOTools.AbstractLinearForm — Type
AbstractLinearForm{T}

Linear form subtypes will create a wrapper around data structures for representing the linear terms $\mathbf{\ell}'\mathbf{x}$ of the QUBO model.

source
QUBOTools.AbstractQuadraticForm — Type
AbstractQuadraticForm{T}

Quadratic form subtypes will create a wrapper around data structures for representing the quadratic terms $\mathbf{x}'\mathbf{Q}\,\mathbf{x}$ of the QUBO model.

source
QUBOTools.form — Function
form(src [, formtype::Type{<:AbstractForm{T}}]; sense, domain) where {T}
+form(src [, formtype::Union{Symbol,Type}, T::Type = Float64]; sense, domain)

Returns the QUBO form stored within src, casting it to the corresponding (sense, domain) frame and, if necessary, converting the coefficients to type T.

The underlying data structure is given by formtype. Current options include :dict, :dense and :sparse.

For more informaion, see QUBOTools.Form and QUBOTools.AbstractForm.

source

Underlying Data Structures

QUBOTools.formtype — Function
formtype(spec::Type)
+formtype(spec::Symbol)

Returns a form type according to the given specification.

formtype(src)

Returns the form type of a form or model.

source
QUBOTools.DictForm — Type
DictForm{T}

This QUBO form is built using dictionaries for both the linear and quadratic terms.

source
QUBOTools.DenseForm — Type
DenseForm{T}

This QUBO form is built using a vector for the linear terms and a matrix for storing the quadratic terms.

source
QUBOTools.SparseForm — Type
SparseForm{T}

This QUBO form is built using a sparse vector for the linear terms and a sparse matrix for the quadratic ones.

source

Solutions

QUBOTools.AbstractSample — Type
AbstractSample

A sample is a triple $(\psi, \lambda, r)$ where $\psi \in \mathbb{U}^{n} \sim \mathbb{B}^{n}$ is the sampled vector, $\lambda \in \mathbb{R}$ is the associated energy value and $r \in \mathbb{N}$ is the number of reads, i. e., the multiplicity of the sample.

source
QUBOTools.sample — Function
sample(model, i::Integer)

Returns the $i$-th sample on the model's current solution, if available.

source
QUBOTools.hassample — Function
hassample(solution::AbstractSolution, i::Integer)

Tells if the $i$-th sample is available on the solution.

source
QUBOTools.SampleSet — Type
SampleSet{T,U}(
     data::Vector{Sample{T,U}},
     metadata::Union{Dict{String,Any},Nothing} = nothing;
     sense::Union{Sense,Symbol}   = :min,
     domain::Union{Domain,Symbol} = :bool,
-) where {T,U}

Reference implementation of QUBOTools.AbstractSolution.

It was inspired by D-Wave's SampleSet[dwave], with a few tweaks. For example, samples are automatically sorted upon instantiation and repeated samples are merged by adding up their reads field. Also, the solution frame is stored, allowing for queries and cast operations.

source
QUBOTools.state — Function
state(sample::AbstractSample{T,U}) where {T,U<:Integer}

Returns a vector containing the assingment of each variable in a sample.

state(model, i::Integer) where {U<:Integer}

Returns a vector corresponding to the bitstring of the $i$-th sample on the model's current solution, if available.

source
QUBOTools.value — Function
value(model)::T where {T}
+) where {T,U}

Reference implementation of QUBOTools.AbstractSolution.

It was inspired by D-Wave's SampleSet[dwave], with a few tweaks. For example, samples are automatically sorted upon instantiation and repeated samples are merged by adding up their reads field. Also, the solution frame is stored, allowing for queries and cast operations.

source
QUBOTools.state — Function
state(sample::AbstractSample{T,U}) where {T,U<:Integer}

Returns a vector containing the assingment of each variable in a sample.

state(model, i::Integer) where {U<:Integer}

Returns a vector corresponding to the bitstring of the $i$-th sample on the model's current solution, if available.

source
QUBOTools.value — Function
value(model)::T where {T}
 
 value(model, i::Integer)::T where {T}
 value(solution::AbstractSolution{T,U}, i::Integer)::T where {T,U}
@@ -19,23 +19,23 @@
 value(solution::AbstractSolution{T,U}, state::AbstractVector{U})::T where {T,U<:Integer}
 
 value(Q::Dict{Tuple{Int,Int},T}, ψ::Vector{U}, α::T = one(T), β::T = zero(T)) where {T}
-value(h::Dict{Int,T}, J::Dict{Tuple{Int,Int},T}, ψ::Vector{U}, α::T = one(T), β::T = zero(T)) where {T}
source
QUBOTools.reads — Function
reads(model)
+value(h::Dict{Int,T}, J::Dict{Tuple{Int,Int},T}, ψ::Vector{U}, α::T = one(T), β::T = zero(T)) where {T}
source
QUBOTools.reads — Function
reads(model)
 reads(solution::AbstractSolution)

Returns the total amount of reads from each sample, combined.

reads(model, i::Integer)
-reads(solution::AbstractSolution, i::Integer)

Returns the sampling frequency of the $i$-th sample on the model's current solution, if available.

source

Solution Errors

Data Access

QUBOTools.linear_terms — Function
linear_terms(model::AbstractModel{V,T,U}) where {V,T,U}

Returns an iterator for the linear nonzero terms of a model as Int => T pairs.

source
QUBOTools.quadratic_terms — Function
quadratic_terms(model::AbstractModel{V,T,U}) where {V,T,U}

Returns an iterator for the quadratic nonzero terms of a model as Tuple{Int,Int} => T pairs.

Info

For every key pair $(i, j)$ we have that $i < j$.

source
QUBOTools.scale — Function
scale(model::AbstractModel)
-scale(model::AbstractForm)

Returns the scaling factor of a model.

source
QUBOTools.offset — Function
offset(model::AbstractModel)
-offset(model::AbstractForm)

Returns the constant offset factor of a model.

source
QUBOTools.data — Function
data(form)
-data(sol::AbstractSolution)

Retrieves the raw data behind solution and form wrappers.

source
QUBOTools.metadata — Function
metadata(model::AbstractModel)
-metadata(sol::AbstractSolution)

Retrieves metadata from a model or solution as a JSON-compatible Dict{String,Any}.

source
QUBOTools.start — Function
start(model::AbstractModel{V,T,U}; domain = domain(model))::Dict{Int,U} where {V,T,U}

Returns a dictionary containing a warm-start value for each variable index.

source
QUBOTools.attach! — Function
attach!(model::AbstractModel{V,T,U}, sol::AbstractSolution{T,U}) where {V,T,U}

Attaches solution to model, replacing existing data and solution metadata. It automatically casts the solution to the model frame upon attachment.

source

File Formats & I/O

QUBOTools.format — Function
format(::AbstractString)::AbstractFormat
+reads(solution::AbstractSolution, i::Integer)

Returns the sampling frequency of the $i$-th sample on the model's current solution, if available.

source

Solution Errors

Data Access

QUBOTools.linear_terms — Function
linear_terms(model::AbstractModel{V,T,U}) where {V,T,U}

Returns an iterator for the linear nonzero terms of a model as Int => T pairs.

source
QUBOTools.quadratic_terms — Function
quadratic_terms(model::AbstractModel{V,T,U}) where {V,T,U}

Returns an iterator for the quadratic nonzero terms of a model as Tuple{Int,Int} => T pairs.

Info

For every key pair $(i, j)$ we have that $i < j$.

source
QUBOTools.scale — Function
scale(model::AbstractModel)
+scale(model::AbstractForm)

Returns the scaling factor of a model.

source
QUBOTools.offset — Function
offset(model::AbstractModel)
+offset(model::AbstractForm)

Returns the constant offset factor of a model.

source
QUBOTools.data — Function
data(form)
+data(sol::AbstractSolution)

Retrieves the raw data behind solution and form wrappers.

source
QUBOTools.metadata — Function
metadata(model::AbstractModel)
+metadata(sol::AbstractSolution)

Retrieves metadata from a model or solution as a JSON-compatible Dict{String,Any}.

source
QUBOTools.start — Function
start(model::AbstractModel{V,T,U}; domain = domain(model))::Dict{Int,U} where {V,T,U}

Returns a dictionary containing a warm-start value for each variable index.

source
QUBOTools.attach! — Function
attach!(model::AbstractModel{V,T,U}, sol::AbstractSolution{T,U}) where {V,T,U}

Attaches solution to model, replacing existing data and solution metadata. It automatically casts the solution to the model frame upon attachment.

source

File Formats & I/O

QUBOTools.format — Function
format(::AbstractString)::AbstractFormat
 format(::Symbol)::AbstractFormat
-format(::Symbol, ::Symbol)::AbstractFormat

Given the file path, tries to infer the type associated to a QUBO model format.

source
QUBOTools.version — Function
version(fmt::AbstractFormat)

Returns the version of a format protocol as a VersionNumber or nothing.

source
QUBOTools.read_model — Function
read_model(::AbstractString)
+format(::Symbol, ::Symbol)::AbstractFormat

Given the file path, tries to infer the type associated to a QUBO model format.

source
QUBOTools.version — Function
version(fmt::AbstractFormat)

Returns the version of a format protocol as a VersionNumber or nothing.

source
QUBOTools.read_model — Function
read_model(::AbstractString)
 read_model(::AbstractString, ::AbstractFormat)
-read_model(::IO, ::AbstractFormat)
source
QUBOTools.write_model — Function
write_model(::AbstractString, ::AbstractModel)
 write_model(::AbstractString, ::AbstractModel, ::AbstractFormat)
-write_model(::IO, ::AbstractModel, ::AbstractFormat)
source
QUBOTools.read_solution — Function
read_solution(::AbstractString)
 read_solution(::AbstractString, ::AbstractFormat)
-read_solution(::IO, ::AbstractFormat)
source
QUBOTools.write_solution — Function
write_solution(::AbstractString, ::AbstractSolution)
 write_solution(::AbstractString, ::AbstractSolution, ::AbstractFormat)
-write_solution(::IO, ::AbstractSolution, ::AbstractFormat)
source

Format & I/O Errors

Model Metrics

QUBOTools.density — Function
density(model)::Float64

Computes the density $\rho$ of non-zero terms in a model, according to the expression[qplib]

\[\rho = \frac{n_{\ell} + 2 n_{q}}{n^{2}}\]

where $n_{\ell}$ is the number of non-zero linear terms, $n_{q}$ the number of quadratic ones and $n$ the number of variables.

If the model is empty, returns NaN.

source
QUBOTools.linear_density — Function
linear_density(model)::Float64

Computes the linear density $\rho_{\ell}$, given by

\[\rho_{\ell} = \frac{n_{\ell}}{n}\]

where $n_{\ell}$ is the number of non-zero linear terms and $n$ the number of variables.

source
QUBOTools.quadratic_density — Function
quadratic_density(model)::Float64

Computes the quadratic density $\rho_{q}$, given by

\[\rho_{q} = \frac{2 n_{q}}{n (n - 1)}\]

where $n_{q}$ is the number of non-zero quadratic terms and $n$ the number of variables.

source
QUBOTools.geometry — Function
geometry

Returns a $n \times N$ matrix describing the placement of the $n$ variable sites in $N$-dimensional space.

source

System Specification

QUBOTools.architecture — Function
architecture(::Any)

It should be defined to provide automatic architecture recognition when writing QUBO Solver interfaces.

Example

struct Solver
+write_solution(::IO, ::AbstractSolution, ::AbstractFormat)
source

Format & I/O Errors

Model Metrics

QUBOTools.density — Function
density(model)::Float64

Computes the density $\rho$ of non-zero terms in a model, according to the expression[qplib]

\[\rho = \frac{n_{\ell} + 2 n_{q}}{n^{2}}\]

where $n_{\ell}$ is the number of non-zero linear terms, $n_{q}$ the number of quadratic ones and $n$ the number of variables.

If the model is empty, returns NaN.

source
QUBOTools.linear_density — Function
linear_density(model)::Float64

Computes the linear density $\rho_{\ell}$, given by

\[\rho_{\ell} = \frac{n_{\ell}}{n}\]

where $n_{\ell}$ is the number of non-zero linear terms and $n$ the number of variables.

source
QUBOTools.quadratic_density — Function
quadratic_density(model)::Float64

Computes the quadratic density $\rho_{q}$, given by

\[\rho_{q} = \frac{2 n_{q}}{n (n - 1)}\]

where $n_{q}$ is the number of non-zero quadratic terms and $n$ the number of variables.

source
QUBOTools.geometry — Function
geometry

Returns a $n \times N$ matrix describing the placement of the $n$ variable sites in $N$-dimensional space.

source

System Specification

QUBOTools.architecture — Function
architecture(::Any)

It should be defined to provide automatic architecture recognition when writing QUBO Solver interfaces.

Example

struct Solver
     ...
 end
 
@@ -43,10 +43,10 @@
     ...
 end
 
-architecture(::Solver) = SolverArchitecture()
source
QUBOTools.AbstractDevice — Type
AbstractDevice{A<:AbstractArchitecture,V,T,U} <: AbstractModel{V,T,U}

A device instance is meant to represent an specific hardware or software device. It is the concrete implementation of an architecture. For example, the topology of a device must be contained within the ideal topology of its architecture.

source
QUBOTools.layout — Function
layout(::Any)
-layout(::Any, ::G) where {G<:AbstractGraph}

Returns the layout of a model, device architecture, i.e., a description of the geometrical placement of each site as long as the network of their connections.

source

Problem Synthesis

QUBOTools.SherringtonKirkpatrick — Type
SherringtonKirkpatrick{T}(n::Integer, μ::T, σ::T)

Generates a Sherrington-Kirkpatrick model in $n$ variables. Coefficients are normally distributed with mean $\mu$ and variance $\sigma$.

source
QUBOTools.Wishart — Type
Wishart{T}(n::Integer, m::Integer)

Represents the Wishart model on $n$ variables whose $\mathbf{W}$ matrix has $m$ columns.

When true, the discretize keyword limits the entries of the $\mathbf{R}$ matrix to $\pm 1$. The precision, on the other hand, is the amount of digits to round each entry $R_{i,j}$ after sampling from a normal distribution $\mathcal{N}(0, 1)$.

source

Solution Metrics

Timing

QUBOTools.total_time — Function
total_time(sol::AbstractSolution)

Retrieves the total time spent during the whole solution gathering process, as experienced by the user.

source
QUBOTools.effective_time — Function
effective_time(sol::AbstractSolution)

Retrieves the time spent by the algorithm in the strict sense, that is, excluding time spent with data access, precompilation and other activities. That said, it is assumed that $t_{\text{effective}} \le t_{\text{total}}$.

source

Solution Quality

QUBOTools.success_rate — Function
success_rate(sol::AbstractSolution{T}, λ::T) where {T}

Returns the success rate according to the given solution and the target objective value $\lambda$.

source

Time-to-Target (TTT)

QUBOTools.time_to_target — Function
time_to_target(sol::AbstractSolution{T}, λ::T, s::Float64=0.99) where {T}

Computes the time-to-target (TTT) given the solution and the target threshold $\lambda$. The success factor $s$ defaults to $0.99$.

time_to_target(t::Float64, p::Float64, s::Float64=0.99)

Computes the time-to-target (TTT) given the effective time $t$ spent running the algorithm and the success probability $p$. The success factor $s$ defaults to $0.99$.

\[\text{ttt}(t, p; s) = t \frac{\log(1 - s)}{\log(1 - p)}\]

source

Hamming Distance

QUBOTools.hamming_distance — Function
hamming_distance(x::Vector{U}, y::Vector{U}) where {U}
-hamming_distance(x::Sample{T,U}, y::Sample{T,U}) where {T,U}
source

Visualization

QUBOTools.AbstractVisualization — Type
AbstractVisualization

Represents a conceptual visualization built from a set of data structures. Its realization may combine multiple plot recipes as well.

Examples

Model Density Heatmap

julia> using Plots
+architecture(::Solver) = SolverArchitecture()
source
QUBOTools.AbstractDevice — Type
AbstractDevice{A<:AbstractArchitecture,V,T,U} <: AbstractModel{V,T,U}

A device instance is meant to represent an specific hardware or software device. It is the concrete implementation of an architecture. For example, the topology of a device must be contained within the ideal topology of its architecture.

source
QUBOTools.layout — Function
layout(::Any)
+layout(::Any, ::G) where {G<:AbstractGraph}

Returns the layout of a model, device architecture, i.e., a description of the geometrical placement of each site as long as the network of their connections.

source

Problem Synthesis

QUBOTools.SherringtonKirkpatrick — Type
SherringtonKirkpatrick{T}(n::Integer, μ::T, σ::T)

Generates a Sherrington-Kirkpatrick model in $n$ variables. Coefficients are normally distributed with mean $\mu$ and variance $\sigma$.

source
QUBOTools.Wishart — Type
Wishart{T}(n::Integer, m::Integer)

Represents the Wishart model on $n$ variables whose $\mathbf{W}$ matrix has $m$ columns.

When true, the discretize keyword limits the entries of the $\mathbf{R}$ matrix to $\pm 1$. The precision, on the other hand, is the amount of digits to round each entry $R_{i,j}$ after sampling from a normal distribution $\mathcal{N}(0, 1)$.

source

Solution Metrics

Timing

QUBOTools.total_time — Function
total_time(sol::AbstractSolution)

Retrieves the total time spent during the whole solution gathering process, as experienced by the user.

source
QUBOTools.effective_time — Function
effective_time(sol::AbstractSolution)

Retrieves the time spent by the algorithm in the strict sense, that is, excluding time spent with data access, precompilation and other activities. That said, it is assumed that $t_{\text{effective}} \le t_{\text{total}}$.

source

Solution Quality

QUBOTools.success_rate — Function
success_rate(sol::AbstractSolution{T}, λ::T) where {T}

Returns the success rate according to the given solution and the target objective value $\lambda$.

source

Time-to-Target (TTT)

QUBOTools.time_to_target — Function
time_to_target(sol::AbstractSolution{T}, λ::T, s::Float64=0.99) where {T}

Computes the time-to-target (TTT) given the solution and the target threshold $\lambda$. The success factor $s$ defaults to $0.99$.

time_to_target(t::Float64, p::Float64, s::Float64=0.99)

Computes the time-to-target (TTT) given the effective time $t$ spent running the algorithm and the success probability $p$. The success factor $s$ defaults to $0.99$.

\[\text{ttt}(t, p; s) = t \frac{\log(1 - s)}{\log(1 - p)}\]

source

Hamming Distance

QUBOTools.hamming_distance — Function
hamming_distance(x::Vector{U}, y::Vector{U}) where {U}
+hamming_distance(x::Sample{T,U}, y::Sample{T,U}) where {T,U}
source

Visualization

QUBOTools.AbstractVisualization — Type
AbstractVisualization

Represents a conceptual visualization built from a set of data structures. Its realization may combine multiple plot recipes as well.

Examples

Model Density Heatmap

julia> using Plots
 
 julia> p = QUBOTools.ModelDensityPlot(model)
 
@@ -60,4 +60,4 @@
 
 julia> p = QUBOTools.EnergyFrequencyPlot(model)
 
-julia> plot(p)
source
+julia> plot(p)source
diff --git a/previews/PR44/assets/README/index.html b/previews/PR44/assets/README/index.html index d44c508..3789f8b 100644 --- a/previews/PR44/assets/README/index.html +++ b/previews/PR44/assets/README/index.html @@ -1,2 +1,2 @@ -QUBOTools.jl's Assets · QUBOTools.jl
GitHub

QUBOTools.jl's Assets

QUBOTools's logo depicts the conversion between binary data and spin states. This represents the available codecs for manipulating Ising and QUBO models.

QUBOTools.jl

Colors

The colors were chosen according to Julia's Reference for logo graphics¹. Text color matches the innermost shape and renders fairly well in both light and dark background themes.

Typography

Arial(#2) Font was used. It was chosen to represent the simplicity of this package.

<a href="#1">¹</a> github.com/JuliaLang/julia-logo-graphics

+QUBOTools.jl's Assets · QUBOTools.jl
GitHub

QUBOTools.jl's Assets

QUBOTools's logo depicts the conversion between binary data and spin states. This represents the available codecs for manipulating Ising and QUBO models.

QUBOTools.jl

Colors

The colors were chosen according to Julia's Reference for logo graphics¹. Text color matches the innermost shape and renders fairly well in both light and dark background themes.

Typography

Arial(#2) Font was used. It was chosen to represent the simplicity of this package.

<a href="#1">¹</a> github.com/JuliaLang/julia-logo-graphics

diff --git a/previews/PR44/formats/BQPJSON/index.html b/previews/PR44/formats/BQPJSON/index.html index 8559b95..b70a7a0 100644 --- a/previews/PR44/formats/BQPJSON/index.html +++ b/previews/PR44/formats/BQPJSON/index.html @@ -1,5 +1,5 @@ -BQPJSON · QUBOTools.jl
GitHub

BQPJSON

Format

Example

{
+BQPJSON · QUBOTools.jl
GitHub
BQPJSON
Format
Example
{
     "id": 2,
     "version": "1.0.0",
     "description": "Simple QUBO Problem",
@@ -78,4 +78,4 @@
             "description": "second solution"
         }
     ]
-}

+}
diff --git a/previews/PR44/formats/MiniZinc/index.html b/previews/PR44/formats/MiniZinc/index.html index 7353ea7..dc5dcf4 100644 --- a/previews/PR44/formats/MiniZinc/index.html +++ b/previews/PR44/formats/MiniZinc/index.html @@ -1,2 +1,2 @@ -MiniZinc · QUBOTools.jl
GitHub
+MiniZinc · QUBOTools.jl
GitHub
diff --git a/previews/PR44/formats/QUBO/index.html b/previews/PR44/formats/QUBO/index.html index e24e360..46a04a0 100644 --- a/previews/PR44/formats/QUBO/index.html +++ b/previews/PR44/formats/QUBO/index.html @@ -1,3 +1,3 @@ QUBO · QUBOTools.jl
GitHub
+QUBO(style::Symbol)source diff --git a/previews/PR44/formats/QUBin/index.html b/previews/PR44/formats/QUBin/index.html index 7879340..f9d856a 100644 --- a/previews/PR44/formats/QUBin/index.html +++ b/previews/PR44/formats/QUBin/index.html @@ -1,2 +1,2 @@ -QUBin · QUBOTools.jl
GitHub
+QUBin · QUBOTools.jl
GitHub
diff --git a/previews/PR44/formats/Qubist/index.html b/previews/PR44/formats/Qubist/index.html index 7600e96..9ef9827 100644 --- a/previews/PR44/formats/Qubist/index.html +++ b/previews/PR44/formats/Qubist/index.html @@ -1,8 +1,8 @@ -Qubist · QUBOTools.jl
GitHub

Qubist

Format

Example

7 2
+Qubist · QUBOTools.jl
GitHub

+2 3 1.0
diff --git a/previews/PR44/index.html b/previews/PR44/index.html index b34b17c..a09ca7f 100644 --- a/previews/PR44/index.html +++ b/previews/PR44/index.html @@ -9,4 +9,4 @@ julia> Pkg.add("QUBOTools") -julia> using QUBOTools

Design Goals

The objective of this package is to provide:

+julia> using QUBOTools

Design Goals

The objective of this package is to provide:

diff --git a/previews/PR44/manual/1-start/index.html b/previews/PR44/manual/1-start/index.html index 42b3bc7..3ddeb33 100644 --- a/previews/PR44/manual/1-start/index.html +++ b/previews/PR44/manual/1-start/index.html @@ -1,2 +1,2 @@ -Introduction · QUBOTools.jl
GitHub
+Introduction · QUBOTools.jl
GitHub
diff --git a/previews/PR44/manual/2-math/index.html b/previews/PR44/manual/2-math/index.html index 64b6df5..c9aa0f7 100644 --- a/previews/PR44/manual/2-math/index.html +++ b/previews/PR44/manual/2-math/index.html @@ -2,4 +2,4 @@ Mathematical Formulation · QUBOTools.jl
GitHub

Mathematical Formulation

This package's mathematical formulation conventions were inspired by BQPJSON's.

\[\min \vert \max f(\mathbf{x}) = \alpha \left[{ \sum_{i < j} Q_{i, j} x_{i} x_{j} + \sum_{i} \ell_{i} x_{i} + \beta }\right]\]

where $\alpha, \beta \in \mathbb{R}$ are the scale and offset parameters. The vector $\mathbf{\ell} \in \mathbb{R}^{n}$ stores the linear terms and $Q \in \mathbb{R}^{n \times n}$, the quadratic interaction matrix, is assumed to be strictly upper triangular.

Info

Internally, any problem loaded with this package will be converted to the normal form presented above.

Info

The scaling factor $\alpha$ must be positive.

Variable Domains

Available domains are represented by the BoolDomain and SpinDomain types, respectively, $x \in \mathbb{B} = \lbrace 0, 1 \rbrace$ and $s \in \mathbb{S} = \lbrace -1, 1 \rbrace$.

Conversion between domains follows the identity:

\[\left\lbrace\begin{align*} s &= 2x - 1 \\ x &= \frac{s + 1}{2} -\end{align*}\right.\]

+\end{align*}\right.\]

diff --git a/previews/PR44/manual/3-usage/index.html b/previews/PR44/manual/3-usage/index.html index a7d388c..fc8a07b 100644 --- a/previews/PR44/manual/3-usage/index.html +++ b/previews/PR44/manual/3-usage/index.html @@ -23,4 +23,4 @@ 2 2 0.4 3 3 -4.4 1 2 -0.8 -1 3 6.0 +1 3 6.0 diff --git a/previews/PR44/manual/4-models/index.html b/previews/PR44/manual/4-models/index.html index a16c924..6aaa852 100644 --- a/previews/PR44/manual/4-models/index.html +++ b/previews/PR44/manual/4-models/index.html @@ -15,4 +15,4 @@ ▷ Domain ……………… BoolDomain The model is empty. -

JuMP Integration

One of the main milestones was to make JuMP / MathOptInterface integration easy. When V is set to MOI.VariableIndex and T matches Optimzer{T}, the QUBOTools backend is able to handle most of the data management workload.

+

JuMP Integration

One of the main milestones was to make JuMP / MathOptInterface integration easy. When V is set to MOI.VariableIndex and T matches Optimzer{T}, the QUBOTools backend is able to handle most of the data management workload.

diff --git a/previews/PR44/manual/5-formats/index.html b/previews/PR44/manual/5-formats/index.html index 74eac01..abb69b1 100644 --- a/previews/PR44/manual/5-formats/index.html +++ b/previews/PR44/manual/5-formats/index.html @@ -27,4 +27,4 @@ else return _read_regular_model(io) end -end
Info

QUBOTools.read_model should return a QUBOTools.Model instance.

+end
Info

QUBOTools.read_model should return a QUBOTools.Model instance.

diff --git a/previews/PR44/manual/6-solutions/index.html b/previews/PR44/manual/6-solutions/index.html index 2c2a45e..0097784 100644 --- a/previews/PR44/manual/6-solutions/index.html +++ b/previews/PR44/manual/6-solutions/index.html @@ -1,2 +1,2 @@ -Solutions · QUBOTools.jl
GitHub

Solutions

A solution, as defined by the QUBOTools.AbstractSolution interface, is an ordered set of samples.

Sample records

A solution instance should contain an array of samples, where each sample is a 3-tuple $(\psi, \lambda, r)$. Moreover, $\psi \in \mathbb{U}^{n} \sim \mathbb{B}^{n}$ is the sampled vector, $\lambda \in \mathbb{R}$ is the associated energy value and $r \in \mathbb{N}$ is the number of reads, i. e., the multiplicity of the sample. Samples should be sorted by increasing values of $\lambda$, then by decreasing the number of reads, and lastly by increasing the lexicographic order of their state vectors.

Reference Implementation

Optimization results and metadata are stored in a specialized data structre, the QUBOTools.SampleSet.

Metadata

The solution metadata should be stored in a JSON-compatible associative map with string keys, such as Dict{String,Any}.

Timing

We define two different time measures to evaluate the solution methods, namely the total time and the effective time. The "time" entry in the solution metadata dictionary is reserved and should be used solely to store the values of these measurements. When present, it must be itself a dictionary with positive numeric values.

Total Time

This measurement accounts for the complete sampling period, including: data manipulation, connection with the solver, problem embedding, solution post-processing, and other related tasks. The "total" entry in the "time" dictionary is reserved for it.

Effective Time

Aimed at recording the time spent exclusively by the solving method, e.g., the actual usage of a Quantum Processing Unit (QPU). It will be stored in the the "effective" entry in the "time" dictionary.

Other Measurements

Solution platforms will commonly provide additional timing information with varying levels of granularity. Besides the "total" and "effective" keys, other fields can be used for solver-specific data without major caveats.

For validation purposes, it is required that the total time is bigger than all other values stored. Since different time records might intersect, there are no restrictions regarding the sum of those.

Origin

When used, the "origin" field is a string referring to the method used for solving the problem, which could be the name of a cloud platform or even hardware identification details.

+Solutions · QUBOTools.jl
GitHub

Solutions

A solution, as defined by the QUBOTools.AbstractSolution interface, is an ordered set of samples.

Sample records

A solution instance should contain an array of samples, where each sample is a 3-tuple $(\psi, \lambda, r)$. Moreover, $\psi \in \mathbb{U}^{n} \sim \mathbb{B}^{n}$ is the sampled vector, $\lambda \in \mathbb{R}$ is the associated energy value and $r \in \mathbb{N}$ is the number of reads, i. e., the multiplicity of the sample. Samples should be sorted by increasing values of $\lambda$, then by decreasing the number of reads, and lastly by increasing the lexicographic order of their state vectors.

Reference Implementation

Optimization results and metadata are stored in a specialized data structre, the QUBOTools.SampleSet.

Metadata

The solution metadata should be stored in a JSON-compatible associative map with string keys, such as Dict{String,Any}.

Timing

We define two different time measures to evaluate the solution methods, namely the total time and the effective time. The "time" entry in the solution metadata dictionary is reserved and should be used solely to store the values of these measurements. When present, it must be itself a dictionary with positive numeric values.

Total Time

This measurement accounts for the complete sampling period, including: data manipulation, connection with the solver, problem embedding, solution post-processing, and other related tasks. The "total" entry in the "time" dictionary is reserved for it.

Effective Time

Aimed at recording the time spent exclusively by the solving method, e.g., the actual usage of a Quantum Processing Unit (QPU). It will be stored in the the "effective" entry in the "time" dictionary.

Other Measurements

Solution platforms will commonly provide additional timing information with varying levels of granularity. Besides the "total" and "effective" keys, other fields can be used for solver-specific data without major caveats.

For validation purposes, it is required that the total time is bigger than all other values stored. Since different time records might intersect, there are no restrictions regarding the sum of those.

Origin

When used, the "origin" field is a string referring to the method used for solving the problem, which could be the name of a cloud platform or even hardware identification details.

diff --git a/previews/PR44/manual/7-analysis/92704c96.svg b/previews/PR44/manual/7-analysis/18fe07b8.svg similarity index 83% rename from previews/PR44/manual/7-analysis/92704c96.svg rename to previews/PR44/manual/7-analysis/18fe07b8.svg index 54601f1..2bda6f3 100644 --- a/previews/PR44/manual/7-analysis/92704c96.svg +++ b/previews/PR44/manual/7-analysis/18fe07b8.svg @@ -1,80 +1,80 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR44/manual/7-analysis/c50ed3f0.svg b/previews/PR44/manual/7-analysis/cb34c784.svg similarity index 88% rename from previews/PR44/manual/7-analysis/c50ed3f0.svg rename to previews/PR44/manual/7-analysis/cb34c784.svg index 41da8aa..483b42a 100644 --- a/previews/PR44/manual/7-analysis/c50ed3f0.svg +++ b/previews/PR44/manual/7-analysis/cb34c784.svg @@ -1,57 +1,57 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - + diff --git a/previews/PR44/manual/7-analysis/218ddfe9.svg b/previews/PR44/manual/7-analysis/e53627cf.svg similarity index 82% rename from previews/PR44/manual/7-analysis/218ddfe9.svg rename to previews/PR44/manual/7-analysis/e53627cf.svg index dba7420..37404e1 100644 --- a/previews/PR44/manual/7-analysis/218ddfe9.svg +++ b/previews/PR44/manual/7-analysis/e53627cf.svg @@ -1,78 +1,78 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + - + diff --git a/previews/PR44/manual/7-analysis/index.html b/previews/PR44/manual/7-analysis/index.html index dd918eb..d80042b 100644 --- a/previews/PR44/manual/7-analysis/index.html +++ b/previews/PR44/manual/7-analysis/index.html @@ -19,7 +19,7 @@ There are no solutions available.

Model Density

using Plots
 
-plot(QUBOTools.ModelDensityPlot(model))
Example block output

System Layout

plot(QUBOTools.SystemLayoutPlot(model))
Example block output

Solutions

solution = magical_solution_method(model)
SampleSet{Float64, Int64} with 12 samples:
+plot(QUBOTools.ModelDensityPlot(model))
Example block output

System Layout

plot(QUBOTools.SystemLayoutPlot(model))
Example block output

Solutions

solution = magical_solution_method(model)
SampleSet{Float64, Int64} with 12 samples:
   Sample{Float64, Int64}([1, 0, 0, 0, 1, 1, 0, 1], -7.935866956098145, 1)
   Sample{Float64, Int64}([1, 0, 0, 1, 0, 0, 0, 1], -4.733655701706034, 1)
   Sample{Float64, Int64}([1, 1, 1, 0, 0, 0, 0, 0], -2.549138683910149, 9)
@@ -32,4 +32,4 @@
   ⋮

Energy Frequency

λ = minimum(QUBOTools.value, solution) # threshold
 
-plot(QUBOTools.EnergyFrequencyPlot(solution, λ))
Example block output +plot(QUBOTools.EnergyFrequencyPlot(solution, λ))Example block output