What are the main outputs of the script suite?

scheme_selector.py outputs recommended, alternatives, and notes; stencil_generator.py outputs offsets, coefficients, order, and accuracy; truncation_error.py outputs error_scale, order, and notes.

How should I handle non-periodic boundaries?

Use central interior stencils where possible and apply one-sided stencils at boundaries; choose BCs consistent with the problem (Dirichlet/Neumann).

How can I verify accuracy and stability?

Perform grid refinement studies, compare truncation error against scales, and use manufactured solutions to isolate discretization errors.

differentiation-schemes

Scanned

npx machina-cli add skill HeshamFS/materials-simulation-skills/differentiation-schemes --openclaw

Files (1)

SKILL.md

5.4 KB

Differentiation Schemes

Goal

Provide a reliable workflow to select a differentiation scheme, generate stencils, and assess accuracy for simulation discretization.

Requirements

Python 3.8+
NumPy (for stencil computations)
No heavy dependencies

Inputs to Gather

Input	Description	Example
Derivative order	First, second, etc.	`1` or `2`
Target accuracy	Order of truncation error	`2` or `4`
Grid type	Uniform, nonuniform	`uniform`
Boundary type	Periodic, Dirichlet, Neumann	`periodic`
Smoothness	Smooth or discontinuous	`smooth`

Decision Guidance

Scheme Selection Flowchart

Is the field smooth?
├── YES → Is domain periodic?
│   ├── YES → Use central differences or spectral
│   └── NO → Use central interior + one-sided at boundaries
└── NO → Are there shocks/discontinuities?
    ├── YES → Use upwind, TVD, or WENO
    └── NO → Use central with limiters

Quick Reference

Situation	Recommended Scheme
Smooth, periodic	Central, spectral
Smooth, bounded	Central + one-sided BCs
Advection-dominated	Upwind
Shocks/fronts	TVD, WENO
High accuracy needed	Compact (Padé), spectral

Script Outputs (JSON Fields)

Script	Key Outputs
`scripts/stencil_generator.py`	`offsets`, `coefficients`, `order`, `accuracy`
`scripts/scheme_selector.py`	`recommended`, `alternatives`, `notes`
`scripts/truncation_error.py`	`error_scale`, `order`, `notes`

Workflow

Identify requirements - derivative order, accuracy, smoothness
Select scheme - Run scripts/scheme_selector.py
Generate stencils - Run scripts/stencil_generator.py
Estimate error - Run scripts/truncation_error.py
Validate - Test with manufactured solutions or grid refinement

Conversational Workflow Example

User: I need to discretize a second derivative for a diffusion equation on a uniform grid. I want 4th-order accuracy.

Agent workflow:

Select appropriate scheme:

python3 scripts/scheme_selector.py --smooth --periodic --order 2 --accuracy 4 --json

Generate the stencil:

python3 scripts/stencil_generator.py --order 2 --accuracy 4 --scheme central --json

Result: 5-point stencil with coefficients [-1/12, 4/3, -5/2, 4/3, -1/12] / dx².

Pre-Discretization Checklist

Confirm derivative order and target accuracy
Choose scheme appropriate to smoothness and boundaries
Generate and inspect stencils at boundaries
Estimate truncation error vs physics scales
Verify with grid refinement study

CLI Examples

# Select scheme for smooth periodic problem
python3 scripts/scheme_selector.py --smooth --periodic --order 1 --accuracy 4 --json

# Generate central difference stencil for first derivative
python3 scripts/stencil_generator.py --order 1 --accuracy 2 --scheme central --json

# Generate 4th-order second derivative stencil
python3 scripts/stencil_generator.py --order 2 --accuracy 4 --scheme central --json

# Estimate truncation error
python3 scripts/truncation_error.py --dx 0.01 --order 2 --accuracy 2 --scale 1.0 --json

Error Handling

Error	Cause	Resolution
`order must be positive`	Invalid derivative order	Use 1, 2, 3, ...
`accuracy must be even for central`	Odd accuracy requested	Use 2, 4, 6, ...
`Unknown scheme`	Invalid scheme type	Use central, upwind, compact

Interpretation Guidance

Stencil Properties

Property	Meaning
Symmetric offsets	Central scheme (no directional bias)
Asymmetric offsets	One-sided or upwind scheme
More points	Higher accuracy but wider stencil

Truncation Error Scaling

Accuracy Order	Error Scales As	Refinement Factor
2nd order	O(dx²)	2× refinement → 4× error reduction
4th order	O(dx⁴)	2× refinement → 16× error reduction
6th order	O(dx⁶)	2× refinement → 64× error reduction

Common Stencils

Derivative	Accuracy	Points	Coefficients (× 1/dx or 1/dx²)
1st	2	3	[-1/2, 0, 1/2]
1st	4	5	[1/12, -2/3, 0, 2/3, -1/12]
2nd	2	3	[1, -2, 1]
2nd	4	5	[-1/12, 4/3, -5/2, 4/3, -1/12]

Limitations

Boundary handling: Stencil generator provides interior stencils; boundaries need special treatment
Nonuniform grids: Standard stencils assume uniform spacing
Spectral: Not covered by stencil generator

References

references/stencil_catalog.md - Common stencils
references/boundary_handling.md - One-sided schemes
references/scheme_selection.md - FD/FV/spectral comparison
references/error_guidance.md - Truncation error scaling

Version History

v1.1.0 (2024-12-24): Enhanced documentation, decision guidance, examples
v1.0.0: Initial release with 3 differentiation scripts

Source

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

View on GitHub

Overview

Differentiation Schemes provides a practical workflow to choose, generate, and evaluate numerical differentiation operators for PDE/ODE discretization. It covers finite difference, finite volume, and spectral approaches, how to build stencils, handle boundaries, estimate truncation error, and analyze dispersion and dissipation.

How This Skill Works

Begin by gathering inputs: derivative order, target accuracy, grid type, boundary type, and smoothness. Use the included scripts to select a scheme (scheme_selector.py), generate stencils (stencil_generator.py), and assess truncation error (truncation_error.py). Validate results with grid refinement or manufactured solutions.

When to Use It

Discretizing a smooth, periodic problem on a uniform grid requiring high accuracy (central or spectral).
Non-periodic domain with Dirichlet or Neumann boundaries and smooth solution needing central interior plus boundary stencils.
Advection-dominated flow with potential shocks where upwind, TVD, or WENO is preferred.
Shocks/fronts or discontinuities require robust non-oscillatory schemes (TVD/WENO).
Need extremely high accuracy in smooth problems via compact (Padé) or spectral schemes.

Quick Start

Step 1: Identify derivative order, target accuracy, grid type, boundary type, and smoothness.
Step 2: Run python3 scripts/scheme_selector.py with appropriate flags (e.g., --smooth --periodic --order 2 --accuracy 4 --json) to get a recommended scheme.
Step 3: Run python3 scripts/stencil_generator.py --order 2 --accuracy 4 --scheme central --json to produce the stencil and coefficients.

Best Practices

Gather derivative order, target accuracy, grid type, boundary type, and smoothness before selecting a scheme.
Use scheme_selector.py to pick recommended options and review alternatives and notes.
Generate and inspect stencils at boundaries with stencil_generator.py before applying them in a solver.
Estimate truncation error with truncation_error.py and compare against physics scales.
Validate results with grid refinement studies or manufactured solutions.

Example Use Cases

4th-order central second-derivative stencil on a uniform grid yielding a 5-point stencil with coefficients [-1/12, 4/3, -5/2, 4/3, -1/12] / dx^2.
Central difference stencil for first derivative on a smooth periodic problem (central or spectral method).
Central interior stencil with one-sided boundary stencils for non-periodic domains with Dirichlet/Neumann BCs.
Advection-dominated flow where upwind schemes (or TVD) are selected to reduce oscillations.
Shocks/fronts handled with TVD or WENO schemes for non-oscillatory solutions.

Frequently Asked Questions

Add this skill to your agents