CombOL: a Library for Practical Enumeration and Boltzmann Sampling of Combinatorial Classes

TL;DR

CombOL is an open-source Python library that automates enumeration and Boltzmann sampling of combinatorial classes, supporting exact and approximate sampling with bias elimination and application-specific object mapping.

Contribution

It introduces a novel early-rejection scheme and dynamic precision adjustment, enhancing accuracy and efficiency in combinatorial sampling methods.

Findings

Supports automatic generation of generating functions and sampling algorithms.

Provides guaranteed statistical correctness by eliminating floating-point bias.

Enables direct sampling of complex application-specific objects.

Abstract

We present CombOL (Combinatorial Objects Library), an open-source library for the enumeration and Boltzmann sampling of combinatorial classes. Classes can be specified by a concise string syntax, and may depend on an arbitrary number of parameters. CombOL automatically derives the associated generating functions, enabling the generation of counting sequences and the compilation of Boltzmann samplers. The library supports exact and approximate-size Boltzmann rejection sampling with automatic parameter tuning to target specific sizes. In addition to implementing established methods, CombOL contributes a novel early-rejection scheme, as well as guaranteed statistical correctness by dynamically increasing the numerical precision, eliminating bias due to floating-point rounding errors. Through the Python interface, sampled structures can be mapped to application-specific objects, enabling direct sampling of domain objects such as graphs, chemical structure representations, or other complex data types. CombOL is available from PyPI as 'combol' (pypi.org/project/combol). The source code is available at gitlab.com/casbjorn/combol.