Smoothing mode

.github/workflows/ci.yml

@@ -1,7 +1,7 @@
 name: CI
 on:
   push:
-    branches: [master]
+    branches: [main]
   pull_request:
     types: [opened, synchronize, reopened]
 jobs:
@@ -21,13 +21,16 @@ jobs:
           - version: '1'
             os: macOS-latest
             arch: x64
+          - version: '1'
+            os: windows-latest
+            arch: x64
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: julia-actions/setup-julia@v2
         with:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
-      - uses: actions/cache@v4
+      - uses: actions/cache@v5
         env:
           cache-name: cache-artifacts
         with:
@@ -40,6 +43,6 @@ jobs:
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v5
+      - uses: codecov/codecov-action@v6
         with:
-          file: lcov.info
+          files: lcov.info

.github/workflows/documentation.yml

@@ -8,8 +8,10 @@ on:
 jobs:
   build:
     runs-on: ubuntu-latest
+    permissions:
+      contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - uses: julia-actions/setup-julia@latest
         with:
           # Build documentation on Julia 1.6

.github/workflows/format_check.yml

@@ -13,7 +13,7 @@ jobs:
       - uses: julia-actions/setup-julia@latest
         with:
           version: '1'
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Format check
         shell: julia --color=yes {0}
         run: |

.gitignore

@@ -32,3 +32,6 @@ docs/src/index.md
 julia
 
 .vscode
+
+docs/src/examples/*.md
+docs/src/examples/*.jl

CITATION.bib

@@ -1,7 +1,18 @@
-@article{miconvexfw,
-  doi = {10.48550/ARXIV.2208.11010},
-  url = {https://arxiv.org/abs/2208.11010},
-  author = {Hendrych, Deborah and Troppens, Hannah and Besançon, Mathieu and Pokutta, Sebastian},
-  title = {Convex integer optimization with Frank-Wolfe methods},
-  year = {2022}
+@article{convexmip,
+    title={Convex mixed-integer optimization with {Frank-Wolfe} algorithms},
+    year={2025},
+    archivePrefix={arXiv},
+    eprint={2208.11010},
+    author={Hendrych, Deborah and Troppens, Hannah and Besançon, Mathieu and Pokutta, Sebastian},
+    journal={Mathematical Programming Computation}
+}
+
+@article{xiao2025bosciajlreviewtutorial,
+      title={{Boscia.jl}: a review and tutorial}, 
+      author={Wenjie Xiao and Deborah Hendrych and Mathieu Besançon and Sebastian Pokutta},
+      year={2025},
+      eprint={2511.01479},
+      archivePrefix={arXiv},
+      primaryClass={math.OC},
+      url={https://arxiv.org/abs/2511.01479}, 
 }

CONTRIBUTING.md

@@ -0,0 +1,96 @@
+# Contributing to FrankWolfe
+
+First, thanks for taking the time to contribute.
+Contributions in any form, such as documentation, bug fix, examples or algorithmic improvement and extensions, are appreciated and welcome.
+
+We list below some guidelines to help you contribute to the package.
+
+## Community Standards
+
+Interactions on this repository must follow the Julia [Community Standards](https://julialang.org/community/standards/) including Pull Requests and issues.
+
+## Where can I get an overview?
+
+Check out the [paper](https://arxiv.org/abs/2208.11010) presenting the package
+for a high-level overview of the feature and algorithms, the [tutorial paper](https://arxiv.org/abs/2511.01479), which
+gives a more high-level overview and some example applications, and
+the [documentation](https://zib-iol.github.io/Boscia.jl/dev/) for more details.
+
+## I just have a question
+
+If your question is related to Julia, its syntax or tooling, the best places to get help will be tied to the Julia community,
+see [the Julia community page](https://julialang.org/community/) for a number of communication channels (Slack, Zulip, and Discourse being the most active).
+
+For now, the best way to ask a question is to file an issue or reach out to [Mathieu Besançon](https://github/matbesancon),
+[Deborah Hendrych](https://github.com/dhendryc) or [Sebastian Pokutta](https://github.com/pokutta).
+You can also ask your question on [discourse.julialang.org](https://discourse.julialang.org) in the optimization topic or on the Julia Slack
+on `#mathematical-optimization`, see [the Julia community page](https://julialang.org/community/) to gain access.
+
+## How can I file an issue?
+
+If you found a bug or want to propose a feature, we track our issues within the [GitHub repository](https://github.com/ZIB-IOL/Boscia.jl/issues).
+Once opened, you can edit the issue or add new comments to continue the conversation.
+
+If you encounter a bug, send the stack trace (the lines appearing after the error occurred containing some source files)
+and ideally a Minimal Working Example (MWE), a small program that reproduces the bug.
+
+## How can I contribute
+
+Contributing to the repository will likely be made in a Pull Request (PR).
+You will need to:
+1. Fork the repository
+2. Clone it on your machine to perform the changes
+3. Create a branch for your modifications, based on the branch you want to merge on (typically main)
+4. Push to this branch on your fork
+5. The GitHub web interface will then automatically suggest opening a PR onto the original repository.
+
+See the GitHub [guide to creating PRs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) for more help on workflows using Git and GitHub.
+
+A PR should do a single thing to reduce the amount of code that must be reviewed.
+Do not run the formatter on the whole repository except if your PR is specifically about formatting.
+
+### Improve the documentation
+
+The documentation can be improved by changing the files in `docs/src`,
+for example to add a section in the documentation, expand a paragraph or add a plot.
+The documentation attached to a given type of function can be modified in the source files directly, it appears above the function / type / thingy you try to document
+with three double quotation marks like this:
+```julia
+"""
+This explains what the function `f` does, it supports markdown.
+"""
+function f(x)
+    # ...
+end
+```
+
+### Provide a new example or test
+
+If you fix a bug, one would typically expect to add a test that validates that the bug is gone.
+A test would be added in a file in the `test/` folder, for which the entry point is `runtests.jl`.
+
+The `examples/` folder features several examples covering different problem settings and algorithms.
+The examples are expected to run with the same environment and dependencies as the tests using
+[TestEnv](https://github.com/JuliaTesting/TestEnv.jl).
+If the example is lightweight enough, it can be added to the `docs/src/examples/` folder which generates
+pages for the documentation based on Literate.jl.
+
+### Provide a new feature
+
+Contributions bringing new features are also welcome.
+If the feature is likely to impact performance, some benchmarks should be run with `BenchmarkTools` on several
+of the examples to assert the effect at different problem sizes.
+If the feature should only be active in some cases, a keyword should be added to one of the settings dictionaries or 
+be linked to a specific mode. 
+
+Some typical features to implement are:
+1. A new Linear Minimization Oracle (LMO) - if this requires additional (big) package imports, please consider adding the LMO to [CombinatorialLinearOracles.jl](https://github.com/ZIB-IOL/CombinatorialLinearOracles.jl) instead.
+2. A new heuristic - for examples, see `src/heuristics.jl`.
+3. A new branching or traverse strategy. 
+
+### Code style
+
+We try to follow the [Julia documentation guidelines](https://docs.julialang.org/en/v1/manual/documentation/).
+We run [`JuliaFormatter.jl`](https://github.com/domluna/JuliaFormatter.jl) on the repo in the way set in the `.JuliaFormatter.toml` file, which enforces a number of conventions.
+
+This contribution guide was inspired by [ColPrac](https://github.com/SciML/ColPrac) and the one in [Manopt.jl](https://github.com/JuliaManifolds/Manopt.jl).

Project.toml

@@ -1,14 +1,12 @@
 name = "Boscia"
 uuid = "36b166db-dac5-4d05-b36a-e6c4cef071c9"
+version = "0.2.12"
 authors = ["ZIB IOL"]
-version = "0.1.39"
 
 [deps]
 Bonobo = "f7b14807-3d4d-461a-888a-05dd4bca8bc3"
-DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 FrankWolfe = "f55ce6ea-fdc5-4628-88c5-0087fe54bd30"
-Hungarian = "e91730f6-4275-51fb-a7a0-7064cfbd3b39"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MathOptInterface = "b8f27783-ece8-5eb3-8dc8-9495eed66fee"
 MathOptSetDistances = "3b969827-a86c-476c-9527-bb6f1a8fbad5"
@@ -27,20 +25,21 @@ BosciaSCIPExt = "SCIP"
 
 [compat]
 Aqua = "0.8"
-Bonobo = "0.1.3"
-DataStructures = "0.18"
+Bonobo = "0.1.5"
+CSV = "0.10"
+CombinatorialLinearOracles = "0.1.2"
 Dates = "1.6"
 Distributions = "0.25"
 DoubleFloats = "1"
-FrankWolfe = "0.5"
+FrankWolfe = "0.6"
+Graphs = "1.13"
 HiGHS = "1"
-Hungarian = "0.7.0"
 LinearAlgebra = "1.6"
 MathOptInterface = "1"
 MathOptSetDistances = "0.2"
 Printf = "1.6"
 Random = "1.6"
-SCIP = "0.11, 0.12"
+SCIP = "0.12"
 SparseArrays = "1.10"
 StableRNGs = "1"
 Statistics = "1.6"
@@ -50,13 +49,17 @@ julia = "1.6"
 
 [extras]
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
+Bonobo = "f7b14807-3d4d-461a-888a-05dd4bca8bc3"
+CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
+CombinatorialLinearOracles = "0002e35e-4a6a-41c8-a2f5-6940c7e5949f"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 DoubleFloats = "497a8b3b-efae-58df-a0af-a86822472b78"
+Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
 HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
 SCIP = "82193955-e24f-5292-bf16-6f2c5261a85f"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Test", "HiGHS", "Distributions", "SCIP", "DoubleFloats", "StableRNGs", "Aqua", "Suppressor"]
+test = ["Test", "HiGHS", "Distributions", "SCIP", "DoubleFloats", "StableRNGs", "Aqua", "Suppressor", "Graphs", "Bonobo", "CSV", "CombinatorialLinearOracles"]

README.md

@@ -23,6 +23,10 @@ The paper presenting the package with mathematical explanations and numerous exa
 
 > Convex mixed-integer optimization with Frank-Wolfe methods: [2208.11010](https://arxiv.org/abs/2208.11010)
 
+A review and tutorial paper presenting the intuition behind the framework and showcasing its use on three examples can be found here:
+
+> Boscia.jl: A review and tutorial: [2511.01479](https://arxiv.org/abs/2511.01479)
+
 `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
@@ -83,7 +87,9 @@ function grad!(storage, x)
     @. storage = x-diffw
 end
 
-x, _, result = Boscia.solve(f, grad!, lmo, settings_bnb=Boscia.settings_bnb(verbose = true))
+settings = Boscia.create_default_settings()
+settings.branch_and_bound[:verbose] = true
+x, _, result = Boscia.solve(f, grad!, lmo, settings=settings)
 
 Boscia Algorithm.
 

docs/Project.toml

@@ -1,7 +1,9 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 SCIP = "82193955-e24f-5292-bf16-6f2c5261a85f"
 
 [compat]
 Documenter = "1.8"
+Literate = "2"

docs/make.jl

@@ -1,17 +1,52 @@
-using Documenter
-using Boscia
+# Add the parent directory to LOAD_PATH so we can import Boscia
+# This doesn't modify Project.toml, keeping it clean like FrankWolfe.jl
+pushfirst!(LOAD_PATH, joinpath(@__DIR__, ".."))
+
+using Documenter, Boscia
+using SparseArrays
+using LinearAlgebra
+
+using Literate
+
+EXAMPLE_DIR = joinpath(dirname(@__DIR__), "examples")
+DOCS_EXAMPLE_DIR = joinpath(@__DIR__, "src", "examples")
+DOCS_REFERENCE_DIR = joinpath(@__DIR__, "src", "reference")
+
+function file_list(dir, extension)
+    return filter(file -> endswith(file, extension), sort(readdir(dir)))
+end
+
+function literate_directory(jl_dir, md_dir)
+    # Remove old markdown files first
+    for filename in file_list(md_dir, ".md")
+        filepath = joinpath(md_dir, filename)
+        rm(filepath)
+    end
+
+    # Process all .jl files that start with "docs"
+    for filename in file_list(jl_dir, ".jl")
+        if startswith(filename, "docs")
+            filepath = joinpath(jl_dir, filename)
+            Literate.markdown(filepath, md_dir; documenter=true, flavor=Literate.DocumenterFlavor())
+        end
+    end
+    return nothing
+end
+
+# Generate markdown files from example .jl files
+literate_directory(EXAMPLE_DIR, DOCS_EXAMPLE_DIR)
 
 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
+    readme_path = joinpath(working_dir, "..", "README.md")
     index_path = joinpath(working_dir, "src", "index.md")
     readme_content = read(readme_path, String)
     return write(index_path, readme_content)
 end
 
-# Call the functions to update index.md and 1_algorithms.md
+# Call the function to update index.md
 copy_readme_to_index()
 
 # Generate documentation
@@ -22,6 +57,11 @@ makedocs(
     pages=[
         "Home" => "index.md",
         "How does it work?" => "basics.md",
+        "Examples" => [
+            "Network Design Problem" => "examples/docs-01-network-design.md",
+            "Graph Isomorphism Problem" => "examples/docs-02-graph-isomorphism.md",
+            "Optimal Design of Experiments" => "examples/docs-03-optimal-design.md",
+        ],
         "API Reference" => [
             #"reference/0_reference.md",
             "reference/1_algorithms.md",