How tqcb/nano_nudge works
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.