科研 Skill
数值解空间时间收敛性分析
convergence-study
Performs spatial/temporal convergence analysis for solution verification: observed order, Richardson extrapolation. Use when checking that a simulation result is grid/timestep independent.
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.10+
- No third-party packages — scripts use only the Python standard library (
math).
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, results.extrapolated_value, results.notes |
Workflow
- Run grid/timestep refinement study with at least 3 levels
- Compute observed convergence order with
h_refinement.pyordt_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? --> Order agreement; check persistence and error assumptions
| +-- 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 | Evidence consistent with the expected error law | Check persistence across levels; label estimates conditional |
| 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 | See caveat below | Confirm with order comparison |
| GCI asymptotic ratio far from 1.0 | Not in asymptotic range | Refine further |
Asymptotic-ratio caveat (constant refinement ratios). When the refinement ratios are equal (
r21 == r32, the common case), the asymptotic ratioAR = GCI_coarse / (r^p * GCI_fine)reduces algebraically tof1/f2. It then only measures the relative gap between the two finest QoI values — not whether the data follow the assumed power law — so anARnear 1.0 can give false reassurance even when the observed order is far from expected. Thegci_calculator.pyJSON emits anotesentry flagging this. For a real asymptotic-range determination:
- Compare the observed order
pto the scheme's theoretical/expected order — a match supports the expected error law but does not establish an asymptotic range.- For stronger verification, use 4+ systematically refined grids and check that the observed order is consistent across successive grid triplets (
h_refinement.pyreports one order per triplet plusmean_order).
Verification checklist
When explaining a refinement result, compare only the dimensionless
results.mean_order with the expected order. The
results.richardson_extrapolated_value estimates the observable at zero spacing
and has the same units as the input observable; it is never the convergence
order. Use order_comparison, extrapolation_evidence, and
scientific_interpretation from h_refinement.py to keep these roles explicit.
For h=(0.2,0.1,0.05) and values=(1.04,1.01,1.0025), p=2 and the extrapolated
observable=1. Compare 2 with the expected order, not 1. Keep this guidance in
the final synthesis context. A single grid triplet cannot establish stable
order across triplets: in_asymptotic_range is null for a positive single
estimate. More grids, residual convergence and model validation remain needed.
Use the deterministic explanation renderer
for final scientific text from trusted, input-verified h_refinement JSON.
An order agreement decision is true when the measured order is within the
stated tolerance, even though physical accuracy and asymptotic behavior remain
unproven. The relative tolerance 0.1 means 10%, not 0.1%.
- Used >= 3 systematically refined grids/timesteps so
h_refinement.py/dt_refinement.pycan report aresults.mean_order; recorded the per-tripletresults.observed_orders(a single-pair Richardson run does not verify order). - Recorded
results.mean_orderand confirmedresults.convergence_assessmentreadsPASS(observed order within 10% of the scheme's expected order); aFAILorunknownmeans the result is not yet verified. - Checked
results.in_asymptotic_rangeand all notes. Null means insufficient evidence; true is only a successive-order heuristic, not proof. Label any quoted extrapolation conditional on the power-law error assumption, and suppress it for invalid or diverging sequences. - Checked refinement ratios
r21/r32fromgci_calculator.pyare >= 1.3 (round-off noise floor) and that noOscillatory convergence detectederror was raised. - Recorded
results.gci_fine(with the safety factor used: 1.25 for >= 3 grids with verified order, 3.0 for 2 grids with assumed order) as the reported discretization uncertainty, plusresults.extrapolated_valueas the best estimate. - For constant refinement ratios, did NOT treat
asymptotic_rationear 1.0 as proof of asymptotic range (it degenerates tof1/f2); confirmed the asymptotic range via observed-order-vs-expected and read thegci_calculator.pynotescaveat.
Common pitfalls & rationalizations
| Tempting shortcut | Why it's wrong / what to do |
|---|---|
| "Two grids agree closely, so it's converged" | Two levels cannot estimate observed order. Run h_refinement.py/dt_refinement.py with >= 3 levels; a 2-grid Richardson run uses an assumed order and needs safety factor 3.0, not 1.25. |
| "The asymptotic ratio is ~1.0, so we're in the asymptotic range" | With constant refinement ratios AR = GCI_coarse/(r^p*GCI_fine) reduces to f1/f2 and only measures the gap between the two finest QoI values. Verify the asymptotic range by comparing observed order to the expected order (and 4+ grid consistency). |
| "GCI_fine is tiny, so the solution is grid-independent" | A near-zero GCI can also mean the QoI is insensitive to refinement or the differences are in round-off noise (ratios < 1.3). Confirm in_asymptotic_range is true and refinement ratios are >= 1.3 first. |
| "Observed order is higher than expected, even better" | Order well above the formal order usually signals superconvergence or error cancellation, not extra accuracy. Treat it as a flag (convergence_assessment is FAIL when >10% off) and verify with more grid levels. |
| "The script printed an extrapolated value, so use it" | When the observed order is non-positive the solution is diverging and h_refinement.py returns richardson_extrapolated_value = null with a diverging note. Do not quote an extrapolated value or GCI in that case. |
| "Implicit/stable solver, so any timestep is fine for the study" | Temporal stability is not temporal accuracy. dt_refinement.py still needs >= 3 systematically reduced timesteps to recover the scheme's order; a too-coarse dt sequence stays pre-asymptotic. |
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 not less than 1.0 (Roache uses Fs in {1.25, 3.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 (
mathmodule); 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 rangereferences/gci_guidelines.md- Roache's GCI method, ASME V&V 20, safety factors
示例提示词
帮我对这组网格加密数据做GCI收敛指数分析,评估离散误差。
所属插件
安装该插件会一并获得同领域的 23 个 Skill / MCP。
同插件的其他科研 Skill
- 制造解法验证与基准测试规划Plans verification and validation campaigns using manufactured solutions, canonical benchmarks. Use when an agent must prove a solver is correct before trusting results.
- PDE数值微分格式选择Selects and applies numerical differentiation schemes for PDE/ODE discretization: finite-difference stencils. Use when choosing a spatial discretization scheme.
- 仿真结果FAIR归档打包Creates FAIR-minded reproducibility bundles for simulations: file inventories, hashes, units, engine versions. Use before publishing or archiving a simulation dataset.
- HPC作业运行诊断Diagnoses HPC runtime and scheduler problems for materials simulations: MPI/OpenMP/GPU layout, modules, scratch paths, walltime. Use when a cluster job fails, hangs, or underperforms.
- 线性方程组求解器选型Selects and configures linear solvers for Ax=b systems: direct (LU, Cholesky) versus iterative (CG, GMRES, BiCGSTAB) methods, sparsity. Use when choosing a linear solver for a simulation.
- 分子动力学分析方案规划Plans molecular dynamics post-processing for materials simulations: RDF, MSD/diffusion, VACF/VDOS, coordination numbers. Use when deciding which MD analysis to run and in what order.
- 数值模拟网格生成规划Plans and evaluates mesh generation for numerical simulations: grid resolution from physics scales, aspect ratio/skewness checks. Use when designing or auditing a simulation mesh.
- 非线性方程组求解器选型Selects and configures nonlinear solvers for root-finding, optimization, and least-squares problems: Newton, quasi-Newton, Broyden, Anderson acceleration. Use when choosing a nonlinear solver.
- 时间积分方法选择Selects and configures time-integration methods for ODE/PDE simulations: explicit Runge-Kutta, BDF, Rosenbrock. Use when choosing a time-stepping scheme for a solver.
- 偏微分方程数值稳定性分析Analyzes numerical stability for time-dependent PDE simulations: CFL/Fourier criteria, von Neumann analysis. Use when a simulation blows up or to check a scheme’s stability limits.
- 材料科学本体浏览查询Parses, navigates, and queries materials science ontology structures: class hierarchies, property domain/range lookup. Use when exploring an unfamiliar materials ontology.
- 材料术语本体映射Maps materials science terms, crystal structures, and sample descriptions to standardized ontology classes with confidence scores. Use when annotating data for ontology interoperability.
- 本体标注一致性校验Validates material sample annotations against ontology constraints: class/property existence, domain/range consistency. Use before publishing ontology-annotated materials data.
- 仿真参数优化与敏感性分析Explores and optimizes simulation parameters via design of experiments, sensitivity analysis, and optimizer selection: Latin Hypercube, quasi-random. Use when calibrating simulation parameters.
- 仿真计算性能剖析Identifies computational bottlenecks, parallel scaling, and memory requirements for materials simulations: parses timing logs for dominant phases. Use when a simulation is slow or scales poorly.
- 仿真输出数据后处理Extracts, analyzes, and summarizes simulation output data: spatial fields at timesteps, time-series trends, steady-state detection. Use when turning raw simulation output into summary statistics.
- 多代码仿真故障分诊Provides first-response triage for cross-code LAMMPS/VASP/QE/MOOSE simulation failures: classifies nonconvergence, NaN/Inf. Use when a simulation crashes and the cause is unclear.
- 多任务仿真批量编排Orchestrates multi-simulation campaigns: generates parameter sweeps (grid, linspace, Latin Hypercube), tracks batch job status. Use when running and managing many related simulation jobs.
- 仿真三阶段有效性校验Validates simulations across three stages: pre-flight config checks, runtime log monitoring for NaN/Inf and residual growth. Use to catch simulation errors before, during, and after a run.
- SLURM作业脚本生成Generates correct SLURM sbatch job scripts and sanity-checks HPC resource requests: nodes, MPI/OpenMP layout, memory, GPUs, walltime. Use when writing or debugging a SLURM submission script.
- 瞬态仿真时间步策略Plans and controls time-step policies for transient simulations: CFL and physics-based stability limits, adaptive stepping. Use when setting up a time-stepping strategy for a solver.
- 计算材料工作流引擎选型Maps computational materials tasks onto workflow engines (atomate2, jobflow, AiiDA, pyiron) or a one-off script. Use when deciding how to structure a reproducible campaign or DAG.
常见问题
数值解空间时间收敛性分析能做什么?
Performs spatial/temporal convergence analysis for solution verification: observed order, Richardson extrapolation. Use when checking that a simulation result is grid/timestep independent。
如何安装数值解空间时间收敛性分析?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「数值解空间时间收敛性分析」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
数值解空间时间收敛性分析需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
数值解空间时间收敛性分析经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。