# IdeaSearch Fitter Demo (/en/docs/fitter/demo)
## 🎬 Demo Video [#-demo-video]
# 🚀 IdeaSearch Fitter Demo Usage Tutorial [#-ideasearch-fitter-demo-usage-tutorial]
## 📖 Overview [#-overview]
IdeaSearch Fitter Demo is an intelligent symbolic regression web application based on the IdeaSearch framework, using large language models to automatically discover mathematical expressions. Users can simply draw curves or upload data, and AI will find the best-fit formulas for you.
### ✨ Key Features [#-key-features]
* 🎨 **Interactive Drawing Canvas** - Intuitively draw target curves with support for multiple drawing modes
* 📁 **File Upload Support** - Support NPZ data file upload and multi-dimensional feature fitting
* 🤖 **Multi-Model Support** - Integrated with mainstream LLMs like GPT, Gemini, Qwen, DeepSeek
* 🧠 **Fuzzy Mode** - Use natural language theory descriptions to assist fitting
* 📊 **Real-time Visualization** - Dynamically display fitting progress and result comparisons
* 🏝️ **Island Evolution Algorithm** - Parallel exploration of multiple solution spaces to improve fitting quality
* 📈 **Pareto Front Analysis** - Balance expression complexity and fitting accuracy
* ⚙️ **Physical Unit Validation** - Ensure generated expressions have correct dimensions
## 🛠️ Environment Setup [#️-environment-setup]
### 1. Clone the Repository [#1-clone-the-repository]
```bash
# Clone repository
git clone https://github.com/IdeaSearch/ideasearch-fit-demo
cd ideasearch-fit-demo
```
### 2. Install uv Package Manager [#2-install-uv-package-manager]
uv is a fast and reliable Python package manager, recommended for use:
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# Or install via pip
pip install uv
```
### 3. Configure Environment and Dependencies [#3-configure-environment-and-dependencies]
```bash
# Sync dependency environment
uv sync
```
### 4. Configure API Keys [#4-configure-api-keys]
Copy the example configuration file and edit:
```bash
# Copy example configuration
cp api_keys.json.example api_keys.json
# Edit configuration file
nano api_keys.json # or use other editors
```
API key configuration format:
```json
{
"Gemini_2.5_Flash": [{
"api_key": "your-gemini-api-key-here",
"base_url": "https://generativelanguage.googleapis.com/v1beta",
"model": "gemini-2.0-flash-exp"
}],
"GPT_4o_Mini": [{
"api_key": "your-openai-api-key",
"base_url": "https://api.openai.com/v1",
"model": "gpt-4o-mini"
}],
"Qwen_Plus": [{
"api_key": "your-qwen-api-key",
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"model": "qwen-plus"
}]
}
```
**Supported Model Names** (Please configure strictly according to the following names):
* **Gemini Series**: `Gemini_2.5_Flash`, `Gemini_2.5_Pro`, `Gemini_Pro`
* **OpenAI Series**: `GPT_4o`, `GPT_4o_Mini`, `GPT_4_Turbo`
* **Domestic Models**: `Qwen_Plus`, `Qwen_Max`, `Qwen3`, `Doubao`
* **Open Source Models**: `Deepseek_V3`, `Grok_4`
## 🚀 Launch Application [#-launch-application]
After configuration, start the application:
```bash
# Use launch script (recommended)
./run.sh
# Or start manually
uv run streamlit run app.py --server.port 8501
```
The application will automatically open in browser: `http://localhost:8501`
## 📖 Usage Guide [#-usage-guide]
The application provides two main tabs for different usage scenarios:
### 🎨 Tab 1: Draw Curve Fitting [#-tab-1-draw-curve-fitting]
This is the most intuitive way to use, suitable for quick exploration and teaching demonstrations.
#### Operation Steps [#operation-steps]
1. **Draw Curves**
* Draw target curves on the left canvas
* Supports three drawing modes:
* **Free Drawing**: Hand-draw curves of any shape
* **Straight Line**: Draw line segments
* **Points**: Mark data points one by one
* Adjustable line width (1-10 pixels)
* Can enable **📷 Pass Image** option to pass canvas images to vision-capable models (like Gemini)
2. **Configure Parameters** (Right sidebar)
* **Model Selection**: Recommend using `Gemini_2.5_Flash` (best balance of speed and quality)
* **Function Configuration**: Select available mathematical functions
```
Basic functions: sin, cos, tan, exp, log, sqrt, abs
Advanced functions: sinh, cosh, tanh, asin, acos, atan
```
* **Fitting Parameter Tuning**:
* **Number of Islands**: 3-8 (Recommended: 5) - Number of parallel search populations
* **Number of Cycles**: 3-10 (Recommended: 5) - Number of evolution generations
* **Unit Interactions**: 5-10 (Recommended: 8) - LLM calls per generation
* **Target Score**: 80.0 (Recommended) - Early stop when reached
* **Fuzzy Mode**: Check to enable natural language theory description assistance
3. **Data Preview**
* The right side displays extracted data point information
* Shows X, Y ranges and data point scatter plots
* Confirm data quality before starting fitting
4. **Execute Fitting**
* Click **▶️ Start Fitting** button
* Observe real-time progress and log output
* Can see during fitting process:
* Current best score and expression
* Real-time fitting curve comparison plots
* API call counts and runtime
#### Fitting Results Interpretation [#fitting-results-interpretation]
After fitting completion, the application displays:
* **📊 Fitting Comparison Plot**: Original curve vs AI-discovered fitting curve
* **📈 Score History**: Shows fitting quality improvement over iterations
* **📊 Pareto Front**: Analyzes trade-off between expression complexity and accuracy
* **📞 API Call Log**: Detailed model call records and performance statistics
### 📁 Tab 2: File Upload Fitting [#-tab-2-file-upload-fitting]
This is the preferred method for professional users, supporting complex multi-dimensional data and physical unit validation.
#### Data Preparation [#data-preparation]
Prepare NPZ files containing the following keys:
* `'x'`: Input features, shape `(n_samples, n_features)`
* `'y'`: Output targets, shape `(n_samples,)`
* `'error'`: Optional error data, shape `(n_samples,)`
Python example code:
```python
import numpy as np
# Generate example data: F = m * a (Newton's second law)
m = np.random.uniform(1, 10, 100) # mass kg
a = np.random.uniform(0.5, 20, 100) # acceleration m/s^2
F = m * a # force N
error = np.random.normal(0, 0.1, 100) # measurement error
# Save as NPZ file
x = np.column_stack([m, a]) # input feature matrix
y = F # output target
np.savez('physics_data.npz', x=x, y=y, error=error)
```
#### Operation Steps [#operation-steps-1]
1. **Upload Data File**
* Click **Choose NPZ File** to upload data
* System will automatically validate data format
* Display basic data information: number of samples, features, whether errors are included
2. **Variable Configuration** (Key step)
Set in **⚙️ Variable Configuration** area:
**Basic Description**:
* **Input Description**: Describe the physical meaning of input data
```
Example: "Use object's mass and acceleration to derive force acting on the object"
```
**Output Variables**:
* **Output Variable Name**: `F`
* **Output Variable Description**: `force`
* **Output Variable Unit**: `kg*m/s^2`
**Input Variable Configuration**:
Configure for each input feature:
* **Variable Name**: `m`, `a` (corresponding to mass, acceleration)
* **Unit**: `kg`, `m/s^2`
* **Description**: `mass`, `acceleration`
3. **Advanced Options**
* **Enable Unit Validation**: When checked, performs dimensional analysis to ensure generated expressions are physically correct
* Uncheck to skip unit checking, suitable for pure mathematical fitting
4. **Parameter Tuning**
* Sidebar parameters same as drawing mode
* For complex data, recommend:
* Number of Islands: 6-8
* Number of Cycles: 8-10
* Enable Fuzzy mode
5. **Execution and Results**
* Click **▶️ Start Fitting**
* For multi-dimensional data, results shown as **predicted vs actual** scatter plots
* Ideally, points should be distributed near the y=x line
## ⚙️ Configuration Parameter Details [#️-configuration-parameter-details]
### IdeaSearch Core Parameters [#ideasearch-core-parameters]
### Canvas Configuration Parameters [#canvas-configuration-parameters]
### Data Processing Parameters [#data-processing-parameters]
### Fitter Configuration Parameters [#fitter-configuration-parameters]
## 🎯 Parameter Tuning Guide [#-parameter-tuning-guide]
### Key Parameter Explanations [#key-parameter-explanations]
| Parameter | Recommended Value | Description | Tuning Suggestions |
| ---------------------- | ----------------- | ---------------------------------------- | ------------------------------------------------------------------ |
| **Number of Islands** | 3-8 | Number of parallel evolution populations | Increase improves diversity but consumes more API |
| **Number of Cycles** | 3-10 | Number of evolution generations | More cycles usually yield better results |
| **Unit Interactions** | 5-10 | LLM calls per cycle | Balance exploration depth and cost |
| **Target Score** | 80.0 | Automatic stop threshold | Adjust based on accuracy requirements (0-100) |
| **Sample Temperature** | 10-30 | Generation randomness control | High temperature increases creativity, low temperature more stable |
## 🔧 Troubleshooting [#-troubleshooting]
### Common Problem Solutions [#common-problem-solutions]
**Q: Application fails to start?**
```bash
# Check Python version (requires 3.10+)
python --version
# Reinstall dependencies
uv sync
```
**Q: API calls failing?**
1. Check if `api_keys.json` format is correct
2. Confirm API keys are valid and have balance
3. Verify network connection
4. Check if model names exactly match configuration file key names
**Q: Fitting results unsatisfactory?**
1. **Increase search intensity**: Raise number of islands and cycles
2. **Enable Fuzzy mode**: Use natural language theory descriptions
3. **Try different models**: GPT-4o usually performs better than Mini versions
4. **Optimize data quality**: Ensure canvas curves are clear and data is evenly distributed
5. **Adjust function library**: Choose appropriate basic functions based on expected function types
**Q: Memory or performance issues?**
1. Lower number of islands and cycles
2. Use more lightweight models
3. Reduce number of data points
4. Turn off some unnecessary visualizations
### Log Viewing [#log-viewing]
The application automatically saves detailed logs in the `logs/` directory:
```
logs/
├── fit_20231208_143022/ # Fitting process logs
├── db_20231208_143022/ # IdeaSearcher database files
└── ...
```
Each fitting creates an independent timestamped directory containing:
* Complete fitting process records
* API call details
* Error messages and debug output
* Best expressions and Pareto front data
## 📚 Technical Architecture [#-technical-architecture]
### Core Components [#core-components]
* **Streamlit**: Web application framework
* **IdeaSearch-framework**: Core optimization engine
* **IdeaSearch-fit**: Symbolic regression adapter
* **streamlit-drawable-canvas**: Drawing canvas component
### Data Flow [#data-flow]
```
User Input (Canvas/File) → Data Preprocessing → IdeaSearchFitter → IdeaSearcher → LLM Calls → Expression Generation → Evaluation and Selection → Result Display
```
### File Structure [#file-structure]
Main application entry, contains complete interface for both tabs
Interactive drawing canvas component, supports data extraction and processing
Sidebar configuration interface component, manages all parameter settings
Result visualization and log display component
FittingEngine fitting engine core logic
Default parameter configuration file
Detailed log directory for each fitting
IdeaSearcher database file directory
API key configuration file (needs manual creation)
API key configuration example file
uv project dependency configuration
Launch script
Project documentation
Project architecture documentation
## 🚀 Advanced Features [#-advanced-features]
### Fuzzy Mode [#fuzzy-mode]
Fuzzy mode is a unique feature of IdeaSearch that first lets LLM generate natural language theory descriptions, then converts them to mathematical expressions:
1. **Theory Generation**: LLM analyzes data characteristics and generates physical or mathematical theory hypotheses
2. **Expression Conversion**: Convert natural language theories to specific mathematical formulas
3. **Iterative Optimization**: Continue refining theories and expressions based on fitting results
Applicable scenarios:
* Physical law discovery
* Complex nonlinear relationship modeling
* Symbolic regression requiring interpretability
### Physical Unit Validation [#physical-unit-validation]
When unit validation is enabled, the system will:
1. **Dimensional Analysis**: Check dimensional consistency of expressions
2. **Unit Derivation**: Verify if output units match expectations
3. **Correction Suggestions**: Provide correction suggestions for expressions that don't conform to units
This ensures generated expressions are physically meaningful.
### Island Evolution Algorithm [#island-evolution-algorithm]
* **Parallel Search**: Multiple "islands" simultaneously evolve different expression populations
* **Population Exchange**: Islands periodically exchange excellent individuals
* **Diversity Maintenance**: Avoid premature convergence to local optima
### Pareto Front Optimization [#pareto-front-optimization]
Balances two objectives:
* **Fitting Accuracy**: Degree of expression matching with data
* **Expression Complexity**: Simplicity of formulas
Helps users find optimal balance between accuracy and interpretability.
## 📈 Performance Optimization Suggestions [#-performance-optimization-suggestions]
1. **Model Selection**: Gemini 2.5 Flash provides best cost-effectiveness
2. **Batch Processing**: Use larger unit interaction numbers to reduce network overhead
3. **Caching**: System automatically caches intermediate results
4. **Parallelization**: Island algorithm naturally supports parallel computing
5. **Early Stopping**: Set reasonable target scores to avoid overfitting
## 🤝 Contribution and Feedback [#-contribution-and-feedback]
Encountering problems or have improvement suggestions?
* 📋 Check [GitHub Issues](https://github.com/IdeaSearch/ideasearch-fit-demo/issues)
* 🆕 [Create New Issue](https://github.com/IdeaSearch/ideasearch-fit-demo/issues/new)
* 📧 Contact development team
***
**🎯 Start exploring AI-driven symbolic regression!**
*Let large language models drive research and promote scientific discovery*
# README (/en/docs/fitter/fitter)
# IdeaSearch-fit [#ideasearch-fit]
## Quick Start [#quick-start]
To install IdeaSearch-fit, run:
```bash
pip install IdeaSearch-fit
```
## Project Overview [#project-overview]
`IdeaSearch-fit` is a symbolic-regression application for the [`IdeaSearch`](https://github.com/IdeaSearch/IdeaSearch-framework) framework. It provides `IdeaSearchFitter`, a Helper object that configures formula generation, numerical parameter fitting, evaluation, and result reporting before being attached to an `IdeaSearcher` with `bind_helper()`.
## Scope [#scope]
Use this package to generate and compare candidate expressions for data `X` and targets `y`, including experiments on how semantic context or `IdeaSearch` search settings affect the result. The package reports numerical fit quality and expression complexity; it does not establish physical interpretation, causal validity, robustness, or extrapolation. Validate selected expressions with held-out data and domain-specific checks.
## Configuration Model [#configuration-model]
| Stage | Main configuration or interface | Result |
| -------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Data | `data`, `data_path`, `result_path` | Input arrays and output directory |
| Semantic context | `variable_names`, `output_name`, units, descriptions, `auto_polish` | Prompt context for candidate generation |
| Expression grammar | `functions`, `constant_whitelist`, `constant_map` | Allowed symbols in executable expressions |
| Generation mode | `generate_fuzzy`, `fuzzy_translator` | Direct expressions or hypothesis-to-expression translation |
| Numerical evaluation | `optimization_method`, `optimization_trial_num`, metric-mapping settings | Fitted parameters and candidate scores |
| Agent loop | `IdeaSearcher.bind_helper()`, model, memory, island, migration, and budget settings | Iterative candidate generation and evaluation |
| Result access | `get_best_fit()`, `get_pareto_frontier()` | Best numerical fit and accuracy–complexity trade-off |
To compare search configurations, keep the data, expression grammar, metric, numerical optimizer, model version, and random settings fixed unless they are the variables being tested.
## Processing Pipeline [#processing-pipeline]
`IdeaSearch-fit` evaluates a candidate in two stages:
1. **Candidate structure generation**: the LLM receives the configured data summary, variable metadata, optional domain descriptions, and expression grammar. It returns an expression directly, or a natural-language hypothesis followed by an expression when `generate_fuzzy=True`.
2. **Parameter fitting and scoring**: the expression is parsed, its free parameters are fitted with `L-BFGS-B` or `differential-evolution`, and the configured metric is mapped to an `IdeaSearch` score.
Only expressions that pass parsing and enabled validation checks enter the reported results.
## Core Input and Output [#core-input-and-output]
**Core Input:**
* **`X`**: Input data (independent variables, multi-dimensional support).
* **`y`**: Target data (dependent variable, one-dimensional).
* **`error`** (Optional): Measurement uncertainty for each value in `y`. When supplied, it is used by the uncertainty-weighted fit metric; otherwise the fitter uses mean squared error.
**Core Output:**
* A Pareto frontier containing the retained accuracy–complexity trade-off, together with access to the current best numerical fit.
## Key Features [#key-features]
* **Evolutionary Symbolic Regression**: Uses the multi-island evolution framework of `IdeaSearch` to explore candidate mathematical expressions.
* **Pareto Frontier**: Reports retained candidates across the configured accuracy–complexity trade-off.
* **Dimensional Consistency Checks**: Checks physical dimensions when unit validation is enabled. Dimensional consistency is a constraint, not proof of physical correctness.
* **Dual-Mode Formula Generation**:
* **Precise Generation**: Directly generates and evolves mathematical expressions that strictly adhere to a specific computational syntax.
* **Fuzzy Generation**: First, an LLM proposes a natural-language hypothesis about patterns in the data. Another LLM agent then translates the hypothesis into a strict mathematical expression.
* **Automated Semantic Polishing**: The system can invoke an LLM to propose descriptions of the inputs and outputs for the search prompt.
* **Seamless Integration and Automation**: As a highly integrated module for `IdeaSearch`, the `IdeaSearchFitter` class only needs to be initialized once. It then automatically configures all the necessary core components for `IdeaSearch`, including the evaluation function (`evaluate_func`), prompts (`prologue_section`, `epilogue_section`), and mutation/crossover operators (`mutation_func`, `crossover_func`).
## Core API [#core-api]
The primary interface for the `IdeaSearch-fit` package is the `IdeaSearchFitter` class, which consists of its constructor and several result-retrieval methods.
* `IdeaSearchFitter(__init__)`: ⭐️ **Important**
* **Function**: Initializes an `IdeaSearchFitter` instance. This is the unified entry point for all configurations, including data loading, problem definition, expression construction, and search strategy settings.
* **Importance**: The first step in using `IdeaSearch-fit`, defining the entire framework for the symbolic regression task.
* `get_best_fit()`:
* **Function**: Returns the numerical expression string, fitted with its optimal parameters, that achieved the lowest metric value (e.g., mean squared error) among all evaluated formulas.
* **Importance**: Retrieves the single best fitting result based on accuracy alone.
* `get_pareto_frontier()`:
* **Function**: Returns a dictionary containing all formulas on the current Pareto frontier, along with their detailed information (complexity, metric value, fitted parameters, etc.).
* **Importance**: Retrieves a set of optimal solutions that balance accuracy and complexity.
## Configuration Parameters [#configuration-parameters]
All configurations for an `IdeaSearchFitter` instance are set in its `__init__` constructor. The parameters are logically grouped by function to facilitate understanding and setup.
### 1. Task Input & Output [#1-task-input--output]
* **`data`**: `Optional[Dict[str, ndarray]]`
* Data passed directly as a dictionary in memory. Must contain keys `"x"` (input, 2D array) and `"y"` (output, 1D array). Can optionally include `"error"` (errors for y, 1D array).
* **`data_path`**: `Optional[str]`
* Path to a local `.npz` file from which to load data. Use either `data` or `data_path`. The file should contain arrays with the same keys.
* **`result_path`**: `str`
* Path to an **existing directory** where fitting results, such as the Pareto frontier report (`pareto_report.txt`) and data (`pareto_data.json`), will be stored.
### 2. Problem Definition & Units [#2-problem-definition--units]
* **`variable_names`**: `Optional[List[str]]`
* A list of names for the input variables (e.g., `["mass", "velocity"]`). Defaults to `["x1", "x2", ...]` if not provided.
* **`output_name`**: `Optional[str]`
* The name of the output variable (e.g., `"energy"`).
* **`perform_unit_validation`**: `bool` (Default: `False`)
* Whether to enable dimensional consistency checks.
* **`variable_units`**: `Optional[List[str]]`
* A list of units corresponding to `variable_names` (e.g., `["kg", "m s^-1"]`). Required when `perform_unit_validation` is `True`.
* **`output_unit`**: `Optional[str]`
* The unit of the output variable (e.g., `"J"` or `"kg m^2 s^-2"`). Required when `perform_unit_validation` is `True`.
* **`auto_polish`**: `bool` (Default: `True`)
* Whether to invoke an LLM to propose variable and output descriptions for the search prompt.
* **`auto_polisher`**: `Optional[str]`
* The name of the LLM model to use for the `auto_polish` task. If `None`, an available model is selected automatically.
* **`input_description`**, **`variable_descriptions`**, **`output_description`**: `Optional[str]`
* Manually specify text descriptions for the system, input variables, and output variable. If provided, the `auto_polish` step will be skipped.
### 3. Expression Building Blocks [#3-expression-building-blocks]
* **`functions`**: `List[str]` (Default: Includes common functions like `sin`, `cos`, `log`, `exp`)
* A list of mathematical functions allowed in expressions. All functions must be supported by the `numexpr` library.
* **`constant_whitelist`**: `List[str]` (Default: `[]`)
* A list of named constants (as strings) allowed in expressions.
* **`constant_map`**: `Dict[str, float]` (Default: `{"pi": np.pi}`)
* A dictionary mapping named constants to their float values.
### 4. Search & Evolution Strategy [#4-search--evolution-strategy]
* **LLM Generation Strategy**
* **`generate_fuzzy`**: `bool` (Default: `True`)
* **\[Master Switch]** Enables "fuzzy generation" mode. If `False`, the LLM will generate strict mathematical expressions directly.
* **`fuzzy_translator`**: `Optional[str]`
* In fuzzy mode, the name of the LLM model used to translate natural language theories into mathematical expressions.
* **Numerical Optimization Strategy**
* **`optimization_method`**: `Literal["L-BFGS-B", "differential-evolution"]` (Default: `"L-BFGS-B"`)
* Specifies the numerical optimization algorithm for fitting ansatz parameters. `L-BFGS-B` is an efficient local optimizer suitable for smoother objective functions. `differential-evolution` is a global optimizer that may be more robust for complex problems with multiple local minima.
* **`optimization_trial_num`**: `int` (Default: `100`)
* The number of trials for the numerical optimizer. For `differential-evolution`, this corresponds to the population size. For non-convex or complex problems, increasing this value can improve the probability of finding the global optimum at the cost of increased computation time.
* **Evolutionary Operators (Still work in progress)**
* **`enable_mutation`**: `bool` (Default: `False`)
* Enables the built-in expression **mutation** functionality.
* **`enable_crossover`**: `bool` (Default: `False`)
* Enables the built-in expression **crossover** functionality.
### 5. Score Mapping [#5-score-mapping]
* **`baseline_metric_value`**: `Optional[float]`
* Defines a "baseline" metric value (e.g., MSE) that will be mapped to an `IdeaSearch` score of `20.0`. If `None`, the result of a naive linear fit is used as the baseline.
* **`good_metric_value`**: `Optional[float]`
* Defines a "good" metric value that will be mapped to an `IdeaSearch` score of `80.0`.
* **`metric_mapping`**: `Literal["linear", "logarithm"]` (Default: `"linear"`)
* The mapping function from metric value to score. Logarithmic mapping is more suitable when metric values can span several orders of magnitude.
### 6. Miscellaneous [#6-miscellaneous]
* **`seed`**: `Optional[int]`
* Seed for the fitter's local random-number generator. Repeating a complete run also requires fixed model versions, API settings, and `IdeaSearch` configuration.
## Workflow [#workflow]
The following is a complete workflow example (from [https://github.com/IdeaSearch/IdeaSearch-fit-test](https://github.com/IdeaSearch/IdeaSearch-fit-test)) that demonstrates how to solve a symbolic regression problem using `IdeaSearch-fit` and `IdeaSearch`.
```python
# pip install IdeaSearch-fit
import numpy as np
from IdeaSearch import IdeaSearcher
from IdeaSearch_fit import IdeaSearchFitter
def build_data():
"""
Builds simulated data for fitting.
True Formula: x = 1.2*A + A*exp(-0.7*gamma*t) - A*exp(-0.5*gamma*t)*cos(3*omega*t)
"""
n_samples = 1000
rng = np.random.default_rng(seed=42)
# Define the value ranges for the independent variables
A_range = (1.0, 10.0)
gamma_range = (0.1, 1.0)
omega_range = (1.0, 5.0)
t_range = (0.0, 10.0)
# Sample randomly within the defined ranges
A_samples = rng.uniform(A_range[0], A_range[1], n_samples)
gamma_samples = rng.uniform(gamma_range[0], gamma_range[1], n_samples)
omega_samples = rng.uniform(omega_range[0], omega_range[1], n_samples)
t_samples = rng.uniform(t_range[0], t_range[1], n_samples)
# Stack the independent variables into the format required by the Fitter (n_samples, n_features)
x_data = np.stack([A_samples, gamma_samples, omega_samples, t_samples], axis=1)
# Calculate the y values based on the true formula and add noise
y_true = (1.2 * A_samples +
A_samples * np.exp(-0.7 * gamma_samples * t_samples) -
A_samples * np.exp(-0.5 * gamma_samples * t_samples) * np.cos(3 * omega_samples * t_samples))
error_data = 0.01 + 0.02 * np.abs(y_true)
y_data = y_true + rng.normal(0, error_data)
# Note: This example does not pass error_data to the Fitter, so MSE will be used as the metric.
return {
"x": x_data,
"y": y_data,
}
def main():
# 1. Prepare the data
data = build_data()
# 2. Initialize IdeaSearchFitter
fitter = IdeaSearchFitter(
result_path = "fit_results", # Ensure this directory exists
data = data,
variable_names = ["A", "gamma", "omega", "t"],
variable_units = ["m", "s^-1", "s^-1", "s"],
output_name = "x",
output_unit = "m",
constant_whitelist = ["1", "2", "pi"],
constant_map = {"1": 1, "2": 2, "pi": np.pi},
auto_polish = True,
generate_fuzzy = True,
perform_unit_validation = True,
optimization_method = "L-BFGS-B",
optimization_trial_num = 5,
)
# 3. Initialize IdeaSearcher
ideasearcher = IdeaSearcher()
# 4. Basic Configuration
ideasearcher.set_program_name("IdeaSearch Fitter Test")
ideasearcher.set_database_path("database") # Ensure this directory exists
ideasearcher.set_api_keys_path("api_keys.json")
ideasearcher.set_models(["gemini-2.5-pro"]) # Use your desired model
ideasearcher.set_record_prompt_in_diary(True) # Optional: Record prompts in the diary log
# 5. Bind the Fitter! (The most crucial step)
ideasearcher.bind_helper(fitter)
# 6. Define and execute the evolutionary loop
island_num = 3
cycle_num = 3
unit_interaction_num = 20
for _ in range(island_num):
ideasearcher.add_island()
for cycle in range(cycle_num):
print(f"---[ Cycle {cycle + 1}/{cycle_num} ]---")
if cycle != 0: ideasearcher.repopulate_islands()
ideasearcher.run(unit_interaction_num)
print("Done.")
# 7. Retrieve and display the results
print("\n---[ Search Complete ]---")
print(f"Best Fit Formula: {fitter.get_best_fit()}")
print("\nOptimal Solutions on the Pareto Frontier:")
pareto_frontier = fitter.get_pareto_frontier()
if not pareto_frontier:
print(" - No solutions found on the Pareto frontier.")
else:
for complexity, info in sorted(pareto_frontier.items()):
metric_key = "reduced chi squared" if "reduced chi squared" in info else "mean square error"
metric_value = info.get(metric_key, float('nan'))
print(f" - Complexity: {complexity}, Error: {metric_value:.4g}, Formula: {info.get('ansatz', 'N/A')}")
if __name__ == "__main__":
# Before running, please ensure:
# 1. The './fit_results' and './database' directories exist.
# 2. The 'api_keys.json' file is correctly configured.
main()
```
# Overview (/en/docs/fitter)
{getPageTreePeers(source.pageTree, '/en/docs/fitter').map((peer) => (
{peer.description}
))}
# README (/en/docs/framework/framework)
# IdeaSearch [#ideasearch]
## Project Overview [#project-overview]
`IdeaSearch` is an open-source Python framework for constructing iterative LLM-agent workflows with user-defined evaluation, persistent candidate memory, and multi-island search. An **Idea** is a text candidate stored in a `.idea` file; it may represent a hypothesis, program, plan, formula, or any other object accepted by the evaluator.
## Quick Start [#quick-start]
```bash
pip install IdeaSearch
```
The complete setup and execution example is provided in [Workflow Overview](#workflow-overview).
## Scope [#scope]
Use `IdeaSearch` when the generation–evaluation loop itself must be configured, recorded, or compared. For a one-off prompt or a task already handled by a general-purpose agent, a direct model or agent call is usually simpler. The framework produces evaluated candidates; it does not independently validate scientific claims.
## Experimental Model [#experimental-model]
The table below maps experimental concepts to the public `IdeaSearcher` interface.
| Concept | Main interface | Function |
| -------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Task and measurement | `set_evaluate_func()`, `set_score_range()`, `set_assess_func()` | Score candidates and optionally assess the database |
| Initial condition | `add_initial_ideas()`, `set_prologue_section()`, `set_epilogue_section()`, `set_models()` | Define starting candidates, task context, and generation models |
| Memory | `set_examples_num()`, `set_include_info_in_prompt()` | Select historical Ideas and feedback for later prompts |
| Exploration | `set_sample_temperature()`, `set_model_temperatures()`, mutation and crossover setters | Control candidate sampling and variation |
| Parallel topology | `add_island()`, `set_samplers_num()`, `set_evaluators_num()`, `repopulate_islands()` | Configure parallel search and migration |
| Interaction budget | `run(additional_interaction_num)` | Add a specified number of generations to every island |
| Persistence | `set_database_path()`, `set_backup_on()`, `set_record_prompt_in_diary()` | Store Ideas, scores, backups, logs, and optional prompt records |
| Result access | `get_best_idea()`, `get_best_score()` | Return the current highest-scoring candidate and score |
Change one or more controls while holding the others fixed to compare agent behavior across runs. Record model versions and stochastic settings separately when external model APIs are used. [IdeaSearch-fit](/en/docs/fitter) provides a symbolic-regression application of this interface.
## Key Features [#key-features]
* **Multi-Island Parallel Search**: Runs separate Idea populations with configurable Sampler and Evaluator counts and explicit inter-island migration.
* **Model Integration**: Loads one or more configured LLM or VLM endpoints and manages concurrent requests through `ModelManager`.
* **Candidate Variation**: Provides sampling, user-defined mutation, and user-defined crossover controls.
* **Evaluation and Assessment**: Uses a user-defined `evaluate_func` for candidates and an optional `assess_func` for database-level measurements.
* **Persistence**: Stores candidate files, scores, logs, visualizations, and optional backups below the configured database path.
* **Extensibility**: Supports custom prompt generation, filters, postprocessors, evaluators, and Helper objects.
## Core API [#core-api]
The following methods in the `IdeaSearcher` class constitute the primary user interface:
### Core Workflow Methods [#core-workflow-methods]
* `__init__()`: ⭐️ **Important**
* **Function**: Initializes an `IdeaSearcher` instance. Sets all default parameters and initializes internal states such as locks, the model manager, and the island dictionary.
* **Importance**: The class constructor, serving as the entry point for all search configurations.
* `run(additional_interaction_num: int)`: ⭐️ **Important**
* **Function**: Starts the Idea search process. This method initializes and runs the samplers for all islands, allowing each island to evolve for `additional_interaction_num` generations (rounds).
* **Importance**: The core method that initiates the entire Idea Search cycle.
### Island and Population Management [#island-and-population-management]
* `add_island()`: ⭐️ **Important**
* **Function**: Adds a new island to the system and returns its `island_id`. The first time an island is added, it performs necessary initialization and cleanup (e.g., clearing logs, old Idea directories, and backups).
* **Importance**: Defines the parallelism of the search and creates independent search units.
* `delete_island(island_id: int)`:
* **Function**: Deletes the island with the specified `island_id` from the system.
* **Importance**: Allows for dynamic management of search resources and strategies.
* `repopulate_islands()`: ⭐️ **Important**
* **Function**: Redistributes Ideas among islands. This method sorts all islands by their "best score" and then copies the best Ideas from the top-half islands to the bottom-half islands, promoting idea sharing and preventing stagnation in local optima.
* **Importance**: A key operation in evolutionary algorithms for global optimization.
### Result Retrieval [#result-retrieval]
* `get_best_score()`: ⭐️ **Important**
* **Function**: Returns the highest Idea score across all islands.
* **Importance**: Retrieves the quality metric of the best Idea found so far.
* `get_best_idea()`: ⭐️ **Important**
* **Function**: Returns the content of the highest-scoring Idea across all islands.
* **Importance**: Retrieves the content of the best Idea found so far.
### Convenience Configuration Methods [#convenience-configuration-methods]
* `add_initial_ideas(ideas: List[str])`:
* **Function**: Programmatically adds a list of initial ideas, serving as an alternative to placing `.idea` files in the `database/ideas/initial_ideas/` directory. This allows users to provide seed ideas without direct file system manipulation.
* **Importance**: Simplifies the setup of the initial population.
* `bind_helper(helper: object)`: ⭐️ **Important**
* **Function**: Binds a "helper" object and uses its attributes to quickly configure multiple core parameters of the `IdeaSearcher`. This is a convenient end-to-end setup method, especially useful for building interface tools on top of the `IdeaSearch` framework (e.g., [IdeaSearch-Fitter](https://github.com/IdeaSearch/IdeaSearch-fit)).
* **Helper Object Attributes**:
* **Required**: `prologue_section` (str), `epilogue_section` (str), `evaluate_func` (Callable)
* **Optional**: `initial_ideas` (List\[str]), `system_prompt` (str), `assess_func` (Callable), `mutation_func` (Callable), `crossover_func` (Callable), `filter_func` (Callable), `postprocess_func` (Callable), etc.
* **Importance**: Greatly simplifies parameter configuration and provides a standard interface for extending the framework.
## Configuration Parameters [#configuration-parameters]
`IdeaSearcher` provides a rich set of `set_` methods to configure its behavior. These parameters are logically grouped by functionality to facilitate understanding and management.
### Project and File System [#project-and-file-system]
* **`program_name`**: `str`
* The name of the project, used for identification in logs and outputs.
* **`database_path`**: `str`
* The root path for the database. **Prerequisite**: Unless using `add_initial_ideas()`, this path must contain an `ideas/initial_ideas/` subdirectory with initial `.idea` files. The system will automatically create subdirectories for island-specific ideas (`ideas/island*/`), data (`data/`), visualizations (`pic/`), and logs (`log/`). **This is the only location on the file system that IdeaSearch will modify**.
* **`diary_path`**: `Optional[str]` (Default: `None`)
* The path to the log file. If `None`, defaults to `{database_path}/log/diary.txt`.
* **`backup_path`**: `Optional[str]` (Default: `None`)
* The path for storing backups. If `None`, defaults to `{database_path}/ideas/backup/`.
* Other path-related parameters (e.g., `model_assess_result_data_path`, `assess_result_pic_path`) follow a similar pattern, using default locations under `database_path` if set to `None`.
### Initialization [#initialization]
* **`load_idea_skip_evaluation`**: `bool` (Default: `True`)
* If `True`, the system will attempt to load scores from a `score_sheet.json` file in the initial ideas directory, skipping re-evaluation.
* **`initialization_cleanse_threshold`**: `float` (Default: `-1.0`)
* The minimum score an idea must achieve to survive the initial screening phase. Ideas below this threshold will be removed.
* **`delete_when_initial_cleanse`**: `bool` (Default: `False`)
* If `True`, ideas scoring below `initialization_cleanse_threshold` during the initial screening are permanently deleted.
### Sampling [#sampling]
* **`samplers_num`**: `int` (Default: `3`)
* The number of parallel Sampler threads to run for each island.
* **`sample_temperature`**: `float` (Default: `50.0`)
* The softmax temperature used to control randomness when sampling historical ideas as examples for the prompt. Higher values increase randomness.
* **`generation_bonus`**: `float` (Default: `0.0`)
* A score bonus added to ideas from more recent generations during sampling, encouraging the exploration of newer evolutionary paths.
### Prompt Engineering [#prompt-engineering]
* **`system_prompt`**: `Optional[str]` (Default: `None`)
* A system-level instruction for the LLM that sets the overall context and persona.
* **`explicit_prompt_structure`**: `bool` (Default: `True`)
* If `True`, automatically includes structural headers (e.g., "Examples:") in the prompt for better organization.
* **`prologue_section`**: `str`
* A user-defined string that appears at the beginning of every prompt, typically for instructions or context.
* **`epilogue_section`**: `str`
* A user-defined string that appears at the end of every prompt, often for formatting instructions or final commands.
* **`filter_func`**: `Optional[Callable[[str], str]]` (Default: `None`)
* A custom function to preprocess idea content before it is sampled and included in a prompt.
* **`examples_num`**: `int` (Default: `3`)
* The number of historical ideas to include as examples in the prompt for each generation round.
* **`include_info_in_prompt`**: `bool` (Default: `True`)
* If `True`, the supplementary `info` string returned by `evaluate_func` will be included alongside the idea's content and score in the prompt.
* **`images`**: `List[Any]` (Default: `[]`)
* A list of images to be passed to a Vision Language Model (VLM). Use placeholders in `prologue_section` or `epilogue_section` to position them; URLs, local file paths, and raw bytes are automatically resolved.
* **`image_placeholder`**: `str` (Default: `""`)
* The placeholder string used in prompt sections to indicate where an image from the `images` list should be inserted.
* **`generate_prompt_func`**: `Optional[Callable[[List[str], List[float], List[Optional[str]]], str]]` (Default: `None`)
* A custom function that provides complete control over prompt generation, overriding the default structure (prologue, examples, epilogue). **Note**: This is an experimental feature and may be unstable.
### Model Configuration [#model-configuration]
* **`api_keys_path`**: `str`
* The file path to the JSON configuration file containing API keys and model endpoint information.
* **`models`**: `List[str]`
* A list of model aliases (e.g., `'GPT4_o'`, `'Deepseek_V3'`) to be used for idea generation. These aliases must be a subset of the keys in the `api_keys_path` file.
* **`model_temperatures`**: `List[float]`
* A list of sampling temperatures for the LLMs. The length and order of this list must match the `models` list.
* **`model_sample_temperature`**: `float` (Default: `50.0`)
* The softmax temperature for selecting which model to use for the next generation. Higher values increase randomness in model selection.
* **`top_p`**: `Optional[float]` (Default: `None`)
* The nucleus sampling parameter `top_p`, corresponding to the standard API parameter.
* **`max_completion_tokens`**: `Optional[int]` (Default: `None`)
* The maximum number of tokens to generate in a completion, corresponding to the standard API parameter.
**API Keys File Format (`api_keys.json`):**
This file should be a JSON object where each top-level key is a unique model alias used in `set_models()`. The value for each alias is a list of dictionaries, where each dictionary represents an instance of that model. This allows you to configure multiple instances (e.g., with different API keys or base URLs) for the same logical model, and the system will manage them automatically.
```json
{
"Deepseek-V3": [
{
"api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"base_url": "https://api.deepseek.com/v1",
"model": "deepseek-chat"
}
],
"Gemini-2.5-Pro": [
{
"api_key": "AIzaSyXXXX-XXXXXXXXXXXXXXXXXXXXXXXX",
"base_url": "https://generativelanguage.googleapis.com/v1beta/",
"model": "gemini-1.5-flash"
}
]
}
```
### Generation and Post-processing [#generation-and-post-processing]
* **`generate_num`**: `int` (Default: `1`)
* The number of new ideas each Sampler thread will attempt to generate in a single round.
* **`postprocess_func`**: `Optional[Callable[[str], str]]` (Default: `None`)
* A custom function to clean or format the raw text generated by the LLM before it is saved as an idea file.
* **`hand_over_threshold`**: `float` (Default: `0.0`)
* The minimum score a newly generated idea must achieve from the Evaluator to be accepted into an island's population.
### Evaluator [#evaluator]
* **`evaluators_num`**: `int` (Default: `3`)
* The number of parallel Evaluator threads to run for each island.
* **`evaluate_func`**: `Callable[[str], Tuple[float, Optional[str]]]`
* The core evaluation function. It takes an idea's content (string) and must return a tuple `(score: float, info: Optional[str])`.
* **`score_range`**: `Tuple[float, float]` (Default: `(0.0, 100.0)`)
* A tuple `(min_score, max_score)` defining the expected output range of `evaluate_func`, used for normalization and visualization.
### Database Assessment [#database-assessment]
* **`assess_func`**: `Optional[Callable[[List[str], List[float], List[Optional[str]]], float]]` (Default: `default_assess_func`)
* A custom function to assess the overall state of the entire idea database, providing a holistic quality metric.
* **`assess_interval`**: `Optional[int]` (Default: `1`)
* The frequency (in rounds) at which the `assess_func` is called to evaluate the entire database.
* **`assess_baseline`**: `Optional[float]` (Default: `60.0`)
* A baseline score value to be drawn as a horizontal line on the database assessment graph for easy performance comparison.
### Model Assessment [#model-assessment]
* **`model_assess_window_size`**: `int` (Default: `20`)
* The number of recent ideas generated by a model to consider when calculating its moving average performance score.
* **`model_assess_initial_score`**: `float` (Default: `100.0`)
* The initial score assigned to each model. A high value encourages initial exploration of all available models.
* **`model_assess_average_order`**: `float` (Default: `1.0`)
* The order $p$ for the p-norm (generalized mean) used to calculate the moving average of model scores. $p=1$ is the arithmetic mean; higher values give more weight to high scores.
* **`model_assess_save_result`**: `bool` (Default: `True`)
* If `True`, saves the model assessment data and visualization to their specified paths.
### Mutation [#mutation]
* **`mutation_func`**: `Optional[Callable[[str], str]]` (Default: `None`)
* A custom function that takes an idea's content and returns a slightly modified version.
* **`mutation_interval`**: `Optional[int]` (Default: `None`)
* The frequency (in rounds) at which the mutation operation is performed on an island's population.
* **`mutation_num`**: `Optional[int]` (Default: `None`)
* The number of new ideas to be generated via mutation each time the operation is triggered.
* **`mutation_temperature`**: `Optional[float]` (Default: `None`)
* The softmax temperature for selecting parent ideas for mutation. Higher values increase the chance of lower-scoring ideas being mutated.
### Crossover [#crossover]
* **`crossover_func`**: `Optional[Callable[[str, str], str]]` (Default: `None`)
* A custom function that takes two ideas' content and returns a new idea combining elements of both.
* **`crossover_interval`**: `Optional[int]` (Default: `None`)
* The frequency (in rounds) at which the crossover operation is performed.
* **`crossover_num`**: `Optional[int]` (Default: `None`)
* The number of new ideas to be generated via crossover each time the operation is triggered.
* **`crossover_temperature`**: `Optional[float]` (Default: `None`)
* The softmax temperature for selecting parent ideas for crossover. Higher values increase randomness in parent selection.
### Similarity (Infrequently Used) [#similarity-infrequently-used]
* **`similarity_threshold`**: `float` (Default: `-1.0`)
* The distance threshold below which two ideas are considered similar. A value of `-1.0` disables similarity checks except for exact duplicates.
* Other related parameters like `similarity_distance_func` are available for more complex similarity control.
### Miscellaneous [#miscellaneous]
* **`idea_uid_length`**: `int` (Default: `6`)
* The character length of the Unique Identifier (UID) used in `.idea` filenames.
* **`record_prompt_in_diary`**: `bool` (Default: `False`)
* If `True`, the full prompt sent to the LLM in each generation round will be recorded in the log file.
* **`backup_on`**: `bool` (Default: `True`)
* If `True`, enables automatic backup of the `ideas` directory at the start of the `run` method.
* **`shutdown_score`**: `float` (Default: `float('inf')`)
* If the best score across all islands reaches this value, the IdeaSearch process will terminate gracefully.
## Workflow Overview [#workflow-overview]
A typical `IdeaSearch` workflow demonstrates how to structure your code for a complete evolutionary loop, including the creation of multiple islands, periodic population migration, and continuous idea generation. The following example, inspired by the [IdeaSearch-test repository](https://github.com/IdeaSearch/IdeaSearch-test), represents a common practical pattern.
```python
# pip install IdeaSearch
from IdeaSearch import IdeaSearcher
from user_code.prompt import prologue_section, epilogue_section
from user_code.evaluation import evaluate
from user_code.initial_ideas import initial_ideas
def main():
# 1. Initialization
ideasearcher = IdeaSearcher()
# 2. Basic Configuration
ideasearcher.set_language("en") # Set language (default: 'zh_CN'; available: 'zh_CN', 'en')
ideasearcher.set_api_keys_path("api_keys.json")
ideasearcher.set_program_name("TemplateProgram")
ideasearcher.set_database_path("database")
# 3. Core Logic Configuration (Evaluation Function)
ideasearcher.set_evaluate_func(evaluate)
# 4. Prompt Engineering Configuration
ideasearcher.set_prologue_section(prologue_section)
ideasearcher.set_epilogue_section(epilogue_section)
# 5. Model Configuration
ideasearcher.set_models([
"Deepseek_V3",
])
ideasearcher.set_model_temperatures([
0.6,
])
# 6. (Optional) Other Configurations
ideasearcher.set_record_prompt_in_diary(True)
# 7. Add Initial Ideas (avoids manual file system operations)
ideasearcher.add_initial_ideas(initial_ideas)
# 8. Define and Execute the Evolutionary Loop
island_num = 2 # Number of islands
cycle_num = 3 # Number of migration cycles
unit_interaction_num = 10 # Number of evolution rounds per cycle
# Create initial islands
for _ in range(island_num):
ideasearcher.add_island()
# Run the evolution
for cycle in range(cycle_num):
print(f"---[ Cycle {cycle + 1}/{cycle_num} ]---")
# Before each cycle (except the first), perform inter-island migration
if cycle != 0:
print("Repopulating islands...")
ideasearcher.repopulate_islands()
# Run evolution for the specified number of rounds within the current cycle
ideasearcher.run(unit_interaction_num)
# 9. Retrieve and Utilize the Final Result
print("\n---[ Search Complete ]---")
best_idea_content = ideasearcher.get_best_idea()
print("Best Idea Content:")
print(best_idea_content)
if __name__ == "__main__":
main()
```
## Internationalization [#internationalization]
`IdeaSearch` supports the internationalization of its interface text.
You can set the system language using the `set_language(value: str)` method.
For example, `ideasearcher.set_language('en')` will switch the interface and log text to English, while `ideasearcher.set_language('zh_CN')` will switch to Simplified Chinese.
The default language of `IdeaSearch` is Simplified Chinese (`zh_CN`).
# IdeaSearch Documentation (/en/docs/framework)
# IdeaSearch Documentation [#ideasearch-documentation]
IdeaSearch is an open-source Python framework for constructing iterative LLM-agent workflows with user-defined evaluation, persistent candidate memory, and multi-island search. It is intended for tasks where the generation–evaluation loop itself must be configured, recorded, or compared.
The framework produces evaluated candidates. Domain interpretation and validation remain separate steps and should use task-appropriate evidence, held-out data, or independent checks.
## Project Components [#project-components]
* **IdeaSearch Framework**: Configures candidate generation, evaluation, memory, parallel islands, migration, budgets, and run artifacts.
* **IdeaSearch-fit**: Applies the framework to symbolic regression by combining candidate-expression generation with numerical parameter fitting.
## Start Here [#start-here]
Configure and run an iterative IdeaSearch workflow.
Open Manual
Configure data, expression grammar, numerical fitting, and result access.
Open Manual
Follow a complete symbolic-regression example.
Open Demo
Browse framework source code, releases, and issue tracking.
View on GitHub
Browse fitter source code, releases, and issue tracking.
View on GitHub
## Framework Controls [#framework-controls]
* **Task and measurement**: User-defined candidate evaluation and optional database-level assessment.
* **Initial conditions and memory**: Starting candidates, prompts, historical examples, and evaluator feedback.
* **Exploration and topology**: Model sampling, mutation, crossover, parallel islands, and migration.
* **Budget and records**: Explicit interaction budgets, candidate databases, scores, logs, and backups.
* **Result access**: Retrieval of the current highest-scoring candidate and its evaluator score.
## Documentation Pages [#documentation-pages]
{getPageTreePeers(source.pageTree, "/en/docs/framework").map((peer) => (
{peer.description}
))}
# IdeaSearch Fitter 演示示例 (/cn/docs/fitter/demo)
## 🎬 演示视频 [#-演示视频]
# 🚀 IdeaSearch Fitter Demo 使用教程 [#-ideasearch-fitter-demo-使用教程]
## 📖 概述 [#-概述]
IdeaSearch Fitter Demo 是一个基于 IdeaSearch 框架的智能符号回归 Web 应用，使用大语言模型自动发现数学表达式。用户只需绘制曲线或上传数据，AI 即可为您找到最佳拟合公式。
### ✨ 主要特性 [#-主要特性]
* 🎨 **交互式绘图画布** - 直观绘制目标曲线，支持多种绘制模式
* 📁 **文件上传支持** - 支持 NPZ 数据文件上传和多维特征拟合
* 🤖 **多模型支持** - 集成 GPT、Gemini、Qwen、DeepSeek 等主流 LLM
* 🧠 **Fuzzy 模式** - 使用自然语言理论描述辅助拟合
* 📊 **实时可视化** - 动态展示拟合进度和结果对比
* 🏝️ **岛屿进化算法** - 并行探索多个解空间，提高拟合质量
* 📈 **Pareto 前沿分析** - 平衡表达式复杂度与拟合精度
* ⚙️ **物理单位验证** - 确保生成的表达式量纲正确
## 🛠️ 环境准备 [#️-环境准备]
### 1. 克隆代码仓库 [#1-克隆代码仓库]
```bash
# 克隆仓库
git clone https://github.com/IdeaSearch/ideasearch-fit-demo
cd ideasearch-fit-demo
```
### 2. 安装 uv 包管理器 [#2-安装-uv-包管理器]
uv 是一个快速且可靠的 Python 包管理器，推荐使用：
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 或使用 pip 安装
pip install uv
```
### 3. 配置环境和依赖 [#3-配置环境和依赖]
```bash
# 同步依赖环境
uv sync
```
### 4. 配置 API 密钥 [#4-配置-api-密钥]
复制示例配置文件并编辑：
```bash
# 复制示例配置
cp api_keys.json.example api_keys.json
# 编辑配置文件
nano api_keys.json # 或使用其他编辑器
```
API 密钥配置格式：
```json
{
"Gemini_2.5_Flash": [{
"api_key": "your-gemini-api-key-here",
"base_url": "https://generativelanguage.googleapis.com/v1beta",
"model": "gemini-2.0-flash-exp"
}],
"GPT_4o_Mini": [{
"api_key": "your-openai-api-key",
"base_url": "https://api.openai.com/v1",
"model": "gpt-4o-mini"
}],
"Qwen_Plus": [{
"api_key": "your-qwen-api-key",
"base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
"model": "qwen-plus"
}]
}
```
**支持的模型名称**（请严格按照以下名称配置）：
* **Gemini 系列**: `Gemini_2.5_Flash`, `Gemini_2.5_Pro`, `Gemini_Pro`
* **OpenAI 系列**: `GPT_4o`, `GPT_4o_Mini`, `GPT_4_Turbo`
* **国产模型**: `Qwen_Plus`, `Qwen_Max`, `Qwen3`, `Doubao`
* **开源模型**: `Deepseek_V3`, `Grok_4`
## 🚀 启动应用 [#-启动应用]
配置完成后，启动应用：
```bash
# 使用启动脚本（推荐）
./run.sh
# 或手动启动
uv run streamlit run app.py --server.port 8501
```
应用将自动在浏览器中打开：`http://localhost:8501`
## 📖 使用指南 [#-使用指南]
应用提供两个主要标签页，对应不同的使用场景：
### 🎨 标签页1：绘制曲线拟合 [#-标签页1绘制曲线拟合]
这是最直观的使用方式，适合快速探索和教学演示。
#### 操作步骤 [#操作步骤]
1. **绘制曲线**
* 在左侧画布上绘制目标曲线
* 支持三种绘制模式：
* **自由绘制**: 手绘任意形状的曲线
* **直线**: 绘制直线段
* **点**: 逐点标记数据点
* 可调整线条宽度（1-10像素）
* 可开启**📷 传递图片**选项，将画布图像传递给支持视觉的模型（如 Gemini）
2. **配置参数**（右侧边栏）
* **模型选择**: 推荐使用 `Gemini_2.5_Flash`（速度与质量平衡最佳）
* **函数配置**: 选择可用的数学函数
```
基础函数: sin, cos, tan, exp, log, sqrt, abs
高级函数: sinh, cosh, tanh, asin, acos, atan
```
* **拟合参数调优**:
* **岛屿数量**: 3-8（推荐：5）- 并行搜索种群数
* **循环次数**: 3-10（推荐：5）- 进化代数
* **单元交互数**: 5-10（推荐：8）- 每代的 LLM 调用次数
* **目标分数**: 80.0（推荐）- 达到后提前停止
* **Fuzzy 模式**: 勾选启用自然语言理论描述辅助
3. **数据预览**
* 右侧会显示提取的数据点信息
* 显示 X、Y 范围和数据点散布图
* 确认数据质量后再开始拟合
4. **执行拟合**
* 点击 **▶️ 开始拟合** 按钮
* 观察实时进度和日志输出
* 可在拟合过程中看到：
* 当前最佳分数和表达式
* 实时拟合曲线对比图
* API调用次数和运行时间
#### 拟合结果解析 [#拟合结果解析]
拟合完成后，应用会显示：
* **📊 拟合对比图**: 原始曲线 vs AI发现的拟合曲线
* **📈 分数历史**: 显示拟合质量随迭代的改进过程
* **📊 Pareto 前沿**: 分析表达式复杂度与精度的权衡
* **📞 API 调用日志**: 详细的模型调用记录和性能统计
### 📁 标签页2：上传文件拟合 [#-标签页2上传文件拟合]
这是专业用户的首选方式，支持复杂多维数据和物理单位验证。
#### 数据准备 [#数据准备]
准备包含以下键的 NPZ 文件：
* `'x'`: 输入特征，形状为 `(n_samples, n_features)`
* `'y'`: 输出目标，形状为 `(n_samples,)`
* `'error'`: 可选的误差数据，形状为 `(n_samples,)`
Python 示例代码：
```python
import numpy as np
# 生成示例数据：F = m * a (牛顿第二定律)
m = np.random.uniform(1, 10, 100) # 质量 kg
a = np.random.uniform(0.5, 20, 100) # 加速度 m/s^2
F = m * a # 力 N
error = np.random.normal(0, 0.1, 100) # 测量误差
# 保存为 NPZ 文件
x = np.column_stack([m, a]) # 输入特征矩阵
y = F # 输出目标
np.savez('physics_data.npz', x=x, y=y, error=error)
```
#### 操作步骤 [#操作步骤-1]
1. **上传数据文件**
* 点击 **选择 NPZ 文件** 上传数据
* 系统会自动验证数据格式
* 显示数据基本信息：样本数、特征数、是否包含误差
2. **变量配置**（关键步骤）
在 **⚙️ 变量配置** 区域设置：
**基本描述**:
* **输入描述**: 描述输入数据的物理意义
```
示例: "使用物体的质量和加速度来推导作用在物体上的力"
```
**输出变量**:
* **输出变量名称**: `F`
* **输出变量描述**: `力`
* **输出变量单位**: `kg*m/s^2`
**输入变量配置**:
针对每个输入特征配置：
* **变量名**: `m`, `a` (对应质量、加速度)
* **单位**: `kg`, `m/s^2`
* **描述**: `质量`, `加速度`
3. **高级选项**
* **启用单位验证**: 勾选后进行量纲分析，确保生成的表达式在物理上正确
* 未勾选则跳过单位检查，适合纯数学拟合
4. **参数调优**
* 侧边栏参数与绘制模式相同
* 针对复杂数据，建议：
* 岛屿数量：6-8
* 循环次数：8-10
* 启用 Fuzzy 模式
5. **执行和结果**
* 点击 **▶️ 开始拟合**
* 对于多维数据，结果显示为**预测vs实际**散点图
* 理想情况下点应分布在 y=x 直线附近
## ⚙️ 配置参数详解 [#️-配置参数详解]
### IdeaSearch 核心参数 [#ideasearch-核心参数]
### 画布配置参数 [#画布配置参数]
### 数据处理参数 [#数据处理参数]
### Fitter 配置参数 [#fitter-配置参数]
## 🎯 参数调优指南 [#-参数调优指南]
### 关键参数说明 [#关键参数说明]
| 参数 | 推荐值 | 说明 | 调优建议 |
| --------- | ----- | ------------- | ----------------- |
| **岛屿数量** | 3-8 | 并行进化种群数 | 增加提高多样性，但消耗更多 API |
| **循环次数** | 3-10 | 进化代数 | 更多循环通常得到更好结果 |
| **单元交互数** | 5-10 | 每循环的 LLM 调用次数 | 平衡探索深度与成本 |
| **目标分数** | 80.0 | 自动停止阈值 | 根据精度要求调整（0-100） |
| **采样温度** | 10-30 | 生成随机性控制 | 高温度增加创造性，低温度更稳定 |
## 🔧 故障排查 [#-故障排查]
### 常见问题解决 [#常见问题解决]
**Q: 应用启动失败？**
```bash
# 检查Python版本（需要3.10+）
python --version
# 重新安装依赖
uv sync
```
**Q: API调用失败？**
1. 检查 `api_keys.json` 格式是否正确
2. 确认 API 密钥有效且有余额
3. 验证网络连接
4. 检查模型名称是否与配置文件键名完全匹配
**Q: 拟合结果不理想？**
1. **增加搜索强度**: 提高岛屿数量和循环次数
2. **启用 Fuzzy 模式**: 使用自然语言理论描述
3. **尝试不同模型**: GPT-4o 通常比 Mini 版本效果更好
4. **优化数据质量**: 确保画布曲线清晰、数据分布均匀
5. **调整函数库**: 根据预期函数类型选择合适的基础函数
**Q: 内存或性能问题？**
1. 降低岛屿数量和循环次数
2. 使用更轻量级的模型
3. 减少数据点数量
4. 关闭一些不必要的可视化
### 日志查看 [#日志查看]
应用会在 `logs/` 目录下自动保存详细日志：
```
logs/
├── fit_20231208_143022/ # 拟合过程日志
├── db_20231208_143022/ # IdeaSearcher 数据库文件
└── ...
```
每次拟合都会创建带时间戳的独立目录，包含：
* 完整的拟合过程记录
* API 调用详情
* 错误信息和调试输出
* 最佳表达式和 Pareto 前沿数据
## 📚 技术架构 [#-技术架构]
### 核心组件 [#核心组件]
* **Streamlit**: Web 应用框架
* **IdeaSearch-framework**: 核心优化引擎
* **IdeaSearch-fit**: 符号回归适配器
* **streamlit-drawable-canvas**: 绘图画布组件
### 数据流 [#数据流]
```
用户输入(画布/文件) → 数据预处理 → IdeaSearchFitter → IdeaSearcher → LLM调用 → 表达式生成 → 评估筛选 → 结果展示
```
### 文件结构 [#文件结构]
主应用入口，包含两个标签页的完整界面
交互式绘图画布组件，支持数据提取和处理
侧边栏配置界面组件，管理所有参数设置
结果可视化和日志展示组件
FittingEngine 拟合引擎核心逻辑
默认参数配置文件
每次拟合的详细日志目录
IdeaSearcher 数据库文件目录
API 密钥配置文件（需手动创建）
API 密钥配置示例文件
uv 项目依赖配置
启动脚本
项目说明文档
项目架构文档
## 🚀 高级特性 [#-高级特性]
### Fuzzy 模式 [#fuzzy-模式]
Fuzzy 模式是 IdeaSearch 的独特功能，它首先让 LLM 生成自然语言的理论描述，然后将其转换为数学表达式：
1. **理论生成**: LLM 分析数据特征，生成物理或数学理论假设
2. **表达式转换**: 将自然语言理论转换为具体的数学公式
3. **迭代优化**: 基于拟合结果继续完善理论和表达式
适用场景：
* 物理定律发现
* 复杂非线性关系建模
* 需要可解释性的符号回归
### 物理单位验证 [#物理单位验证]
启用单位验证后，系统会：
1. **量纲分析**: 检查表达式的量纲一致性
2. **单位推导**: 验证输出单位是否与预期一致
3. **建议修正**: 对不符合单位的表达式提供修正建议
这确保了生成的表达式在物理上是有意义的。
### 岛屿进化算法 [#岛屿进化算法]
* **并行搜索**: 多个"岛屿"同时进化不同的表达式族群
* **种群交换**: 岛屿间定期交换优秀个体
* **多样性保持**: 避免过早收敛到局部最优解
### Pareto 前沿优化 [#pareto-前沿优化]
平衡两个目标：
* **拟合精度**: 表达式与数据的匹配程度
* **表达式复杂度**: 公式的简洁性
帮助用户在精度和可解释性之间找到最佳平衡点。
## 📈 性能优化建议 [#-性能优化建议]
1. **模型选择**: Gemini 2.5 Flash 提供最佳性价比
2. **批处理**: 使用较大的单元交互数减少网络开销
3. **缓存**: 系统自动缓存中间结果
4. **并行**: 岛屿算法天然支持并行计算
5. **早停**: 设置合理的目标分数避免过度拟合
## 🤝 贡献与反馈 [#-贡献与反馈]
遇到问题或有改进建议？
* 📋 查看 [GitHub Issues](https://github.com/IdeaSearch/ideasearch-fit-demo/issues)
* 🆕 [创建新 Issue](https://github.com/IdeaSearch/ideasearch-fit-demo/issues/new)
* 📧 联系开发团队
***
**🎯 开始探索 AI 驱动的符号回归吧！**
*让大语言模型驱动研究，促进科学发现*
# 使用文档 (/cn/docs/fitter/fitter)
# IdeaSearch-fit [#ideasearch-fit]
## 快速开始 [#快速开始]
运行以下指令以安装 IdeaSearch-fit：
```bash
pip install IdeaSearch-fit
```
## 项目概述 [#项目概述]
`IdeaSearch-fit` 是 [`IdeaSearch`](https://github.com/IdeaSearch/IdeaSearch-framework) 框架的符号回归应用。它提供 Helper 对象 `IdeaSearchFitter`，用于配置公式生成、数值参数拟合、评价和结果报告，再通过 `bind_helper()` 绑定到 `IdeaSearcher`。
## 适用范围 [#适用范围]
使用本软件可以针对数据 `X` 和目标 `y` 生成并比较候选表达式，也可以研究语义背景或 `IdeaSearch` 搜索设置如何影响结果。软件报告数值拟合质量和表达式复杂度，但不建立物理解释、因果有效性、稳健性或外推能力。应使用留出数据和领域检验验证选定表达式。
## 配置模型 [#配置模型]
| 阶段 | 主要配置或接口 | 结果 |
| ----- | ----------------------------------------------------- | ---------------- |
| 数据 | `data`、`data_path`、`result_path` | 输入数组与输出目录 |
| 语义背景 | `variable_names`、`output_name`、单位、描述、`auto_polish` | 候选生成使用的提示词背景 |
| 表达式语法 | `functions`、`constant_whitelist`、`constant_map` | 可执行表达式允许使用的符号 |
| 生成模式 | `generate_fuzzy`、`fuzzy_translator` | 直接表达式或“假说—表达式”翻译 |
| 数值评价 | `optimization_method`、`optimization_trial_num`、度量映射设置 | 拟合参数与候选分数 |
| 智能体循环 | `IdeaSearcher.bind_helper()`、模型、记忆、岛屿、迁徙和预算设置 | 迭代式候选生成与评价 |
| 结果访问 | `get_best_fit()`、`get_pareto_frontier()` | 最佳数值拟合与精度—复杂度权衡 |
比较不同搜索配置时，除非某项设置正是待研究变量，否则应固定数据、表达式语法、度量、数值优化器、模型版本和随机设置。
## 处理流程 [#处理流程]
`IdeaSearch-fit` 分两个阶段评价候选：
1. **候选结构生成**：大语言模型接收已配置的数据摘要、变量元数据、可选领域描述和表达式语法。模型直接返回表达式；当 `generate_fuzzy=True` 时，则先返回自然语言假说，再生成表达式。
2. **参数拟合与评分**：系统解析表达式，使用 `L-BFGS-B` 或 `differential-evolution` 拟合自由参数，并将配置的度量映射为 `IdeaSearch` 分数。
只有通过解析和已启用校验的表达式才会进入报告结果。
## 核心输入与输出 [#核心输入与输出]
> **核心输入:**
>
> * **`X`**: 输入数据（自变量，支持多维）。
> * **`y`**: 目标数据（因变量，一维）。
> * **`error`** (可选): `y` 中每个数据点的测量不确定度。提供时用于带不确定度权重的拟合度量；未提供时使用均方误差。
>
> **核心输出:**
>
> * 一个**帕累托前沿 (Pareto Frontier)**，记录保留的精度—复杂度权衡；同时可以访问当前最佳数值拟合。
## 关键特性 [#关键特性]
* **进化式符号回归**：依托 `IdeaSearch` 的多岛屿进化框架探索候选数学表达式。
* **帕累托前沿**：报告配置的精度—复杂度权衡下保留的候选表达式。
* **量纲一致性检查**：启用量纲验证时检查表达式的物理量纲。量纲一致性是一项约束，不能单独证明物理正确性。
* **双模态公式生成**:
* **精确生成 (Precise Generation)**: 直接生成和进化严格遵循特定计算语法的数学表达式。
* **模糊生成 (Fuzzy Generation)**：首先由大语言模型提出关于数据模式的自然语言假说，再由另一个 LLM 智能体将假说翻译为严格的数学表达式。
* **自动语义补全**：系统可以调用 LLM 为搜索提示词提议输入、输出和变量描述。
* **高度集成与自动化**: 作为 `IdeaSearch` 的一个高度集成的模块，用户只需初始化 `IdeaSearchFitter` 类，它就能自动配置好 `IdeaSearch` 所需的评估函数 (`evaluate_func`)、提示词 (`prologue_section`, `epilogue_section`)、变异/交叉算子 (`mutation_func`, `crossover_func`) 等全部核心组件。
## 核心 API [#核心-api]
`IdeaSearch-fit` 包的主要交互接口是 `IdeaSearchFitter` 类，它由构造函数和几个结果获取方法组成。
* `IdeaSearchFitter(__init__)`: ⭐️ **重要**
* **功能**: 初始化一个 `IdeaSearchFitter` 实例。这是所有配置的统一入口，涵盖了数据加载、问题定义、表达式构建、搜索策略设定等所有环节。
* **重要性**: 使用 `IdeaSearch-fit` 的第一步，决定了整个符号回归任务的框架。
* `get_best_fit()`:
* **功能**: 从所有已评估的公式中，返回经最优参数拟合后的数值表达式字符串。该表达式在所有公式中达到了最低的度量值（如均方误差）。
* **重要性**: 获取单一维度的最佳拟合结果。
* `get_pareto_frontier()`:
* **功能**: 返回一个字典，包含了构成当前帕累托前沿的所有公式及其详细信息（复杂度、度量值、拟合参数等）。
* **重要性**: 获取一系列在精度和复杂度之间取得最优权衡的拟合结果。
## 配置参数详解 [#配置参数详解]
`IdeaSearchFitter` 实例的所有配置都在其 `__init__` 构造函数中完成。参数已按逻辑功能划分，以便于理解和配置。
### 1. 任务输入与输出 [#1-任务输入与输出]
* **`data`**: `Optional[Dict[str, ndarray]]`
* 以字典形式直接传入内存中的数据。必需包含键 `"x"` (输入, 2D array) 和 `"y"` (输出, 1D array)，可选包含 `"error"` (y 的误差, 1D array)。
* **`data_path`**: `Optional[str]`
* 从本地 `.npz` 文件加载数据，与 `data` 参数二选一。文件内应包含与 `data` 参数相同的键。
* **`result_path`**: `str`
* 一个**已存在的文件夹路径**，用于存储拟合过程的产出，如帕累托前沿报告 (`pareto_report.txt`) 和数据 (`pareto_data.json`)。
### 2. 问题定义与量纲 [#2-问题定义与量纲]
* **`variable_names`**: `Optional[List[str]]`
* 输入变量的名称列表 (如 `["mass", "velocity"]`)。若不提供，则默认为 `["x1", "x2", ...]`.
* **`output_name`**: `Optional[str]`
* 输出变量的名称 (如 `"energy"`)。
* **`perform_unit_validation`**: `bool` (默认: `False`)
* 是否启用量纲一致性检查。
* **`variable_units`**: `Optional[List[str]]`
* 与 `variable_names` 对应的单位列表 (如 `["kg", "m s^-1"]`)。当 `perform_unit_validation` 为 `True` 时必需。
* **`output_unit`**: `Optional[str]`
* 输出变量的单位 (如 `"J"` 或 `"kg m^2 s^-2"`)。当 `perform_unit_validation` 为 `True` 时必需。
* **`auto_polish`**: `bool` (默认: `True`)
* 是否调用 LLM 为搜索提示词提议变量和输出描述。
* **`auto_polisher`**: `Optional[str]`
* 用于执行 `auto_polish` 任务的 LLM 模型名称。若为 `None`，将自动选择可用模型。
* **`input_description`**, **`variable_descriptions`**, **`output_description`**: `Optional[str]`
* 手动指定对整个系统、输入变量、输出变量的文字描述。如果提供了这些信息，`auto_polish` 步骤将被跳过。
### 3. 表达式构建模块 [#3-表达式构建模块]
* **`functions`**: `List[str]` (默认: 包含 `sin`, `cos`, `log`, `exp` 等常用函数)
* 允许在表达式中使用的数学函数列表。所有函数必须受 `numexpr` 库支持。
* **`constant_whitelist`**: `List[str]` (默认: `[]`)
* 允许在表达式中使用的常数名称列表（字符串形式）。
* **`constant_map`**: `Dict[str, float]` (默认: `{"pi": np.pi}`)
* 将常数名称映射到其浮点数值的字典。
### 4. 搜索与进化策略 [#4-搜索与进化策略]
* **LLM 生成策略**
* **`generate_fuzzy`**: `bool` (默认: `True`)
* **\[核心开关]** 是否启用“模糊生成”模式。若为 `False`，LLM 将直接生成严格的数学表达式。
* **`fuzzy_translator`**: `Optional[str]`
* 在“模糊生成”模式下，用于将自然语言理论翻译成数学表达式的 LLM 模型名称。
* **数值优化策略**
* **`optimization_method`**: `Literal["L-BFGS-B", "differential-evolution"]` (默认: `"L-BFGS-B"`)
* 指定用于求解拟设参数的数值优化算法。`L-BFGS-B` 是一种高效的局部优化算法，适用于较为平滑的目标函数。`differential-evolution` 是一种全局优化算法，对于存在多个局部最优解的复杂问题可能更具鲁棒性。
* **`optimization_trial_num`**: `int` (默认: `100`)
* 每次拟合时，数值优化器的尝试次数。对于 `differential-evolution`，这对应于种群大小。对于非凸或复杂问题，增加此值可以提高找到全局最优解的概率，但会增加计算时间。
* **进化算子（开发中）**
* **`enable_mutation`**: `bool` (默认: `False`)
* 是否启用内置的表达式**变异**功能。
* **`enable_crossover`**: `bool` (默认: `False`)
* 是否启用内置的表达式**交叉**功能。
### 5. 评分映射 [#5-评分映射]
* **`baseline_metric_value`**: `Optional[float]`
* 定义一个“基准”度量值（如 MSE），该值将被映射为 `IdeaSearch` 的分数 `20.0`。若为 `None`，将使用朴素线性拟合的结果作为基准。
* **`good_metric_value`**: `Optional[float]`
* 定义一个“良好”度量值，该值将被映射为 `IdeaSearch` 的分数 `80.0`。
* **`metric_mapping`**: `Literal["linear", "logarithm"]` (默认: `"linear"`)
* 度量值到分数的映射方式。对数 (`logarithm`) 映射更适用于度量值数量级变化剧烈的情况。
### 6. 杂项 [#6-杂项]
* **`seed`**: `Optional[int]`
* 拟合器本地随机数生成器的种子。重复完整运行还需要固定模型版本、API 设置和 `IdeaSearch` 配置。
## 工作流程 [#工作流程]
以下是一个完整的工作流程示例（[https://github.com/IdeaSearch/IdeaSearch-fit-test](https://github.com/IdeaSearch/IdeaSearch-fit-test)），展示了如何使用 `IdeaSearch-fit` 和 `IdeaSearch` 解决一个符号回归问题。
```python
# pip install IdeaSearch-fit
import numpy as np
from IdeaSearch import IdeaSearcher
from IdeaSearch_fit import IdeaSearchFitter
def build_data():
"""
构建用于拟合的模拟数据。
真实公式: x = 1.2*A + A*exp(-0.7*gamma*t) - A*exp(-0.5*gamma*t)*cos(3*omega*t)
"""
n_samples = 1000
rng = np.random.default_rng(seed=42)
# 定义自变量的取值范围
A_range = (1.0, 10.0)
gamma_range = (0.1, 1.0)
omega_range = (1.0, 5.0)
t_range = (0.0, 10.0)
# 在范围内随机采样
A_samples = rng.uniform(A_range[0], A_range[1], n_samples)
gamma_samples = rng.uniform(gamma_range[0], gamma_range[1], n_samples)
omega_samples = rng.uniform(omega_range[0], omega_range[1], n_samples)
t_samples = rng.uniform(t_range[0], t_range[1], n_samples)
# 将自变量组合成 Fitter 需要的格式 (n_samples, n_features)
x_data = np.stack([A_samples, gamma_samples, omega_samples, t_samples], axis=1)
# 根据真实公式计算 y 值，并加入噪声
y_true = (1.2 * A_samples +
A_samples * np.exp(-0.7 * gamma_samples * t_samples) -
A_samples * np.exp(-0.5 * gamma_samples * t_samples) * np.cos(3 * omega_samples * t_samples))
error_data = 0.01 + 0.02 * np.abs(y_true)
y_data = y_true + rng.normal(0, error_data)
# 注意：本示例未将 error_data 传给 Fitter，因此将使用 MSE 作为度量
return {
"x": x_data,
"y": y_data,
}
def main():
# 1. 准备数据
data = build_data()
# 2. 初始化 IdeaSearchFitter
fitter = IdeaSearchFitter(
result_path = "fit_results", # 确保此文件夹已创建
data = data,
variable_names = ["A", "gamma", "omega", "t"],
variable_units = ["m", "s^-1", "s^-1", "s"],
output_name = "x",
output_unit = "m",
constant_whitelist = ["1", "2", "pi"],
constant_map = {"1": 1, "2": 2, "pi": np.pi},
auto_polish = True,
generate_fuzzy = True,
perform_unit_validation = True,
optimization_method = "L-BFGS-B",
optimization_trial_num = 5,
)
# 3. 初始化 IdeaSearcher
ideasearcher = IdeaSearcher()
# 4. 基础配置
ideasearcher.set_program_name("IdeaSearch Fitter Test")
ideasearcher.set_database_path("database") # 确保此文件夹已创建
ideasearcher.set_api_keys_path("api_keys.json")
ideasearcher.set_models(["gemini-2.5-pro"]) # 使用您期望的模型
ideasearcher.set_record_prompt_in_diary(True) # 可选配置：在日志中记录提示词
# 5. 绑定 Fitter！ (最关键的一步)
ideasearcher.bind_helper(fitter)
# 6. 定义并执行进化循环
island_num = 3
cycle_num = 3
unit_interaction_num = 20
for _ in range(island_num):
ideasearcher.add_island()
for cycle in range(cycle_num):
print(f"---[ 周期 {cycle + 1}/{cycle_num} ]---")
if cycle != 0: ideasearcher.repopulate_islands()
ideasearcher.run(unit_interaction_num)
print("完成。")
# 7. 获取并展示结果
print("\n---[ 搜索完成 ]---")
print(f"最佳拟合公式: {fitter.get_best_fit()}")
print("\n帕累托前沿上的最优解集:")
pareto_frontier = fitter.get_pareto_frontier()
if not pareto_frontier:
print(" - 未在帕累托前沿上找到解。")
else:
for complexity, info in sorted(pareto_frontier.items()):
metric_key = "reduced chi squared" if "reduced chi squared" in info else "mean square error"
metric_value = info.get(metric_key, float('nan'))
print(f" - 复杂度: {complexity}, 误差: {metric_value:.4g}, 公式: {info.get('ansatz', 'N/A')}")
if __name__ == "__main__":
# 在运行前，请确保已创建 `./fit_results` 和 `./database` 文件夹
# 并已正确配置 `api_keys.json` 文件
main()
```
# 概览 (/cn/docs/fitter)
{getPageTreePeers(source.pageTree, '/cn/docs/fitter').map((peer) => (
{peer.description}
))}
# 使用文档 (/cn/docs/framework/framework)
# IdeaSearch [#ideasearch]
## 项目概述 [#项目概述]
`IdeaSearch` 是一个开源 Python 框架，用于构建包含用户自定义评价、持久候选记忆和多岛屿搜索的迭代式大模型智能体工作流。一个**思路 (Idea)** 是保存在 `.idea` 文件中的文本候选；它可以表示假说、程序、方案、公式，或评价器能够接收的其他对象。
## 快速开始 [#快速开始]
```bash
pip install IdeaSearch
```
完整的配置和运行示例见[工作流程概览](#工作流程概览)。
## 适用范围 [#适用范围]
当生成—评价循环本身需要配置、记录或比较时，使用 `IdeaSearch`。对于一次性提示，或通用智能体已经能够直接完成的任务，直接调用模型或智能体通常更简单。框架产生经过评价的候选，但不独立验证科学论断。
## 实验模型 [#实验模型]
下表将实验概念对应到 `IdeaSearcher` 的公开接口。
| 概念 | 主要接口 | 功能 |
| ----- | -------------------------------------------------------------------------------------- | --------------------- |
| 任务与测量 | `set_evaluate_func()`、`set_score_range()`、`set_assess_func()` | 为候选评分，并可选评估整个数据库 |
| 初始条件 | `add_initial_ideas()`、`set_prologue_section()`、`set_epilogue_section()`、`set_models()` | 定义起始候选、任务上下文和生成模型 |
| 记忆 | `set_examples_num()`、`set_include_info_in_prompt()` | 为后续提示词选择历史思路与反馈 |
| 探索 | `set_sample_temperature()`、`set_model_temperatures()`、变异与交叉设置方法 | 控制候选采样与变化 |
| 并行拓扑 | `add_island()`、`set_samplers_num()`、`set_evaluators_num()`、`repopulate_islands()` | 配置并行搜索与迁徙 |
| 交互预算 | `run(additional_interaction_num)` | 为每个岛屿增加指定轮数 |
| 持久化 | `set_database_path()`、`set_backup_on()`、`set_record_prompt_in_diary()` | 保存思路、分数、备份、日志和可选提示词记录 |
| 结果访问 | `get_best_idea()`、`get_best_score()` | 返回当前最高分候选及其分数 |
比较不同运行时，应只改变待研究的控制量，并固定其他设置。使用外部模型 API 时，还应另行记录模型版本和随机采样条件。[IdeaSearch-fit](/cn/docs/fitter) 提供了该接口的符号回归应用。
## 关键特性 [#关键特性]
* **多岛屿并行搜索**：运行相互分离的思路种群，分别配置采样器和评价器数量，并显式执行岛屿间迁徙。
* **模型集成**：加载一个或多个已配置的 LLM 或 VLM 端点，并通过 `ModelManager` 管理并发请求。
* **候选变化**：提供采样、用户自定义变异和用户自定义交叉控制。
* **评价与评估**：通过用户定义的 `evaluate_func` 评价候选，并可通过 `assess_func` 进行数据库级测量。
* **持久化**：在配置的数据库路径下保存候选文件、分数、日志、可视化和可选备份。
* **可扩展性**：支持自定义提示生成、过滤器、后处理器、评价器和 Helper 对象。
## 核心 API [#核心-api]
`IdeaSearcher` 类中的以下方法构成了用户交互的主要接口：
### 核心流程方法 [#核心流程方法]
* `__init__()`: ⭐️ **重要**
* **功能**: 初始化一个 `IdeaSearcher` 实例。设置所有默认参数并初始化内部状态，如锁、模型管理器和岛屿字典。
* **重要性**: 类的构造函数，是所有搜索参数设置的起点。
* `run(additional_interaction_num: int)`: ⭐️ **重要**
* **功能**: 启动思路搜索过程。该方法会初始化并运行所有岛屿的采样器，让每个岛屿进化 `additional_interaction_num` 个世代（轮次）。
* **重要性**: 启动整个思路搜索周期的核心方法。
### 岛屿与种群管理 [#岛屿与种群管理]
* `add_island()`: ⭐️ **重要**
* **功能**: 向系统中添加一个新岛屿，并返回其 `island_id`。首次添加岛屿时，会执行必要的初始化清理工作（例如，清理日志、旧的思路目录和备份）。
* **重要性**: 定义搜索的并行度，并创建独立的搜索单元。
* `delete_island(island_id: int)`:
* **功能**: 从系统中删除指定 `island_id` 的岛屿。
* **重要性**: 允许动态管理搜索资源和策略。
* `repopulate_islands()`: ⭐️ **重要**
* **功能**: 在岛屿之间重新分配思路。此方法按“最佳分数”对所有岛屿进行排序，然后将排名前半部分岛屿的最佳思路复制到后半部分的岛屿中，促进思路共享并防止陷入局部最优。
* **重要性**: 进化算法中用于全局优化的关键操作。
### 结果获取 [#结果获取]
* `get_best_score()`: ⭐️ **重要**
* **功能**: 返回所有岛屿中最高的思路分数。
* **重要性**: 获取迄今为止找到的最佳思路的质量度量。
* `get_best_idea()`: ⭐️ **重要**
* **功能**: 返回所有岛屿中分数最高的思路内容。
* **重要性**: 获取迄今为止找到的最佳思路的内容。
### 便捷配置方法 [#便捷配置方法]
* `add_initial_ideas(ideas: List[str])`:
* **功能**: 以编程方式添加初始思路列表，作为 `database/ideas/initial_ideas/` 目录下存放 `.idea` 文件的替代方案。这使得用户无需直接操作文件系统即可提供种子思路。
* **重要性**: 简化了初始种群的设置流程。
* `bind_helper(helper: object)`: ⭐️ **重要**
* **功能**: 绑定一个 "helper" 对象，并使用其属性来快速配置 `IdeaSearcher` 的多个核心参数。这是一个便捷的端到端设置方法，尤其适用于构建基于 `IdeaSearch` 框架的接口工具（例如 [IdeaSearch-Fitter](https://github.com/IdeaSearch/IdeaSearch-fit)）。
* **Helper 对象属性**:
* **必需**: `prologue_section` (str), `epilogue_section` (str), `evaluate_func` (Callable)
* **可选**: `initial_ideas` (List\[str]), `system_prompt` (str), `assess_func` (Callable), `mutation_func` (Callable), `crossover_func` (Callable), `filter_func` (Callable), `postprocess_func` (Callable) 等。
* **重要性**: 极大地简化了参数配置，并为框架的二次开发提供了标准接口。
## 配置参数详解 [#配置参数详解]
`IdeaSearcher` 提供了丰富的 `set_` 方法来配置其行为。这些参数逻辑上可划为多个类别，以便于理解与管理。
### 项目与文件系统 (Project and File System) [#项目与文件系统-project-and-file-system]
* **`program_name`**: `str`
* 项目的名称，用于日志和输出中的识别。
* **`database_path`**: `str`
* 数据库的根路径。**前置条件**: 除非使用 `add_initial_ideas()`，否则必须包含 `ideas/initial_ideas/` 子目录并在其中存放初始的 `.idea` 文件。系统将在此路径下自动创建岛屿专属的思路目录 (`ideas/island*/`)、数据目录 (`data/`)、可视化图表目录 (`pic/`) 和日志目录 (`log/`)。**这是 IdeaSearch 将会修改的唯一文件系统位置**。
* **`diary_path`**: `Optional[str]` (默认: `None`)
* 日志文件的路径。如果为 `None`，则默认为 `{database_path}/log/diary.txt`。
* **`backup_path`**: `Optional[str]` (默认: `None`)
* 备份存储路径。如果为 `None`，则默认为 `{database_path}/ideas/backup/`。
* 其他路径参数（如 `model_assess_result_data_path`, `assess_result_pic_path` 等）也遵循类似的模式，若为 `None` 则使用 `database_path` 下的默认位置。
### 初始化 (Initialization) [#初始化-initialization]
* **`load_idea_skip_evaluation`**: `bool` (默认: `True`)
* 如果为 `True`，系统会尝试从初始思路所在目录的 `score_sheet.json` 文件中加载分数，从而跳过对这些思路的重新评估。
* **`initialization_cleanse_threshold`**: `float` (默认: `-1.0`)
* 一个思路在初始净化阶段必须达到的最低分数。低于此阈值的思路将被删除。
* **`delete_when_initial_cleanse`**: `bool` (默认: `False`)
* 如果为 `True`，在初始净化阶段分数低于 `initialization_cleanse_threshold` 的思路将被永久删除。
### 采样 (Sampling) [#采样-sampling]
* **`samplers_num`**: `int` (默认: `3`)
* 每个岛屿并行运行的采样器 (Sampler) 线程数量。
* **`sample_temperature`**: `float` (默认: `50.0`)
* 用于采样历史思路作为提示词上下文的 softmax 温度。值越高，随机性越大。
* **`generation_bonus`**: `float` (默认: `0.0`)
* 在采样过程中，为较新代际的思路添加的分数奖励。这鼓励系统探索更新的进化路径。
### 提示词工程 (Prompt Engineering) [#提示词工程-prompt-engineering]
* **`system_prompt`**: `Optional[str]` (默认: `None`)
* 发送给大语言模型的系统级指令，用于设定整体上下文和角色。
* **`explicit_prompt_structure`**: `bool` (默认: `True`)
* 如果为 `True`，将在提示词中自动包含结构化标题（如 "Examples:"），以获得更好的组织性。
* **`prologue_section`**: `str`
* 用户定义的字符串，出现在每个提示词的开头，通常用于提供指令或背景。
* **`epilogue_section`**: `str`
* 用户定义的字符串，出现在每个提示词的末尾，常用于格式化指令或最终命令。
* **`filter_func`**: `Optional[Callable[[str], str]]` (默认: `None`)
* 一个自定义函数，用于在思路内容被采样并包含到提示词中之前对其进行预处理。
* **`examples_num`**: `int` (默认: `3`)
* 在每一轮生成中，作为示例包含在提示词中的历史思路数量。
* **`include_info_in_prompt`**: `bool` (默认: `True`)
* 如果为 `True`，将在提示词中包含由 `evaluate_func` 返回的补充 `info` 字符串，与思路内容和分数一起展示。
* **`images`**: `List[Any]` (默认: `[]`)
* 要传递给视觉语言模型 (VLM) 的图像列表。在 `prologue_section` 或 `epilogue_section` 中使用占位符来定位它们；可自动解析 url、图片文件路径和裸字节。
* **`image_placeholder`**: `str` (默认: `""`)
* 在提示词部分用于指示应插入 `images` 列表中图像的占位符字符串。
* **`generate_prompt_func`**: `Optional[Callable[[List[str], List[float], List[Optional[str]]], str]]` (默认: `None`)
* 一个自定义函数，可以完全控制提示词的生成，覆盖默认的（序言、示例、跋语）结构。**注意**: 这是一个实验性功能，可能不稳定。
### 模型配置 (Model Configuration) [#模型配置-model-configuration]
* **`api_keys_path`**: `str`
* 指向包含 API 密钥和模型端点信息的 JSON 配置文件路径。
* **`models`**: `List[str]`
* 用于思路生成的模型别名列表（例如, `'GPT4_o'`, `'Deepseek_V3'`）。这些别名必须是 `api_keys_path` 文件中键的子集。
* **`model_temperatures`**: `List[float]`
* LLM 的采样温度列表。此列表的长度和顺序必须与 `models` 列表匹配。
* **`model_sample_temperature`**: `float` (默认: `50.0`)
* 用于选择下一轮生成使用哪个模型的 softmax 温度。值越高，模型选择的随机性越大。
* **`top_p`**: `Optional[float]` (默认: `None`)
* `top_p` 核采样参数，控制令牌选择的累积概率。对应于标准的 API 参数。
* **`max_completion_tokens`**: `Optional[int]` (默认: `None`)
* 在一次补全中生成的最大令牌数。对应于标准的 API 参数。
**API 密钥文件格式 (`api_keys.json`):**
此文件应为一个 JSON 对象，其中每个顶级键对应于您将在 `set_models()` 中使用的唯一模型别名。每个模型别名的值是一个字典列表，每个字典代表该模型的一个实例。这允许您为同一个逻辑模型配置多个实例（例如，使用不同的 API 密钥或基础 URL），系统将自动管理它们。
```json
{
"Deepseek-V3": [
{
"api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"base_url": "https://api.deepseek.com/v1",
"model": "deepseek-chat"
}
],
"Gemini-2.5-Pro": [
{
"api_key": "AIzaSyXXXX-XXXXXXXXXXXXXXXXXXXXXXXX",
"base_url": "https://generativelanguage.googleapis.com/v1beta/",
"model": "gemini-1.5-flash"
}
]
}
```
### 生成与后处理 (Generation and Post-processing) [#生成与后处理-generation-and-post-processing]
* **`generate_num`**: `int` (默认: `1`)
* 每个采样器线程在单轮中尝试生成的新思路数量。
* **`postprocess_func`**: `Optional[Callable[[str], str]]` (默认: `None`)
* 一个自定义函数，用于在 LLM 生成的原始文本保存为思路文件之前对其进行清理或格式化。
* **`hand_over_threshold`**: `float` (默认: `0.0`)
* 新生成的思路必须从评估器获得最低分数才能被接纳到岛屿的种群中。
### 评估器 (Evaluator) [#评估器-evaluator]
* **`evaluators_num`**: `int` (默认: `3`)
* 每个岛屿并行运行的评估器 (Evaluator) 线程数量。
* **`evaluate_func`**: `Callable[[str], Tuple[float, Optional[str]]]`
* 核心评估函数。它接受一个思路的内容（字符串）作为输入，并且必须返回一个元组 `(score: float, info: Optional[str])`。
* **`score_range`**: `Tuple[float, float]` (默认: `(0.0, 100.0)`)
* 一个元组 `(min_score, max_score)`，定义了 `evaluate_func` 的预期输出范围。用于归一化和可视化。
### 数据库评估 (Database Assessment) [#数据库评估-database-assessment]
* **`assess_func`**: `Optional[Callable[[List[str], List[float], List[Optional[str]]], float]]` (默认: `default_assess_func`)
* 一个自定义函数，用于评估整个思路数据库的总体状态，提供一个整体的质量度量。
* **`assess_interval`**: `Optional[int]` (默认: `1`)
* 调用 `assess_func` 来评估整个数据库的频率（以轮次为单位）。
* **`assess_baseline`**: `Optional[float]` (默认: `60.0`)
* 一个基线分数值，将在数据库评估图上绘制为水平线，以便于性能比较。
### 模型评估 (Model Assessment) [#模型评估-model-assessment]
* **`model_assess_window_size`**: `int` (默认: `20`)
* 在计算模型移动平均性能得分时，所考虑的由该模型最近生成的思路数量。
* **`model_assess_initial_score`**: `float` (默认: `100.0`)
* 分配给每个模型的初始分数。较高的值鼓励对所有可用模型的初始探索。
* **`model_assess_average_order`**: `float` (默认: `1.0`)
* 用于计算模型得分移动平均的 p-范数（广义平均值）的阶数 $p$。$p=1$ 是算术平均值，较高的值会给予高分更大的权重。
* **`model_assess_save_result`**: `bool` (默认: `True`)
* 如果为 `True`，将模型评估数据和可视化结果保存到指定的路径。
### 变异 (Mutation) [#变异-mutation]
* **`mutation_func`**: `Optional[Callable[[str], str]]` (默认: `None`)
* 一个自定义函数，接受一个思路的内容并返回一个轻微修改后的版本。
* **`mutation_interval`**: `Optional[int]` (默认: `None`)
* 在岛屿种群上执行变异操作的频率（以轮次为单位）。
* **`mutation_num`**: `Optional[int]` (默认: `None`)
* 每次触发操作时通过变异生成的新思路数量。
* **`mutation_temperature`**: `Optional[float]` (默认: `None`)
* 用于选择变异父代思路的 softmax 温度。值越高，得分较低的思路被变异的机会就越大。
### 交叉 (Crossover) [#交叉-crossover]
* **`crossover_func`**: `Optional[Callable[[str, str], str]]` (默认: `None`)
* 一个自定义函数，接受两个思路的内容并返回一个结合了两方元素的新思路。
* **`crossover_interval`**: `Optional[int]` (默认: `None`)
* 执行交叉操作的频率（以轮次为单位）。
* **`crossover_num`**: `Optional[int]` (默认: `None`)
* 每次触发操作时通过交叉生成的新思路数量。
* **`crossover_temperature`**: `Optional[float]` (默认: `None`)
* 用于选择交叉父代思路的 softmax 温度。值越高，父代选择的随机性越大。
### 相似度 (Similarity) - 不常用 [#相似度-similarity---不常用]
* **`similarity_threshold`**: `float` (默认: `-1.0`)
* 距离阈值，低于此值的两个思路被认为是相似的。值为 `-1.0` 表示除完全重复外，禁用相似性检查。
* 其他相关参数如 `similarity_distance_func` 等用于更复杂的相似性控制。
### 杂项 (Miscellaneous) [#杂项-miscellaneous]
* **`idea_uid_length`**: `int` (默认: `6`)
* `.idea` 文件名中使用的唯一标识符 (UID) 的字符长度。
* **`record_prompt_in_diary`**: `bool` (默认: `False`)
* 如果为 `True`，每轮生成中发送给 LLM 的完整提示词将被记录在日志文件中。
* **`backup_on`**: `bool` (默认: `True`)
* 如果为 `True`，则在 `run` 方法开始时启用对 `ideas` 目录的自动备份。
* **`shutdown_score`**: `float` (默认: `float('inf')`)
* 如果所有岛屿中的最佳分数达到此值，IdeaSearch 进程将优雅地终止。
## 工作流程概览 [#工作流程概览]
一个典型的 `IdeaSearch` 使用流程展示了如何组织代码以实现完整的进化循环，包括多岛屿的创建、周期性的种群交换和持续的思路生成。以下示例借鉴自 [IdeaSearch-test 仓库](https://github.com/IdeaSearch/IdeaSearch-test)，代表了一种常见的实践模式。
```python
# pip install IdeaSearch
from IdeaSearch import IdeaSearcher
from user_code.prompt import prologue_section, epilogue_section
from user_code.evaluation import evaluate
from user_code.initial_ideas import initial_ideas
def main():
# 1. 初始化
ideasearcher = IdeaSearcher()
# 2. 基础配置
ideasearcher.set_language("zh_CN") # 设置语言 (默认: 'zh_CN'; 可选: 'zh_CN', 'en')
ideasearcher.set_api_keys_path("api_keys.json")
ideasearcher.set_program_name("TemplateProgram")
ideasearcher.set_database_path("database")
# 3. 核心逻辑配置 (评估函数)
ideasearcher.set_evaluate_func(evaluate)
# 4. 提示词工程配置
ideasearcher.set_prologue_section(prologue_section)
ideasearcher.set_epilogue_section(epilogue_section)
# 5. 模型配置
ideasearcher.set_models([
"Deepseek_V3",
])
ideasearcher.set_model_temperatures([
0.6,
])
# 6. (可选) 其他配置
ideasearcher.set_record_prompt_in_diary(True)
# 7. 添加初始思路 (无需在文件系统中操作)
ideasearcher.add_initial_ideas(initial_ideas)
# 8. 定义并执行进化循环
island_num = 2 # 岛屿数量
cycle_num = 3 # 迁徙周期数
unit_interaction_num = 10 # 每个周期的进化轮次
# 创建初始岛屿
for _ in range(island_num):
ideasearcher.add_island()
# 运行进化
for cycle in range(cycle_num):
print(f"---[ 周期 {cycle + 1}/{cycle_num} ]---")
# 在每个周期开始前 (除第一个周期外) 进行岛屿间思路迁徙
if cycle != 0:
print("正在重新繁衍岛屿...")
ideasearcher.repopulate_islands()
# 在当前周期内运行指定轮次的进化
ideasearcher.run(unit_interaction_num)
# 9. 获取并利用最终结果
print("\n---[ 搜索完成 ]---")
best_idea_content = ideasearcher.get_best_idea()
print("最佳思路内容:")
print(best_idea_content)
if __name__ == "__main__":
main()
```
## 国际化 [#国际化]
`IdeaSearch` 支持其界面文本的国际化。
你可以使用 `set_language(value: str)` 方法来设置系统语言。
例如, `ideasearcher.set_language('en')` 会将界面和日志文本切换为英文，而 `ideasearcher.set_language('zh_CN')` 会切换为简体中文。
`IdeaSearch` 的默认语言是简体中文 (`zh_CN`)。
# IdeaSearch 文档 (/cn/docs/framework)
# IdeaSearch 文档 [#ideasearch-文档]
IdeaSearch 是一个开源 Python 框架，用于构建包含用户自定义评价、持久候选记忆和多岛屿搜索的迭代式大模型智能体工作流。它适用于需要配置、记录或比较生成—评价循环的任务。
框架产生经过评价的候选。领域解释和验证是独立步骤，应使用与任务相适应的证据、留出数据或独立检验完成。
## 项目组成 [#项目组成]
* **IdeaSearch Framework**：配置候选生成、评价、记忆、并行岛屿、迁徙、预算和运行产物。
* **IdeaSearch-fit**：将该框架用于符号回归，结合候选表达式生成与数值参数拟合。
## 从这里开始 [#从这里开始]
配置并运行一个迭代式 IdeaSearch 工作流。
打开手册
配置数据、表达式语法、数值拟合与结果访问。
打开手册
查看一个完整的符号回归示例。
打开示例
查看框架源码、版本发布和问题跟踪。
查看 GitHub
查看拟合器源码、版本发布和问题跟踪。
查看 GitHub
## 框架控制项 [#框架控制项]
* **任务与测量**：用户定义的候选评价，以及可选的数据库整体评估。
* **初始条件与记忆**：起始候选、提示词、历史示例和评价反馈。
* **探索与拓扑**：模型采样、变异、交叉、并行岛屿和迁徙。
* **预算与记录**：显式交互预算、候选数据库、分数、日志和备份。
* **结果访问**：读取当前最高分候选及其评价器分数。
## 文档页面 [#文档页面]
{getPageTreePeers(source.pageTree, "/cn/docs/framework").map((peer) => (
{peer.description}
))}