Sweep and Study Guide

Table of Contents

• 3. Study Contract Essentials
• 4. Outputs and Aggregates
• 5. Operational Workflow

pic.flow sweep orchestrates parameter studies with generated run variants, scheduler arrays, and aggregate metrics.

1. Required Input Roles

A sweep/study commonly uses:

• base case/solver/monitor/post templates,
• study.yml defining parameter combinations and metrics,
• optional cluster scheduler settings for array submission.

Starter templates are available under examples/*/*study*.yml and examples/master_template/.

2. Core Command Patterns

./scripts/pic.flow sweep --study <study.yml> --scheduler slurm

Typical optional flags include dry-run or no-submit behaviors depending on workflow stage.

3. Study Contract Essentials

A study definition usually specifies:

• parameter space (explicit lists/ranges),
• mapping from parameter key -> YAML target path,
• execution controls,
• metric extraction definitions.

Each combination yields a generated run with fully materialized config set.

4. Outputs and Aggregates

Expected study outputs include:

• per-combination run directories,
• aggregate table (for example metrics_table.csv),
• summary metadata (for example summary.json),
• optional plot outputs in results/plots.

This keeps raw run data and comparative study diagnostics in one reproducible structure.

5. Operational Workflow

Recommended workflow:

1. run a tiny subset locally or with --no-submit,
2. verify parameter substitution and metric extraction,
3. launch full array,
4. inspect aggregate outputs,
5. archive the exact study file with results for reproducibility.

For fragile metrics, add smoke tests or fixture-based validation before large queue submissions.

1. Reference Scales

• Cluster Run Guide (Slurm)
• Configuration Reference: Postprocessor YAML
• Testing, Smoke, and Quality Gates Guide