diff --git a/chapter4-README.md b/chapter4-README.md new file mode 100644 index 0000000000..931d555802 --- /dev/null +++ b/chapter4-README.md @@ -0,0 +1,158 @@ +# Devito: Fast Stencil Computation from Symbolic Specification +# Instructions for automated temporal blocking code-generation +# Temporal blocking scheme used is Wavefront temporal blocking + +## Reproducing benchmarks for Chapter 4 of the thesis + +After installing (see [Installation](#installation)) Devito, set environment variables: +```python +export DEVITO_AUTOTUNING=aggressive +export DEVITO_LANGUAGE=openmp +export DEVITO_LOGGING=DEBUG +export OMP_PROC_BIND=close +export OMP_PLACES=threads +``` + +### For the Laplace benchmark +```python +python examples/bench_laplace_thesis.py -d 512 512 512 --tn 512 -so 4 +python examples/bench_laplace_thesis.py -d 512 512 512 --tn 512 -so 8 +python examples/bench_laplace_thesis.py -d 512 512 512 --tn 512 -so 12 +``` + +### For the acoustic benchmark +```python +python examples/seismic/acoustic/bench_acoustic_thesis.py -d 512 512 512 --tn 512 -so 4 +python examples/seismic/acoustic/bench_acoustic_thesis.py -d 512 512 512 --tn 512 -so 8 +python examples/seismic/acoustic/bench_acoustic_thesis.py -d 512 512 512 --tn 512 -so 12 +``` + +### For the TTI benchmark +```python +python examples/seismic/tti/bench_tti_thesis.py -d 512 512 512 --tn 512 --a aggressive -so 4 +python examples/seismic/tti/bench_tti_thesis.py -d 512 512 512 --tn 512 --a aggressive -so 8 +python examples/seismic/tti/bench_tti_thesis.py -d 512 512 512 --tn 512 --a aggressive -so 12 +``` + + +[Devito](http://www.devitoproject.org) 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](http://www.sympy.org/en/index.html) 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](#about-devito) +- [Installation](#installation) +- [Resources](#resources) +- [Performance](#performance) +- [Get in touch](#get-in-touch) +- [Interactive jupyter notebooks](#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 + +```python +>>> 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 + +```python +>>> op(t=timesteps) +``` + +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: +``` +# 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](https://jupyter.org/) notebook session where you can go +through the [tutorials](https://github.com/devitocodes/devito/tree/master/examples) +provided with Devito or create your own notebooks. + +[See here](http://devitocodes.github.io/devito/download.html) for detailed installation +instructions and other options. If you encounter a problem during installation, please +see the +[installation issues](https://github.com/devitocodes/devito/wiki/Installation-Issues) we +have seen in the past. + +## Resources + +To learn how to use Devito, +[here](https://github.com/devitocodes/devito/blob/master/examples) is a good +place to start, with lots of examples and tutorials. + +The [website](https://www.devitoproject.org/) also provides access to other +information, including documentation and instructions for citing us. + +Some FAQs are discussed [here](https://github.com/devitocodes/devito/wiki/FAQ). + +## 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](https://github.com/devitocodes/devito/blob/master/benchmarks/user). + +You may also be interested in +[TheMatrix](https://www.devitocodes.com/blog/thematrix) -- a cross-architecture +benchmarking framework showing the performance of several production-grade +seismic operators implemented with Devito. + +## 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](https://join.slack.com/t/devitocodes/shared_invite/zt-gtd2yxj9-Y31YKk_7lr9AwfXeL2iMFg). + +## Interactive jupyter notebooks +The tutorial jupyter notebook are available interactively at the public [binder](https://mybinder.org/v2/gh/devitocodes/devito/master) jupyterhub.