Merge pull request #8 from psrenergy/px/qubotools-v1

Update `QUBOTools -> v0.9; QUBODrivers -> 0.3`

.github/workflows/ci.yml

@@ -13,10 +13,10 @@ jobs:
       fail-fast: false
       matrix:
         include:
-          - version: '1'
+          - version: '1.9'
             os: ubuntu-latest
             arch: x64
-          - version: '1'
+          - version: '1.9'
             os: windows-latest
             arch: x64
     steps:

.github/workflows/documentation.yml

@@ -14,7 +14,7 @@ jobs:
       - name: Setup Julia
         uses: julia-actions/setup-julia@latest
         with:
-          version: '1.6'
+          version: '1.9'
       - name: Develop QUBODrivers.jl
         run: julia --project=docs/ -e 'using Pkg; Pkg.develop(path=pwd())'
       - name: Build Package

Project.toml

@@ -1,21 +1,16 @@
-name    = "QUBODrivers"
-uuid    = "a3f166f7-2cd3-47b6-9e1e-6fbfe0449eb0"
-version = "0.2.0"
-authors = [
-    "pedromxavier <[email protected]>",
-    "pedroripper <[email protected]>",
-    "AndradeTiago <[email protected]>",
-    "joaquimg <[email protected]>",
-    "bernalde <[email protected]>",
-]
+name = "QUBODrivers"
+uuid = "a3f166f7-2cd3-47b6-9e1e-6fbfe0449eb0"
+authors = ["pedromxavier <[email protected]>", "pedroripper <[email protected]>", "AndradeTiago <[email protected]>", "joaquimg <[email protected]>", "bernalde <[email protected]>"]
+version = "0.3.0"
 
 [deps]
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
-QUBOTools        = "60eb5b62-0a39-4ddc-84c5-97d2adff9319"
-Random           = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
-Test             = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+QUBOTools = "60eb5b62-0a39-4ddc-84c5-97d2adff9319"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [compat]
 MathOptInterface = "1"
-QUBOTools        = "0.8"
-julia            = "1.6"
+QUBOTools = "~0.9"
+julia = "1.9"

docs/Project.toml

@@ -1,13 +1,14 @@
 [deps]
-Documenter       = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-JuMP             = "4076af6c-e467-56ae-b986-b466b2749572"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
-Plots            = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
-QUBOTools        = "60eb5b62-0a39-4ddc-84c5-97d2adff9319"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+QUBODrivers = "a3f166f7-2cd3-47b6-9e1e-6fbfe0449eb0"
+QUBOTools = "60eb5b62-0a39-4ddc-84c5-97d2adff9319"
 
 [compat]
-Documenter       = "0.27"
-JuMP             = "1"
+Documenter = "1"
+JuMP = "1"
 MathOptInterface = "1"
-Plots            = "1.38"
-QUBOTools        = "0.8"
+Plots = "1.38"
+QUBOTools = "0.9"

docs/make.jl

@@ -1,33 +1,42 @@
 using Documenter
 using QUBODrivers
-using QUBOTools
 
 # Set up to run docstrings with jldoctest
 DocMeta.setdocmeta!(QUBODrivers, :DocTestSetup, :(using QUBODrivers); recursive = true)
-DocMeta.setdocmeta!(QUBOTools, :DocTestSetup, :(using QUBOTools); recursive = true)
 
 makedocs(;
-    modules = [QUBODrivers],
-    doctest = true,
-    clean = true,
-    format = Documenter.HTML(
+    modules  = [QUBODrivers, QUBODrivers.QUBOTools],
+    doctest  = true,
+    clean    = true,
+    warnonly = [:missing_docs],
+    format   = Documenter.HTML(
         assets = ["assets/extra_styles.css"], #, "assets/favicon.ico"],
         mathengine = Documenter.KaTeX(),
         sidebar_sitename = false,
     ),
     sitename = "QUBODrivers.jl",
     authors = "Pedro Xavier and Pedro Ripper and Tiago Andrade and Joaquim Garcia and David Bernal",
     pages = [
-        "Home" => "index.md",
-        # "Manual" => "manual.md",
-        # "Examples" => "examples.md",
-        # "Samplers" => "samplers.md",
+        "Home"   => "index.md",
+        "Manual" => [
+            "Introduction"  => "manual/1-intro.md",
+            "Solving QUBO"  => "manual/2-solve.md",
+            "Samplers"      => "manual/3-samplers.md",
+            "Sampler Setup" => "manual/4-setup.md",
+            "Test Suite"    => "manual/5-tests.md",
+            "Benchmarking"  => "manual/6-benchmarks.md",
+        ],
+        "Booklet" => [
+            "Itroduction"       => "booklet/1-intro.md",
+            "Sampler Interface" => "booklet/2-interface.md",
+            "Attribute System"  => "booklet/3-attributes.md",
+        ],
     ],
-    workdir = @__DIR__,
+    workdir = @__DIR__
 )
 
 if "--skip-deploy" ∈ ARGS
     @warn "Skipping deployment"
 else
-    deploydocs(repo = raw"github.com/psrenergy/QUBODrivers.jl.git", push_preview = true)
+    deploydocs(; repo = raw"github.com/psrenergy/QUBODrivers.jl.git", push_preview = true)
 end

docs/src/booklet/1-intro.md

@@ -0,0 +1,12 @@
+# QUBODrivers.jl Booklet
+
+This booklet aims to provide an advanced overview of the QUBODrivers.jl package, delving into the details of the package's inner workings.
+It is meant to discuss the package's design choices and provide a guide for developers who wish not only to implement new interfaces but also to extend the package's functionality.
+Reading this booklet is not required to use the package, but it is strongly recommended for those who wish to contribute to the project.
+
+## Table of Contents
+
+```@contents
+Pages = ["2-interface.md", "3-attributes.md"]
+Depth = 2
+```

docs/src/booklet/2-interface.md

@@ -0,0 +1,9 @@
+# Sampler Interface
+
+```@docs
+QUBODrivers.AbstractSampler
+```
+
+```@docs
+QUBODrivers.set_model!
+```

docs/src/booklet/3-attributes.md

@@ -0,0 +1,61 @@
+# Attributes
+
+## API
+
+```@docs
+QUBODrivers.SamplerAttribute
+```
+
+```@docs
+QUBODrivers.RawSamplerAttribute
+QUBODrivers.@raw_attr_str
+```
+
+```@docs
+QUBODrivers.get_raw_attr
+QUBODrivers.set_raw_attr!
+QUBODrivers.default_raw_attr
+```
+
+## An advanced example
+
+```julia
+module SuperSampler
+
+import QUBODrivers
+import QUBODrivers: QUBOTools
+import MathOptInterface as MOI
+
+QUBODrivers.@setup Optimizer begin
+    name    = "Super Sampler"
+    version = v"1.0.2"
+    attributes = begin
+        NumberOfReads["num_reads"]::Integer  = 100_000
+        SuperAttribute["super_attr"]::String = "super"
+    end
+end
+
+function MOI.set(sampler::Optimizer, attr::raw_attr"", value)
+    if !(value isa Integer)
+        error("'num_reads' must be an integer")
+    else
+        QUBODrivers.set_raw_attr!(sampler, attr, value)
+    end
+
+    return nothing
+end
+
+function MOI.set(sampler::Optimizer, attr::raw_attr"super_attr", value)
+    if !(value isa AbstractString)
+        error("'super_attr' must be a string")
+    elseif !(value ∈ ("super", "ultra", "mega"))
+        error("'super_attr' must be one of the following: 'super', 'ultra', 'mega'")
+    else
+        QUBODrivers.set_raw_attr!(sampler, attr, value)
+    end
+
+    return nothing
+end
+
+end # SuperSampler module
+```

docs/src/index.md

@@ -1,21 +1,24 @@
 # QUBODrivers.jl Documentation
 
 ## Introduction
+
 This package aims to provide a common [MOI](https://github.com/jump-dev/MathOptInterface.jl)-compliant API for [QUBO](https://en.wikipedia.org/wiki/Quadratic_unconstrained_binary_optimization) Sampling & Annealing machines.
 It also contains a few utility samplers and testing tools for performance comparison, sanity checks and basic analysis features.
 
 ## Quick Start
 
 ### Installation
+
 [QUBODrivers.jl](https://github.com/psrenergy/QUBODrivers.jl) is registered in Julia's General Registry and is available for download using the standard package manager.
 
 ```julia-repl
 julia> import Pkg
 
 julia> Pkg.add("QUBODrivers")
-``` 
+```
 
 ### Example
+
 ```@example
 using JuMP
 using QUBODrivers
@@ -36,22 +39,21 @@ optimize!(model)
 for i = 1:result_count(model)
     xi = value.(x; result=i)
     yi = objective_value(model; result=i)
-    ri = reads(model; result=i)
 
-    println("f($xi) = $yi ($ri)")
+    println("f($xi) = $yi")
 end
 ```
 
 <!-- ## Citing QUBODrivers.jl
 ```tex
 @software{QUBODrivers.jl:2023,
-  author = {Pedro Xavier and Pedro Ripper and Tiago Andrade and Joaquim Garcia and David Bernal},
-  title        = {QUBODrivers.jl},
-  month        = {apr},
-  year         = {2023},
-  publisher    = {Zenodo},
-  version      = {v0.1.0},
-  doi          = {10.5281/zenodo.6390515},
-  url          = {https://doi.org/10.5281/zenodo.6390515}
+  author    = {Pedro Xavier and Pedro Ripper and Tiago Andrade and Joaquim Garcia and David Bernal},
+  title     = {QUBODrivers.jl},
+  month     = {apr},
+  year      = {2023},
+  publisher = {Zenodo},
+  version   = {v0.1.0},
+  doi       = {10.5281/zenodo.6390515},
+  url       = {https://doi.org/10.5281/zenodo.6390515}
 }
 ``` -->