Faultree

A Python tool for Fault Tree Analysis (FTA) using Ordered Binary Decision Diagrams (OBDD).

Overview

• Converts a Fault Tree (FTA) JSON into an Ordered BDD using the dd package.
• Supports logic gates: AND, OR, XOR (exactly-one), K-of-N.
• Exact top-event and intermediate-event probabilities in O(|BDD|) time (memoized Shannon cofactor recursion) — repeated/shared events are handled exactly, with no cut-set approximations.
• Outputs algebraic and symbolic expressions.
• Supports internal event cloning via ref (reference nodes), making the model a DAG.
• Probabilities can be scalars or sample arrays (evaluated elementwise), given inline, as a JSON mapping, or loaded from CSV/Excel files.

Installation

Requires Python ≥ 3.10.

pip install faultree            # library + CLI
pip install "faultree[server]"  # + FastAPI/uvicorn for the API server

From a checkout of this repository:

pip install -e ".[server,test]"

Tree Format

• Fields:
  • id (string): Unique identifier for the event.
  • name (string): Descriptive name.
  • event_type: top, intermediate, basic, or undeveloped.
  • gate: AND, OR, XOR, K_OF_N, or null/BASIC for leaves.
  • children (list): Child nodes.
  • k (int): Required for K_OF_N gates (0 <= k <= n).
  • prob (float or list of floats): Probability for basic/undeveloped events. A list is treated as a sample vector and propagated elementwise.
  • ref (string): ID of another node to clone/reference.
  • prob_file (string, optional, top level): CSV/Excel file with one column per basic-event id, resolved relative to the tree JSON.

Gate semantics: XOR means exactly one input (a mutually-exclusive gate), not chained parity. K_OF_N means at least k of the n inputs.

Every basic event must have a probability (from the tree, --probs, or a probability file); a missing probability is an error unless --assume-missing-zero is passed.

Supported Formats

Faultree supports two JSON formats (auto-detected):

1. Recursive Tree (standard): Nodes nested within children.
2. Flat List: Nodes defined in ft_nodes and be_nodes lists, with branches referencing child IDs.

Usage

faultree examples/basic_tree.json
# or equivalently
python -m faultree examples/basic_tree.json

Override probabilities (inline JSON or a CSV/Excel path):

faultree examples/basic_tree.json --probs '{"BE1": 0.05}'
faultree examples/fta4b.json --probs examples/fta4b_probs.csv

Reliability analysis (dual/success tree). The tree keeps its failure-logic structure, but inputs are interpreted as reliabilities and the result is the system success probability R = 1 - Q:

faultree examples/fta3_success.json --reliability

Run the API server (binds to 127.0.0.1 by default; pass --host 0.0.0.0 to expose it):

faultree --serve

Example request:

curl -X POST http://localhost:8000/analyze \
  -H "Content-Type: application/json" \
  -d '{
    "tree": {
      "id": "TOP",
      "gate": "OR",
      "children": [
        {"id": "A", "prob": 0.1},
        {"id": "B", "prob": 0.2}
      ]
    }
  }'

Features

• Logic Gates: AND, OR, XOR (exactly one), K-of-N (at least k).
• Exact quantification: weighted model counting via the BDD cofactor recursion — linear in BDD size, exact for repeated/shared events.
• Dual tree mode: reliability/success probability from the same tree.
• Sampled probabilities: array-valued probabilities propagate elementwise (resampling of unequal-length arrays is seeded and reproducible; --seed/--shuffle).
• Symbolic output: algebraic expressions (e.g. (A + B * C)).
• Ref/clones: reuse events within the same tree using {"ref": "ID"} (cycles are detected and rejected).
• API: FastAPI server (/analyze, /health) for integrating with other tools.

Development

pip install -e ".[server,test]"
python -m pytest

tests/test_auto_examples.py cross-checks every example tree against an independent brute-force oracle; tests/test_examples.py pins hand-computed golden values; tests/test_fixes.py covers regression cases (success-mode XOR duality, cycle detection, input validation, server behavior).

Backlog

• Minimal Cut Sets: Extract and report minimal cut sets (ZBDD).
• Importance Measures: Birnbaum, criticality, Fussell-Vesely, RAW, RRW.
• Variable Ordering: Heuristics and dd sifting for BDD size reduction.
• Time-Dependent Analysis: Exponential/Weibull distributions, availability.
• Sound Uncertainty Propagation: jointly sampled Monte Carlo / LHS with percentile bounds (replacing per-event resampling).
• Common-Cause Failure: beta-factor / MGL / alpha-factor groups.
• Transfer Symbols: Split trees across multiple files (transfer_in).
• Open-PSA MEF: import/export for ecosystem interoperability.
• Frontend: Web UI for visualization and analysis.

Notes

• Assumes independent basic events.
• Variable ordering is based on traversal order unless specified with --ordering (which must cover all basic events).
• The engine (and the underlying dd library) is recursive: extremely deep trees/BDDs (~1000 levels) can hit Python's recursion limit.