Devito: Fast Stencil Computation from Symbolic Specification

Devito is a Python package to implement
optimized stencil computation (e.g., finite differences, image processing,
machine learning) from high-level symbolic problem definitions. Devito builds
on SymPy and employs automated code
generation and just-in-time compilation to execute optimized computational
kernels on several computer platforms, including CPUs, GPUs, and clusters
thereof.

• About Devito
• Installation
• Resources
• FAQs
• Performance
• Get in touch
• Interactive jupyter notebooks

About Devito

Devito provides a functional language to implement sophisticated operators that
can be made up of multiple stencil computations, boundary conditions, sparse
operations (e.g., interpolation), and much more. A typical use case is
explicit finite difference methods for approximating partial differential
equations. For example, a 2D diffusion operator may be implemented with Devito
as follows

pythonCopy
>>> grid = Grid(shape=(10, 10))
>>> f = TimeFunction(name='f', grid=grid, space_order=2)
>>> eqn = Eq(f.dt, 0.5 * f.laplace)
>>> op = Operator(Eq(f.forward, solve(eqn, f.forward)))

An Operator generates low-level code from an ordered collection of Eq (the
example above being for a single equation). This code may also be compiled and
executed

pythonCopy
>>> op(t=timesteps, dt=dt)

There is virtually no limit to the complexity of an Operator -- the Devito
compiler will automatically analyze the input, detect and apply optimizations
(including single- and multi-node parallelism), and eventually generate code
with suitable loops and expressions.

Key features include:

• A functional language to express finite difference operators.
• Straightforward mechanisms to adjust the discretization.
• Constructs to express sparse operators (e.g., interpolation), classic linear
  operators (e.g., convolutions), and tensor contractions.
• Seamless support for boundary conditions and adjoint operators.
• A flexible API to define custom stencils, sub-domains, sub-sampling,
  and staggered grids.
• Generation of highly optimized parallel code (SIMD vectorization, CPU and
  GPU parallelism via OpenMP and OpenACC, multi-node parallelism via MPI,
  blocking, aggressive symbolic transformations for FLOP reduction, etc.).
• Distributed NumPy arrays over multi-node (MPI) domain decompositions.
• Inspection and customization of the generated code.
• Autotuning framework to ease performance tuning.
• Smooth integration with popular Python packages such as NumPy, SymPy, Dask,
  and SciPy, as well as machine learning frameworks such as TensorFlow and
  PyTorch.

Installation

The easiest way to try Devito is through Docker using the following commands:

bashCopy
# get the code
git clone https://github.com/devitocodes/devito.git
cd devito

# start a jupyter notebook server on port 8888
docker-compose up devito

After running the last command above, the terminal will display a URL such as
https://127.0.0.1:8888/?token=XXX. Copy-paste this URL into a browser window
to start a Jupyter notebook session where you can go
through the tutorials
provided with Devito or create your own notebooks.

See here for detailed installation
instructions and other options. If you encounter a problem during installation, please
see the
installation issues we
have seen in the past.

Resources

To learn how to use Devito,
here is a good
place to start, with lots of examples and tutorials.

The website also provides access to other
information, including documentation and instructions for citing us.

Some FAQs are discussed here.

Performance

If you are interested in any of the following

• Generation of parallel code (CPU, GPU, multi-node via MPI);
• Performance tuning;
• Benchmarking operators;

then you should take a look at this
README.

Get in touch

If you're using Devito, we would like to hear from you. Whether you
are facing issues or just trying it out, join the
conversation.

Interactive jupyter notebooks

The tutorial jupyter notebook are available interactively at the public binder jupyterhub.