examples: Update notebooks

Author: EdCaunt

examples/seismic/tutorials/16_ader_fd.ipynb

@@ -5,7 +5,7 @@
    "id": "0",
    "metadata": {},
    "source": [
-    "# 15 - ADER-FD\n",
+    "# 16 - ADER-FD\n",
     "\n",
     "This notebook demonstrates the implementation of a finite-difference scheme for solving the first-order formulation of the acoustic wave equation using ADER (Arbitrary-order-accuracy via DERivatives) time integration. This enables a temporal discretisation up the order of the spatial discretisation, whilst preventing the grid-grid decoupling (often referred to as checkerboarding) associated with solving first-order systems of equations on a single finite-difference grid.\n",
     "\n",

examples/userapi/02_apply.ipynb

@@ -8,9 +8,9 @@
     "\n",
     "This tutorial describes three fundamental user APIs:\n",
     "\n",
-    "* Operator.apply\n",
-    "* Operator.arguments\n",
-    "* Operator.estimate_memory\n",
+    "* `Operator.apply`\n",
+    "* `Operator.arguments`\n",
+    "* `Operator.estimate_memory`\n",
     "\n",
     "We will use a trivial `Operator` that, at each time step, increments by 1 all points in the physical domain."
    ]
@@ -57,7 +57,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Under the hood, some code has been generated (`print(op)` to display the generated code), JIT-compiled, and executed. Since no additional arguments have been passed, `op` has used `u` as input. We can verify that the content of `u.data` is as expected"
+    "Under the hood, some code has been generated, JIT-compiled, and executed. Note that one can print `op.ccode` to display the generated code. Since no additional arguments have been passed, `op` has used `u` as input. We can verify that the content of `u.data` is as expected"
    ]
   },
   {
@@ -162,7 +162,7 @@
    "source": [
     "`'u'` stores a pointer to the allocated data; `'timers'` stores a pointer to a data structure used for C-level performance profiling.\n",
     "\n",
-    "One may want to replace some of these default arguments. For example, we could increase the minimum iteration point along the spatial Dimensions `x` and `y`, and execute only the very first timestep:"
+    "One may want to replace some of these default arguments. For example, we could reduce the maximum iteration point along the spatial Dimensions `x` and `y`, and execute only the very first timestep:"
    ]
   },
   {
@@ -174,14 +174,14 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "Operator `Kernel` run in 0.00 s\n"
+      "Operator `Kernel` ran in 0.01 s\n"
      ]
     }
    ],
    "source": [
     "#NBVAL_IGNORE_OUTPUT\n",
     "u.data[:] = 0.  # Explicit reset to initial value\n",
-    "summary = op.apply(x_m=2, y_m=2, time_M=0)"
+    "summary = op.apply(x_M=1, y_M=1, time_M=0)"
    ]
   },
   {
@@ -204,10 +204,10 @@
        "       [0., 0., 0., 0.],\n",
        "       [0., 0., 0., 0.]],\n",
        "\n",
-       "      [[0., 0., 0., 0.],\n",
-       "       [0., 0., 0., 0.],\n",
-       "       [0., 0., 1., 1.],\n",
-       "       [0., 0., 1., 1.]],\n",
+       "      [[1., 1., 1., 0.],\n",
+       "       [1., 1., 1., 0.],\n",
+       "       [1., 1., 1., 0.],\n",
+       "       [0., 0., 0., 0.]],\n",
        "\n",
        "      [[0., 0., 0., 0.],\n",
        "       [0., 0., 0., 0.],\n",
@@ -228,12 +228,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
+    "Side note: in practice, iterating over a subset of the grid by directly overriding the minimum and maximum values of a dimension is not advised. Instead, a `SubDomain` interface is available for this purpose (detailed in tutorial `03_subdomains`).\n",
+    "\n",
     "Given a generic `Dimension` `d`, the naming convention is such that:\n",
     "\n",
     "* `d_m` is the minimum iteration point\n",
     "* `d_M` is the maximum iteration point\n",
     "\n",
-    "Hence, `op.apply(..., d_m=4, d_M=7, ...)` will run `op` in the compact interval `[4, 7]` along `d`. For historical reasons, `d=...` aliases to `d_M=...`; in many Devito examples it happens to see `op.apply(..., time=10, ...)` -- this is just equivalent to `op.apply(..., time_M=10, ...)`.\n",
+    "Hence, `op.apply(..., d_m=4, d_M=7, ...)` will run `op` in the compact interval `[4, 7]` along `d`. For historical reasons, `d=...` aliases to `d_M=...`; in many Devito examples it happens to see `op.apply(..., time=10, ...)` -- this is just equivalent to `op.apply(..., time_M=10, ...)`. `SpaceDimension`s, such as those attached to a `Grid` do not have a `d_m`, as these dimensions will essentially always be indexed from zero to `d_M` along each axis.\n",
     "\n",
     "If we try to specify an invalid iteration extreme, Devito will raise an exception."
    ]