name	devito-sim
description	Use when driving Devito (symbolic finite-difference DSL with JIT C codegen, originally for seismic imaging at Imperial College) via Python scripts — wave / heat / acoustic / elastic PDEs on regular grids with high-order stencils, automatic vectorization & OpenMP through codegen, through sim runtime one-shot execution.

devito-sim

You are connected to Devito via sim-cli.

Devito generates and JIT-compiles optimized C kernels from a symbolic finite-difference description (built on SymPy). Pip-installable (pip install devito); requires a system C compiler (gcc/clang) present on PATH.

Scripts are plain .py:

from devito import Grid, TimeFunction, Eq, solve, Operator
grid = Grid(shape=(100, 100), extent=(1.0, 1.0))
u = TimeFunction(name='u', grid=grid, time_order=1, space_order=2)
eq = Eq(u.dt, 0.1*(u.dx2 + u.dy2))            # diffusion
op = Operator([Eq(u.forward, solve(eq, u.forward))])
op.apply(time_M=100, dt=0.001)

Same subprocess driver mode as PyBaMM / PyMFEM.

base/ — always relevant

Path	What's there
`base/reference/workflow.md`	Grid → Function → Eq → Operator → apply.
`base/reference/derivatives.md`	`.dt`, `.dx`, `.dx2`, `.laplace`, mixed derivatives.
`base/reference/operators.md`	`solve()`, `Operator()`, time_M / space iteration limits.
`base/snippets/01_diffusion.py`	Verified 2D heat-diffusion E2E.
`base/known_issues.md`	C compiler dep, time_order vs space_order, codegen cache.

sdk/4/ — Devito 4.x

sdk/4/notes.md — version-specific surface notes.

Hard constraints

Devito requires a C compiler on PATH (gcc, clang, or icc). The driver detects Devito Python module; runtime compile failures show up at first op.apply(...) call.
Function for static fields, TimeFunction for time-dependent. TimeFunction(time_order=N) allocates N+1 time slots (current + N history) cyclically.
CFL stability: explicit schemes need dt ≤ C * dx² / α (diffusion) or dt ≤ dx / v (advection / wave). Pick conservatively.
Acceptance != "ran without error". Validate against:
- mass / energy conservation (closed BC: sum should be invariant)
- analytical (e.g. Gaussian diffusion peak decay, plane wave amplitude)
- peak position (advection: should move v*t)
Print results as JSON on the last stdout line. Cast numpy floats: float(u.data[-1].max()).

Required protocol

Gather inputs:
- Category A: PDE, domain shape & extent, IC/BCs, time span, stencil order, acceptance.
- Category B: dt, OpenMP threads (env var DEVITO_LANGUAGE=openmp and OMP_NUM_THREADS), codegen cache dir.
sim check devito.
Write .py per base/reference/workflow.md.
sim lint script.py.
sim run script.py --solver devito.
Validate JSON.

devito-sim

You are connected to Devito via sim-cli.

Scripts are plain .py:

from devito import Grid, TimeFunction, Eq, solve, Operator grid = Grid(shape=(100, 100), extent=(1.0, 1.0)) u = TimeFunction(name='u', grid=grid, time_order=1, space_order=2) eq = Eq(u.dt, 0.1*(u.dx2 + u.dy2)) # diffusion op = Operator([Eq(u.forward, solve(eq, u.forward))]) op.apply(time_M=100, dt=0.001)

Same subprocess driver mode as PyBaMM / PyMFEM.

base/ — always relevant

Path

What's there

base/reference/workflow.md

Grid → Function → Eq → Operator → apply.

base/reference/derivatives.md

.dt, .dx, .dx2, .laplace, mixed derivatives.

base/reference/operators.md

solve(), Operator(), time_M / space iteration limits.

base/snippets/01_diffusion.py

Verified 2D heat-diffusion E2E.

base/known_issues.md

C compiler dep, time_order vs space_order, codegen cache.

sdk/4/ — Devito 4.x

sdk/4/notes.md — version-specific surface notes.

Hard constraints

Devito requires a C compiler on PATH (gcc, clang, or icc). The driver detects Devito Python module; runtime compile failures show up at first op.apply(...) call.

Function for static fields, TimeFunction for time-dependent. TimeFunction(time_order=N) allocates N+1 time slots (current + N history) cyclically.

CFL stability: explicit schemes need dt ≤ C * dx² / α (diffusion) or dt ≤ dx / v (advection / wave). Pick conservatively.

Acceptance != "ran without error". Validate against:

mass / energy conservation (closed BC: sum should be invariant)
analytical (e.g. Gaussian diffusion peak decay, plane wave amplitude)
peak position (advection: should move v*t)

Print results as JSON on the last stdout line. Cast numpy floats: float(u.data[-1].max()).

Required protocol

Gather inputs:

Category A: PDE, domain shape & extent, IC/BCs, time span, stencil order, acceptance.
Category B: dt, OpenMP threads (env var DEVITO_LANGUAGE=openmp and OMP_NUM_THREADS), codegen cache dir.

sim check devito.

Write .py per base/reference/workflow.md.

sim lint script.py.

sim run script.py --solver devito.

Validate JSON.