synbo 0.1.0__tar.gz

synbo-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ReactionOpt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synbo-0.1.0/PKG-INFO

@@ -0,0 +1,365 @@
+Metadata-Version: 2.4
+Name: synbo
+Version: 0.1.0
+Summary: A multi-objective reaction optimization framework based on Bayesian Optimization
+Author-email: Zhenzhi Tan <tanzhenzhi8@gmail.com>
+Maintainer-email: Zhenzhi Tan <tanzhenzhi8@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 ReactionOpt
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Bug Tracker, https://github.com/yourusername/reactionopt/issues
+Project-URL: Documentation, https://reactionopt.readthedocs.io
+Project-URL: Homepage, https://github.com/yourusername/reactionopt
+Project-URL: Repository, https://github.com/yourusername/reactionopt
+Keywords: chemistry,reaction optimization,bayesian optimization,machine learning,catalysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: scikit-learn>=1.0.0
+Requires-Dist: matplotlib>=3.3.0
+Requires-Dist: seaborn>=0.11.0
+Requires-Dist: openpyxl>=3.0.0
+Requires-Dist: tqdm>=4.60.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: torch>=2.8.0
+Requires-Dist: botorch>=0.15.0
+Requires-Dist: ax-platform>=0.2.0
+Requires-Dist: rdkit>=2024.9.1
+Requires-Dist: pyDOE>=0.3.8
+Requires-Dist: lxml>=6.0.2
+Requires-Dist: epam.indigo>=1.36.1
+Requires-Dist: openai>=2.20.0
+Requires-Dist: tabulate>=0.10.0
+Requires-Dist: qspoc>=0.5.0
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.8; extra == "dev"
+Requires-Dist: mypy>=0.800; extra == "dev"
+Requires-Dist: pre-commit>=2.10; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=4.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
+Requires-Dist: myst-parser>=0.15; extra == "docs"
+Provides-Extra: test
+Requires-Dist: pytest>=6.0; extra == "test"
+Requires-Dist: pytest-cov>=2.0; extra == "test"
+Requires-Dist: pytest-mock>=3.0; extra == "test"
+Dynamic: license-file
+
+# SynBO: Synthetic Bayesian Optimization for Reaction Condition Screening
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-312/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**SynBO** (Synthetic Bayesian Optimization) is an intelligent reaction optimization tool designed specifically for synthetic chemists. It uses Bayesian Optimization (BO) algorithms to help you find optimal reaction conditions with minimal experimental effort.
+
+---
+
+## Why Do Chemists Need SynBO?
+
+Optimizing a new chemical reaction typically involves screening numerous combinations of reaction conditions:
+
+- **Catalysts** (various organocatalysts or metal complexes)
+- **Solvents** 
+- **Bases/Additives** (acids/bases, ligands, electrolyte etc.)
+- **Temperature**
+- **Concentration**
+- **reaction time**, etc.
+
+The traditional approach is **OFAT** (One-Factor-At-A-Time). But with 5 catalysts × 5 solvents × 4 bases × 4 temperatures = **400 combinations**, this is clearly impractical.
+
+**SynBO's Solution**: Like an experienced chemist, it "learns" from previous experiments and "predicts" which conditions are most likely to succeed next. Typically, you only need **50-80 experiments** to find optimal conditions.
+
+---
+
+## How Does Bayesian Optimization Work?
+
+Imagine you are a mountain climber searching for the highest peak in the dark:
+
+1. **Initialization**: Take a few random steps and record the altitude (corresponds to: randomly run a few experimeecord yield/selectivity)
+2. **Build a Mental Map**: Based on where you've been, infer the shape of the entire mountain (corresponds to: algorithm learns reaction patterns)
+3. **Intelligent Decision**: Go to places that might be higher (exploitation), but also explore unknown areas (exploration)
+4. **Iterate**: Repeat steps 2-3 until you find the highest peak (corresponds to: finding optimal reaction conditions)
+
+**Chemistry Analogy**:
+- Just like when you optimize reactions in the lab, adjusting your strategy based on previous rounds
+- If a particular catalyst performs well, you'll try similar catalysts (exploitation)
+- But you'll also try some conditions that look different, in case you miss something better (exploration)
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Requires Python 3.12 or higher
+pip install synbo
+```
+
+### Basic Example: Optimizing a Coupling Reaction
+
+```python
+from synbo import ReactionOptimizer
+import pandas as pd
+
+# 1. Create optimizer and specify objectives
+optimizer = ReactionOptimizer(
+    opt_metrics=['yield', 'ee'],  # Optimize both yield and enantioselectivity
+    opt_type='auto',               # Auto-detect init or optimization phase
+    random_seed=42
+)
+
+# 2. Define reaction space (all possible condition combinations)
+condition_dict = {
+    'catalyst': ['Pd(OAc)2', 'Pd(PPh3)4', 'Pd2(dba)3', 'Xantphos-Pd'],
+    'solvent': ['THF', 'Dioxane', 'Toluene', 'DMF', 'MeCN'],
+    'base': ['Cs2CO3', 'K2CO3', 'NaOEt', 'DBU', 'Et3N'],
+    'temperature': [25, 50, 80, 100]
+}
+optimizer.load_rxn_space(condition_dict)
+
+# 3. Load molecular descriptors (optional, for more accurate predictions)
+# If not provided, system will automatically use OneHot encoding
+optimizer.load_desc()
+
+# 4. Run first batch of experiments (recommend 5-10, Latin Hypercube Sampling)
+optimizer.run(batch_size=8)
+
+# 5. Save recommended experimental conditions
+optimizer.save_results(filetype='csv')  # Generates "recommended_batch_0.csv"
+
+# ============================================
+# After completing these experiments in lab, fill results into CSV
+# ============================================
+
+# 6. Load completed experimental results
+results = pd.read_csv('experimental_results.csv')  # Must contain 'yield' and 'ee' columns
+optimizer.load_prev_rxn(results)
+
+# 7. Continue optimization, algorithm recommends next batch based on data
+optimizer.run(batch_size=5)
+optimizer.save_results(filetype='csv')  # Generates "recommended_batch_1.csv"
+
+# Repeat steps 6-7 until satisfactory yield and selectivity are achieved
+```
+
+### Single-Objective Optimization (Yield Only)
+
+```python
+optimizer = ReactionOptimizer(
+    opt_metrics='yield',  # Only optimize yield
+    opt_metric_settings={
+        'opt_direct': 'max',      # Maximize
+        'opt_range': [0, 100],    # Yield range 0-100%
+        'metric_weight': 1.0
+    }
+)
+```
+
+### Multi-Objective Optimization (Yield + Enantioselectivity)
+
+```python
+optimizer = ReactionOptimizer(
+    opt_metrics=['yield', 'ee'],
+    opt_metric_settings=[
+        {'opt_direct': 'max', 'opt_range': [0, 100], 'metric_weight': 1.0},  # Yield
+        {'opt_direct': 'max', 'opt_range': [0, 100], 'metric_weight': 2.0}   # ee, higher weight
+    ]
+)
+```
+
+---
+
+## 🔬 Advanced Features
+
+### 1. LLM-Powered Analysis of Failed Experiments
+
+When certain condition combinations repeatedly fail, SynBO can call a Large Language Model (LLM) to analyze the causes and automatically exclude these "problematic reagents":
+
+```python
+# After round 3, let AI analyze which conditions to avoid
+constraints = optimizer.get_constraints(method='llm')
+
+# Apply constraints to next round of optimization
+optimizer.run(batch_size=5, constraints=constraints)
+```
+
+**Application Scenarios**:
+- Discover "DBU + high temperature" always leads to decomposition → Auto-exclude
+- Discover "toluene solvent" works best with specific catalyst → Prioritize similar combinations
+
+### 2. Track Optimization Progress (Hypervolume)
+
+In multi-objective optimization, the Hypervolume metric helps you determine if you're approaching the optimum:
+
+```python
+# Calculate Hypervolume for current Pareto front
+hv = optimizer.calculate_current_hv()
+print(f"Current optimization progress: {hv['hv_normalized']*100:.1f}%")
+
+# View progress across rounds
+progress = optimizer.calculate_hv_by_batch()
+```
+
+**Chemistry Explanation**:
+- Hypervolume measures the "performance space" covered by currently found optimal conditions
+- When Hypervolume growth slows down, you're near optimal and can consider stopping experiments
+
+### 3. Choose Different Optimization Strategies
+
+```python
+# Standard Bayesian Optimization (Recommended)
+optimizer.run(optimize_method='default_BO')
+
+# Particle Swarm (suitable for complex nonlinear relationships)
+optimizer.run(optimize_method='particle_swarm')
+
+# Evolutionary Algorithm (suitable for discrete space search)
+optimizer.run(optimize_method='evolution')
+
+# Random Search (baseline comparison)
+optimizer.run(optimize_method='random_select')
+```
+
+---
+
+## 📊 The Chemistry Behind the Algorithms
+
+### Surrogate Models — "Predicting Reaction Outcomes"
+
+| Model | Chemistry Intuition | Best For |
+|-------|---------------------|----------|
+| **GP (Gaussian Process)** | Assumes similar conditions give similar results | Fewer experiments (<50), clear reaction mechanisms |
+| **Random Forest** | Voting via multiple decision trees | Many categorical variables (many catalyst/solvent types) |
+| **BNN (Neural Network Ensemble)** | Deep learning for complex nonlinear relationships | Large-scale high-throughput screening (>100 experiments) |
+| **Bayesian Linear** | Linear approximation, fast but simple | Preliminary screening, need quick results |
+
+### Acquisition Functions — "Choosing the Next Experiment"
+
+| Function | Chemistry Strategy | When to Use |
+|----------|-------------------|-------------|
+| **EHVI** (Default) | Balance yield and selectivity, find Pareto optimal frontier | Optimizing yield and ee simultaneously, both important |
+| **UCB** | Conservative strategy, prioritize high-yield conditions with certainty | Limited time, cannot afford failures |
+| **ParEGO** | Transform multi-objective into single-objective | More than 2 objectives (e.g., yield + ee + cost) |
+| **NEI** | Account for experimental error | High variability in replicate experiments |
+
+---
+
+## 📁 Real-World Case Studies
+
+### Case 1: Asymmetric Hydrogenation
+
+**Background**: Screening chiral phosphoric acid catalysts for imine asymmetric hydrogenation
+
+```python
+condition_dict = {
+    'catalyst': ['CPA-1', 'CPA-2', 'CPA-3', 'CPA-4', 'CPA-5', 'CPA-6'],
+    'additive': ['MsOH', 'TfOH', 'TFA', 'None'],
+    'solvent': ['DCE', 'PhCF3', 'Toluene', 'Et2O'],
+    'temperature': [-20, 0, 25, 40],
+    'H2_pressure': [1, 10, 20, 50]  # atm
+}
+
+# Optimization objective: High yield + High ee
+optimizer = ReactionOptimizer(
+    opt_metrics=['yield', 'ee'],
+    opt_type='auto'
+)
+```
+
+**Result**: Only 24 experiments needed (vs. 384 full combinations), found conditions with 94% yield and 98% ee.
+
+### Case 2: Buchwald-Hartwig Amination
+
+**Background**: Pd-catalyzed aromatic amination, screening ligand and base combinations
+
+```python
+# Use LLM to analyze failed ligand-base combinations
+constraints = optimizer.get_constraints(method='llm')
+# LLM identifies "XPhos + strong base" leads to catalyst deactivation
+# Automatically excludes these combinations, saving experimental time
+```
+
+---
+
+## 🔧 Project Structure
+
+```
+synbo/
+├── synbo.py              # Main optimizer class
+├── initialize.py         # Initial sampling strategies (Latin Hypercube, etc.)
+├── optimize.py           # Optimization algorithm dispatcher
+├── algorithm/
+│   ├── bo_core.py        # Bayesian optimization core
+│   ├── acq_function.py   # Acquisition functions (EHVI/UCB/ParEGO/NEI)
+│   ├── sg_model.py       # Surrogate models (GP/RF/BNN)
+│   ├── evolution.py      # Evolutionary algorithm
+│   └── particle_swarm.py # Particle swarm algorithm
+├── descriptor/           # Molecular descriptor processing (RDKit support)
+├── analysis/             # LLM-powered analysis module
+└── utils/                # Utility functions (visualization, I/O, etc.)
+```
+
+---
+
+## 📚 Citation
+
+If you use SynBO in your research, please cite:
+
+```bibtex
+@software{synbo2025,
+  title={SynBO: Synthetic Bayesian Optimization for Chemical Reaction Optimization},
+  author={Zhenzhi Tan},
+  year={2025},
+  url={https://github.com/yourusername/synbo}
+}
+```
+
+---
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome! For synthetic chemistry-related feature suggestions, please describe your reaction type and optimization needs in detail.
+
+---
+
+## 📧 Contact
+
+- **Author**: Zhenzhi Tan
+- **Email**: zhenzhi-tan@outlook.com
+
+---
+
+**Happy Synthesizing! 🧪⚗️**

synbo-0.1.0/README.md

@@ -0,0 +1,286 @@
+# SynBO: Synthetic Bayesian Optimization for Reaction Condition Screening
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/release/python-312/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**SynBO** (Synthetic Bayesian Optimization) is an intelligent reaction optimization tool designed specifically for synthetic chemists. It uses Bayesian Optimization (BO) algorithms to help you find optimal reaction conditions with minimal experimental effort.
+
+---
+
+## Why Do Chemists Need SynBO?
+
+Optimizing a new chemical reaction typically involves screening numerous combinations of reaction conditions:
+
+- **Catalysts** (various organocatalysts or metal complexes)
+- **Solvents** 
+- **Bases/Additives** (acids/bases, ligands, electrolyte etc.)
+- **Temperature**
+- **Concentration**
+- **reaction time**, etc.
+
+The traditional approach is **OFAT** (One-Factor-At-A-Time). But with 5 catalysts × 5 solvents × 4 bases × 4 temperatures = **400 combinations**, this is clearly impractical.
+
+**SynBO's Solution**: Like an experienced chemist, it "learns" from previous experiments and "predicts" which conditions are most likely to succeed next. Typically, you only need **50-80 experiments** to find optimal conditions.
+
+---
+
+## How Does Bayesian Optimization Work?
+
+Imagine you are a mountain climber searching for the highest peak in the dark:
+
+1. **Initialization**: Take a few random steps and record the altitude (corresponds to: randomly run a few experimeecord yield/selectivity)
+2. **Build a Mental Map**: Based on where you've been, infer the shape of the entire mountain (corresponds to: algorithm learns reaction patterns)
+3. **Intelligent Decision**: Go to places that might be higher (exploitation), but also explore unknown areas (exploration)
+4. **Iterate**: Repeat steps 2-3 until you find the highest peak (corresponds to: finding optimal reaction conditions)
+
+**Chemistry Analogy**:
+- Just like when you optimize reactions in the lab, adjusting your strategy based on previous rounds
+- If a particular catalyst performs well, you'll try similar catalysts (exploitation)
+- But you'll also try some conditions that look different, in case you miss something better (exploration)
+
+---
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Requires Python 3.12 or higher
+pip install synbo
+```
+
+### Basic Example: Optimizing a Coupling Reaction
+
+```python
+from synbo import ReactionOptimizer
+import pandas as pd
+
+# 1. Create optimizer and specify objectives
+optimizer = ReactionOptimizer(
+    opt_metrics=['yield', 'ee'],  # Optimize both yield and enantioselectivity
+    opt_type='auto',               # Auto-detect init or optimization phase
+    random_seed=42
+)
+
+# 2. Define reaction space (all possible condition combinations)
+condition_dict = {
+    'catalyst': ['Pd(OAc)2', 'Pd(PPh3)4', 'Pd2(dba)3', 'Xantphos-Pd'],
+    'solvent': ['THF', 'Dioxane', 'Toluene', 'DMF', 'MeCN'],
+    'base': ['Cs2CO3', 'K2CO3', 'NaOEt', 'DBU', 'Et3N'],
+    'temperature': [25, 50, 80, 100]
+}
+optimizer.load_rxn_space(condition_dict)
+
+# 3. Load molecular descriptors (optional, for more accurate predictions)
+# If not provided, system will automatically use OneHot encoding
+optimizer.load_desc()
+
+# 4. Run first batch of experiments (recommend 5-10, Latin Hypercube Sampling)
+optimizer.run(batch_size=8)
+
+# 5. Save recommended experimental conditions
+optimizer.save_results(filetype='csv')  # Generates "recommended_batch_0.csv"
+
+# ============================================
+# After completing these experiments in lab, fill results into CSV
+# ============================================
+
+# 6. Load completed experimental results
+results = pd.read_csv('experimental_results.csv')  # Must contain 'yield' and 'ee' columns
+optimizer.load_prev_rxn(results)
+
+# 7. Continue optimization, algorithm recommends next batch based on data
+optimizer.run(batch_size=5)
+optimizer.save_results(filetype='csv')  # Generates "recommended_batch_1.csv"
+
+# Repeat steps 6-7 until satisfactory yield and selectivity are achieved
+```
+
+### Single-Objective Optimization (Yield Only)
+
+```python
+optimizer = ReactionOptimizer(
+    opt_metrics='yield',  # Only optimize yield
+    opt_metric_settings={
+        'opt_direct': 'max',      # Maximize
+        'opt_range': [0, 100],    # Yield range 0-100%
+        'metric_weight': 1.0
+    }
+)
+```
+
+### Multi-Objective Optimization (Yield + Enantioselectivity)
+
+```python
+optimizer = ReactionOptimizer(
+    opt_metrics=['yield', 'ee'],
+    opt_metric_settings=[
+        {'opt_direct': 'max', 'opt_range': [0, 100], 'metric_weight': 1.0},  # Yield
+        {'opt_direct': 'max', 'opt_range': [0, 100], 'metric_weight': 2.0}   # ee, higher weight
+    ]
+)
+```
+
+---
+
+## 🔬 Advanced Features
+
+### 1. LLM-Powered Analysis of Failed Experiments
+
+When certain condition combinations repeatedly fail, SynBO can call a Large Language Model (LLM) to analyze the causes and automatically exclude these "problematic reagents":
+
+```python
+# After round 3, let AI analyze which conditions to avoid
+constraints = optimizer.get_constraints(method='llm')
+
+# Apply constraints to next round of optimization
+optimizer.run(batch_size=5, constraints=constraints)
+```
+
+**Application Scenarios**:
+- Discover "DBU + high temperature" always leads to decomposition → Auto-exclude
+- Discover "toluene solvent" works best with specific catalyst → Prioritize similar combinations
+
+### 2. Track Optimization Progress (Hypervolume)
+
+In multi-objective optimization, the Hypervolume metric helps you determine if you're approaching the optimum:
+
+```python
+# Calculate Hypervolume for current Pareto front
+hv = optimizer.calculate_current_hv()
+print(f"Current optimization progress: {hv['hv_normalized']*100:.1f}%")
+
+# View progress across rounds
+progress = optimizer.calculate_hv_by_batch()
+```
+
+**Chemistry Explanation**:
+- Hypervolume measures the "performance space" covered by currently found optimal conditions
+- When Hypervolume growth slows down, you're near optimal and can consider stopping experiments
+
+### 3. Choose Different Optimization Strategies
+
+```python
+# Standard Bayesian Optimization (Recommended)
+optimizer.run(optimize_method='default_BO')
+
+# Particle Swarm (suitable for complex nonlinear relationships)
+optimizer.run(optimize_method='particle_swarm')
+
+# Evolutionary Algorithm (suitable for discrete space search)
+optimizer.run(optimize_method='evolution')
+
+# Random Search (baseline comparison)
+optimizer.run(optimize_method='random_select')
+```
+
+---
+
+## 📊 The Chemistry Behind the Algorithms
+
+### Surrogate Models — "Predicting Reaction Outcomes"
+
+| Model | Chemistry Intuition | Best For |
+|-------|---------------------|----------|
+| **GP (Gaussian Process)** | Assumes similar conditions give similar results | Fewer experiments (<50), clear reaction mechanisms |
+| **Random Forest** | Voting via multiple decision trees | Many categorical variables (many catalyst/solvent types) |
+| **BNN (Neural Network Ensemble)** | Deep learning for complex nonlinear relationships | Large-scale high-throughput screening (>100 experiments) |
+| **Bayesian Linear** | Linear approximation, fast but simple | Preliminary screening, need quick results |
+
+### Acquisition Functions — "Choosing the Next Experiment"
+
+| Function | Chemistry Strategy | When to Use |
+|----------|-------------------|-------------|
+| **EHVI** (Default) | Balance yield and selectivity, find Pareto optimal frontier | Optimizing yield and ee simultaneously, both important |
+| **UCB** | Conservative strategy, prioritize high-yield conditions with certainty | Limited time, cannot afford failures |
+| **ParEGO** | Transform multi-objective into single-objective | More than 2 objectives (e.g., yield + ee + cost) |
+| **NEI** | Account for experimental error | High variability in replicate experiments |
+
+---
+
+## 📁 Real-World Case Studies
+
+### Case 1: Asymmetric Hydrogenation
+
+**Background**: Screening chiral phosphoric acid catalysts for imine asymmetric hydrogenation
+
+```python
+condition_dict = {
+    'catalyst': ['CPA-1', 'CPA-2', 'CPA-3', 'CPA-4', 'CPA-5', 'CPA-6'],
+    'additive': ['MsOH', 'TfOH', 'TFA', 'None'],
+    'solvent': ['DCE', 'PhCF3', 'Toluene', 'Et2O'],
+    'temperature': [-20, 0, 25, 40],
+    'H2_pressure': [1, 10, 20, 50]  # atm
+}
+
+# Optimization objective: High yield + High ee
+optimizer = ReactionOptimizer(
+    opt_metrics=['yield', 'ee'],
+    opt_type='auto'
+)
+```
+
+**Result**: Only 24 experiments needed (vs. 384 full combinations), found conditions with 94% yield and 98% ee.
+
+### Case 2: Buchwald-Hartwig Amination
+
+**Background**: Pd-catalyzed aromatic amination, screening ligand and base combinations
+
+```python
+# Use LLM to analyze failed ligand-base combinations
+constraints = optimizer.get_constraints(method='llm')
+# LLM identifies "XPhos + strong base" leads to catalyst deactivation
+# Automatically excludes these combinations, saving experimental time
+```
+
+---
+
+## 🔧 Project Structure
+
+```
+synbo/
+├── synbo.py              # Main optimizer class
+├── initialize.py         # Initial sampling strategies (Latin Hypercube, etc.)
+├── optimize.py           # Optimization algorithm dispatcher
+├── algorithm/
+│   ├── bo_core.py        # Bayesian optimization core
+│   ├── acq_function.py   # Acquisition functions (EHVI/UCB/ParEGO/NEI)
+│   ├── sg_model.py       # Surrogate models (GP/RF/BNN)
+│   ├── evolution.py      # Evolutionary algorithm
+│   └── particle_swarm.py # Particle swarm algorithm
+├── descriptor/           # Molecular descriptor processing (RDKit support)
+├── analysis/             # LLM-powered analysis module
+└── utils/                # Utility functions (visualization, I/O, etc.)
+```
+
+---
+
+## 📚 Citation
+
+If you use SynBO in your research, please cite:
+
+```bibtex
+@software{synbo2025,
+  title={SynBO: Synthetic Bayesian Optimization for Chemical Reaction Optimization},
+  author={Zhenzhi Tan},
+  year={2025},
+  url={https://github.com/yourusername/synbo}
+}
+```
+
+---
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome! For synthetic chemistry-related feature suggestions, please describe your reaction type and optimization needs in detail.
+
+---
+
+## 📧 Contact
+
+- **Author**: Zhenzhi Tan
+- **Email**: zhenzhi-tan@outlook.com
+
+---
+
+**Happy Synthesizing! 🧪⚗️**