Agent skill

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."

View SKILL.md on GitHub Repository
Stars 29
Forks 2

Install this agent skill to your Project

npx add-skill https://github.com/HeshamFS/materials-simulation-skills/tree/main/skills/core-numerical/convergence-study

Metadata

Additional technical details for this skill

author
HeshamFS
version
1.1.0
eval cases
2
tested with 
[
    "claude-code",
    "gemini-cli",
    "vs-code-copilot"
]
last reviewed
2026-03-26
security tier
high
security reviewed
YES

SKILL.md

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

  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

bash
# 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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

HeshamFS/materials-simulation-skills

post-processing

Extract, analyze, and summarize simulation output data — pull spatial fields at specific timesteps, compute time-series trends and detect steady state, extract line profiles through the domain, generate statistical summaries and distributions, calculate derived quantities (gradients, fluxes, volume fractions, interface area), compare results against analytical solutions or experimental data, and produce automated analysis reports. Use when interpreting finished simulation results, checking mass or energy conservation, comparing two runs or meshes, extracting interface profiles from phase-field output, or preparing publication-quality analysis, even if the user only says "what do my results look like" or "did my simulation reach steady state."

29 2
Explore
HeshamFS/materials-simulation-skills

performance-profiling

Identify computational bottlenecks, analyze parallel scaling, estimate memory requirements, and generate optimization recommendations for materials simulations — parse timing logs to find dominant phases (solver, assembly, I/O), evaluate strong and weak scaling efficiency, profile memory from mesh and field parameters, and detect bottlenecks with actionable fix suggestions. Use when a simulation is running slower than expected, investigating MPI scaling efficiency, planning HPC resource allocation, deciding whether to tune the preconditioner or reduce I/O frequency, or estimating if a problem fits in available RAM, even if the user only says "my simulation is too slow" or "how many nodes do I need."

29 2
Explore
HeshamFS/materials-simulation-skills

parameter-optimization

Explore and optimize simulation parameters via design of experiments (DOE), sensitivity analysis, and optimizer selection — generate Latin Hypercube, quasi-random, or factorial sample plans, rank parameter influence with sensitivity scores, recommend Bayesian optimization, CMA-ES, or gradient- based methods based on dimension and budget, and fit surrogate models for expensive evaluations. Use when calibrating material properties against experimental data, planning a parameter sweep, performing uncertainty quantification, or choosing an optimization strategy for a simulation with a limited evaluation budget, even if the user only says "which parameters matter most" or "how do I calibrate my model."

29 2
Explore
HeshamFS/materials-simulation-skills

simulation-validator

Validate simulations across three stages — run pre-flight checks on configuration files (parameter ranges, required fields, disk space), monitor runtime logs for residual growth, NaN/Inf, and adaptive dt collapse, and perform post-flight validation of results (physical bounds, mass/energy conservation, convergence). Diagnose failed simulations with probable-cause analysis and recommended fixes. Use when preparing to launch a simulation, checking whether a running job is healthy, verifying that finished results are trustworthy, or debugging a crash or blow-up, even if the user only says "my simulation crashed" or "can I trust these results."

29 2
Explore
HeshamFS/materials-simulation-skills

simulation-orchestrator

Orchestrate multi-simulation campaigns — generate parameter sweep configurations (grid, linspace, or Latin Hypercube sampling), initialize and track batch job campaigns, monitor job completion status, and aggregate results with summary statistics across all runs. Use when running a parameter study across dt, kappa, or other simulation inputs, managing dozens or hundreds of simulation configurations, combining outputs from completed batch runs to find the best result, or automating the generate-run-collect workflow for systematic studies, even if the user only says "I need to try many parameter combinations" or "how do I organize a sweep."

29 2
Explore
HeshamFS/materials-simulation-skills

ontology-explorer

Parse, navigate, and query materials science ontology structures — browse class hierarchies, inspect individual classes and their properties, look up object and data property definitions with domain/range, search for ontology terms by keyword, and parse or summarize raw OWL/XML files. Supports the OCDO ecosystem (CMSO, ASMO, CDCO, PODO, PLDO, LDO). Use when exploring what classes or properties an ontology provides, finding the right CMSO term for a crystal structure or simulation concept, understanding parent-child class relationships, or onboarding to an unfamiliar materials ontology, even if the user only says "what ontology terms describe my FCC copper simulation" or "show me the CMSO class hierarchy."

29 2
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results