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
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 stencilsreferences/boundary_handling.md - One-sided schemesreferences/scheme_selection.md - FD/FV/spectral comparisonreferences/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
1---2name: differentiation-schemes3description: Select and apply numerical differentiation schemes for PDE/ODE discretization. Use when choosing finite difference/volume/spectral schemes, building stencils, handling boundaries, estimating truncation error, or analyzing dispersion and dissipation.4---5
6# Differentiation Schemes
7
8## Goal
9
10Provide a reliable workflow to select a differentiation scheme, generate stencils, and assess accuracy for simulation discretization.
11
12## Requirements
13
14- Python 3.8+
15- NumPy (for stencil computations)
16- No heavy dependencies
17
18## Inputs to Gather
19
20| Input | Description | Example |
21|-------|-------------|---------|
22| Derivative order | First, second, etc. | `1` or `2` |
23| Target accuracy | Order of truncation error | `2` or `4` |
24| Grid type | Uniform, nonuniform | `uniform` |
25| Boundary type | Periodic, Dirichlet, Neumann | `periodic` |
26| Smoothness | Smooth or discontinuous | `smooth` |
27
28## Decision Guidance
29
30### Scheme Selection Flowchart
31
32```
33Is the field smooth?
34├── YES → Is domain periodic?
35│ ├── YES → Use central differences or spectral
36│ └── NO → Use central interior + one-sided at boundaries
37└── NO → Are there shocks/discontinuities?
38 ├── YES → Use upwind, TVD, or WENO
39 └── NO → Use central with limiters
40```
41
42### Quick Reference
43
44| Situation | Recommended Scheme |
45|-----------|-------------------|
46| Smooth, periodic | Central, spectral |
47| Smooth, bounded | Central + one-sided BCs |
48| Advection-dominated | Upwind |
49| Shocks/fronts | TVD, WENO |
50| High accuracy needed | Compact (Padé), spectral |
51
52## Script Outputs (JSON Fields)
53
54| Script | Key Outputs |
55|--------|-------------|
56| `scripts/stencil_generator.py` | `offsets`, `coefficients`, `order`, `accuracy` |
57| `scripts/scheme_selector.py` | `recommended`, `alternatives`, `notes` |
58| `scripts/truncation_error.py` | `error_scale`, `order`, `notes` |
59
60## Workflow
61
621. **Identify requirements** - derivative order, accuracy, smoothness
632. **Select scheme** - Run `scripts/scheme_selector.py`
643. **Generate stencils** - Run `scripts/stencil_generator.py`
654. **Estimate error** - Run `scripts/truncation_error.py`
665. **Validate** - Test with manufactured solutions or grid refinement
67
68## Conversational Workflow Example
69
70**User**: I need to discretize a second derivative for a diffusion equation on a uniform grid. I want 4th-order accuracy.
71
72**Agent workflow**:
731. Select appropriate scheme:
74 ```bash
75 python3 scripts/scheme_selector.py --smooth --periodic --order 2 --accuracy 4 --json
76 ```
772. Generate the stencil:
78 ```bash
79 python3 scripts/stencil_generator.py --order 2 --accuracy 4 --scheme central --json
80 ```
813. Result: 5-point stencil with coefficients `[-1/12, 4/3, -5/2, 4/3, -1/12]` / dx².
82
83## Pre-Discretization Checklist
84
85- [ ] Confirm derivative order and target accuracy
86- [ ] Choose scheme appropriate to smoothness and boundaries
87- [ ] Generate and inspect stencils at boundaries
88- [ ] Estimate truncation error vs physics scales
89- [ ] Verify with grid refinement study
90
91## CLI Examples
92
93```bash
94# Select scheme for smooth periodic problem
95python3 scripts/scheme_selector.py --smooth --periodic --order 1 --accuracy 4 --json
96
97# Generate central difference stencil for first derivative
98python3 scripts/stencil_generator.py --order 1 --accuracy 2 --scheme central --json
99
100# Generate 4th-order second derivative stencil
101python3 scripts/stencil_generator.py --order 2 --accuracy 4 --scheme central --json
102
103# Estimate truncation error
104python3 scripts/truncation_error.py --dx 0.01 --order 2 --accuracy 2 --scale 1.0 --json
105```
106
107## Error Handling
108
109| Error | Cause | Resolution |
110|-------|-------|------------|
111| `order must be positive` | Invalid derivative order | Use 1, 2, 3, ... |
112| `accuracy must be even for central` | Odd accuracy requested | Use 2, 4, 6, ... |
113| `Unknown scheme` | Invalid scheme type | Use central, upwind, compact |
114
115## Interpretation Guidance
116
117### Stencil Properties
118
119| Property | Meaning |
120|----------|---------|
121| Symmetric offsets | Central scheme (no directional bias) |
122| Asymmetric offsets | One-sided or upwind scheme |
123| More points | Higher accuracy but wider stencil |
124
125### Truncation Error Scaling
126
127| Accuracy Order | Error Scales As | Refinement Factor |
128|----------------|-----------------|-------------------|
129| 2nd order | O(dx²) | 2× refinement → 4× error reduction |
130| 4th order | O(dx⁴) | 2× refinement → 16× error reduction |
131| 6th order | O(dx⁶) | 2× refinement → 64× error reduction |
132
133### Common Stencils
134
135| Derivative | Accuracy | Points | Coefficients (× 1/dx or 1/dx²) |
136|------------|----------|--------|-------------------------------|
137| 1st | 2 | 3 | [-1/2, 0, 1/2] |
138| 1st | 4 | 5 | [1/12, -2/3, 0, 2/3, -1/12] |
139| 2nd | 2 | 3 | [1, -2, 1] |
140| 2nd | 4 | 5 | [-1/12, 4/3, -5/2, 4/3, -1/12] |
141
142## Limitations
143
144- **Boundary handling**: Stencil generator provides interior stencils; boundaries need special treatment
145- **Nonuniform grids**: Standard stencils assume uniform spacing
146- **Spectral**: Not covered by stencil generator
147
148## References
149
150- `references/stencil_catalog.md` - Common stencils
151- `references/boundary_handling.md` - One-sided schemes
152- `references/scheme_selection.md` - FD/FV/spectral comparison
153- `references/error_guidance.md` - Truncation error scaling
154
155## Version History
156
157- **v1.1.0** (2024-12-24): Enhanced documentation, decision guidance, examples
158- **v1.0.0**: Initial release with 3 differentiation scripts
tools-only