{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The Devito compiler\n",
    "\n",
    "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).\n",
    "\n",
    "![compiler-stages](https://user-images.githubusercontent.com/478143/57969349-6a6ad980-7976-11e9-89ae-8866e383e2e9.png)\n",
    "\n",
    "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.\n",
    "\n",
    "Many of the examples and exercises shown here are extracted from test cases found in the folder `devito/tests`, or from the documentation itself.\n",
    "\n",
    "## Outline\n",
    "\n",
    "* Preliminaries\n",
    "    * [Data regions](https://github.com/opesci/devito/blob/master/examples/compiler/01_data_regions.ipynb)\n",
    "    * Data dependence analysis\n",
    "* Lowering\n",
    "    * [Indexification](https://github.com/opesci/devito/blob/master/examples/compiler/02_indexification.ipynb)\n",
    "    * Substitutions\n",
    "    * Domain alignment\n",
    "    * Eq -> LoweredEq\n",
    "* Clustering\n",
    "* Symbolic optimization via the Devito Symbolic Engine (DSE)\n",
    "* Tree-fication\n",
    "    * Clusters -> ScheduleTree\n",
    "    * ScheduleTree -> Iteration/Expression Tree (IET)\n",
    "    * IET examples\n",
    "        * [Part A: top-down inspection](https://github.com/opesci/devito/blob/master/examples/compiler/03_iet-A.ipynb)\n",
    "        * [Part B: bottom-up construction](https://github.com/opesci/devito/blob/master/examples/compiler/04_iet-B.ipynb)\n",
    "* IET analysis\n",
    "* Loop optimization via the Devito Loop Engine (DLE)\n",
    "    * Classic transformations (SIMD, blocking, ...)\n",
    "    * OpenMP parallelism\n",
    "    * MPI parallelism\n",
    "* Finalization\n",
    "\n",
    "### References\n",
    "\n",
    "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]"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}