MBDlyb

MBDlyb is a Python library for design-driven model-based diagnostics, developed from the SD2Act and Carefree projects. It lets you describe a system as hardware, functions, dependencies, and observations, then use probabilistic reasoning to investigate possible faults. Models can be built directly in Python; a graph database is not required for the example below.

For background on the methodology, see the SD2Act report and the MBDlyb project website.

A front-end web interface for MBDlyb is available in a separate repository, MBDlyb-UI. A user guide is also available online, containing background information on the methodology and implementation, including some example projects.

Install

MBDlyb requires Python 3.13. To install from this checkout with uv, run the following from the repository root:

uv sync

uv sync creates .venv if needed and installs the project and its dependencies. Run scripts in that environment with uv run python example.py (or activate .venv first).

Install a built wheel

To build a wheel from this checkout, run uv build --wheel. From the directory containing dist, select the resulting wheel (adjust the version or path if needed) in PowerShell:

$wheel = (Resolve-Path .\dist\mbdlyb-0.6.0-py3-none-any.whl).Path

Choose one of the following ways to create an environment and install the wheel, using the same PowerShell session. Each option also installs the project's dependencies.

With uv:

uv venv --python 3.13 .venv
uv pip install --python .\.venv\Scripts\python.exe $wheel

With Python and pip (no uv required):

py -3.13 -m venv .venv
.\.venv\Scripts\python.exe -m pip install $wheel

With Conda, create a Python 3.13 environment and use pip inside that environment to install the wheel:

conda create --name mbdlyb python=3.13 pip
conda run --name mbdlyb python -m pip install $wheel

For the uv or pip options, run the installed package with .\.venv\Scripts\python.exe example.py. For Conda, use conda run --name mbdlyb python example.py.

Example: diagnose a fan that is not spinning

Save this as example.py and run it with uv run python example.py. The model has a power supply and a motor; the power supply enables the fan to spin, and an observation of the fan provides evidence about both components.

from mbdlyb import Evidence
from mbdlyb.formalisms.bayesnet import BayesNetReasoner
from mbdlyb.functional import (
    Cluster,
    DirectObservable,
    Function,
    Hardware,
    ObservedByRelation,
    RealizesRelation,
    RequiredForRelation,
)

system = Cluster("FanSystem")
power_supply = Hardware("PowerSupply", {"Broken": 0.02}, system)
motor = Hardware("Motor", {"Broken": 0.05}, system)
provide_power = Function("ProvidePower", Function.DEFAULT_STATES, system)
spin_fan = Function("SpinFan", Function.DEFAULT_STATES, system)
fan_spinning = DirectObservable(
    "FanSpinning", DirectObservable.DEFAULT_STATES, 0.01, 0.01, system
)

RealizesRelation(power_supply, provide_power)
RealizesRelation(motor, spin_fan)
RequiredForRelation(provide_power, spin_fan)
ObservedByRelation(spin_fan, fan_spinning)

reasoner = BayesNetReasoner(system)
reasoner.evidence.add(Evidence({fan_spinning: "NOk"}))
for component, probabilities in reasoner.infer(power_supply, motor).items():
    print(f"{component.name}: P(Broken | fan not spinning) = {probabilities['Broken']:.3f}")

The output assigns a higher probability of failure to the motor than to the power supply for these example fault rates. The model is created in memory and uses the Bayesian-network reasoner; it does not connect to Neo4j. For a larger example with operating modes and diagnostic tests, see tests/test_model.py.

Example projects and model storage

The MBDlyb user guide provides two larger example projects, CDRadioPlayer and Car, with Capella models and Neo4j database exports. A CDRadioPlayer model in tests/test_model.py is built directly in Python.

Neo4j is used for graph-database-backed model storage and import workflows; it is not needed to build in-memory models or run the example above. See the user guide for database setup and the downloadable example projects.

The database round-trip tests in tests/test_gdb.py are opt-in. Set MBDLYB_TEST_NEO4J_URL to a writable Neo4j connection URL (including credentials and, optionally, the database name), then run python -m unittest discover -s tests -p test_gdb.py. They create uniquely named test graphs and remove them afterward. Without the URL, only the database-free CPT serialization test runs.

Package structure

The Python package is under src/mbdlyb/:

Package or module	Purpose
base.py, fqn.py, evidence.py, reasoner.py	Model elements, hierarchical names, evidence, and reasoning interfaces
functional/	Functional models, diagnosis and analysis, operating modes, and optional Capella/graph-database integration
formalisms/	Bayesian-network, Markov-network, and tensor-network implementations
gdb.py, io.py	Optional graph-database support and model export utilities

Example models and checks live in tests/.

Contact

For questions about MBDlyb or its methodology, contact Thomas Nägele. MBDlyb is licensed under EPL-2.0.