parts/diffusion_2d/diffusion_2d.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Introducing the example: Diffusion 2D"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "* **The brief physics intro**\n",
    "  * 2D explicit diffusion using the finite-difference method\n",
    "\n",
    "* **The code structure overview**\n",
    "  * Compute and \"main\" functions\n",
    "  * [`shared.jl`](./../shared.jl) (included) script\n",
    "\n",
    "* **The output**\n",
    "  * Visualisation\n",
    "  * `Time` and `T_eff` - Performance reporting in the REPL\n",
    "\n",
    "* **The serial loop version**\n",
    "  * Macros, \"race\" conditions\n",
    "  * Moving to a single compute function"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The brief physics intro"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "During this workshop, we will use a 2D diffusion solver to investigate how Julia allows us to tackle various HPC concepts in a concise fashion, without trading performance.\n",
    "\n",
    "We will solve the 2D diffusion equation for a quantity $C$,\n",
    "$$\n",
    "\\frac{∂C}{∂t} = -∇ ⋅ q~,\n",
    "$$\n",
    "where $q$ represents the diffusive flux:\n",
    "$$\n",
    "q = -D \\; ∇C~,\n",
    "$$\n",
    "and where $D$ stands for the diffusion coefficient.\n",
    "\n",
    "\n",
    "We will solve this partial differential equation (PDE) using the finite-difference method and an explicit forward Euler time integrator on a regular staggered Cartesian grid.\n",
    "\n",
    "<img src=\"imgs/stagg_2D.png\" width=400px>\n",
    "\n",
    "The 2D domain is of size $L=10$ and the scalar linear diffusion coefficient $D=1$. We use a constant grid size `ds = L / ns`, where `ns` represent the number of finite-difference cells in both $x$ and $y$ dimension.\n",
    "\n",
    "As initial condition, we define a Gaussian perturbation centred in the middle of the domain of amplitude and standard deviation equal to 1.\n",
    "\n",
    "<img src=\"imgs/initial.png\" width=400px>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The code structure overview"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's have a look at the code structure. We'll first look at the [`diffusion_2d.jl`](diffusion_2d.jl) script. It contains:\n",
    "- 2 compute functions implementing the spatial and temporal discretisation of the PDE;\n",
    "\n",
    "- a \"main\" function to run the code;\n",
    "\n",
    "- an include statement for [`shared.jl`](./../shared.jl), mostly containing parameters and arrays initialisation, and visualisation."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The output"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Graphics\n",
    "\n",
    "The visualisation renders the evolution of the distribution of the diffusing quantity $C$ throughout the simulation at frequency intervals defined by `nout = nt / 5`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Timing and performance\n",
    "\n",
    "Besides plotting, the code also reports performance using wall-time and effective memory throughput as metric and prints in the REPL."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### Wall time\n",
    "\n",
    "The first performance metric is wall time, or total runtime. It is computed using a simple custom tic-toc approach, making sure to skip the first 10 iterations to account for \"warm-up\". For any performance assessment, we should make sure to run the code for at least 1 second in order to ensure reliable results.\n",
    "\n",
    "#### Effective memory throughput\n",
    "\n",
    "The second metric is the effective memory throughput $T_\\mathrm{eff}$ (`T_eff` in the REPL). It defines as the **non-redundant** memory access per iteration divided by the time per iteration $t_\\mathrm{it}$ (in sec.):\n",
    "$$\n",
    "T_\\mathrm{eff} = \\frac{A_\\mathrm{eff}}{t_\\mathrm{it}}~,\n",
    "$$\n",
    "where $A_\\mathrm{eff} = n_\\mathrm{IO} ~ n_s^2 ~ s_\\mathrm{DAT} ~ 10^{-9}$ is the effective memory access (in GB).\n",
    "\n",
    "In our example, $n_\\mathrm{IO} = 2$ as we only need to read old values of $C$ and write them back to solve the diffusion PDE. $s_\\mathrm{DAT} = 8$ as we are running double precision floating point arithmetic.\n",
    "\n",
    "$T_\\mathrm{eff}$ provides an idea on how far from the performance of memory copy only memory-bounded codes are, under various assumptions. Refer to [Räss et al. (2022)](https://doi.org/10.5194/gmd-15-5757-2022) for details.\n",
    "\n",
    "We will further use this metric in the GPU computing part."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The serial loop version\n",
    "\n",
    "The final step to look at, before we start our deep dive, is the serial loop version of the 2D diffusion code. If we now open the [`diffusion_2d_loop.jl`](diffusion_2d_loop.jl) script aside the vectorized one ([`diffusion_2d.jl`](diffusion_2d.jl)), we can diff them \"by eye\" to see the major change being the change in the `diffusion_step!` function.\n",
    "\n",
    "In a nutshell:\n",
    "- we do no longer explicitly assign flux computation results to temporary variable in global memory (previously `qx` and `qy`);\n",
    "\n",
    "- we introduce a nested loop of spacial dimensions respecting a **column major order**;\n",
    "\n",
    "- we introduce a temporary second array `C2` to not read and write from the same array in order to avoid race conditions;\n",
    "\n",
    "- we use `@inbounds` upon having verified the correctness of the results to skip bound-checking."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**→ Hands-on** (see [README.md](README.md))"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Julia 1.10.4",
   "language": "julia",
   "name": "julia-1.10"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}