#!/usr/bin/env python
# coding: utf-8

# # The Devito compiler
# 
# In Devito, an `Operator` carries out three fundamental tasks: generation of low-level code, JIT compilation, and execution. Overall, the lowering process performed by an `Operator` – from high-level equations to dynamically compiled and executable code – consists of multiple compiler passes, summarized in the Figure bellow. The following series of notebooks will describe these compilation passes in a hands-on fashion. We will explore the heart of the `Operator` class, which orchestrates code generation and compilation. For more details, see the [Operator class](https://github.com/opesci/devito/blob/master/devito/operator.py).
# 
# ![compiler-stages](https://user-images.githubusercontent.com/478143/57969349-6a6ad980-7976-11e9-89ae-8866e383e2e9.png)
# 
# The reader of this series of tutorials is expected to be familiar with the basic Devito API (i.e., `Grid`, `Function`/`TimeFunction`, `Operator`, ...). Otherwise, the CFD tutorials in `examples/cfd` are a better place to start.
# 
# Many of the examples and exercises shown here are extracted from test cases found in the folder `devito/tests`, or from the documentation itself.
# 
# ## Outline
# 
# * Preliminaries
#     * [Data regions](https://github.com/opesci/devito/blob/master/examples/compiler/01_data_regions.ipynb)
#     * Data dependence analysis
# * Lowering
#     * [Indexification](https://github.com/opesci/devito/blob/master/examples/compiler/02_indexification.ipynb)
#     * Substitutions
#     * Domain alignment
#     * Eq -> LoweredEq
# * Clustering
# * Symbolic optimization via the Devito Symbolic Engine (DSE)
# * Tree-fication
#     * Clusters -> ScheduleTree
#     * ScheduleTree -> Iteration/Expression Tree (IET)
#     * IET examples
#         * [Part A: top-down inspection](https://github.com/opesci/devito/blob/master/examples/compiler/03_iet-A.ipynb)
#         * [Part B: bottom-up construction](https://github.com/opesci/devito/blob/master/examples/compiler/04_iet-B.ipynb)
# * IET analysis
# * Loop optimization via the Devito Loop Engine (DLE)
#     * Classic transformations (SIMD, blocking, ...)
#     * OpenMP parallelism
#     * MPI parallelism
# * Finalization
# 
# ### References
# 
# F. Luporini, M. Lange, M. Loubotin, N. Kukreja, J. Huckelheim, C. Yount, P. Witte, P. Kelly, G. Gorman, F. Herrmann. _Architecture and Performance of Devito, A System for Automated Stencil Computation_. Submitted to SIAM Journal on Scientific Computing, 2018. [arXiv:1807.03032]