Global Benchmark Database (GBD)
GBD is a comprehensive suite of tools for provisioning and sustainably maintaining benchmark instances and their metadata for empirical research on hard algorithmic problem classes. For an introduction to the GBD concept, the underlying data model, and specific use cases, please refer to our 2024 SAT Tool Paper.
GBD contributes data to your algorithmic evaluations
GBD provides benchmark instance identifiers, feature extractors, and instance transformers for hard algorithmic problem domains, now including propositional satisfiability (SAT) and optimization (MaxSAT), and pseudo-Boolean optimization (PBO).
GBD solves several problems
- benchmark instance identification
- identification of equivalence classes of benchmark instances
- distribution of benchmark instances and benchmark metadata
- initialization and maintenance of instance feature databases
- transformation algorithms for benchmark instances
GBD provides an extensible set of problem domains, feature extractors, and instance transformers. For a description of those currently supported, see the GBDC documentation. GBDC provides GBD's performance-critical code (written in C++) as standalone command-line tools (feature extractors and instance transformers) that gbd invokes as external processes. It is maintained in a separate repository. Extractors and transformers are registered in gbd's configuration, so you can also write and register your own tools.
Installation and Configuration
- Run
pip install gbd-tools - Run
pip install 'gbd-tools[gbdc]'on supported platforms to also install the GBDC feature extractors and instance transformers used bygbd initandgbd transform - Obtain a GBD database, e.g. download https://benchmark-database.de/getdatabase/meta.db.
- Register your databases via the environment:
export GBD_DB=path/to/database1:path/to/database2. - Alternatively, register a central TOML configuration file via
export GBD=path/to/gbd.toml. It can declare databases, contexts, extractors, and transformers. When set, it takes precedence overGBD_DB; a-d/--dbargument (a database list or a config file) overrides both. - Test the command line interface with the
gbd infoandgbd --helpcommands.
GBD Interfaces
GBD provides the command-line tool gbd, the web interface gbd serve, and the Python interface class GBD.
GBD Command-Line Interface
Central commands in gbd are those for data access gbd get and database initialization gbd init.
See gbd --help for more commands.
Once a database is registered (via GBD_DB, a GBD config file, or -d/--db), the gbd get command can be used to access data.
See gbd get --help for more information.
gbd init provides access to registered feature extractors, such as the standalone tools provided by gbdc, and gbd transform applies registered instance transformers.
All initialization routines can be run in parallel, and resource limits can be set per process.
See gbd init --help for more information.
For example, once a database is registered you can resolve features for a set of instances with:
gbd -d meta.db get "family = hardware-bmc" -r verified-result runtime-kissat
GBD Server
The GBD server can be started locally with gbd serve. Our instance of the GBD server is hosted at https://benchmark-database.de/. You can download benchmark instances and prebuilt feature databases from there.
GBD Python Interface
The GBD Python interface is used by all programs in the GBD ecosystem. Important here is the query command, which returns GBD data in the form of a Polars dataframe for further analysis, as shown in the following example.
from gbd import GBD
with GBD(['path/to/database1', 'path/to/database2']) as gbd:
df = gbd.query("family = hardware-bmc", resolve=['verified-result', 'runtime-kissat'])
Scripts and use cases of GBD's Python interface are available on https://udopia.github.io/gbdeval/. The evaluation demo demonstrates portfolio analysis and subsequent category-wise performance evaluation using the 2023 SAT competition data. The prediction demo demonstrates category prediction from instance features and subsequent feature importance evaluation.
Release Notes
GBD 5.3
In GBD 5.3, the integration between gbd-tools and gbdc has been hardened and refined. gbdc is now a mandatory dependency and ships with pre-built wheels across a wider selection of systems and platform versions. To keep gbdc lightweight, experimental features with heavy dependencies have been factored out into standalone packages. Specifically, the gate feature extractor and its CaDiCaL dependency are no longer part of gbdc. As a separate tool, they can still be manually linked via the configuration system introduced in GBD 5.1. Moving forward, gbdc focuses strictly on core instance and equivalence class identifier algorithms, alongside basic feature extractors and instance transformers.
GBD 5.3.1 Queries now use None consistently for both stored multi-value defaults and values missing through LEFT joins; None can be used to include or exclude them. Joins are explicitly LEFT or INNER, including across contexts. External tool calls running through gbd init or gbd transform now need explicit confirmation, except if -f/--force is used.
GBD 5.2
GBD 5.2 adds the gbd interactive command, which opens an IPython shell with the result of a query available as a Polars dataframe for exploratory analysis (install via pip install 'gbd-tools[interactive]').
Database initialization is also considerably faster: feature values are now written in batches, which greatly reduces the time spent populating large feature databases.
Both features are based on contributions by Christoph Jabs (@chrjabs, pull requests #32 and #39), imported and adapted to the Polars-based interface and the configuration-driven architecture introduced in 5.1.
GBD 5.1
GBD 5.1 decouples gbd from GBDC: the performance-critical feature extractors and instance transformers are now standalone command-line tools that gbd invokes as external processes, rather than a hard Python dependency.
Extractors, transformers, contexts, and databases are declared in a TOML configuration, so you can register and use your own tools.
A central configuration file can be provided via the new GBD environment variable, which takes precedence over GBD_DB.
GBD 5.0
In addition to several bug fixes and performance improvements, GBD 5.0 no longer depends on Pandas for its interface module. This simplifies installation and use in various environments. The faster, more lightweight Polars library is now used for dataframes instead. Therefore, upgrading to GBD 5.0 requires existing code to be adapted to use Polars dataframes, or Polars dataframes to be explicitly converted to Pandas dataframes (e.g. via df.to_pandas()).
Citation
If you use GBD in your research, please cite our 2024 SAT Tool Paper. Citation metadata for the software itself is provided in CITATION.cff, and archived releases are available on Zenodo (this concept DOI always resolves to the latest release; each release also has its own version DOI).
License
GBD is released under the MIT License.
1 maintainer
Release files for gbd-tools 5.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gbd_tools-5.3.1.tar.gz | 1.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| gbd_tools-5.3.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 3.4 MB
Release files / gbd_tools-5.3.1.tar.gz
| Download URL | gbd_tools-5.3.1.tar.gz |
|---|---|
| Size | 1.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
07c0795ce023abf64c0a4869789b77351936c048724b589c25738698307e2a83
|
|
BLAKE2b-256 checksum How to use checksums |
8c68d24d1f60ee791dd6d72f1ec87d671ab84089e01d26dc663e5d75cd4ca711
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / gbd_tools-5.3.1-py3-none-any.whl
| Download URL | gbd_tools-5.3.1-py3-none-any.whl |
|---|---|
| Size | 1.7 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0cfb6350e6ea3377db34b37045a11237ed8e80dfcefd92c72db18ce66569c62b
|
|
BLAKE2b-256 checksum How to use checksums |
f9ef00acd71b925c3b629db0e893d75f08d1667e58e40196d7513f78f5881d10
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
