{"id":47623075,"url":"https://github.com/urmzd/linear-gp","last_synced_at":"2026-04-19T21:11:29.764Z","repository":{"id":38180544,"uuid":"485165805","full_name":"urmzd/linear-gp","owner":"urmzd","description":"A production-grade Rust framework for Linear Genetic Programming research, featuring modular architecture, Q-Learning integration, automated hyperparameter optimization, and support for reinforcement learning and classification tasks.","archived":false,"fork":false,"pushed_at":"2026-04-02T03:43:03.000Z","size":48876,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-02T06:29:30.206Z","etag":null,"topics":["evolutionary-algorithms","genetic-algorithm","genetic-programming","linear-algebra","linear-genetic-programming","machine-learning","optimization","parallel-computing","reinforcement-learning","rust"],"latest_commit_sha":null,"homepage":"https://github.com/urmzd/linear-gp","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urmzd.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2022-04-24T23:36:09.000Z","updated_at":"2026-03-30T06:55:20.000Z","dependencies_parsed_at":"2024-01-12T23:37:13.637Z","dependency_job_id":"10ff83ea-d306-4944-bd21-e6f0c3d5a46d","html_url":"https://github.com/urmzd/linear-gp","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/urmzd/linear-gp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Flinear-gp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Flinear-gp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Flinear-gp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Flinear-gp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urmzd","download_url":"https://codeload.github.com/urmzd/linear-gp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urmzd%2Flinear-gp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31588039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-09T05:33:47.836Z","status":"ssl_error","status_checked_at":"2026-04-09T05:32:26.579Z","response_time":112,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["evolutionary-algorithms","genetic-algorithm","genetic-programming","linear-algebra","linear-genetic-programming","machine-learning","optimization","parallel-computing","reinforcement-learning","rust"],"created_at":"2026-04-01T22:26:36.249Z","updated_at":"2026-04-19T21:11:29.757Z","avatar_url":"https://github.com/urmzd.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003elinear-gp\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\n    A Rust framework for solving reinforcement learning and classification tasks using Linear Genetic Programming (LGP).\n    \u003cbr /\u003e\u003cbr /\u003e\n    \u003ca href=\"https://github.com/urmzd/linear-gp/releases\"\u003eDownload\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/urmzd/linear-gp/issues\"\u003eReport Bug\u003c/a\u003e\n    \u0026middot;\n    \u003ca href=\"https://github.com/urmzd/linear-gp/tree/main/outputs\"\u003eExperiments\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/urmzd/linear-gp/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/urmzd/linear-gp/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u0026nbsp;\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/urmzd/linear-gp\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## Showcase\n\n\u003ctable align=\"center\"\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"showcase/list-experiments.gif\" alt=\"lgp list\" width=\"400\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eAvailable Experiments\u003c/b\u003e\u003c/sub\u003e\n    \u003c/td\u003e\n    \u003ctd align=\"center\"\u003e\n      \u003cimg src=\"showcase/run-experiment.gif\" alt=\"lgp run\" width=\"400\" /\u003e\n      \u003cbr /\u003e\n      \u003csub\u003e\u003cb\u003eRunning an Experiment\u003c/b\u003e\u003c/sub\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### Iris Classification — Operator Comparison\n\nComparison of four experiments (population 100, 200 generations, seed 42), each isolating a different genetic operator.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"showcase/iris-comparison.png\" alt=\"Fitness over generations for all four Iris experiments\" width=\"800\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"showcase/final-accuracy.png\" alt=\"Final best accuracy by experiment\" width=\"800\"\u003e\n\u003c/p\u003e\n\n| Experiment | Operators | Final Accuracy | Description |\n|------------|-----------|----------------|-------------|\n| `iris_baseline` | None | 33.3% | Pure elitism — population converges to a single individual |\n| `iris_mutation` | Mutation | 66.7% | Random instruction perturbation explores nearby program space |\n| `iris_crossover` | Crossover | 97.3% | Two-point crossover recombines instruction sequences from fit parents |\n| `iris_full` | Both | 90.7% | Full GP with mutation + crossover |\n\n\u003e Crossover dominates on this problem: recombining proven instruction subsequences is more effective than random perturbation. The shaded regions show the spread between worst and best fitness in each generation.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eHow It Works\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\n┌─────────────────────────────────────────────────────────┐\n│                    LGP Execution Model                  │\n├─────────────────────────────────────────────────────────┤\n│                                                         │\n│  Input Features          Registers (r0..r3)             │\n│  ┌──────────────┐        ┌─────┬─────┬─────┬─────┐     │\n│  │ sepal_length │        │ r0  │ r1  │ r2  │ r3  │     │\n│  │ sepal_width  │───────▶│Set. │Ver. │Vir. │Scr. │     │\n│  │ petal_length │        └──┬──┴──┬──┴──┬──┴──┬──┘     │\n│  │ petal_width  │           │     │     │     │         │\n│  └──────────────┘           ▼     ▼     ▼     ▼         │\n│                          ┌─────────────────────┐        │\n│                          │  Execute N instrs   │        │\n│                          │  r[s] = r[s] op x   │        │\n│                          └─────────┬───────────┘        │\n│                                    │                    │\n│                                    ▼                    │\n│                          ┌─────────────────────┐        │\n│                          │  argmax(r0, r1, r2) │        │\n│                          │  → predicted class   │        │\n│                          └─────────────────────┘        │\n│                                                         │\n│  Instruction Modes:                                     │\n│    Internal: r[src] = r[src] op r[tgt]                  │\n│    External: r[src] = r[src] op (factor × input[tgt])   │\n│                                                         │\n└─────────────────────────────────────────────────────────┘\n```\n\nEach individual is a sequence of register-machine instructions. Programs operate on **4 registers** (r0-r2 map to Iris classes, r3 is scratch). After execution, the class with the highest action register value is the prediction. Programs are evolved through elitist selection, crossover, and mutation over generations.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eRegenerate showcase\u003c/b\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```bash\n# Terminal GIFs (requires teasr: cargo install teasr-cli)\nteasr showme\n\n# Plotters charts (run all four experiments first)\nlgp run iris_baseline --override hyperparameters.seed=42\nlgp run iris_mutation --override hyperparameters.seed=42\nlgp run iris_crossover --override hyperparameters.seed=42\nlgp run iris_full --override hyperparameters.seed=42\ncargo run -p lgp --example generate_showcase --features plot\n```\n\n\u003c/details\u003e\n\n## Contents\n\n- [Overview](#overview)\n- [Install](#install)\n- [Quick Start](#quick-start)\n- [CLI Reference](#cli-reference)\n- [Performance](#performance)\n- [Hyperparameter Search](#hyperparameter-search)\n- [Visualizations](#visualizations)\n- [Output Structure](#output-structure)\n- [Logging](#logging)\n- [Packages](#packages)\n- [Extending the Framework](#extending-the-framework)\n- [Thesis \u0026 References](#thesis--references)\n- [Agent Skill](#agent-skill)\n- [License](#license)\n\n## Overview\n\nLinear Genetic Programming (LGP) is a variant of genetic programming that evolves sequences of instructions operating on registers, similar to machine code. This framework provides:\n\n- **Modular architecture** - Trait-based design for easy extension to new problem domains\n- **Multiple problem types** - Built-in support for OpenAI Gym environments and classification tasks\n- **Q-Learning integration** - Hybrid LGP + Q-Learning for enhanced reinforcement learning\n- **Hyperparameter search** - Built-in random search with parallel evaluation\n- **Parallel evaluation** - Rayon-powered parallel fitness evaluation\n- **Experiment automation** - Full pipeline: search, run, and analyze from a single CLI\n- **Optional plotting** - PNG chart generation via `plotters` (behind `--features plot`)\n\n### Supported Environments\n\n| Environment | Type | Inputs | Actions | Description |\n|-------------|------|--------|---------|-------------|\n| CartPole | RL | 4 | 2 | Balance a pole on a moving cart |\n| MountainCar | RL | 2 | 3 | Drive a car up a steep mountain |\n| Iris | Classification | 4 | 3 | Classify iris flower species |\n\n## Install\n\n**Prebuilt binary (recommended):**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/urmzd/linear-gp/main/install.sh | sh\n```\n\nYou can pin a version or change the install directory:\n\n```bash\nLGP_VERSION=v1.0.0 LGP_INSTALL_DIR=~/.local/bin \\\n  curl -fsSL https://raw.githubusercontent.com/urmzd/linear-gp/main/install.sh | sh\n```\n\n**From source:**\n\n```bash\ngit clone https://github.com/urmzd/linear-gp.git \u0026\u0026 cd linear-gp\ncargo install --path crates/lgp-cli\n```\n\n## Quick Start\n\n```bash\n# List available experiments\nlgp list\n\n# Run CartPole with pure LGP\nlgp run cart_pole_lgp\n\n# Run Iris classification\nlgp run iris_baseline\n\n```\n\n### Examples\n\nRun the standalone Rust examples directly with cargo:\n\n```bash\ncargo run -p lgp-core --example cart_pole --features gym\ncargo run -p lgp-core --example iris_classification\n```\n\n## CLI Reference\n\n```bash\n# Run experiment with default config\nlgp run iris_baseline\n\n# Run with optimal config (after search)\nlgp run iris_baseline --config optimal\n\n# Run with parameter overrides\nlgp run iris_baseline --override hyperparameters.program.max_instructions=50\n\n# Q-learning parameter overrides\nlgp run cart_pole_with_q --override operations.q_learning.alpha=0.5\n\n# Preview config (dry-run)\nlgp run iris_baseline --dry-run\n\n# Search hyperparameters\nlgp search iris_baseline\nlgp search iris_baseline --n-trials 20 --n-threads 8\n\n# Analyze results (generates CSV tables + optional PNG plots)\nlgp analyze\nlgp analyze --input outputs --output outputs\n\n# Run full experiment pipeline (search -\u003e run -\u003e analyze)\nlgp experiment iris_baseline\nlgp experiment iris_baseline --iterations 20\nlgp experiment --skip-search\n```\n\n### Available Experiments\n\n| Experiment | Description | Median run |\n|------------|-------------|-----------:|\n| `iris_baseline` | Iris baseline (no mutation, no crossover) | 0.21s |\n| `iris_mutation` | Iris with mutation only | 0.37s |\n| `iris_crossover` | Iris with crossover only | 1.19s |\n| `iris_full` | Iris full (mutation + crossover) | 0.43s |\n| `cart_pole_lgp` | CartPole with pure LGP | 0.15s |\n| `cart_pole_with_q` | CartPole with Q-Learning | 0.16s |\n| `mountain_car_lgp` | MountainCar with pure LGP | 2.06s |\n| `mountain_car_with_q` | MountainCar with Q-Learning | 2.23s |\n\n## Performance\n\nWall-clock times for `lgp run \u003cexperiment\u003e --override hyperparameters.seed=42` with the bundled default configs, built with `cargo build --release`. Fitness evaluation is parallelized across the population via `rayon`, so numbers scale with core count.\n\n**Hardware:** Apple M4 Pro (12 cores), 24 GB RAM, macOS. **Samples:** n=100 per experiment.\n\n| Experiment | min | median | mean | p95 | max |\n|------------|----:|-------:|-----:|----:|----:|\n| `iris_baseline` | 0.15s | 0.21s | 0.21s | 0.24s | 0.25s |\n| `iris_mutation` | 0.10s | 0.37s | 0.34s | 0.48s | 0.57s |\n| `iris_crossover` | 0.20s | 1.19s | 1.28s | 2.51s | 3.56s |\n| `iris_full` | 0.13s | 0.43s | 0.41s | 0.66s | 0.84s |\n| `cart_pole_lgp` | 0.14s | 0.15s | 0.16s | 0.16s | 0.49s |\n| `cart_pole_with_q` | 0.16s | 0.16s | 0.16s | 0.17s | 0.18s |\n| `mountain_car_lgp` | 1.54s | 2.06s | 2.20s | 2.92s | 4.54s |\n| `mountain_car_with_q` | 1.69s | 2.23s | 2.40s | 3.30s | 4.78s |\n\nRunning all 8 experiments sequentially takes ≈ 7s at the medians. `iris_crossover` has the widest spread — recombining variable-length programs produces runs with meaningfully more instructions to execute. MountainCar dominates wall-clock time because episodes run the full 200-step default, while CartPole episodes terminate early when the pole falls.\n\n## Hyperparameter Search\n\nThe framework includes built-in hyperparameter search with parallel evaluation via `rayon`.\n\n```bash\n# Search for a specific config\nlgp search cart_pole_lgp\n\n# Search all configs (LGP first, then Q-Learning)\nlgp search\n\n# Search with custom options\nlgp search cart_pole_with_q --n-trials 100 --n-threads 8 --median-trials 15\n```\n\n### Parameters Searched\n\n| Parameter | Range |\n|-----------|-------|\n| `max_instructions` | 1-100 |\n| `external_factor` | 0.0-100.0 |\n| `alpha` (Q-Learning) | 0.0-1.0 |\n| `gamma` (Q-Learning) | 0.0-1.0 |\n| `epsilon` (Q-Learning) | 0.0-1.0 |\n| `alpha_decay` (Q-Learning) | 0.0-1.0 |\n| `epsilon_decay` (Q-Learning) | 0.0-1.0 |\n\nResults are saved to:\n- `outputs/parameters/\u003cconfig\u003e.json`\n- `configs/\u003cconfig\u003e/optimal.toml`\n\n## Visualizations\n\n```bash\n# Analyze results (generates CSV tables)\nlgp analyze\n\n# Build with plot feature for PNG chart generation\ncargo install --path crates/lgp-cli --features plot\nlgp analyze\n```\n\n## Output Structure\n\n```\noutputs/\n├── parameters/                 # Optimized hyperparameters (JSON)\n│   ├── cart_pole_lgp.json\n│   └── ...\n├── \u003cexperiment\u003e/               # Experiment outputs (timestamped runs)\n│   └── \u003ctimestamp\u003e/\n│       ├── config/\n│       │   └── config.toml     # Resolved config with seed/timestamp\n│       ├── outputs/\n│       │   ├── best.json       # Best individual from final generation\n│       │   ├── median.json     # Median individual\n│       │   ├── worst.json      # Worst individual\n│       │   ├── population.json # Full population history\n│       │   └── params.json     # Hyperparameters used\n│       └── post_process/       # Post-processing outputs\n├── tables/                     # Generated CSV statistics\n│   └── \u003cexperiment\u003e.csv\n└── figures/                    # Generated PNG plots (with --features plot)\n    └── \u003cexperiment\u003e.png\n```\n\n## Logging\n\n```bash\n# Default (info level, pretty format)\nlgp run iris_baseline\n\n# Verbose mode (debug level)\nlgp -v run iris_baseline\n\n# JSON format for log aggregation\nlgp --log-format json run iris_baseline\n\n# Fine-grained control via RUST_LOG\nRUST_LOG=lgp=debug lgp run iris_baseline\nRUST_LOG=lgp::core=trace,lgp=info lgp run iris_baseline\n```\n\n| Level | Use Case |\n|-------|----------|\n| `error` | Fatal issues only |\n| `warn` | Potential problems |\n| `info` | Progress updates (default) |\n| `debug` | Detailed diagnostics |\n| `trace` | Instruction-by-instruction execution |\n\n## Packages\n\n| Package | Description |\n|---------|-------------|\n| [lgp-core](crates/lgp/README.md) | Core library — traits, evolutionary engine, built-in problems |\n| [lgp](crates/lgp-cli/README.md) | CLI binary for running experiments, search, and analysis |\n\n## Extending the Framework\n\nThe framework is built around these key traits:\n\n- **`State`** - Represents an environment state with value access and action execution\n- **`RlState`** - Extends State for RL environments with terminal state detection\n- **`Core`** - Main trait defining the genetic algorithm components\n- **`Fitness`** - Evaluates individual performance on states\n- **`Breed`** - Two-point crossover for creating offspring\n- **`Mutate`** - Mutation operators for genetic variation\n\nYou can add new classification problems, RL environments, genetic operators, and fitness functions. See [skills/lgp-experiment/SKILL.md](skills/lgp-experiment/SKILL.md) for the complete guide.\n\n## Thesis \u0026 References\n\nThe accompanying thesis, *Reinforced Linear Genetic Programming*, and full references are maintained in a [separate repository](https://github.com/urmzd/rlgp-thesis).\n\n## Agent Skill\n\nThis repo's conventions are available as portable agent skills in [`skills/`](skills/).\n\n## License\n\n[Apache-2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furmzd%2Flinear-gp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furmzd%2Flinear-gp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furmzd%2Flinear-gp/lists"}