- aGrUM is a C++ library designed to facilitate the development of applications using graphical models such as Bayesian networks, influence diagrams, decision trees, GAI networks or Markov decision processes.
It is written to provide the basic building blocks to perform the following tasks :
* graphical models learning/elicitation,
* probabilistic inference with graphical models,
* planification.
- pyAgrum is a Python wrapper for the C++ aGrUM library (using SWIG interface generator). It provides a high-level interface to the part of aGrUM allowing to create, model, learn, use, calculate with and embed Bayesian Networks and other graphical models. Some specific (python and C++) code was added in order to simplify and extend the aGrUM API.
The aforementioned extensions are (implemented as pure python modules using pyAgrum) :
* Scikit-learn-compliant probabilistic classifiers based on Bayesian networks,
* Probabilistic causality (causal networks, do-calculus),
* dynamic Bayesian network,
* tools for explainability in Bayesian networks.
pip install pyAgrumconda install -c conda-forge pyagrumFor a less technical introduction, checkout the project's homepage.
aGrUM's initial purpose was to support, sustain and share new frameworks and algorithms from the Graphical Models and Decision team at LIP6: Christophe Gonzales, Pierre-Henri Wuillemin and students and former students. aGrUM then took the form of a generic framework designed to ease the emergence and experimentation of new ideas. More and more, as a consequence, it began to fulfill all the requirements for providing a complete library to build applications using Probabilistic Graphical Models, with a strong emphasis on Bayesian networks. Once the project reached this state, the team decided to provide it as an open source contribution for the decision support and data science communities. The last move in that direction has been to port its main code repository at gitlab.
aGrUM main goals include code quality, code reuse and performance: aGrUM is written in modern C++20 (cross-platform: gcc>=8.0, clang and visual C++); tests and continuous integration are at the core of aGrUM's development; many classical algorithms have been reimplemented and multi-threaded to speed up learning and inference.
Moreover, aGrUM allows its users to very finely tune learning (choosing priors, score, constraints, algorithms and more), inference (choosing their algorithms but also their components like message passing algorithms, triangulation algorithms, etc.) and modeling (choosing the type of discrete variables, making qualitative and quantitative introspection in the model, etc.). The different frameworks (Bayesian networks, influence diagram, credal networks, FMDP, etc.) are treated in the same way (see here for a more exhaustive list of features).
The main drawback of such a complex toolbox is of course the long and arduous learning curve associated to its inherent complexities. It is the reason why it has been decided to ship wrappers in easier language with easier APIs together with aGrUM. pyAgrum (for python) is the main wrapper of aGrUM. jAgrum and other experimental wrappers could be shipped soon (if needed or asked).
aGrUM uses swig to build these wrappers.
Documentation is a never-ending story for a library with a complex API. The team tries its best to keep
up to date but maintaining them is a difficult task and we are actively looking for people to help us writing those documentations and tutorials.
aGrUM's team tries its best to not introduce external dependencies with aGrUM (understand no external dependencies for the C++ code of aGrUM). All external dependencies are included in aGrUM's source. At the moment the external programs shipped with aGrUM are:
pyAgrum's dependencies can be found in wrappers/pyAgrum/requirements.txt and wrappers/pyAgrum/optional_requirements.txt.
The project's root is composed of the following folders:
- acttools: implementation of ACT, the aGrUM Compiler Tool
- apps: Examples using aGrUM or pyAgrum
- src: aGrUM's C++ source code
- wrappers: aGrUM's wrappers
In src you can find the following folders:
- agrum: aGrUM's C++ source code
- cmake: CMake files used to compile aGrUM
- docs: aGrUM's documentation
- testunits: aGrUM's tests
In wrappers you can find the following folders:
- swig: generic files declaring the part of aGrUM's API that will be wrapped.
- pyAgrum: pyAgrum files (including proper tests and sphinx documentation)
- jAgrum: experimental java wrapper
It is strongly recommended to use ACT to build aGrUM. Act requires Python (>=3.9) and you will need, depending of your platform, the following tools:
- Linux (X86_64 and ARM):
- Python
- g++
- CMake
- MacOS (intel and ARM):
- Python
- xCode
- CMake
- Microsoft Windows:
- Python
- Microsoft Visual 2022 Community Edition
- CMake
If you chose not to use act, you can directly use CMake to build aGrUM, but you will need
some tweaking to run tests or use specific compilation options.
To get the full list of act commands, you can run act --help. act uses three
agruments: a target, a version and an action. Values for each argument do
not intersect, so order is not important.
The target argument tells ACT what to build: aGrUM, pyAgrum or jAgrum.
The version argument tells ACT to build either in release or debug.
The action argument tells ACT what to do one the build is finished. Some actions
are only available for one target. For example the wheel action only works with
the pyAgrum target and builds the pyAgrum Python wheel.
Common actions to all targets are:
install: installs the target, use option-dto set installation pathuninstall: uninstalls the targettest: execute tests for the given targetlib: compiles the targetdoc: builds the target's documentation
Actions install, uninstall and test are self explanatory (we will cover
options later). Action lib will just compile the target.
Some actions are not related to any target:
clean: cleans the build folderautoindent: applies clang formatting to all C++ source codeshow: shows current values for each options of act
act caches the last command, so you can simply execute act to rerun the previous
command.
One action only applies to the target pyAgrum:
- wheel: builds a PIP wheel, use option
-dto define the wheels localisation
To build aGrUM, the following command can be used: act test release aGrUM.
Testing your build IS recommended, but it running all tests is long so use action
lib to not run any tests or use option -m or -t to reduce the number of test.
To build pyAgrum, the following command can be used: act test release pyAgrum.
As for aGrUM, testing your build IS recommended. You can use action lib to not
run any tests or use option -t quick to not execute notebooks tests (which are
quite long).
To build a wheel of pyAgrum use the following command: act wheel release pyAgrum -d $(pwd)
to copy the wheel in your current folder.
Building wheels do not use CMake to compile aGrUM and pyAgrum, so the compile can be quite longer on some systems.
Conda package are automatically build here.
You can choose different compilers depending on your system with the option --compiler
Current possible values are gcc,clang,mvsc22,mvsc22_32,mvsc19,mvsc19_32,
mvsc17,mvsc17_32,mvsc15,mvsc15_32,mingw64.
To contribute to aGrUM, you should fork the project and proceed with a merge request one your contribution is done.
Please note that there is a contribution policy to sign and email us before we can accept any contribution. You can find the details for upload your contribution agreement here.
We use the following convention for branch names:
documentation/*for documentation branchesinternal/*for any utility development (CI, act, etc..)bug/*for debuggingfeature/*for implementing new featuresbackport/*for maintaining specific tags
Each commits are tested on Ubuntu (20.04 for python 3.9, 22.04 for all others), Mac OS (last version, Intel and ARM) and Windows 11. The build process as follow:
- Builds aGrUM on all platforms
- Builds pyAgrum on all platforms
- Tests aGrUM on all platforms
- Tests pyAgrum on all platforms
We are continuously improving on automatic builds, so expect this to change on a regularly basis.
Testing aGrUM is done using action test on target aGrUM. Important options are:
-m MODULES: executes tests for modules specified byMODULES-t TESTS: executes tests for tests suites specified byTESTS
The -t option supersedes -m options, but act will raise an error if you ask
for test suites not in the modules list set by -m.
Test files are located in src/testunits. Test suites are placed in there respective module folder:
- module_BASE is used to test modules core, graph, multidim, variables
- module_XXXX is used to test module agrum/XXX
Testing pyAgrum is done using action test on target pyAgrum. It is not possible
to test a single test suite for pyAgrum, you can however run tests including
notebooks with option -t all or only tests with -t quick.
Notebooks are not written with the intent to serve as tests, but we find it useful to make our tests fails when a given cell in a notebooks fails to keep them up-to-date.
See aGrUM's reference.