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:

{
  "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:

{
  "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"