Write Docs for v0.1.5

.github/workflows/documentation.yml

@@ -14,10 +14,12 @@ jobs:
       - uses: julia-actions/setup-julia@latest
         with:
           version: '1.6'
+      - name: Develop ToQUBO.jl
+        run: julia --project=docs -e 'using Pkg; Pkg.develop(path=pwd())'
       - uses: julia-actions/julia-buildpkg@latest
         with: 
-            project: "docs/"
+            project: "docs"
       - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
-        run: julia --project=docs/ docs/make.jl
+        run: julia --project=docs docs/make.jl

CITATION.bib

@@ -1,7 +1,7 @@
 % If you use this software, please cite it as below.
 @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},
+  title        = {{ToQUBO.jl}},
   month        = {feb},
   year         = {2023},
   publisher    = {Zenodo},

README.md

@@ -28,10 +28,7 @@ ToQUBO.jl was written as a [MathOptInterface](https://github.com/jump-dev/MathOp
 
 ### Installation
 ToQUBO is available via Julia's Pkg:
-```julia
-julia> ]add ToQUBO
-```
-or
+
 ```julia
 julia> using Pkg
 
@@ -53,9 +50,10 @@ model = Model(() -> ToQUBO.Optimizer(ExactSampler.Optimizer))
 optimize!(model)
 
 for i = 1:result_count(model)
-    xᵢ = value.(x, result = i)
-    yᵢ = objective_value(model, result = i)
-    println("f($xᵢ) = $yᵢ")
+    xi = value.(x, result = i)
+    yi = objective_value(model, result = i)
+
+    println("f($xi) = $yi")
 end
 ```
 
@@ -135,15 +133,15 @@ If you think this list is incomplete, consider creating an [Issue](https://githu
 ## Citing ToQUBO.jl
 If you use `ToQUBO.jl` in your work, we kindly ask you to include the following citation:
 ```tex
-@software{toqubo:2022,
-  author       = {Pedro Xavier and Tiago Andrade and Joaquim Garcia and David Bernal},
+@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}},
-  month        = {mar},
-  year         = {2022},
+  month        = {feb},
+  year         = {2023},
   publisher    = {Zenodo},
-  version      = {v0.1.0},
-  doi          = {10.5281/zenodo.6387592},
-  url          = {https://doi.org/10.5281/zenodo.6387592}
+  version      = {v0.1.5},
+  doi          = {10.5281/zenodo.7644291},
+  url          = {https://doi.org/10.5281/zenodo.7644291}
 }
 ```
 

docs/Project.toml

@@ -4,14 +4,16 @@ DWaveNeal = "870cdf72-5502-4b10-839c-127ceab78f22"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
-MQLib = "16f11440-1623-44c9-850c-358a6c72f3c9"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
-QUBODrivers = "a3f166f7-2cd3-47b6-9e1e-6fbfe0449eb0"
+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"
 JuMP = "1"

docs/make.jl

@@ -7,24 +7,44 @@ DocMeta.setdocmeta!(
 )
 
 makedocs(;
-    modules=[ToQUBO],
-    doctest=true,
-    clean=true,
-    format=Documenter.HTML(
-        assets = ["assets/extra_styles.css", "assets/favicon.ico"],
-        mathengine=Documenter.MathJax2(),
-        sidebar_sitename=false,
+    modules = [ToQUBO],
+    doctest = true,
+    clean   = true,
+    format  = Documenter.HTML(
+        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),
+        ],
+        mathengine       = Documenter.KaTeX(),
+        sidebar_sitename = false,
     ), 
-    sitename="ToQUBO.jl",
-    authors="Pedro Xavier and Tiago Andrade and Joaquim Garcia and David Bernal",
-    pages=[
+    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" => "manual.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",
+        ],
         "Examples" => [
-            "Knapsack" =>"examples/knapsack.md",
-            "Prime Factorization" => "examples/prime_factorization.md",
+            "Knapsack"               => "examples/knapsack.md",
+            "Prime Factorization"    => "examples/prime_factorization.md",
+            "Portfolio Optimization" => "examples/portfolio_optimization.md",
+        ],
+        "Booklet" => [
+            "Introduction"    => "booklet/1-intro.md",
+            "QUBO"            => "booklet/2-qubo.md",
+            "PBO"             => "booklet/3-pbo.md",
+            "Encoding"        => "booklet/4-encoding.md",
+            "Virtual Mapping" => "booklet/5-virtual.md",
+            "The Compiler"    => "booklet/6-compiler.md",
+            "Solvers"         => "booklet/7-solvers.md",
+            "Appendix"        => "booklet/8-appendix.md",
         ],
-        "Booklet" => "booklet.md"
     ],
     workdir="."
 )

docs/src/assets/extra_styles.css

@@ -1,4 +1,15 @@
 .docs-sidebar .docs-logo > img {
     max-height: 16rem !important;
     margin: auto;
-}
+}
+
+/* Center images & diagrams */
+p:has(img) {
+    text-align: center;
+    margin: 0 auto;
+}
+
+div.mermaid {
+    text-align: center;
+    margin: 0 auto;
+}

docs/src/assets/init.js

@@ -0,0 +1,24 @@
+/* Ref:
+** https://discourse.julialang.org/t/use-javascript-library-with-documenter-jl/34984/8
+*/
+require.config({
+    paths: {
+        mermaid: "https://cdnjs.cloudflare.com/ajax/libs/mermaid/9.4.0/mermaid.min"
+    }
+});
+
+require(['mermaid'], function (mermaid) {
+    mermaid.initialize({
+        startOnLoad : true,
+        theme       : 'neutral',
+        // themeVariables: {
+        //     primaryColor: '#BB2528',
+        //     primaryTextColor: '#fff',
+        //     primaryBorderColor: '#7C0000',
+        //     lineColor: '#F8B229',
+        //     secondaryColor: '#006100',
+        //     tertiaryColor: '#aaa',
+        //     noteBorderColor: '#ff0',
+        // }
+    })
+});

docs/src/booklet/1-intro.md

@@ -0,0 +1,11 @@
+# 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
+```@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

@@ -0,0 +1,41 @@
+# QUBO
+
+## Definition
+**Q**uadratic **U**nconstrained **B**inary **O**ptimization, as its name suggests, refers to the global minimization or maximization of a given quadratic polynomial over binary variables whose domain is that often reliesany way. on the laws of physics to compute solution candidates.
+A common mathematical presentation is given by their quadratic matrix form, i.e.
+
+```math
+\begin{array}{rl}
+   \min_{\mathbf{x}} & \mathbf{x}' Q\,\mathbf{x} \\
+   \textrm{s.t.}     & \mathbf{x} \in \mathbb{B}^{n}
+\end{array}
+```
+
+where ``Q \in \mathbb{R}^{n \times n}`` is symmetric and ``\mathbb{B} = \lbrace{0, 1}\rbrace``.
+
+## 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 if 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](https://en.wikipedia.org/wiki/Ising_model), on the other hand, is a mathematical abstraction to describe statistical interactions within mechanical systems.
+Its _Hamiltonian energy function_ leads to an optimization formulation in terms of the ``\pm 1`` _spin_ values of their states, written as
+
+```math
+\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}
+```
+
+where ``J \in \mathbb{R}^{n \times n}`` is strictly upper triangular and ``\mathbf{h} \in \mathbb{R}``.
+
+[![D-Wave Washington 1000Q](../assets/figures/quantum-chip.png)](https://commons.wikimedia.org/wiki/File:D-Wave-Washington-1000Q.jpg)
+
+The Ising reformulation alternative draws the bridge between QUBO problems and specialized devices that rely on the laws of physics to compute solution candidates.
+Some of the paradigms that stand out in this context are quantum gate-based optimization algorithms (QAOA and VQE), quantum annealers and hardware-accelerated platforms (Coherent Ising Machines and Simulated Bifurcation Machines).
+The significant advances in these computing systems contributed to the growing popularity of the model across the literature.