# toulbar2
## Exact optimization for cost function networks and additive graphical models
[](https://app.travis-ci.com/github/toulbar2/toulbar2)
[](https://pypi.org/project/pytoulbar2)[](https://pypi.org/project/pytoulbar2)[](https://pypi.org/project/pytoulbar2)
<!-- (_README_1)= -->
## What is toulbar2?
toulbar2 is an open-source black-box C++ optimizer for cost function
networks and discrete additive graphical models. This also covers Max-SAT, Max-Cut, QUBO (and constrained variants), among others. It can read a variety
of formats. The optimized criteria and feasibility should be provided
factorized in local cost functions on discrete variables. Constraints
are represented as functions that produce costs that exceed a
user-provided primal bound. toulbar2 looks for a non-forbidden assignment
of all variables that optimizes the sum of all functions (a decision
NP-complete problem).
toulbar2 won several competitions on deterministic and probabilistic
graphical models:
* Max-CSP 2008 Competition [CPAI08][cpai08] (winner on 2-ARY-EXT and N-ARY-EXT)
* Probabilistic Inference Evaluation [UAI 2008][uai2008] (winner on several MPE tasks, inra entries)
* 2010 UAI APPROXIMATE INFERENCE CHALLENGE [UAI 2010][uai2010] (winner on 1200-second MPE task)
* The Probabilistic Inference Challenge [PIC 2011][pic2011] (second place by ficolofo on 1-hour MAP task)
* UAI 2014 Inference Competition [UAI 2014][uai2014] (winner on all MAP task categories, see Proteus, Robin, and IncTb entries)
* [XCSP3][xcsp] Competitions (*first place* on Mini COP in 2023 *and 2025*, second place on Mini COP and Parallel COP tracks in 2022, third place in 2024)
* UAI 2022 Inference Competition [UAI 2022][uai2022] (winner on all MPE and MMAP task categories)
* Pseudo-Boolean Competition 2025 [PB25][pbo25] (OPT-LIN ranking 39/46 ; PARTIAL-LIN ranking 6/9, but it gave the best known answer from an incomplete solver point of view in [185][partiallin25] instances among 208)
[cpai08]: http://www.cril.univ-artois.fr/CPAI08
[uai2008]: http://graphmod.ics.uci.edu/uai08/Evaluation/Report
[uai2010]: http://www.cs.huji.ac.il/project/UAI10/summary.php
[pic2011]: http://www.cs.huji.ac.il/project/PASCAL/board.php
[uai2014]: https://personal.utdallas.edu/~vibhav.gogate/uai14-competition/leaders.html
[xcsp]: https://xcsp.org/competitions
[uai2022]: https://uaicompetition.github.io/uci-2022/results/final-leader-board
[pbo25]: https://www.cril.univ-artois.fr/PB25
[partiallin25]: https://www.cril.univ-artois.fr/PB25/results/globalbybench.php?idev=118&idcat=119
toulbar2 is now also able to collaborate with ML code that can learn
an additive graphical model (with constraints) from data (see the
associated
[paper](https://miat.inrae.fr/schiex/Export/Pushing_Data_in_your_CP_model.pdf),
[slides](https://miat.inrae.fr/schiex/Export/Pushing_Data_in_your_CP_model-Slides.pdf)
and [video](https://www.youtube.com/watch?v=IpUr6KIEjMs) where it is
shown how it can learn user preferences or how to play the Sudoku
without knowing the rules). The current CFN learning code is available
on [GitHub](https://github.com/toulbar2/CFN-learn).
<!-- (_README_2)= -->
## Installation from binaries
You can install toulbar2 directly using the package manager in Debian
and Debian derived Linux distributions (Ubuntu, Mint,...):
sudo apt-get update
sudo apt-get install toulbar2 toulbar2-doc
For the most recent binary or the Python API, compile from source.
<!-- (_README_3)= -->
## Python interface
An alpha-release Python interface can be tested through pip on Linux and MacOS:
python3 -m pip install --upgrade pip
python3 -m pip install pytoulbar2
The first line is only useful for Linux distributions that ship "old" versions of pip.
Commands for compiling the Python API on Linux/MacOS with cmake (Python module in lib/\*/pytb2.cpython\*.so):
pip3 install pybind11
mkdir build
cd build
cmake -DPYTB2=ON ..
make
Move the cpython library and the experimental [pytoulbar2.py](https://github.com/toulbar2/toulbar2/raw/master/pytoulbar2/pytoulbar2.py) python class wrapper in the folder of the python script that does "import pytoulbar2".
<!-- (_README_4)= -->
## Download
Download the latest release from GitHub
(https://github.com/toulbar2/toulbar2) or similarly use tag versions,
e.g.:
git clone --branch 1.2.0 https://github.com/toulbar2/toulbar2.git
<!-- (_README_5)= -->
## Installation from sources
Compilation requires git, cmake and a C++-17 capable compiler (in C++17 mode).
Required library:
* libgmp-dev
* bc (used during cmake)
Recommended libraries (default use):
* libboost-graph-dev
* libboost-iostreams-dev
* libboost-serialization-dev
* zlib1g-dev
* liblzma-dev
* libbz2-dev
Optional libraries:
* libjemalloc-dev
* pybind11-dev
* libopenmpi-dev
* libboost-mpi-dev
* libicuuc
* libicui18n
* libicudata
* libxml2-dev
* libxcsp3parser
* libeigen3-dev
On MacOS, run ./misc/script/MacOS-requirements-install.sh to install the recommended libraries. For Mac with ARM64, add option -DBoost=OFF to cmake.
Commands for compiling toulbar2 on Linux/MacOS with cmake (binary in build/bin/\*/toulbar2):
mkdir build
cd build
cmake ..
make
Commands for statically compiling toulbar2 on Linux in directory toulbar2/src without cmake:
bash
cd src
echo '#define Toulbar_VERSION "1.2.0"' > ToulbarVersion.hpp
g++ -o toulbar2 -std=c++17 -O3 -DNDEBUG -march=native -flto -static -static-libgcc -static-libstdc++ -DBOOST -DLONGDOUBLE_PROB -DLONGLONG_COST -DWCSPFORMATONLY \
-I. -I./pils/src tb2*.cpp applis/*.cpp convex/*.cpp core/*.cpp globals/*.cpp incop/*.cpp mcriteria/*.cpp pils/src/exe/*.cpp search/*.cpp utils/*.cpp vns/*.cpp ToulbarVersion.cpp \
-lboost_graph -lboost_iostreams -lboost_serialization -lgmp -lz -lbz2 -llzma
Use OPENMPI flag and MPI compiler for a parallel version of toulbar2 (must be run with mpirun, use mpirun -n 1 for the sequential version of HBFS or VNS):
bash
cd src
echo '#define Toulbar_VERSION "1.2.0"' > ToulbarVersion.hpp
mpicxx -o toulbar2 -std=c++17 -O3 -DNDEBUG -march=native -flto -DBOOST -DLONGDOUBLE_PROB -DLONGLONG_COST -DWCSPFORMATONLY -DOPENMPI \
-I. -I./pils/src tb2*.cpp applis/*.cpp convex/*.cpp core/*.cpp globals/*.cpp incop/*.cpp mcriteria/*.cpp pils/src/exe/*.cpp search/*.cpp utils/*.cpp vns/*.cpp ToulbarVersion.cpp \
-lboost_graph -lboost_iostreams -lboost_serialization -lboost_mpi -lgmp -lz -lbz2 -llzma
Replace LONGLONG_COST by INT_COST to reduce memory usage by two and reduced cost range (costs must be smaller than 10^8).
Replace WCSPFORMATONLY by XMLFLAG3 and add libxcsp3parser.a from xcsp.org in your current directory for reading XCSP3 files:
bash
cd src
echo '#define Toulbar_VERSION "1.2.0"' > ToulbarVersion.hpp
mpicxx -o toulbar2 -std=c++17 -O3 -DNDEBUG -march=native -flto -DBOOST -DLONGDOUBLE_PROB -DLONGLONG_COST -DXMLFLAG3 -DOPENMPI \
-I/usr/include/libxml2 -I. -I./pils/src -I./xmlcsp3 tb2*.cpp applis/*.cpp convex/*.cpp core/*.cpp globals/*.cpp incop/*.cpp mcriteria/*.cpp pils/src/exe/*.cpp search/*.cpp utils/*.cpp vns/*.cpp ToulbarVersion.cpp \
-lboost_graph -lboost_iostreams -lboost_serialization -lboost_mpi -lxml2 -licuuc -licui18n -licudata libxcsp3parser.a -lgmp -lz -lbz2 -llzma -lm -lpthread -ldl
Copyright (C) 2006-2025, toulbar2 team.
toulbar2 is currently maintained by Simon de Givry, INRAE - MIAT, Toulouse, France (simon.de-givry@inrae.fr)
Raw data
{
"_id": null,
"home_page": "http://miat.inrae.fr/toulbar2",
"name": "pytoulbar2",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "optimization graphical-model",
"author": "ToulBar2 team",
"author_email": "thomas.schiex@inrae.fr",
"download_url": null,
"platform": null,
"description": "# toulbar2\n## Exact optimization for cost function networks and additive graphical models \n\n[](https://app.travis-ci.com/github/toulbar2/toulbar2)\n[](https://pypi.org/project/pytoulbar2)[](https://pypi.org/project/pytoulbar2)[](https://pypi.org/project/pytoulbar2)\n\n<!-- (_README_1)= -->\n## What is toulbar2? \n\ntoulbar2 is an open-source black-box C++ optimizer for cost function\nnetworks and discrete additive graphical models. This also covers Max-SAT, Max-Cut, QUBO (and constrained variants), among others. It can read a variety\nof formats. The optimized criteria and feasibility should be provided\nfactorized in local cost functions on discrete variables. Constraints\nare represented as functions that produce costs that exceed a\nuser-provided primal bound. toulbar2 looks for a non-forbidden assignment \nof all variables that optimizes the sum of all functions (a decision \nNP-complete problem).\n\ntoulbar2 won several competitions on deterministic and probabilistic\ngraphical models:\n\n* Max-CSP 2008 Competition [CPAI08][cpai08] (winner on 2-ARY-EXT and N-ARY-EXT)\n* Probabilistic Inference Evaluation [UAI 2008][uai2008] (winner on several MPE tasks, inra entries)\n* 2010 UAI APPROXIMATE INFERENCE CHALLENGE [UAI 2010][uai2010] (winner on 1200-second MPE task)\n* The Probabilistic Inference Challenge [PIC 2011][pic2011] (second place by ficolofo on 1-hour MAP task)\n* UAI 2014 Inference Competition [UAI 2014][uai2014] (winner on all MAP task categories, see Proteus, Robin, and IncTb entries)\n* [XCSP3][xcsp] Competitions (*first place* on Mini COP in 2023 *and 2025*, second place on Mini COP and Parallel COP tracks in 2022, third place in 2024)\n* UAI 2022 Inference Competition [UAI 2022][uai2022] (winner on all MPE and MMAP task categories)\n* Pseudo-Boolean Competition 2025 [PB25][pbo25] (OPT-LIN ranking 39/46 ; PARTIAL-LIN ranking 6/9, but it gave the best known answer from an incomplete solver point of view in [185][partiallin25] instances among 208)\n\n[cpai08]: http://www.cril.univ-artois.fr/CPAI08\n[uai2008]: http://graphmod.ics.uci.edu/uai08/Evaluation/Report\n[uai2010]: http://www.cs.huji.ac.il/project/UAI10/summary.php\n[pic2011]: http://www.cs.huji.ac.il/project/PASCAL/board.php\n[uai2014]: https://personal.utdallas.edu/~vibhav.gogate/uai14-competition/leaders.html \n[xcsp]: https://xcsp.org/competitions\n[uai2022]: https://uaicompetition.github.io/uci-2022/results/final-leader-board\n[pbo25]: https://www.cril.univ-artois.fr/PB25\n[partiallin25]: https://www.cril.univ-artois.fr/PB25/results/globalbybench.php?idev=118&idcat=119\n\ntoulbar2 is now also able to collaborate with ML code that can learn\nan additive graphical model (with constraints) from data (see the\nassociated\n[paper](https://miat.inrae.fr/schiex/Export/Pushing_Data_in_your_CP_model.pdf),\n[slides](https://miat.inrae.fr/schiex/Export/Pushing_Data_in_your_CP_model-Slides.pdf)\nand [video](https://www.youtube.com/watch?v=IpUr6KIEjMs) where it is\nshown how it can learn user preferences or how to play the Sudoku\nwithout knowing the rules). The current CFN learning code is available\non [GitHub](https://github.com/toulbar2/CFN-learn).\n\n<!-- (_README_2)= -->\n## Installation from binaries\n\nYou can install toulbar2 directly using the package manager in Debian\nand Debian derived Linux distributions (Ubuntu, Mint,...):\n\n sudo apt-get update\n sudo apt-get install toulbar2 toulbar2-doc\n\nFor the most recent binary or the Python API, compile from source.\n\n<!-- (_README_3)= -->\n## Python interface\n\nAn alpha-release Python interface can be tested through pip on Linux and MacOS:\n\n python3 -m pip install --upgrade pip\n python3 -m pip install pytoulbar2\n\nThe first line is only useful for Linux distributions that ship \"old\" versions of pip.\n\nCommands for compiling the Python API on Linux/MacOS with cmake (Python module in lib/\\*/pytb2.cpython\\*.so):\n\n pip3 install pybind11\n mkdir build\n cd build\n cmake -DPYTB2=ON ..\n make\n\nMove the cpython library and the experimental [pytoulbar2.py](https://github.com/toulbar2/toulbar2/raw/master/pytoulbar2/pytoulbar2.py) python class wrapper in the folder of the python script that does \"import pytoulbar2\".\n\n<!-- (_README_4)= -->\n## Download\n\nDownload the latest release from GitHub\n(https://github.com/toulbar2/toulbar2) or similarly use tag versions,\ne.g.:\n\n git clone --branch 1.2.0 https://github.com/toulbar2/toulbar2.git\n\n<!-- (_README_5)= -->\n## Installation from sources\n\nCompilation requires git, cmake and a C++-17 capable compiler (in C++17 mode). \n\nRequired library:\n* libgmp-dev\n* bc (used during cmake)\n\nRecommended libraries (default use):\n* libboost-graph-dev\n* libboost-iostreams-dev\n* libboost-serialization-dev\n* zlib1g-dev\n* liblzma-dev\n* libbz2-dev\n\nOptional libraries:\n* libjemalloc-dev\n* pybind11-dev\n* libopenmpi-dev\n* libboost-mpi-dev\n* libicuuc\n* libicui18n\n* libicudata\n* libxml2-dev\n* libxcsp3parser\n* libeigen3-dev\n\nOn MacOS, run ./misc/script/MacOS-requirements-install.sh to install the recommended libraries. For Mac with ARM64, add option -DBoost=OFF to cmake.\n\nCommands for compiling toulbar2 on Linux/MacOS with cmake (binary in build/bin/\\*/toulbar2):\n\n mkdir build\n cd build\n cmake ..\n make\n\nCommands for statically compiling toulbar2 on Linux in directory toulbar2/src without cmake:\n\n bash\n cd src\n echo '#define Toulbar_VERSION \"1.2.0\"' > ToulbarVersion.hpp\n g++ -o toulbar2 -std=c++17 -O3 -DNDEBUG -march=native -flto -static -static-libgcc -static-libstdc++ -DBOOST -DLONGDOUBLE_PROB -DLONGLONG_COST -DWCSPFORMATONLY \\\n -I. -I./pils/src tb2*.cpp applis/*.cpp convex/*.cpp core/*.cpp globals/*.cpp incop/*.cpp mcriteria/*.cpp pils/src/exe/*.cpp search/*.cpp utils/*.cpp vns/*.cpp ToulbarVersion.cpp \\\n -lboost_graph -lboost_iostreams -lboost_serialization -lgmp -lz -lbz2 -llzma\n\nUse OPENMPI flag and MPI compiler for a parallel version of toulbar2 (must be run with mpirun, use mpirun -n 1 for the sequential version of HBFS or VNS):\n\n bash\n cd src\n echo '#define Toulbar_VERSION \"1.2.0\"' > ToulbarVersion.hpp\n mpicxx -o toulbar2 -std=c++17 -O3 -DNDEBUG -march=native -flto -DBOOST -DLONGDOUBLE_PROB -DLONGLONG_COST -DWCSPFORMATONLY -DOPENMPI \\\n -I. -I./pils/src tb2*.cpp applis/*.cpp convex/*.cpp core/*.cpp globals/*.cpp incop/*.cpp mcriteria/*.cpp pils/src/exe/*.cpp search/*.cpp utils/*.cpp vns/*.cpp ToulbarVersion.cpp \\\n -lboost_graph -lboost_iostreams -lboost_serialization -lboost_mpi -lgmp -lz -lbz2 -llzma\n\nReplace LONGLONG_COST by INT_COST to reduce memory usage by two and reduced cost range (costs must be smaller than 10^8).\n\nReplace WCSPFORMATONLY by XMLFLAG3 and add libxcsp3parser.a from xcsp.org in your current directory for reading XCSP3 files:\n\n bash\n cd src\n echo '#define Toulbar_VERSION \"1.2.0\"' > ToulbarVersion.hpp\n mpicxx -o toulbar2 -std=c++17 -O3 -DNDEBUG -march=native -flto -DBOOST -DLONGDOUBLE_PROB -DLONGLONG_COST -DXMLFLAG3 -DOPENMPI \\\n -I/usr/include/libxml2 -I. -I./pils/src -I./xmlcsp3 tb2*.cpp applis/*.cpp convex/*.cpp core/*.cpp globals/*.cpp incop/*.cpp mcriteria/*.cpp pils/src/exe/*.cpp search/*.cpp utils/*.cpp vns/*.cpp ToulbarVersion.cpp \\\n -lboost_graph -lboost_iostreams -lboost_serialization -lboost_mpi -lxml2 -licuuc -licui18n -licudata libxcsp3parser.a -lgmp -lz -lbz2 -llzma -lm -lpthread -ldl\n\nCopyright (C) 2006-2025, toulbar2 team.\ntoulbar2 is currently maintained by Simon de Givry, INRAE - MIAT, Toulouse, France (simon.de-givry@inrae.fr)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "ToulBar2 Python package",
"version": "0.0.0.5",
"project_urls": {
"Homepage": "http://miat.inrae.fr/toulbar2"
},
"split_keywords": [
"optimization",
"graphical-model"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f7fa879cd1286962e89e6363a4ba4de72818d002c18842764109903b5f0302b7",
"md5": "ec20a07fd2cfa2e2e6ff6017f887cf54",
"sha256": "b502bf35d259fe82b8584f2d8e8d2e43ef4dbff08cc4d7c926656760db31c257"
},
"downloads": -1,
"filename": "pytoulbar2-0.0.0.5-cp38-cp38-macosx_13_0_x86_64.whl",
"has_sig": false,
"md5_digest": "ec20a07fd2cfa2e2e6ff6017f887cf54",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": null,
"size": 17637255,
"upload_time": "2025-10-17T15:37:50",
"upload_time_iso_8601": "2025-10-17T15:37:50.060794Z",
"url": "https://files.pythonhosted.org/packages/f7/fa/879cd1286962e89e6363a4ba4de72818d002c18842764109903b5f0302b7/pytoulbar2-0.0.0.5-cp38-cp38-macosx_13_0_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7947bafaa32f3649a1b223191c3de2e8b37389a5808e1dd63fe2a671cc42c5ca",
"md5": "a0dea82a4b459b06f984e83596c80785",
"sha256": "19cd6c078750c733e07b22fa534ef70a8cafaa0a6f6e025c58cf61199ef097a3"
},
"downloads": -1,
"filename": "pytoulbar2-0.0.0.5-cp38-cp38-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"has_sig": false,
"md5_digest": "a0dea82a4b459b06f984e83596c80785",
"packagetype": "bdist_wheel",
"python_version": "cp38",
"requires_python": null,
"size": 15873587,
"upload_time": "2025-10-17T15:37:52",
"upload_time_iso_8601": "2025-10-17T15:37:52.425323Z",
"url": "https://files.pythonhosted.org/packages/79/47/bafaa32f3649a1b223191c3de2e8b37389a5808e1dd63fe2a671cc42c5ca/pytoulbar2-0.0.0.5-cp38-cp38-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ddf1d62b29f75ed0a492b7231672dab25209e296caff68c2fc97923dd10e9077",
"md5": "56fd8dbe8951832838aa4795d0950444",
"sha256": "e6cf3b4dbc95fcf1374dd6ca147a9c782645b218fca60e34d51efa285758904f"
},
"downloads": -1,
"filename": "pytoulbar2-0.0.0.5-cp39-cp39-macosx_14_0_arm64.whl",
"has_sig": false,
"md5_digest": "56fd8dbe8951832838aa4795d0950444",
"packagetype": "bdist_wheel",
"python_version": "cp39",
"requires_python": null,
"size": 17087646,
"upload_time": "2025-10-17T15:37:54",
"upload_time_iso_8601": "2025-10-17T15:37:54.552411Z",
"url": "https://files.pythonhosted.org/packages/dd/f1/d62b29f75ed0a492b7231672dab25209e296caff68c2fc97923dd10e9077/pytoulbar2-0.0.0.5-cp39-cp39-macosx_14_0_arm64.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-17 15:37:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pytoulbar2"
}
JSON