convergence-study

name convergence-study description Spatial and temporal convergence analysis with Richardson extrapolation and Grid Convergence Index (GCI) for solution verification allowed-tools ["Bash","Read"] 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 range references/gci_guidelines.md - Roache's GCI method, ASME V&V 20, safety factors