Parameter Sweep

---
name: gpd:parameter-sweep
description: Systematic parameter sweep with parallel execution and result aggregation
argument-hint: "[phase] [--param name --range start:end:steps] [--adaptive] [--log]"
context_mode: project-required
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Task
  - AskUserQuestion
---

<!-- Tool names and @ includes are platform-specific. The installer translates paths for your runtime. -->
<!-- Allowed-tools are runtime-specific. Other platforms may use different tool interfaces. -->

<objective>
Execute a systematic parameter sweep: vary one or more parameters across a range, collect results, and produce summary tables and data. Uses wave-based parallelism for independent parameter values.

**Why a dedicated command:** Parameter sweeps are the workhorse of computational physics — mapping phase diagrams, finding critical points, checking universality, validating scaling laws. But sweeps done ad hoc lead to wasted compute (uniform grids in boring regions), missed features (phase transitions between grid points), and disorganized results (scattered output files). This command structures the sweep from design through execution to analysis.

**The principle:** A well-designed sweep puts points where the physics is, not on a uniform grid. It monitors convergence during execution, refines near interesting features, and produces structured output that downstream analysis can consume.
</objective>

<execution_context>
@./.claude/get-physics-done/workflows/parameter-sweep.md
</execution_context>

<context>
Phase: $ARGUMENTS

@.gpd/ROADMAP.md
@.gpd/STATE.md
</context>

<process>
Execute the parameter-sweep workflow from @./.claude/get-physics-done/workflows/parameter-sweep.md end-to-end.

## 1. Define the Parameter Space

Specify what varies and what stays fixed:

- **Sweep parameters** — which parameters to vary, with ranges and scaling
- **Fixed parameters** — which parameters are held constant (and at what values)
- **Observable(s)** — what to compute at each point
- **Constraints** — any parameter combinations to exclude (e.g., g > g_c for ordered phase only)

### Grid Design

| Grid Type | When to Use | Example |
| --- | --- | --- |
| **Uniform** | Default for smooth observables | `np.linspace(0, 1, 20)` |
| **Logarithmic** | Parameters spanning orders of magnitude (couplings, masses, energies) | `np.logspace(-3, 1, 20)` |
| **Chebyshev** | Need to interpolate the result accurately | `0.5*(1 + cos(pi*k/N))` |
| **Adaptive** | Phase transitions, critical points, sharp features | Start coarse, refine where gradient is large |
| **Latin Hypercube** | Multi-dimensional sweeps with limited budget | `scipy.stats.qmc.LatinHypercube(d=3).random(n=50)` |

```python
import numpy as np

# 1D uniform
g_values = np.linspace(0.0, 2.0, 21)

# 1D logarithmic (for coupling constants, masses)
m_values = np.logspace(-2, 2, 21)  # 0.01 to 100

# 2D grid (tensor product)
g_grid, T_grid = np.meshgrid(
    np.linspace(0, 2, 11),
    np.linspace(0.1, 5.0, 11)
)
param_pairs = list(zip(g_grid.ravel(), T_grid.ravel()))

Resolution guidance:

• Phase diagrams: 20-50 points per dimension (minimum to resolve boundaries)
• Scaling laws: 10-20 points on log scale (need to fit power law)
• Convergence studies: 5-8 points in geometric sequence (need Richardson extrapolation)
• Quick survey: 5-10 points to find interesting region, then refine

2. Parallelization Strategy

Group sweep points into independent waves for parallel execution:

Wave 1: [g=0.0, g=0.4, g=0.8, g=1.2, g=1.6, g=2.0]  — coarse skeleton
Wave 2: [g=0.2, g=0.6, g=1.0, g=1.4, g=1.8]           — fill in gaps
Wave 3: [adaptive refinement near features found in waves 1-2]

Wave design principles:

• Wave 1 covers the full range at coarse resolution — reveals the landscape
• Wave 2 fills in the gaps — smooth regions need no more, interesting regions get wave 3
• Wave 3+ adapts: refine near phase transitions, critical points, extrema, or unexpected features
• Within each wave, all points are independent and execute in parallel via Task tool

For multi-dimensional sweeps, each wave executes a slice or random subset of the full grid.

3. Convergence Monitoring During Sweep

After each wave completes, check whether the results are sufficiently resolved:

def needs_refinement(x_values, y_values, threshold=0.1):
    """Identify intervals needing refinement."""
    refine_at = []
    for i in range(len(y_values) - 1):
        # Large relative change between adjacent points
        dy = abs(y_values[i+1] - y_values[i])
        y_scale = max(abs(y_values[i]), abs(y_values[i+1]), 1e-10)
        if dy / y_scale > threshold:
            refine_at.append(0.5 * (x_values[i] + x_values[i+1]))
    return refine_at

Convergence criteria:

• Smooth regions — relative change between adjacent points < 10% (or user-specified tolerance)
• Near critical points — switch to fine grid, estimate critical exponent from log-log slope
• Discontinuities — identify jump location, report as phase boundary
• Divergences — identify divergence location, fit critical exponent, report pole

4. Adaptive Refinement (--adaptive flag)

When --adaptive is specified, the sweep automatically refines:

1. Execute wave 1 (coarse grid)
2. Analyze results: find large gradients, sign changes, extrema
3. Generate wave 2 centered on interesting features
4. Repeat until convergence criterion is met or budget is exhausted

def adaptive_sweep(compute_f, x_range, initial_points=10, max_points=100, tol=0.05):
    """Adaptive 1D sweep with refinement."""
    x = np.linspace(x_range[0], x_range[1], initial_points)
    y = np.array([compute_f(xi) for xi in x])

    while len(x) < max_points:
        new_points = needs_refinement(x, y, threshold=tol)
        if not new_points:
            break
        new_y = np.array([compute_f(xi) for xi in new_points])
        x = np.sort(np.concatenate([x, new_poin