AutoOptLib

AutoOptLib is a Python framework for component-based automated design of metaheuristic optimizers. It searches over typed operator pathways containing selection, search, and update components, and evaluates candidate algorithms on user-provided training instances before testing them on held-out instances.

Version 1.2.0 is the first release packaged as a self-contained Python project. The earlier MATLAB implementation remains available from the repository's historical releases.

Features

• Components for continuous, discrete, and permutation search spaces.
• Joint search over operator composition and component parameters.
• Exact, racing, intensification, and surrogate-assisted evaluation modes.
• Quality, evaluation-count, wall-clock, and anytime objectives.
• Deterministic runs through a single user-provided random seed.
• Strict ProbFE objective budgets and MATLAB-compatible AlgFE proposal budgets.
• Versioned JSON export for designed algorithms.
• A small public factory for ordinary Python objective functions.
• Runtime registration of custom components without editing package internals.
• Bundled CEC 2013 data that works from source and installed wheels.
• Executable reference models for material stacking and RIS beamforming.
• Retry, hard-timeout, failure-penalty, evaluation-cache, and JSONL logging controls for external objectives.
• Automatic experiment manifests with software and invocation provenance.
• Optional ALDes autoregressive generation, PPO training, continual-learning, and pure-Python execution of an ALDes-compatible discrete token vocabulary.

Installation

AutoOptLib requires Python 3.9 or newer.

Install the latest release from PyPI:

python -m pip install autooptlib

For development:

python -m pip install -e ".[dev]"
python -m ruff check .
python -m ruff format --check .
python -m pytest -W error

Install the learning-based ALDes designer separately so core users do not need PyTorch or IOH:

python -m pip install "autooptlib[aldes]"

Quick start

The following example designs a small optimizer for the bundled CEC 2013 shifted-sphere problem. The small budgets are intended only as a smoke test.

from autooptlib import autoopt, make_problem

sphere = make_problem(
    lambda decision, dimension: float((decision**2).sum()),
    bounds=(-5.0, 5.0),
    name="sphere",
)

algorithms, trace = autoopt(
    Mode="design",
    Problem=sphere,
    InstanceTrain=[10],
    InstanceTest=[20],
    AlgN=2,
    AlgFE=40,
    AlgRuns=2,
    ProbN=10,
    ProbFE=500,
    Evaluate="exact",
    Compare="average",
    Seed=2026,
    OutputDir="results/design",
)

print(algorithms[0].operator_pheno)

To run a built-in optimizer directly:

from autooptlib import autoopt

best, history = autoopt(
    Mode="solve",
    Problem="cec2013_f1",
    InstanceSolve=[10],
    AlgName="CMA-ES",
    AlgRuns=3,
    ProbN=20,
    ProbFE=2000,
    Metric="quality",
    Seed=2026,
)

The design call writes portable files such as Algorithm_1.json to OutputDir. Use one output directory per experiment. Designed algorithms can later be loaded without executing pickle code:

best, history = autoopt(
    Mode="solve",
    Problem=sphere,
    InstanceSolve=[30],
    AlgFile="results/design/Algorithm_1.json",
    ProbN=20,
    ProbFE=2000,
    Seed=2026,
    OutputDir="results/solve",
)

All public keyword names are case-insensitive and accept snake case. Unknown keywords raise an error. ProbFE includes initial-population evaluations and is a hard upper bound per algorithm run. For compatibility with the published MATLAB procedure, AlgFE counts newly proposed algorithms after the initial AlgN incumbents; held-out evaluation of the final algorithms is separate. Sequential problems receive a fresh ProbFE budget at every stage.

Learning-based design with ALDes

autooptlib.aldes contains a constrained 32-token ALDes grammar, sequence-to-pathway codec, PyTorch generator, PPO/EWC training utilities, IOH PBO adapter, and a direct evaluation bridge. A trained generator can be used through the same high-level entry point:

from autooptlib import autoopt

algorithms, trace = autoopt(
    Mode="design",
    Designer="aldes",
    Problem=my_discrete_problem,
    InstanceTrain=[train_instance],
    InstanceTest=[test_instance],
    ALDesModel="checkpoints/aldes.pt",
    ALDesCandidates=32,
    AlgN=5,
    ProbN=50,
    ProbFE=5_000,
    AlgRuns=5,
    Seed=2026,
)

Single-problem design is the default: create the generator with the default GeneratorConfig, use ALDesMode="single" (or omit it), and do not calculate or pass landscape features. For continual design, train a generator with GeneratorConfig(condition_on_features=True) and call the workflow with ALDesMode="continual" plus ALDesFeatures=problem_features. The continual feature extractor is available as autooptlib.aldes.extract_pbo_features and returns both the feature vector and sampled initial populations. Its result object can be passed directly as ALDesFeatures; the associated populations are then reused automatically, or they can be supplied separately through ALDesInitialPopulations.

The ordinary Designer="search" workflow remains the default. ALDes decodes its generated programs into the same Design and pathway objects used by the rest of AutoOptLib; MATLAB and MATLAB Engine are not required. ALDesModel checkpoint paths must be produced by ALDesGenerator.save_checkpoint; unversioned checkpoints from the historical standalone ALDes repository are not loaded implicitly.

Reproducibility

Pass Seed=<integer> to autoopt. Version 1.2.0 routes this seed through algorithm construction, component execution, selection, archiving, and surrogate sampling. Repeating the same call with the same software version, inputs, and platform produces the same stochastic sequence.

For expensive thread-safe objectives, set EvalWorkers above one to evaluate candidate batches concurrently while preserving result order. Static and sequential Solve runs and the outer Design search support atomic CheckpointDir/Resume recovery; see the reliability guide.

For archival experiments, record the AutoOptLib version, Python and NumPy versions, operating system, complete call arguments, and the generated output files.

Extending the component library

Components use a mode-based callable interface. A custom component can be registered at runtime:

from autooptlib import register_component

def search_example(*args):
    mode = args[-1]
    if mode == "execute":
        parent = args[0]
        aux = args[3]
        return parent.decs(), aux
    if mode == "parameter":
        return None, None
    if mode == "behavior":
        return ["", "GS"], None
    raise ValueError(f"Unsupported mode: {mode}")

register_component(
    "search_example",
    search_example,
    category="search",
    problem_types=["continuous"],
)

Registered components are automatically added to compatible design spaces created later in the same Python process.

For most applications, use make_problem as in the quick start. Advanced dynamic or sequential problems can implement the ProblemDefinition protocol. See the user-problem guide and the API guide. The canonical rendered documentation is hosted on Read the Docs.

Application examples

The repository contains runnable examples for the material-stacking and RIS passive-beamforming problem classes discussed in the paper. The included instances are synthetic and public; they validate the software workflow but do not reproduce the paper's proprietary stacking records or original wireless channel files. See the application guide and examples/applications.

Scope and limitations

AutoOptLib performs offline algorithm design and can require many objective function evaluations. It is most appropriate when the design cost can be amortized over repeated solution of related instances. The default component space is curated rather than exhaustive, and the current graph representation encodes one or more bounded operator pathways rather than arbitrary programs. It is a research-oriented beta: application-specific validation, complete constraint modelling, simulator resource isolation, and deployment monitoring remain the user's responsibility, although opt-in retry, timeout, penalty, caching, and evaluation logging controls are available. AutoOptLib is not a universal replacement for expert optimizer selection on a one-off problem.

Contributing and support

See CONTRIBUTING.md for the development workflow. Report bugs and request features through the GitHub issue tracker.

Citation

Citation metadata is provided in CITATION.cff. Until the software paper is published, please cite:

@article{zhao2023autooptlib,
  title   = {AutoOptLib: Tailoring Metaheuristic Optimizers via Automated Algorithm Design},
  author  = {Zhao, Qi and Yan, Bai and Hu, Taiwei and Chen, Xianglong and Duan, Qiqi and Yang, Jian and Shi, Yuhui},
  journal = {arXiv preprint arXiv:2303.06536},
  year    = {2023}
}

License

AutoOptLib is licensed under the Apache License 2.0.