scip-toolbox 0.1.0

Pure-Python notebook API for SCIP run analytics (.statistics + .vbc)

SCIP Toolbox

A clean, notebook-first Python API for analysing SCIP solver runs. Two analysis tracks are exposed as one importable package:

Module	What it does
scip_toolbox.statistics	Parse .statistics files into pandas DataFrames
scip_toolbox.vbc	Parse .vbc files & build Plotly B&B-tree figures

There is no CLI and no web UI — everything is plain Python you call from a Jupyter notebook (or any script). All visualisations are returned as Plotly Figure objects so they render inline and can be exported to HTML/PNG with a single method call.

Install

# inside the repo root
uv sync
# or, with editable install + dev tools:
uv sync --extra dev

Notebook quick start

A single import gets you the full API:

from scip_toolbox import (
    # statistics
    load_directory, aggregate, extract_columns,
    GenericIdParser, RegexIdParser, TemplateIdParser,
    # vbc
    VBCParser, build_graph,
    plot_tree_plotly, plot_tree_at_step, plot_realistic_depth_animated,
    BoundsPlot, GapPlot,
)

1. Aggregate .statistics files

runs = load_directory("path/to/runs/", pattern="*.statistics")

df = aggregate(runs, simple={
    "status":     ("SCIP Status", "Status"),
    "total_time": ("Total Time",  "Total"),
    "primal":     ("Solution",    "Primal Bound"),
    "dual":       ("Solution",    "Dual Bound"),
    "gap":        ("Solution",    "Gap"),
    "nodes":      ("B&B Tree",    "nodes"),
})
df.head()

load_directory caches the parsed bundle next to the folder as a pickle. Pass cache=False to disable, or reload=True to force a re-parse.

2. Custom instance-name parsers

Instance IDs often encode parameters (Instance_15_1_DEU_NLD_3_wj_zk_Config_1_1_1_0_1_0_0). Three pluggable parsers ship with the toolbox:

Parser	When to use it
GenericIdParser	Just split on _ and store tokens as token_0, token_1, …
RegexIdParser	You want full regex control with named groups.
TemplateIdParser	Friendly {name} placeholder template, loadable from a file.

Template parser, in code:

parser = TemplateIdParser(
    "Instance_{n_tasks}_{version}_{country:[A-Z]+_[A-Z]+}"
    "_{n_instance}_{weather}_{teams}"
    "_Config_{c1}_{c2}_{c3}_{c4}_{c5}_{c6}_{c7}",
    numeric=("n_tasks", "version", "n_instance"),
)
runs = load_directory("path/to/runs/", id_parser=parser)

Or, externalise it to a small text file (examples/instance_id_template.txt) and load it without writing code:

parser = TemplateIdParser.from_file("examples/instance_id_template.txt")
runs = load_directory("path/to/runs/", id_parser=parser)

3. Visualise a single .vbc run

parser = VBCParser(filepath="run.vbc")
parser.parse()

g = build_graph(parser)

# Full B&B tree with realistic-depth (dual-bound) Y axis:
plot_tree_plotly(g, realistic_depth=True).show()

# Primal vs reconstructed global dual bound + relative gap:
BoundsPlot(parser, show_gap=True).build().show()

# Optimality gap over time:
GapPlot(parser).build().show()

Step-by-step replay:

snapshots = parser.build_snapshots()
plot_tree_at_step(g, snapshots[42]).show()

Animated realistic-depth view:

plot_realistic_depth_animated(g, parser).show()

Export any Plotly figure with fig.write_html("tree.html") / fig.write_image("tree.png").

Testing

uv run pytest -q

Releasing to PyPI

The examples/ folder (sample data, generated figures/tables) is intentionally excluded from the published package - only src/scip_toolbox, README.md, LICENSE and CITATION.cff are shipped (see [tool.hatch.build.targets.sdist]/[tool.hatch.build.targets.wheel] in pyproject.toml).

First release (manual, one-time): PyPI requires a project to already exist before you can register a CI/CD trusted publisher for it.

uv build                 # writes dist/*.whl and dist/*.tar.gz
uv run twine check dist/*
uv run twine upload dist/*   # asks for your PyPI username/password or API token

Every following release (automated via GitLab CI/CD):

1. On pypi.org, open the project -> Publishing -> Add a new publisher -> GitLab, and register: namespace lars.jaeger, project scip_toolbox, workflow filepath .gitlab-ci.yml, environment name pypi. This lets GitLab CI publish using short-lived OIDC tokens - no PyPI API token needs to be stored as a GitLab CI/CD variable.
2. Bump version in pyproject.toml.
3. Tag and push: git tag v0.1.1 && git push --tags.
4. The .gitlab-ci.yml pipeline builds the package and publishes it automatically.

Layout

src/scip_toolbox/
├── __init__.py            # flat re-exports for one-line notebook imports
├── statistics/            # .statistics file parsing & aggregation
│   ├── id_parser.py       # GenericIdParser, RegexIdParser, TemplateIdParser
│   ├── loader.py          # read_statistics_file, load_directory
│   └── summary.py         # aggregate, extract_columns
└── vbc/                   # .vbc file parsing & visualisation
    ├── models/            # NodeData, BoundEvent, layout helpers
    ├── parser/            # VBCParser, classifier, snapshot builder, graph builder
    └── viz/               # tree.py, bounds_plot.py, gap_plot.py, last_bound_scatter.py (all return Plotly/matplotlib figures)

See examples/example.ipynb for an end-to-end, heavily-commented walkthrough that starts from raw SCIP output files and ends with publication-ready tables and figures.

The .statistics/.stats and .vbc files used by that example (a vehicle routing problem solved with branch-and-price, column generation, and a compact MIP model) come from vrp_example_scip_cpp, which also serves as a standalone teaching example of how to implement a branch-and-price algorithm with SCIP/SCIP-SoPlex in C++. Check it out if you want to see how the analysed runs were produced, or are looking to implement your own branch-and-price solver.

License

Licensed under the Apache License, Version 2.0.

Citing

If you use scip_toolbox in your research, please cite it - see CITATION.cff.

This toolbox only analyses output produced by the SCIP Optimization Suite. If you publish results obtained by running SCIP (with or without this toolbox), please also cite SCIP itself, e.g. the original SCIP paper:

@article{Achterberg2009,
  author  = {Tobias Achterberg},
  title   = {{SCIP}: solving constraint integer programs},
  journal = {Mathematical Programming Computation},
  year    = {2009},
  volume  = {1},
  number  = {1},
  pages   = {1--41},
  doi     = {10.1007/s12532-008-0001-1}
}

See scipopt.org for the up-to-date recommended citation for the specific SCIP Optimization Suite version you used.