Merge pull request #4 from psrenergy/px/interface

Update Interface
JuliaQUBO · Oct 16, 2023 · f6b09fb · f6b09fb · pedromxavier · Oct 16, 2023
2 parents 5e1243a + 1458a60
commit f6b09fb
Show file tree

Hide file tree

Showing 68 changed files with 2,317 additions and 1,635 deletions.
diff --git a/.github/workflows/benchmark.yml b/.github/workflows/benchmark.yml
@@ -1,7 +1,7 @@
 name: Benchmark
 on:
-  pull_request:
-    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+
 jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}

diff --git a/Project.toml b/Project.toml
@@ -1,12 +1,13 @@
-name    = "PseudoBooleanOptimization"
-uuid    = "c8fa9a04-bc42-452d-8558-dc51757be744"
+name = "PseudoBooleanOptimization"
+uuid = "c8fa9a04-bc42-452d-8558-dc51757be744"
 authors = ["pedromxavier <[email protected]>"]
 version = "0.1.1"
 
 [deps]
-LinearAlgebra      = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MutableArithmetics = "d8a4904e-b15c-11e9-3269-09a3773c0cb0"
-Random             = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+TOML = "fa267f1f-6049-4f14-aa54-33bafae1ed76"
 
 [compat]
 MutableArithmetics = "1.3"

diff --git a/benchmark/benchmark.jl b/benchmark/benchmark.jl
@@ -15,6 +15,8 @@ const PBO = PseudoBooleanOptimization
 
 Random.seed!(0)
 
+erste(f) = f isa Tuple ? first(f) : f
+
 const SUITE = BenchmarkGroup()
 
 include("suites/constructors.jl")

diff --git a/benchmark/suites/operators.jl b/benchmark/suites/operators.jl
@@ -16,15 +16,15 @@ function benchmark_add!(suite, ::Type{F}) where {V,T,F<:PBO.AbstractFunction{V,T
     suite["operators"]["+"]["small"] = @benchmarkable(
         f + g;
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10)
-            g = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10)
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10))
+            g = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10))
         end
     )
     suite["operators"]["+"]["large"] = @benchmarkable(
         f + g;
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100)
-            g = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100)
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100))
+            g = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100))
         end
     )
 
@@ -36,15 +36,15 @@ function benchmark_sub!(suite, ::Type{F}) where {V,T,F<:PBO.AbstractFunction{V,T
     suite["operators"]["-"]["small"] = @benchmarkable(
         f - g;
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10)
-            g = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10)
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10))
+            g = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10))
         end
     )
     suite["operators"]["-"]["large"] = @benchmarkable(
         f - g;
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100)
-            g = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100)
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100))
+            g = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100))
         end
     )
 
@@ -56,15 +56,15 @@ function benchmark_mul!(suite, ::Type{F}) where {V,T,F<:PBO.AbstractFunction{V,T
     suite["operators"]["*"]["small"] = @benchmarkable(
         f * g;
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10)
-            g = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10)
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10))
+            g = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10))
         end
     )
     suite["operators"]["*"]["large"] = @benchmarkable(
         f * g;
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 32)
-            g = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 32)
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 32))
+            g = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 32))
         end
     )
 
@@ -76,15 +76,15 @@ function benchmark_dict_evaluation!(suite, ::Type{F}) where {V,T,F<:PBO.Abstract
     suite["operators"]["dict-evaluation"]["small"] = @benchmarkable(
         f(x);
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10)
-            x = Dict{Int,Int}(i => rand((0, 1)) for i = 1:10)
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10))
+            x = erste(Dict{Int,Int}(i => rand((0, 1)) for i = 1:10))
         end
     )
     suite["operators"]["dict-evaluation"]["large"] = @benchmarkable(
         f(x);
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100)
-            x = Dict{Int,Int}(i => rand((0, 1)) for i = 1:100)
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100))
+            x = erste(Dict{Int,Int}(i => rand((0, 1)) for i = 1:100))
         end
     )
 
@@ -96,15 +96,15 @@ function benchmark_set_evaluation!(suite, ::Type{F}) where {V,T,F<:PBO.AbstractF
     suite["operators"]["set-evaluation"]["small"] = @benchmarkable(
         f(x);
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10)
-            x = Set{Int}(i for i = 1:10 if rand(Bool))
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 10))
+            x = erste(Set{Int}(i for i = 1:10 if rand(Bool)))
         end
     )
     suite["operators"]["set-evaluation"]["large"] = @benchmarkable(
         f(x);
         setup = begin
-            f = PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100)
-            x = Set{Int}(i for i = 1:100 if rand(Bool))
+            f = erste(PBO.sherrington_kirkpatrick(Random.GLOBAL_RNG, $F, 100))
+            x = erste(Set{Int}(i for i = 1:100 if rand(Bool)))
         end
     )
 

diff --git a/benchmark/suites/quadratization.jl b/benchmark/suites/quadratization.jl
@@ -4,13 +4,13 @@ function benchmark_quadratization!(suite, ::Type{F}) where {V,T,F<:PBO.AbstractF
     suite["quadratization"]["automatic"]["small"] = @benchmarkable(
         PBO.quadratize(f, PBO.Quadratization{PBO.INFER}());
         setup = begin
-            f = PBO.k_regular_k_xorsat(Random.GLOBAL_RNG, $F, 10, 3; quad = nothing)
+            f = erste(PBO.k_regular_k_xorsat(Random.GLOBAL_RNG, $F, 10, 3; quad = nothing))
         end
     )
     suite["quadratization"]["automatic"]["large"] = @benchmarkable(
         PBO.quadratize(f, PBO.Quadratization{PBO.INFER}());
         setup = begin
-            f = PBO.k_regular_k_xorsat(Random.GLOBAL_RNG, $F, 100, 3; quad = nothing)
+            f = erste(PBO.k_regular_k_xorsat(Random.GLOBAL_RNG, $F, 100, 3; quad = nothing))
         end
     )
 

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -2,3 +2,6 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterDiagrams = "a106ebf2-4182-4cba-90d4-44cd3cc36e85"
 PseudoBooleanOptimization = "c8fa9a04-bc42-452d-8558-dc51757be744"
+
+[compat]
+Documenter = "1"
diff --git a/docs/make.jl b/docs/make.jl
@@ -3,28 +3,44 @@ using PseudoBooleanOptimization
 const PBO = PseudoBooleanOptimization
 
 # Set up to run docstrings with jldoctest
-DocMeta.setdocmeta!(PseudoBooleanOptimization, :DocTestSetup, :(using PseudoBooleanOptimization); recursive = true)
+DocMeta.setdocmeta!(
+    PseudoBooleanOptimization,
+    :DocTestSetup,
+    :(using PseudoBooleanOptimization);
+    recursive = true,
+)
 
 makedocs(;
-    modules = [PseudoBooleanOptimization],
-    doctest = true,
-    clean = true,
-    format = Documenter.HTML(
-        assets = ["assets/extra_styles.css", "assets/favicon.ico"],
-        mathengine = Documenter.KaTeX(),
+    modules  = [PseudoBooleanOptimization],
+    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 = "PseudoBooleanOptimization.jl",
-    authors = "Pedro Maciel Xavier",
-    pages = [
-        "Home"           => "index.md",
-        "Quadratization" => "quadratization.md"
+    authors  = "Pedro Maciel Xavier",
+    pages    = [ # 
+        "Home"          => "index.md",
+        "Manual"        => [
+            "manual/1-intro.md",
+            "manual/2-function.md",
+            "manual/3-operators.md",
+            "manual/4-quadratization.md",
+            "manual/5-synthesis.md",
+        ],
+        "API Reference" => "api.md",
     ],
-    workdir = @__DIR__,
+    workdir  = @__DIR__
 )
 
 if "--skip-deploy" ∈ ARGS
     @warn "Skipping deployment"
 else
-    deploydocs(repo = raw"github.com/pedromxavier/PseudoBooleanOptimization.jl.git", push_preview = true)
+    deploydocs(
+        repo = raw"github.com/pedromxavier/PseudoBooleanOptimization.jl.git",
+        push_preview = true,
+    )
 end
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -0,0 +1,82 @@
+# API Reference
+
+## Variables
+
+```@docs
+PBO.varlt
+PBO.varmul
+PBO.varmap
+PBO.vargen
+PBO.varshow
+```
+
+## Terms
+
+```@docs
+PBO.term
+PBO.term_head
+PBO.term_tail
+```
+
+## Functions
+
+```@docs
+PBO.AbstractPBF
+PBO.PBF
+PBO.data
+```
+
+## Analysis
+
+```@docs
+PBO.isconstant
+PBO.degree
+```
+
+```@docs
+PBO.lowerbound
+PBO.upperbound
+PBO.bounds
+PBO.mingap
+PBO.maxgap
+```
+
+```@docs
+PBO.derivative
+PBO.gradient
+PBO.residual
+```
+
+```@docs
+PBO.discretize
+PBO.discretize!
+```
+
+```@docs
+PBO.relaxedgcd
+```
+
+## Quadratization
+
+```@docs
+PBO.quadratize
+PBO.quadratize!
+PBO.infer_quadratization
+```
+
+```@docs
+PBO.INFER
+PBO.DEFAULT
+PBO.PTR_BG
+PBO.NTR_KZFD
+```
+
+## Synthesis
+
+```@docs
+PBO.wishart
+PBO.sherrington_kirkpatrick
+PBO.not_all_equal_3sat
+PBO.k_regular_k_xorsat
+PBO.r_regular_k_xorsat
+```
diff --git a/docs/src/assets/README.md b/docs/src/assets/README.md
@@ -12,14 +12,15 @@ The colors were chosen according to *Julia's Reference for logo graphics*[^Julia
 Text color matches renders fairly well in both light and dark background themes.
 
 ## Typography
+
 The *MADETYPE Sunflower*[^Sunflower] font was chosen.
 It was converted to a SVG path using the *Google Font to Svg Path*[^DanMarshall] online tool.
 
 [^Julia]:
     [github.com/JuliaLang/julia-logo-graphics](https://github.com/JuliaLang/julia-logo-graphics/)
 
 [^Sunflower]:
-    [Licensed](/docs/src/assets/fonts/Sunflower-LICENSE.txt) by the authors for use in this project
+    [Licensed](./fonts/Sunflower-LICENSE.txt) by the authors for use in this project
 
 [^DanMarshall]:
     [danmarshall.github.io/google-font-to-svg-path](https://danmarshall.github.io/google-font-to-svg-path/)
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -7,14 +7,26 @@ f(\mathbf{x}) = \sum_{\omega \subseteq [n]} c_{\omega} \prod_{j \in \omega} x_{j
 ## Getting Started
 
 ```@example
-using PseudoBooleanOptimization
-const PBO = PseudoBooleanOptimization
+import PseudoBooleanOptimization as PBO
 
 f = PBO.PBF{Symbol,Float64}(
     :x       => 3.0,
     (:y, :z) => 4.0,
     (:x, :w) => 1.0,
+    -100.0,
 )
 
-g = f^2 - f
+g = f^2 - 2f
+```
+
+## Table of Contents
+
+```@contents
+Pages = [
+    "manual/1-intro.md",
+    "manual/2-function.md",
+    "manual/3-operators.md",
+    "manual/4-quadratization.md",
+]
+Depth = 2
 ```
diff --git a/docs/src/manual/1-intro.md b/docs/src/manual/1-intro.md
@@ -0,0 +1,3 @@
+# PseudoBooleanOptimization.jl Manual
+
+## Introduction
diff --git a/docs/src/manual/2-function.md b/docs/src/manual/2-function.md
@@ -0,0 +1,9 @@
+# Pseudo-Boolean functions
+
+Let `f: \mathbb{B}^{n} \to \mathbb{R}`. Then `f` can be written as
+
+```math
+f(\mathbf{x}) = \sum_{\omega \subseteq [n]} c_{\omega} \prod_{j \in \omega} x_{j}
+```
+
+where ``c_{\omega} \in \mathbb{R}`` and ``x_{j} \in \{ 0, 1 \}`` for all ``j \in [n] = \{ 1, \dots, n \}``.
diff --git a/docs/src/manual/3-operators.md b/docs/src/manual/3-operators.md
@@ -0,0 +1,5 @@
+# Operations with pseudo-Boolean functions
+
+## Arithmetic operations
+
+The arithmetic operations `+`, `-`, `*`, `/`, `^` are defined for pseudo-Boolean functions. The result of an arithmetic operation is a pseudo-Boolean function.
diff --git a/docs/src/manual/4-quadratization.md b/docs/src/manual/4-quadratization.md
@@ -0,0 +1,7 @@
+# Quadratization
+
+A Quadratization is a mapping ``\mathcal{Q}\{f\}: \mathsrc{F} \to \mathsrc{F}^{2}`` such that
+
+```math
+\min_{\mathbf{y}} \mathsrc{Q}\{f\}(\mathbf{x}, \mathbf{y}) = f(\mathbf{x}) ~\forall \mathbf{x} \in \mathbb{B}^{n}.~\forall f \in \mathsrc{F}.
+```
diff --git a/docs/src/manual/5-synthesis.md b/docs/src/manual/5-synthesis.md
@@ -0,0 +1,7 @@
+# Synthetic Problem Generation
+
+```@example synthesis
+import PseudoBooleanOptimization as PBO
+
+f = PBO.wishart(PBO.PBF{Int,Float64}, 3, 5)
+```
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# PseudoBooleanOptimization.jl Manual

		## Introduction