Metadata-Version: 2.4
Name: autooptlib
Version: 1.3.0
Summary: Component-based automated design of metaheuristic optimizers
Author: Swarm Intelligence Lab
Author-email: Qi Zhao <zhaoq@sustech.edu.cn>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/auto4opt/AutoOptLib
Project-URL: Documentation, https://autooptlib.readthedocs.io/
Project-URL: Repository, https://github.com/auto4opt/AutoOptLib
Project-URL: Issues, https://github.com/auto4opt/AutoOptLib/issues
Keywords: automated algorithm design,metaheuristics,optimization,evolutionary computation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.23
Provides-Extra: test
Requires-Dist: pytest>=7.4; extra == "test"
Requires-Dist: pytest-cov>=4.1; extra == "test"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: sphinx<9,>=7.2; extra == "dev"
Requires-Dist: sphinx-rtd-theme<4,>=2; extra == "dev"
Requires-Dist: myst-parser<5,>=2; extra == "dev"
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Requires-Dist: ruff<1,>=0.9; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx<9,>=7.2; extra == "docs"
Requires-Dist: sphinx-rtd-theme<4,>=2; extra == "docs"
Requires-Dist: myst-parser<5,>=2; extra == "docs"
Provides-Extra: applications
Requires-Dist: scipy<2,>=1.10; extra == "applications"
Provides-Extra: surrogate
Requires-Dist: scikit-learn<2,>=1.2; extra == "surrogate"
Provides-Extra: aldes
Requires-Dist: torch<3,>=2.1; extra == "aldes"
Requires-Dist: ioh<1,>=0.3.14; extra == "aldes"
Requires-Dist: pandas<4,>=2; extra == "aldes"
Requires-Dist: pflacco<2,>=1.2; extra == "aldes"
Requires-Dist: scikit-learn<2,>=1.2; extra == "aldes"
Dynamic: license-file

# AutoOptLib

[![Version](https://img.shields.io/badge/version-1.3.0-blue.svg)](https://github.com/auto4opt/AutoOptLib/releases)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
[![Tests](https://github.com/auto4opt/AutoOptLib/actions/workflows/tests.yml/badge.svg)](https://github.com/auto4opt/AutoOptLib/actions/workflows/tests.yml)
[![Documentation](https://readthedocs.org/projects/autooptlib/badge/?version=latest)](https://autooptlib.readthedocs.io/)

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:

```bash
python -m pip install autooptlib
```

For development:

```bash
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:

```bash
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.

```python
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:

```python
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:

```python
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:

```python
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](docs/reliability.md).

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:

```python
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](docs/custom-problems.md) and
[the API guide](docs/api.md). The canonical rendered documentation is hosted
on [Read the Docs](https://autooptlib.readthedocs.io/).

## 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](docs/applications.md) and
[`examples/applications`](examples/applications/README.md).

## 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](CONTRIBUTING.md) for the development workflow. Report
bugs and request features through the
[GitHub issue tracker](https://github.com/auto4opt/AutoOptLib/issues).

## Citation

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

```bibtex
@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](LICENSE).
