Metadata-Version: 2.4
Name: cmenpy
Version: 2026b1
Summary: An extensible Python framework for designing and benchmarking metaheuristics
Author-email: ltsim <tsim@cucei.udg.mx>
License: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/ltsim/cmenpy
Project-URL: Source Code, https://github.com/ltsim/cmenpy
Project-URL: Bug Tracker, https://github.com/ltsim/cmenpy/issues
Project-URL: Change Log, https://github.com/ltsim/cmenpy/blob/main/CHANGELOG.md
Keywords: metaheuristics,metaheuristic design,evolutionary computation,population-based algorithms,nature-inspired algorithms,hybrid algorithms,adaptive search,self-adaptation,benchmark functions,performance analysis,exploration versus exploitation,stochastic optimization,global optimization,black-box optimization,soft computing
Classifier: Typing :: Typed
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: System :: Benchmark
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=2.0.2
Provides-Extra: numba
Requires-Dist: numba>=0.67.0; extra == "numba"
Provides-Extra: dev
Requires-Dist: numba>=0.67.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: mypy>=1.9.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: flake8>=7.0; extra == "dev"
Requires-Dist: pandas-stubs>=2.2.3; extra == "dev"
Requires-Dist: scipy-stubs>=1.15.0; extra == "dev"
Requires-Dist: black>=21.9b0; extra == "dev"
Requires-Dist: opfunu-core>=1.0.6; extra == "dev"
Requires-Dist: enoppy-core>=0.1.2.1; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material<10,>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.26; extra == "docs"
Provides-Extra: benchmarks
Requires-Dist: opfunu-core>=1.0.6; extra == "benchmarks"
Requires-Dist: enoppy-core>=0.1.2.1; extra == "benchmarks"
Dynamic: license-file

# cmenpy

![cmenpy](https://raw.githubusercontent.com/ltsim/cmenpy/main/resources/cmenpy.png)

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg?style=flat-square)](https://www.gnu.org/licenses/gpl-3.0)
![PyPI - Version](https://img.shields.io/pypi/v/cmenpy?style=flat-square)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/cmenpy?style=flat-square)
![PyPI - Wheel](https://img.shields.io/pypi/wheel/cmenpy?style=flat-square)
![PyPI - Downloads](https://img.shields.io/pypi/dm/cmenpy?style=flat-square)
![Publish](https://img.shields.io/github/actions/workflow/status/ltsim/cmenpy/publish.yml?style=flat-square&logo=pypi&label=Publish)
![Testing](https://img.shields.io/github/actions/workflow/status/ltsim/cmenpy/test.yml?style=flat-square&logo=pytest&label=Testing)
![Typed](https://img.shields.io/github/actions/workflow/status/ltsim/cmenpy/type.yml?style=flat-square&logo=python&label=Typed)

**C**ompute **M**etaheuristic **En**gine for **P**ython (_cmenpy_ or _/siːmɛnpaɪ/_) is an extensible, flexible, and vectorized Python framework for designing and prototyping metaheuristic and population-based optimization algorithms.

It provides the clean abstractions necessary to build custom evolutionary algorithms, swarm intelligence methods, and hybrid heuristics from scratch — with absolute architectural control.

## Installation

```bash
pip install cmenpy
```

Requires Python `>=3.11`. Numba is **optional**: kernels compile when it is
installed (`pip install "cmenpy[numba]"`), and run as pure NumPy/Python when
it is not — or whenever a model asks with `numba=False`.

To develop or build the docs:

```bash
git clone https://github.com/ltsim/cmenpy.git
cd cmenpy
uv sync --extra dev        # tests, type checks, linters
uv sync --extra docs       # ... plus the MkDocs toolchain
uv sync --extra benchmarks # ... plus opfunu-core / enoppy-core test functions
```

## Quick example

```python
import numpy as np
import cmenpy as cm


@cm.declare(x=cm.Argument[int, (0, 3), 2])
def my_algorithm(args, epoch, ctx):
    pop = cm.PopulationSwarm(ctx.buff)
    pop.compute << ctx.rng.uniform(
        ctx.bounds.low, ctx.bounds.up, (pop.size, ctx.bounds.ndim)
    )
    for _ in epoch:  # one epoch of your operator, per iteration
        ...


best_fitness, best_x = my_algorithm(x=1).solve(
    lambda x: np.sum(x**2), cm.Bounds([(-1, 1)] * 3), epochs=150, pop_size=15
)
```

See the [Quickstart](https://ltsim.github.io/cmenpy/quickstart/) for both the function (`@cm.declare`) and class (`@cm.template`) styles.

## Core pillars

- **Vectorized data structures.** Population arrays, agent states, and search spaces use a flattened, vectorized layout with no per-individual objects. Buffer views (`pop.X`, `pop.F`) interoperate with NumPy through the explicit `cm.cast(...)` helper and can be passed directly to `cmenpy` kernels, which unwrap them internally.
- **Extensible architecture.** Custom operators, mutation rules, or entirely new paradigms require overriding only a few decoupled, well-defined methods. Reusable **Operator Modules** (`@cm.module`) share kernels, helpers, and `cm.Constant` fields across models.
- **Non-monolithic flexibility.** No visualization tools, file exporters, or rigid loggers — just the mathematical engine and its structural flow.
- **Research ready.** Licensed under the **GNU GPLv3**. Design, modify, and distribute your algorithms freely; derivative works stay open, keeping the software a public good for research and commercial development.

## Documentation

Full guides and the API reference are published at **[ltsim.github.io/cmenpy](https://ltsim.github.io/cmenpy/)**.

| Guide | Covers |
| ----- | ------ |
| [Quickstart](https://ltsim.github.io/cmenpy/quickstart/) | Solve your first problem in minutes |
| [Models](https://ltsim.github.io/cmenpy/models/) | `@cm.declare` vs `@cm.template`, the `ctx` object |
| [Build a custom model](https://ltsim.github.io/cmenpy/tutorial-custom-model/) | Step-by-step tutorial implementing your own optimizer |
| [Numba kernels](https://ltsim.github.io/cmenpy/compile/) | `@cm.precompile`, `@cm.vectorize`, `@cm.reduce` |
| [Population](https://ltsim.github.io/cmenpy/population/) | `PopulationSwarm`, buffers, selection, ranking |
| [Target functions](https://ltsim.github.io/cmenpy/target/) | Objectives, NFE budget, vectorized targets |
| [Examples](https://ltsim.github.io/cmenpy/examples/) | Runnable algorithms in `example/` |
| [Test functions](https://ltsim.github.io/cmenpy/benchmarks/) | Benchmarks with `opfunu-core` and `enoppy-core` |
| [API reference](https://ltsim.github.io/cmenpy/api/) | Full reference for every public symbol, by category |
| [Roadmap](https://ltsim.github.io/cmenpy/roadmap/) | Planned and scheduled work |
| [Changelog](https://ltsim.github.io/cmenpy/changelog/) | Release notes |

To preview locally: `uv sync --extra docs && .venv/bin/mkdocs serve`.

## Contributing

Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the list of [contributors](CONTRIBUTORS.md).

---

*Developed by [LTSIM](mailto:tsim@cucei.udg.mx) @ 2026. Licensed under [GNU GPLv3](LICENSE.md).*
