gp-elite 0.1.0__tar.gz

gp_elite-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sabri Hakou
+
+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.

gp_elite-0.1.0/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: gp-elite
+Version: 0.1.0
+Summary: Régression symbolique par programmation génétique — lois interprétables sur données expérimentales (pur Python/NumPy)
+Author: Sabri Hakou
+License: MIT
+Project-URL: Homepage, https://github.com/ariel95500-create/gp-elite
+Project-URL: Repository, https://github.com/ariel95500-create/gp-elite
+Project-URL: Issues, https://github.com/ariel95500-create/gp-elite/issues
+Keywords: symbolic-regression,genetic-programming,machine-learning,interpretable-ml,equation-discovery,scientific-computing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: scikit-learn>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# GP_ELITE
+
+**Genetic-programming symbolic regression — discover interpretable laws from your experimental data.**
+
+*[🇫🇷 Version française](README.fr.md)*
+
+GP_ELITE searches for a **mathematical formula** linking your variables to a target, instead of a black box. It is built for small experimental datasets (≤10 variables, 100–5000 points) where you want to *understand* the relationship: degradation laws, sensor calibration, engineering correlations, dose–response curves, physical laws.
+
+Pure **Python / NumPy** — no Julia, no compilation, no GPU. `pip install` and you're ready.
+
+```python
+from gp_elite import symbolic_regression
+
+result = symbolic_regression(X, y, feature_names=["cycle", "temperature", "current"])
+print(result.expression)        # capacity_SOH = 0.913 - 0.352·tanh(...)
+print(result.r2_validation)     # 0.996  (on data never seen during training)
+```
+
+---
+
+## Why GP_ELITE?
+
+| | GP_ELITE | Neural networks | PySR (state of the art) |
+|---|---|---|---|
+| Output | **readable formula** | black box | readable formula |
+| Installation | `pip install` (pure Python) | heavy | requires **Julia** |
+| Overfitting guard | **built-in** (hold-out) | do it yourself | do it yourself |
+| Variable selection | **importance report** | no | partial |
+
+GP_ELITE's niche: **zero barrier to entry**. A lab engineer, a student, or a technician points at a CSV file and gets a validated law back — without becoming a developer.
+
+---
+
+## Installation
+
+```bash
+pip install gp-elite          # from PyPI
+# or, from source:
+git clone https://github.com/ariel95500-create/gp-elite
+cd gp-elite && pip install -e .
+```
+
+Dependencies: `numpy`, `pandas`, `scikit-learn`.
+
+---
+
+## Usage
+
+### One line, on your own data (console UI)
+
+```bash
+gp-elite
+```
+
+Choose mode **6 (generic CSV)**, point to your file, and keep the defaults. GP_ELITE detects the columns, holds out a validation set, evolves, and prints the discovered law with its generalization report.
+
+### Programmatically (notebooks, pipelines)
+
+```python
+import numpy as np
+from gp_elite import symbolic_regression
+
+X = np.random.uniform(1, 5, (200, 2))
+y = 2.0 + 3.0 * np.sqrt(X[:, 0]) - 0.5 * X[:, 1]
+
+result = symbolic_regression(
+    X, y,
+    feature_names=["a", "b"],
+    operators="physical",   # 'physical' | 'trig' | 'full' | 'poly'
+    generations=60,
+    speed="fast",           # 'ultrafast' | 'fast' | 'normal'
+)
+
+print(result.expression)        # e.g. 2.0 + 3.0·sqrt(a) - 0.5·b
+print(result.r2_validation)     # quality on the hold-out set
+print(result.size)              # node count (readability)
+```
+
+---
+
+## Full example: battery degradation (NASA data)
+
+```bash
+python examples/battery_soh.py
+```
+
+From 168 real charge cycles, GP_ELITE discovers a state-of-health (SOH) law:
+
+```
+capacity_SOH ≈ 0.913 − 0.352 · tanh( cycle^((temperature/cycle)^0.485) )
+
+R² validation = 0.996   (on cycles never seen)   12 nodes
+```
+
+A saturating degradation with cycle count, modulated by temperature — physically plausible, and **certified on unseen data**.
+
+---
+
+## What is GP_ELITE good (and less good) at?
+
+**Good at**: physical / engineering laws with multiplicative or exponential structure, modest-size noisy experimental data, problems where interpretability matters most.
+
+On a representative subset of the **Feynman Symbolic Regression Benchmark** (16 physics equations), in `fast` mode (~15 s/equation): **81% of equations solved at R² > 0.999**, mean R² 0.993.
+
+**Less good at**: chaotic sequences (e.g. Collatz flight time — an intrinsically random component), >15–20 variables (the search space explodes), large datasets where raw accuracy outweighs interpretability (ensemble models dominate there).
+
+---
+
+## Technical features
+
+- **Asymmetric island model** (explorer / cleaner / stigmergic) with periodic migration
+- **Linear scaling** (Keijzer 2003): the engine searches for the *shape*; scale and offset coefficients are solved in closed form
+- **ε-lexicase selection** (La Cava 2016) to preserve behavioral diversity
+- **Island parallelism** (multi-core) — ≈ ×3 measured on 4 cores
+- **Hold-out validation** + parsimonious champion selection (R² tolerance): built-in overfitting guard
+- **Shift-free normalization** preserving multiplicative structure (x·y stays a clean product)
+- **Transferable stigmergic memory** across runs (grammar export/import)
+
+---
+
+## Tests
+
+```bash
+pip install pytest
+pytest -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Free to use, including commercially, with retention of the copyright notice.
+
+## Citing GP_ELITE
+
+If GP_ELITE is useful in academic work, see [CITATION.cff](CITATION.cff).

gp_elite-0.1.0/README.md

@@ -0,0 +1,136 @@
+# GP_ELITE
+
+**Genetic-programming symbolic regression — discover interpretable laws from your experimental data.**
+
+*[🇫🇷 Version française](README.fr.md)*
+
+GP_ELITE searches for a **mathematical formula** linking your variables to a target, instead of a black box. It is built for small experimental datasets (≤10 variables, 100–5000 points) where you want to *understand* the relationship: degradation laws, sensor calibration, engineering correlations, dose–response curves, physical laws.
+
+Pure **Python / NumPy** — no Julia, no compilation, no GPU. `pip install` and you're ready.
+
+```python
+from gp_elite import symbolic_regression
+
+result = symbolic_regression(X, y, feature_names=["cycle", "temperature", "current"])
+print(result.expression)        # capacity_SOH = 0.913 - 0.352·tanh(...)
+print(result.r2_validation)     # 0.996  (on data never seen during training)
+```
+
+---
+
+## Why GP_ELITE?
+
+| | GP_ELITE | Neural networks | PySR (state of the art) |
+|---|---|---|---|
+| Output | **readable formula** | black box | readable formula |
+| Installation | `pip install` (pure Python) | heavy | requires **Julia** |
+| Overfitting guard | **built-in** (hold-out) | do it yourself | do it yourself |
+| Variable selection | **importance report** | no | partial |
+
+GP_ELITE's niche: **zero barrier to entry**. A lab engineer, a student, or a technician points at a CSV file and gets a validated law back — without becoming a developer.
+
+---
+
+## Installation
+
+```bash
+pip install gp-elite          # from PyPI
+# or, from source:
+git clone https://github.com/ariel95500-create/gp-elite
+cd gp-elite && pip install -e .
+```
+
+Dependencies: `numpy`, `pandas`, `scikit-learn`.
+
+---
+
+## Usage
+
+### One line, on your own data (console UI)
+
+```bash
+gp-elite
+```
+
+Choose mode **6 (generic CSV)**, point to your file, and keep the defaults. GP_ELITE detects the columns, holds out a validation set, evolves, and prints the discovered law with its generalization report.
+
+### Programmatically (notebooks, pipelines)
+
+```python
+import numpy as np
+from gp_elite import symbolic_regression
+
+X = np.random.uniform(1, 5, (200, 2))
+y = 2.0 + 3.0 * np.sqrt(X[:, 0]) - 0.5 * X[:, 1]
+
+result = symbolic_regression(
+    X, y,
+    feature_names=["a", "b"],
+    operators="physical",   # 'physical' | 'trig' | 'full' | 'poly'
+    generations=60,
+    speed="fast",           # 'ultrafast' | 'fast' | 'normal'
+)
+
+print(result.expression)        # e.g. 2.0 + 3.0·sqrt(a) - 0.5·b
+print(result.r2_validation)     # quality on the hold-out set
+print(result.size)              # node count (readability)
+```
+
+---
+
+## Full example: battery degradation (NASA data)
+
+```bash
+python examples/battery_soh.py
+```
+
+From 168 real charge cycles, GP_ELITE discovers a state-of-health (SOH) law:
+
+```
+capacity_SOH ≈ 0.913 − 0.352 · tanh( cycle^((temperature/cycle)^0.485) )
+
+R² validation = 0.996   (on cycles never seen)   12 nodes
+```
+
+A saturating degradation with cycle count, modulated by temperature — physically plausible, and **certified on unseen data**.
+
+---
+
+## What is GP_ELITE good (and less good) at?
+
+**Good at**: physical / engineering laws with multiplicative or exponential structure, modest-size noisy experimental data, problems where interpretability matters most.
+
+On a representative subset of the **Feynman Symbolic Regression Benchmark** (16 physics equations), in `fast` mode (~15 s/equation): **81% of equations solved at R² > 0.999**, mean R² 0.993.
+
+**Less good at**: chaotic sequences (e.g. Collatz flight time — an intrinsically random component), >15–20 variables (the search space explodes), large datasets where raw accuracy outweighs interpretability (ensemble models dominate there).
+
+---
+
+## Technical features
+
+- **Asymmetric island model** (explorer / cleaner / stigmergic) with periodic migration
+- **Linear scaling** (Keijzer 2003): the engine searches for the *shape*; scale and offset coefficients are solved in closed form
+- **ε-lexicase selection** (La Cava 2016) to preserve behavioral diversity
+- **Island parallelism** (multi-core) — ≈ ×3 measured on 4 cores
+- **Hold-out validation** + parsimonious champion selection (R² tolerance): built-in overfitting guard
+- **Shift-free normalization** preserving multiplicative structure (x·y stays a clean product)
+- **Transferable stigmergic memory** across runs (grammar export/import)
+
+---
+
+## Tests
+
+```bash
+pip install pytest
+pytest -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE). Free to use, including commercially, with retention of the copyright notice.
+
+## Citing GP_ELITE
+
+If GP_ELITE is useful in academic work, see [CITATION.cff](CITATION.cff).

gp_elite-0.1.0/gp_elite/__init__.py

@@ -0,0 +1,34 @@
+"""
+GP_ELITE — Régression symbolique par programmation génétique (1-D, N-D, CSV).
+
+Découverte de lois empiriques interprétables sur petits jeux de données
+expérimentaux : ≤10 variables, 100-5000 points, où l'on veut une FORMULE
+plutôt qu'une boîte noire. Pur Python/NumPy, sans dépendance exotique.
+
+Caractéristiques principales
+----------------------------
+- Modèle en îles asymétriques (explorer / cleaner / stigmergic) avec migration
+- Linear scaling (Keijzer) + sélection ε-lexicase
+- Parallélisme des îles (ProcessPoolExecutor, multi-cœurs)
+- Validation hold-out + sélection parcimonieuse du champion (tolérance R²)
+- Normalisation shift-free préservant la structure multiplicative
+- Mode CSV générique : pointez un fichier, obtenez une loi validée
+- Mémoire stigmergique transférable entre exécutions
+
+Exemple minimal
+---------------
+>>> import numpy as np
+>>> from gp_elite import symbolic_regression
+>>> X = np.random.uniform(1, 5, (200, 2))
+>>> y = 2.0 + 3.0 * np.sqrt(X[:, 0]) - 0.5 * X[:, 1]
+>>> result = symbolic_regression(X, y, feature_names=["a", "b"], generations=40)
+>>> print(result.expression)   # ex : 2.0 + 3.0*sqrt(a) - 0.5*b
+>>> print(result.r2_validation)
+"""
+
+from .api import symbolic_regression, SRResult
+from . import core
+
+__version__ = "0.1.0"
+
+__all__ = ["symbolic_regression", "SRResult", "core", "__version__"]

gp_elite-0.1.0/gp_elite/__main__.py

@@ -0,0 +1,5 @@
+"""Permet `python -m gp_elite` → lance le menu interactif."""
+from .cli import main
+
+if __name__ == "__main__":
+    main()

gp_elite-0.1.0/gp_elite/api.py

@@ -0,0 +1,171 @@
+"""
+API haut niveau de GP_ELITE.
+
+Expose une fonction unique `symbolic_regression(X, y, ...)` qui encapsule le
+moteur d'évolution et retourne un objet résultat propre. Pensé pour l'usage
+programmatique (notebooks, pipelines) ; le menu interactif reste accessible
+via la CLI `gp-elite` ou `python -m gp_elite`.
+"""
+from __future__ import annotations
+
+import io
+import random
+import contextlib
+from dataclasses import dataclass
+from typing import Optional, Sequence
+
+import numpy as np
+
+from . import core
+
+
+@dataclass
+class SRResult:
+    """Résultat d'une régression symbolique.
+
+    Attributs
+    ---------
+    expression       : str   — la formule trouvée (noms de colonnes si fournis)
+    r2_validation    : float — R² sur le hold-out (None si validation désactivée)
+    mse_validation   : float — MSE sur le hold-out
+    mse_train        : float — MSE sur l'entraînement
+    size             : int   — nombre de nœuds de l'arbre
+    depth            : int   — profondeur de l'arbre
+    feature_names    : list  — noms des variables
+    node             : core.Node — l'arbre brut (pour évaluation / inspection)
+    predict          : callable — predict(X_norm) -> ndarray
+    """
+    expression: str
+    r2_validation: Optional[float]
+    mse_validation: Optional[float]
+    mse_train: float
+    size: int
+    depth: int
+    feature_names: list
+    node: "core.Node"
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """Prédit sur des features DÉJÀ normalisées (mêmes échelles que le fit)."""
+        return core.evaluate_vector(self.node, np.asarray(X, dtype=float))
+
+    def __str__(self) -> str:
+        r2 = f"{self.r2_validation:.4f}" if self.r2_validation is not None else "n/a"
+        return (f"SRResult(expr='{self.expression}', "
+                f"R²_val={r2}, size={self.size})")
+
+
+def symbolic_regression(
+    X: np.ndarray,
+    y: np.ndarray,
+    feature_names: Optional[Sequence[str]] = None,
+    *,
+    operators: str = "physical",
+    normalize: str = "auto",
+    generations: int = 100,
+    speed: str = "fast",
+    parallel: Optional[bool] = None,
+    validation_split: float = 0.20,
+    seed: Optional[int] = None,
+    verbose: bool = False,
+) -> SRResult:
+    """Trouve une expression symbolique reliant X à y.
+
+    Paramètres
+    ----------
+    X : ndarray (n_samples, n_features)  — variables explicatives (valeurs brutes)
+    y : ndarray (n_samples,)             — cible
+    feature_names : noms des colonnes (sinon X0, X1, …) — apparaissent dans la formule
+    operators : 'physical' | 'trig' | 'full' | 'poly'  — pool d'opérateurs
+    normalize : 'auto' | 'divmax' | 'minmax' | 'standard'
+                'auto' = shift-free si toutes les features sont positives
+    generations : nombre de générations
+    speed : 'ultrafast' | 'fast' | 'normal'  — taille population / îles
+    parallel : True force le multi-processus, False le désactive,
+               None = auto (≥4 cœurs)
+    validation_split : fraction hold-out (0.0 = pas de validation)
+    seed : graine de reproductibilité
+    verbose : True affiche les logs détaillés du moteur
+
+    Retourne
+    --------
+    SRResult
+    """
+    X = np.asarray(X, dtype=float)
+    y = np.asarray(y, dtype=float)
+    if X.ndim != 2:
+        raise ValueError(f"X doit être 2-D (n_samples, n_features), reçu {X.shape}")
+    if y.ndim != 1 or len(y) != len(X):
+        raise ValueError("y doit être 1-D de même longueur que X")
+    n_feat = X.shape[1]
+
+    if feature_names is None:
+        feature_names = [f"X{i}" for i in range(n_feat)]
+    feature_names = list(feature_names)
+    if len(feature_names) != n_feat:
+        raise ValueError("feature_names doit avoir une entrée par colonne de X")
+
+    if seed is not None:
+        random.seed(seed)
+        np.random.seed(seed)
+
+    # ── Normalisation (réutilise le sélecteur du moteur) ──
+    scaler, _desc = core._choose_scaler(X, normalize, (-2.0, 2.0))
+    X_scaled = scaler.fit_transform(X)
+
+    # ── Pool d'opérateurs + noms de colonnes (mode CSV générique) ──
+    pool = (operators or "physical").lower()
+    if pool not in core._GENCSV_POOLS:
+        pool = "physical"
+    b_ops, b_w, u_ops, u_w = core._GENCSV_POOLS[pool]
+    core._GENERIC_BINARY_OPS, core._GENERIC_BINARY_WEIGHTS = list(b_ops), list(b_w)
+    core._GENERIC_UNARY_OPS, core._GENERIC_UNARY_WEIGHTS = list(u_ops), list(u_w)
+    core._GENERIC_CSV_MODE = True
+    core.CSV_FEATURE_NAMES = list(feature_names)
+    core.CSV_TARGET_NAME = "y"
+
+    fast = (speed == "fast")
+    ultrafast = (speed == "ultrafast")
+
+    cfg = core.make_cfg_nd(n_features=n_feat, x_min=-2.0, x_max=2.0,
+                           fast=fast, ultrafast=ultrafast, use_seeding=False,
+                           use_lib=True, use_cograph=True, use_seqmem=True)
+    cfg.GENERATIONS = int(generations)
+    cfg.N_POINTS = len(y)
+    cfg.VALIDATION_SPLIT = float(validation_split)
+    if parallel is not None:
+        cfg.PARALLEL_ISLANDS = bool(parallel)
+
+    _placeholder = lambda Xm: np.zeros(Xm.shape[0])
+    sink = contextlib.nullcontext() if verbose else contextlib.redirect_stdout(io.StringIO())
+    try:
+        with sink:
+            best, X_full, y_full = core.evolve(
+                _placeholder, cfg, problem_key="GENERIC_CSV",
+                X_override=X_scaled, y_override=y)
+        # Capturer l'expression PENDANT que le mode CSV est actif, pour que
+        # to_string substitue bien les noms de colonnes (a, b, …) à X[i].
+        expression = core.to_string(best)
+    finally:
+        core._GENERIC_CSV_MODE = False
+
+    # ── Métriques ──
+    mse_tr = core._pure_mse(best, X_full, y_full)
+    val_xs = getattr(core, "_VAL_XS", None)
+    val_ys = getattr(core, "_VAL_YS", None)
+    r2_val = mse_val = None
+    if val_xs is not None and val_ys is not None and len(val_ys) > 1:
+        preds = core.evaluate_vector(best, val_xs)
+        mse_val = float(np.mean((preds - val_ys) ** 2))
+        var = float(np.var(val_ys))
+        r2_val = (1.0 - mse_val / var) if var > 1e-15 else float("nan")
+
+    return SRResult(
+        expression=expression,
+        r2_validation=r2_val,
+        mse_validation=mse_val,
+        mse_train=float(mse_tr),
+        size=core.tree_size(best),
+        depth=core.tree_depth(best),
+        feature_names=feature_names,
+        node=best,
+    )

gp_elite-0.1.0/gp_elite/cli.py

@@ -0,0 +1,32 @@
+"""Point d'entrée ligne de commande : `gp-elite` ou `python -m gp_elite`.
+
+Lance le menu interactif du moteur (modes 1-D, N-D, Syracuse, CSV générique).
+Le guard if __name__ est requis pour le parallélisme (multiprocessing spawn).
+"""
+import sys
+import traceback
+
+from . import core
+
+
+def main():
+    try:
+        core._interactive_menu()
+    except KeyboardInterrupt:
+        print("\nInterrompu.")
+        sys.exit(130)
+    except Exception:
+        print("\n" + "=" * 70)
+        print("ERREUR FATALE — traceback complet :")
+        print("=" * 70)
+        traceback.print_exc()
+        print("=" * 70)
+        try:
+            input("\nAppuyez sur Entrée pour quitter...")
+        except Exception:
+            pass
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()