{
 "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/devitocodes/devito/blob/master/devito/operator/operator.py).\n",
    "\n",
    "![compiler-stages](https://raw.githubusercontent.com/gist/georgebisbas/cab358b6ee2c834c1eb7100dabf832de/raw/bfbe3ba8cc8ce6d58c57eebd39941b5868ffd942/devito-outline-4.7.svg)\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/devitocodes/devito/blob/master/examples/compiler/01_data_regions.ipynb)\n",
    "    * Data dependence analysis\n",
    "* Lowering\n",
    "    * [Indexification](https://github.com/devitocodes/devito/blob/master/examples/compiler/02_indexification.ipynb)\n",
    "    * Substitutions\n",
    "    * Domain alignment\n",
    "    * Eq -> LoweredEq\n",
    "* Clustering\n",
    "* Symbolic optimization via a set of compilation passes operating on symbolic expressions\n",
    "* Tree-fication (from symbolic expressions to Abstract Syntax Tree)\n",
    "    * Clusters -> ScheduleTree\n",
    "    * ScheduleTree -> Iteration/Expression Tree (IET)\n",
    "    * IET examples\n",
    "        * [Part A: top-down inspection](https://github.com/devitocodes/devito/blob/master/examples/compiler/03_iet-A.ipynb)\n",
    "        * [Part B: bottom-up construction](https://github.com/devitocodes/devito/blob/master/examples/compiler/04_iet-B.ipynb)\n",
    "* IET analysis\n",
    "* Loop optimization via a set of compilation passes operating on the IET\n",
    "    * Classic transformations (SIMD, blocking, ...)\n",
    "    * OpenMP shared-memory parallelism\n",
    "    * MPI distributed-memory 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_. ACM Trans. Math. Softw. 46, 1, Article 6 (March 2020), 28 pages. [https://dl.acm.org/doi/10.1145/3374916]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}