# acerbilab/pyvbmc architecture

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

- Interactive diagram: https://gitdiagram.com/acerbilab/pyvbmc
- Repository: https://github.com/acerbilab/pyvbmc

## Overview

##### Project Type and Purpose
- PyVBMC is a specialized Python library for sample-efficient Bayesian inference. Its primary goal is to approximate posterior distributions and estimate model evidence (ELBO) by combining variational inference with Bayesian quadrature.
- The README explains that the package is designed to be used when model likelihood evaluations are expensive or noisy. It provides a high-level API to define a target (log) density, set parameter bounds, run VBMC inference, and examine results.
- The project is structured for both users (via the public API) and developers (with extensive testing, CI/CD workflows, and detailed documentation).

##### File Structure Analysis
- The top-level directories include configuration files, CI configurations, the documentation folder (docsrc), examples, and the core source code folder (pyvbmc).
- Inside the pyvbmc folder, you see a set of submodules. These are clearly separated by functionality:
- "acquisition_functions": Contains various acquisition function implementations (e.g., for active sampling).
- "decorators": Implements function wrappers to standardize input handling.
- "entropy": Contains methods for entropy estimation.
- "formatting": Provides output formatting utilities.
- "function_logger": Logging functionalities around function evaluations.
- "parameter_transformer": Deals with transforming or scaling input parameters.
- "priors": Contains function and class definitions to support different prior distributions.
- "stats": Implements statistical methods such as computing high probability density (HPD) intervals or kernel density estimation.
- "timer": Timing utilities.
- "variational_posterior": Defines the VariationalPosterior class that captures the variational approximation to the target density.
- "vbmc": The core logic of the VBMC algorithm, including optimization routines like "minimize_adam" and procedures for active sampling and Gaussian process training.
- "whitening": Handles pre-processing (e.g., input whitening) for more stable inference.
- A robust testing suite is available under "pyvbmc/testing", where unit tests for each submodule (and even MATLAB comparisons) ensure proper integration.
- The existence of documentation (in docsrc) and example notebooks/scripts facilitates both end-user guidance and contributing developers’ understanding.

A. Core Engine:
- The central hub is the VBMC inference loop (located in the pyvbmc/vbmc module). It integrates several subcomponents:
- It receives user inputs (target log-density function, starting points, and parameter bounds).
- It orchestrates function evaluations and manages the iterative sampling process.
∘ Acquisition Functions (pyvbmc/acquisition_functions): Responsible for choosing the next evaluation points via active sampling.
∘ Gaussian Process Training: Part of the VBMC module (e.g., gaussian_process_train.py) to build the surrogate model of the (log) posterior.
∘ Optimization Routines: Represented by functions like "minimize_adam" and "variational_optimization" that update the variational posterior.
∘ Active Sampling: Uses components from both acquisition functions and GP modeling to decide where to sample next.

B. Supporting Subsystems:
- Modules for Utilities:
- Parameter Transformer: Adjusts and scales inputs.
- Priors: Creates and manages the prior distributions which feed into the inference.
- Function Logger & Timer: Monitor and record evaluation metrics and timing information.
- Entropy & Stats: Compute entropy estimates and other diagnostic measures essential for the ELBO estimation.
- Visual Representation: Place these utility services as auxiliary blocks connected to the core engine, indicating that they provide data, logging, or processing support to the central VBMC algorithm.

C. External Interfaces:
- User Interface/CLI: Indicated by the __main__.py file in the pyvbmc module, which provides a command-line entry point.
- Examples & Documentation: Represent how users might interact with the system through notebooks and the online documentation (docsrc). Though not part of the runtime engine, these components are essential for understanding and validating the system.

##### Architectural Patterns and Design Principles
- Modularity: Every core functionality (from acquisition functions to priors) has a dedicated module. Emphasize these distinct boundaries with separate labeled blocks.
- Separation of Concerns: The user interface, core algorithm (inference loop), utility functions, and testing are clearly separated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    UI["User Inputs"]

    %% Core Engine and Internal Modules
    E["PyVBMC Engine"]:::engine

    subgraph "Core Modules"
        AF["Acquisition Functions"]:::module
        GP["Gaussian Process Training"]:::module
        subgraph "Optimization Routines"
            OR1["Minimize Adam"]:::module
            OR2["Variational Optimization"]:::module
        end
        subgraph "Active Sampling"
            AS1["Active Sample"]:::module
            AS2["Active Importance Sampling"]:::module
        end
        VP["Variational Posterior"]:::module
        WH["Preprocessing (Whitening)"]:::module
    end

    %% Utility Services
    subgraph "Utility Services"
        PT["Parameter Transformer"]:::utility
        PR["Priors"]:::utility
        FL["Function Logger"]:::utility
        TM["Timer"]:::utility
        EN["Entropy Estimation"]:::utility
        ST["Stats Diagnostics"]:::utility
    end

    %% External Interfaces
    subgraph "External Interfaces"
        CLI["User Interface/CLI"]:::external
        DOC["Documentation & Examples"]:::external
        TEST["Testing Suite"]:::external
    end

    %% Connections: Initialization
    UI -->|"provides data"| E

    %% Connections: Core Engine interactions
    E -->|"triggers"| AF
    E -->|"triggers"| GP
    E -->|"invokes"| OR1
    E -->|"invokes"| OR2
    E -->|"triggers"| AS1
    E -->|"triggers"| AS2
    E -->|"updates"| VP
    E -->|"applies"| WH

    %% Feedback loops within core modules
    GP -->|"informs"| AF
    OR1 -->|"optimizes"| VP
    OR2 -->|"optimizes"| VP
    AS1 -->|"selects points"| E
    AS2 -->|"selects points"| E

    %% Utility Services supporting the Engine
    PT -->|"transforms"| E
    PR -->|"supplies priors"| E
    FL -->|"logs"| E
    TM -->|"times"| E
    EN -->|"estimates"| E
    ST -->|"provides stats"| E

    %% External Interfaces interactions
    CLI -->|"launches"| E
    DOC -->|"guides users"| E
    TEST -- "validates" --> E

    %% Click Events for Core Engine Components
    click E "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/vbmc/vbmc.py"
    click AF "https://github.com/acerbilab/pyvbmc/tree/main/pyvbmc/acquisition_functions/"
    click GP "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/vbmc/gaussian_process_train.py"
    click OR1 "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/vbmc/minimize_adam.py"
    click OR2 "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/vbmc/variational_optimization.py"
    click AS1 "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/vbmc/active_sample.py"
    click AS2 "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/vbmc/active_importance_sampling.py"
    click VP "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/variational_posterior/variational_posterior.py"
    click WH "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/whitening/whitening.py"

    %% Click Events for Utility Services
    click PT "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/parameter_transformer/parameter_transformer.py"
    click PR "https://github.com/acerbilab/pyvbmc/tree/main/pyvbmc/priors/"
    click FL "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/function_logger/function_logger.py"
    click TM "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/timer/timer.py"
    click EN "https://github.com/acerbilab/pyvbmc/tree/main/pyvbmc/entropy/"
    click ST "https://github.com/acerbilab/pyvbmc/tree/main/pyvbmc/stats/"

    %% Click Event for External Interface
    click CLI "https://github.com/acerbilab/pyvbmc/blob/main/pyvbmc/__main__.py"
    click DOC "https://github.com/acerbilab/pyvbmc/tree/main/docsrc/"
    click TEST "https://github.com/acerbilab/pyvbmc/tree/main/pyvbmc/testing/"

    %% Class Definitions for Colors
    classDef engine fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef module fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef utility fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef external fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
