evograd-diff 0.1.2__tar.gz → 0.2.0__tar.gz

{evograd_diff-0.1.2 → evograd_diff-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evograd-diff
-Version: 0.1.2
+Version: 0.2.0
 Summary: PyTorch-based framework for differentiable evolutionary computation and swarm intelligence
 Project-URL: Homepage, https://github.com/andreatangherloni/EvoGrad
 Project-URL: Repository, https://github.com/andreatangherloni/EvoGrad
@@ -25,15 +25,18 @@ Requires-Dist: seaborn>=0.13.2
 Requires-Dist: torch>=2.11.0
 Description-Content-Type: text/markdown
 
-# EvoGrad: Metaheuristics in a Differentiable Wonderland
+# EvoGrad: Accelerated Metaheuristics in a Differentiable Wonderland
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+">
   <img src="https://img.shields.io/badge/pytorch-2.0+-orange.svg" alt="PyTorch 2.0+">
   <img src="https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg" alt="License: Apache-2.0">
+  <img src="https://img.shields.io/badge/IEEE%20CEC-2026-success.svg" alt="IEEE CEC 2026">
  
 </p>
 
+> 🎉 **EvoGrad has been accepted at [IEEE CEC 2026](#-citation)!**
+
 **EvoGrad** is a PyTorch-based framework for differentiable Evolutionary Computation and Swarm Intelligence. It bridges classical population-based optimisation with modern differentiable programming by enabling gradient flow through evolutionary operators.
 
 ## 🌟 Key Features
@@ -421,11 +424,88 @@ EvoGrad makes evolutionary algorithms differentiable through:
 
 ## 📊 Benchmarks
 
-TODO
+EvoGrad ships a self-contained, **PyTorch-native benchmark suite** (`evograd.benchmarks`) together with a parallel runner that evaluates every algorithm in its four operating modes against two reference baselines.
+
+### Function library
+
+All functions share a common `BenchmarkFunction` interface (`f(x)` on an `(N, n_var)` batch, plus `.bounds` and the known optimum) and run on CPU/GPU/MPS.
+
+| Category | Functions |
+|----------|-----------|
+| **Classical — unimodal** | Sphere, Ellipsoid, SumOfDifferentPowers, Schwefel 2.22, Cigar, Discus, BentCigar, Rosenbrock, DixonPrice, Powell, Trid |
+| **Classical — multimodal** | Rastrigin, Ackley, Griewank, Schwefel, Levy, Michalewicz, Zakharov, Weierstrass, Alpine, Salomon, Styblinski–Tang |
+| **CEC 2017** (`F1`–`F30`) | Simple/unimodal (F1–F10), Hybrid (F11–F20), Composition (F21–F30) — the full competition suite, **rewritten from scratch in PyTorch** |
+| **Multi-Basin / Smoothed-Funnel** | `MultiBasinRastrigin`, `MultiBasinRosenbrock`, `DeceptiveLandscape` — designed for differentiable EAs |
+| **Transforms** | Shifted / Rotated / Scaled / Asymmetric / Oscillated / Biased wrappers for building custom variants |
+
+```python
+import torch
+from evograd.benchmarks.functions import Sphere, Rastrigin, get_cec2017_function, MultiBasinRastrigin
+
+f = get_cec2017_function(14, n_var=30)   # CEC 2017 F14 in 30D
+y = f(torch.randn(100, 30))              # batch evaluation -> shape [100]
+```
+
+The **Multi-Basin** functions aggregate `K` basins (each a full Rastrigin/Rosenbrock landscape) with a smooth *log-sum-exp* minimum, so the surface stays differentiable everywhere while still trapping pure gradient descent in distractor basins — exactly the setting where population search combined with gradient refinement pays off.
+
+### Running the benchmarks
+
+The runner evaluates the four EvoGrad modes — **Classical**, **Differentiable**, **Adaptive**, **Full** — and, by default, the **pymoo** and **Adam** (multi-start) baselines:
+
+```bash
+# 30 runs of DE on the full CEC 2017 suite in 30D (vs pymoo + Adam)
+python -m evograd.benchmarks.run_benchmark_functions -a DE -s cec2017 -D 30 -r 30
+
+# CMA-ES on the multi-basin functions, on GPU
+python -m evograd.benchmarks.run_benchmark_functions -a CMAES -s funnel -D 30 --device cuda
+
+# List every available function and suite
+python -m evograd.benchmarks.run_benchmark_functions --list_functions
+```
+
+Key flags: `-a {DE,SHADE,PSO,GA,CMAES,ADAM}`, `-s` suite (`classical`, `standard`, `cec2017[_simple|_hybrid|_composition]`, `funnel`, …), `-D` dimensionality, `-r` runs, `-p` population size, `--no_pymoo` / `--no_adam` to drop baselines. Plotting utilities live in `plot_benchmarks.py`.
+
+### Results
+
+The three differentiable variants are compared against the **Classical** baseline and pymoo:
+
+- **Adaptive** — learnable hyperparameters, purely stochastic variation (no gradient through the population).
+- **Diff** (Differentiable) — fixed hyperparameters, gradients refine the population.
+- **Full** — both: learnable hyperparameters *and* gradient-based population refinement.
+
+**CEC 2017 (30D & 100D).** 29 functions (F2 excluded, per the competition), search space `[-100, 100]^D`, 100 individuals, `10000·D` evaluations, 30 independent paired runs, one-sided Wilcoxon signed-rank test with Benjamini–Hochberg correction. Highlights:
+
+- Differentiable variants are **statistically significantly better than the classical baseline in ~31% of all comparisons**, and **never substantially worse** — gradient refinement can be added to EAs safely.
+- Gains concentrate where local refinement helps most: **GA (70.1%)** and **DE (46.0%)** of comparisons improved, versus **PSO (6.9%)** and **CMA-ES (1.1%)**, which already include strong built-in adaptation.
+- Across variants, **Full (41.4%) > Adaptive (35.3%) > Diff (16.4%)** — combining hyperparameter learning with population refinement helps the most, increasingly so at 100D.
+- CMA-ES is the strongest method overall (especially on hybrid/composition functions), and EvoGrad runs ~**3× faster** than the pymoo baselines on CPU *despite* the added gradient computation.
+
+**Multi-Basin Rastrigin** (`D=30`, bounds `[-5, 5]^D`, 150,000 evaluations, 30 runs). Every CMA-ES variant locates the global basin (best fitness `0.00`); a multi-start **Adam** baseline (100 parallel solutions) stays trapped in distractor basins:
+
+| Configuration | Best | Mean | Std | Time (s) |
+|---|---|---|---|---|
+| CMA-ES Classical | 0.00 | 2.22 | 3.04 | 25.66 |
+| CMA-ES Differentiable | 0.00 | 1.49 | 2.16 | 9.77 |
+| CMA-ES Adaptive | 0.00 | **0.99** | **1.36** | 45.24 |
+| CMA-ES Full | 0.00 | 1.29 | 2.12 | **7.94** |
+| Adam (multi-start, pop-based) | 116.41 | 153.77 | 13.98 | 3.88 |
+
+The **Adaptive** variant reaches the lowest mean/variance, while **Full** matches it closely at the **fastest** runtime — gradient flow yields large speed-ups while population search secures the global basin. Adam alone is **>2 orders of magnitude worse**, confirming that pure gradient descent cannot escape distractor basins.
+
+> Full experimental details are in the paper (see [Citation](#-citation)).
 
 ## 📖 Citation
 
-TBA
+EvoGrad was accepted at the **IEEE Congress on Evolutionary Computation (CEC) 2026**. If you use EvoGrad in your research, please cite:
+
+```bibtex
+@inproceedings{citterio2026evograd,
+  title     = {{EvoGrad}: Accelerated Metaheuristics in a Differentiable Wonderland},
+  author    = {Citterio, Beatrice F. R. and Papetti, Daniele M. and Dimitri, Giovanna Maria and Tangherloni, Andrea},
+  booktitle = {Proceedings of the IEEE Congress on Evolutionary Computation (CEC)},
+  year      = {2026},
+}
+```
 
 ## 📄 License
 

{evograd_diff-0.1.2 → evograd_diff-0.2.0}/README.md

@@ -1,12 +1,15 @@
-# EvoGrad: Metaheuristics in a Differentiable Wonderland
+# EvoGrad: Accelerated Metaheuristics in a Differentiable Wonderland
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="Python 3.9+">
   <img src="https://img.shields.io/badge/pytorch-2.0+-orange.svg" alt="PyTorch 2.0+">
   <img src="https://img.shields.io/badge/license-Apache%20License%202.0-blue.svg" alt="License: Apache-2.0">
+  <img src="https://img.shields.io/badge/IEEE%20CEC-2026-success.svg" alt="IEEE CEC 2026">
  
 </p>
 
+> 🎉 **EvoGrad has been accepted at [IEEE CEC 2026](#-citation)!**
+
 **EvoGrad** is a PyTorch-based framework for differentiable Evolutionary Computation and Swarm Intelligence. It bridges classical population-based optimisation with modern differentiable programming by enabling gradient flow through evolutionary operators.
 
 ## 🌟 Key Features
@@ -394,11 +397,88 @@ EvoGrad makes evolutionary algorithms differentiable through:
 
 ## 📊 Benchmarks
 
-TODO
+EvoGrad ships a self-contained, **PyTorch-native benchmark suite** (`evograd.benchmarks`) together with a parallel runner that evaluates every algorithm in its four operating modes against two reference baselines.
+
+### Function library
+
+All functions share a common `BenchmarkFunction` interface (`f(x)` on an `(N, n_var)` batch, plus `.bounds` and the known optimum) and run on CPU/GPU/MPS.
+
+| Category | Functions |
+|----------|-----------|
+| **Classical — unimodal** | Sphere, Ellipsoid, SumOfDifferentPowers, Schwefel 2.22, Cigar, Discus, BentCigar, Rosenbrock, DixonPrice, Powell, Trid |
+| **Classical — multimodal** | Rastrigin, Ackley, Griewank, Schwefel, Levy, Michalewicz, Zakharov, Weierstrass, Alpine, Salomon, Styblinski–Tang |
+| **CEC 2017** (`F1`–`F30`) | Simple/unimodal (F1–F10), Hybrid (F11–F20), Composition (F21–F30) — the full competition suite, **rewritten from scratch in PyTorch** |
+| **Multi-Basin / Smoothed-Funnel** | `MultiBasinRastrigin`, `MultiBasinRosenbrock`, `DeceptiveLandscape` — designed for differentiable EAs |
+| **Transforms** | Shifted / Rotated / Scaled / Asymmetric / Oscillated / Biased wrappers for building custom variants |
+
+```python
+import torch
+from evograd.benchmarks.functions import Sphere, Rastrigin, get_cec2017_function, MultiBasinRastrigin
+
+f = get_cec2017_function(14, n_var=30)   # CEC 2017 F14 in 30D
+y = f(torch.randn(100, 30))              # batch evaluation -> shape [100]
+```
+
+The **Multi-Basin** functions aggregate `K` basins (each a full Rastrigin/Rosenbrock landscape) with a smooth *log-sum-exp* minimum, so the surface stays differentiable everywhere while still trapping pure gradient descent in distractor basins — exactly the setting where population search combined with gradient refinement pays off.
+
+### Running the benchmarks
+
+The runner evaluates the four EvoGrad modes — **Classical**, **Differentiable**, **Adaptive**, **Full** — and, by default, the **pymoo** and **Adam** (multi-start) baselines:
+
+```bash
+# 30 runs of DE on the full CEC 2017 suite in 30D (vs pymoo + Adam)
+python -m evograd.benchmarks.run_benchmark_functions -a DE -s cec2017 -D 30 -r 30
+
+# CMA-ES on the multi-basin functions, on GPU
+python -m evograd.benchmarks.run_benchmark_functions -a CMAES -s funnel -D 30 --device cuda
+
+# List every available function and suite
+python -m evograd.benchmarks.run_benchmark_functions --list_functions
+```
+
+Key flags: `-a {DE,SHADE,PSO,GA,CMAES,ADAM}`, `-s` suite (`classical`, `standard`, `cec2017[_simple|_hybrid|_composition]`, `funnel`, …), `-D` dimensionality, `-r` runs, `-p` population size, `--no_pymoo` / `--no_adam` to drop baselines. Plotting utilities live in `plot_benchmarks.py`.
+
+### Results
+
+The three differentiable variants are compared against the **Classical** baseline and pymoo:
+
+- **Adaptive** — learnable hyperparameters, purely stochastic variation (no gradient through the population).
+- **Diff** (Differentiable) — fixed hyperparameters, gradients refine the population.
+- **Full** — both: learnable hyperparameters *and* gradient-based population refinement.
+
+**CEC 2017 (30D & 100D).** 29 functions (F2 excluded, per the competition), search space `[-100, 100]^D`, 100 individuals, `10000·D` evaluations, 30 independent paired runs, one-sided Wilcoxon signed-rank test with Benjamini–Hochberg correction. Highlights:
+
+- Differentiable variants are **statistically significantly better than the classical baseline in ~31% of all comparisons**, and **never substantially worse** — gradient refinement can be added to EAs safely.
+- Gains concentrate where local refinement helps most: **GA (70.1%)** and **DE (46.0%)** of comparisons improved, versus **PSO (6.9%)** and **CMA-ES (1.1%)**, which already include strong built-in adaptation.
+- Across variants, **Full (41.4%) > Adaptive (35.3%) > Diff (16.4%)** — combining hyperparameter learning with population refinement helps the most, increasingly so at 100D.
+- CMA-ES is the strongest method overall (especially on hybrid/composition functions), and EvoGrad runs ~**3× faster** than the pymoo baselines on CPU *despite* the added gradient computation.
+
+**Multi-Basin Rastrigin** (`D=30`, bounds `[-5, 5]^D`, 150,000 evaluations, 30 runs). Every CMA-ES variant locates the global basin (best fitness `0.00`); a multi-start **Adam** baseline (100 parallel solutions) stays trapped in distractor basins:
+
+| Configuration | Best | Mean | Std | Time (s) |
+|---|---|---|---|---|
+| CMA-ES Classical | 0.00 | 2.22 | 3.04 | 25.66 |
+| CMA-ES Differentiable | 0.00 | 1.49 | 2.16 | 9.77 |
+| CMA-ES Adaptive | 0.00 | **0.99** | **1.36** | 45.24 |
+| CMA-ES Full | 0.00 | 1.29 | 2.12 | **7.94** |
+| Adam (multi-start, pop-based) | 116.41 | 153.77 | 13.98 | 3.88 |
+
+The **Adaptive** variant reaches the lowest mean/variance, while **Full** matches it closely at the **fastest** runtime — gradient flow yields large speed-ups while population search secures the global basin. Adam alone is **>2 orders of magnitude worse**, confirming that pure gradient descent cannot escape distractor basins.
+
+> Full experimental details are in the paper (see [Citation](#-citation)).
 
 ## 📖 Citation
 
-TBA
+EvoGrad was accepted at the **IEEE Congress on Evolutionary Computation (CEC) 2026**. If you use EvoGrad in your research, please cite:
+
+```bibtex
+@inproceedings{citterio2026evograd,
+  title     = {{EvoGrad}: Accelerated Metaheuristics in a Differentiable Wonderland},
+  author    = {Citterio, Beatrice F. R. and Papetti, Daniele M. and Dimitri, Giovanna Maria and Tangherloni, Andrea},
+  booktitle = {Proceedings of the IEEE Congress on Evolutionary Computation (CEC)},
+  year      = {2026},
+}
+```
 
 ## 📄 License
 

{evograd_diff-0.1.2 → evograd_diff-0.2.0}/evograd/__init__.py

@@ -57,7 +57,7 @@ Authors
 Andrea Tangherloni <andrea.tangherloni@unibocconi.it>
 """
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __author__ = "Andrea Tangherloni"
 
 __all__ = [

{evograd_diff-0.1.2 → evograd_diff-0.2.0}/evograd/core/algorithm.py

@@ -523,26 +523,65 @@ class Algorithm(nn.Module, ABC):
         
         return self.state.best_fitness
     
-    def forward(self) -> Tensor:
+    def forward(self, reduction: str = "mean", live_selection: bool = True) -> Tensor:
         """
         PyTorch forward pass for differentiable optimisation.
-        
+
         In differentiable mode, this builds a computation graph
-        through the entire generation, returning the best fitness
-        as a differentiable scalar loss. Call update_state() after
+        through the entire generation and reduces the per-offspring
+        fitness to a scalar loss. Call update_state() after
         loss.backward() and optimizer.step() to commit changes.
-        
+
+        Args:
+            reduction: How to reduce the (n_offsprings,) offspring fitness
+                into the scalar loss that is backpropagated:
+                - 'mean' (default): average fitness — gradient reaches the
+                  whole population, driving every member downhill.
+                - 'sum': total fitness — same per-member gradient direction
+                  as 'mean', scaled by n_offsprings.
+                - 'min': best offspring only — gradient flows solely through
+                  the single best offspring's ancestry (sparse signal).
+            live_selection: Whether selection routing carries gradient back to
+                the population.
+                - True (default, "live"): re-evaluate the current population so
+                  the selection logits depend on the live parameter — the
+                  Gumbel-Softmax selection gradient then reaches the population
+                  (fully end-to-end differentiable generation). For a
+                  deterministic objective this re-evaluation reproduces the
+                  committed fitness values exactly, so it is graph
+                  reconstruction, not new sampling: it is intentionally NOT
+                  counted in the evaluation budget (n_evals). It is, however, a
+                  real extra objective pass (wall-clock/FLOPs). For a stochastic
+                  objective the values may differ from the committed fitness.
+                - False ("detached", memetic): selection uses the cached,
+                  detached committed fitness as fixed routing weights; gradient
+                  only refines positions. Cheaper (no extra pass), lower
+                  variance, and the correct choice for stochastic objectives.
+
         Returns:
-            Best fitness as a scalar tensor (for backprop).
-        
+            Reduced offspring fitness as a scalar tensor (for backprop).
+
         Raises:
             RuntimeError: If algorithm not initialized.
+            ValueError: If reduction is not one of 'mean', 'sum', 'min'.
         """
         if not self._is_initialized:
             raise RuntimeError(
                 "Algorithm not initialized. Call initialize(problem) first."
             )
-        
+
+        if reduction not in ("mean", "sum", "min"):
+            raise ValueError(
+                f"reduction must be one of 'mean', 'sum', 'min'; got {reduction!r}"
+            )
+
+        # Live selection: attach a fresh autograd graph to the parent fitness so
+        # selection gradients flow into the population. Deliberately does NOT
+        # increment n_evals (values match the committed fitness for a
+        # deterministic objective — this only rebuilds the graph).
+        if live_selection:
+            self.state.fitness = self._evaluate(self.population)
+
         # Generate offspring (differentiable)
         offspring = self._infill()
         
@@ -561,7 +600,12 @@ class Algorithm(nn.Module, ABC):
         self._pending_offspring = offspring
         self._pending_fitness = offspring_fitness
         
-        # Return best fitness as loss
+        # Reduce per-offspring fitness to the scalar loss for backprop.
+        if reduction == "mean":
+            return offspring_fitness.mean()
+        if reduction == "sum":
+            return offspring_fitness.sum()
+        # reduction == "min"
         return offspring_fitness.min()
     
     @torch.no_grad()

{evograd_diff-0.1.2 → evograd_diff-0.2.0}/evograd/core/maximize.py

@@ -168,6 +168,8 @@ def maximize(
     scheduler_patience: int = 50,
     scheduler_factor: float = 0.5,
     min_lr: float = 1e-6,
+    reduction: str = "mean",
+    live_selection: bool = True,
 ) -> Result:
     """
     Maximise an objective function using a population-based algorithm.
@@ -260,6 +262,8 @@ def maximize(
         scheduler_patience=scheduler_patience,
         scheduler_factor=scheduler_factor,
         min_lr=min_lr,
+        reduction=reduction,
+        live_selection=live_selection,
     )
     
     # Fix problem name in result

{evograd_diff-0.1.2 → evograd_diff-0.2.0}/evograd/core/minimize.py

@@ -93,7 +93,9 @@ def minimize(
     scheduler_patience: int = 50,
     scheduler_factor: float = 0.5,
     min_lr: float = 1e-6,
-) -> Result:    
+    reduction: str = "mean",
+    live_selection: bool = True,
+) -> Result:
     
     """
     Minimise an objective function using a population-based algorithm.
@@ -169,7 +171,17 @@ def minimize(
             reducing LR (for 'plateau' scheduler).
         scheduler_factor: Factor to multiply LR when reducing.
         min_lr: Minimum learning rate.
-    
+        reduction: Reduction used to turn the (n_offsprings,) offspring
+            fitness into the scalar loss in differentiable mode:
+            'mean' (default), 'sum', or 'min'. Only used when backprop is
+            active; ignored in classical mode.
+        live_selection: If True (default), selection routing carries gradient
+            to the population via a per-generation re-evaluation of the current
+            population (not counted in n_evals; deterministic objectives only —
+            see Algorithm.forward). If False, selection uses the cached,
+            detached fitness (memetic; cheaper; for stochastic objectives).
+            Only used when backprop is active.
+
     Returns:
         Result object containing:
             - best_solution: Best solution found
@@ -381,6 +393,8 @@ def minimize(
                 hyper_params,
                 grad_clip_pop,
                 grad_clip_hyper,
+                reduction,
+                live_selection,
             )
         else:
             algorithm.step()
@@ -680,6 +694,8 @@ def _step_differentiable(
     hyper_params: Optional[List],
     grad_clip_pop: Optional[float],
     grad_clip_hyper: Optional[float],
+    reduction: str = "mean",
+    live_selection: bool = True,
 ) -> float:
     """
     Perform one generation step with gradient-based updates.
@@ -709,7 +725,7 @@ def _step_differentiable(
         opt.zero_grad(set_to_none=True)
     
     # Forward pass (builds computation graph)
-    loss = algorithm.forward()
+    loss = algorithm.forward(reduction=reduction, live_selection=live_selection)
     
     # Backward pass
     loss.backward()

{evograd_diff-0.1.2 → evograd_diff-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "evograd-diff"
-version = "0.1.2"
+version = "0.2.0"
 description = "PyTorch-based framework for differentiable evolutionary computation and swarm intelligence"
 readme = "README.md"
 license = { text = "Apache-2.0" }
@@ -51,3 +51,14 @@ packages = ["evograd"]
 
 [tool.hatch.build.targets.wheel.force-include]
 "evograd/benchmarks/functions/cec2017/data.pkl" = "evograd/benchmarks/functions/cec2017/data.pkl"
+
+# Restrict the source distribution to the package and standard metadata so that
+# repo-only files (paper source, notebooks, .claude/, scratch scripts, lockfile)
+# are not shipped to PyPI.
+[tool.hatch.build.targets.sdist]
+include = [
+    "/evograd",
+    "/README.md",
+    "/LICENSE",
+    "/pyproject.toml",
+]

evograd_diff-0.1.2/.claude/settings.local.json

@@ -1,17 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git add *)",
-      "Bash(git commit -m ' *)",
-      "Bash(git push *)",
-      "Bash(uv build *)",
-      "Bash(python -m zipfile -l dist/evograd-0.1.0-py3-none-any.whl)",
-      "WebFetch(domain:pypi.org)",
-      "Bash(uv run *)",
-      "Bash(git check-ignore *)",
-      "Bash(uv lock *)",
-      "Bash(git stash *)",
-      "Bash(grep -n '```' README.md)"
-    ]
-  }
-}

evograd_diff-0.1.2/.python-version

@@ -1 +0,0 @@
-3.12