From 380d69e35f50dbdf2aa21d75579a00326d26ffe9 Mon Sep 17 00:00:00 2001 From: Urmzd Mukhammadnaim Date: Sun, 29 Mar 2026 01:16:25 -0500 Subject: [PATCH 1/4] docs: simplify README to focus on install.sh and core usage Strip verbose sections (architecture, output structure, hyperparameter details, full CLI reference) in favor of a concise install + usage flow. The prebuilt binary install via install.sh is now the recommended path. --- README.md | 351 +++++++----------------------------------------------- 1 file changed, 42 insertions(+), 309 deletions(-) diff --git a/README.md b/README.md index 0c188985..3446914e 100644 --- a/README.md +++ b/README.md @@ -21,335 +21,86 @@ LGP experiment output

-## Overview +## Install -Linear Genetic Programming (LGP) is a variant of genetic programming that evolves sequences of instructions operating on registers, similar to machine code. This framework provides: - -- **Modular architecture** - Trait-based design for easy extension to new problem domains -- **Multiple problem types** - Built-in support for OpenAI Gym environments and classification tasks -- **Q-Learning integration** - Hybrid LGP + Q-Learning for enhanced reinforcement learning -- **Hyperparameter search** - Built-in random search with parallel evaluation -- **Parallel evaluation** - Rayon-powered parallel fitness evaluation -- **Experiment automation** - Full pipeline: search, run, and analyze from a single CLI -- **Optional plotting** - PNG chart generation via `plotters` (behind `--features plot`) - -### Supported Environments - -| Environment | Type | Inputs | Actions | Description | -|-------------|------|--------|---------|-------------| -| CartPole | RL | 4 | 2 | Balance a pole on a moving cart | -| MountainCar | RL | 2 | 3 | Drive a car up a steep mountain | -| Iris | Classification | 4 | 3 | Classify iris flower species | - -## Quick Start - -### Prerequisites - -| Dependency | Version | Installation | -|------------|---------|--------------| -| Rust | 1.70+ | [rustup.rs](https://rustup.rs/) | - -### Installation - -```bash -# Clone the repository -git clone https://github.com/urmzd/linear-gp.git -cd linear-gp - -# Install the lgp binary -cargo install --path crates/lgp-cli -``` - -### First Experiment +**Prebuilt binary (recommended):** ```bash -# List available experiments -lgp list - -# Run CartPole with pure LGP -lgp run cart_pole_lgp - -# Run Iris classification -lgp run iris_baseline - -# Run an example -lgp example cart_pole - -# Run benchmarks -cargo bench -``` - -## Packages - -| Package | Path | Description | -|---------|------|-------------| -| [lgp](crates/lgp/README.md) | `crates/lgp` | Core Rust library — traits, evolutionary engine, built-in problems | -| [lgp-cli](crates/lgp-cli/README.md) | `crates/lgp-cli` | CLI binary (`lgp`) for running experiments, search, and analysis | - -## Project Architecture - -``` -linear-gp/ -├── crates/ -│ ├── lgp/ # Core LGP library -│ │ ├── src/ -│ │ │ ├── lib.rs # Library exports -│ │ │ ├── core/ # Core LGP implementation -│ │ │ ├── problems/ # Problem implementations -│ │ │ ├── extensions/ # Extended functionality -│ │ │ └── utils/ # Utility functions -│ │ ├── benches/ # Performance benchmarks -│ │ └── tests/ # Integration tests -│ └── lgp-cli/ # CLI application -│ └── src/ -│ ├── main.rs # CLI entry point -│ ├── commands/ # Subcommands (run, list, search, analyze, experiment) -│ ├── config_discovery.rs -│ ├── config_override.rs -│ └── experiment_runner.rs -├── configs/ # Experiment configurations -│ ├── iris_baseline/default.toml -│ ├── cart_pole_lgp/default.toml -│ └── ... -├── outputs/ # Experiment outputs -│ ├── parameters/ # Optimized hyperparameters (JSON) -│ ├── / # Per-experiment outputs -│ │ └── / # Timestamped runs -│ ├── tables/ # CSV statistics -│ └── figures/ # PNG plots -└── skills/ # Agent skills & documentation +curl -fsSL https://raw.githubusercontent.com/urmzd/linear-gp/main/install.sh | bash ``` -### Core Traits - -The framework is built around these key traits: - -- **`State`** - Represents an environment state with value access and action execution -- **`RlState`** - Extends State for RL environments with terminal state detection -- **`Core`** - Main trait defining the genetic algorithm components -- **`Fitness`** - Evaluates individual performance on states -- **`Breed`** - Two-point crossover for creating offspring -- **`Mutate`** - Mutation operators for genetic variation - -See [skills/lgp-experiment/SKILL.md](skills/lgp-experiment/SKILL.md#core-traits) for detailed trait documentation. - -## Logging and Tracing - -The framework includes comprehensive structured logging via the [tracing](https://docs.rs/tracing) ecosystem. - -### Quick Start +You can pin a version or change the install directory: ```bash -# Default (info level, pretty format) -lgp run iris_baseline - -# Verbose mode (debug level) -lgp -v run iris_baseline - -# JSON format for log aggregation -lgp --log-format json run iris_baseline +LGP_VERSION=v1.0.0 LGP_INSTALL_DIR=~/.local/bin \ + curl -fsSL https://raw.githubusercontent.com/urmzd/linear-gp/main/install.sh | bash ``` -### Environment Variables - -| Variable | Description | Example | -|----------|-------------|---------| -| `RUST_LOG` | Control log level filtering | `lgp=debug`, `lgp=trace` | -| `LGP_LOG_FORMAT` | Override output format | `pretty`, `compact`, `json` | - -### Log Level Guide - -| Level | Use Case | Example Output | -|-------|----------|----------------| -| `error` | Fatal issues only | Panics, unrecoverable errors | -| `warn` | Potential problems | Deprecated features, suspicious values | -| `info` | Progress updates (default) | Generation stats, experiment start/complete | -| `debug` | Detailed diagnostics | Config loading, individual fitness scores | -| `trace` | Very verbose | Instruction execution, Q-table updates | - -### Examples +**From source:** ```bash -# Debug level for LGP crate only -RUST_LOG=lgp=debug lgp run iris_baseline - -# Trace level (very verbose - instruction-by-instruction) -RUST_LOG=lgp=trace lgp run iris_baseline - -# Different levels for different modules -RUST_LOG=lgp::core=trace,lgp=info lgp run iris_baseline - -# JSON output for log aggregation (ELK, Datadog, etc.) -lgp --log-format json run iris_baseline 2>&1 | jq . +git clone https://github.com/urmzd/linear-gp.git && cd linear-gp +cargo install --path crates/lgp-cli ``` -## CLI Reference +## Usage ```bash # List available experiments lgp list -# Run experiment with default config +# Run an experiment lgp run iris_baseline - -# Run with optimal config (after search) -lgp run iris_baseline --config optimal - -# Run with overrides -lgp run iris_baseline --override hyperparameters.program.max_instructions=50 - -# Q-learning parameter overrides -lgp run cart_pole_with_q --override operations.q_learning.alpha=0.5 - -# Preview config (dry-run) -lgp run iris_baseline --dry-run - -# Search hyperparameters -lgp search iris_baseline -lgp search iris_baseline --n-trials 20 --n-threads 8 - -# Analyze results (generates CSV tables + optional PNG plots) -lgp analyze -lgp analyze --input outputs --output outputs - -# Run full experiment pipeline (search -> run -> analyze) -lgp experiment iris_baseline -lgp experiment iris_baseline --iterations 20 -lgp experiment --skip-search +lgp run cart_pole_lgp # Run a Rust example lgp example cart_pole -# List available examples -lgp example --list -``` - -**Available Experiments:** - -| Experiment | Description | -|------------|-------------| -| `iris_baseline` | Iris baseline (no mutation, no crossover) | -| `iris_mutation` | Iris with mutation only | -| `iris_crossover` | Iris with crossover only | -| `iris_full` | Iris full (mutation + crossover) | -| `cart_pole_lgp` | CartPole with pure LGP | -| `cart_pole_with_q` | CartPole with Q-Learning | -| `mountain_car_lgp` | MountainCar with pure LGP | -| `mountain_car_with_q` | MountainCar with Q-Learning | - -## Hyperparameter Search - -The framework includes built-in hyperparameter search with parallel evaluation via `rayon`. - -### Running Search - -```bash -# Search for a specific config -lgp search cart_pole_lgp - -# Search all configs (LGP first, then Q-Learning) -lgp search +# Search for optimal hyperparameters +lgp search iris_baseline -# Search with custom options -lgp search cart_pole_with_q --n-trials 100 --n-threads 8 --median-trials 15 +# Full pipeline: search -> run -> analyze +lgp experiment iris_baseline ``` -### Parameters Searched - -| Parameter | Range | -|-----------|-------| -| `max_instructions` | 1-100 | -| `external_factor` | 0.0-100.0 | -| `alpha` (Q-Learning) | 0.0-1.0 | -| `gamma` (Q-Learning) | 0.0-1.0 | -| `epsilon` (Q-Learning) | 0.0-1.0 | -| `alpha_decay` (Q-Learning) | 0.0-1.0 | -| `epsilon_decay` (Q-Learning) | 0.0-1.0 | +### Available Experiments -Results are saved to: -- `outputs/parameters/.json` -- `configs//optimal.toml` +| Experiment | Type | Description | +|------------|------|-------------| +| `iris_baseline` | Classification | Iris (no mutation, no crossover) | +| `iris_mutation` | Classification | Iris with mutation only | +| `iris_crossover` | Classification | Iris with crossover only | +| `iris_full` | Classification | Iris full (mutation + crossover) | +| `cart_pole_lgp` | RL | CartPole with pure LGP | +| `cart_pole_with_q` | RL | CartPole with Q-Learning | +| `mountain_car_lgp` | RL | MountainCar with pure LGP | +| `mountain_car_with_q` | RL | MountainCar with Q-Learning | -## Running Experiments +### Logging ```bash -# Run with default config -lgp run cart_pole_lgp - -# Run with optimized config (after search) -lgp run cart_pole_lgp --config optimal - -# Run with parameter overrides -lgp run cart_pole_lgp --override hyperparameters.n_generations=200 -``` - -### Generating Visualizations +# Verbose output +lgp -v run iris_baseline -```bash -# Analyze results (generates CSV tables) -lgp analyze +# JSON format +lgp --log-format json run iris_baseline -# Build with plot feature for PNG chart generation -cargo install --path crates/lgp-cli --features plot -lgp analyze +# Fine-grained control +RUST_LOG=lgp=debug lgp run iris_baseline ``` -### Output Structure - -``` -outputs/ -├── parameters/ # Optimized hyperparameters (JSON) -│ ├── cart_pole_lgp.json -│ └── ... -├── / # Experiment outputs (timestamped runs) -│ └── / # e.g., 20260201_083623 -│ ├── config/ -│ │ └── config.toml # Resolved config with seed/timestamp -│ ├── outputs/ -│ │ ├── best.json # Best individual from final generation -│ │ ├── median.json # Median individual -│ │ ├── worst.json # Worst individual -│ │ ├── population.json # Full population history -│ │ └── params.json # Hyperparameters used -│ └── post_process/ # Post-processing outputs -├── tables/ # Generated CSV statistics -│ └── .csv -└── figures/ # Generated PNG plots (with --features plot) - └── .png +## Packages -configs/ -└── / - ├── default.toml # Default configuration - └── optimal.toml # Generated by search -``` +| Package | Description | +|---------|-------------| +| [lgp](crates/lgp/README.md) | Core library — traits, evolutionary engine, built-in problems | +| [lgp-cli](crates/lgp-cli/README.md) | CLI binary for running experiments, search, and analysis | ## Extending the Framework -The framework is designed to be extensible. You can add: - -- New classification problems (e.g., XOR, MNIST) -- New RL environments (custom or gym-rs compatible) -- Custom genetic operators (mutation, crossover) -- Alternative fitness functions - -See the [Quick Start](skills/lgp-experiment/SKILL.md#extension-quick-start) for a minimal example, or [skills/lgp-experiment/SKILL.md](skills/lgp-experiment/SKILL.md) for the complete guide. - -## Agent Skill +The framework is trait-based and designed for extension. You can add new classification problems, RL environments, genetic operators, and fitness functions. -This project ships an [Agent Skill](https://github.com/vercel-labs/skills) for use with Claude Code, Cursor, and other compatible agents. - -Available as portable agent skills in [`skills/`](skills/). - -Once installed, use `/lgp-experiment` to run experiments, tune hyperparameters, and analyze results. - -## Contributing - -Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for: - -- Development setup instructions -- Code style guidelines -- Testing requirements -- Pull request process +See [skills/lgp-experiment/SKILL.md](skills/lgp-experiment/SKILL.md) for the complete guide. ## Thesis @@ -357,25 +108,7 @@ The accompanying thesis, *Reinforced Linear Genetic Programming*, is maintained ## References -### Genetic Programming - -- Koza, J. R. (1993). *Genetic Programming: On the Programming of Computers by Means of Natural Selection*. MIT Press. -- Poli, R., Langdon, W. B., & McPhee, N. F. (2008). *A Field Guide to Genetic Programming*. lulu.com. http://www.gp-field-guide.org.uk/ -- Luke, S. (2009). *Essentials of Metaheuristics*. Lulu. https://cs.gmu.edu/~sean/book/metaheuristics/ - -### Linear Genetic Programming - - Brameier, M., & Banzhaf, W. (2001). A Comparison of Linear Genetic Programming and Neural Networks in Medical Data Mining. *IEEE Transactions on Evolutionary Computation*, 5(1), 17-26. -- Song, D., Heywood, M. I., & Zincir-Heywood, A. N. (2003). A Linear Genetic Programming Approach to Intrusion Detection. In *GECCO 2003*, LNCS 2724, pp. 2325-2336. Springer. -- Peeler, H., Li, S. S., Sloss, A. N., Reid, K. N., Yuan, Y., & Banzhaf, W. (2022). Optimizing LLVM Pass Sequences with Shackleton: A Linear Genetic Programming Framework. In *GECCO 2022 Companion*, pp. 578-581. ACM. - -### Reinforcement Learning - - Sutton, R. S., & Barto, A. G. (2018). *Reinforcement Learning: An Introduction* (2nd ed.). MIT Press. -- Downing, H. L. (1995). Reinforced Genetic Programming. In *Proceedings of the Sixth International Conference on Genetic Algorithms (ICGA95)*, pp. 276-283. -- Amaral, R., Ianta, A., Bayer, C., Smith, R. J., & Heywood, M. I. (2022). Benchmarking Genetic Programming in a Multi-Action Reinforcement Learning Locomotion Task. In *GECCO 2022 Companion*, pp. 522-525. ACM. - -### Environments & Datasets - -- Brockman, G., Cheung, V., Pettersson, L., Schneider, J., Schulman, J., Tang, J., & Zaremba, W. (2016). OpenAI Gym. arXiv:1606.01540. +- Koza, J. R. (1993). *Genetic Programming*. MIT Press. - Fisher, R. A. (1936). The Use of Multiple Measurements in Taxonomic Problems. *Annals of Eugenics*, 7(2), 179-188. From 31e6657ea605a0a94d0812fe7c0322ab10c6fbcf Mon Sep 17 00:00:00 2001 From: Urmzd Mukhammadnaim Date: Sun, 29 Mar 2026 01:17:16 -0500 Subject: [PATCH 2/4] docs: restore full references section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Keep all original references with categorical grouping intact — important context for an academic project. --- README.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3446914e..9b983331 100644 --- a/README.md +++ b/README.md @@ -108,7 +108,25 @@ The accompanying thesis, *Reinforced Linear Genetic Programming*, is maintained ## References +### Genetic Programming + +- Koza, J. R. (1993). *Genetic Programming: On the Programming of Computers by Means of Natural Selection*. MIT Press. +- Poli, R., Langdon, W. B., & McPhee, N. F. (2008). *A Field Guide to Genetic Programming*. lulu.com. http://www.gp-field-guide.org.uk/ +- Luke, S. (2009). *Essentials of Metaheuristics*. Lulu. https://cs.gmu.edu/~sean/book/metaheuristics/ + +### Linear Genetic Programming + - Brameier, M., & Banzhaf, W. (2001). A Comparison of Linear Genetic Programming and Neural Networks in Medical Data Mining. *IEEE Transactions on Evolutionary Computation*, 5(1), 17-26. +- Song, D., Heywood, M. I., & Zincir-Heywood, A. N. (2003). A Linear Genetic Programming Approach to Intrusion Detection. In *GECCO 2003*, LNCS 2724, pp. 2325-2336. Springer. +- Peeler, H., Li, S. S., Sloss, A. N., Reid, K. N., Yuan, Y., & Banzhaf, W. (2022). Optimizing LLVM Pass Sequences with Shackleton: A Linear Genetic Programming Framework. In *GECCO 2022 Companion*, pp. 578-581. ACM. + +### Reinforcement Learning + - Sutton, R. S., & Barto, A. G. (2018). *Reinforcement Learning: An Introduction* (2nd ed.). MIT Press. -- Koza, J. R. (1993). *Genetic Programming*. MIT Press. +- Downing, H. L. (1995). Reinforced Genetic Programming. In *Proceedings of the Sixth International Conference on Genetic Algorithms (ICGA95)*, pp. 276-283. +- Amaral, R., Ianta, A., Bayer, C., Smith, R. J., & Heywood, M. I. (2022). Benchmarking Genetic Programming in a Multi-Action Reinforcement Learning Locomotion Task. In *GECCO 2022 Companion*, pp. 522-525. ACM. + +### Environments & Datasets + +- Brockman, G., Cheung, V., Pettersson, L., Schneider, J., Schulman, J., Tang, J., & Zaremba, W. (2016). OpenAI Gym. arXiv:1606.01540. - Fisher, R. A. (1936). The Use of Multiple Measurements in Taxonomic Problems. *Annals of Eugenics*, 7(2), 179-188. From 8883ee0ab5fec88db28cd48ef944e8ff30ceb2a9 Mon Sep 17 00:00:00 2001 From: Urmzd Mukhammadnaim Date: Sun, 29 Mar 2026 01:17:53 -0500 Subject: [PATCH 3/4] docs: move references to rlgp-thesis repository Consolidate all academic references in the thesis repo and point readers there from the README. --- README.md | 29 ++--------------------------- 1 file changed, 2 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 9b983331..4872e455 100644 --- a/README.md +++ b/README.md @@ -102,31 +102,6 @@ The framework is trait-based and designed for extension. You can add new classif See [skills/lgp-experiment/SKILL.md](skills/lgp-experiment/SKILL.md) for the complete guide. -## Thesis +## Thesis & References -The accompanying thesis, *Reinforced Linear Genetic Programming*, is maintained in a [separate repository](https://github.com/urmzd/rlgp-thesis). - -## References - -### Genetic Programming - -- Koza, J. R. (1993). *Genetic Programming: On the Programming of Computers by Means of Natural Selection*. MIT Press. -- Poli, R., Langdon, W. B., & McPhee, N. F. (2008). *A Field Guide to Genetic Programming*. lulu.com. http://www.gp-field-guide.org.uk/ -- Luke, S. (2009). *Essentials of Metaheuristics*. Lulu. https://cs.gmu.edu/~sean/book/metaheuristics/ - -### Linear Genetic Programming - -- Brameier, M., & Banzhaf, W. (2001). A Comparison of Linear Genetic Programming and Neural Networks in Medical Data Mining. *IEEE Transactions on Evolutionary Computation*, 5(1), 17-26. -- Song, D., Heywood, M. I., & Zincir-Heywood, A. N. (2003). A Linear Genetic Programming Approach to Intrusion Detection. In *GECCO 2003*, LNCS 2724, pp. 2325-2336. Springer. -- Peeler, H., Li, S. S., Sloss, A. N., Reid, K. N., Yuan, Y., & Banzhaf, W. (2022). Optimizing LLVM Pass Sequences with Shackleton: A Linear Genetic Programming Framework. In *GECCO 2022 Companion*, pp. 578-581. ACM. - -### Reinforcement Learning - -- Sutton, R. S., & Barto, A. G. (2018). *Reinforcement Learning: An Introduction* (2nd ed.). MIT Press. -- Downing, H. L. (1995). Reinforced Genetic Programming. In *Proceedings of the Sixth International Conference on Genetic Algorithms (ICGA95)*, pp. 276-283. -- Amaral, R., Ianta, A., Bayer, C., Smith, R. J., & Heywood, M. I. (2022). Benchmarking Genetic Programming in a Multi-Action Reinforcement Learning Locomotion Task. In *GECCO 2022 Companion*, pp. 522-525. ACM. - -### Environments & Datasets - -- Brockman, G., Cheung, V., Pettersson, L., Schneider, J., Schulman, J., Tang, J., & Zaremba, W. (2016). OpenAI Gym. arXiv:1606.01540. -- Fisher, R. A. (1936). The Use of Multiple Measurements in Taxonomic Problems. *Annals of Eugenics*, 7(2), 179-188. +The accompanying thesis, *Reinforced Linear Genetic Programming*, and full references are maintained in a [separate repository](https://github.com/urmzd/rlgp-thesis). From 8d179c7788ca9116d170b77ab56aa5265e97d4e7 Mon Sep 17 00:00:00 2001 From: Urmzd Mukhammadnaim Date: Sun, 29 Mar 2026 01:20:21 -0500 Subject: [PATCH 4/4] docs: restore overview, CLI reference, search, and output sections MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add back the feature overview, supported environments, full CLI reference with flags, hyperparameter search details, output structure, log levels, and core traits — keeping the streamlined install.sh flow. --- README.md | 181 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 160 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 4872e455..9842e531 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,26 @@ LGP experiment output

+## Overview + +Linear Genetic Programming (LGP) is a variant of genetic programming that evolves sequences of instructions operating on registers, similar to machine code. This framework provides: + +- **Modular architecture** - Trait-based design for easy extension to new problem domains +- **Multiple problem types** - Built-in support for OpenAI Gym environments and classification tasks +- **Q-Learning integration** - Hybrid LGP + Q-Learning for enhanced reinforcement learning +- **Hyperparameter search** - Built-in random search with parallel evaluation +- **Parallel evaluation** - Rayon-powered parallel fitness evaluation +- **Experiment automation** - Full pipeline: search, run, and analyze from a single CLI +- **Optional plotting** - PNG chart generation via `plotters` (behind `--features plot`) + +### Supported Environments + +| Environment | Type | Inputs | Actions | Description | +|-------------|------|--------|---------|-------------| +| CartPole | RL | 4 | 2 | Balance a pole on a moving cart | +| MountainCar | RL | 2 | 3 | Drive a car up a steep mountain | +| Iris | Classification | 4 | 3 | Classify iris flower species | + ## Install **Prebuilt binary (recommended):** @@ -43,52 +63,164 @@ git clone https://github.com/urmzd/linear-gp.git && cd linear-gp cargo install --path crates/lgp-cli ``` -## Usage +## Quick Start ```bash # List available experiments lgp list -# Run an experiment -lgp run iris_baseline +# Run CartPole with pure LGP lgp run cart_pole_lgp +# Run Iris classification +lgp run iris_baseline + # Run a Rust example lgp example cart_pole +``` -# Search for optimal hyperparameters +## CLI Reference + +```bash +# Run experiment with default config +lgp run iris_baseline + +# Run with optimal config (after search) +lgp run iris_baseline --config optimal + +# Run with parameter overrides +lgp run iris_baseline --override hyperparameters.program.max_instructions=50 + +# Q-learning parameter overrides +lgp run cart_pole_with_q --override operations.q_learning.alpha=0.5 + +# Preview config (dry-run) +lgp run iris_baseline --dry-run + +# Search hyperparameters lgp search iris_baseline +lgp search iris_baseline --n-trials 20 --n-threads 8 + +# Analyze results (generates CSV tables + optional PNG plots) +lgp analyze +lgp analyze --input outputs --output outputs -# Full pipeline: search -> run -> analyze +# Run full experiment pipeline (search -> run -> analyze) lgp experiment iris_baseline +lgp experiment iris_baseline --iterations 20 +lgp experiment --skip-search + +# Run a Rust example +lgp example cart_pole + +# List available examples +lgp example --list ``` ### Available Experiments -| Experiment | Type | Description | -|------------|------|-------------| -| `iris_baseline` | Classification | Iris (no mutation, no crossover) | -| `iris_mutation` | Classification | Iris with mutation only | -| `iris_crossover` | Classification | Iris with crossover only | -| `iris_full` | Classification | Iris full (mutation + crossover) | -| `cart_pole_lgp` | RL | CartPole with pure LGP | -| `cart_pole_with_q` | RL | CartPole with Q-Learning | -| `mountain_car_lgp` | RL | MountainCar with pure LGP | -| `mountain_car_with_q` | RL | MountainCar with Q-Learning | +| Experiment | Description | +|------------|-------------| +| `iris_baseline` | Iris baseline (no mutation, no crossover) | +| `iris_mutation` | Iris with mutation only | +| `iris_crossover` | Iris with crossover only | +| `iris_full` | Iris full (mutation + crossover) | +| `cart_pole_lgp` | CartPole with pure LGP | +| `cart_pole_with_q` | CartPole with Q-Learning | +| `mountain_car_lgp` | MountainCar with pure LGP | +| `mountain_car_with_q` | MountainCar with Q-Learning | + +## Hyperparameter Search -### Logging +The framework includes built-in hyperparameter search with parallel evaluation via `rayon`. ```bash -# Verbose output +# Search for a specific config +lgp search cart_pole_lgp + +# Search all configs (LGP first, then Q-Learning) +lgp search + +# Search with custom options +lgp search cart_pole_with_q --n-trials 100 --n-threads 8 --median-trials 15 +``` + +### Parameters Searched + +| Parameter | Range | +|-----------|-------| +| `max_instructions` | 1-100 | +| `external_factor` | 0.0-100.0 | +| `alpha` (Q-Learning) | 0.0-1.0 | +| `gamma` (Q-Learning) | 0.0-1.0 | +| `epsilon` (Q-Learning) | 0.0-1.0 | +| `alpha_decay` (Q-Learning) | 0.0-1.0 | +| `epsilon_decay` (Q-Learning) | 0.0-1.0 | + +Results are saved to: +- `outputs/parameters/.json` +- `configs//optimal.toml` + +## Visualizations + +```bash +# Analyze results (generates CSV tables) +lgp analyze + +# Build with plot feature for PNG chart generation +cargo install --path crates/lgp-cli --features plot +lgp analyze +``` + +## Output Structure + +``` +outputs/ +├── parameters/ # Optimized hyperparameters (JSON) +│ ├── cart_pole_lgp.json +│ └── ... +├── / # Experiment outputs (timestamped runs) +│ └── / +│ ├── config/ +│ │ └── config.toml # Resolved config with seed/timestamp +│ ├── outputs/ +│ │ ├── best.json # Best individual from final generation +│ │ ├── median.json # Median individual +│ │ ├── worst.json # Worst individual +│ │ ├── population.json # Full population history +│ │ └── params.json # Hyperparameters used +│ └── post_process/ # Post-processing outputs +├── tables/ # Generated CSV statistics +│ └── .csv +└── figures/ # Generated PNG plots (with --features plot) + └── .png +``` + +## Logging + +```bash +# Default (info level, pretty format) +lgp run iris_baseline + +# Verbose mode (debug level) lgp -v run iris_baseline -# JSON format +# JSON format for log aggregation lgp --log-format json run iris_baseline -# Fine-grained control +# Fine-grained control via RUST_LOG RUST_LOG=lgp=debug lgp run iris_baseline +RUST_LOG=lgp::core=trace,lgp=info lgp run iris_baseline ``` +| Level | Use Case | +|-------|----------| +| `error` | Fatal issues only | +| `warn` | Potential problems | +| `info` | Progress updates (default) | +| `debug` | Detailed diagnostics | +| `trace` | Instruction-by-instruction execution | + ## Packages | Package | Description | @@ -98,9 +230,16 @@ RUST_LOG=lgp=debug lgp run iris_baseline ## Extending the Framework -The framework is trait-based and designed for extension. You can add new classification problems, RL environments, genetic operators, and fitness functions. +The framework is built around these key traits: + +- **`State`** - Represents an environment state with value access and action execution +- **`RlState`** - Extends State for RL environments with terminal state detection +- **`Core`** - Main trait defining the genetic algorithm components +- **`Fitness`** - Evaluates individual performance on states +- **`Breed`** - Two-point crossover for creating offspring +- **`Mutate`** - Mutation operators for genetic variation -See [skills/lgp-experiment/SKILL.md](skills/lgp-experiment/SKILL.md) for the complete guide. +You 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. ## Thesis & References