Skip to content

docs: simplify README for install.sh and core usage #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
urmzd merged 4 commits into from
Mar 29, 2026
Merged

docs: simplify README for install.sh and core usage #11

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
380d69e
docs: simplify README to focus on install.sh and core usage
urmzd Mar 29, 2026
31e6657
docs: restore full references section
urmzd Mar 29, 2026
8883ee0
docs: move references to rlgp-thesis repository
urmzd Mar 29, 2026
8d179c7
docs: restore overview, CLI reference, search, and output sections
urmzd Mar 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
245 changes: 55 additions & 190 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,26 +41,29 @@ Linear Genetic Programming (LGP) is a variant of genetic programming that evolve
| MountainCar | RL | 2 | 3 | Drive a car up a steep mountain |
| Iris | Classification | 4 | 3 | Classify iris flower species |

## Quick Start
## Install

### Prerequisites
**Prebuilt binary (recommended):**

| Dependency | Version | Installation |
|------------|---------|--------------|
| Rust | 1.70+ | [rustup.rs](https://rustup.rs/) |
```bash
curl -fsSL https://raw.githubusercontent.com/urmzd/linear-gp/main/install.sh | bash
```

### Installation
You can pin a version or change the install directory:

```bash
# Clone the repository
git clone https://github.com/urmzd/linear-gp.git
cd linear-gp
LGP_VERSION=v1.0.0 LGP_INSTALL_DIR=~/.local/bin \
curl -fsSL https://raw.githubusercontent.com/urmzd/linear-gp/main/install.sh | bash
```

# Install the lgp binary
**From source:**

```bash
git clone https://github.com/urmzd/linear-gp.git && cd linear-gp
cargo install --path crates/lgp-cli
```

### First Experiment
## Quick Start

```bash
# List available experiments
Expand All @@ -72,130 +75,20 @@ lgp run cart_pole_lgp
# Run Iris classification
lgp run iris_baseline

# Run an example
# Run a Rust 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)
│ ├── <experiment>/ # Per-experiment outputs
│ │ └── <timestamp>/ # Timestamped runs
│ ├── tables/ # CSV statistics
│ └── figures/ # PNG plots
└── skills/ # Agent skills & documentation
```

### 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

```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
```

### 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

```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 .
```

## CLI Reference

```bash
# List available experiments
lgp list

# Run experiment with default config
lgp run iris_baseline

# Run with optimal config (after search)
lgp run iris_baseline --config optimal

# Run with overrides
# Run with parameter overrides
lgp run iris_baseline --override hyperparameters.program.max_instructions=50

# Q-learning parameter overrides
Expand Down Expand Up @@ -224,7 +117,7 @@ lgp example cart_pole
lgp example --list
```

**Available Experiments:**
### Available Experiments

| Experiment | Description |
|------------|-------------|
Expand All @@ -241,8 +134,6 @@ lgp example --list

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
Expand Down Expand Up @@ -270,20 +161,7 @@ Results are saved to:
- `outputs/parameters/<config>.json`
- `configs/<config>/optimal.toml`

## Running Experiments

```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
## Visualizations

```bash
# Analyze results (generates CSV tables)
Expand All @@ -294,15 +172,15 @@ cargo install --path crates/lgp-cli --features plot
lgp analyze
```

### Output Structure
## Output Structure

```
outputs/
├── parameters/ # Optimized hyperparameters (JSON)
│ ├── cart_pole_lgp.json
│ └── ...
├── <experiment>/ # Experiment outputs (timestamped runs)
│ └── <timestamp>/ # e.g., 20260201_083623
│ └── <timestamp>/
│ ├── config/
│ │ └── config.toml # Resolved config with seed/timestamp
│ ├── outputs/
Expand All @@ -316,66 +194,53 @@ outputs/
│ └── <experiment>.csv
└── figures/ # Generated PNG plots (with --features plot)
└── <experiment>.png

configs/
└── <experiment>/
├── default.toml # Default configuration
└── optimal.toml # Generated by search
```

## 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.
## Logging

## Agent Skill

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:
```bash
# Default (info level, pretty format)
lgp run iris_baseline

- Development setup instructions
- Code style guidelines
- Testing requirements
- Pull request process
# Verbose mode (debug level)
lgp -v run iris_baseline

## Thesis
# JSON format for log aggregation
lgp --log-format json run iris_baseline

The accompanying thesis, *Reinforced Linear Genetic Programming*, is maintained in a [separate repository](https://github.com/urmzd/rlgp-thesis).
# 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
```

## References
| Level | Use Case |
|-------|----------|
| `error` | Fatal issues only |
| `warn` | Potential problems |
| `info` | Progress updates (default) |
| `debug` | Detailed diagnostics |
| `trace` | Instruction-by-instruction execution |

### Genetic Programming
## Packages

- 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/
| 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 |

### Linear Genetic Programming
## Extending the Framework

- 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.
The framework is built around these key traits:

### Reinforcement Learning
- **`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

- 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.
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.

### Environments & Datasets
## Thesis & References

- 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).
Loading