Convergence Study

Perform spatial and temporal convergence analysis for solution verification — compute observed convergence orders from grid or timestep refinement studies, apply Richardson extrapolation to estimate discretization error, and calculate the Grid Convergence Index (GCI) per ASME V&V 20 standards. Use when verifying that a numerical solution converges at the expected rate, estimating the error on the finest mesh, checking whether grids are in the asymptotic range, or preparing formal verification reports, even if the user only asks "is my mesh fine enough" or "how accurate is my solution."

zuoguyoupan2023 Updated Sep 22, 2026

Coding & Dev Tools

Install

Press C to copy

$ npx skillmds@latest add zuoguyoupan2023/convergence-study

Installs into ~/.claude/skills (or .claude/skills inside a project). Restart Claude Code to pick it up.

＋ Add to plugin

README badge

[![SkillMD](https://skillmd.com/badge/zuoguyoupan2023/convergence-study.svg)](https://skillmd.com/skills/zuoguyoupan2023/convergence-study)

Trust & safety

Audits pending

Not yet audited · commit 6a57e0e

Permissions this skill uses

Executes scripts
The instructions run shell commands or bundled script files.

Works with: Claude Code Claude.ai OpenAI Codex +

File contents

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

---name: convergence-studydescription: Perform spatial and temporal convergence analysis for solution verification — compute observed convergence orders from grid or timestep refinement studies, apply Richardson extrapolation to estimate discretization error, and calculate the Grid Convergence Index (GCI) per ASME V&V 20 standards. Use when verifying that a numerical solution converges at the expected rate, estimating the error on the finest mesh, checking whether grids are in the asymptotic range, or preparing formal verification reports, even if the user only asks "is my mesh fine enough" or "how accurate is my solution."---# Convergence Study## GoalProvide script-driven convergence analysis for verifying that numerical solutions converge at the expected rate as the mesh or timestep is refined.## Requirements- Python 3.10+- 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` |## Workflow1. **Run grid/timestep refinement study** with at least 3 levels2. **Compute observed convergence order** with `h_refinement.py` or `dt_refinement.py`3. **Compare** observed order to expected order of the scheme4. **Estimate discretization error** via Richardson extrapolation5. **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```bash# Spatial convergence with 4 grid levelspython3 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 levelspython3 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-orderpython3 scripts/richardson_extrapolation.py --spacings 0.02,0.01 --values 1.0032,1.0008 --order 2.0 --json# GCI for 3-mesh verificationpython3 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 range- `references/gci_guidelines.md` - Roache's GCI method, ASME V&V 20, safety factors

zuoguyoupan2023/awesome-ai-skills/tree/main/skills/HeshamFS/materials-simulation-skills/core-numerical commit 6a57e0eddd

Frequently asked questions

npx skillmds@latest add zuoguyoupan2023/convergence-study