# acerbilab/pybads architecture

> Architecture diagram of the GitHub repository acerbilab/pybads, 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/acerbilab/pybads
- Repository: https://github.com/acerbilab/pybads

## Overview

##### Project Type and Purpose
- The README makes it clear that the tool is used as an optimization library rather than a full-stack application. The focus is on algorithmic components (poll and search steps) with a clear emphasis on modularity.

##### Analyzing the File Structure
- Top-Level Directories:
- The root contains configuration files (.gitignore, setup.py, pyproject.toml) and workflow definitions under .github which highlight the CI/CD aspects.
- “docsrc” contains the Sphinx documentation source, indicating that the project emphasizes well-documented API and usage examples.
- “examples” provides Jupyter notebooks and Python scripts for demonstrating usage.
- “pybads” is the main package directory. It is further broken into sub-modules like acquisition_functions, bads, decorators, function_logger, init_functions, poll, search, stats, testing, utils, variable_transformer.
- The structure suggests a modular design where each component (such as the optimization algorithm, logging, and utility functions) is isolated in its own module. There is also a specific structure for:
- Core algorithmic components (in pybads/bads)
- Extensions for search strategies (pybads/search) and acquisition functions (pybads/acquisition_functions)
- Support modules (e.g., decorators, stats, variable_transformer, function_logger)
- Testing and examples for demonstration and validation.

##### Insights from the README
- It outlines the typical workflow from defining a target function, setting up optimization bounds, running the optimizer, and interpreting the results.
- Documentation URLs and links to further details (for example about the OptimizeResult class) underscore an API-centric design intended for programmers to integrate the optimizer into their own projects.

##### Architectural Patterns and Design Principles
- Modular Design: Each functionality (e.g., search, polling, option management) is in dedicated subpackages, making the system loosely coupled.
- Layered Architecture: There is an API level that wraps the core optimization engine. Utility modules provide cross-cutting concerns.
- Emphasis on Extensibility: The structure (e.g., decorators, options configs) suggests that it is designed for future enhancements and integration with other systems such as posterior estimation tools.
- Testing and Documentation have first-class status, ensuring reliable builds and thorough guidance.

##### Elements
- Testing/Examples/Documentation (a separate style)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interface / API Layer
    subgraph "User Interface / API Layer"
        UI_Main["__main__.py"]:::ui
        UI_Init["__init__.py"]:::ui
    end

    %% Core Optimization Engine
    subgraph "Core Optimization Engine"
        BADS["BADS Algorithm"]:::core
        Poll["Poll Strategies"]:::core
        Search["Search Strategies"]:::core
        Acquisition["Acquisition Functions"]:::core
    end

    %% Supporting Components
    subgraph "Supporting Components"
        OptionConfigs["Option Configurations"]:::support
        Utilities["Utility Functions"]:::support
        FuncLogger["Function Logging"]:::support
        Decorators["Decorators"]:::support
        Stats["Statistical Tools"]:::support
        VarTrans["Variable Transformations"]:::support
    end

    %% Testing and Examples
    subgraph "Testing and Examples"
        Testing["Testing Suite"]:::test
        Examples["Examples"]:::test
    end

    %% Documentation and CI/CD
    subgraph "Documentation and CI/CD"
        Documentation["Documentation & API Reference"]:::doc
        CICD["CI/CD Workflows"]:::doc
    end

    %% Connections from UI to Core
    UI_Main -->|"calls"| BADS
    UI_Init -->|"initializes"| BADS

    %% Core internal connections
    BADS -->|"executes"| Poll
    BADS -->|"executes"| Search
    Search -->|"utilizes"| Acquisition

    %% Connections from Core to Supporting Components
    BADS -->|"uses"| OptionConfigs
    BADS -->|"uses"| Utilities
    BADS -->|"logs to"| FuncLogger
    BADS -->|"wrapped by"| Decorators
    BADS -->|"analyzes via"| Stats
    BADS -->|"transforms with"| VarTrans

    %% Testing and Examples connections
    Testing -->|"validates"| BADS
    Examples -->|"demonstrates"| UI_Main

    %% External Documentation and CI/CD connections
    Documentation -->|"documents"| BADS
    Documentation -->|"guides"| UI_Main
    CICD -->|"builds/tests"| BADS

    %% Click Events for mapping
    click UI_Main "https://github.com/acerbilab/pybads/blob/main/pybads/__main__.py"
    click UI_Init "https://github.com/acerbilab/pybads/blob/main/pybads/__init__.py"
    click BADS "https://github.com/acerbilab/pybads/blob/main/pybads/bads/bads.py"
    click Poll "https://github.com/acerbilab/pybads/tree/main/pybads/poll/"
    click Search "https://github.com/acerbilab/pybads/tree/main/pybads/search/"
    click Acquisition "https://github.com/acerbilab/pybads/tree/main/pybads/acquisition_functions/"
    click OptionConfigs "https://github.com/acerbilab/pybads/tree/main/pybads/bads/option_configs/"
    click Utilities "https://github.com/acerbilab/pybads/tree/main/pybads/utils/"
    click FuncLogger "https://github.com/acerbilab/pybads/tree/main/pybads/function_logger/"
    click Decorators "https://github.com/acerbilab/pybads/tree/main/pybads/decorators/"
    click Stats "https://github.com/acerbilab/pybads/tree/main/pybads/stats/"
    click VarTrans "https://github.com/acerbilab/pybads/tree/main/pybads/variable_transformer/"
    click Testing "https://github.com/acerbilab/pybads/tree/main/pybads/testing/"
    click Examples "https://github.com/acerbilab/pybads/tree/main/examples/"
    click Documentation "https://github.com/acerbilab/pybads/tree/main/docsrc/"
    click CICD "https://github.com/acerbilab/pybads/tree/main/.github/workflows/"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef support fill:#FFEB99,stroke:#000,stroke-width:2px;
    classDef test fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef doc fill:#D3D3D3,stroke:#000,stroke-width:2px;
```
