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 |
Security
Input Validation
- All numeric parameters (
spacings, timesteps, values, expected-order, order) are validated as finite positive numbers - Comma-separated value lists are length-matched (spacings and values must have equal length) and capped at 10,000 entries
- GCI calculator enforces exactly 3 refinement levels; Richardson extrapolation requires at least 2
- Safety factor is validated as a finite number greater than 1.0
File Access
- Scripts read no external files; all inputs are provided via CLI arguments
- Scripts write only to stdout (JSON output); no files are created unless the agent explicitly uses the Write tool
Tool Restrictions
- Bash: Used to execute the four Python analysis scripts (
h_refinement.py, dt_refinement.py, richardson_extrapolation.py, gci_calculator.py) with explicit argument lists - Read: Used to inspect script source and reference documentation
Safety Measures
- No
eval(), exec(), or dynamic code generation - All subprocess calls use explicit argument lists (no
shell=True) - Scripts use only Python standard library (
math module); no pickle loading or deserialization of untrusted data - Minimal tool surface (Bash and Read only) limits the agent's ability to modify the filesystem
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
