Metadata-Version: 2.4
Name: saealib
Version: 0.1.0b2
Summary: A Python library for Surrogate-Assisted Evolutionary Algorithms (SAEAs)
Project-URL: Homepage, https://github.com/shlka/saealib
Project-URL: Repository, https://github.com/shlka/saealib
Project-URL: Documentation, https://shlka.github.io/saealib/
Project-URL: Bug Tracker, https://github.com/shlka/saealib/issues
Author-email: shlka <82360718+shlka@users.noreply.github.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.22.1
Requires-Dist: scipy>=1.0.0
Requires-Dist: typing-extensions>=4.15.0
Provides-Extra: lightgbm
Requires-Dist: lightgbm>=3.0.0; extra == 'lightgbm'
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.0.0; extra == 'sklearn'
Provides-Extra: torch
Requires-Dist: torch>=2.0.0; extra == 'torch'
Provides-Extra: xgboost
Requires-Dist: xgboost>=1.7.0; extra == 'xgboost'
Description-Content-Type: text/markdown

# saealib
![Status: Alpha](https://img.shields.io/badge/Status-Alpha-orange)

**Status: Active Development (Alpha)**
> **Warning**: This project is under active development. APIs are subject to change without notice. Operation is not guaranteed in production environments.

A comprehensive library for **Surrogate-Assisted Evolutionary Algorithms (SAEAs)** in Python.  
Designed for expensive optimization problems where function evaluations are costly, `saealib` provides a modular framework to combine evolutionary algorithms, surrogate models, and model management strategies.

## Documents
https://shlka.github.io/saealib/index.html

## Key Features

- **Modular Architecture**: Easily mix and match Algorithms (e.g., GA), Surrogates (e.g., RBF), and Management Strategies.
- **Method Chaining**: The `Optimizer` class allows for fluent and readable configuration.
- **Customizable Components**:
  - **Algorithms**: Genetic Algorithms (GA) with various operators.
  - **Surrogates**: Radial Basis Function (RBF) networks with Gaussian kernels.
  - **Strategies**: Individual-based management strategies (e.g., generation-based or pre-selection).
  - **Operators**: Includes BLX-Alpha Crossover, Uniform Mutation, and various Selection methods.

## Installation

### Requirements
- Python >= 3.10
- numpy
- scipy

### Install via pip

```bash
pip install saealib
```

To install the latest beta release explicitly:

```bash
pip install saealib==0.1.0b1
```

Or to install the latest pre-release version:

```bash
pip install --pre saealib
```

### Install via uv

```bash
uv add saealib
```

To install the latest beta release explicitly:

```bash
uv add saealib==0.1.0b1
```

### Install from source

```bash
git clone https://github.com/shlka/saealib.git
cd saealib
pip install .
```

Or for development (editable mode):

```bash
pip install -e .
```

## Quick Start

Here is a simple example of how to use `saealib` to minimize a Sphere function using a Surrogate-Assisted GA (SAGA) with an RBF model.

```python
import numpy as np
from saealib import (
    GA,
    Optimizer,
    Problem,
    RBFsurrogate,
    LHSInitializer,
    CrossoverBLXAlpha,
    MutationUniform,
    SequentialSelection,
    TruncationSelection,
    IndividualBasedStrategy,
    Termination,
    max_fe,
    gaussian_kernel
)

# 1. Define the Objective Function (e.g., Sphere Function)
def sphere(x):
    return np.sum(x**2)

# 2. Setup the Optimization Problem
dim = 5
problem = Problem(
    func=sphere,
    dim=dim,
    n_obj=1,
    weight=np.array([-1.0]),  # -1.0 implies minimization
    lb=[-5.0] * dim,          # Lower bounds
    ub=[5.0] * dim,           # Upper bounds
)

# 3. Configure Components

# Initialization: Latin Hypercube Sampling
initializer = LHSInitializer(
    n_init_archive=5 * dim,      # Initial samples for the surrogate
    n_init_population=4 * dim,   # Initial population size
    seed=42,
)

# Algorithm: Genetic Algorithm
algorithm = GA(
    crossover=CrossoverBLXAlpha(crossover_rate=0.7, alpha=0.4),
    mutation=MutationUniform(mutation_rate=0.3),
    parent_selection=SequentialSelection(),
    survivor_selection=TruncationSelection(),
)

# Surrogate Model: RBF with Gaussian Kernel
surrogate = RBFsurrogate(gaussian_kernel, dim)

# Strategy: Individual-Based Management
# evaluation_ratio=0.1: Ratio of offspring selected for true objective evaluation
strategy = IndividualBasedStrategy(evaluation_ratio=0.1)

# Termination Criterion
termination = Termination(max_fe(100))  # Stop after 100 function evaluations

# 4. Build and Run the Optimizer
opt = (
    Optimizer(problem)
    .set_initializer(initializer)
    .set_algorithm(algorithm)
    .set_termination(termination)
    .set_surrogate(surrogate)
    .set_strategy(strategy)
)

print("Starting optimization...")
opt.run()
print("Optimization finished.")
```

## Architecture Overview

`saealib` is built around the `Optimizer` class which orchestrates the interaction between:

- **Problem**: Defines the objective function, constraints, and bounds.
- **Algorithm**: The evolutionary search engine (e.g., GA).
- **Surrogate**: The approximate model used to replace expensive evaluations.
- **Strategy**: Decides when to use the surrogate and when to use the real function (e.g., Pre-selection, Generation control).
- **Initializer**: Generates the initial dataset.

## Contributing

Contributions are welcome! Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute to this project.

## License

[MIT License](LICENSE) (Assuming standard open source license, please verify)
