lgp 1.7.2

CLI for Linear Genetic Programming experiments
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134

# lgp

Command-line interface for running Linear Genetic Programming experiments.

[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)

## Overview

`lgp` is a CLI for running LGP experiments using TOML-based configuration files. It supports listing available experiments, running them with config overrides, hyperparameter search, result analysis, and end-to-end experiment pipelines.

## Installation

```bash
cargo install lgp
```

Or build from source:

```bash
cargo install --path crates/lgp-cli

# With plot support (PNG chart generation)
cargo install --path crates/lgp-cli --features plot
```

## Usage

```bash
# List available experiments
lgp list

# Run an experiment with default config
lgp run iris_baseline

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

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

# Preview resolved config without running
lgp run iris_baseline --dry-run

# Search hyperparameters
lgp search iris_baseline --n-trials 40 --n-threads 4

# Analyze experiment results
lgp analyze

# Run full pipeline (search -> run -> analyze)
lgp experiment iris_baseline --iterations 10

```

## Global Options

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Enable debug-level logging |
| `--log-format <FORMAT>` | Log output format: `pretty` (default), `compact`, `json` |
| `--log-file <PATH>` | Write logs to a file instead of stdout |

## Commands

### `lgp list`

Lists all available experiments discovered from the `configs/` directory.

### `lgp run <EXPERIMENT>`

Runs an experiment by name. Configuration is loaded from `configs/<experiment>/default.toml` (or `optimal.toml` with `--config optimal`).

| Option | Description |
|--------|-------------|
| `--config <NAME>` | Config variant to use (`default` or `optimal`) |
| `--override <KEY=VALUE>` | Override a config parameter (repeatable) |
| `--dry-run` | Print resolved config and exit |

### `lgp search [CONFIG]`

Search for optimal hyperparameters. If no config is specified, searches all configs.

| Option | Description |
|--------|-------------|
| `--n-trials <N>` | Number of trials (default: 40) |
| `--n-threads <N>` | Parallel threads (default: 4) |
| `--median-trials <N>` | Runs for median (default: 10) |

### `lgp analyze`

Generate statistics tables (CSV) and optional plots (PNG) from experiment results.

| Option | Description |
|--------|-------------|
| `--input <DIR>` | Input directory (default: `outputs`) |
| `--output <DIR>` | Output directory (default: `outputs`) |

### `lgp experiment [CONFIG]`

Run end-to-end pipeline: search -> run -> analyze.

| Option | Description |
|--------|-------------|
| `--iterations <N>` | Number of experiment iterations (default: 10) |
| `--skip-search` | Skip hyperparameter search phase |
| `--skip-analyze` | Skip analysis phase |
| `--n-trials <N>` | Search trials (default: 40) |
| `--n-threads <N>` | Search threads (default: 4) |
| `--median-trials <N>` | Runs for median (default: 10) |

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

## Logging

The CLI integrates with the `tracing` ecosystem. Control log levels via `RUST_LOG`:

```bash
# Debug level for all LGP modules
RUST_LOG=lgp=debug lgp run iris_baseline

# JSON output for log aggregation
lgp --log-format json run iris_baseline
```