Metadata-Version: 2.5
Name: sceua
Version: 0.2.0
Summary: Shuffled Complex Evolution (SCE-UA) global optimization for model calibration.
Project-URL: Changelog, https://github.com/cheginit/sceua/releases
Project-URL: CI, https://github.com/cheginit/sceua/actions
Project-URL: Documentation, https://cheginit.github.io/sceua/
Project-URL: Homepage, https://github.com/cheginit/sceua
Project-URL: Issues, https://github.com/cheginit/sceua/issues
Author-email: Taher Chegini <cheginit@gmail.com>
License: MIT
License-File: AUTHORS.md
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: numpy>=2
Requires-Dist: scipy>=1.15
Description-Content-Type: text/markdown

# SCE-UA: Shuffle Complex Evolution Algorithm for Optimization

[![PyPi](https://img.shields.io/pypi/v/sceua.svg)](https://pypi.python.org/pypi/sceua)
[![Conda Version](https://img.shields.io/conda/vn/conda-forge/sceua.svg)](https://anaconda.org/conda-forge/sceua)
[![CodeCov](https://codecov.io/gh/cheginit/sceua/branch/main/graph/badge.svg)](https://codecov.io/gh/cheginit/sceua)
[![Python Versions](https://img.shields.io/pypi/pyversions/sceua.svg)](https://pypi.python.org/pypi/sceua)
[![Downloads](https://static.pepy.tech/badge/sceua)](https://pepy.tech/project/sceua)

[![CodeFactor](https://www.codefactor.io/repository/github/cheginit/sceua/badge)](https://www.codefactor.io/repository/github/cheginit/sceua)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/cheginit/sceua/HEAD?labpath=docs%2Fexamples)
[![CodSpeed Badge](https://img.shields.io/endpoint?url=https://codspeed.io/badge.json)](https://codspeed.io/cheginit/sceua)

SCE-UA is a lightweight Python package implementing the Shuffled Complex Evolution
(SCE-UA) algorithm for global optimization. Designed primarily for hydrological model
calibration, it leverages NumPy and SciPy for efficient computation and seamless
integration into Python workflows.

Full documentation is available at
[cheginit.github.io/sceua](https://cheginit.github.io/sceua/).

## 🌟 Features

This implementation of the **SCE-UA** algorithm incorporates several major improvements
from the literature over the original 1994 version. These enhancements include:

- **Adaptive smoothing parameter (θ)** that adjusts based on problem scale, improving
    numerical stability and convergence.
- **Latin Hypercube Sampling (LHS)** for initial population generation, ensuring better
    parameter space coverage compared to uniform random sampling.
- **PCA-based recovery mechanism** to detect and restore lost dimensions in the
    population.
- **Best solution inclusion** in every complex to accelerate convergence.
- **Optimized complex evolution strategy** with enhanced reflection, contraction, and
    mutation operations.
- **Automatic parameter determination** with sensible defaults based on problem
    dimensionality.
- **Scale-free stopping rules**: a run ends when neither the best value nor the
    population median improves for a number of iterations, when every parameter's range
    shrinks below a fraction of its bounds, or at an iteration or evaluation budget.

Additionally, the package offers:

- **Multithreading support** for parallel objective function evaluations using
    threading.
- **Detailed results object** providing in-depth insights into the optimization process
    suitable for further analysis and visualization.
- **Type hinting and modern Python implementation**, ensuring maintainability and
    adherence to best coding practices.

## 📦 Installation

Choose your preferred installation method:

### Using `pip`

```console
pip install sceua
```

### Using `micromamba` (recommended)

```console
micromamba install -c conda-forge sceua
```

Alternatively, you can use `conda` or `mamba`.

## 🚀 Quick Start Guide

The SCE-UA package has one main function called `minimize`, which is used to optimize a
given objective function. The API follows a similar pattern to `scipy.optimize.minimize`
for easy adoption.

### Key Parameters

The most important tuning parameters are **`n_complexes`** and **`n_points_complex`**
for all cases, while **`pca_freq`** and **`pca_tol`** are particularly relevant for
problems with highly correlated parameters and/or high dimensionality. Default values
are set to reasonable standards, but you can adjust them as needed for your specific
problem.

For more details, refer to the [API reference](https://cheginit.github.io/sceua/api/).

### Example Usage

The signature for the objective function can be either:

```python
def objective(params: FloatArray) -> float:
    """Objective function to minimize."""
    # Your implementation here
```

or

```python
def objective(params: FloatArray, *args: Any) -> float:
    """Objective function to minimize."""
    # Your implementation here
```

where `params` is a NumPy array of parameters to optimize, and `args` is a tuple of
additional arguments to pass to the objective function. The function should return a
single floating-point value representing the objective function value.

Here's a simple example of how to use the package:

```python
from typing import Any
import numpy as np
from numpy.typing import NDArray

import sceua

FloatArray = NDArray[np.floating[Any]]


def objective(params: FloatArray, *args: Any) -> float:
    """Objective function to minimize."""
    sim_arg1, sim_arg2, obs = args
    sim = simulation_func(params, sim_arg1, sim_arg2)
    return metric_func(sim, obs)


# Define parameter bounds as a sequence of (min, max) pairs
bounds = [(lower1, upper1), (lower2, upper2), ..., (lowerN, upperN)]

# Run optimization
result = sceua.minimize(objective, bounds, args=(sim_arg1, sim_arg2, obs), seed=42, max_workers=8)

# Access the optimization results
best_params = result.x
best_function_value = result.fun
num_iterations = result.nit
num_function_evaluations = result.nfev
```

### Result Object

The `result` object contains the following attributes:

- `x` (`numpy.ndarray`): Best parameters found.
- `fun` (`float`): Best function value corresponding to the best parameters.
- `nit` (`int`): Number of iterations.
- `nfev` (`int`): Number of function evaluations.
- `message` (`str`): Message describing the termination reason.
- `success` (`bool`): Whether the optimization was successful.
- `xv` (`numpy.ndarray`): All evaluated parameter sets.
- `funv` (`numpy.ndarray`): Function values for all evaluated parameter sets.

### Visualization

The result attributes can be used to create convergence plots and analyze optimization
performance:

```python
import matplotlib.pyplot as plt


_, ax1 = plt.subplots()
ax1.plot(np.minimum.accumulate(results.funv))
ax2 = ax1.twinx()
ax2.set_yscale("log")
ax2.plot(np.cumsum(results.funv - true_min), color="r")
```

![Convergence](https://raw.githubusercontent.com/cheginit/sceua/main/docs/examples/images/convergence.png)

Check the [docs](https://cheginit.github.io/sceua/) for more examples and API details.

## 📚 References

This package is based on the following references:

- Duan, Q., Sorooshian, S., & Gupta, V. K. (1992). Effective and efficient global
    optimization for conceptual rainfall-runoff models. Water Resources Research, 28(4),
    1015-1031. [doi:10.1029/91WR02985](https://doi.org/10.1029/91WR02985)
- Duan, Q., Gupta, V. K., & Sorooshian, S. (1994). Optimal use of the SCE-UA global
    optimization method for calibrating watershed models. Journal of Hydrology,
    158(3-4), 265-284.
    [doi:10.1016/0022-1694(94)90057-4](<https://doi.org/10.1016/0022-1694(94)90057-4>)
- Duan, Q., Sorooshian, S., & Gupta, V. K. (1994). A shuffled complex evolution approach
    for effective and efficient global minimization. Journal of optimization theory and
    applications, 76(3), 501-521.
    [doi:10.1007/BF00939380](https://doi.org/10.1007/BF00939380)
- Muttil, N., & Jayawardena, A. W. (2008). Shuffled Complex Evolution model calibrating
    algorithm: enhancing its robustness and efficiency. Hydrological Processes, 22(23),
    4628-4638. Portico. [doi:10.1002/hyp.7082](https://doi.org/10.1002/hyp.7082)
- Chu, W., Gao, X., & Sorooshian, S. (2010). Improving the shuffled complex evolution
    scheme for optimization of complex nonlinear hydrological systems: Application to
    the calibration of the Sacramento soil-moisture accounting model. Water Resources
    Research, 46(9). Portico.
    [doi:10.1029/2010wr009224](https://doi.org/10.1029/2010wr009224)

Additionally, some ideas were inspired by [UQPyL](https://github.com/smasky/UQPyL) and
[SAMBO](https://github.com/sambo-optimization/sambo) Python packages.

## 🤝 Contributing

We welcome contributions! Please see the
[contributing](https://cheginit.github.io/sceua/contributing/) section for guidelines
and instructions.

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.
