Metadata-Version: 2.3
Name: tyrannis
Version: 0.1.0a1
Summary: Flexible optimization framework for particle-based population algorithms, supporting diverse search spaces, optimization strategies, and execution backends.
Keywords: optimization,metaheuristics,population-based optimization,particle-based optimization,swarm intelligence,particle swarm optimization,PSO,artificial bee colony optimization,ABC,parallel optimization,distributed optimization,island model,mixed search space
Author: Samuel Carlos Pessoa Oliveira
License: BSD 3-Clause License
         
         Copyright (c) 2026, Samuel Carlos Pessoa Oliveira
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         1. Redistributions of source code must retain the above copyright notice, this
            list of conditions and the following disclaimer.
         
         2. Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
         
         3. Neither the name of the copyright holder nor the names of its
            contributors may be used to endorse or promote products derived from
            this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
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 :: 3.14
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Dist: numpy>=2.1.3,<3.0.0
Requires-Dist: scipy>=1.15.3,<2.0.0
Requires-Dist: cloudpickle>=3.0.0,<4.0.0
Requires-Dist: joblib>=1.4.2,<2.0.0
Requires-Dist: cachetools>=5.5.1 ; extra == 'cache'
Requires-Dist: pyspark>=4.1.3 ; extra == 'spark'
Requires-Dist: pandas>=2.2.3 ; extra == 'spark'
Requires-Dist: pyarrow>=19.0.1 ; extra == 'spark'
Requires-Python: >=3.11, <=3.14
Project-URL: Repository, https://github.com/renard162/tyrannis_optimizer
Project-URL: Issues, https://github.com/renard162/tyrannis_optimizer/issues
Provides-Extra: cache
Provides-Extra: spark
Description-Content-Type: text/markdown

# Tyrannis

**A flexible metaheuristic optimization framework built for diverse search spaces and scalable execution.**

Tyrannis is a Python framework for solving optimization problems with population-based metaheuristic algorithms while keeping the problem definition independent from the execution strategy. Define your search space, choose an optimization algorithm, and decide how the workload should run—from a simple local execution to parallel or distributed processing. Tyrannis also provides support for mixed-variable optimization, allowing continuous, integer, binary, categorical, and permutation variables to coexist in the same problem.

## Installation

### Basic installation

For a local installation with the standard execution capabilities:

```bash
pip install tyrannis
```

This installation provides the core framework, including local execution and the basic LRU and disk caching mechanisms.

### Advanced caching

To enable the additional caching capabilities:

```bash
pip install "tyrannis[cache]"
```

The `cache` extra installs the additional dependencies required by Tyrannis' advanced cache resources. Without this extra, only the basic LRU and disk cache mechanisms are available.

### Distributed processing with Spark

To enable distributed processing with Spark:

```bash
pip install "tyrannis[spark]"
```

This installs the dependencies required by the Spark backend. Distributed execution with Spark requires an appropriate Spark infrastructure to be usable.

### Combining extras

Extras can be installed together:

```bash
pip install "tyrannis[cache,spark]"
```

## Public API

The core optimization requires only three components: an **optimizer**, a **search space**, and an **optimization algorithm**. The processor, backend, and migration components are optional and can be added to control how the optimization is executed, parallelized, distributed, and coordinated.

### Algorithms

`tyrannis.algorithm`

Algorithms are the optimization methods used to search for the best solution within the defined search space.

| Import                | Description                                                                               |
| --------------------- | ----------------------------------------------------------------------------------------- |
| `PSO`                 | Particle Swarm Optimization algorithm for population-based continuous and encoded search. |
| `ArtificialBeeColony` | Artificial Bee Colony algorithm inspired by the foraging behavior of honey bees.          |

### Spaces

`tyrannis.space`

Spaces define the search space of the optimization problem, including the variables, their possible values or boundaries, and the cost function that is optimized.

| Import        | Description                                                                                        |
| ------------- | -------------------------------------------------------------------------------------------------- |
| `Continuous`  | Defines a continuous search space bounded by numerical lower and upper limits.                     |
| `Integer`     | Defines an integer search space bounded by numerical lower and upper limits.                       |
| `Binary`      | Defines a binary search space whose variables can take the values `0` or `1`.                      |
| `Categorical` | Defines a categorical search space based on a finite set of discrete choices.                      |
| `Permutation` | Defines a search space for permutation-based optimization problems.                                |
| `Mixed`       | Combines multiple search spaces, allowing optimization problems with heterogeneous variable types. |

### Processors

`tyrannis.processor`

Processors define how the optimization algorithm is executed on each machine involved in the optimization, including whether particle processing is performed serially or in parallel.

| Import        | Description                                                  |
| ------------- | ------------------------------------------------------------ |
| `Joblib`      | Executes particle processing using Joblib-based parallelism. |
| `ProcessPool` | Executes particle processing using multiple processes.       |
| `ThreadsPool` | Executes particle processing using a pool of threads.        |

### Backends

`tyrannis.backend`

Backends define how the processing of the optimization algorithm is distributed between machines, determining how the optimization workload and population are organized across the available execution resources.

| Import             | Description                                                                                                                             |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `SparkParallel`    | Executes optimization using distributed processing with Spark on a single island.                                                       |
| `SparkDistributed` | Executes optimization using distributed processing with Spark across multiple islands, supporting distributed population and migration. |

### Migrations

`tyrannis.migration`

Migrations define how the machines participating in distributed optimization communicate and exchange information about the optimization process, allowing solutions to move between islands.

| Import            | Description                                                                                     |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| `GlobalBest`      | Shares the globally best solution between islands during distributed optimization.              |
| `IslandMigration` | Provides migration of solutions between islands according to the configured migration strategy. |

## Examples

### Basic optimization

A simple continuous optimization problem can be configured by defining a search space, selecting an algorithm, and creating an optimizer:

```python
from tyrannis import Optimizer
from tyrannis.algorithm import PSO
from tyrannis.space import Continuous


def cost_function(x, y):
    return x**2 + y**2


space = Continuous(
    boundaries={"x": (-10, 10), "y": (-10, 10)},
    cost_function=cost_function
)

algorithm = PSO()

optimizer = Optimizer(
    space=space,
    algorithm=algorithm,
    n_iterations=100,
    n_particles=50
)

optimizer.fit()

print(optimizer.best_solution)
# {"x": 0.0, "y": 0.0}

print(optimizer.best_fitness)
# 0.0
```

### Mixed search space and parallel processing

Tyrannis can combine different variable types in the same optimization problem. In this example, a continuous variable and a categorical variable are optimized together using the Artificial Bee Colony algorithm and a Joblib processor:

```python
from tyrannis import Optimizer
from tyrannis.algorithm import ArtificialBeeColony
from tyrannis.processor import Joblib
from tyrannis.space import Categorical, Continuous, Mixed


def cost_function(x, category):
    category_target = {
        "low": 0.0,
        "medium": 1.0,
        "high": 2.0,
    }
    return (x - category_target[category]) ** 2


space = Mixed(
    spaces={
        "x": Continuous((-5.0, 5.0)),
        "category": Categorical(("low", "medium", "high"))
    },
    cost_function=cost_function
)

algorithm = ArtificialBeeColony()
processor = Joblib(joblib_backend="loky")

optimizer = Optimizer(
    space=space,
    algorithm=algorithm,
    processor=processor,
    n_iterations=100,
    n_particles=50
)

optimizer.fit()

print(optimizer.best_solution)
# {"x": 0.0, "category": "low"}

print(optimizer.best_fitness)
# 0.0
```

In this example, no backend is specified, so the optimization runs locally. The `Joblib` processor parallelizes particle evaluation across the available CPUs.

## Status

Tyrannis is currently in the **alpha stage of development**. The core architecture and initial optimization capabilities are already available, but the API and implementation are still evolving.

The following features are planned for future releases.

### Roadmap

#### Algorithms

* PSOGSA
* Genetic Algorithm
* GSA — Gravitational Search Algorithm
* Differential Evolution
* CMA-ES — Covariance Matrix Adaptation Evolution Strategy
* Ant Colony Optimization
* Grey Wolf Optimization
* Whale Optimization Algorithm

#### Spaces

* Ordinal
* Set
* Graph

#### Backends

* MPI
* Ray
* Dask

#### Migration

* Diffusion

#### Testing

* Construction and maintenance of unit tests
* Construction and maintenance of integration tests
* Increased coverage of algorithms, spaces, processors, backends, and migration strategies
* Validation of distributed execution behavior

## License

Tyrannis is distributed under the BSD 3-Clause License.
