# lexloki/pybdm-lba architecture

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

- Interactive diagram: https://gitdiagram.com/lexloki/pybdm-lba
- Repository: https://github.com/lexloki/pybdm-lba

## Overview

##### Main Components
- Core Library (pybdm):
- This package contains the core functionality. The main components include:
– BDM module (bdm.py): Implements the object-oriented API for computing algorithmic complexity.
– Algorithms (algorithms.py): Contains additional routines such as perturbation experiments.
– Utility Modules (encoding.py, options.py, partitions.py, utils.py): Provide supporting operations like data transformation, configuring parameters, or decomposing datasets.
– CTM Data (pybdm/ctmdata): Holds precomputed datasets in compressed pickle files.
- LBA Generation (lba_generation):
- Supports extension datasets and utilities for Linear Bounded Automata (LBA) operations.
- Includes example notebooks, external data sets, and test call scripts.
- Tests:
- The tests/ directory provides unit tests for validating the correct behavior of algorithmic modules.
- Documentation:
- The docs/ directory sets up Sphinx documentation to provide user guides and reference material.
- Build/Configuration & Packaging:
- Files like setup.py, requirements.txt, Makefile, and configuration files (e.g., setup.cfg, tox.ini) support building, testing, and packaging the library.

##### Relationships and Data Flow
- At the highest level, users/programs import the library (pybdm) to obtain a BDM object.
- The BDM object interacts with various utility components and data sources (CTM datasets) to perform its computations.
- For advanced features, such as perturbation analysis, the BDM object calls functions from the algorithms module.
- The lba_generation directory supports experiments and data generation that feed into or exemplify the library’s methods.
- Parallel processing is taken into account (using joblib), so indicate that the BDM methods can delegate sub-tasks to parallel worker processes.
- External dependencies like NumPy and joblib can be depicted as external resources that interface with the core modules.

##### Architectural Patterns and Design Principles
- Object-Oriented Design: The architecture inside the pybdm package is based on classes (e.g., the BDM class and the PerturbationExperiment class).
- Modularization: Functions and algorithms are divided across multiple modules allowing for clear separation of concerns.
- Extendability: The separation of the core algorithm (in pybdm) from dataset generation (in lba_generation) is a design that supports extension for different types of input (i.e., Turing Machines vs. LBAs).

- Nodes/Blocks:
- User/Application Code (client code that instantiates and uses BDM).
- PyBDM Core Module:
» BDM API (bdm.py)
» Auxiliary Algorithms (algorithms.py, perturbation tests)
» Utility Modules (encoding, options, partitions, utils)
» CTM dataset access (pybdm/ctmdata)
- LBA Generation Module:
» Jupyter Notebook (bdm.ipynb)
» CTM data files and test call scripting (lba_test_call.cpp, etc.)
- Testing Framework:
» Unit tests from the tests/ directory.
- Documentation/Build Pipeline:
» Sphinx configuration and documentation in docs/.
- External Libraries:
» NumPy for array handling.
» Joblib for parallel processing.
» Others (if needed, e.g., logging, packaging tools).
- That, for parallel processing, tasks flow from the BDM API to external joblib processes.
- That the LBA Generation module outputs or supports data that may be consumed by the BDM modules.
- Test pipeline actively verifying components in the pybdm package.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User & External Dependencies
    U["User/Application Code"]:::userapps
    Num["NumPy"]:::external
    Job["Joblib"]:::external

    %% PyBDM Core Modules
    subgraph "PyBDM Core Modules"
        BDM["pybdm/bdm.py: BDM API"]:::core
        Alg["pybdm/algorithms.py: Algorithms Module"]:::core
        CTM["pybdm/ctmdata: CTM Data Access"]:::core
    end

    %% PyBDM Utility Modules
    subgraph "PyBDM Utility Modules"
        Enc["pybdm/encoding.py"]:::core
        Opt["pybdm/options.py"]:::core
        Part["pybdm/partitions.py"]:::core
        Util["pybdm/utils.py"]:::core
    end

    %% LBA Generation Module
    subgraph "LBA Generation Module"
        LBA_NB["lba_generation/bdm.ipynb: Experiment Notebook"]:::extension
        LBA_TC["lba_generation/lba_test_call.cpp: Test Call Script"]:::extension
    end

    %% Testing Framework
    subgraph "Testing Framework"
        Test["tests: Unit Tests"]:::testing
    end

    %% Documentation & Build/Packaging
    subgraph "Documentation & Build/Packaging"
        Docs["docs: Sphinx Docs & Guides"]:::docs
        Build["Build & Packaging\n(setup.py, Makefile, requirements.txt,\nsetup.cfg, tox.ini)"]:::build
    end

    %% Relationships and Data Flow
    U -->|"imports"| BDM
    BDM -->|"calls"| Alg
    BDM -->|"accesses"| CTM
    BDM -->|"utilizes"| Enc
    BDM -->|"utilizes"| Opt
    BDM -->|"utilizes"| Part
    BDM -->|"utilizes"| Util
    BDM -->|"delegates_parallel"| Job
    Num -->|"used_by"| BDM

    LBA_NB -->|"supports_experiment"| BDM
    LBA_TC -->|"provides_testdata"| BDM

    U -->|"executes"| Test
    Test -->|"validates"| BDM
    Test -->|"validates"| Alg
    Test -->|"validates"| Enc
    Test -->|"validates"| Opt
    Test -->|"validates"| Part
    Test -->|"validates"| Util

    Docs -->|"documents"| BDM
    Docs -->|"documents"| Alg
    Docs -->|"documents"| Enc
    Docs -->|"documents"| Opt
    Docs -->|"documents"| Part
    Docs -->|"documents"| Util

    Build -->|"builds"| BDM
    Build -->|"builds"| Alg
    Build -->|"builds"| Enc
    Build -->|"builds"| Opt
    Build -->|"builds"| Part
    Build -->|"builds"| Util

    %% Styles Definitions
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef extension fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef testing fill:#d6d8d9,stroke:#343a40,stroke-width:2px;
    classDef docs fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef build fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef userapps fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef external fill:#f5c6cb,stroke:#721c24,stroke-width:2px;

    %% Click Events
    click BDM "https://github.com/lexloki/pybdm-lba/blob/master/pybdm/bdm.py"
    click Alg "https://github.com/lexloki/pybdm-lba/blob/master/pybdm/algorithms.py"
    click CTM "https://github.com/lexloki/pybdm-lba/tree/master/pybdm/ctmdata"
    click Enc "https://github.com/lexloki/pybdm-lba/blob/master/pybdm/encoding.py"
    click Opt "https://github.com/lexloki/pybdm-lba/blob/master/pybdm/options.py"
    click Part "https://github.com/lexloki/pybdm-lba/blob/master/pybdm/partitions.py"
    click Util "https://github.com/lexloki/pybdm-lba/blob/master/pybdm/utils.py"
    click LBA_NB "https://github.com/lexloki/pybdm-lba/blob/master/lba_generation/bdm.ipynb"
    click LBA_TC "https://github.com/lexloki/pybdm-lba/blob/master/lba_generation/lba_test_call.cpp"
    click Test "https://github.com/lexloki/pybdm-lba/tree/master/tests"
    click Docs "https://github.com/lexloki/pybdm-lba/tree/master/docs"
    click Build "https://github.com/lexloki/pybdm-lba/blob/master/setup.py"
```
