# infer-actively/pymdp architecture

> Architecture diagram of the GitHub repository infer-actively/pymdp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/infer-actively/pymdp
- Repository: https://github.com/infer-actively/pymdp

## Overview

##### Project type and purpose
- This is an open-source Python library (package) named “pymdp” for simulating Active Inference agents in discrete Markov Decision Process (MDP) environments.
- It provides core algorithms (inference, control, learning), environment models (grid worlds, T-maze, visual foraging), utility/math functions, and both NumPy and JAX implementations. It ships documentation, examples, notebooks, tests, and CI workflows.

##### File structure
- Top-level package:
– `pymdp/` contains the library’s core modules:
- `agent.py` – high-level Agent API
- `algos/` – inference/control algorithms (FPI, MMP, old variants)
- `control.py`, `inference.py`, `learning.py` – generic pipelines
- `default_models.py` – built-in A/B matrices, C vectors
- `envs/` – environment definitions (gridworlds, T-maze, visual foraging)
- `utils.py`, `maths.py` – basic array utilities, math operations
– `pymdp/jax/` mirrors the same structure for JAX-based acceleration.
- Documentation: `docs/` (Sphinx/ReadTheDocs), tutorial notebooks.
- Examples: `examples/` – Jupyter notebooks and scripts showing usage.
- Tests: `test/` – unit/integration tests, MATLAB crossvalidation.
- CI/config: GitHub Actions workflow, `.readthedocs.yml`, `setup.py`, `requirements.txt`, `LICENSE`.

##### README insights
- Stack: Python, NumPy, optional JAX.
- Key components: Agent class, utility to define A/B/C matrices, policy inference, action sampling, environment stepping.
- Emphasis on algorithm validation against MATLAB SPM functions.

##### Main components and their relationships
a. User / Client
- Interacts via Python import (`import pymdp`) or CLI (pip installation).
- Defines or loads environment parameters (A, B, C arrays).
- Instantiates `Agent` and calls methods (`infer_states`, `infer_policies`, `sample_action`).
b. Core Library
- Agent API – orchestrates inference, policy evaluation, control, and learning loops.
- Inference module – variational updates over hidden states given observations.
- Control module – computes expected free energies, policy posterior.
- Learning module – updates A/B matrices or model parameters online.
- Algos subpackage – specific implementations (FPI, message passing MMP).
- Utils/Maths – random matrix generators, array operations, Dirichlet functions.
c. Environment Models
- Provide observation and state transition functions.
- Used by examples and tests to simulate agent-environment loop.
d. JAX Extensions
- Parallel versions of Agent, inference, control, learning, maths to leverage JIT and GPUs.
e. External Libraries & Tools
- NumPy (core computations), JAX (optional acceleration), pytest (testing), Sphinx (docs).
- GitHub Actions for CI, ReadTheDocs for documentation hosting.

##### Architectural patterns and design principles
- Modular layering: separation of high-level API (Agent) from low-level math/inference functions.
- Dual implementation pattern: mirrored NumPy and JAX modules under `pymdp/jax/`.
- Test-driven development: comprehensive unit tests, MATLAB crossvalidation suite.
- Pluggable environments: abstract Env interface in `pymdp/envs/env.py`.
- Declarative model representation: use of A (likelihood), B (transition), C (preferences) arrays.

##### Essential elements
- Arrowheads showing call direction and data flow (e.g., observations → inference, actions → environment)
- Annotations for major data objects (A-matrix, B-matrix, C-vector, q(s), π distributions)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User / Client<br/>Examples, Notebooks"]:::external

    %% Core Library - NumPy and JAX
    subgraph "Core Library"
        AgentAPI_NP["Agent API (NumPy)"]:::core
        AgentAPI_JAX["Agent API (JAX)"]:::jax
        Inference_NP["Inference Engine (NumPy)"]:::core
        Inference_JAX["Inference Engine (JAX)"]:::jax
        Control_NP["Control Engine (NumPy)"]:::core
        Control_JAX["Control Engine (JAX)"]:::jax
        Learning_NP["Learning Engine (NumPy)"]:::core
        Learning_JAX["Learning Engine (JAX)"]:::jax
        Algos_NP["Algorithms (FPI, MMP)"]:::mod
        Algos_JAX["Algorithms (JAX)"]:::jax
        DefaultModels["Default Models (A/B/C)"]:::mod
        subgraph "Utils & Maths"
            Utils_NP["Utility Functions (NumPy)"]:::utils
            Maths_NP["Mathematical Ops (NumPy)"]:::utils
            Utils_JAX["Utility Functions (JAX)"]:::jax_utils
            Maths_JAX["Mathematical Ops (JAX)"]:::jax_utils
        end
    end

    %% Environments
    subgraph "Environment Models"
        EnvInterface["Env Interface"]:::mod
        Grid["GridWorld Env"]:::mod
        TMaze["T-Maze Env"]:::mod
        Visual["Visual Foraging Env"]:::mod
    end

    %% Documentation & Examples
    subgraph "Documentation & Examples"
        Docs["Documentation (Sphinx)"]:::external
        Examples["Examples & Notebooks"]:::external
    end

    %% Testing & CI
    subgraph "Testing & CI"
        TestsCore["Tests (NumPy)"]:::external
        TestsJAX["Tests (JAX)"]:::external
        TestsMATLAB["MATLAB Crossvalidation"]:::external
        CI["CI Workflow"]:::external
    end

    %% Relationships
    User -->|imports| AgentAPI_NP
    User -->|imports| AgentAPI_JAX
    AgentAPI_NP -->|calls| Inference_NP
    AgentAPI_NP -->|calls| Control_NP
    AgentAPI_NP -->|calls| Learning_NP
    AgentAPI_JAX -->|calls| Inference_JAX
    AgentAPI_JAX -->|calls| Control_JAX
    AgentAPI_JAX -->|calls| Learning_JAX
    AgentAPI_NP -->|uses| Algos_NP
    AgentAPI_JAX -->|uses| Algos_JAX
    AgentAPI_NP -->|loads| DefaultModels
    AgentAPI_JAX -->|loads| DefaultModels
    Inference_NP -->|compute| Utils_NP
    Control_NP -->|compute| Utils_NP
    Learning_NP -->|compute| Utils_NP
    Inference_JAX -->|compute| Utils_JAX
    Control_JAX -->|compute| Utils_JAX
    Learning_JAX -->|compute| Utils_JAX
    AgentAPI_NP -->|acts on| EnvInterface
    AgentAPI_JAX -->|acts on| EnvInterface
    EnvInterface --> Grid
    EnvInterface --> TMaze
    EnvInterface --> Visual
    Docs --> AgentAPI_NP
    Docs --> Inference_NP
    Docs --> Control_NP
    Docs --> Learning_NP
    Docs --> EnvInterface
    Examples --> AgentAPI_NP
    Examples --> EnvInterface
    TestsCore --> AgentAPI_NP
    TestsCore --> Inference_NP
    TestsCore --> Control_NP
    TestsCore --> Learning_NP
    TestsJAX --> AgentAPI_JAX
    TestsJAX --> Inference_JAX
    TestsJAX --> Control_JAX
    TestsJAX --> Learning_JAX
    TestsJAX --> Algos_JAX
    TestsMATLAB --> AgentAPI_NP
    CI --> AgentAPI_NP
    CI --> AgentAPI_JAX
    CI --> TestsCore
    CI --> TestsJAX
    CI --> Docs

    %% Click Events
    click AgentAPI_NP "https://github.com/infer-actively/pymdp/blob/master/pymdp/agent.py"
    click AgentAPI_JAX "https://github.com/infer-actively/pymdp/blob/master/pymdp/jax/agent.py"
    click Inference_NP "https://github.com/infer-actively/pymdp/blob/master/pymdp/inference.py"
    click Inference_JAX "https://github.com/infer-actively/pymdp/blob/master/pymdp/jax/inference.py"
    click Control_NP "https://github.com/infer-actively/pymdp/blob/master/pymdp/control.py"
    click Control_JAX "https://github.com/infer-actively/pymdp/blob/master/pymdp/jax/control.py"
    click Learning_NP "https://github.com/infer-actively/pymdp/blob/master/pymdp/learning.py"
    click Learning_JAX "https://github.com/infer-actively/pymdp/blob/master/pymdp/jax/learning.py"
    click Algos_NP "https://github.com/infer-actively/pymdp/blob/master/pymdp/algos/fpi.py"
    click Algos_NP "https://github.com/infer-actively/pymdp/blob/master/pymdp/algos/mmp.py"
    click Algos_NP "https://github.com/infer-actively/pymdp/blob/master/pymdp/algos/mmp_old.py"
    click Algos_JAX "https://github.com/infer-actively/pymdp/blob/master/pymdp/jax/algos.py"
    click Utils_NP "https://github.com/infer-actively/pymdp/blob/master/pymdp/utils.py"
    click Maths_NP "https://github.com/infer-actively/pymdp/blob/master/pymdp/maths.py"
    click Utils_JAX "https://github.com/infer-actively/pymdp/blob/master/pymdp/jax/utils.py"
    click Maths_JAX "https://github.com/infer-actively/pymdp/blob/master/pymdp/jax/maths.py"
    click DefaultModels "https://github.com/infer-actively/pymdp/blob/master/pymdp/default_models.py"
    click EnvInterface "https://github.com/infer-actively/pymdp/blob/master/pymdp/envs/env.py"
    click Grid "https://github.com/infer-actively/pymdp/blob/master/pymdp/envs/grid_worlds.py"
    click TMaze "https://github.com/infer-actively/pymdp/blob/master/pymdp/envs/tmaze.py"
    click Visual "https://github.com/infer-actively/pymdp/blob/master/pymdp/envs/visual_foraging.py"
    click Docs "https://github.com/infer-actively/pymdp/blob/master/docs/index.rst"
    click Examples "https://github.com/infer-actively/pymdp/blob/master/examples/*.ipynb"
    click TestsCore "https://github.com/infer-actively/pymdp/blob/master/test/test_agent.py"
    click TestsJAX "https://github.com/infer-actively/pymdp/blob/master/test/test_agent_jax.py"
    click TestsMATLAB "https://github.com/infer-actively/pymdp/tree/master/test/matlab_crossval/**"
    click CI "https://github.com/infer-actively/pymdp/blob/master/.github/workflows/python-package.yml"

    %% Styles
    classDef core fill:#d0e1f9,stroke:#0366d6,stroke-width:1px
    classDef mod fill:#daf5d9,stroke:#22863a,stroke-width:1px
    classDef utils fill:#f0f0f0,stroke:#6a737d,stroke-width:1px
    classDef jax fill:#ffe5b4,stroke:#d47500,stroke-width:1px
    classDef jax_utils fill:#fff3e0,stroke:#d47500,stroke-width:1px
    classDef external fill:#f5e6ff,stroke:#6f42c1,stroke-width:1px,stroke-dasharray: 5 5
    class User,Docs,Examples,TestsCore,TestsJAX,TestsMATLAB,CI external
```
