What inputs are required for the convergence study?

Grid spacings, timestep sizes, QoI values, the expected order of the scheme, and a safety factor (GCI defaults to 1.25).

How many refinement levels are needed for reliable results?

At least 3 refinement levels are recommended for both spatial and temporal convergence. Richardson extrapolation can be used with 2 levels if the order is assumed, but it is less reliable without order verification.

What outputs do the scripts produce?

h_refinement.py outputs observed_orders, mean_order, Richardson_extrapolated_value, and convergence_assessment; dt_refinement.py provides the same fields for temporal convergence; richardson_extrapolation.py yields extrapolated_value, error_estimate, and observed_order; gci_calculator.py reports observed_order, gci_fine, gci_coarse, asymptotic_ratio, and in_asymptotic_range.

convergence-study

Scanned

npx machina-cli add skill HeshamFS/materials-simulation-skills/convergence-study --openclaw

Files (1)

SKILL.md

4.2 KB

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

Source

git clone https://github.com/HeshamFS/materials-simulation-skills/blob/main/skills/core-numerical/convergence-study/SKILL.md

View on GitHub

Overview

Provides script-driven convergence analysis to verify numerical solutions converge at the expected rate as mesh or timestep is refined. It uses Richardson extrapolation and the Grid Convergence Index (GCI) to quantify discretization errors and solution verification. Inputs include grid spacings, timestep sizes, QoI values, the scheme order, and a safety factor.

How This Skill Works

Requires Python 3.8+; orchestrates four scripts (h_refinement.py, dt_refinement.py, richardson_extrapolation.py, gci_calculator.py) to compute observed orders, extrapolated values, errors, and GCI metrics. You feed in sequences of grid spacings, timestep sizes, and QoI values; the scripts output structured JSON fields such as observed_orders, extrapolated_value, gci_fine, gci_coarse, and convergence assessments.

When to Use It

You have at least 3 refinement levels for spatial grids or timesteps
You want to verify that the numerical order matches the formal order of the scheme
You need Richardson extrapolation to estimate discretization error
You require Grid Convergence Index (GCI) for formal solution verification
You are documenting convergence results and any anomalies in a project report

Quick Start

Step 1: Prepare inputs (spacings or timesteps, QoI values, and expected order)
Step 2: Run the appropriate script, e.g., 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
Step 3: Review the generated JSON results (observed_order, extrapolated_value, gci metrics) to assess convergence

Best Practices

Use at least 3 refinement levels and ensure QoI is monotone with refinement
Keep the QoI definition consistent across all refinement levels
Compare observed order to the expected order and inspect pre-asymptotic behavior
Ensure refinements stay within the asymptotic range before relying on GCI
Document any deviations, anomalies, or potential coding errors during refinement

Example Use Cases

Spatial convergence: run h_refinement.py with spacings 0.4, 0.2, 0.1, 0.05 and QoI 1.16, 1.04, 1.01, 1.0025
Temporal convergence: run dt_refinement.py with timesteps 0.04, 0.02, 0.01 and QoI 2.12, 2.03, 2.0075
Richardson extrapolation: apply richardson_extrapolation.py with spacings 0.02, 0.01, QoI 1.0032, 1.0008 and order 2
GCI verification: run gci_calculator.py with spacings 0.04, 0.02, 0.01 and values 1.0128, 1.0032, 1.0008
Interpretation: analyze observed orders, asymptotic range, and document convergence results

Frequently Asked Questions

Add this skill to your agents