docs/optimization_guide.md

# Optimization guide

LAMPSUI uses Optuna for parameter sweeps. The "Optimize" tab exposes the same
controls as `optuna.create_study` plus a UI for the search space.

## Picking a metric

The agent should match the user's goal to a thermo column + reduction:

| Goal | Metric | Reduce | Direction |
|------|--------|--------|-----------|
| "Find params where pressure converges to zero" | `Press` | `abs_last` | minimize |
| "Find the most stable parameter set" | `Press` | `stability` | minimize |
| "Find the highest mean pressure" | `Press` | `mean` | maximize |
| "Find params that minimize numerical noise in temperature" | `Temp` | `stability` | minimize |
| "Settle quickly" (proxy: low energy late in run) | `TotEng` | `last` | minimize |

`stability` = stdev of the second half of the trace. Useful when the run
has a transient + steady state and you want the steady state to be quiet.

## Picking a sampler

| Sampler | Use when |
|---------|----------|
| **TPE** (default) | 1 objective, ≤10 trials, mixed continuous/integer params |
| **Random** | Baseline / smoke testing |
| **CMA-ES** | 1 objective, all-continuous params, ≥30 trials |
| **NSGA-II** (default for multi-obj) | 2+ objectives, ≥20 trials |
| **NSGA-III** | 3+ objectives with structured reference points |

Constraints:
- NSGA-II/III require ≥2 objectives — submit will reject otherwise
- CMA-ES is single-objective only — submit will reject otherwise

## Picking a search space

For HF free tier, keep budgets small:

```json
{
  "dh":     {"type": "float", "low": 0.18, "high": 0.25, "step": 0.01},
  "sigmao": {"type": "float", "low": 0.5,  "high": 2.0}
}
```

with `n_trials=10`, `prodRun=1000` per trial → ~10–15 minutes total on free
tier.

For real research:

```json
{
  "dh":     {"type": "float", "low": 0.10, "high": 0.30, "log": true},
  "sigmao": {"type": "float", "low": 0.1,  "high": 5.0,  "log": true},
  "F":      {"type": "categorical", "choices": [1, 2, 3]}
}
```

with `n_trials=50–100`, `prodRun=20 000+` → run on a workstation overnight.

## Using `step` for discretization

If you want `prodRun` to stay on a coarse grid (cost varies linearly with it),
set `step=100` and `low=100, high=1000` — Optuna will only try
`{100, 200, …, 1000}`. Without step, it picks any integer.

For floats, `step=0.05` on `dh` means trials sample only `0.10, 0.15, 0.20…`.

## Multi-objective: typical pairs

| Pair | What it tells you |
|------|-------------------|
| `Press abs_last` ↓ + `Temp stability` ↓ | Find params with both small final pressure error AND low numerical noise |
| `prodRun` ↓ + `Press abs_last` ↓ | Cheap settings that still converge — Pareto front is the cost-quality trade-off |
| `Press mean` ↑ + `Press stability` ↓ | High mean pressure but quiet steady state |

The Pareto front in the UI shows the non-dominated trials. For 2 objectives
it renders as a scatter plot with grey dots = all trials and a blue dashed
line + dots = Pareto front.

## Reading the analysis report

Once a study has ≥3 completed trials, the bottom of the Optimize tab shows:

- **Parameter importance** (fANOVA): which knobs actually moved the
  objective. <5% means the parameter could be removed from the search.
- **Optimization history**: best-so-far per trial. Flat line late in the
  run = converged or stuck.
- **Correlations** (Pearson r): linear sensitivity. High |r| but low
  importance means the relationship is monotonic but the search didn't
  explore variation in that param.
- **Slice plots**: per-parameter scatter of objective vs that knob.
  Trends visible by eye.

A combination of low importance (<10%) and low |r| (<0.3) means the parameter
is essentially noise for the chosen objective — drop it from the search.

## When to start an optimization vs a single run

The agent should start a single run when:
- The user asks to verify behaviour at known parameters
- The user is debugging a setup
- Compute budget is tight (HF free tier)

The agent should start an optimization when:
- The user wants to find the best parameters
- The user is doing a sensitivity study
- The user mentions "sweep", "scan", "find the best", "trade-off"