diff --git a/.github/workflows/documentation.yml b/.github/workflows/docs.yml similarity index 91% rename from .github/workflows/documentation.yml rename to .github/workflows/docs.yml index ac80d3e..3feee67 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/docs.yml @@ -19,4 +19,4 @@ jobs: - name: Build and deploy env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token - run: julia --project=docs/ docs/make_qubo.jl \ No newline at end of file + run: julia --project=docs/ docs/make.jl \ No newline at end of file diff --git a/.github/workflows/multi_documentation.yml b/.github/workflows/multidocs.yml similarity index 91% rename from .github/workflows/multi_documentation.yml rename to .github/workflows/multidocs.yml index 1621ec5..dbd691b 100644 --- a/.github/workflows/multi_documentation.yml +++ b/.github/workflows/multidocs.yml @@ -17,4 +17,4 @@ jobs: - name: Build and deploy env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token - run: julia --project=docs/ docs/make.jl \ No newline at end of file + run: julia --project=docs/ docs/multimake.jl \ No newline at end of file diff --git a/docs/make.jl b/docs/make.jl index 9fc7554..e5d243d 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -1,79 +1,26 @@ using Documenter -using MultiDocumenter -temp_dir = mktempdir() - - -docs = [ - MultiDocumenter.MultiDocRef( - upstream = joinpath(temp_dir, "QUBO.jl"), - path = "QUBO.jl", - name = "QUBO.jl", - giturl = "https://github.com/psrenergy/QUBO.jl.git", - branch ="gh-pages" - ), - MultiDocumenter.MultiDocRef( - upstream = joinpath(temp_dir, "ToQUBO.jl"), - path = "ToQUBO.jl", - name = "ToQUBO.jl", - giturl = "https://github.com/psrenergy/ToQUBO.jl.git", - ), - MultiDocumenter.MultiDocRef( - upstream = joinpath(temp_dir, "QUBODrivers.jl"), - path = "QUBODrivers.jl", - name = "QUBODrivers.jl", - giturl = "https://github.com/psrenergy/QUBODrivers.jl.git", - ), - MultiDocumenter.MultiDocRef( - upstream = joinpath(temp_dir, "QUBOTools.jl"), - path = "QUBOTools.jl", - name = "QUBOTools.jl", - giturl = "https://github.com/psrenergy/QUBOTools.jl.git", +makedocs(; + doctest=true, + clean=true, + format=Documenter.HTML( + assets=[ + "assets/extra_styles.css", + # "assets/favicon.ico", + ], + mathengine=Documenter.KaTeX(), + sidebar_sitename=false, ), - -] - -outpath = mktempdir() - - -MultiDocumenter.make( - outpath, - docs; - search_engine = MultiDocumenter.SearchConfig( - index_versions = ["stable"], - engine = MultiDocumenter.FlexSearch - ), - rootpath = "/QUBO.jl", + sitename="QUBO.jl", + authors="Pedro Xavier and Pedro Ripper and Tiago Andrade and Joaquim Garcia and David Bernal", + pages=[ + "Home" => "index.md" + ], + workdir="." ) -gitroot = normpath(joinpath(@__DIR__, "..")) -run(`git pull`) -outbranch = "gh-multi-pages" -has_outbranch = true -if !success(`git checkout $outbranch`) - has_outbranch = false - if !success(`git checkout -b $outbranch`) - @error "Cannot create new orphaned branch $outbranch." - exit(1) - end -end - -for file in readdir(gitroot; join = true) - endswith(file, ".git") && continue - rm(file; force = true, recursive = true) -end -for file in readdir(outpath) - cp(joinpath(outpath, file), joinpath(gitroot, file)) -end -run(`git add .`) -if success(`git commit -m 'Aggregate documentation'`) - @info "Pushing updated documentation." - if has_outbranch - run(`git push`) - else - run(`git push -u origin $outbranch`) - end - run(`git checkout master`) +if "--skip-deploy" ∈ ARGS + @warn "Skipping deployment" else - @info "No changes to aggregated documentation." + deploydocs(raw"github.com/psrenergy/QUBO.jl.git", push_preview=true) end \ No newline at end of file diff --git a/docs/make_qubo.jl b/docs/make_qubo.jl deleted file mode 100644 index a34abf7..0000000 --- a/docs/make_qubo.jl +++ /dev/null @@ -1,26 +0,0 @@ -using Documenter - -makedocs(; - doctest=true, - clean=true, - format=Documenter.HTML( - # assets = ["assets/extra_styles.css", "assets/favicon.ico"], - mathengine=Documenter.MathJax2(), - sidebar_sitename=false, - ), - sitename="QUBO.jl", - authors="Pedro Xavier and Pedro Ripper and Tiago Andrade and Joaquim Garcia and David Bernal", - pages=[ - "Home" => "index.md" - ], - workdir="." -) - -if "--skip-deploy" ∈ ARGS - @warn "Skipping deployment" -else - deploydocs( - repo=raw"github.com/psrenergy/QUBO.jl.git", - push_preview = true - ) -end \ No newline at end of file diff --git a/docs/multimake.jl b/docs/multimake.jl new file mode 100644 index 0000000..05080b9 --- /dev/null +++ b/docs/multimake.jl @@ -0,0 +1,103 @@ +using Documenter +using MultiDocumenter + +temp_dir = mktempdir() + +docs = [ + MultiDocumenter.MultiDocRef( + upstream=joinpath(temp_dir, "QUBO.jl"), + path="QUBO.jl", + name="QUBO.jl", + giturl="https://github.com/psrenergy/QUBO.jl.git", + branch="gh-pages", + ), + MultiDocumenter.MultiDocRef( + upstream=joinpath(temp_dir, "ToQUBO.jl"), + path="ToQUBO.jl", + name="ToQUBO.jl", + giturl="https://github.com/psrenergy/ToQUBO.jl.git", + branch="gh-pages", + ), + MultiDocumenter.MultiDocRef( + upstream=joinpath(temp_dir, "QUBODrivers.jl"), + path="QUBODrivers.jl", + name="QUBODrivers.jl", + giturl="https://github.com/psrenergy/QUBODrivers.jl.git", + branch="gh-pages", + ), + MultiDocumenter.MultiDocRef( + upstream=joinpath(temp_dir, "QUBOTools.jl"), + path="QUBOTools.jl", + name="QUBOTools.jl", + giturl="https://github.com/psrenergy/QUBOTools.jl.git", + branch="gh-pages", + ), +] + +function buildmultidocs(path::AbstractString, docs) + MultiDocumenter.make( + path, + docs; + search_engine=MultiDocumenter.SearchConfig( + index_versions=["stable"], + engine=MultiDocumenter.FlexSearch + ), + rootpath="/QUBO.jl" + ) + + return nothing +end + +function deploymultidocs(path::AbstractString; branch::String="gh-multi-pages", main::String="main") + root_path = normpath(joinpath(@__DIR__, "..")) + + run(`git pull`) + + has_branch = true + + if !success(`git checkout $branch`) + has_branch = false + if !success(`git checkout -b $branch`) + @error "Cannot create new orphaned branch $branch" + exit(1) + end + end + + for file in readdir(root_path; join=true) + endswith(file, ".git") && continue + rm(file; force=true, recursive=true) + end + + for file in readdir(path) + cp(joinpath(path, file), joinpath(root_path, file)) + end + + run(`git add .`) + + if success(`git commit -m 'Aggregate documentation'`) + @info "Pushing updated documentation" + + if has_branch + run(`git push`) + else + run(`git push -u origin $branch`) + end + + run(`git checkout $main`) + else + @info "No changes to aggregated documentation" + end + + return nothing +end + +# creates if not exists +build_path = mkpath(joinpath(@__DIR__, "build_path")) + +buildmultidocs(build_path, docs) + +if "--skip-deploy" ∈ ARGS + @warn "Skipping deployment" +else + deploymultidocs(build_path; main="master") +end \ No newline at end of file diff --git a/docs/src/index.md b/docs/src/index.md index 9f2af8e..cf73b77 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -5,23 +5,24 @@ `QUBO.jl` is an all-in-one package for working with QUBO formulations in [JuMP](https://github.com/jump-dev/JuMP.jl) and interfacing with QUBO solvers. This project aggregates three complementary packages: [`ToQUBO.jl`](https://github.com/psrenergy/ToQUBO.jl), [`QUBODrivers.jl`](https://github.com/psrenergy/QUBODrivers.jl) and [`QUBOTools.jl`](https://github.com/psrenergy/QUBOTools.jl). -## What is a QUBO? +## QUBO? QUBO is an acronym for *Quadratic Unconstrained Binary Optimization*. So every QUBO problem is comprised of: -- an objective function at most quadratic +- a linear or quadratic objective function - no constraints - binary variables -We can represent a QUBO problem as follows. +We can represent such problem as follows: ```math \begin{array}{rl} \min & \mathbf{x}' Q\,\mathbf{x} \\ - \mathrm{s.t.} & \mathbf{x} \in \mathbb{B}^{n} + \textrm{s.t.} & \mathbf{x} \in \mathbb{B}^{n} \end{array} ``` -QUBOs are suited for representing non-convex global optimization problems. With that said, the significant advances in computing systems and algorithms specialized for sampling QUBOs have contributed to their popularity. +QUBOs are suited for representing non-convex global optimization problems. +With that said, the significant advances in computing systems and algorithms specialized for sampling QUBOs have contributed to their popularity. Some of the paradigms that stand out for running QUBOs are quantum gate-based optimization algorithms (QAOA and VQE), quantum annealers and hardware-accelerated platforms (Coherent Ising Machines and Simulated Bifurcation Machines). @@ -46,10 +47,8 @@ julia> ]add https://github.com/psrenergy/QUBO.jl#master ### Example ```julia -using QUBO using JuMP -ToQUBO = QUBO.ToQUBO -Anneal = QUBO.QUBODrivers +using QUBO model = Model(() -> ToQUBO.Optimizer(ExactSampler.Optimizer)) @@ -60,14 +59,15 @@ model = Model(() -> ToQUBO.Optimizer(ExactSampler.Optimizer)) optimize!(model) for i = 1:result_count(model) - xᵢ = value.(x, result = i) - yᵢ = objective_value(model, result = i) - println("f($xᵢ) = $yᵢ") + xi = value.(x, result = i) + yi = objective_value(model, result = i) + + println("f($xi) = $yi") end ``` - +```@raw html

QUBO.jl Packages

@@ -80,3 +80,4 @@ end QUBOTools.jl
+```