examples: Add note on legacy SubDomain API to tutorial notebook

Author: EdCaunt

examples/userapi/03_subdomains.ipynb

@@ -13,6 +13,8 @@
    "source": [
     "This tutorial is designed to introduce users to the concept of subdomains in Devito and how to utilize them within simulations for a variety of purposes.\n",
     "\n",
+    "It is worth noting that Devito has two `SubDomain` APIs, the current and legacy APIs. Backward compatibility is retained for the latter API (outlined in the appendix at the end of this notebook). However, use of the current API outlined in this notebook is encouraged.\n",
+    "\n",
     "We will begin by exploring the subdomains created internally (and by default) when creating a `Grid` and then explore in detail how users can define and utilize their own subdomains.\n",
     "\n",
     "Consider the construction of the following `Grid`:"
@@ -912,6 +914,65 @@
     "assert np.isclose(norm(v[0]), 0.10301, rtol=1e-4)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Legacy API\n",
+    "\n",
+    "The legacy `SubDomain` API required `SubDomain`s to be created prior to the `Grid`, and passed to the `Grid` on instantiation. This interface can still be used to avoid breaking backward compatibility with existing codes. We can use the `Middle`, `Left`, and `Right` classes from earlier to illustrate this API."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 33,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "Operator `Kernel` ran in 0.01 s\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "Data([[2., 2., 2., 2., 2., 2., 2., 2., 5., 5.],\n",
+       "      [2., 2., 2., 2., 2., 2., 2., 2., 5., 5.],\n",
+       "      [0., 0., 0., 0., 0., 0., 0., 0., 3., 3.],\n",
+       "      [0., 0., 0., 0., 1., 1., 1., 0., 3., 3.],\n",
+       "      [0., 0., 0., 0., 1., 1., 1., 0., 3., 3.],\n",
+       "      [0., 0., 0., 0., 1., 1., 1., 0., 3., 3.],\n",
+       "      [0., 0., 0., 0., 0., 0., 0., 0., 3., 3.],\n",
+       "      [0., 0., 0., 0., 0., 0., 0., 0., 3., 3.],\n",
+       "      [0., 0., 0., 0., 0., 0., 0., 0., 3., 3.],\n",
+       "      [0., 0., 0., 0., 0., 0., 0., 0., 3., 3.]], dtype=float32)"
+      ]
+     },
+     "execution_count": 33,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "left = Left()\n",
+    "right = Right()\n",
+    "mid = Middle()\n",
+    "\n",
+    "new_grid = Grid(shape=(10, 10), subdomains=(left, right, mid))\n",
+    "\n",
+    "g = Function(name='g', grid=new_grid)\n",
+    "\n",
+    "eq1 = Eq(g, g+1, subdomain=new_grid.subdomains['middle'])\n",
+    "eq2 = Eq(g, g+2, subdomain=new_grid.subdomains['left'])\n",
+    "eq3 = Eq(g, g+3, subdomain=new_grid.subdomains['right'])\n",
+    "\n",
+    "Operator([eq1, eq2, eq3])()\n",
+    "\n",
+    "g.data"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},