aGrUM/pyAgrum

aGrUM is a fast and powerful C++ library for developing applications based on graphical models such as Bayesian networks, influence diagrams, decision trees, GAI networks, and Markov decision processes. It provides fundamental building blocks for tasks such as:

Graphical model learning/elicitation
Probabilistic inference with graphical models
Planning and decision-making

pyAgrum is a Python wrapper for the C++ aGrUM library (built using SWIG). It offers a high-level interface to simplify the creation, modeling, learning, inference, and embedding of Bayesian Networks and other graphical models. Additionally, it includes extensions for:

Scikit-learn-compatible probabilistic classifiers based on Bayesian networks
Causal analysis tools, including causal networks and do-calculus
Dynamic Bayesian networks
Explainability tools for Bayesian networks

Quick Start

Installation

Install pyAgrum via pip or conda:

pip install pyagrum

conda install -c conda-forge pyagrum

Learning Resources

Dependencies

aGrUM is designed to minimize external dependencies in its C++ codebase. All essential dependencies are included in the source code. The external libraries currently used by aGrUM are:

nanodbc: A lightweight C++ wrapper for ODBC
lrs: A vertex enumeration program
tinyxml: A simple and lightweight XML parser
doctest: A fast single-header C++ testing framework (since version 2.4.0, replaces CxxTest)

pyAgrum Dependencies

The Python wrapper pyAgrum introduces additional dependencies. These are managed separately and specified in the following files:

requirements.txt: Mandatory dependencies
optional_requirements.txt: Optional dependencies for advanced features

For most users, installation via pip or conda will automatically handle these dependencies.

Project Structure

The project is organized as follows:

/acttools       # aGrUM Compiler Tool (ACT) implementation
/apps           # Application examples using aGrUM or pyAgrum
/src            # aGrUM's C++ source code
/wrappers       # Wrappers for aGrUM (Python, Java, etc.)

Key Directories

/src/agrum: Core C++ library
/wrappers/pyAgrum: pyAgrum files, including tests and Sphinx documentation
/src/docs: aGrUM documentation
/src/testunits: Unit tests

Philosophy & Design

aGrUM was initially developed to support the research of the Graphical Models and Decision team at LIP6. Over time, it evolved into a comprehensive open-source library to aid both research and practical applications in decision support and data science.

Key design principles include:

Modern C++20 development for cross-platform compatibility (GCC ≥ 8.0, Clang, MSVC)
Emphasis on performance (multi-threaded algorithms for faster learning/inference)
Support for fine-grained customization in learning, inference, and modeling

For more details, visit the aGrUM feature list.

Wrappers

To make aGrUM more accessible, various wrappers have been developed, including:

pyAgrum: The primary Python wrapper
jAgrum: An experimental Java wrapper

Wrappers are built using SWIG.

Building aGrUM

The recommended build tool is ACT (aGrUM Compilation Tool). It requires Python (≥ 3.9) and platform-specific tools:

Linux: Python, g++, CMake
macOS: Python, clang or g++, CMake
Windows: Python, MSVC 2022, CMake

ACT Commands

act [target] [version] [action]

Targets: aGrUM, pyAgrum, jAgrum
Versions: release, debug
Actions: install, uninstall, test, lib, doc, wheel, etc.

Example:

act test release pyAgrum

For more details, run act --help.

Contributions

We welcome contributions! Please fork the repository, make your changes, and submit a merge request.

Note: Contributors must sign a contribution policy before their changes can be merged.

Continuous Integration

Every commit is tested (with several compilers) on:

Ubuntu (22.04, x84-64)
macOS (15.x, x86-64 & ARM)
Windows (11, x84-64)

The CI pipeline builds and tests both aGrUM and pyAgrum to ensure cross-platform stability.

Testing

C++ Tests (aGrUM)

Run C++ tests with the act test command:

# Run all C++ tests
act test release aGrUM

# Run specific modules (BASE, BN, MRF, CN, ID, CM, FMDP)
act test release aGrUM -m BN
act test release aGrUM -m BASE+BN

# Run specific test suites
act test release aGrUM -t BayesNetTestSuite
act test release aGrUM -t BayesNetTestSuite+BNLearnerTestSuite

# Show available modules/tests
act test release aGrUM -m show
act test release aGrUM -t show

Running Tests Directly (doctest)

After building with act test release aGrUM, you can run the test executable directly for faster iteration:

./gumTest                              # Run all tests
./gumTest --list-test-cases            # List all test cases
./gumTest --test-case="*BayesNet*"     # Run tests matching pattern
./gumTest --test-case="*[BN]*"         # Run all BN module tests
./gumTest --test-case="*[BASE]*"       # Run all BASE module tests

Python Tests (pyAgrum)

act test release pyAgrum -t quick      # Fast tests only
act test release pyAgrum -t all        # Includes notebook tests

Bibliography

For academic references, see the aGrUM bibliography.

AGrUM

Install / Use

README