ikn-library 0.1.0__tar.gz

ikn_library-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check src tests
+
+      - name: Run tests
+        run: pytest

ikn_library-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,60 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: |
+          pip install build
+          python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ikn-library
+    permissions:
+      id-token: write  # required for PyPI Trusted Publishing (OIDC)
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

ikn_library-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.DS_Store

ikn_library-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isman Kurniawan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ikn_library-0.1.0/PKG-INFO

@@ -0,0 +1,120 @@
+Metadata-Version: 2.5
+Name: ikn-library
+Version: 0.1.0
+Summary: Nature-inspired metaheuristic algorithms for feature selection and parameter optimization
+Project-URL: Homepage, https://github.com/ismankrn/ikn-library
+Author-email: Isman Kurniawan <isman.krn@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ant-colony-optimization,feature-selection,hyperparameter-optimization,metaheuristic,optimization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: scikit-learn>=1.3; extra == 'dev'
+Provides-Extra: ml
+Requires-Dist: scikit-learn>=1.3; extra == 'ml'
+Description-Content-Type: text/markdown
+
+# ikn-library
+
+Nature-inspired metaheuristic algorithms for continuous optimization, feature
+selection, and parameter optimization — focusing on algorithms not yet
+available in [NiaPy](https://github.com/NiaOrg/NiaPy), starting with
+**Ant Colony Optimization for continuous domains (ACO-R)**.
+
+## Installation
+
+```bash
+pip install ikn-library
+```
+
+Or from source (development mode):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from ikn_library import Task
+from ikn_library.problems import Sphere
+from ikn_library.algorithms import AntColonyOptimization
+
+task = Task(problem=Sphere(dimension=10), max_evals=10000)
+algo = AntColonyOptimization(population_size=30, archive_size=50, seed=42)
+best_x, best_fitness = algo.run(task)
+
+print("Best fitness:", best_fitness)
+print("Best solution:", best_x)
+```
+
+## Custom problems
+
+Subclass `Problem` and implement `_evaluate` — for example, a
+cross-validation score for hyperparameter optimization:
+
+```python
+import numpy as np
+from ikn_library.problems import Problem
+
+class MyProblem(Problem):
+    def __init__(self, dimension=10):
+        super().__init__(dimension, lower=-10.0, upper=10.0)
+
+    def _evaluate(self, x):
+        return float(np.sum(np.abs(x)))
+```
+
+Use `OptimizationType.MAXIMIZATION` in the `Task` when higher is better
+(e.g. accuracy).
+
+## Feature selection
+
+Wrapper-based feature selection with a scikit-learn estimator
+(`pip install ikn-library[ml]`):
+
+```python
+from sklearn.datasets import load_breast_cancer
+
+from ikn_library import Task
+from ikn_library.problems import FeatureSelectionProblem
+from ikn_library.algorithms import BinaryAntColonyOptimization
+
+X, y = load_breast_cancer(return_X_y=True)
+problem = FeatureSelectionProblem(X, y, cv=5, alpha=0.99)
+task = Task(problem=problem, max_evals=1000)
+algo = BinaryAntColonyOptimization(population_size=20, seed=42)
+best_x, best_fitness = algo.run(task)
+
+print("Selected features:", problem.selected_features(best_x))
+```
+
+The fitness balances the cross-validated score against the subset size:
+`alpha * (1 - cv_score) + (1 - alpha) * n_selected / n_features`.
+
+## Algorithms
+
+| Algorithm | Class | Domain | Reference |
+|---|---|---|---|
+| Ant Colony Optimization (ACO-R) | `AntColonyOptimization` | continuous | Socha & Dorigo, EJOR 185(3), 2008 |
+| Binary Ant Colony Optimization | `BinaryAntColonyOptimization` | binary / subsets | hyper-cube pheromone update |
+
+More algorithms are planned.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

ikn_library-0.1.0/README.md

@@ -0,0 +1,97 @@
+# ikn-library
+
+Nature-inspired metaheuristic algorithms for continuous optimization, feature
+selection, and parameter optimization — focusing on algorithms not yet
+available in [NiaPy](https://github.com/NiaOrg/NiaPy), starting with
+**Ant Colony Optimization for continuous domains (ACO-R)**.
+
+## Installation
+
+```bash
+pip install ikn-library
+```
+
+Or from source (development mode):
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Quick start
+
+```python
+from ikn_library import Task
+from ikn_library.problems import Sphere
+from ikn_library.algorithms import AntColonyOptimization
+
+task = Task(problem=Sphere(dimension=10), max_evals=10000)
+algo = AntColonyOptimization(population_size=30, archive_size=50, seed=42)
+best_x, best_fitness = algo.run(task)
+
+print("Best fitness:", best_fitness)
+print("Best solution:", best_x)
+```
+
+## Custom problems
+
+Subclass `Problem` and implement `_evaluate` — for example, a
+cross-validation score for hyperparameter optimization:
+
+```python
+import numpy as np
+from ikn_library.problems import Problem
+
+class MyProblem(Problem):
+    def __init__(self, dimension=10):
+        super().__init__(dimension, lower=-10.0, upper=10.0)
+
+    def _evaluate(self, x):
+        return float(np.sum(np.abs(x)))
+```
+
+Use `OptimizationType.MAXIMIZATION` in the `Task` when higher is better
+(e.g. accuracy).
+
+## Feature selection
+
+Wrapper-based feature selection with a scikit-learn estimator
+(`pip install ikn-library[ml]`):
+
+```python
+from sklearn.datasets import load_breast_cancer
+
+from ikn_library import Task
+from ikn_library.problems import FeatureSelectionProblem
+from ikn_library.algorithms import BinaryAntColonyOptimization
+
+X, y = load_breast_cancer(return_X_y=True)
+problem = FeatureSelectionProblem(X, y, cv=5, alpha=0.99)
+task = Task(problem=problem, max_evals=1000)
+algo = BinaryAntColonyOptimization(population_size=20, seed=42)
+best_x, best_fitness = algo.run(task)
+
+print("Selected features:", problem.selected_features(best_x))
+```
+
+The fitness balances the cross-validated score against the subset size:
+`alpha * (1 - cv_score) + (1 - alpha) * n_selected / n_features`.
+
+## Algorithms
+
+| Algorithm | Class | Domain | Reference |
+|---|---|---|---|
+| Ant Colony Optimization (ACO-R) | `AntColonyOptimization` | continuous | Socha & Dorigo, EJOR 185(3), 2008 |
+| Binary Ant Colony Optimization | `BinaryAntColonyOptimization` | binary / subsets | hyper-cube pheromone update |
+
+More algorithms are planned.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

ikn_library-0.1.0/examples/feature_selection.py

@@ -0,0 +1,29 @@
+"""Example: feature selection on the breast-cancer dataset with Binary ACO.
+
+Requires scikit-learn: pip install ikn-library[ml]
+"""
+
+from sklearn.datasets import load_breast_cancer
+from sklearn.model_selection import cross_val_score
+from sklearn.neighbors import KNeighborsClassifier
+
+from ikn_library import Task
+from ikn_library.problems import FeatureSelectionProblem
+from ikn_library.algorithms import BinaryAntColonyOptimization
+
+data = load_breast_cancer()
+X, y = data.data, data.target
+estimator = KNeighborsClassifier(n_neighbors=5)
+
+problem = FeatureSelectionProblem(X, y, estimator=estimator, cv=5, alpha=0.99)
+task = Task(problem=problem, max_evals=1000)
+algo = BinaryAntColonyOptimization(population_size=20, evaporation=0.1, seed=42)
+best_x, best_fitness = algo.run(task)
+
+selected = problem.selected_features(best_x)
+baseline = cross_val_score(estimator, X, y, cv=5).mean()
+score = cross_val_score(estimator, X[:, selected], y, cv=5).mean()
+
+print(f"All {X.shape[1]} features : accuracy = {baseline:.4f}")
+print(f"Selected {len(selected)} features: accuracy = {score:.4f}")
+print("Selected feature names:", list(data.feature_names[selected]))

ikn_library-0.1.0/examples/run_aco.py

@@ -0,0 +1,12 @@
+"""Example: minimize benchmark functions with Ant Colony Optimization."""
+
+from ikn_library import Task
+from ikn_library.problems import Ackley, Rastrigin, Sphere
+from ikn_library.algorithms import AntColonyOptimization
+
+for problem_cls in (Sphere, Rastrigin, Ackley):
+    task = Task(problem=problem_cls(dimension=10), max_evals=20000)
+    algo = AntColonyOptimization(population_size=30, archive_size=50, seed=42)
+    best_x, best_fitness = algo.run(task)
+    print(f"{problem_cls.__name__:>10}: best fitness = {best_fitness:.6g} "
+          f"({task.evals} evals, {task.iters} iters)")

ikn_library-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ikn-library"
+version = "0.1.0"
+description = "Nature-inspired metaheuristic algorithms for feature selection and parameter optimization"
+readme = "README.md"
+license = "MIT"
+authors = [{ name = "Isman Kurniawan", email = "isman.krn@gmail.com" }]
+requires-python = ">=3.9"
+keywords = [
+    "optimization",
+    "metaheuristic",
+    "ant-colony-optimization",
+    "feature-selection",
+    "hyperparameter-optimization",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "numpy>=1.24",
+]
+
+[project.optional-dependencies]
+ml = [
+    "scikit-learn>=1.3",
+]
+dev = [
+    "pytest>=7.0",
+    "ruff",
+    "scikit-learn>=1.3",
+]
+
+[project.urls]
+Homepage = "https://github.com/ismankrn/ikn-library"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ikn_library"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

ikn_library-0.1.0/src/ikn_library/__init__.py

@@ -0,0 +1,18 @@
+"""ikn_library: nature-inspired metaheuristic algorithms.
+
+Metaheuristic algorithms for continuous optimization, feature selection,
+and parameter optimization, following a NiaPy-like workflow:
+
+    >>> from ikn_library import Task
+    >>> from ikn_library.problems import Sphere
+    >>> from ikn_library.algorithms import AntColonyOptimization
+    >>> task = Task(problem=Sphere(dimension=10), max_evals=10000)
+    >>> algo = AntColonyOptimization(population_size=30, seed=42)
+    >>> best_x, best_fitness = algo.run(task)
+"""
+
+from ikn_library.task import OptimizationType, Task
+
+__version__ = "0.1.0"
+
+__all__ = ["OptimizationType", "Task", "__version__"]

ikn_library-0.1.0/src/ikn_library/algorithms/__init__.py

@@ -0,0 +1,7 @@
+"""Metaheuristic algorithms."""
+
+from ikn_library.algorithms.aco import AntColonyOptimization
+from ikn_library.algorithms.algorithm import Algorithm
+from ikn_library.algorithms.binary_aco import BinaryAntColonyOptimization
+
+__all__ = ["Algorithm", "AntColonyOptimization", "BinaryAntColonyOptimization"]

ikn_library-0.1.0/src/ikn_library/algorithms/aco.py

@@ -0,0 +1,76 @@
+"""Ant Colony Optimization for continuous domains (ACO-R).
+
+Reference:
+    K. Socha and M. Dorigo, "Ant colony optimization for continuous
+    domains," European Journal of Operational Research, 185(3), 2008.
+"""
+
+import numpy as np
+
+from ikn_library.algorithms.algorithm import Algorithm
+
+
+class AntColonyOptimization(Algorithm):
+    """ACO-R: Ant Colony Optimization for continuous search spaces.
+
+    Keeps an archive of the best solutions found so far. Each ant builds
+    a new solution by picking a guide solution from the archive (better
+    solutions are picked with higher probability) and sampling each
+    coordinate from a Gaussian centered on the guide. The Gaussian width
+    shrinks as the archive converges, balancing exploration and
+    exploitation — the archive plays the role of the pheromone trail.
+
+    Args:
+        population_size: Number of ants (new solutions) per iteration.
+        archive_size: Number of solutions kept in the archive (k).
+        intensification: Locality of search (q). Small values focus on
+            the best archive solutions; larger values spread the
+            selection more evenly.
+        evaporation: Speed of convergence (xi). Plays a role similar to
+            pheromone evaporation: higher values mean slower convergence.
+        seed: Random seed for reproducibility.
+    """
+
+    def __init__(self, population_size=30, archive_size=50,
+                 intensification=0.1, evaporation=0.85, seed=None):
+        super().__init__(population_size=population_size, seed=seed)
+        if archive_size < 2:
+            raise ValueError("archive_size must be >= 2")
+        self.archive_size = int(archive_size)
+        self.intensification = float(intensification)
+        self.evaporation = float(evaporation)
+
+    def init_population(self, task):
+        archive = self.rng.uniform(
+            task.lower, task.upper, (self.archive_size, task.dimension)
+        )
+        fitness = np.array([task.eval(x) for x in archive])
+        order = np.argsort(fitness)
+        return archive[order], fitness[order]
+
+    def _selection_weights(self):
+        k, q = self.archive_size, self.intensification
+        ranks = np.arange(k)
+        weights = np.exp(-(ranks ** 2) / (2.0 * (q * k) ** 2)) / (q * k * np.sqrt(2.0 * np.pi))
+        return weights / np.sum(weights)
+
+    def run_iteration(self, task, state):
+        archive, fitness = state
+        probabilities = self._selection_weights()
+
+        ants = np.empty((self.population_size, task.dimension))
+        for a in range(self.population_size):
+            guide = self.rng.choice(self.archive_size, p=probabilities)
+            # Gaussian width per dimension: mean distance from the guide
+            # to the rest of the archive, scaled by the evaporation rate.
+            sigma = self.evaporation * np.sum(
+                np.abs(archive - archive[guide]), axis=0
+            ) / (self.archive_size - 1)
+            ants[a] = task.repair(self.rng.normal(archive[guide], np.maximum(sigma, 1e-12)))
+        ant_fitness = np.array([task.eval(x) for x in ants])
+
+        # Merge ants into the archive and keep the best archive_size solutions.
+        merged = np.vstack([archive, ants])
+        merged_fitness = np.concatenate([fitness, ant_fitness])
+        order = np.argsort(merged_fitness)[: self.archive_size]
+        return merged[order], merged_fitness[order]

ikn_library-0.1.0/src/ikn_library/algorithms/algorithm.py

@@ -0,0 +1,54 @@
+"""Base class for metaheuristic algorithms."""
+
+import numpy as np
+
+
+class Algorithm:
+    """Base class for population-based metaheuristic algorithms.
+
+    Subclasses implement :meth:`init_population` and :meth:`run_iteration`;
+    the shared :meth:`run` loop handles the budget and result reporting.
+
+    Args:
+        population_size: Number of individuals in the population.
+        seed: Random seed for reproducibility (optional).
+    """
+
+    def __init__(self, population_size=25, seed=None):
+        if population_size < 1:
+            raise ValueError("population_size must be >= 1")
+        self.population_size = int(population_size)
+        self.rng = np.random.default_rng(seed)
+
+    def run(self, task):
+        """Run the algorithm on ``task`` until its budget is exhausted.
+
+        Returns:
+            tuple: ``(best_x, best_fitness)``.
+        """
+        state = self.init_population(task)
+        task.next_iter()
+        while not task.stopping_condition():
+            state = self.run_iteration(task, state)
+            task.next_iter()
+        return task.result()
+
+    def init_population(self, task):
+        """Create the initial population; return the algorithm state.
+
+        The default creates ``population_size`` uniform random solutions
+        and returns ``(population, fitness)`` arrays.
+        """
+        population = self.rng.uniform(
+            task.lower, task.upper, (self.population_size, task.dimension)
+        )
+        fitness = np.array([task.eval(x) for x in population])
+        return population, fitness
+
+    def run_iteration(self, task, state):
+        """Perform one iteration; receive and return the algorithm state."""
+        raise NotImplementedError
+
+    @property
+    def name(self):
+        return type(self).__name__

ikn_library-0.1.0/src/ikn_library/algorithms/binary_aco.py

@@ -0,0 +1,73 @@
+"""Binary Ant Colony Optimization for subset-selection problems.
+
+Each decision variable is a bit (1 = selected, 0 = not selected). A
+pheromone value is maintained per (variable, bit-value) pair; ants build
+bit strings by sampling each bit with a probability proportional to its
+pheromone. Pheromone is updated in the hyper-cube framework: it
+evaporates toward the bit values of the best solution found so far, and
+is clamped to ``[tau_min, tau_max]`` to preserve exploration.
+"""
+
+import numpy as np
+
+from ikn_library.algorithms.algorithm import Algorithm
+
+
+class BinaryAntColonyOptimization(Algorithm):
+    """Binary ACO for feature selection and other subset problems.
+
+    Solutions are 0/1 vectors, so the wrapped problem must interpret its
+    input as a bit mask (e.g.
+    :class:`~ikn_library.problems.FeatureSelectionProblem`).
+
+    Args:
+        population_size: Number of ants per iteration.
+        evaporation: Pheromone evaporation/learning rate (rho) in (0, 1).
+            Higher values converge faster toward the best solution.
+        alpha: Pheromone importance exponent.
+        tau_min: Lower pheromone limit, keeps every bit reachable.
+        tau_max: Upper pheromone limit.
+        seed: Random seed for reproducibility.
+    """
+
+    def __init__(self, population_size=30, evaporation=0.1, alpha=1.0,
+                 tau_min=0.1, tau_max=0.9, seed=None):
+        super().__init__(population_size=population_size, seed=seed)
+        if not 0.0 < evaporation < 1.0:
+            raise ValueError("evaporation must be in (0, 1)")
+        if not 0.0 < tau_min < tau_max:
+            raise ValueError("require 0 < tau_min < tau_max")
+        self.evaporation = float(evaporation)
+        self.alpha = float(alpha)
+        self.tau_min = float(tau_min)
+        self.tau_max = float(tau_max)
+
+    def _sample_ants(self, task, pheromone):
+        weights = pheromone ** self.alpha
+        p_one = weights[:, 1] / np.sum(weights, axis=1)
+        ants = (self.rng.random((self.population_size, task.dimension)) < p_one).astype(float)
+        # An all-zero ant selects nothing and is unevaluable as a subset;
+        # repair it by switching one random bit on.
+        for ant in ants:
+            if not ant.any():
+                ant[self.rng.integers(task.dimension)] = 1.0
+        return ants
+
+    def init_population(self, task):
+        pheromone = np.full((task.dimension, 2), 0.5)
+        ants = self._sample_ants(task, pheromone)
+        for ant in ants:
+            task.eval(ant)
+        return pheromone
+
+    def run_iteration(self, task, pheromone):
+        ants = self._sample_ants(task, pheromone)
+        for ant in ants:
+            task.eval(ant)
+
+        # Hyper-cube pheromone update toward the best-so-far solution.
+        best_bits = task.best_x.astype(int)
+        deposit = np.zeros_like(pheromone)
+        deposit[np.arange(task.dimension), best_bits] = 1.0
+        pheromone = (1.0 - self.evaporation) * pheromone + self.evaporation * deposit
+        return np.clip(pheromone, self.tau_min, self.tau_max)

ikn_library-0.1.0/src/ikn_library/problems/__init__.py

@@ -0,0 +1,7 @@
+"""Optimization problems: base class, benchmarks, and feature selection."""
+
+from ikn_library.problems.benchmarks import Ackley, Rastrigin, Sphere
+from ikn_library.problems.feature_selection import FeatureSelectionProblem
+from ikn_library.problems.problem import Problem
+
+__all__ = ["Ackley", "FeatureSelectionProblem", "Problem", "Rastrigin", "Sphere"]

ikn_library-0.1.0/src/ikn_library/problems/benchmarks.py

@@ -0,0 +1,41 @@
+"""Standard benchmark functions for testing algorithms.
+
+All benchmarks are minimization problems with a known global optimum of 0.
+"""
+
+import numpy as np
+
+from ikn_library.problems.problem import Problem
+
+
+class Sphere(Problem):
+    """Sphere function: ``f(x) = sum(x_i^2)``. Optimum ``f(0) = 0``."""
+
+    def __init__(self, dimension=10, lower=-5.12, upper=5.12):
+        super().__init__(dimension, lower, upper)
+
+    def _evaluate(self, x):
+        return np.sum(x ** 2)
+
+
+class Rastrigin(Problem):
+    """Rastrigin function, highly multimodal. Optimum ``f(0) = 0``."""
+
+    def __init__(self, dimension=10, lower=-5.12, upper=5.12):
+        super().__init__(dimension, lower, upper)
+
+    def _evaluate(self, x):
+        return 10.0 * self.dimension + np.sum(x ** 2 - 10.0 * np.cos(2.0 * np.pi * x))
+
+
+class Ackley(Problem):
+    """Ackley function, multimodal with a nearly flat outer region. Optimum ``f(0) = 0``."""
+
+    def __init__(self, dimension=10, lower=-32.768, upper=32.768):
+        super().__init__(dimension, lower, upper)
+
+    def _evaluate(self, x):
+        n = self.dimension
+        term1 = -20.0 * np.exp(-0.2 * np.sqrt(np.sum(x ** 2) / n))
+        term2 = -np.exp(np.sum(np.cos(2.0 * np.pi * x)) / n)
+        return term1 + term2 + 20.0 + np.e

ikn_library-0.1.0/src/ikn_library/problems/feature_selection.py

@@ -0,0 +1,86 @@
+"""Wrapper-based feature selection as an optimization problem."""
+
+import numpy as np
+
+from ikn_library.problems.problem import Problem
+
+
+class FeatureSelectionProblem(Problem):
+    """Wrapper feature selection: pick the feature subset that maximizes
+    a cross-validated model score while keeping the subset small.
+
+    Solutions are vectors in ``[0, 1]``; entries above ``threshold`` mark
+    selected features, so both binary algorithms (which emit 0/1 bits)
+    and continuous algorithms can optimize this problem.
+
+    The fitness (minimized) is::
+
+        alpha * (1 - cv_score) + (1 - alpha) * n_selected / n_features
+
+    Requires scikit-learn (``pip install ikn-library[ml]``).
+
+    Args:
+        X: Feature matrix of shape ``(n_samples, n_features)``.
+        y: Target vector of shape ``(n_samples,)``.
+        estimator: A scikit-learn estimator. Defaults to
+            ``KNeighborsClassifier(n_neighbors=5)``, a common choice in
+            wrapper feature-selection studies.
+        cv: Number of cross-validation folds.
+        scoring: scikit-learn scoring name (e.g. ``"accuracy"``, ``"f1"``).
+        alpha: Trade-off between score quality and subset size, in [0, 1].
+            Values near 1 prioritize the model score.
+        threshold: Cut-off above which a variable counts as selected.
+    """
+
+    def __init__(self, X, y, estimator=None, cv=5, scoring="accuracy",
+                 alpha=0.99, threshold=0.5):
+        try:
+            from sklearn.model_selection import cross_val_score  # noqa: F401
+        except ImportError as exc:
+            raise ImportError(
+                "FeatureSelectionProblem requires scikit-learn; "
+                "install it with: pip install ikn-library[ml]"
+            ) from exc
+
+        self.X = np.asarray(X)
+        self.y = np.asarray(y)
+        if self.X.ndim != 2:
+            raise ValueError("X must be 2-dimensional (n_samples, n_features)")
+        if len(self.X) != len(self.y):
+            raise ValueError("X and y must have the same number of samples")
+        if not 0.0 <= alpha <= 1.0:
+            raise ValueError("alpha must be in [0, 1]")
+
+        super().__init__(dimension=self.X.shape[1], lower=0.0, upper=1.0)
+
+        if estimator is None:
+            from sklearn.neighbors import KNeighborsClassifier
+            estimator = KNeighborsClassifier(n_neighbors=5)
+        self.estimator = estimator
+        self.cv = cv
+        self.scoring = scoring
+        self.alpha = float(alpha)
+        self.threshold = float(threshold)
+
+    def feature_mask(self, x):
+        """Boolean mask of selected features for a solution vector."""
+        return np.asarray(x, dtype=float) > self.threshold
+
+    def selected_features(self, x):
+        """Indices of the features selected by a solution vector."""
+        return np.flatnonzero(self.feature_mask(x))
+
+    def _evaluate(self, x):
+        from sklearn.base import clone
+        from sklearn.model_selection import cross_val_score
+
+        mask = self.feature_mask(x)
+        n_selected = int(np.sum(mask))
+        if n_selected == 0:
+            return 1.0  # worst possible fitness: nothing selected
+        score = cross_val_score(
+            clone(self.estimator), self.X[:, mask], self.y,
+            cv=self.cv, scoring=self.scoring,
+        ).mean()
+        return (self.alpha * (1.0 - score)
+                + (1.0 - self.alpha) * n_selected / self.dimension)

ikn_library-0.1.0/src/ikn_library/problems/problem.py

@@ -0,0 +1,52 @@
+"""Base class for optimization problems."""
+
+import numpy as np
+
+
+class Problem:
+    """An optimization problem defined on a box-constrained search space.
+
+    Subclass this and implement :meth:`_evaluate` to define a custom
+    problem (e.g. a machine-learning objective for parameter optimization
+    or a wrapper objective for feature selection).
+
+    Args:
+        dimension: Number of decision variables.
+        lower: Lower bound(s) of the search space. Scalar or array of
+            shape ``(dimension,)``.
+        upper: Upper bound(s) of the search space. Scalar or array of
+            shape ``(dimension,)``.
+
+    Example:
+        >>> class MyProblem(Problem):
+        ...     def __init__(self, dimension):
+        ...         super().__init__(dimension, lower=-10.0, upper=10.0)
+        ...     def _evaluate(self, x):
+        ...         return float(np.sum(x ** 2))
+    """
+
+    def __init__(self, dimension, lower=-1.0, upper=1.0):
+        if dimension < 1:
+            raise ValueError("dimension must be >= 1")
+        self.dimension = int(dimension)
+        self.lower = np.full(self.dimension, lower, dtype=float) if np.isscalar(lower) else np.asarray(lower, dtype=float)
+        self.upper = np.full(self.dimension, upper, dtype=float) if np.isscalar(upper) else np.asarray(upper, dtype=float)
+        if self.lower.shape != (self.dimension,) or self.upper.shape != (self.dimension,):
+            raise ValueError("lower/upper must be scalars or arrays of shape (dimension,)")
+        if np.any(self.lower >= self.upper):
+            raise ValueError("each lower bound must be strictly less than its upper bound")
+
+    def evaluate(self, x):
+        """Evaluate a solution vector and return its fitness as ``float``."""
+        x = np.asarray(x, dtype=float)
+        if x.shape != (self.dimension,):
+            raise ValueError(f"expected solution of shape ({self.dimension},), got {x.shape}")
+        return float(self._evaluate(x))
+
+    def _evaluate(self, x):
+        """Compute the objective value for solution ``x``. Must be overridden."""
+        raise NotImplementedError
+
+    @property
+    def name(self):
+        return type(self).__name__

ikn_library-0.1.0/src/ikn_library/task.py

@@ -0,0 +1,92 @@
+"""Task: wraps a Problem with a stopping condition and bookkeeping."""
+
+from enum import Enum
+
+import numpy as np
+
+
+class OptimizationType(Enum):
+    MINIMIZATION = 1
+    MAXIMIZATION = -1
+
+
+class Task:
+    """An optimization run: a problem plus a budget and progress tracking.
+
+    The task counts evaluations, tracks the best solution found so far,
+    and records the convergence history. Algorithms should call
+    :meth:`eval` for every candidate solution and check :meth:`stopping_condition`.
+
+    Args:
+        problem: The :class:`~ikn_library.problems.Problem` to optimize.
+        max_evals: Stop after this many fitness evaluations (optional).
+        max_iters: Stop after this many iterations (optional). The
+            algorithm must call :meth:`next_iter` once per iteration.
+        optimization_type: Minimize (default) or maximize.
+
+    At least one of ``max_evals`` / ``max_iters`` must be given.
+    """
+
+    def __init__(self, problem, max_evals=None, max_iters=None,
+                 optimization_type=OptimizationType.MINIMIZATION):
+        if max_evals is None and max_iters is None:
+            raise ValueError("provide max_evals and/or max_iters")
+        self.problem = problem
+        self.max_evals = np.inf if max_evals is None else int(max_evals)
+        self.max_iters = np.inf if max_iters is None else int(max_iters)
+        self.optimization_type = optimization_type
+
+        self.evals = 0
+        self.iters = 0
+        self.best_x = None
+        self.best_fitness = np.inf
+        self.convergence = []  # best internal fitness after each iteration
+
+    @property
+    def dimension(self):
+        return self.problem.dimension
+
+    @property
+    def lower(self):
+        return self.problem.lower
+
+    @property
+    def upper(self):
+        return self.problem.upper
+
+    def repair(self, x):
+        """Clip a solution back into the search-space bounds."""
+        return np.clip(x, self.lower, self.upper)
+
+    def eval(self, x):
+        """Evaluate ``x``, update counters and the best-so-far solution.
+
+        Returns the fitness in *internal* form (maximization problems are
+        negated so that algorithms can always minimize).
+        """
+        if self.stopping_condition():
+            return np.inf
+        fitness = self.problem.evaluate(x) * self.optimization_type.value
+        self.evals += 1
+        if fitness < self.best_fitness:
+            self.best_fitness = fitness
+            self.best_x = np.array(x, dtype=float)
+        return fitness
+
+    def next_iter(self):
+        """Advance the iteration counter and record convergence."""
+        self.iters += 1
+        self.convergence.append(self.best_fitness)
+
+    def stopping_condition(self):
+        """True when the evaluation or iteration budget is exhausted."""
+        return self.evals >= self.max_evals or self.iters >= self.max_iters
+
+    def result(self):
+        """Return ``(best_x, best_fitness)`` in the problem's original sense."""
+        return self.best_x, self.best_fitness * self.optimization_type.value
+
+    def convergence_data(self):
+        """Convergence history as ``(iterations, best_fitness_values)``."""
+        values = np.array(self.convergence) * self.optimization_type.value
+        return np.arange(1, len(values) + 1), values

ikn_library-0.1.0/tests/test_aco.py

@@ -0,0 +1,54 @@
+import numpy as np
+import pytest
+
+from ikn_library import Task
+from ikn_library.algorithms import AntColonyOptimization
+from ikn_library.problems import Rastrigin, Sphere
+
+
+def test_aco_converges_on_sphere():
+    task = Task(problem=Sphere(dimension=5), max_evals=10000)
+    algo = AntColonyOptimization(population_size=30, archive_size=50, seed=42)
+    best_x, best_fitness = algo.run(task)
+    assert best_fitness < 1e-3
+    assert best_x.shape == (5,)
+
+
+def test_aco_improves_on_rastrigin():
+    problem = Rastrigin(dimension=5)
+    task = Task(problem=problem, max_evals=10000)
+    algo = AntColonyOptimization(population_size=30, archive_size=50, seed=1)
+    _, best_fitness = algo.run(task)
+    random_baseline = min(
+        problem.evaluate(x)
+        for x in np.random.default_rng(1).uniform(-5.12, 5.12, (100, 5))
+    )
+    assert best_fitness < random_baseline
+
+
+def test_aco_respects_bounds():
+    task = Task(problem=Sphere(dimension=3), max_evals=2000)
+    algo = AntColonyOptimization(population_size=10, archive_size=20, seed=7)
+    best_x, _ = algo.run(task)
+    assert np.all(best_x >= task.lower) and np.all(best_x <= task.upper)
+
+
+def test_aco_is_reproducible_with_seed():
+    results = []
+    for _ in range(2):
+        task = Task(problem=Sphere(dimension=4), max_evals=3000)
+        algo = AntColonyOptimization(population_size=20, seed=123)
+        results.append(algo.run(task))
+    np.testing.assert_allclose(results[0][0], results[1][0])
+    assert results[0][1] == results[1][1]
+
+
+def test_aco_respects_eval_budget():
+    task = Task(problem=Sphere(dimension=3), max_evals=500)
+    AntColonyOptimization(population_size=10, seed=0).run(task)
+    assert task.evals <= 500
+
+
+def test_invalid_archive_size():
+    with pytest.raises(ValueError):
+        AntColonyOptimization(archive_size=1)

ikn_library-0.1.0/tests/test_binary_aco.py

@@ -0,0 +1,74 @@
+import numpy as np
+import pytest
+
+from ikn_library import Task
+from ikn_library.algorithms import BinaryAntColonyOptimization
+from ikn_library.problems import Problem
+
+
+class SubsetMatch(Problem):
+    """Minimize the Hamming distance to a known target bit mask."""
+
+    def __init__(self, target):
+        self.target = np.asarray(target, dtype=float)
+        super().__init__(dimension=len(self.target), lower=0.0, upper=1.0)
+
+    def _evaluate(self, x):
+        return float(np.sum((x > 0.5) != (self.target > 0.5)))
+
+
+def test_binary_aco_finds_target_subset():
+    target = np.array([1, 0, 1, 1, 0, 0, 0, 1, 0, 0])
+    task = Task(problem=SubsetMatch(target), max_evals=6000)
+    algo = BinaryAntColonyOptimization(population_size=20, seed=42)
+    best_x, best_fitness = algo.run(task)
+    assert best_fitness == 0.0
+    np.testing.assert_array_equal(best_x, target)
+
+
+def test_binary_aco_emits_only_bits():
+    target = np.ones(6)
+    task = Task(problem=SubsetMatch(target), max_evals=500)
+    best_x, _ = BinaryAntColonyOptimization(population_size=10, seed=3).run(task)
+    assert set(np.unique(best_x)) <= {0.0, 1.0}
+
+
+def test_binary_aco_never_selects_empty_subset():
+    class CountOnes(Problem):
+        def __init__(self):
+            super().__init__(dimension=8, lower=0.0, upper=1.0)
+
+        def _evaluate(self, x):
+            assert np.sum(x) >= 1, "empty subset was evaluated"
+            return float(np.sum(x))
+
+    task = Task(problem=CountOnes(), max_evals=2000)
+    best_x, _ = BinaryAntColonyOptimization(population_size=15, seed=5).run(task)
+    assert np.sum(best_x) >= 1
+
+
+def test_binary_aco_is_reproducible_with_seed():
+    target = np.array([1, 0, 1, 0, 1, 0])
+    results = []
+    for _ in range(2):
+        task = Task(problem=SubsetMatch(target), max_evals=1000)
+        algo = BinaryAntColonyOptimization(population_size=10, seed=99)
+        results.append(algo.run(task))
+    np.testing.assert_array_equal(results[0][0], results[1][0])
+    assert results[0][1] == results[1][1]
+
+
+def test_binary_aco_respects_eval_budget():
+    task = Task(problem=SubsetMatch(np.ones(5)), max_evals=300)
+    BinaryAntColonyOptimization(population_size=10, seed=0).run(task)
+    assert task.evals <= 300
+
+
+@pytest.mark.parametrize("kwargs", [
+    {"evaporation": 0.0},
+    {"evaporation": 1.0},
+    {"tau_min": 0.5, "tau_max": 0.4},
+])
+def test_binary_aco_invalid_params(kwargs):
+    with pytest.raises(ValueError):
+        BinaryAntColonyOptimization(**kwargs)

ikn_library-0.1.0/tests/test_feature_selection.py

@@ -0,0 +1,62 @@
+import numpy as np
+import pytest
+
+sklearn = pytest.importorskip("sklearn")
+
+from sklearn.datasets import make_classification
+
+from ikn_library import Task
+from ikn_library.algorithms import BinaryAntColonyOptimization
+from ikn_library.problems import FeatureSelectionProblem
+
+
+@pytest.fixture(scope="module")
+def dataset():
+    return make_classification(
+        n_samples=120, n_features=10, n_informative=3, n_redundant=0,
+        n_repeated=0, shuffle=False, random_state=42,
+    )
+
+
+def test_selected_features_and_mask(dataset):
+    X, y = dataset
+    problem = FeatureSelectionProblem(X, y)
+    x = np.array([0.9, 0.1, 0.6, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.7])
+    np.testing.assert_array_equal(problem.selected_features(x), [0, 2, 9])
+    assert problem.feature_mask(x).sum() == 3
+
+
+def test_empty_subset_gets_worst_fitness(dataset):
+    X, y = dataset
+    problem = FeatureSelectionProblem(X, y)
+    assert problem.evaluate(np.zeros(10)) == 1.0
+
+
+def test_fitness_in_unit_interval(dataset):
+    X, y = dataset
+    problem = FeatureSelectionProblem(X, y, cv=3)
+    fitness = problem.evaluate(np.ones(10))
+    assert 0.0 <= fitness <= 1.0
+
+
+def test_binary_aco_feature_selection_improves(dataset):
+    X, y = dataset
+    problem = FeatureSelectionProblem(X, y, cv=3)
+    all_features_fitness = problem.evaluate(np.ones(10))
+
+    task = Task(problem=problem, max_evals=300)
+    algo = BinaryAntColonyOptimization(population_size=10, seed=42)
+    best_x, best_fitness = algo.run(task)
+
+    assert best_fitness <= all_features_fitness
+    assert len(problem.selected_features(best_x)) >= 1
+
+
+def test_input_validation(dataset):
+    X, y = dataset
+    with pytest.raises(ValueError):
+        FeatureSelectionProblem(X, y[:-5])
+    with pytest.raises(ValueError):
+        FeatureSelectionProblem(X, y, alpha=1.5)
+    with pytest.raises(ValueError):
+        FeatureSelectionProblem(X[0], y)

ikn_library-0.1.0/tests/test_problems.py

@@ -0,0 +1,32 @@
+import numpy as np
+import pytest
+
+from ikn_library.problems import Ackley, Problem, Rastrigin, Sphere
+
+
+@pytest.mark.parametrize("cls", [Sphere, Rastrigin, Ackley])
+def test_benchmark_optimum_is_zero(cls):
+    problem = cls(dimension=10)
+    assert problem.evaluate(np.zeros(10)) == pytest.approx(0.0, abs=1e-9)
+
+
+def test_evaluate_rejects_wrong_shape():
+    problem = Sphere(dimension=5)
+    with pytest.raises(ValueError):
+        problem.evaluate(np.zeros(3))
+
+
+def test_custom_problem():
+    class Linear(Problem):
+        def __init__(self):
+            super().__init__(dimension=3, lower=0.0, upper=1.0)
+
+        def _evaluate(self, x):
+            return np.sum(x)
+
+    assert Linear().evaluate([0.1, 0.2, 0.3]) == pytest.approx(0.6)
+
+
+def test_invalid_bounds_raise():
+    with pytest.raises(ValueError):
+        Sphere(dimension=2, lower=1.0, upper=-1.0)

ikn_library-0.1.0/tests/test_task.py

@@ -0,0 +1,44 @@
+import numpy as np
+import pytest
+
+from ikn_library import OptimizationType, Task
+from ikn_library.problems import Sphere
+
+
+def test_requires_a_budget():
+    with pytest.raises(ValueError):
+        Task(problem=Sphere(dimension=2))
+
+
+def test_counts_evals_and_tracks_best():
+    task = Task(problem=Sphere(dimension=2), max_evals=10)
+    task.eval(np.array([1.0, 1.0]))
+    task.eval(np.array([0.5, 0.5]))
+    assert task.evals == 2
+    assert task.best_fitness == pytest.approx(0.5)
+    np.testing.assert_allclose(task.best_x, [0.5, 0.5])
+
+
+def test_stops_at_max_evals():
+    task = Task(problem=Sphere(dimension=2), max_evals=3)
+    for _ in range(5):
+        task.eval(np.array([1.0, 1.0]))
+    assert task.evals == 3
+    assert task.stopping_condition()
+
+
+def test_repair_clips_to_bounds():
+    task = Task(problem=Sphere(dimension=2), max_evals=10)
+    repaired = task.repair(np.array([100.0, -100.0]))
+    np.testing.assert_allclose(repaired, [5.12, -5.12])
+
+
+def test_maximization_result_sign():
+    task = Task(
+        problem=Sphere(dimension=2),
+        max_evals=10,
+        optimization_type=OptimizationType.MAXIMIZATION,
+    )
+    task.eval(np.array([2.0, 0.0]))
+    _, best = task.result()
+    assert best == pytest.approx(4.0)