Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Write Docs for v0.1.5 #64

Merged
merged 42 commits into from
Apr 20, 2023
Merged
Changes from 5 commits
Commits
Show all changes
42 commits
Select commit Hold shift + click to select a range
be28607
Organize manual & booklet chapters in separate files
pedromxavier Feb 16, 2023
604620b
Fix authors' names
pedromxavier Feb 16, 2023
aff1f3b
Update text + Fix typos
pedromxavier Feb 16, 2023
2b29b29
Update text [no ci]
pedromxavier Feb 16, 2023
433488c
Update text
pedromxavier Feb 16, 2023
20958a3
Fix citation
pedromxavier Feb 16, 2023
6706d58
Fix `make.jl`
pedromxavier Feb 16, 2023
b615572
Add example to Quick Start
pedromxavier Feb 16, 2023
2b596f0
Update docs(qubo and quadratization)
pedroripper Feb 16, 2023
34d32bc
Add docs for quadratization and fix typos
pedroripper Feb 17, 2023
34f7a77
Merge branch 'master' into px/docs
pedromxavier Feb 23, 2023
e8eee66
Add double brackets to title in TeX citation
pedromxavier Feb 23, 2023
afc69be
Enhance quadatization methods' docs
pedromxavier Feb 23, 2023
43cc809
Minor Fix
pedromxavier Feb 23, 2023
72be8fa
Merge branch 'master' into px/docs
pedromxavier Feb 23, 2023
3df0a05
Update docs
pedromxavier Feb 24, 2023
1152620
Center images & diagrams
pedromxavier Feb 24, 2023
80ee186
Fix `extra_styles.css`
pedromxavier Feb 24, 2023
7eb1ae4
Add encoding intro
pedroripper Feb 24, 2023
e56193c
Update docs for constraint encoding
pedroripper Feb 28, 2023
a7786cc
Update docs
pedromxavier Mar 17, 2023
7791aec
Merge branch 'px/docs' of https://github.com/psrenergy/ToQUBO.jl into…
pedromxavier Mar 17, 2023
11383fb
Update docs [no ci]
pedroripper Apr 3, 2023
44b3b9b
Update README [no ci]
pedromxavier Apr 5, 2023
ea009d9
Replace `Anneal -> QUBODrivers`
pedromxavier Apr 5, 2023
b99166e
Add Portfolio Optimization tutorial
pedroripper Apr 14, 2023
777680a
Merge branch 'master' into px/docs
pedroripper Apr 14, 2023
95239a8
Update docs dependencies
pedromxavier Apr 17, 2023
e783c57
Polish portfolio optimization example
pedromxavier Apr 17, 2023
e0d68b1
Enhance plots
pedromxavier Apr 17, 2023
38d240f
Add text
pedromxavier Apr 17, 2023
a0618c4
Update dependencies
pedromxavier Apr 17, 2023
263b5b8
Update docs action
pedromxavier Apr 17, 2023
8081763
Enhance text [incomplete]
pedromxavier Apr 17, 2023
b27628f
Rewrite `QUBO` chapter
pedromxavier Apr 18, 2023
bfa79e1
Fix text
pedromxavier Apr 18, 2023
bc0ac56
Rephrase
pedromxavier Apr 18, 2023
1123961
Update docs
pedroripper Apr 19, 2023
f3eb784
Update docs
pedroripper Apr 19, 2023
2940896
Add encoding expansions
pedromxavier Apr 19, 2023
cad8e12
Update text
pedromxavier Apr 20, 2023
65b0441
Add explanation on encoding error
pedromxavier Apr 20, 2023
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -136,12 +136,12 @@ If you think this list is incomplete, consider creating an [Issue](https://githu
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},
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},
publisher = {Zenodo},
version = {v0.1.0},
version = {v0.1.5},
doi = {10.5281/zenodo.6387592},
url = {https://doi.org/10.5281/zenodo.6387592}
}
39 changes: 26 additions & 13 deletions docs/make.jl
Original file line number Diff line number Diff line change
@@ -7,24 +7,37 @@ 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"],
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",
"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",
"The Compiler" => "booklet/6-compiler.md"
"Solvers" => "booklet/7-solvers.md",
]
],
workdir="."
)
121 changes: 0 additions & 121 deletions docs/src/booklet.md

This file was deleted.

11 changes: 11 additions & 0 deletions docs/src/booklet/1-intro.md
Original file line number Diff line number Diff line change
@@ -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"]
Depth = 2
```
22 changes: 22 additions & 0 deletions docs/src/booklet/2-qubo.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# 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?

!!! warning "Work in progress"
We hope to write this part of the documentation soon.
Please come back later!

```@docs
ToQUBO.isqubo
ToQUBO.toqubo
ToQUBO.toqubo!
```
23 changes: 23 additions & 0 deletions docs/src/booklet/3-pbo.md
Original file line number Diff line number Diff line change
@@ -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.
25 changes: 25 additions & 0 deletions docs/src/booklet/4-encoding.md
Original file line number Diff line number Diff line change
@@ -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
21 changes: 21 additions & 0 deletions docs/src/booklet/5-virtual.md
Original file line number Diff line number Diff line change
@@ -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 encoding information for later expansion and evaluation.

```@docs
ToQUBO.VirtualVariable
ToQUBO.encode!
```
18 changes: 18 additions & 0 deletions docs/src/booklet/6-compiler.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# The Compiler

!!! warning "Work in progress"
We hope to write this part of the documentation soon.
Please come back later!

## Compilation Steps

```@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!
```
29 changes: 29 additions & 0 deletions docs/src/booklet/7-solvers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
# QUBO Solvers

## Solvers, Annealers & Samplers
[`ToQUBO.jl`](https://github.com/psrenergy/ToQUBO.jl)'s main goal is to make use of parameterized stochastic optimization solvers, particularly those relying on non-conventional hardware such as *Quantum Annealing* and other *Ising Machines*.
A few `MOI`-compliant interfaces for annealers and samplers are bundled within [`ToQUBO.jl`](https://github.com/psrenergy/ToQUBO.jl) via the [`Anneal.jl`](https://github.com/psrenergy/Anneal.jl) companion package.
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 configurations you would find using the Quantum API.
Its adoption is recommended for basic usage, tests, and research due to its robustness, simplicity and ease of use.
The [`DWaveNeal.jl`](https://github.com/psrenergy/DWaveNeal.jl) package uses [`Anneal.jl`](https://github.com/psrenergy/Anneal.jl) to deliver an interface to this sampler.

## Quantum Annealing
Interfacing with [D-Wave](https://www.dwavesys.com/)'s quantum annealer is one of the milestones we expect to achieve with this package.
Like other proprietary optimization resources such as [Gurobi](https://gurobi.com), [FICO® Xpress](https://www.fico.com/en/products/fico-xpress-solver) and [IBM® CPLEX®](https://www.ibm.com/products/ilog-cplex-optimization-studio/cplex-optimizer), this requires licensing and extra steps are needed to get an access token.
In a first moment, for those willing to get started, the [`DWaveNeal.jl`](https://github.com/psrenergy/DWaveNeal.jl) optimizer might be enough to learn the ropes.

## 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 (Exhaustive 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 at most ``\sym 20`` variables should be provided since visiting ``2^{20} \sym 10^{6}`` can already take up to a few seconds.

## Mixed-Integer Quadratic Programming
The most accessible alternative to the forementioned methods are Mixed-Integer Quadratic Programming (MIQP) solvers such as [Gurobi](https://github.com/jump-dev/Gurobi.jl), [CPLEX](https://github.com/jump-dev/CPLEX.jl), [SCIP](https://github.com/scipopt/SCIP.jl) and [BARON](https://github.com/jump-dev/BARON.jl).
These are not intended to be of regular use alongside [`ToQUBO.jl`](https://github.com/psrenergy/ToQUBO.jl) since providing a QUBO reformulation will usually make things harder for non-specialized solvers.
Yet, there are still a few cases where they may be suitable, such as tests, benchmarks, or any other situation where global optimality is a must.
2 changes: 1 addition & 1 deletion docs/src/examples/prime_factorization.md
Original file line number Diff line number Diff line change
@@ -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)
23 changes: 4 additions & 19 deletions docs/src/manual.md → docs/src/manual/1-start.md
Original file line number Diff line number Diff line change
@@ -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
```
5 changes: 5 additions & 0 deletions docs/src/manual/2-model.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# Running a Model

!!! warning "Work in progress"
We hope to write this part of the documentation soon.
Please come back later!
Loading