Write Docs for v0.1.5

docs/make.jl

@@ -19,12 +19,24 @@ makedocs(;
     authors="Pedro Xavier and Tiago Andrade and Joaquim Garcia and David Bernal",
     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",
         ],
-        "Booklet" => "booklet.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",
+            "Solvers"         => "booklet/6-solvers.md",
+        ]
     ],
     workdir="."
 )

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-solvers.md"]
+Depth = 2
+```

docs/src/booklet/2-qubo.md

@@ -0,0 +1,29 @@
+# QUBO
+
+## Definition
+
+```math
+\begin{array}{rl}
+   \min        & \mathbf{x}^{\intercal} Q\,\mathbf{x} \\
+   \text{s.t.} & \mathbf{x} \in \mathbb{B}^{n}
+\end{array}
+```
+
+## OK, but why QUBO?
+
+```@docs
+ToQUBO.isqubo
+ToQUBO.toqubo
+ToQUBO.toqubo!
+```
+
+```@docs
+ToQUBO.toqubo_sense!
+ToQUBO.toqubo_variables!
+ToQUBO.toqubo_constraint
+ToQUBO.toqubo_constraints!
+ToQUBO.toqubo_objective!
+ToQUBO.toqubo_penalties!
+ToQUBO.toqubo_parse!
+ToQUBO.toqubo_build!
+```

docs/src/booklet/3-pbo.md

@@ -0,0 +1,23 @@
+# 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 quadratic PBFs and QUBO forms.
+
+```@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. There are many quadratization methods available, and `ToQUBO` implements a few of them.
+
+```@docs
+ToQUBO.PBO.quadratize!
+```
+
+### 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

@@ -0,0 +1,25 @@
+# Encoding Methods
+
+## Variable Encoding
+
+### Linear Encoding Methods
+```@docs
+ToQUBO.LinearEncoding
+ToQUBO.Binary
+ToQUBO.Unary
+ToQUBO.Arithmetic
+ToQUBO.OneHot
+```
+
+### Sequential Encoding Methods
+```@docs
+ToQUBO.SequentialEncoding
+ToQUBO.DomainWall
+```
+
+### Bounded Coefficients
+```@docs
+ToQUBO.Bounded
+```
+
+## Constraint Encoding

docs/src/booklet/5-virtual.md

@@ -0,0 +1,21 @@
+# 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
+```@docs
+ToQUBO.VirtualModel
+```
+
+## 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 enconding information for later expansion and evaluation.
+
+```@docs
+ToQUBO.VirtualVariable
+ToQUBO.encode!
+```

docs/src/booklet/6-solvers.md

@@ -0,0 +1,21 @@
+# QUBO Solvers
+
+## Solvers, Annealers & Samplers
+`ToQUBO`'s main goal is to benefit from non-deterministic samplers, especially *Quantum Adiabatic* devices and other *Annealing* machines. A few `MOI`-compliant interfaces for annealers and samplers are bundled within `ToQUBO` via the `Anneal.jl` submodule and package prototype. Some of them are presented below.
+
+### Simulated Annealing
+Provided by D-Wave's open-source code libraries, this [Simulated Annealing](https://en.wikipedia.org/wiki/Simulated_annealing) engine implements some of the features and configuration you would find using the Quantum API. Its adoption is recommended for basic usage, tests, and during early research steps due to its simplicity and ease of use. It does not implement the most advanced Simulated Annealing algorithm available but performs fairly well on small instances. `Anneal.jl` exports this interface as `SimulatedAnnealer.Optimizer`.
+
+### Quantum Annealing
+Interfacing with [D-Wave](https://www.dwavesys.com/)'s quantum computers is one of the milestones we expect to achieve with this package. Like other proprietary optimization resources such as [Gurobi](https://gurobi.com) and [FICO® Xpress](https://www.fico.com/en/products/fico-xpress-solver), this requires licensing and extra steps are needed to get access to it. In a first moment, for those willing to get started, the *Simulated Annealing* optimizer might be enough.
+
+While in `JuMP`, run `using Anneal` and look for `QuantumAnnealer.Optimizer`.
+
+### 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 Anneal` command, `RandomSampler.Optimizer` will be available.
+
+### Exact Solver (Exaustive 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 no more than 20 variables should be provided.
+
+## MIQP Solvers
+The most accessible alternative to Annealers and Samplers are Mixed-Integer Quadratic Programming (MIQP) Solvers such as [Gurobi](https://github.com/jump-dev/Gurobi.jl) and [CPLEX](https://github.com/jump-dev/CPLEX.jl). These are not intended to be of regular use alongside `ToQUBO` since reformulation usually makes things harder for these folks. Yet, there are still cases where they may be suitable for tests on small instances.

docs/src/examples/prime_factorization.md

@@ -25,7 +25,7 @@ using ToQUBO
 using DWaveNeal
 
 function factor(R::Integer; optimizer = DWaveNeal.Optimizer)
-    return factor(identity, R; optimizer = optimizer)
+    return factor(identity, R; optimizer)
 end
 
 function factor(config!::Function, R::Integer; optimizer = DWaveNeal.Optimizer)

docs/src/manual.md → docs/src/manual/1-start.md

@@ -19,23 +19,8 @@ optimize!(model)
 solution_summary(model)
 ```
 
-## Compiler Flags
-
-### Architecture
-```@docs
-ToQUBO.Attributes.Architecture
-```
-
-### Quadratization
-```@docs
-ToQUBO.Attributes.Quadratize
-ToQUBO.Attributes.QuadratizationMethod
-ToQUBO.Attributes.StableQuadratization
-```
-
-### Variable & Constraint Encoding
-```@docs
-ToQUBO.Attributes.VariableEncodingMethod
-ToQUBO.Attributes.VariableEncodingPenalty
-ToQUBO.Attributes.ConstraintEncodingPenalty
+## Table of Contents
+```@contents
+Pages = ["2-model.md", "3-results.md", "4-settings.md"]
+Depth = 2
 ```

docs/src/manual/2-model.md

@@ -0,0 +1 @@
+# Running a Model

docs/src/manual/3-results.md

@@ -0,0 +1 @@
+# Gathering Results

docs/src/manual/4-settings.md

@@ -0,0 +1,25 @@
+# Compiler Settings
+
+## Architecture
+```@docs
+ToQUBO.Attributes.Architecture
+```
+
+## Quadratization
+```@docs
+ToQUBO.Attributes.Quadratize
+ToQUBO.Attributes.QuadratizationMethod
+ToQUBO.Attributes.StableQuadratization
+```
+
+## Variable & Constraint Encoding
+```@docs
+ToQUBO.Attributes.VariableEncodingBits
+ToQUBO.Attributes.DefaultVariableEncodingBits
+ToQUBO.Attributes.VariableEncodingATol
+ToQUBO.Attributes.DefaultVariableEncodingATol
+ToQUBO.Attributes.VariableEncodingMethod
+ToQUBO.Attributes.DefaultVariableEncodingMethod
+ToQUBO.Attributes.VariableEncodingPenalty
+ToQUBO.Attributes.ConstraintEncodingPenalty
+```

src/attributes/compiler.jl

@@ -1,6 +1,14 @@
 module Attributes
 
-import ..ToQUBO
+import ..ToQUBO:
+    ToQUBO,
+    Unary,
+    Binary,
+    Arithmetic,
+    OneHot,
+    DomainWall,
+    Bounded
+
 import MathOptInterface as MOI
 const MOIU = MOI.Utilities
 const VI = MOI.VariableIndex
@@ -75,7 +83,7 @@ end
     QuadratizationMethod()
 
 Defines which quadratization method to use.
-Available options are defined in the [`PBO`](@ref) submodule.
+Available options are defined in the `PBO` submodule.
 """ struct QuadratizationMethod <: CompilerAttribute end
 
 function MOI.get(model::ToQUBO.VirtualModel, ::QuadratizationMethod)
@@ -293,7 +301,7 @@ end
 MOI.is_set_by_optimize(::ConstraintEncodingPenalty) = true
 
 @doc raw"""
-    QUBONormalForm
+    QUBONormalForm()
 """ struct QUBONormalForm <: CompilerAttribute end
 
 function MOI.get(