diff --git a/previews/PR81/.documenter-siteinfo.json b/previews/PR81/.documenter-siteinfo.json index 00a5506..c6d99e8 100644 --- a/previews/PR81/.documenter-siteinfo.json +++ b/previews/PR81/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-11-25T21:48:16","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-11-26T07:28:54","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/previews/PR81/assets/fonts/Sunflower-LICENSE/index.html b/previews/PR81/assets/fonts/Sunflower-LICENSE/index.html index 6449404..b6b8247 100644 --- a/previews/PR81/assets/fonts/Sunflower-LICENSE/index.html +++ b/previews/PR81/assets/fonts/Sunflower-LICENSE/index.html @@ -1,2 +1,2 @@ -Sunflower Font License · ToQUBO.jl
GitHub
+Sunflower Font License · ToQUBO.jl
GitHub
diff --git a/previews/PR81/booklet/1-intro/index.html b/previews/PR81/booklet/1-intro/index.html index a6b498f..7a34025 100644 --- a/previews/PR81/booklet/1-intro/index.html +++ b/previews/PR81/booklet/1-intro/index.html @@ -1,2 +1,2 @@ -Introduction · ToQUBO.jl
GitHub

ToQUBO.jl Booklet

This booklet aims to gather the theoretical and practical details behind ToQUBO and provide documentation for project internals. The target audience includes, among others, advanced users and those willing to contribute to the project. The latter are advised to read the following sections, as they give a glimpse of the ideas employed up to now.

Table of Contents

+Introduction · ToQUBO.jl
GitHub

ToQUBO.jl Booklet

This booklet aims to gather the theoretical and practical details behind ToQUBO and provide documentation for project internals. The target audience includes, among others, advanced users and those willing to contribute to the project. The latter are advised to read the following sections, as they give a glimpse of the ideas employed up to now.

Table of Contents

diff --git a/previews/PR81/booklet/2-qubo/index.html b/previews/PR81/booklet/2-qubo/index.html index 6be1895..bebd314 100644 --- a/previews/PR81/booklet/2-qubo/index.html +++ b/previews/PR81/booklet/2-qubo/index.html @@ -5,4 +5,4 @@ \end{array}\]

where $Q \in \mathbb{R}^{n \times n}$ is symmetric and $\mathbb{B} = \lbrace{0, 1}\rbrace$. Note that, since $x^{2} = x$ holds for $x \in \mathbb{B}$, the linear terms of the objective function are stored in the main diagonal of $Q$.

OK, but why QUBO?

Mathematically speaking, there is a notorious equivalence between QUBO and Max-Cut problems, e.g. for every QUBO instance there is an information preserving Max-Cut reformulation and vice versa. This statement is followed by two immediate implications:

  1. In the general case, solving QUBO globally is NP-Hard.
  2. It is a simple yet expressive mathematical programming framework.

Implication 1. tells us that such problems are computationally intractable and that heuristics and metaheuristics are to be employed instead of exact methods. No 2. relates to the fact that we are able to represent many other optimization models by means of the QUBO formalism.

The Ising Model, on the other hand, is a mathematical abstraction to describe statistical interactions within mechanical systems with interesting properties for encoding combinatorial problems. Its Hamiltonian leads to an optimization formulation in terms of the spin values of their states, given by

\[\begin{array}{rl} \min_{\mathbf{s}} & \mathbf{h}'\mathbf{s} + \mathbf{s}' J\,\mathbf{s} \\ \textrm{s.t.} & \mathbf{s} \in \lbrace{-1,+1}\rbrace^{n} -\end{array}\]

with strictly upper triangular $J \in \mathbb{R}^{n \times n}$ and $\mathbf{h} \in \mathbb{R}$.

D-Wave Washington 1000Q

The Ising reformulation alternative draws the bridge between QUBO problems and devices designed to sample global or approximate ground states of the Ising Hamiltonian with high probability[Mohseni2022]. Some of the paradigms that stand out in this context are quantum gate-based optimization algorithms (QAOA and VQE), quantum annealers, hardware-accelerated platforms (Coherent Ising Machines and Simulated Bifurcation Machines) and physics-inspired methods (Simulated Annealing, Parallel Tempering). The significant advances in these computing systems contributed to the growing popularity of the model across the literature.

+\end{array}\]

with strictly upper triangular $J \in \mathbb{R}^{n \times n}$ and $\mathbf{h} \in \mathbb{R}$.

D-Wave Washington 1000Q

The Ising reformulation alternative draws the bridge between QUBO problems and devices designed to sample global or approximate ground states of the Ising Hamiltonian with high probability[Mohseni2022]. Some of the paradigms that stand out in this context are quantum gate-based optimization algorithms (QAOA and VQE), quantum annealers, hardware-accelerated platforms (Coherent Ising Machines and Simulated Bifurcation Machines) and physics-inspired methods (Simulated Annealing, Parallel Tempering). The significant advances in these computing systems contributed to the growing popularity of the model across the literature.

diff --git a/previews/PR81/booklet/3-pbo/index.html b/previews/PR81/booklet/3-pbo/index.html index c7754fe..bcced5c 100644 --- a/previews/PR81/booklet/3-pbo/index.html +++ b/previews/PR81/booklet/3-pbo/index.html @@ -1,2 +1,2 @@ -PBO · ToQUBO.jl
GitHub

Pseudo-Boolean Optimization

Internally, problems are represented through a Pseudo-Boolean Optimization (PBO) framework. The main goal is to represent a given problem using a Pseudo-Boolean Function (PBF) since there is an immediate correspondence between optimization over quadratic PBFs and the QUBO formalism.

Quadratization

In order to successfully achieve a QUBO formulation, sometimes it is needed to quadratize the resulting PBF, i.e., reduce its degree until reaching the quadratic case.

A quadratization is a mapping $\mathcal{Q}: \mathscr{F} \to \mathscr{F}^{2}$ such that

\[\forall f \in \mathscr{F}, \forall x \in \{0, 1\}^{n}, \min_{y} \mathcal{Q}\left\lbrace{}f\right\rbrace{}(x; y) = f(x)\]

There are many quadratization methods available[Dattani2019], and ToQUBO implements two of them for now. However, using Julia's multiple dispatch paradigm, it's possible to extend the quadratization method coverage with your own algorithms.

Quadratization Methods

Stable Quadratization

The quadratization of a PBF does not guarantee that the resulting function will always be the same, as the order of terms can be different each time. This can be an issue in some situations where a deterministic output is required.

With said that, we have introduced the concept of Stable Quadratization, where the terms of the PBF are sorted, guaranteeing that the resulting PBF will be the same every time. We have defined it as an attribute of the compiler, with the ToQUBO.Attributes.StableQuadratization flag.

  • Dattani2019Nikesh S. Dattani, Quadratization in discrete optimization and quantum mechanics, ArXiv, 2019 {doi}
+PBO · ToQUBO.jl
GitHub

Pseudo-Boolean Optimization

Internally, problems are represented through a Pseudo-Boolean Optimization (PBO) framework. The main goal is to represent a given problem using a Pseudo-Boolean Function (PBF) since there is an immediate correspondence between optimization over quadratic PBFs and the QUBO formalism.

Quadratization

In order to successfully achieve a QUBO formulation, sometimes it is needed to quadratize the resulting PBF, i.e., reduce its degree until reaching the quadratic case.

A quadratization is a mapping $\mathcal{Q}: \mathscr{F} \to \mathscr{F}^{2}$ such that

\[\forall f \in \mathscr{F}, \forall x \in \{0, 1\}^{n}, \min_{y} \mathcal{Q}\left\lbrace{}f\right\rbrace{}(x; y) = f(x)\]

There are many quadratization methods available[Dattani2019], and ToQUBO implements two of them for now. However, using Julia's multiple dispatch paradigm, it's possible to extend the quadratization method coverage with your own algorithms.

Quadratization Methods

Stable Quadratization

The quadratization of a PBF does not guarantee that the resulting function will always be the same, as the order of terms can be different each time. This can be an issue in some situations where a deterministic output is required.

With said that, we have introduced the concept of Stable Quadratization, where the terms of the PBF are sorted, guaranteeing that the resulting PBF will be the same every time. We have defined it as an attribute of the compiler, with the ToQUBO.Attributes.StableQuadratization flag.

  • Dattani2019Nikesh S. Dattani, Quadratization in discrete optimization and quantum mechanics, ArXiv, 2019 {doi}
diff --git a/previews/PR81/booklet/4-encoding/index.html b/previews/PR81/booklet/4-encoding/index.html index 499e6d9..eba4cd3 100644 --- a/previews/PR81/booklet/4-encoding/index.html +++ b/previews/PR81/booklet/4-encoding/index.html @@ -1,5 +1,5 @@ -Encoding · ToQUBO.jl
GitHub

Encoding Methods

Variables

As you may already know, QUBO models are comprised only of binary variables. So when we are reformulating general optimization problems, one important step is to encode variables into binary ones.

ToQUBO currently implements 6 encoding techniques. Each method introduces a different number of variables, quadratic terms and linear terms. Also, they differ in the magnitude of their coefficients $\Delta$.

EncodingBinary Variables# Linear terms# Quadratic terms$\Delta$
Binary$O(\log n)$$O(\log n)$-$O(n)$
Unary$O(n)$$O(n)$-$O(1)$
One-Hot$O(n)$$O(n)$$O(n^2)$$O(n)$
Domain-Wall$O(n)$$O(n)$$O(n)$$O(n)$
Bounded-Coefficient$O(n)$$O(n)$-$O(1)$
Arithmetic Prog$O(\sqrt{n})$$O(\sqrt{n})$-$O(\sqrt{n})$

Mirror Encoding

Interval Encoding

ToQUBO.Encoding.Unary — Type
Unary{T}()

Integer

Let $x \in [a, b] \subset \mathbb{Z}$, $n = b - a$ and $\mathbf{y} \in \mathbb{B}^{n}$.

\[\xi{[a, b]}(\mathbf{y}) = a + \sum_{j = 1}^{b - a} y_{j}\]

Real

Given $n \in \mathbb{N}$ for $x \in [a, b] \subset \mathbb{R}$,

\[\xi{[a, b]}(\mathbf{y}) = a + \frac{b - a}{n} \sum_{j = 1}^{n} y_{j}\]

Representation error

Given $\tau > 0$, for the expected encoding error to be less than or equal to $\tau$, at least

\[n \ge 1 + \frac{b - a}{4 \tau}\]

binary variables become necessary.

source
ToQUBO.Encoding.Binary — Type
Binary{T}()

Integer

Let $x \in [a, b] \subset \mathbb{Z}$, $n = \left\lceil \log_{2}(b - a) + 1 \right\rceil$ and $\mathbf{y} \in \mathbb{B}^{n}$.

\[\xi{[a, b]}(\mathbf{y}) = a + \left(b - a - 2^{n - 1} + 1\right) y_{n} + \sum_{j = 1}^{n - 1} 2^{j - 1} y_{j}\]

Real

Given $n \in \mathbb{N}$ for $x \in [a, b] \subset \mathbb{R}$,

\[\xi{[a, b]}(\mathbf{y}) = a + \frac{b - a}{2^{n} - 1} \sum_{j = 1}^{n} 2^{j - 1} y_{j}\]

Representation error

Given $\tau > 0$, for the expected encoding error to be less than or equal to $\tau$, at least

\[n \ge \log_{2} \left[1 + \frac{b - a}{4 \tau}\right]\]

binary variables become necessary.

source
ToQUBO.Encoding.Arithmetic — Type
Arithmetic{T}()

Integer

Let $x \in [a, b] \subset \mathbb{Z}$, $n = \left\lceil{ \frac{1}{2} {\sqrt{1 + 8 (b - a)}} - \frac{1}{2} }\right\rceil$ and $\mathbf{y} \in \mathbb{B}^{n}$.

\[\xi{[a, b]}(\mathbf{y}) = a + \left( {b - a - \frac{n (n - 1)}{2}} \right) y_{n} + \sum_{j = 1}^{n - 1} j y_{j}\]

Real

Given $n \in \mathbb{N}$ for $x \in [a, b] \subset \mathbb{R}$,

\[\xi{[a, b]}(\mathbf{y}) = a + \frac{b - a}{n (n + 1)} \sum_{j = 1}^{n} j y_{j}\]

Representation error

Given $\tau > 0$, for the expected encoding error to be less than or equal to $\tau$, at least

\[n \ge \frac{1}{2} \left[ 1 + \sqrt{3 + \frac{(b - a)}{2 \tau})} \right]\]

source

Bounded Coefficients

ToQUBO.Encoding.Bounded — Type
Bounded{E,T}(μ::T) where {E<:Encoding,T}

The bounded-coefficient encoding method[Karimi2019] consists in limiting the magnitude of the coefficients in the encoding expansion to a parameter $\mu$. This can be applied to the Unary, Binary and Arithmetic encoding methods.

Let $\xi[a, b] : \mathbb{B}^{n} \to [a, b]$ be an encoding function over the closed interval $[a, b]$. The bounded-coefficient encoding function given $\mu$ is defined as

\[\xi_{\mu}[a, b] = \xi[0, \delta](y_{1}, \dots, y_{k}) + \sum_{j = k + 1}^{r} \mu y{j}\]

```

source

Arbitrary Set Encoding

ToQUBO.Encoding.OneHot — Type
OneHot{T}()

The one-hot encoding is a linear technique used to represent a variable $x \in \set{\gamma_{j}}_{j \in [n]}$.

The associated encoding function is combined with a constraint assuring that only one and exactly one of the expansion's variables $y_{j}$ is activated at a time.

\[\xi[\set{\gamma_{j}}_{j \in [n]}](\mathbf{y}) = \sum_{j = 1}^{n} \gamma_{j} y_{j} ~\textrm{s.t.}~ \sum_{j = 1}^{n} y_{j} = 1\]

When a variable is encoded following this approach, a penalty term of the form

\[\rho \left[ \sum_{j = 1}^{n} y_{j} - 1 \right]^{2}\]

is added to the objective function.

source
ToQUBO.Encoding.DomainWall — Type
DomainWall{T}()

The Domain Wall[Chancellor2019] encoding method is a sequential approach that requires $n - 1$ bits to represent $n$ distinct values.

\[\xi{[\set{\gamma_{j}}_{j \in [n]}]}(\mathbf{y}) = \sum_{j = 1}^{n} \gamma_{j} (y_{j} - y_{j + 1}) ~\textrm{s.t.}~ \sum_{j = 1}^{n} y_{j} \oplus y_{j + 1} = 1, y_{1} = 1, y_{n + 1} = 0\]

where $\mathbf{y} \in \mathbb{B}^{n + 1}$.

source

Representation Error

Let $\set{x_{i}}_{i \in [k]}$ be the collection of $k$ evenly spaced samples from the discretization of an interval $[a, b] \subseteq \mathbb{R}$.

The representation error for a given point $x$ with respect to $\set{x_{i}}_{i \in [k]}$ is

\[e_{k}(x) = \min_{i \in [k]} \left|x - x_{i}\right|\]

Assuming that $x$ behaves as a uniformly distributed random variable, the expected absolute encoding error is

\[\begin{align*} +Encoding · ToQUBO.jl

GitHub

Encoding Methods

Variables

As you may already know, QUBO models are comprised only of binary variables. So when we are reformulating general optimization problems, one important step is to encode variables into binary ones.

ToQUBO currently implements 6 encoding techniques. Each method introduces a different number of variables, quadratic terms and linear terms. Also, they differ in the magnitude of their coefficients $\Delta$.

EncodingBinary Variables# Linear terms# Quadratic terms$\Delta$
Binary$O(\log n)$$O(\log n)$-$O(n)$
Unary$O(n)$$O(n)$-$O(1)$
One-Hot$O(n)$$O(n)$$O(n^2)$$O(n)$
Domain-Wall$O(n)$$O(n)$$O(n)$$O(n)$
Bounded-Coefficient$O(n)$$O(n)$-$O(1)$
Arithmetic Prog$O(\sqrt{n})$$O(\sqrt{n})$-$O(\sqrt{n})$

Mirror Encoding

Interval Encoding

ToQUBO.Encoding.Unary — Type
Unary{T}()

Integer

Let $x \in [a, b] \subset \mathbb{Z}$, $n = b - a$ and $\mathbf{y} \in \mathbb{B}^{n}$.

\[\xi{[a, b]}(\mathbf{y}) = a + \sum_{j = 1}^{b - a} y_{j}\]

Real

Given $n \in \mathbb{N}$ for $x \in [a, b] \subset \mathbb{R}$,

\[\xi{[a, b]}(\mathbf{y}) = a + \frac{b - a}{n} \sum_{j = 1}^{n} y_{j}\]

Representation error

Given $\tau > 0$, for the expected encoding error to be less than or equal to $\tau$, at least

\[n \ge 1 + \frac{b - a}{4 \tau}\]

binary variables become necessary.

source
ToQUBO.Encoding.Binary — Type
Binary{T}()

Integer

Let $x \in [a, b] \subset \mathbb{Z}$, $n = \left\lceil \log_{2}(b - a) + 1 \right\rceil$ and $\mathbf{y} \in \mathbb{B}^{n}$.

\[\xi{[a, b]}(\mathbf{y}) = a + \left(b - a - 2^{n - 1} + 1\right) y_{n} + \sum_{j = 1}^{n - 1} 2^{j - 1} y_{j}\]

Real

Given $n \in \mathbb{N}$ for $x \in [a, b] \subset \mathbb{R}$,

\[\xi{[a, b]}(\mathbf{y}) = a + \frac{b - a}{2^{n} - 1} \sum_{j = 1}^{n} 2^{j - 1} y_{j}\]

Representation error

Given $\tau > 0$, for the expected encoding error to be less than or equal to $\tau$, at least

\[n \ge \log_{2} \left[1 + \frac{b - a}{4 \tau}\right]\]

binary variables become necessary.

source
ToQUBO.Encoding.Arithmetic — Type
Arithmetic{T}()

Integer

Let $x \in [a, b] \subset \mathbb{Z}$, $n = \left\lceil{ \frac{1}{2} {\sqrt{1 + 8 (b - a)}} - \frac{1}{2} }\right\rceil$ and $\mathbf{y} \in \mathbb{B}^{n}$.

\[\xi{[a, b]}(\mathbf{y}) = a + \left( {b - a - \frac{n (n - 1)}{2}} \right) y_{n} + \sum_{j = 1}^{n - 1} j y_{j}\]

Real

Given $n \in \mathbb{N}$ for $x \in [a, b] \subset \mathbb{R}$,

\[\xi{[a, b]}(\mathbf{y}) = a + \frac{b - a}{n (n + 1)} \sum_{j = 1}^{n} j y_{j}\]

Representation error

Given $\tau > 0$, for the expected encoding error to be less than or equal to $\tau$, at least

\[n \ge \frac{1}{2} \left[ 1 + \sqrt{3 + \frac{(b - a)}{2 \tau})} \right]\]

source

Bounded Coefficients

ToQUBO.Encoding.Bounded — Type
Bounded{E,T}(μ::T) where {E<:Encoding,T}

The bounded-coefficient encoding method[Karimi2019] consists in limiting the magnitude of the coefficients in the encoding expansion to a parameter $\mu$. This can be applied to the Unary, Binary and Arithmetic encoding methods.

Let $\xi[a, b] : \mathbb{B}^{n} \to [a, b]$ be an encoding function over the closed interval $[a, b]$. The bounded-coefficient encoding function given $\mu$ is defined as

\[\xi_{\mu}[a, b] = \xi[0, \delta](y_{1}, \dots, y_{k}) + \sum_{j = k + 1}^{r} \mu y{j}\]

```

source

Arbitrary Set Encoding

ToQUBO.Encoding.OneHot — Type
OneHot{T}()

The one-hot encoding is a linear technique used to represent a variable $x \in \set{\gamma_{j}}_{j \in [n]}$.

The associated encoding function is combined with a constraint assuring that only one and exactly one of the expansion's variables $y_{j}$ is activated at a time.

\[\xi[\set{\gamma_{j}}_{j \in [n]}](\mathbf{y}) = \sum_{j = 1}^{n} \gamma_{j} y_{j} ~\textrm{s.t.}~ \sum_{j = 1}^{n} y_{j} = 1\]

When a variable is encoded following this approach, a penalty term of the form

\[\rho \left[ \sum_{j = 1}^{n} y_{j} - 1 \right]^{2}\]

is added to the objective function.

source
ToQUBO.Encoding.DomainWall — Type
DomainWall{T}()

The Domain Wall[Chancellor2019] encoding method is a sequential approach that requires $n - 1$ bits to represent $n$ distinct values.

\[\xi{[\set{\gamma_{j}}_{j \in [n]}]}(\mathbf{y}) = \sum_{j = 1}^{n} \gamma_{j} (y_{j} - y_{j + 1}) ~\textrm{s.t.}~ \sum_{j = 1}^{n} y_{j} \oplus y_{j + 1} = 1, y_{1} = 1, y_{n + 1} = 0\]

where $\mathbf{y} \in \mathbb{B}^{n + 1}$.

source

Representation Error

Let $\set{x_{i}}_{i \in [k]}$ be the collection of $k$ evenly spaced samples from the discretization of an interval $[a, b] \subseteq \mathbb{R}$.

The representation error for a given point $x$ with respect to $\set{x_{i}}_{i \in [k]}$ is

\[e_{k}(x) = \min_{i \in [k]} \left|x - x_{i}\right|\]

Assuming that $x$ behaves as a uniformly distributed random variable, the expected absolute encoding error is

\[\begin{align*} \mathbb{E}\left[{e_{k}(x)}\right] &= \frac{1}{b - a} \int_{a}^{b} e_{k}(x) ~\mathrm{d}x \\ &= \frac{1}{4} \frac{b - a}{k - 1} -\end{align*}\]

Thus, for encoding methods that rely on the regular division of an interval, it is possible to define the number of samples $k$ necessary to limit the expected error according to an upper bound $\tau$, that is,

\[\mathbb{E}\left[{e_{k}(x)}\right] \le \tau \implies k \ge 1 + \frac{b - a}{4 \tau}\]

This allows the compiler to automatically infer the number of bits to allocate for an encoded variable given the tolerance factor.

Constraints

A QUBO model is unconstrained. So when ToQUBO is reformulating a problem, it needs to encode all constraints into the objective function losing as little information as possible.

As constraints are introduced into the objective function, we need to make sure that they won't be violated. In order to do that, ToQUBO multiplies the encoded constraint by a large penalty $\rho$, so that any violation would result in a sub-optimal solution to the problem.

Sometimes, the encoding process might introduce higher-order terms, demanding ToQUBO to reduce the offending polynomials back to a quadratic form.

  • Karimi2019Karimi, S. & Ronagh, P. Practical integer-to-binary mapping for quantum annealers. Quantum Inf Process 18, 94 (2019). {doi}
  • Chancellor2019Nicholas Chancellor, Domain wall encoding of discrete variables for quantum annealing and QAOA, Quantum Science Technology 4, 2019.
+\end{align*}\]

Thus, for encoding methods that rely on the regular division of an interval, it is possible to define the number of samples $k$ necessary to limit the expected error according to an upper bound $\tau$, that is,

\[\mathbb{E}\left[{e_{k}(x)}\right] \le \tau \implies k \ge 1 + \frac{b - a}{4 \tau}\]

This allows the compiler to automatically infer the number of bits to allocate for an encoded variable given the tolerance factor.

Constraints

A QUBO model is unconstrained. So when ToQUBO is reformulating a problem, it needs to encode all constraints into the objective function losing as little information as possible.

As constraints are introduced into the objective function, we need to make sure that they won't be violated. In order to do that, ToQUBO multiplies the encoded constraint by a large penalty $\rho$, so that any violation would result in a sub-optimal solution to the problem.

Sometimes, the encoding process might introduce higher-order terms, demanding ToQUBO to reduce the offending polynomials back to a quadratic form.

  • Karimi2019Karimi, S. & Ronagh, P. Practical integer-to-binary mapping for quantum annealers. Quantum Inf Process 18, 94 (2019). {doi}
  • Chancellor2019Nicholas Chancellor, Domain wall encoding of discrete variables for quantum annealing and QAOA, Quantum Science Technology 4, 2019.
diff --git a/previews/PR81/booklet/5-virtual/index.html b/previews/PR81/booklet/5-virtual/index.html index 1084c3e..85a4867 100644 --- a/previews/PR81/booklet/5-virtual/index.html +++ b/previews/PR81/booklet/5-virtual/index.html @@ -1,2 +1,2 @@ -Virtual Mapping · ToQUBO.jl
GitHub

Virtual Mapping

During reformulation, ToQUBO holds two distinct models, namely the Source Model and the Target Model. The source model is a generic MOI model restricted to the supported constraints. The target one is on the QUBO form used during the solving process. Both lie within a Virtual Model, which provides the necessary API integration and keeps all variable and constraint mapping tied together.

This is done in a transparent fashion for both agents since the user will mostly interact with the presented model, and the solvers will only access the generated one.

Virtual Model

ToQUBO.Virtual.Model — Type
Model{T}(optimizer::Union{Nothing, Type{<:MOI.AbstractOptimizer}} = nothing) where {T}

This Virtual Model links the final QUBO formulation to the original one, allowing variable value retrieving and other features.

source

Virtual Variables

Every virtual model stores a collection of virtual variables, intended to provide a link between those in the source and those to be created in the target model. Each virtual variable stores encoding information for later expansion and evaluation.

+Virtual Mapping · ToQUBO.jl
GitHub

Virtual Mapping

During reformulation, ToQUBO holds two distinct models, namely the Source Model and the Target Model. The source model is a generic MOI model restricted to the supported constraints. The target one is on the QUBO form used during the solving process. Both lie within a Virtual Model, which provides the necessary API integration and keeps all variable and constraint mapping tied together.

This is done in a transparent fashion for both agents since the user will mostly interact with the presented model, and the solvers will only access the generated one.

Virtual Model

ToQUBO.Virtual.Model — Type
Model{T}(optimizer::Union{Nothing, Type{<:MOI.AbstractOptimizer}} = nothing) where {T}

This Virtual Model links the final QUBO formulation to the original one, allowing variable value retrieving and other features.

source

Virtual Variables

Every virtual model stores a collection of virtual variables, intended to provide a link between those in the source and those to be created in the target model. Each virtual variable stores encoding information for later expansion and evaluation.

diff --git a/previews/PR81/booklet/6-compiler/index.html b/previews/PR81/booklet/6-compiler/index.html index 152fdc5..65e6e56 100644 --- a/previews/PR81/booklet/6-compiler/index.html +++ b/previews/PR81/booklet/6-compiler/index.html @@ -1,7 +1,7 @@ -The Compiler · ToQUBO.jl
GitHub

The Compiler

Work in progress

We hope to write this part of the documentation soon. Please come back later!

Compilation Steps

Setup

Parsing

ToQUBO.Compiler.parse! — Function
parse!(
+The Compiler · ToQUBO.jl
GitHub
The Compiler
Work in progress
We hope to write this part of the documentation soon. Please come back later!
Compilation Steps
Setup
Parsing
ToQUBO.Compiler.parse! — Function
parse!(
     model::Virtual.Model{T},
     g::PBO.PBF{VI,T},
     f::MOI.AbstractFunction,
     arch::AbstractArchitecture
-) where {T}
Parses the given MOI function f into PBF g.
source
Reformulation
ToQUBO.Compiler.sense! — Function
sense!(model::Virtual.Model, ::AbstractArchitecture)
Copies MOI.ObjectiveSense from model.source_model to model.target_model.
source
Copying
ToQUBO.Compiler.isqubo — Function
isqubo(model::MOI.ModelLike)
Tells if a given model is ready to be interpreted as a QUBO model.
For it to be true, a few conditions must be met:
  1. All variables must be binary (MOI.VariableIndex ∈ MOI.ZeroOne)
  2. No other constraints are allowed
  3. The objective function must be of type MOI.ScalarQuadraticFunction, MOI.ScalarAffineFunction or MOI.VariableIndex
  4. The objective sense must be either MOI.MIN_SENSE or MOI.MAX_SENSE
source
Hamiltonian Assembly

+) where {T}

Parses the given MOI function f into PBF g.

source

Reformulation

ToQUBO.Compiler.sense! — Function
sense!(model::Virtual.Model, ::AbstractArchitecture)

Copies MOI.ObjectiveSense from model.source_model to model.target_model.

source

Copying

ToQUBO.Compiler.isqubo — Function
isqubo(model::MOI.ModelLike)

Tells if a given model is ready to be interpreted as a QUBO model.

For it to be true, a few conditions must be met:

  1. All variables must be binary (MOI.VariableIndex ∈ MOI.ZeroOne)
  2. No other constraints are allowed
  3. The objective function must be of type MOI.ScalarQuadraticFunction, MOI.ScalarAffineFunction or MOI.VariableIndex
  4. The objective sense must be either MOI.MIN_SENSE or MOI.MAX_SENSE
source

Hamiltonian Assembly

diff --git a/previews/PR81/booklet/7-solvers/index.html b/previews/PR81/booklet/7-solvers/index.html index b991917..7c8fa4a 100644 --- a/previews/PR81/booklet/7-solvers/index.html +++ b/previews/PR81/booklet/7-solvers/index.html @@ -1,2 +1,2 @@ -Solvers · ToQUBO.jl
GitHub

QUBO Solvers

Solvers, Annealers & Samplers

ToQUBO.jl's main goal is to make use of parameterized stochastic optimization solvers, particularly those relying on non-conventional hardware such as Quantum Annealing and other Ising Machines. A few MOI-compliant interfaces for annealers and samplers are bundled within ToQUBO.jl via the QUBODrivers.jl companion package. Some of them are presented below.

Simulated Annealing

Provided by D-Wave's open-source code libraries, this Simulated Annealing engine implements some of the features and configurations you would find using the Quantum API. Its adoption is recommended for basic usage, tests, and research due to its robustness, simplicity and ease of use. The DWave.jl's DWave.Neal module uses QUBODrivers.jl to deliver an interface to this sampler.

Quantum Annealing

Interfacing with D-Wave's quantum annealer is one of the milestones we expect to achieve with this package. Like other proprietary optimization resources such as Gurobi, FICO® Xpress and IBM® CPLEX®, this requires licensing and extra steps are needed to get an access token. In a first moment, for those willing to get started, the DWave.Neal optimizer might be enough to learn the ropes.

Random Sampling

This sampler is implemented for test purposes and simply assigns 0 or 1 to each variable according to a given probability bias $0 \le p \le 1$, which defaults to $p = 0.5$. After running the using QUBODrivers command, RandomSampler.Optimizer will be available.

Exact Solver (Exhaustive Enumeration)

Also made to be used in tests, the ExactSolver.Optimizer interface runs through all possible state configurations, which implies in an exponential time complexity on the number of variables. Thus, only problems with at most $\approxeq 20$ variables should be provided since visiting $2^{20} \approxeq 10^{6}$ states can already take up to a few seconds.

Mixed-Integer Quadratic Programming

The most accessible alternative to the forementioned methods are Mixed-Integer Quadratic Programming (MIQP) solvers such as Gurobi, CPLEX, SCIP and BARON. These are not intended to be of regular use alongside ToQUBO.jl since providing a QUBO reformulation will usually make things harder for non-specialized solvers. Yet, there are still a few cases where they may be suitable, such as tests, benchmarks, or any other situation where global optimality is a must.

+Solvers · ToQUBO.jl
GitHub

QUBO Solvers

Solvers, Annealers & Samplers

ToQUBO.jl's main goal is to make use of parameterized stochastic optimization solvers, particularly those relying on non-conventional hardware such as Quantum Annealing and other Ising Machines. A few MOI-compliant interfaces for annealers and samplers are bundled within ToQUBO.jl via the QUBODrivers.jl companion package. Some of them are presented below.

Simulated Annealing

Provided by D-Wave's open-source code libraries, this Simulated Annealing engine implements some of the features and configurations you would find using the Quantum API. Its adoption is recommended for basic usage, tests, and research due to its robustness, simplicity and ease of use. The DWave.jl's DWave.Neal module uses QUBODrivers.jl to deliver an interface to this sampler.

Quantum Annealing

Interfacing with D-Wave's quantum annealer is one of the milestones we expect to achieve with this package. Like other proprietary optimization resources such as Gurobi, FICO® Xpress and IBM® CPLEX®, this requires licensing and extra steps are needed to get an access token. In a first moment, for those willing to get started, the DWave.Neal optimizer might be enough to learn the ropes.

Random Sampling

This sampler is implemented for test purposes and simply assigns 0 or 1 to each variable according to a given probability bias $0 \le p \le 1$, which defaults to $p = 0.5$. After running the using QUBODrivers command, RandomSampler.Optimizer will be available.

Exact Solver (Exhaustive Enumeration)

Also made to be used in tests, the ExactSolver.Optimizer interface runs through all possible state configurations, which implies in an exponential time complexity on the number of variables. Thus, only problems with at most $\approxeq 20$ variables should be provided since visiting $2^{20} \approxeq 10^{6}$ states can already take up to a few seconds.

Mixed-Integer Quadratic Programming

The most accessible alternative to the forementioned methods are Mixed-Integer Quadratic Programming (MIQP) solvers such as Gurobi, CPLEX, SCIP and BARON. These are not intended to be of regular use alongside ToQUBO.jl since providing a QUBO reformulation will usually make things harder for non-specialized solvers. Yet, there are still a few cases where they may be suitable, such as tests, benchmarks, or any other situation where global optimality is a must.

diff --git a/previews/PR81/booklet/8-appendix/index.html b/previews/PR81/booklet/8-appendix/index.html index 0a72097..0dc1c7a 100644 --- a/previews/PR81/booklet/8-appendix/index.html +++ b/previews/PR81/booklet/8-appendix/index.html @@ -1,2 +1,2 @@ -Appendix · ToQUBO.jl
GitHub

Appendix

ToQUBO.jl's Assets

The ideia behind ToQUBO.jl's logo comes from a wordplay in Portuguese and Spanish. The package's main purpose is to assemble QUBO Models, which sounds like cubo[1], the translation for cube.

ToQUBO.jl Logo

Colors

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

Typography

The MADETYPE Sunflower[3] font was chosen. It was converted to a SVG path using the Google Font to Svg Path[4] online tool.

Web Icon ToQUBO.jl Icon

The icon used to decorate the documentation resembles an assembled version of the cube with its blue face making up the background.

+Appendix · ToQUBO.jl
GitHub

Appendix

ToQUBO.jl's Assets

The ideia behind ToQUBO.jl's logo comes from a wordplay in Portuguese and Spanish. The package's main purpose is to assemble QUBO Models, which sounds like cubo[1], the translation for cube.

ToQUBO.jl Logo

Colors

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

Typography

The MADETYPE Sunflower[3] font was chosen. It was converted to a SVG path using the Google Font to Svg Path[4] online tool.

Web Icon ToQUBO.jl Icon

The icon used to decorate the documentation resembles an assembled version of the cube with its blue face making up the background.

diff --git a/previews/PR81/examples/integer_factorization/index.html b/previews/PR81/examples/integer_factorization/index.html index edd47cb..89ba21e 100644 --- a/previews/PR81/examples/integer_factorization/index.html +++ b/previews/PR81/examples/integer_factorization/index.html @@ -32,4 +32,4 @@ set_optimizer_attribute(model, "num_sweeps", 2_000) end -print("$p, $q")
3, 5
+print("$p, $q")
3, 5
diff --git a/previews/PR81/examples/knapsack/index.html b/previews/PR81/examples/knapsack/index.html index 70077f1..8604dfd 100644 --- a/previews/PR81/examples/knapsack/index.html +++ b/previews/PR81/examples/knapsack/index.html @@ -33,7 +33,7 @@ Objective value : 5.00000e+00 * Work counters - Solve time (sec) : 1.98650e-01 + Solve time (sec) : 2.00716e-01

The final decision is to take items $2$ and $3$, i.e., $x_{1} = 0, x_{2} = 1, x_{3} = 1$.

value.(x)
3-element Vector{Float64}:
  0.0
  1.0
@@ -60,4 +60,4 @@
 # Add Results as a new column
 df[:,:select] = map(xi -> ifelse(xi > 0, "✅", "❌"), value.(x))
 
-df
8×3 DataFrame
Rowcostweightselect
Int64Int64String
16679✅
28520✅
31240✅
4388✅
5734✅
69866✅
76929✅
8797❌
+df
8×3 DataFrame
Rowcostweightselect
Int64Int64String
16679✅
28520✅
31240✅
4388✅
5734✅
69866✅
76929✅
8797❌
diff --git a/previews/PR81/examples/portfolio_optimization/9ce754fd.svg b/previews/PR81/examples/portfolio_optimization/1fd00527.svg similarity index 91% rename from previews/PR81/examples/portfolio_optimization/9ce754fd.svg rename to previews/PR81/examples/portfolio_optimization/1fd00527.svg index c0dca9f..84b4027 100644 --- a/previews/PR81/examples/portfolio_optimization/9ce754fd.svg +++ b/previews/PR81/examples/portfolio_optimization/1fd00527.svg @@ -1,52 +1,52 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/previews/PR81/examples/portfolio_optimization/index.html b/previews/PR81/examples/portfolio_optimization/index.html index 491883e..014cb2c 100644 --- a/previews/PR81/examples/portfolio_optimization/index.html +++ b/previews/PR81/examples/portfolio_optimization/index.html @@ -92,4 +92,4 @@ plot!(plt, Λ, X[tag]; label=string(tag)) end -pltExample block output +pltExample block output diff --git a/previews/PR81/index.html b/previews/PR81/index.html index cd1d432..d2d45ca 100644 --- a/previews/PR81/index.html +++ b/previews/PR81/index.html @@ -16,7 +16,7 @@ solution_summary(model)
* Solver : Virtual QUBO Model
 
 * Status
-  Result count       : 23
+  Result count       : 25
   Termination status : LOCALLY_SOLVED
   Message from the solver:
   ""
@@ -27,7 +27,7 @@
   Objective value    : 5.00000e+00
 
 * Work counters
-  Solve time (sec)   : 1.98933e-01
+  Solve time (sec)   : 1.98703e-01

Citing ToQUBO.jl

If you use ToQUBO.jl in your work, we kindly ask you to include the following citation:

@software{toqubo:2023,
   author       = {Pedro Maciel Xavier and Pedro Ripper and Tiago Andrade and Joaquim Dias Garcia and David E. Bernal Neira},
   title        = {{ToQUBO.jl}},
@@ -37,4 +37,4 @@
   version      = {v0.1.5},
   doi          = {10.5281/zenodo.7644291},
   url          = {https://doi.org/10.5281/zenodo.7644291}
-}
+} diff --git a/previews/PR81/manual/1-start/index.html b/previews/PR81/manual/1-start/index.html index 92c6c00..a196a45 100644 --- a/previews/PR81/manual/1-start/index.html +++ b/previews/PR81/manual/1-start/index.html @@ -16,7 +16,7 @@ solution_summary(model)
* Solver : Virtual QUBO Model
 
 * Status
-  Result count       : 24
+  Result count       : 21
   Termination status : LOCALLY_SOLVED
   Message from the solver:
   ""
@@ -27,5 +27,5 @@
   Objective value    : 5.00000e+00
 
 * Work counters
-  Solve time (sec)   : 1.99208e-01
-

Table of Contents

+ Solve time (sec) : 1.98593e-01 +

Table of Contents

diff --git a/previews/PR81/manual/2-model/index.html b/previews/PR81/manual/2-model/index.html index fc69ed9..c865229 100644 --- a/previews/PR81/manual/2-model/index.html +++ b/previews/PR81/manual/2-model/index.html @@ -1,2 +1,2 @@ -Running a Model · ToQUBO.jl
GitHub

Running a Model

Work in progress

We hope to write this part of the documentation soon. Please come back later!

+Running a Model · ToQUBO.jl
GitHub

Running a Model

Work in progress

We hope to write this part of the documentation soon. Please come back later!

diff --git a/previews/PR81/manual/3-results/index.html b/previews/PR81/manual/3-results/index.html index ad85fde..c048e85 100644 --- a/previews/PR81/manual/3-results/index.html +++ b/previews/PR81/manual/3-results/index.html @@ -1,2 +1,2 @@ -Gathering Results · ToQUBO.jl
GitHub

Gathering Results

Work in progress

We hope to write this part of the documentation soon. Please come back later!

+Gathering Results · ToQUBO.jl
GitHub

Gathering Results

Work in progress

We hope to write this part of the documentation soon. Please come back later!

diff --git a/previews/PR81/manual/4-settings/index.html b/previews/PR81/manual/4-settings/index.html index 24e1df3..dfd7669 100644 --- a/previews/PR81/manual/4-settings/index.html +++ b/previews/PR81/manual/4-settings/index.html @@ -1,2 +1,2 @@ -Compiler Settings · ToQUBO.jl
GitHub

Compiler Settings

Compiler Messages

Compiler Optimization

Working with target architectures

Quadratization

ToQUBO.Attributes.Quadratize — Type
Quadratize()

Boolean flag to conditionally perform the quadratization step. Is automatically set by the compiler when high-order functions are generated.

source
ToQUBO.Attributes.StableQuadratization — Type
StableQuadratization()

When set, this boolean flag enables stable quadratization methods, thus yielding predictable results. This is intended to be used during tests or other situations where deterministic output is desired. On the other hand, usage in production is not recommended since it requires increased memory and processing resources.

source

Variable & Constraint Encoding

Discretization

+Compiler Settings · ToQUBO.jl
GitHub

Compiler Settings

Compiler Messages

Compiler Optimization

Working with target architectures

Quadratization

ToQUBO.Attributes.Quadratize — Type
Quadratize()

Boolean flag to conditionally perform the quadratization step. Is automatically set by the compiler when high-order functions are generated.

source
ToQUBO.Attributes.StableQuadratization — Type
StableQuadratization()

When set, this boolean flag enables stable quadratization methods, thus yielding predictable results. This is intended to be used during tests or other situations where deterministic output is desired. On the other hand, usage in production is not recommended since it requires increased memory and processing resources.

source

Variable & Constraint Encoding

Discretization