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

Script Outputs (JSON Fields)

Workflow

1. Run grid/timestep refinement study with at least 3 levels
2. Compute observed convergence order with h_refinement.py or dt_refinement.py
3. Compare observed order to expected order of the scheme
4. Estimate discretization error via Richardson extrapolation
5. Report GCI for formal solution verification using gci_calculator.py
6. 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

Interpretation Guidance

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 range
• references/gci_guidelines.md - Roache's GCI method, ASME V&V 20, safety factors