pyecsago 0.1.0__tar.gz

pyecsago-0.1.0/PKG-INFO

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: pyecsago
+Version: 0.1.0
+Summary: Python implementation of the evolutionary clustering ECSAGO - Evolutionary Clustering with Self Adaptive Genetic Operators
+Author: Joan Sebastian Tamayo Rivera
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: numpy>=2.0,<3
+Requires-Dist: matplotlib>=3.9,<4
+Requires-Dist: scikit-learn>=1.5,<2
+Requires-Dist: pandas>=2.2,<3
+Requires-Dist: seaborn>=0.13,<1
+Requires-Dist: scipy>=1.14,<2
+Requires-Dist: tqdm>=4.67,<5
+Requires-Dist: cupy-cuda12x>=13.3.0,<14 ; extra == 'cuda'
+Requires-Python: >=3.12, <4
+Provides-Extra: cuda
+Description-Content-Type: text/markdown
+
+# pyecsago
+
+Python implementation of **ECSAGO** (Evolutionary Clustering with Self-Adaptive Genetic Operators), a robust evolutionary clustering algorithm that automatically discovers the number of clusters in data while being resistant to noise.
+
+![ECSAGO vs K-Means](docs/ecsago_vs_kmeans.png)
+
+## Features
+
+- **Automatic cluster detection** — no need to specify *k* in advance
+- **Noise-robust** density-based fitness function (RBF kernel weights)
+- **Self-adaptive operators** via HAEA (Hybrid Adaptive Evolutionary Algorithm)
+- **Deterministic Crowding** for niche maintenance
+- **MDE refinement** (Maximal Density Estimator) for prototype center/spread convergence
+- **GPU acceleration** — optional CUDA support via CuPy
+
+## Installation
+
+CPU only:
+
+```bash
+pip install pyecsago
+```
+
+With CUDA support:
+
+```bash
+pip install pyecsago[cuda]
+```
+
+### From source
+
+```bash
+git clone https://github.com/pwnaoj/pyecsago
+cd pyecsago
+pip install .
+```
+
+## Quick start
+
+```python
+import numpy as np
+from pyecsago import ECSAGO
+
+# Sample data: 3 Gaussian clusters
+data = np.vstack([
+    np.random.randn(100, 2) + [0, 0],
+    np.random.randn(100, 2) + [5, 5],
+    np.random.randn(100, 2) + [10, 0],
+])
+
+config = {
+    "population_size": 100,
+    "weight_threshold": 0.3,
+    "max_generations": 30,
+    "iterations": 10,
+    "extraction_type": {2: 0.25},   # PROPORTION_MAX with 25% threshold
+    "k": 13.8,
+    "use_cuda": False,
+}
+
+ecsago = ECSAGO(config)
+results = ecsago.run(data)
+
+prototypes = results["refined_prototypes"]
+labels = results["cluster_assignments"]
+
+print(f"Clusters found: {len(prototypes)}")
+```
+
+## Step-by-step usage
+
+For finer control you can invoke each stage independently:
+
+```python
+ecsago = ECSAGO(config)
+
+# 1. Load data
+ecsago.context.set_data(data)
+
+# 2. Evolve the population
+ecsago.evolve()
+
+# 3. Extract prototypes
+prototypes = ecsago.extract_prototypes(
+    extraction_type={2: 0.25},
+    k=13.8,
+)
+
+# 4. Refine with MDE
+refined = ecsago.refine_prototypes(
+    prototypes=prototypes,
+    iterations=10,
+    k=13.8,
+)
+```
+
+## Configuration
+
+All parameters are passed as a dictionary to `ECSAGO(config)`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `population_size` | `int` | Number of individuals in the evolutionary population |
+| `weight_threshold` | `float` | Threshold for weight binarization (0–1) |
+| `max_generations` | `int` | Maximum number of evolutionary generations |
+| `iterations` | `int` | Number of MDE refinement iterations |
+| `extraction_type` | `dict` | Extraction method — key is the type (0–4), value is the threshold |
+| `k` | `float` | Chi-squared factor for minimum inter-prototype distance |
+| `use_cuda` | `bool` | Enable CUDA/GPU acceleration via CuPy |
+
+### Extraction types
+
+| Key | Method | Threshold meaning |
+|---|---|---|
+| 0 | `ABSOLUTE_VALUE` | Absolute fitness threshold (auto-calculated) |
+| 1 | `PROPORTION_AVG` | Proportion of average fitness |
+| 2 | `PROPORTION_MAX` | Proportion of maximum fitness |
+| 3 | `PROPORTION_MEDIAN` | Proportion of median fitness |
+| 4 | `MINIMUM_DENSITY` | Based on minimum density |
+
+## Output
+
+`ecsago.run(data)` returns a dictionary:
+
+| Key | Description |
+|---|---|
+| `final_population` | Full evolved population |
+| `prototypes` | Extracted prototypes (before refinement) |
+| `refined_prototypes` | Refined prototypes (after MDE) |
+| `cluster_assignments` | Cluster label for each data point |
+
+Each prototype is an `ECSAGOIndividual` with attributes `genome` (center), `sigma2` (spread), and `fitness`.
+
+## Architecture
+
+```
+pyecsago/
+├── core/               # Abstract base classes and exceptions
+├── implementations/
+│   └── ecsago/         # ECSAGO algorithm, context, individual, population
+├── strategies/
+│   ├── evolution/      # Evolution strategy (HAEA + Deterministic Crowding)
+│   ├── extraction/     # Prototype extraction (fitness, niche, composite)
+│   ├── fitness/        # Fitness calculation (CPU and CUDA)
+│   ├── niching/        # Deterministic Crowding
+│   ├── operators/      # Genetic operators (mutation, crossover, HAEA)
+│   └── refinement/     # MDE refinement (CPU and CUDA)
+└── utils/              # Data type strategies, compatibility, utilities
+```
+
+## License
+
+**pyecsago** was created by Joan Sebastian Tamayo Rivera. It is licensed under the terms of the MIT license.
+
+## References
+
+- León, E. *"Scalable and Adaptive Evolutionary Clustering for Noisy and Dynamic Data"*
+- León, E., Nasraoui, O., & Gómez, J. *"ECSAGO: Evolutionary Clustering with Self-Adaptive Genetic Operators"*
+- Gómez, J. *"Self Adaptation of Operator Rates for Multimodal Optimization"*
+- Tamayo, J. *"GPU/CUDA-Based Parallelization of the ECSAGO Evolutionary Algorithm"*

pyecsago-0.1.0/README.md

@@ -0,0 +1,160 @@
+# pyecsago
+
+Python implementation of **ECSAGO** (Evolutionary Clustering with Self-Adaptive Genetic Operators), a robust evolutionary clustering algorithm that automatically discovers the number of clusters in data while being resistant to noise.
+
+![ECSAGO vs K-Means](docs/ecsago_vs_kmeans.png)
+
+## Features
+
+- **Automatic cluster detection** — no need to specify *k* in advance
+- **Noise-robust** density-based fitness function (RBF kernel weights)
+- **Self-adaptive operators** via HAEA (Hybrid Adaptive Evolutionary Algorithm)
+- **Deterministic Crowding** for niche maintenance
+- **MDE refinement** (Maximal Density Estimator) for prototype center/spread convergence
+- **GPU acceleration** — optional CUDA support via CuPy
+
+## Installation
+
+CPU only:
+
+```bash
+pip install pyecsago
+```
+
+With CUDA support:
+
+```bash
+pip install pyecsago[cuda]
+```
+
+### From source
+
+```bash
+git clone https://github.com/pwnaoj/pyecsago
+cd pyecsago
+pip install .
+```
+
+## Quick start
+
+```python
+import numpy as np
+from pyecsago import ECSAGO
+
+# Sample data: 3 Gaussian clusters
+data = np.vstack([
+    np.random.randn(100, 2) + [0, 0],
+    np.random.randn(100, 2) + [5, 5],
+    np.random.randn(100, 2) + [10, 0],
+])
+
+config = {
+    "population_size": 100,
+    "weight_threshold": 0.3,
+    "max_generations": 30,
+    "iterations": 10,
+    "extraction_type": {2: 0.25},   # PROPORTION_MAX with 25% threshold
+    "k": 13.8,
+    "use_cuda": False,
+}
+
+ecsago = ECSAGO(config)
+results = ecsago.run(data)
+
+prototypes = results["refined_prototypes"]
+labels = results["cluster_assignments"]
+
+print(f"Clusters found: {len(prototypes)}")
+```
+
+## Step-by-step usage
+
+For finer control you can invoke each stage independently:
+
+```python
+ecsago = ECSAGO(config)
+
+# 1. Load data
+ecsago.context.set_data(data)
+
+# 2. Evolve the population
+ecsago.evolve()
+
+# 3. Extract prototypes
+prototypes = ecsago.extract_prototypes(
+    extraction_type={2: 0.25},
+    k=13.8,
+)
+
+# 4. Refine with MDE
+refined = ecsago.refine_prototypes(
+    prototypes=prototypes,
+    iterations=10,
+    k=13.8,
+)
+```
+
+## Configuration
+
+All parameters are passed as a dictionary to `ECSAGO(config)`.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `population_size` | `int` | Number of individuals in the evolutionary population |
+| `weight_threshold` | `float` | Threshold for weight binarization (0–1) |
+| `max_generations` | `int` | Maximum number of evolutionary generations |
+| `iterations` | `int` | Number of MDE refinement iterations |
+| `extraction_type` | `dict` | Extraction method — key is the type (0–4), value is the threshold |
+| `k` | `float` | Chi-squared factor for minimum inter-prototype distance |
+| `use_cuda` | `bool` | Enable CUDA/GPU acceleration via CuPy |
+
+### Extraction types
+
+| Key | Method | Threshold meaning |
+|---|---|---|
+| 0 | `ABSOLUTE_VALUE` | Absolute fitness threshold (auto-calculated) |
+| 1 | `PROPORTION_AVG` | Proportion of average fitness |
+| 2 | `PROPORTION_MAX` | Proportion of maximum fitness |
+| 3 | `PROPORTION_MEDIAN` | Proportion of median fitness |
+| 4 | `MINIMUM_DENSITY` | Based on minimum density |
+
+## Output
+
+`ecsago.run(data)` returns a dictionary:
+
+| Key | Description |
+|---|---|
+| `final_population` | Full evolved population |
+| `prototypes` | Extracted prototypes (before refinement) |
+| `refined_prototypes` | Refined prototypes (after MDE) |
+| `cluster_assignments` | Cluster label for each data point |
+
+Each prototype is an `ECSAGOIndividual` with attributes `genome` (center), `sigma2` (spread), and `fitness`.
+
+## Architecture
+
+```
+pyecsago/
+├── core/               # Abstract base classes and exceptions
+├── implementations/
+│   └── ecsago/         # ECSAGO algorithm, context, individual, population
+├── strategies/
+│   ├── evolution/      # Evolution strategy (HAEA + Deterministic Crowding)
+│   ├── extraction/     # Prototype extraction (fitness, niche, composite)
+│   ├── fitness/        # Fitness calculation (CPU and CUDA)
+│   ├── niching/        # Deterministic Crowding
+│   ├── operators/      # Genetic operators (mutation, crossover, HAEA)
+│   └── refinement/     # MDE refinement (CPU and CUDA)
+└── utils/              # Data type strategies, compatibility, utilities
+```
+
+## License
+
+**pyecsago** was created by Joan Sebastian Tamayo Rivera. It is licensed under the terms of the MIT license.
+
+## References
+
+- León, E. *"Scalable and Adaptive Evolutionary Clustering for Noisy and Dynamic Data"*
+- León, E., Nasraoui, O., & Gómez, J. *"ECSAGO: Evolutionary Clustering with Self-Adaptive Genetic Operators"*
+- Gómez, J. *"Self Adaptation of Operator Rates for Multimodal Optimization"*
+- Tamayo, J. *"GPU/CUDA-Based Parallelization of the ECSAGO Evolutionary Algorithm"*

pyecsago-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "pyecsago"
+version = "0.1.0"
+description = "Python implementation of the evolutionary clustering ECSAGO - Evolutionary Clustering with Self Adaptive Genetic Operators"
+authors = [{ name = "Joan Sebastian Tamayo Rivera" }]
+requires-python = ">=3.12,<4"
+readme = "README.md"
+license = "MIT"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "numpy>=2.0,<3",
+    "matplotlib>=3.9,<4",
+    "scikit-learn>=1.5,<2",
+    "pandas>=2.2,<3",
+    "seaborn>=0.13,<1",
+    "scipy>=1.14,<2",
+    "tqdm>=4.67,<5",
+]
+
+[project.optional-dependencies]
+cuda = ["cupy-cuda12x>=13.3.0,<14"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0,<9",
+    "pytest-cov>=6.0,<7",
+]
+docs = [
+    "mkdocs-material>=9.6,<10",
+    "mkdocstrings[python]>=0.29,<1",
+    "mkdocs-jupyter>=0.25,<1",
+    "mkdocs-include-markdown-plugin>=7.0,<8",
+]
+
+[tool.uv]
+default-groups = "all"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["pyecsago"]
+omit = [
+    "src/pyecsago/utils/cuda/*",
+    "src/pyecsago/strategies/refinement/cuda_mde.py",
+]
+
+[tool.coverage.report]
+exclude_also = [
+    "if TYPE_CHECKING:",
+    "@abstractmethod",
+    "pass$",
+    "raise NotImplementedError",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.21,<0.10.0"]
+build-backend = "uv_build"

pyecsago-0.1.0/src/pyecsago/__init__.py

@@ -0,0 +1,31 @@
+# read version from installed package
+from importlib.metadata import version
+__version__ = version("pyecsago")
+
+# import features
+from .implementations.ecsago.algorithm import ECSAGO
+from .core.algorithm import EvolutionaryAlgorithm
+from .strategies.evolution.factory import ECSAGOStrategyFactory
+from .strategies.evolution.ecsago import ECSAGOStrategy
+from .implementations.ecsago.population import ECSAGOPopulation
+from .implementations.ecsago.individual import ECSAGOIndividual
+from .strategies.fitness.ecsago import ECSAGOFitnessCalculator, CUDAECSAGOFitnessCalculator
+from .strategies.operators.crossover import LinearCrossoverPerDimension
+from .strategies.operators.mutation import AdaptiveGaussianMutation, GaussianMutation
+from .strategies.niching.deterministic_crowding import DeterministicCrowding
+from .strategies.operators.haea import HAEA
+__all__ = [
+    'ECSAGO',
+    'EvolutionaryAlgorithm',
+    'ECSAGOStrategyFactory',
+    'ECSAGOStrategy',
+    'ECSAGOPopulation',
+    'ECSAGOIndividual',
+    'ECSAGOFitnessCalculator',
+    'CUDAECSAGOFitnessCalculator',
+    'LinearCrossoverPerDimension',
+    'AdaptiveGaussianMutation',
+    'GaussianMutation',
+    'DeterministicCrowding',
+    'HAEA'
+]

pyecsago-0.1.0/src/pyecsago/core/__init__.py

@@ -0,0 +1,16 @@
+from .algorithm import EvolutionaryAlgorithm
+from .context import AlgorithmContext
+from .individual import BaseIndividual
+from .population import BasePopulation
+from .exceptions import PyECSAGOError, ValidationError, ConfigurationError, EvolutionError
+
+__all__ = [
+    'EvolutionaryAlgorithm',
+    'AlgorithmContext',
+    'BaseIndividual',
+    'BasePopulation',
+    'PyECSAGOError',
+    'ValidationError',
+    'ConfigurationError',
+    'EvolutionError',
+]

pyecsago-0.1.0/src/pyecsago/core/algorithm.py

@@ -0,0 +1,46 @@
+"""Base class for evolutionary algorithms."""
+
+from abc import ABC, abstractmethod
+
+
+class EvolutionaryAlgorithm(ABC):
+    """Abstract base class defining the evolutionary algorithm interface.
+
+    Subclasses must implement evolve, extract_prototypes, and refine_prototypes.
+    """
+
+    def __init__(self, config: dict):
+        """Initializes the algorithm with configuration.
+
+        Args:
+            config: Algorithm configuration dictionary.
+        """
+        self.config: dict = config
+        self.use_cuda: bool = config.get('use_cuda', False)
+
+    @abstractmethod
+    def evolve(self, max_generations: int = 100):
+        """Runs the main evolutionary loop.
+
+        Args:
+            max_generations: Maximum number of generations.
+        """
+        pass
+
+    @abstractmethod
+    def extract_prototypes(self):
+        """Extracts final prototypes from the evolved population."""
+        pass
+
+    @abstractmethod
+    def refine_prototypes(self, prototypes, iterations: int = 10):
+        """Refines extracted prototypes.
+
+        Args:
+            prototypes: Prototypes to refine.
+            iterations: Number of refinement iterations.
+
+        Returns:
+            List of refined prototypes.
+        """
+        pass

pyecsago-0.1.0/src/pyecsago/core/context.py

@@ -0,0 +1,80 @@
+"""Abstract context interface for evolutionary algorithms."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pyecsago.utils.data_types import DataTypeStrategy
+
+
+class AlgorithmContext(ABC):
+    """Abstract context managing data, type strategy, and CUDA resources."""
+
+    @property
+    @abstractmethod
+    def dtype_strategy(self) -> DataTypeStrategy:
+        """Returns the data type strategy (NumPy/CuPy)."""
+        pass
+
+    @property
+    @abstractmethod
+    def use_cuda(self) -> bool:
+        """Returns whether CUDA is enabled."""
+        pass
+
+    @property
+    @abstractmethod
+    def cuda_context(self) -> Any | None:
+        """Returns the CUDA context, or None if not available."""
+        pass
+
+    @abstractmethod
+    def _initialize_sigma_limits(self) -> None:
+        """Initializes sigma2 bounds based on current data."""
+        pass
+
+    @abstractmethod
+    def get_sigma2_max(self) -> Any:
+        """Returns the maximum allowed sigma2 value."""
+        pass
+
+    @abstractmethod
+    def get_sigma2_min(self) -> Any:
+        """Returns the minimum allowed sigma2 value."""
+        pass
+
+    @abstractmethod
+    def get_sigma2_initial(self) -> Any:
+        """Returns the initial sigma2 value for new individuals."""
+        pass
+
+    @abstractmethod
+    def set_data(self, data: Any) -> None:
+        """Sets the dataset in the context.
+
+        Args:
+            data: Dataset to set.
+        """
+        pass
+
+    @abstractmethod
+    def get_data(self) -> Any:
+        """Returns the current dataset."""
+        pass
+
+    @abstractmethod
+    def execute(self, func: Callable, *args: Any, **kwargs: Any) -> Any:
+        """Executes a function in the appropriate context (CPU/GPU).
+
+        Args:
+            func: Function to execute.
+            *args: Positional arguments.
+            **kwargs: Keyword arguments.
+
+        Returns:
+            Function result.
+        """
+        pass

pyecsago-0.1.0/src/pyecsago/core/exceptions.py

@@ -0,0 +1,21 @@
+"""Custom exception hierarchy for PyECSAGO."""
+
+
+class PyECSAGOError(Exception):
+    """Base exception for the PyECSAGO project."""
+    pass
+
+
+class ValidationError(PyECSAGOError, ValueError):
+    """Raised when data or parameter validation fails."""
+    pass
+
+
+class ConfigurationError(PyECSAGOError, ValueError):
+    """Raised when algorithm configuration is invalid."""
+    pass
+
+
+class EvolutionError(PyECSAGOError, RuntimeError):
+    """Raised when an error occurs during the evolutionary process."""
+    pass

pyecsago-0.1.0/src/pyecsago/core/individual.py

@@ -0,0 +1,33 @@
+"""Base class for population individuals."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from abc import ABC, abstractmethod
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import cupy as cp
+
+
+class BaseIndividual(ABC):
+    """Abstract base class for a population individual."""
+
+    def __init__(self, genome: np.ndarray | cp.ndarray, sigma2: np.ndarray | cp.ndarray, **kwargs: Any) -> None:
+        self.genome = genome
+        self.sigma2 = sigma2
+        self.fitness = 0.0
+
+    @abstractmethod
+    def calculate_fitness(self, data: np.ndarray, **kwargs: Any) -> None:
+        """Calculates the individual's fitness."""
+        pass
+
+    def clone(self) -> BaseIndividual:
+        """Creates a copy of the individual.
+
+        Raises:
+            NotImplementedError: Subclasses must override this method.
+        """
+        raise NotImplementedError("Subclasses must override clone()")

pyecsago-0.1.0/src/pyecsago/core/population.py

@@ -0,0 +1,17 @@
+"""Base class for populations."""
+
+from abc import ABC, abstractmethod
+
+
+class BasePopulation(ABC):
+    """Abstract base class for a population of individuals."""
+
+    @abstractmethod
+    def evaluate_population(self):
+        """Evaluates fitness for all individuals in the population."""
+        pass
+
+    @abstractmethod
+    def evolve(self):
+        """Evolves the population to the next generation."""
+        pass

pyecsago-0.1.0/src/pyecsago/implementations/ecsago/__init__.py

@@ -0,0 +1,11 @@
+from .algorithm import ECSAGO
+from .context import StandardAlgorithmContext
+from .individual import ECSAGOIndividual
+from .population import ECSAGOPopulation
+
+__all__ = [
+    'ECSAGO',
+    'StandardAlgorithmContext',
+    'ECSAGOIndividual',
+    'ECSAGOPopulation',
+]