Simulation Validator
Goal
Provide a three-stage validation protocol: pre-flight checks, runtime monitoring, and post-flight validation for materials simulations.
Requirements
- Python 3.8+
- No external dependencies (uses Python standard library only)
- Works on Linux, macOS, and Windows
Inputs to Gather
Before running validation scripts, collect from the user:
| Input |
Description |
Example |
| Config file |
Simulation configuration (JSON/YAML) |
simulation.json |
| Log file |
Runtime output log |
simulation.log |
| Metrics file |
Post-run metrics (JSON) |
results.json |
| Required params |
Parameters that must exist |
dt,dx,kappa |
| Valid ranges |
Parameter bounds |
dt:1e-6:1e-2 |
Decision Guidance
When to Run Each Stage
Is simulation about to start?
├── YES → Run Stage 1: preflight_checker.py
│ └── BLOCK status? → Fix issues, do NOT run simulation
│ └── WARN status? → Review warnings, document if accepted
│ └── PASS status? → Proceed to run simulation
│
Is simulation running?
├── YES → Run Stage 2: runtime_monitor.py (periodically)
│ └── Alerts? → Consider stopping, check parameters
│
Has simulation finished?
├── YES → Run Stage 3: result_validator.py
│ └── Failed checks? → Do NOT use results
│ → Run failure_diagnoser.py
│ └── All passed? → Results are valid
Choosing Validation Thresholds
| Metric |
Conservative |
Standard |
Relaxed |
| Mass tolerance |
1e-6 |
1e-3 |
1e-2 |
| Residual growth |
2x |
10x |
100x |
| dt reduction |
10x |
100x |
1000x |
Script Outputs (JSON Fields)
| Script |
Output Fields |
scripts/preflight_checker.py |
report.status, report.blockers, report.warnings |
scripts/runtime_monitor.py |
alerts, residual_stats, dt_stats |
scripts/result_validator.py |
checks, confidence_score, failed_checks |
scripts/failure_diagnoser.py |
probable_causes, recommended_fixes |
Three-Stage Validation Protocol
Stage 1: Pre-flight (Before Simulation)
- Run
scripts/preflight_checker.py --config simulation.json
- BLOCK status: Stop immediately, fix all blocker issues
- WARN status: Review warnings, document accepted risks
- PASS status: Proceed to simulation
python3 scripts/preflight_checker.py \
--config simulation.json \
--required dt,dx,kappa \
--ranges "dt:1e-6:1e-2,dx:1e-4:1e-1" \
--min-free-gb 1.0 \
--json
Stage 2: Runtime (During Simulation)
- Run
scripts/runtime_monitor.py --log simulation.log periodically
- Configure alert thresholds based on problem type
- Stop simulation if critical alerts appear
python3 scripts/runtime_monitor.py \
--log simulation.log \
--residual-growth 10.0 \
--dt-drop 100.0 \
--json
Stage 3: Post-flight (After Simulation)
- Run
scripts/result_validator.py --metrics results.json
- All checks PASS: Results are valid for analysis
- Any check FAIL: Do NOT use results, diagnose failure
python3 scripts/result_validator.py \
--metrics results.json \
--bound-min 0.0 \
--bound-max 1.0 \
--mass-tol 1e-3 \
--json
Failure Diagnosis
When validation fails:
python3 scripts/failure_diagnoser.py --log simulation.log --json
Conversational Workflow Example
User: My phase field simulation crashed after 1000 steps. Can you help me figure out why?
Agent workflow:
- First, check the log for obvious errors:
python3 scripts/failure_diagnoser.py --log simulation.log --json
- If diagnosis suggests numerical blow-up, check runtime stats:
python3 scripts/runtime_monitor.py --log simulation.log --json
- Recommend fixes based on findings:
- If residual grew rapidly → reduce time step
- If dt collapsed → check stability conditions
- If NaN detected → check initial conditions
Error Handling
| Error |
Cause |
Resolution |
Config not found |
File path invalid |
Verify config path exists |
Non-numeric value |
Parameter is not a number |
Fix config file format |
out of range |
Parameter outside bounds |
Adjust parameter or bounds |
Output directory not writable |
Permission issue |
Check directory permissions |
Insufficient disk space |
Disk nearly full |
Free up space or reduce output |
Interpretation Guidance
Status Meanings
| Status |
Meaning |
Action |
| PASS |
All checks passed |
Proceed with confidence |
| WARN |
Non-critical issues found |
Review and document |
| BLOCK |
Critical issues found |
Must fix before proceeding |
Confidence Score Interpretation
| Score |
Meaning |
| 1.0 |
All validation checks passed |
| 0.75+ |
Most checks passed, minor issues |
| 0.5-0.75 |
Significant issues, review carefully |
| < 0.5 |
Major problems, do not trust results |
Common Failure Patterns
| Pattern in Log |
Likely Cause |
Recommended Fix |
| NaN, Inf, overflow |
Numerical instability |
Reduce dt, increase damping |
| max iterations, did not converge |
Solver failure |
Tune preconditioner, tolerances |
| out of memory |
Memory exhaustion |
Reduce mesh, enable out-of-core |
| dt reduced |
Adaptive stepping triggered |
May be okay if controlled |
Limitations
- Not a real-time monitor: Scripts analyze logs after-the-fact
- Regex-based: Log parsing depends on pattern matching; may miss unusual formats
- No automatic fixes: Scripts diagnose but don't modify simulations
References
references/validation_protocol.md - Detailed checklist and criteriareferences/log_patterns.md - Common failure signatures and regex patterns
Version History
- v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, Windows compatibility
- v1.0.0: Initial release with 4 validation scripts
1---2name: simulation-validator3description: Validate simulations before, during, and after execution. Use for pre-flight checks, runtime monitoring, post-run validation, diagnosing failed simulations, checking convergence, detecting NaN/Inf, or verifying mass/energy conservation.4---5
6# Simulation Validator
7
8## Goal
9
10Provide a three-stage validation protocol: pre-flight checks, runtime monitoring, and post-flight validation for materials simulations.
11
12## Requirements
13
14- Python 3.8+
15- No external dependencies (uses Python standard library only)
16- Works on Linux, macOS, and Windows
17
18## Inputs to Gather
19
20Before running validation scripts, collect from the user:
21
22| Input | Description | Example |
23|-------|-------------|---------|
24| Config file | Simulation configuration (JSON/YAML) | `simulation.json` |
25| Log file | Runtime output log | `simulation.log` |
26| Metrics file | Post-run metrics (JSON) | `results.json` |
27| Required params | Parameters that must exist | `dt,dx,kappa` |
28| Valid ranges | Parameter bounds | `dt:1e-6:1e-2` |
29
30## Decision Guidance
31
32### When to Run Each Stage
33
34```
35Is simulation about to start?
36├── YES → Run Stage 1: preflight_checker.py
37│ └── BLOCK status? → Fix issues, do NOT run simulation
38│ └── WARN status? → Review warnings, document if accepted
39│ └── PASS status? → Proceed to run simulation
40│
41Is simulation running?
42├── YES → Run Stage 2: runtime_monitor.py (periodically)
43│ └── Alerts? → Consider stopping, check parameters
44│
45Has simulation finished?
46├── YES → Run Stage 3: result_validator.py
47│ └── Failed checks? → Do NOT use results
48│ → Run failure_diagnoser.py
49│ └── All passed? → Results are valid
50```
51
52### Choosing Validation Thresholds
53
54| Metric | Conservative | Standard | Relaxed |
55|--------|--------------|----------|---------|
56| Mass tolerance | 1e-6 | 1e-3 | 1e-2 |
57| Residual growth | 2x | 10x | 100x |
58| dt reduction | 10x | 100x | 1000x |
59
60## Script Outputs (JSON Fields)
61
62| Script | Output Fields |
63|--------|---------------|
64| `scripts/preflight_checker.py` | `report.status`, `report.blockers`, `report.warnings` |
65| `scripts/runtime_monitor.py` | `alerts`, `residual_stats`, `dt_stats` |
66| `scripts/result_validator.py` | `checks`, `confidence_score`, `failed_checks` |
67| `scripts/failure_diagnoser.py` | `probable_causes`, `recommended_fixes` |
68
69## Three-Stage Validation Protocol
70
71### Stage 1: Pre-flight (Before Simulation)
72
731. Run `scripts/preflight_checker.py --config simulation.json`
742. **BLOCK status**: Stop immediately, fix all blocker issues
753. **WARN status**: Review warnings, document accepted risks
764. **PASS status**: Proceed to simulation
77
78```bash
79python3 scripts/preflight_checker.py \
80 --config simulation.json \
81 --required dt,dx,kappa \
82 --ranges "dt:1e-6:1e-2,dx:1e-4:1e-1" \
83 --min-free-gb 1.0 \
84 --json
85```
86
87### Stage 2: Runtime (During Simulation)
88
891. Run `scripts/runtime_monitor.py --log simulation.log` periodically
902. Configure alert thresholds based on problem type
913. Stop simulation if critical alerts appear
92
93```bash
94python3 scripts/runtime_monitor.py \
95 --log simulation.log \
96 --residual-growth 10.0 \
97 --dt-drop 100.0 \
98 --json
99```
100
101### Stage 3: Post-flight (After Simulation)
102
1031. Run `scripts/result_validator.py --metrics results.json`
1042. **All checks PASS**: Results are valid for analysis
1053. **Any check FAIL**: Do NOT use results, diagnose failure
106
107```bash
108python3 scripts/result_validator.py \
109 --metrics results.json \
110 --bound-min 0.0 \
111 --bound-max 1.0 \
112 --mass-tol 1e-3 \
113 --json
114```
115
116### Failure Diagnosis
117
118When validation fails:
119
120```bash
121python3 scripts/failure_diagnoser.py --log simulation.log --json
122```
123
124## Conversational Workflow Example
125
126**User**: My phase field simulation crashed after 1000 steps. Can you help me figure out why?
127
128**Agent workflow**:
1291. First, check the log for obvious errors:
130 ```bash
131 python3 scripts/failure_diagnoser.py --log simulation.log --json
132 ```
1332. If diagnosis suggests numerical blow-up, check runtime stats:
134 ```bash
135 python3 scripts/runtime_monitor.py --log simulation.log --json
136 ```
1373. Recommend fixes based on findings:
138 - If residual grew rapidly → reduce time step
139 - If dt collapsed → check stability conditions
140 - If NaN detected → check initial conditions
141
142## Error Handling
143
144| Error | Cause | Resolution |
145|-------|-------|------------|
146| `Config not found` | File path invalid | Verify config path exists |
147| `Non-numeric value` | Parameter is not a number | Fix config file format |
148| `out of range` | Parameter outside bounds | Adjust parameter or bounds |
149| `Output directory not writable` | Permission issue | Check directory permissions |
150| `Insufficient disk space` | Disk nearly full | Free up space or reduce output |
151
152## Interpretation Guidance
153
154### Status Meanings
155
156| Status | Meaning | Action |
157|--------|---------|--------|
158| PASS | All checks passed | Proceed with confidence |
159| WARN | Non-critical issues found | Review and document |
160| BLOCK | Critical issues found | Must fix before proceeding |
161
162### Confidence Score Interpretation
163
164| Score | Meaning |
165|-------|---------|
166| 1.0 | All validation checks passed |
167| 0.75+ | Most checks passed, minor issues |
168| 0.5-0.75 | Significant issues, review carefully |
169| < 0.5 | Major problems, do not trust results |
170
171### Common Failure Patterns
172
173| Pattern in Log | Likely Cause | Recommended Fix |
174|----------------|--------------|-----------------|
175| NaN, Inf, overflow | Numerical instability | Reduce dt, increase damping |
176| max iterations, did not converge | Solver failure | Tune preconditioner, tolerances |
177| out of memory | Memory exhaustion | Reduce mesh, enable out-of-core |
178| dt reduced | Adaptive stepping triggered | May be okay if controlled |
179
180## Limitations
181
182- **Not a real-time monitor**: Scripts analyze logs after-the-fact
183- **Regex-based**: Log parsing depends on pattern matching; may miss unusual formats
184- **No automatic fixes**: Scripts diagnose but don't modify simulations
185
186## References
187
188- `references/validation_protocol.md` - Detailed checklist and criteria
189- `references/log_patterns.md` - Common failure signatures and regex patterns
190
191## Version History
192
193- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, Windows compatibility
194- **v1.0.0**: Initial release with 4 validation scripts
tools-only