CLI Usage

The CLI entry point is recipes/run.py. Run it directly with Python:

python recipes/run.py -physics <key> [options]

Minimal example

# 2-D forward pass, isotropic acoustic, 101×101 grid
python recipes/run.py \
    -physics iso-acoustic \
    -d 101 101 \
    -s 10.0 10.0 \
    -nt 500

Option reference

Physics and model geometry

Flag Default Description
-physics / -phys iso-acoustic Physics key (see Supported Physics)
-d / --shape — Grid shape, e.g. -d 101 101 (2-D) or -d 101 101 51 (3-D)
-s / --spacing — Grid spacing in meters, e.g. -s 10.0 10.0
-nt 100 Number of time steps
-so / --space-order 4 Spatial FD order
-to / --time-order 2 Time discretization order (1 or 2)
-nlayers / --nl 4 Number of velocity layers in the layered model
--nbl 40 Number of absorbing boundary layers

Source and receiver

Flag Default Description
-f0 0.010 Ricker source dominant frequency (Hz)
-io / --interp-order 2 Interpolation order for source and receivers

Wavefields and saving

Flag Default Description
--time-slots / --ts 2 Rolling wavefield buffer depth
--t-sub / --time-sub 4 Subsampling factor when writing wavefield snapshots
--notransient off Disable transient TimeFunction memory optimisation
-save-mode all Elastic adjoint save mode: all saves velocity and stress; v saves velocity only and recomputes stress on the fly

Data types

Flag Default Description
-Pdtype float32 Physical parameter precision (float16, float32, float64)
-Wdtype float32 Wavefield precision (float16, float32, float64)

Boundary conditions

Flag Default Description
--fs off Conventional free surface
-wl / --waterlayer off Isotropic acoustic water layer subdomain
--qp / --visco off SLS viscoacoustic attenuation

Optimisation and performance

Flag Default Description
-a / --autotune off Operator auto-tuning: off, basic, or aggressive
--opt-op all Apply the custom opt string only to the named operator
--abox off Adaptive bounding-box subdomain (source-driven active region)
--compression — Wavefield compression (cvxcompress, bitcomp)
--fd-kernel-only off Run only the FD kernel — no source, no receivers, Gaussian IC

Computing gradients

Pass -g / --gradients followed by one or more parameter names. The CLI runs the forward pass (with saving) and then the adjoint pass, and reports the gradient norms.

python recipes/run.py \
    -physics iso-acoustic \
    -d 101 101 -s 10.0 10.0 -nt 500 \
    -g vp

For TTI physics, multiple parameters can be requested:

python recipes/run.py \
    -physics tti-zhang \
    -d 101 101 -s 10.0 10.0 -nt 500 \
    -g vp epsilon delta

Targeting optimisation to one operator

Use --opt-op together with -opt to apply a custom optimisation tuple only to one operator while leaving the others at their default level:

python recipes/run.py \
    -physics iso-acoustic \
    -d 101 101 -s 10.0 10.0 -nt 500 \
    -g vp \
    --opt-op ForwardAcousticIsotropic \
    -opt advanced
Back to top