documentation setup

.github/dependabot.yml

@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

.github/workflows/documentation.yml

@@ -0,0 +1,31 @@
+docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write # needed to allow julia-actions/cache to proactively delete old caches that it has created
+      contents: write
+      statuses: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v1
+      - name: Configure doc environment
+        shell: julia --project=docs --color=yes {0}
+        run: |
+          using Pkg
+          Pkg.develop(PackageSpec(path=pwd()))
+          Pkg.instantiate()
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+      - name: Run doctests
+        shell: julia --project=docs --color=yes {0}
+        run: |
+          using Documenter: DocMeta, doctest
+          using Boscia
+          DocMeta.setdocmeta!(Boscia, :DocTestSetup, :(using Boscia); recursive=true)
+          doctest(Boscia)

.gitignore

@@ -1,3 +1,8 @@
+*.jl.*.cov
+*.jl.cov
+*.jl.mem
+/docs/Manifest.toml
+/docs/build/
 # Files generated by invoking Julia with --code-coverage
 *.jl.cov
 *.jl.*.cov

README.md

@@ -7,38 +7,50 @@ A solver for Mixed-Integer Convex Optimization that uses Frank-Wolfe methods for
 
 ## Overview
 
-The Boscia.jl solver combines (a variant of) the Frank-Wolfe algorithm with a branch-and-bound like algorithm to solve mixed-integer convex optimization problems of the form
-`min_{x ∈ C, x_I ∈ Z^n} f(x)`,
-where `f` is a differentiable convex function, `C` is a convex and compact set, and `I` is a set of indices of integral variables.
-
-They are especially useful when we have a method to optimize a linear function over `C` and the integrality constraints in a compuationally efficient way.
-`C` is specified using the MathOptInterface API or any DSL like JuMP implementing it.
-
-A paper presenting the package with mathematical explanations and numerous examples can be found here:
+The Boscia.jl solver uses a combination of a variant of the Frank-Wolfe algorithm and a branch-and-bound-like algorithm to solve mixed-integer convex optimization problems. These problems are of the form:
+**min_{x ∈ C, x_I ∈ Z^n} f(x)**,
+This approach is particularly effective if we can solve the mixed-integer linear minimization problem over C efficiently and handle the integer constraints. The set C is specified using the MathOptInterface API or any domain-specific language (DSL) like Julia for Mathematical Programming (**JuMP**) that implements this API.
+The paper presenting the package with mathematical explanations and numerous examples can be found here:
 
 > Convex integer optimization with Frank-Wolfe methods: [2208.11010](https://arxiv.org/abs/2208.11010)
 
 `Boscia.jl` uses [`FrankWolfe.jl`](https://github.com/ZIB-IOL/FrankWolfe.jl) for solving the convex subproblems, [`Bonobo.jl`](https://github.com/Wikunia/Bonobo.jl) for managing the search tree, and oracles optimizing linear functions over the feasible set, for instance calling [SCIP](https://scipopt.org) or any MOI-compatible solver to solve MIP subproblems.
 
 ## Installation
 
-Add the Boscia stable release with:
 
-```julia
-import Pkg
-Pkg.add("Boscia")
+Once you have installed Julia , From the Julia REPL, type ] to enter the Pkg REPL mode and run 
+```Boscia
+pkg > add Boscia
+
 ```
 
-Or get the latest master branch with:
+or alternatively via Pkg in any Julia code:
 ```julia
 import Pkg
-Pkg.add(url="https://github.com/ZIB-IOL/Boscia.jl", rev="main")
+Pkg.add("Boscia")
 ```
 
+
+
+
+
+If you want to use SCIP within Boscia and your OS is windows, you will have download SCIP separately, see SCIP.jl.
+Note that you do not necessarily have to download the binaries but can also use the installer provided by SCIP.
+
+
+**For Window Users** You need not to download whole SCIP binary instead you can follow **Custom Installation** mentioned on this page and download and link SCIP with your JULIA .
+
+
+
+
+
+
 ## Getting started
 
 Here is a simple example to get started. For more examples, see the examples folder in the package.
 
+
 ```julia
 using Boscia
 using FrankWolfe
@@ -86,8 +98,6 @@ Parameter settings.
 	 Total number of varibales: 6
 	 Number of integer variables: 0
 	 Number of binary variables: 6
-
-
 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
    Iteration       Open          Bound      Incumbent      Gap (abs)      Gap (rel)       Time (s)      Nodes/sec        FW (ms)       LMO (ms)  LMO (calls c)   FW (Its)   #ActiveSet  Discarded
 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
@@ -124,3 +134,4 @@ Search Statistics.
 	 LMO calls / sec: 1205.1724137931035
 	 Nodes / sec: 218.96551724137933
 	 LMO calls / node: 5.503937007874016
+```

docs/make.jl

@@ -0,0 +1,51 @@
+using Documenter
+using Boscia
+
+working_dir = @__DIR__
+
+# Function to copy contents of README.md to index.md
+function copy_readme_to_index()
+    readme_path = joinpath(working_dir, "..", "README.md")  # Adjusted path
+    index_path = joinpath(working_dir, "src", "index.md")
+    readme_content = read(readme_path, String)
+    write(index_path, readme_content)
+end
+
+
+
+# Call the functions to update index.md and 1_algorithms.md
+copy_readme_to_index()
+
+
+# Generate documentation
+makedocs(
+    sitename = "Boscia.jl",
+    modules = [Boscia],
+    format = Documenter.HTML(repolink = "https://github.com/ZIB-IOL/Boscia.jl"),
+    pages = [
+        "Home" => "index.md",
+        "How does it work?" => "basics.md",
+
+        "API Reference" => [
+            "reference/0_reference.md",
+            "reference/1_algorithms.md", 
+            "reference/2_blmo_build.md" , 
+            "reference/custom.md" ,
+            "reference/fw_variant.md" ,
+            "reference/utilities.md"
+
+        ]
+    ],
+    warnonly = true
+)
+
+# Deploy documentation
+deploydocs(
+    repo = "https://github.com/saurabhintoml/Boscia.jl.git",
+    devbranch = "main",
+    devurl = "dev",
+    target = "build",
+    branch = "gh-pages",
+    versions = ["stable" => "v^", "v#.#"],
+    push_preview = true
+)

docs/src/basics.md

@@ -0,0 +1,52 @@
+# How does it work  ?
+
+Boscia focuses on mixed-integer convex problems in which the constraints linear , objective non linear  are convex and presents a new algorithmic framework for solving these problems that exploit recent advances in so-called Frank-Wolfe (FW) or Conditional Gradient (CG) methods. The problem class we consider is of the type: 
+$$
+\min ( f(x) ) \text{ where } x \in \mathbb{R}^n, \, x \in X
+$$
+
+where \( X \) is a compact nonconvex set admitting a boundable linear minimization oracle (LMO), i.e., a set over which optimizing a linear function can be done efficiently (comparatively to the original problem), even when bounds are added or modified. Formally, we consider we have access to an oracle taking new bounds \( (l, u) \) and a direction \( d \):
+
+Given : 
+$$
+\( (l, u, d) \in \mathbb{R}^n \times \mathbb{R}^n \times \mathbb{R}^n \),  \( \arg\min_{v \in \mathbb{R}^n} \langle v, d \rangle \) 
+ \text {subject to}    \( v \in X \cap [l, u] \).
+$$
+
+
+# Branch and Bound Techniques 
+
+In this section, we present the techniques derived from Frank Wolfe that can be used in our
+framework .
+
+## FW gap based termination 
+
+Frank-Wolfe methods produce primal feasible iterates and an FW gap, offering many inexpensive iterations with a gradually increasing dual bound. This allows early termination of nodes when the dual bound reaches the best incumbent's objective value, avoiding unnecessary computations. Nodes can be stopped anytime to produce a useful dual bound, aiding overall progress. This flexibility contrasts with other nonlinear solvers, enabling more efficient optimization.
+
+## Tree stae-dependent termination and evolving error 
+
+We implement termination criteria in node processing to reduce iterations, prioritizing nodes with promising lower bounds. An adaptive Frank-Wolfe gap criterion increases precision with depth in the branch-and-bound tree. Frank Wolfe's convex combinations of integer extreme points ensure valid dual bound, even with reduced precision runs. This approach balances efficiency and accuracy in solving optimization problems.we have Hybrid branching which couples strong branching and most infeasible branching. Strong branching is very expensive to do for the whole tree and it's usually more beneficial to utilize strong branching only up to a certain depth.
+
+
+
+
+## Strong Branching 
+
+In tackling large discrete optimization problems, our method utilizes Frank-Wolfe algorithms to approximate lower bound improvements efficiently. By relaxing strong branching to continuous LPs for the Linear Minimization Oracle and controlling FW iterations or gap tolerances, we balance computational cost with accuracy. This approach optimizes variable selection in branch-and-bound algorithms, enhancing scalability and efficiency in solving complex discrete optimization challenges.
+
+## Dual fixing and tightening 
+
+In subproblems where variables are at bounds, our approach utilizes convexity and primal solutions to tighten dual bounds effectively. Drawing from methods pioneered by Dantzig and extended in various contexts, we leverage Frank-Wolfe methods and FW gaps, adaptable to scenarios without explicit dual solutions, such as those involving MIP-based LMOs.
+
+
+
+
+## BPCG (used as default)
+
+The classic FW algorithm's reliance on an LMO is inefficient for polytopes due to expensive calls. The Blended Pairwise Conditional Gradient (BPCG) algorithm improves efficiency by combining FW steps with pairwise steps that avoid LMO calls. BPCG maintains a smaller active set of vertices, enhancing performance. We use a modified lazified BPCG from FrankWolfe.jl.
+
+
+
+
+
+

docs/src/index.md

@@ -0,0 +1,139 @@
+# Boscia.jl
+
+[![Build Status](https://github.com/ZIB-IOL/Boscia.jl/workflows/CI/badge.svg)](https://github.com/ZIB-IOL/Boscia.jl/actions)
+[![Coverage](https://codecov.io/gh/ZIB-IOL/Boscia.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/ZIB-IOL/Boscia.jl)
+
+A solver for Mixed-Integer Convex Optimization that uses Frank-Wolfe methods for convex relaxations and a branch-and-bound algorithm.
+
+## Overview
+
+The Boscia.jl solver uses a combination of a variant of the Frank-Wolfe algorithm and a branch-and-bound-like algorithm to solve mixed-integer convex optimization problems. These problems are of the form:
+**min_{x ∈ C, x_I ∈ Z^n} f(x)**,
+This approach is particularly effective if we can solve the mixed-integer linear minimization problem over C efficiently and handle the integer constraints. The set C is specified using the MathOptInterface API or any domain-specific language (DSL) like Julia for Mathematical Programming (**JuMP**) that implements this API.
+The paper presenting the package with mathematical explanations and numerous examples can be found here:
+
+> Convex integer optimization with Frank-Wolfe methods: [2208.11010](https://arxiv.org/abs/2208.11010)
+
+`Boscia.jl` uses [`FrankWolfe.jl`](https://github.com/ZIB-IOL/FrankWolfe.jl) for solving the convex subproblems, [`Bonobo.jl`](https://github.com/Wikunia/Bonobo.jl) for managing the search tree, and oracles optimizing linear functions over the feasible set, for instance calling [SCIP](https://scipopt.org) or any MOI-compatible solver to solve MIP subproblems.
+
+## Installation
+
+
+Once you have installed Julia , From the Julia REPL, type ] to enter the Pkg REPL mode and run 
+```Boscia
+pkg > add Boscia
+
+```
+
+or alternatively via Pkg in any Julia code:
+```julia
+import Pkg
+Pkg.add("Boscia")
+```
+
+
+
+Suggested change
+If you don't have SCIP  , you can on go this link and add SCIP as instructed ['SCIP'](https://github.com/scipopt/SCIP.jl)
+
+
+If you want to use SCIP within Boscia and your OS is windows, you will have download SCIP separately, see SCIP.jl.
+Note that you do not necessarily have to download the binaries but can also use the installer provided by SCIP.
+
+
+**For Window Users** You need not to download whole SCIP binary instead you can follow **Custom Installation** mentioned on this page and download and link SCIP with your JULIA .
+
+
+
+
+
+
+## Getting started
+
+Here is a simple example to get started. For more examples, see the examples folder in the package.
+
+
+```julia
+using Boscia
+using FrankWolfe
+using Random
+using SCIP
+using LinearAlgebra
+import MathOptInterface
+const MOI = MathOptInterface
+
+n = 6
+
+const diffw = 0.5 * ones(n)
+o = SCIP.Optimizer()
+
+MOI.set(o, MOI.Silent(), true)
+
+x = MOI.add_variables(o, n)
+
+for xi in x
+    MOI.add_constraint(o, xi, MOI.GreaterThan(0.0))
+    MOI.add_constraint(o, xi, MOI.LessThan(1.0))
+    MOI.add_constraint(o, xi, MOI.ZeroOne())
+end
+
+lmo = FrankWolfe.MathOptLMO(o)
+
+function f(x)
+    return sum(0.5*(x.-diffw).^2)
+end
+
+function grad!(storage, x)
+    @. storage = x-diffw
+end
+
+x, _, result = Boscia.solve(f, grad!, lmo, verbose = true)
+
+Boscia Algorithm.
+
+Parameter settings.
+	 Tree traversal strategy: Move best bound
+	 Branching strategy: Most infeasible
+	 Absolute dual gap tolerance: 1.000000e-06
+	 Relative dual gap tolerance: 1.000000e-02
+	 Frank-Wolfe subproblem tolerance: 1.000000e-05
+	 Total number of varibales: 6
+	 Number of integer variables: 0
+	 Number of binary variables: 6
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+   Iteration       Open          Bound      Incumbent      Gap (abs)      Gap (rel)       Time (s)      Nodes/sec        FW (ms)       LMO (ms)  LMO (calls c)   FW (Its)   #ActiveSet  Discarded
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+*          1          2  -1.202020e-06   7.500000e-01   7.500012e-01            Inf   3.870000e-01   7.751938e+00            237              2              9         13            1          0
+         100         27   6.249998e-01   7.500000e-01   1.250002e-01   2.000004e-01   5.590000e-01   2.271914e+02              0              0            641          0            1          0
+         127          0   7.500000e-01   7.500000e-01   0.000000e+00   0.000000e+00   5.770000e-01   2.201040e+02              0              0            695          0            1          0
+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+Postprocessing
+
+Blended Pairwise Conditional Gradient Algorithm.
+MEMORY_MODE: FrankWolfe.InplaceEmphasis() STEPSIZE: Adaptive EPSILON: 1.0e-7 MAXITERATION: 10000 TYPE: Float64
+GRADIENTTYPE: Nothing LAZY: true lazy_tolerance: 2.0
+[ Info: In memory_mode memory iterates are written back into x0!
+
+----------------------------------------------------------------------------------------------------------------
+  Type     Iteration         Primal           Dual       Dual Gap           Time         It/sec     #ActiveSet
+----------------------------------------------------------------------------------------------------------------
+  Last             0   7.500000e-01   7.500000e-01   0.000000e+00   1.086583e-03   0.000000e+00              1
+----------------------------------------------------------------------------------------------------------------
+    PP             0   7.500000e-01   7.500000e-01   0.000000e+00   1.927792e-03   0.000000e+00              1
+----------------------------------------------------------------------------------------------------------------
+
+Solution Statistics.
+	 Solution Status: Optimal (tree empty)
+	 Primal Objective: 0.75
+	 Dual Bound: 0.75
+	 Dual Gap (relative): 0.0
+
+Search Statistics.
+	 Total number of nodes processed: 127
+	 Total number of lmo calls: 699
+	 Total time (s): 0.58
+	 LMO calls / sec: 1205.1724137931035
+	 Nodes / sec: 218.96551724137933
+	 LMO calls / node: 5.503937007874016
+```

docs/src/reference/0_reference.md

@@ -0,0 +1,3 @@
+# API Reference
+
+In this section we present the algorithm interface and the possible settings.

docs/src/reference/1_algorithms.md

@@ -0,0 +1,12 @@
+# Algorithm
+
+This section contains information about interface.jl
+
+## Interface
+
+```@autodocs
+Modules = [Boscia]
+Pages = ["interface.jl"]
+```
+
+