saealib 0.1.0b3

A Python library for Surrogate-Assisted Evolutionary Algorithms (SAEAs)

saealib

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

pip install saealib

To install the latest beta release explicitly:

pip install saealib==0.1.0b1

Or to install the latest pre-release version:

pip install --pre saealib

Install via uv

uv add saealib

To install the latest beta release explicitly:

uv add saealib==0.1.0b1

Install from source

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

Or for development (editable mode):

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.

import numpy as np
from saealib import (
    GA,
    Optimizer,
    Problem,
    RBFsurrogate,
    LHSInitializer,
    CrossoverBLXAlpha,
    MutationUniform,
    SequentialSelection,
    TruncationSelection,
    IndividualBasedStrategy,
    Termination,
    max_fe,
    f_target,
    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
# Conditions compose with & (AND), | (OR), and ~ (NOT).
# Here: stop after 100 evaluations OR once the objective reaches the target.
termination = Termination(max_fe(100) | f_target(1e-6))

# 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 for guidelines on how to contribute to this project.

License

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