Metadata-Version: 2.4
Name: evidencelib
Version: 1.0.0
Summary: Computational belief functions for DST and DSmT.
Project-URL: Documentation, https://evidencelib.readthedocs.io/en/latest/
Project-URL: Source, https://github.com/itaprac/evidencelib
Project-URL: Issues, https://github.com/itaprac/evidencelib/issues
Author: evidencelib contributors
License: MIT License
        
        Copyright (c) 2026 evidencelib contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
License-File: LICENSE
Keywords: belief-functions,dempster-shafer,dsmt,dst,evidence-theory
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: myst-parser>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: sphinx-rtd-theme>=3.0; extra == 'dev'
Requires-Dist: sphinx>=8.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-parser>=4.0; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=3.0; extra == 'docs'
Requires-Dist: sphinx>=8.0; extra == 'docs'
Description-Content-Type: text/markdown

# evidencelib

[![CI](https://github.com/itaprac/evidencelib/actions/workflows/ci.yml/badge.svg)](https://github.com/itaprac/evidencelib/actions/workflows/ci.yml)
[![Documentation Status](https://readthedocs.org/projects/evidencelib/badge/?version=latest)](https://evidencelib.readthedocs.io/en/latest/?badge=latest)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

Python library for belief-function calculations in Dempster-Shafer theory
(DST) and Dezert-Smarandache theory (DSmT).

`evidencelib` provides a compact quantitative core for finite frames: symbolic
propositions, basic belief assignments, evidence fusion rules, belief measures,
and pignistic decision support.

Documentation is available on
[Read the Docs](https://evidencelib.readthedocs.io/en/latest/).

---

## Installation

You can install `evidencelib` using pip:

```bash
pip install evidencelib
```

For local development:

```bash
git clone https://github.com/itaprac/evidencelib.git
cd evidencelib
python3.10 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,docs]"
```

Run the test suite:

```bash
python -m pytest -q
```

Build the documentation locally:

```bash
python -m sphinx -W -b html docs docs/_build/html
```

---

## Available Functionality

The library contains:

### Models

| Constructor | Description |
| --- | --- |
| `Frame.dst(...)` | Shafer's classical DST model with exhaustive and mutually exclusive hypotheses. |
| `Frame.dsmt(...)` | Free DSm model where hypotheses may overlap. |
| `Frame.hybrid(...)` | Constrained DSm model with explicit emptiness or exclusivity constraints. |

### Proposition Algebra

| Operation | Meaning |
| --- | --- |
| `A \| B` | Union / disjunction, `A ∪ B`. |
| `A & B` | Intersection / conjunction, `A ∩ B`. |
| `frame.proposition("A ∩ (B ∪ C)")` | Parse a proposition from text. |
| `frame.elements()` | Generate the model's power set or hyper-power set. |

### Belief Measures

| Method | Description |
| --- | --- |
| `mass(A)` | Direct mass assigned to a proposition. |
| `belief(A)` | Sum of masses contained in `A`. |
| `plausibility(A)` | Sum of masses intersecting `A`. |
| `commonality(A)` | Sum of masses containing `A`. |
| `conflict` | Mass assigned to the empty proposition. |

### Fusion Rules

| Method | Description |
| --- | --- |
| `conjunctive(...)` | Unnormalized conjunctive rule. |
| `dsmc(...)` | Classic DSm rule on a free DSm frame. |
| `smets(...)` | TBM/Smets rule, keeping conflict on the empty proposition. |
| `dempster(...)` | Normalized Dempster rule. |
| `yager(...)` | Yager rule, moving conflict to total ignorance. |
| `dsmh(...)` | Hybrid DSm rule for constrained models. |
| `dubois_prade(...)` | Static Dubois-Prade-style conflict transfer. |
| `pcr5(...)` | PCR5 for two sources. |
| `pcr6(...)` | PCR6 for two or more sources. |

### Decision Support

| Method | Description |
| --- | --- |
| `pignistic()` | Singleton pignistic scores. |
| `pignistic_regions()` | Probability distribution over disjoint model regions. |
| `decision()` | Singleton with the largest pignistic score. |

---

## Usage Example

```python
from evidencelib import Frame

frame = Frame.dst(["A", "B"])
A, B = frame.symbols()

m1 = frame.mass({
    A: 0.6,
    A | B: 0.4,
})

m2 = frame.mass({
    B: 0.3,
    A | B: 0.7,
})

print(m1.dempster(m2).to_dict())
print(m1.pcr5(m2).to_dict())
```

Output:

```python
{"A": 0.5121951219512195, "A|B": 0.34146341463414637, "B": 0.14634146341463414}
{"A": 0.54, "A|B": 0.28, "B": 0.18}
```

Free DSmT example:

```python
frame = Frame.dsmt(["A", "B"])
A, B = frame.symbols()

m = frame.mass({
    A: 0.2,
    B: 0.3,
    A & B: 0.4,
    A | B: 0.1,
})

print(m.pignistic())
print(m.pignistic_regions())
```

In DSmT, singleton hypotheses can overlap, so `pignistic()` returns decision
scores that do not necessarily sum to one. Use `pignistic_regions()` for a
probability distribution over disjoint Venn regions.

More examples are available in the [`examples/`](examples/) directory and in
the documentation.

---

## References

- Shafer, G. (1976). *A Mathematical Theory of Evidence*. Princeton University Press.
- Smarandache, F., & Dezert, J. (eds.). *Advances and Applications of DSmT for Information Fusion*.
- Dezert, J., & Smarandache, F. *An Introduction to DSmT*.
- Zadeh, L. A. (1986). A simple view of the Dempster-Shafer theory of evidence and its implication for the rule of combination. *AI Magazine*, 7(2), 85-90.

---

## License

`evidencelib` is released under the MIT License.
