# tqcb/nano_nudge architecture

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

- Interactive diagram: https://gitdiagram.com/tqcb/nano_nudge
- Repository: https://github.com/tqcb/nano_nudge

## Overview

##### Project Type and Purpose
- This is a small, open-source Python library (“nano-nudge”) implementing surrogate-based Bayesian Optimization.

##### High-Level Component Breakdown
a. User Interface Layer
- demo_sbo.py (example script/entry point)
- Public API: SurrogateBayesianOptimizer class in optimizer.py
b. Core Optimization Engine
- SurrogateBayesianOptimizer (optimizer.py)
- SurrogateModel (surrogate_model.py)
- Acquisition functions (acquisition.py)
- Trial (trial.py)
- Utility functions / samplers (utility.py)
c. Data / State Management
- Trial objects store (suggestion, value) pairs
- Optimizer.history records all trials and exposes get_best_trial()
d. Extension Points
- Swappable surrogate models (inherits from SurrogateModel)
- Custom acquisition functions (defined or substituted in acquisition.py)
- Future support: parallel q-EI, TPE, categorical/integer spaces

##### Key Interactions and Data Flow
1. User defines objective(trial) and instantiates SurrogateBayesianOptimizer.
2. optimizer.optimize():
a. If first iteration or after acquiring new data, call SurrogateModel.fit(history).
b. Generate a candidate by:
– Trial.suggest_* → uses utility samplers to propose a point within bounds.
– Acquisition.compute( SurrogateModel.predict, candidate_set ) → returns best next point.
c. Pass new Trial to user-provided objective → receive objective value.
d. Append trial to history. Loop until n_trials reached.
3. At end, optimizer.history.get_best_trial() returns the optimal result.

##### Architectural Patterns & Principles
- Separation of concerns:
- SurrogateModel handles probabilistic modeling (e.g., Gaussian Process).
- Acquisition functions quantify exploration vs. exploitation.
- Trial encapsulates a single suggestion + evaluation.
- Optimizer orchestrates the loop and stores history.
- Open/closed for extension: new models and acquisition strategies can be added without modifying existing code.
- Single-responsibility: each module focuses on one aspect of the optimization.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Actor
    User([User / Demo Script]):::actor
    click User "https://github.com/tqcb/nano_nudge/blob/main/demo_sbo.py"

    %% Core Modules
    subgraph "Public API"
        Optimizer["SurrogateBayesianOptimizer\n(optimizer.py)"]:::module
        click Optimizer "https://github.com/tqcb/nano_nudge/blob/main/nano_nudge/optimizer.py"
    end

    subgraph "Core Optimization Engine"
        SM[(SurrogateModel)]:::interface
        click SM "https://github.com/tqcb/nano_nudge/blob/main/nano_nudge/surrogate_model.py"
        AC[(Acquisition Functions)]:::interface
        click AC "https://github.com/tqcb/nano_nudge/blob/main/nano_nudge/acquisition.py"
        TR["Trial\n(trial.py)"]:::module
        click TR "https://github.com/tqcb/nano_nudge/blob/main/nano_nudge/trial.py"
        UT["Utility Samplers\n(utility.py)"]:::utility
        click UT "https://github.com/tqcb/nano_nudge/blob/main/nano_nudge/utility.py"
    end

    %% Data Store
    History[(History Store)]:::data
    click History "https://github.com/tqcb/nano_nudge/blob/main/nano_nudge/optimizer.py"

    %% Relationships
    User -->|"instantiate, provide objective"| Optimizer
    Optimizer -->|"fit(), predict()"| SM
    Optimizer -->|"compute()"| AC
    Optimizer -->|"create Trial"| TR
    TR -->|"suggest_*()"| UT
    TR -->|"evaluate objective"| User
    TR -->|"append()"| History
    History -->|"training data"| SM

    %% Styles
    classDef actor fill:#FFD700,stroke:#B8860B,stroke-width:2px;
    classDef module fill:#87CEEB,stroke:#4682B4,stroke-width:2px;
    classDef interface fill:#E6E6FA,stroke:#9370DB,stroke-width:2px,stroke-dasharray: 5 5;
    classDef data fill:#98FB98,stroke:#2E8B57,stroke-width:2px;
    classDef utility fill:#FFB6C1,stroke:#DB7093,stroke-width:2px;
```
