JuliaQUBO · pedromxavier · Feb 15, 2023 · Jan 3, 2023 · Jan 5, 2023 · Jan 5, 2023
diff --git a/Project.toml b/Project.toml
@@ -1,17 +1,21 @@
-name = "ToQUBO"
-uuid = "9a412ddf-83fa-43b6-9748-7843c851aa65"
-authors = ["pedromxavier <pedroxavier@psr-inc.com>", "joaquimg <joaquim@psr-inc.com>", "AndradeTiago <tiago.andrade@psr-inc.com>", "David Bernal <dbernalneira@usra.edu>"]
+name    = "ToQUBO"
+uuid    = "9a412ddf-83fa-43b6-9748-7843c851aa65"
+authors = [
+    "pedromxavier <pedroxavier@psr-inc.com>",
+    "pedroripper <pedroripper@psr-inc.com>",
+    "joaquimg <joaquim@psr-inc.com>",
+    "AndradeTiago <tiago.andrade@psr-inc.com>",
+    "bernalde <dbernalneira@usra.edu>",
+]
 version = "0.1.4"
 
 [deps]
-MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
-MutableArithmetics = "d8a4904e-b15c-11e9-3269-09a3773c0cb0"
-QUBOTools = "60eb5b62-0a39-4ddc-84c5-97d2adff9319"
-Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
-TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
+MathOptInterface   = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
+QUBOTools          = "60eb5b62-0a39-4ddc-84c5-97d2adff9319"
+Random             = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+TOML               = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 
 [compat]
-MathOptInterface = "1"
-MutableArithmetics = "1"
-QUBOTools = "0.4"
-julia = "1.6"
+MathOptInterface   = "1"
+QUBOTools          = "0.6.1"
+julia              = "1.6"
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,18 +1,20 @@
 [deps]
 Anneal = "e4d9eb7f-b088-426e-aeb5-1c0dae3d8abb"
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+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"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 ToQUBO = "9a412ddf-83fa-43b6-9748-7843c851aa65"
 
 [compat]
-Anneal = "0.1"
+Anneal = "0.6"
 CSV = "0.10"
 DataFrames = "1.3"
 Documenter = "0.27"
-JuMP = "0.23"
+JuMP = "1"
 MathOptInterface = "1"
 ToQUBO = "0.1"
diff --git a/docs/make.jl b/docs/make.jl
@@ -19,14 +19,21 @@ makedocs(;
     authors="Pedro Xavier and Tiago Andrade and Joaquim Garcia and David Bernal",
     pages=[
         "Home" => "index.md",
-        "manual.md",
-        "examples.md",
+        "Manual" => "manual.md",
+        "Examples" => [
+            "Knapsack" =>"examples/knapsack.md",
+            "Prime Factorization" => "examples/prime_factorization.md",
+        ],
         "Booklet" => "booklet.md"
     ],
     workdir="."
 )
 
-deploydocs(
-    repo=raw"github.com/psrenergy/ToQUBO.jl.git",
-    push_preview = true
-)
+if "--skip-deploy" ∈ ARGS
+    @warn "Skipping deployment"
+else
+    deploydocs(
+        repo=raw"github.com/psrenergy/ToQUBO.jl.git",
+        push_preview = true
+    )
+end
diff --git a/docs/src/booklet.md b/docs/src/booklet.md
@@ -18,8 +18,12 @@ ToQUBO.toqubo!
 ```@docs
 ToQUBO.toqubo_sense!
 ToQUBO.toqubo_variables!
-ToQUBO.toqubo_constraint!
+ToQUBO.toqubo_constraint
+ToQUBO.toqubo_constraints!
 ToQUBO.toqubo_objective!
+ToQUBO.toqubo_penalties!
+ToQUBO.toqubo_parse!
+ToQUBO.toqubo_build!
 ```
 
 ## Pseudo-Boolean Optimization
@@ -32,16 +36,23 @@ ToQUBO.PBO.derivative
 ToQUBO.PBO.gradient
 ToQUBO.PBO.gap
 ToQUBO.PBO.sharpness
-ToQUBO.PBO.discretize
 ToQUBO.PBO.relaxed_gcd
 ```
 
+### 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.
+
 ### 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
-ToQUBO.PBO.@quadratization
+ToQUBO.PBO.quadratize!
 ```
 
 ## Virtual Mapping
@@ -53,20 +64,22 @@ This is done in a transparent fashion for both agents since the user will mostly
 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.VirtualMapping.VirtualVariable
-ToQUBO.VirtualMapping.mapvar!
-ToQUBO.VirtualMapping.expandℝ!
-ToQUBO.VirtualMapping.slackℝ!
-ToQUBO.VirtualMapping.expandℤ!
-ToQUBO.VirtualMapping.slackℤ!
-ToQUBO.VirtualMapping.mirror𝔹!
-ToQUBO.VirtualMapping.slack𝔹!
+ToQUBO.VirtualVariable
+ToQUBO.encode!
+```
+
+### Variable Encoding
+```@docs
+ToQUBO.Binary
+ToQUBO.Unary
+ToQUBO.Arithmetic
+ToQUBO.OneHot
+ToQUBO.DomainWall
 ```
 
 ### Virtual Models
 ```@docs
-ToQUBO.VirtualMapping.AbstractVirtualModel
-ToQUBO.VirtualQUBOModel
+ToQUBO.VirtualModel
 ```
 
 ### Annealing & Sampling

diff --git a/docs/src/examples.md → docs/src/examples/knapsack.md b/docs/src/examples.md → docs/src/examples/knapsack.md
@@ -1,5 +1,3 @@
-# Examples
-
 ## Knapsack
 We start with some instances of the discrete [Knapsack Problem](https://en.wikipedia.org/wiki/Knapsack_problem) whose standard formulation is
 ```math
@@ -18,13 +16,13 @@ import MathOptInterface as MOI
 const MOIU = MOI.Utilities
 
 using ToQUBO
-using Anneal # <- Your favourite Annealer / Sampler / Solver here
+using DWaveNeal # <- Your favourite Annealer / Sampler / Solver here
 
 # Example from https://jump.dev/MathOptInterface.jl/stable/tutorials/example/
 
 # Virtual QUBO Model
 model = MOI.instantiate(
-   () -> ToQUBO.Optimizer(SimulatedAnnealer.Optimizer),
+   () -> ToQUBO.Optimizer(DWaveNeal.Optimizer),
    with_bridge_type = Float64,
 )
 
@@ -33,10 +31,12 @@ c = [1.0, 2.0, 3.0]
 w = [0.3, 0.5, 1.0]
 C = 3.2;
 
-# -*- Variables -*- #
 x = MOI.add_variables(model, n);
 
-# -*- Objective -*- #
+for xᵢ in x
+   MOI.add_constraint(model, xᵢ, MOI.ZeroOne())
+end
+
 MOI.set(model, MOI.ObjectiveSense(), MOI.MAX_SENSE)
 
 MOI.set(
@@ -45,22 +45,16 @@ MOI.set(
    MOI.ScalarAffineFunction(MOI.ScalarAffineTerm.(c, x), 0.0),
 );
 
-# -*- Constraints -*- #
 MOI.add_constraint(
    model,
    MOI.ScalarAffineFunction(MOI.ScalarAffineTerm.(w, x), 0.0),
    MOI.LessThan(C),
 );
 
-for xᵢ in x
-   MOI.add_constraint(model, xᵢ, MOI.ZeroOne())
-end
-
-# Run!
 MOI.optimize!(model)
 
 # Collect Solution
-MOI.get(model, MOI.VariablePrimal(), x)
+MOI.get.(model, MOI.VariablePrimal(), x)
 ```
 
 ### JuMP + D-Wave Examples
@@ -73,7 +67,7 @@ using CSV
 using DataFrames
 using Random
 
-# -> Generate Data <-
+# Generate Data
 rng = MersenneTwister(1)
 
 df = DataFrame(
@@ -94,35 +88,21 @@ df = CSV.read("knapsack.csv", DataFrame)
 ```@example dwave-knapsack
 using JuMP
 using ToQUBO
-using Anneal # <- Your favourite Annealer / Sampler / Solver here
+using DWaveNeal # <- Your favourite Annealer/Sampler/Solver here
 
-# -> Model <-
-model = Model(() -> ToQUBO.Optimizer(SimulatedAnnealer.Optimizer))
+model = Model(() -> ToQUBO.Optimizer(DWaveNeal.Optimizer))
 
 n = size(df, 1)
 c = collect(Float64, df[!, :cost])
 w = collect(Float64, df[!, :weight])
 C = round(0.8 * sum(w))
 
-# -> Variables <-
-@variable(model, x[i=1:n], Bin)
-
-# -> Objective <-
+@variable(model, x[1:n], Bin)
 @objective(model, Max, c' * x)
-
-# -> Constraint <-
 @constraint(model, w' * x <= C)
 
-# ->-> Run! ->->
 optimize!(model)
 
 # Add Results as a new column
-insertcols!(
-   df,
-   3, 
-   :select => map(
-      (ξ) -> (ξ > 0.0) ? "Yes" : "No",
-      value.(x),
-   ),
-)
+insertcols!(df, 3, :select => map((ξ) -> (ξ > 0.0) ? "Yes" : "No", value.(x)))
 ```
diff --git a/docs/src/examples/prime_factoring.md b/docs/src/examples/prime_factoring.md
diff --git a/docs/src/examples/prime_factorization.md b/docs/src/examples/prime_factorization.md
@@ -0,0 +1,57 @@
+# Prime Factorization
+
+A central problem in Number Theory and cryptography is to factor ``R \in \mathbb{N}``, which is known
+to be the product of two distinct prime numbers ``p, q \in \mathbb{N}``.
+[Shor's Algorithm](https://en.wikipedia.org/wiki/Shor%27s_algorithm), designed to address such task is
+often regarded as one of the major theoretical landmarks in Quantum Computing, being responsible for
+driving increasingly greater interest to the area.
+
+A naïve approach to model this problem can be stated as a quadratically-constrained integer program:
+```math
+\begin{array}{rl}
+\text{s.t.} & p \times q = R \\
+            & p, q \ge 0     \\
+            & p, q \in \mathbb{Z}
+\end{array}
+```
+
+From the definition and the basics of number theory, we are able to retrieve a few assumptions about the problem's variables:
+- ``p`` and ``q`` are bounded to the interval ``\left[1, R\right]``
+- Moreover, it is fine to assume ``1 < p \le \sqrt{R} \le q \le R \div 2``.
+
+```@example prime-factorization
+using JuMP
+using ToQUBO
+using DWaveNeal
+
+function factor(R::Integer; optimizer = DWaveNeal.Optimizer)
+    return factor(identity, R; optimizer = optimizer)
+end
+
+function factor(config!::Function, R::Integer; optimizer = DWaveNeal.Optimizer)
+    model = Model(() -> ToQUBO.Optimizer(optimizer))
+
+    @variable(model,  1 <= p <= √R, Int)
+    @variable(model, √R <= q <= R ÷ 2, Int)
+
+    @constraint(model, p * q == R)
+
+    config!(model)
+
+    optimize!(model)
+
+    p = round(Int, value(model[:p]))
+    q = round(Int, value(model[:q]))
+
+    return (p, q)
+end
+```
+
+```@example prime-factorization
+p, q = factor(15) do model
+    set_optimizer_attribute(model, "num_reads", 1_000)
+    set_optimizer_attribute(model, "num_sweeps", 2_000)
+end
+
+print("$p, $q")
+```
diff --git a/docs/src/manual.md b/docs/src/manual.md
@@ -4,15 +4,38 @@
 ```@example quick-start
 using JuMP
 using ToQUBO
-using Anneal
+using DWaveNeal # <- Your favourite Annealer/Sampler/Solver here
 
-model = Model(() -> ToQUBO.Optimizer(SimulatedAnnealer.Optimizer))
+model = Model(() -> ToQUBO.Optimizer(DWaveNeal.Optimizer))
 
 @variable(model, x[1:3], Bin)
+
 @objective(model, Max, 1.0 * x[1] + 2.0 * x[2] + 3.0 * x[3])
-@constraint(model, 0.3 * x[1] + 0.5 * x[2] + 1.0 * x[3] <= 3.2)
+
+@constraint(model, 0.3 * x[1] + 0.5 * x[2] + 1.0 * x[3] <= 1.6)
 
 optimize!(model)
 
 solution_summary(model)
+```
+
+## Compiler Flags
+
+### Architecture
+```@docs
+ToQUBO.ARCHITECTURE
+```
+
+### Quadratization
+```@docs
+ToQUBO.QUADRATIZE
+ToQUBO.QUADRATIZATION_METHOD
+ToQUBO.STABLE_QUADRATIZATION
+```
+
+### Variable & Constraint Encoding
+```@docs
+ToQUBO.VARIABLE_ENCODING_METHOD
+ToQUBO.VARIABLE_ENCODING_PENALTY
+ToQUBO.CONSTRAINT_ENCODING_PENALTY
 ```