Convergence Study
Goal
Provide script-driven convergence analysis for verifying that numerical solutions converge at the expected rate as the mesh or timestep is refined.
Requirements
- Python 3.8+
- NumPy (not required; scripts use only math stdlib)
Inputs to Gather
| Input |
Description |
Example |
| Grid spacings |
Sequence of mesh sizes (coarse to fine) |
0.4,0.2,0.1,0.05 |
| Timestep sizes |
Sequence of dt values |
0.04,0.02,0.01 |
| Solution values |
QoI at each refinement level |
1.16,1.04,1.01,1.0025 |
| Expected order |
Formal order of the numerical scheme |
2.0 |
| Safety factor |
GCI safety factor (1.25 default) |
1.25 |
Script Outputs (JSON Fields)
| Script |
Key Outputs |
scripts/h_refinement.py |
results.observed_orders, results.mean_order, results.richardson_extrapolated_value, results.convergence_assessment |
scripts/dt_refinement.py |
Same as h_refinement but for temporal convergence |
scripts/richardson_extrapolation.py |
results.extrapolated_value, results.error_estimate, results.observed_order |
scripts/gci_calculator.py |
results.observed_order, results.gci_fine, results.gci_coarse, results.asymptotic_ratio, results.in_asymptotic_range |
Workflow
- Run grid/timestep refinement study with at least 3 levels
- Compute observed convergence order with
h_refinement.py or dt_refinement.py
- Compare observed order to expected order of the scheme
- Estimate discretization error via Richardson extrapolation
- Report GCI for formal solution verification using
gci_calculator.py
- Document convergence results and any anomalies
Decision Guidance
Do you have 3+ refinement levels?
+-- YES --> Run h_refinement.py or dt_refinement.py
| +-- Observed order matches expected? --> Solution verified
| +-- Order too low? --> Check: pre-asymptotic, coding error, insufficient resolution
| +-- Order too high? --> Check: superconvergence or cancellation effects
+-- NO (only 2 levels) --> Use richardson_extrapolation.py with assumed order
(less reliable without order verification)
CLI Examples
# Spatial convergence with 4 grid levels
python3 scripts/h_refinement.py --spacings 0.4,0.2,0.1,0.05 --values 1.16,1.04,1.01,1.0025 --expected-order 2.0 --json
# Temporal convergence with 3 timestep levels
python3 scripts/dt_refinement.py --timesteps 0.04,0.02,0.01 --values 2.12,2.03,2.0075 --expected-order 2.0 --json
# Richardson extrapolation with assumed 2nd-order
python3 scripts/richardson_extrapolation.py --spacings 0.02,0.01 --values 1.0032,1.0008 --order 2.0 --json
# GCI for 3-mesh verification
python3 scripts/gci_calculator.py --spacings 0.04,0.02,0.01 --values 1.0128,1.0032,1.0008 --json
Error Handling
| Error |
Cause |
Resolution |
spacings and values must have the same length |
Mismatched input arrays |
Provide equal-length lists |
At least 2 refinement levels required |
Too few data points |
Add more refinement levels |
Exactly 3 refinement levels required |
GCI needs 3 levels |
Provide fine/medium/coarse |
Oscillatory convergence detected |
Non-monotone convergence |
Check mesh quality or scheme |
Interpretation Guidance
| Scenario |
Meaning |
Action |
| Observed order matches expected |
Solution in asymptotic range |
Report GCI, extrapolate |
| Observed order < expected |
Pre-asymptotic or coding bug |
Refine further or debug |
| Negative observed order |
Solution diverging |
Check implementation |
| GCI asymptotic ratio near 1.0 |
Grids in asymptotic range |
Results are reliable |
| GCI asymptotic ratio far from 1.0 |
Not in asymptotic range |
Refine further |
References
references/convergence_theory.md - Formal convergence order, log-log analysis, asymptotic rangereferences/gci_guidelines.md - Roache's GCI method, ASME V&V 20, safety factors
1---2name: convergence-study3description: Spatial and temporal convergence analysis with Richardson extrapolation and Grid Convergence Index (GCI) for solution verification4---56# Convergence Study78## Goal910Provide script-driven convergence analysis for verifying that numerical solutions converge at the expected rate as the mesh or timestep is refined.1112## Requirements1314- Python 3.8+15- NumPy (not required; scripts use only math stdlib)1617## Inputs to Gather1819| Input | Description | Example |20|-------|-------------|---------|21| Grid spacings | Sequence of mesh sizes (coarse to fine) | `0.4,0.2,0.1,0.05` |22| Timestep sizes | Sequence of dt values | `0.04,0.02,0.01` |23| Solution values | QoI at each refinement level | `1.16,1.04,1.01,1.0025` |24| Expected order | Formal order of the numerical scheme | `2.0` |25| Safety factor | GCI safety factor (1.25 default) | `1.25` |2627## Script Outputs (JSON Fields)2829| Script | Key Outputs |30|--------|-------------|31| `scripts/h_refinement.py` | `results.observed_orders`, `results.mean_order`, `results.richardson_extrapolated_value`, `results.convergence_assessment` |32| `scripts/dt_refinement.py` | Same as h_refinement but for temporal convergence |33| `scripts/richardson_extrapolation.py` | `results.extrapolated_value`, `results.error_estimate`, `results.observed_order` |34| `scripts/gci_calculator.py` | `results.observed_order`, `results.gci_fine`, `results.gci_coarse`, `results.asymptotic_ratio`, `results.in_asymptotic_range` |3536## Workflow37381. **Run grid/timestep refinement study** with at least 3 levels392. **Compute observed convergence order** with `h_refinement.py` or `dt_refinement.py`403. **Compare** observed order to expected order of the scheme414. **Estimate discretization error** via Richardson extrapolation425. **Report GCI** for formal solution verification using `gci_calculator.py`436. **Document** convergence results and any anomalies4445## Decision Guidance4647```48Do you have 3+ refinement levels?49+-- YES --> Run h_refinement.py or dt_refinement.py50| +-- Observed order matches expected? --> Solution verified51| +-- Order too low? --> Check: pre-asymptotic, coding error, insufficient resolution52| +-- Order too high? --> Check: superconvergence or cancellation effects53+-- NO (only 2 levels) --> Use richardson_extrapolation.py with assumed order54 (less reliable without order verification)55```5657## CLI Examples5859```bash60# Spatial convergence with 4 grid levels61python3 scripts/h_refinement.py --spacings 0.4,0.2,0.1,0.05 --values 1.16,1.04,1.01,1.0025 --expected-order 2.0 --json6263# Temporal convergence with 3 timestep levels64python3 scripts/dt_refinement.py --timesteps 0.04,0.02,0.01 --values 2.12,2.03,2.0075 --expected-order 2.0 --json6566# Richardson extrapolation with assumed 2nd-order67python3 scripts/richardson_extrapolation.py --spacings 0.02,0.01 --values 1.0032,1.0008 --order 2.0 --json6869# GCI for 3-mesh verification70python3 scripts/gci_calculator.py --spacings 0.04,0.02,0.01 --values 1.0128,1.0032,1.0008 --json71```7273## Error Handling7475| Error | Cause | Resolution |76|-------|-------|------------|77| `spacings and values must have the same length` | Mismatched input arrays | Provide equal-length lists |78| `At least 2 refinement levels required` | Too few data points | Add more refinement levels |79| `Exactly 3 refinement levels required` | GCI needs 3 levels | Provide fine/medium/coarse |80| `Oscillatory convergence detected` | Non-monotone convergence | Check mesh quality or scheme |8182## Interpretation Guidance8384| Scenario | Meaning | Action |85|----------|---------|--------|86| Observed order matches expected | Solution in asymptotic range | Report GCI, extrapolate |87| Observed order < expected | Pre-asymptotic or coding bug | Refine further or debug |88| Negative observed order | Solution diverging | Check implementation |89| GCI asymptotic ratio near 1.0 | Grids in asymptotic range | Results are reliable |90| GCI asymptotic ratio far from 1.0 | Not in asymptotic range | Refine further |9192## References9394- `references/convergence_theory.md` - Formal convergence order, log-log analysis, asymptotic range95- `references/gci_guidelines.md` - Roache's GCI method, ASME V&V 20, safety factors
luokai0