update demo notebook

docs/pg-rad-in-python.ipynb

@@ -5,14 +5,22 @@
    "id": "5e30f59a",
    "metadata": {},
    "source": [
-    "# Demo of PG-RAD\n",
+    "# Using PG-RAD as a module\n",
     "\n",
-    "This is a demo."
+    "This discusses the overall design of the code to understand how different parts interact, doing so by an interactive notebook demo. For specific usage of functions and classes, consult the API documentation in the side bar (relevant API documentation sections will also be hyperlinked in the below explanation)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f18912e5",
+   "metadata": {},
+   "source": [
+    "## Imports"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 5,
    "id": "415fdd25",
    "metadata": {},
    "outputs": [],
@@ -22,7 +30,7 @@
     "from pg_rad.dataloader import load_data\n",
     "from pg_rad.path import path_from_RT90\n",
     "from pg_rad.landscape import Landscape\n",
-    "from pg_rad.objects import Source\n",
+    "from pg_rad.sources import PointSource\n",
     "\n",
     "from pg_rad.isotope import Isotope"
    ]
@@ -37,7 +45,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
+   "execution_count": 6,
    "id": "5a0e470a",
    "metadata": {},
    "outputs": [],
@@ -56,7 +64,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 7,
    "id": "2ec97553",
    "metadata": {},
    "outputs": [
@@ -64,7 +72,7 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "2026-01-27 20:48:51,754 - INFO: Piecewise regression reduced path from 105 to 4 segments.\n"
+      "2026-01-28 13:31:03,130 - INFO: Piecewise regression reduced path from 105 to 4 segments.\n"
      ]
     },
     {
@@ -79,8 +87,8 @@
     }
    ],
    "source": [
-    "p1 = path_from_RT90(df, east_col = \"East\", north_col = \"North\", simplify_path = False)\n",
+    "p1 = path_from_RT90(df, east_col = \"East\", north_col = \"North\", path_simplify = False)\n",
-    "p2 = path_from_RT90(df, east_col = \"East\", north_col = \"North\", simplify_path = True)\n",
+    "p2 = path_from_RT90(df, east_col = \"East\", north_col = \"North\", path_simplify = True)\n",
     "\n",
     "p1.plot(color='r', linestyle='-', linewidth = 10, label = \"Full path\")\n",
     "p2.plot(color='b', linestyle='-', marker = 'o', label = \"Reduced path\")\n",
@@ -96,14 +104,20 @@
    "id": "da8620fa",
    "metadata": {},
    "source": [
-    "## Making a landscape\n",
+    "## Landscape\n",
     "\n",
-    "You can make a landscape with or without a path. Let's make an empty landscape."
+    "The [Landscape](/API/landscape/landscape) is the starting point for the model. It is essentially an empty data structure which represents a cuboid space\n",
+    "\n",
+    "$$\n",
+    "C = [0, x_{\\max}] \\times [0, y_{\\max}] \\times [0, z_{\\max}] \\subset \\mathbb{R}^3\n",
+    "$$\n",
+    "\n",
+    "where $x_{\\max}, y_{\\max}, z_{\\max}$ are defined by the user upon creating the landscape object."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": 8,
    "id": "24f1159d",
    "metadata": {},
    "outputs": [
@@ -119,47 +133,57 @@
     }
    ],
    "source": [
-    "landscape = Landscape()\n",
+    "my_landscape = Landscape(size = (500, 500, 500), scale = 'meters')\n",
-    "fig, ax = landscape.plot()\n",
+    "fig, ax = my_landscape.plot()\n",
     "plt.show()"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "a285a2b6",
+   "metadata": {},
+   "source": [
+    "Not much to see here, but we created the backbone of our simulation now."
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "035b4f42",
    "metadata": {},
    "source": [
-    "## Adding a source"
+    "## Point sources\n",
+    "\n",
+    "A [PointSource](/API/sources/point_source) can be added to `my_landscape` in the following way:"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": 9,
    "id": "91019da5",
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "[Source(name=Source 1, pos=(100, 100, 0), isotope=Cs137, A=100 MBq)]"
+       "[PointSource(name=Source 1, pos=(100, 100, 0), isotope=Cs137, A=100 MBq)]"
       ]
      },
-     "execution_count": 5,
+     "execution_count": 9,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
     "cs137 = Isotope(name = \"Cs137\", E = 662.66, b = 0.851)\n",
-    "my_source = Source(x = 100, y = 100, z = 0, activity = 100, isotope = cs137)\n",
+    "my_source = PointSource(x = 100, y = 100, z = 0, activity = 100, isotope = cs137)\n",
-    "landscape.add_sources(my_source)\n",
+    "my_landscape.add_sources(my_source)\n",
     "\n",
-    "landscape.sources"
+    "my_landscape.sources"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": 10,
    "id": "7913fe1e",
    "metadata": {},
    "outputs": [
@@ -170,7 +194,7 @@
        " <Axes: xlabel='X [meters]', ylabel='Y [meters]'>)"
       ]
      },
-     "execution_count": 6,
+     "execution_count": 10,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -186,12 +210,12 @@
     }
    ],
    "source": [
-    "landscape.plot()"
+    "my_landscape.plot()"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": 11,
    "id": "df4715c1",
    "metadata": {},
    "outputs": [
@@ -202,7 +226,7 @@
        " <Axes: xlabel='X [meters]', ylabel='Y [meters]'>)"
       ]
      },
-     "execution_count": 7,
+     "execution_count": 11,
      "metadata": {},
      "output_type": "execute_result"
     },
@@ -218,8 +242,8 @@
     }
    ],
    "source": [
-    "landscape.set_path(p2)\n",
+    "my_landscape.set_path(p2)\n",
-    "landscape.plot()"
+    "my_landscape.plot()"
    ]
   },
   {