Metadata-Version: 2.4
Name: fcmaes-rust
Version: 0.1.2
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Requires-Dist: numpy>=1.20
Requires-Dist: scipy>=1.8
Requires-Dist: pytest>=7 ; extra == 'test'
Provides-Extra: test
License-File: LICENSE
Summary: Native Rust implementation of fast, parallel, gradient-free optimization.
Keywords: optimization,gradient-free,black-box optimization,CMA-ES,multi-objective optimization
Author: Dietmar Wolz
License-Expression: MIT
Requires-Python: >=3.11, <3.14
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Changelog, https://github.com/dietmarwo/fcmaes-rust/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/dietmarwo/fcmaes-rust/tree/main/docs
Project-URL: Issues, https://github.com/dietmarwo/fcmaes-rust/issues
Project-URL: Repository, https://github.com/dietmarwo/fcmaes-rust

# fcmaes-rust for Python

`fcmaes-rust` provides Python access to fast, parallel, gradient-free
optimization algorithms implemented in native Rust. The optimizer core is
pure Rust and does not compile, link, or load the historical C++ backend.

## Installation

```bash
python -m pip install fcmaes-rust
```

The initial release supports CPython 3.11 through 3.13 on the platforms for
which wheels are listed on PyPI.

## Quick check

```python
import fcmaes_rust

print(fcmaes_rust.__version__)
print(fcmaes_rust.phase1_build_info())
```

## Optimizers

The package exposes one-shot and ask/tell interfaces for Differential
Evolution, active CMA-ES, CR-FM-NES, PGPE and BiteOpt, plus Dual Annealing,
MODE, MAP-Elites, the Diversifier, independent retry, coordinated retry and
weighted multi-objective retry.

The functions currently return low-level NumPy arrays, tuples or dictionaries.
See the [Python binding guide](https://github.com/dietmarwo/fcmaes-rust/blob/main/docs/python-bindings.md)
for signatures, examples, parallelism behavior and result layouts.
SciPy is a runtime dependency because retry callbacks receive a public
`scipy.optimize.Bounds` object.

```python
import numpy as np
import fcmaes_rust

def sphere(x):
    return float(np.dot(x, x))

dim = 4
empty = np.empty(0, dtype=np.float64)
x, value, evaluations, iterations, stop = fcmaes_rust.optimize_de(
    sphere,
    dim,
    np.full(dim, -5.0),
    np.full(dim, 5.0),
    empty,
    empty,
    np.empty(0, dtype=np.bool_),
    seed=7,
    max_evaluations=4_000,
    popsize=20,
)
print(value, evaluations, x)
```

Python callbacks must reacquire the GIL. Native Rust objectives offer the
strongest parallel scaling; cheap pure-Python callbacks are usually
callback-bound.

## Project links

- [Source repository](https://github.com/dietmarwo/fcmaes-rust)
- [Documentation](https://github.com/dietmarwo/fcmaes-rust/tree/main/docs)
- [Issue tracker](https://github.com/dietmarwo/fcmaes-rust/issues)
- [Release history](https://github.com/dietmarwo/fcmaes-rust/releases)

## License

MIT

