ToQUBO Compiler Upgrade

.github/workflows/documentation.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: julia-actions/setup-julia@latest
         with:
-          version: '1.6'
+          version: '1.9'
       - name: Develop ToQUBO.jl
         run: julia --project=docs -e 'using Pkg; Pkg.develop(path=pwd())'
       - uses: julia-actions/julia-buildpkg@latest

Project.toml

@@ -1,15 +1,16 @@
 name = "ToQUBO"
 uuid = "9a412ddf-83fa-43b6-9748-7843c851aa65"
 authors = ["pedromxavier <[email protected]>", "pedroripper <[email protected]>", "joaquimg <[email protected]>", "AndradeTiago <[email protected]>", "bernalde <[email protected]>"]
-version = "0.1.6"
+version = "0.1.7"
 
 [deps]
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
+PseudoBooleanOptimization = "c8fa9a04-bc42-452d-8558-dc51757be744"
 QUBOTools = "60eb5b62-0a39-4ddc-84c5-97d2adff9319"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 
 [compat]
 MathOptInterface = "1"
-QUBOTools = "0.8.0"
-julia = "1.6"
+QUBOTools = "0.9"
+julia = "1.9"

docs/Project.toml

@@ -1,21 +1,19 @@
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
-DWaveNeal = "870cdf72-5502-4b10-839c-127ceab78f22"
+DWave = "4d534982-bf11-4157-9e48-fe3a62208a50"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
+Measures = "442fdcdd-2543-5da2-b0f3-8c86c306513e"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
-PythonPlot = "274fc56d-3b97-40fa-a1cd-1b4a50311bf9"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 ToQUBO = "9a412ddf-83fa-43b6-9748-7843c851aa65"
 
 [compat]
 CSV = "0.10"
-DWaveNeal = "0.4"
 DataFrames = "1.3"
-Documenter = "0.27"
+Documenter = "1"
 JuMP = "1"
 MathOptInterface = "1"
-ToQUBO = "0.1"

docs/make.jl

@@ -2,46 +2,43 @@ using Documenter
 using ToQUBO
 
 # Set up to run docstrings with jldoctest
-DocMeta.setdocmeta!(
-    ToQUBO, :DocTestSetup, :(using ToQUBO); recursive=true
-)
+DocMeta.setdocmeta!(ToQUBO, :DocTestSetup, :(using ToQUBO); recursive = true)
 
 makedocs(;
-    modules = [ToQUBO],
-    doctest = true,
-    clean   = true,
-    format  = Documenter.HTML(
+    modules  = [ToQUBO],
+    doctest  = true,
+    clean    = true,
+    warnonly = [:missing_docs, :cross_references],
+    format   = Documenter.HTML( #
         sidebar_sitename = false,
         mathengine       = Documenter.KaTeX(
             Dict(
-                :macros => Dict(
-                    raw"\set" => raw"\left\lbrace{#1}\right\rbrace"
-                )
+                :macros => Dict(raw"\set" => raw"\left\lbrace{#1}\right\rbrace")
             )
         ),
-        assets           = [
+        assets = [ #
             "assets/extra_styles.css",
             "assets/favicon.ico",
-            asset("https://tikzjax.com/v1/fonts.css"; class = :css),
-            asset("https://tikzjax.com/v1/tikzjax.js"; class = :js),
-        ],
-    ), 
+            # asset("https://tikzjax.com/v1/fonts.css"; class = :css),
+            # asset("https://tikzjax.com/v1/tikzjax.js"; class = :js),
+        ]
+    ),
     sitename = "ToQUBO.jl",
     authors  = "Pedro Maciel Xavier and Pedro Ripper and Tiago Andrade and Joaquim Dias Garcia and David E. Bernal Neira",
-    pages    = [
-        "Home" => "index.md",
-        "Manual" => [
+    pages    = [ # 
+        "Home"   => "index.md",
+        "Manual" => [ #
             "Getting Started"   => "manual/1-start.md",
             "Running a Model"   => "manual/2-model.md",
             "Gathering Results" => "manual/3-results.md",
-            "Compiler Settings" => "manual/4-settings.md",
+            "Compiler Settings" => "manual/4-settings.md"
         ],
-        "Examples" => [
+        "Examples" => [ #
             "Knapsack"               => "examples/knapsack.md",
-            "Prime Factorization"    => "examples/prime_factorization.md",
+            "Integer Factorization"  => "examples/integer_factorization.md",
             "Portfolio Optimization" => "examples/portfolio_optimization.md",
         ],
-        "Booklet" => [
+        "Booklet" => [ #
             "Introduction"    => "booklet/1-intro.md",
             "QUBO"            => "booklet/2-qubo.md",
             "PBO"             => "booklet/3-pbo.md",
@@ -50,16 +47,13 @@ makedocs(;
             "The Compiler"    => "booklet/6-compiler.md",
             "Solvers"         => "booklet/7-solvers.md",
             "Appendix"        => "booklet/8-appendix.md",
-        ],
+        ]
     ],
-    workdir="."
+    workdir = @__DIR__,
 )
 
 if "--skip-deploy" ∈ ARGS
     @warn "Skipping deployment"
 else
-    deploydocs(
-        repo=raw"github.com/psrenergy/ToQUBO.jl.git",
-        push_preview = true
-    )
-end
+    deploydocs(repo = raw"github.com/psrenergy/ToQUBO.jl.git", push_preview = true)
+end

docs/src/assets/fonts/Sunflower-LICENSE.md

@@ -0,0 +1,26 @@
+# Sunflower Font License
+
+```@raw txt
+MadeType
+behance.com/madetype
+
+https://www.fontspring.com/fonts/madetype
+https://creativemarket.com/MadeType
+https://www.youworkforthem.com/designer/1002/madetype/
+https://crella.net/store/madetype/
+https://thehungryjpeg.com/madetype
+
+
+END USER LICENSE AGREEMENT
+
+- FOR PERSONAL USE. 
+
+- Contact me at [email protected] before commercial using it.
+
+- MadeType is not liable for any damage resulting from the use ot this typeface.
+
+- All rights are retained by MadeType.
+
+
+THANK YOU!
+```

docs/src/booklet/1-intro.md

@@ -5,7 +5,8 @@ The target audience includes, among others, advanced users and those willing to
 The latter are advised to read the following sections, as they give a glimpse of the ideas employed up to now.
 
 ## Table of Contents
+
 ```@contents
 Pages = ["2-qubo.md", "3-pbo.md", "4-encoding.md", "5-virtual.md", "6-compiler.md", "7-solvers.md", "8-appendix.md"]
 Depth = 2
-```
+```

docs/src/booklet/2-qubo.md

@@ -15,6 +15,7 @@ where ``Q \in \mathbb{R}^{n \times n}`` is symmetric and ``\mathbb{B} = \lbrace{
 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](https://en.wikipedia.org/wiki/Maximum_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:
 

docs/src/booklet/3-pbo.md

@@ -1,54 +1,29 @@
 # 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.
 
-```@docs
-ToQUBO.PBO.PseudoBooleanFunction
-```
-
 ## 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
 
-```math 
+```math
 \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.
 
-```@docs
-ToQUBO.PBO.quadratize!
-```
-
 [^Dattani2019]:
     Nikesh S. Dattani, **Quadratization in discrete optimization and quantum mechanics**, *ArXiv*, 2019 [{doi}](https://doi.org/10.48550/arXiv.1901.04405)
 
-### Implemented Quadratization Techniques
-
-Currently, `ToQUBO` has two reduction algorithms, one for negative and another for positive terms.
-
-```@docs
-ToQUBO.PBO.NTR_KZFD
-ToQUBO.PBO.PTR_BG
-```
+### 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`](@ref) flag.
-
-
-
-### A Primer on Submodularity
-A set function ``f : 2^{S} \to \mathbb{R}`` is said to be submodular if
-
-```math
-f(X \cup Y) + f(X \cap Y) \le f(X) + f(Y) \forall X, Y \subset S
-```
-
-holds.

docs/src/booklet/4-encoding.md

@@ -1,9 +1,15 @@
 # Encoding Methods
 
+```@docs
+ToQUBO.Encoding.encode
+ToQUBO.Encoding.encode!
+ToQUBO.Encoding.encodes
+```
+
 ## 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. 
+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.
@@ -18,29 +24,43 @@ Also, they differ in the magnitude of their coefficients ``\Delta``.
 | Bounded-Coefficient   |    ``O(n)``        |    ``O(n)``      |       -             | ``O(1)``         |
 | Arithmetic Prog       |  ``O(\sqrt{n})``   |  ``O(\sqrt{n})`` |       -             | ``O(\sqrt{n})``  |
 
-### Linear Encoding
+### Mirror Encoding
+
+```@docs
+ToQUBO.Encoding.VariableEncodingMethod
+ToQUBO.Encoding.Mirror
+```
+
+### Interval Encoding
+
 ```@docs
-ToQUBO.Unary
-ToQUBO.Binary
-ToQUBO.Arithmetic
-ToQUBO.OneHot
+ToQUBO.Encoding.IntervalVariableEncodingMethod
+ToQUBO.Encoding.Unary
+ToQUBO.Encoding.Binary
+ToQUBO.Encoding.Arithmetic
 ```
 
+#### Bounded Coefficients
+
 ```@docs
-ToQUBO.Mirror
+ToQUBO.Encoding.Bounded
 ```
 
-### Sequential Encoding
+### Arbitrary Set Encoding
+
 ```@docs
-ToQUBO.DomainWall
+ToQUBO.Encoding.SetVariableEncodingMethod
+ToQUBO.Encoding.OneHot
+ToQUBO.Encoding.DomainWall
 ```
 
-### Bounded Coefficients
+### Representation Error
+
 ```@docs
-ToQUBO.Bounded
+ToQUBO.Encoding.encoding_bits
+ToQUBO.Encoding.encoding_points
 ```
 
-### Encoding 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
@@ -73,11 +93,4 @@ A QUBO model is unconstrained. So when `ToQUBO` is reformulating a problem, it n
 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. 
-
-As of today, `ToQUBO` provides encoding for the following constraints:
-
-```@docs
-ToQUBO.toqubo_constraint
-```
-
+Sometimes, the encoding process might introduce higher-order terms, demanding `ToQUBO` to reduce the offending polynomials back to a quadratic form.