Swarm rework / dev merged

docs/user/NextSteps.qmd

@@ -17,11 +17,10 @@ In addition to the notebooks in this brief set of examples, there are a number o
   - [The Underworld Website / Blog](https://www.underworldcode.org)
 
   - [The API documentation](https://underworldcode.github.io/underworld3/main_api/underworld3/index.html)
-  (all the modules and functions and their full sets of arguments) is automatically generated from the source code and uses the same rich markdown content as the notebook help text. 
+  (all the modules and functions and their full sets of arguments) is automatically generated from the source code and uses the same rich markdown
+  content as the notebook help text. 
   There is also a set of [API docs](https://underworldcode.github.io/underworld3/development_api/underworld3/index.html) for the development branch.
 
-  - The [`underworld3` GitHub repository](https://github.com/underworldcode/underworld3) is the most active development community for the code.
-
 
 ### Benchmarks
 

docs/user/Notebooks/1-Meshes.ipynb

@@ -14,15 +14,13 @@
    },
    "source": [
     "<div style=\"float: right; width: 40%\">\n",
-    "<img src=\"media/SampleSphericalMesh.png\" width=100%>\n",
-    "<caption>\n",
-    "<i>\n",
-    "</i>\n",
-    "</caption>\n",
+    "    \n",
+    "![](media/SampleSphericalMesh.png)\n",
+    "\n",
     "</div>\n",
     "\n",
     "\n",
-    "# Notebook 1: Meshes\n",
+    "## Notebook 1: Meshes\n",
     "\n",
     "Introducing meshes: how to build them, interrogate them and visualise them.\n",
     "\n",
@@ -36,7 +34,6 @@
     "\n",
     "Mesh adaptivity is a work-in-progress.\n",
     "\n",
-    "\n",
     "\n"
    ]
   },
@@ -64,7 +61,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 9,
+   "execution_count": 2,
    "id": "5a4437ff-63ae-4ffa-9f2b-8ec1b8b4baeb",
    "metadata": {
     "editable": true,
@@ -109,15 +106,26 @@
     },
     "tags": []
    },
-   "outputs": [],
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Constructing UW mesh from gmsh .meshes/uw_cubed_spherical_shell_ro1.0_ri0.547_elts8_plexTrue.msh\n",
+      "Mesh refinement levels: 0\n",
+      "Mesh coarsening levels: None\n",
+      "Populating mesh coordinates CoordinateSystemType.SPHERICAL\n"
+     ]
+    }
+   ],
    "source": [
     "mesh = uw.meshing.uw.meshing.CubedSphere(\n",
     "    radiusOuter=1.0,\n",
     "    radiusInner=0.547,\n",
     "    numElements=8,\n",
     "    refinement=0,\n",
-    "    simplex=False,\n",
-    "    verbose=False,\n",
+    "    simplex=True,\n",
+    "    verbose=True,\n",
     ")"
    ]
   },
@@ -152,9 +160,9 @@
        "       [-0.57735027,  0.57735027, -0.57735027],\n",
        "       [-0.57735027, -0.57735027, -0.57735027],\n",
        "       ...,\n",
-       "       [ 0.58691901, -0.41511058, -0.41511058],\n",
-       "       [ 0.6269543 , -0.44342636, -0.44342636],\n",
-       "       [ 0.66698958, -0.47174214, -0.47174214]])"
+       "       [ 0.61340251,  0.4866531 ,  0.41538064],\n",
+       "       [ 0.56556024,  0.42209717,  0.44274422],\n",
+       "       [ 0.51755571,  0.41031492,  0.44421012]])"
       ]
      },
      "execution_count": 4,
@@ -166,6 +174,14 @@
     "mesh.data"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a7c5dd7e-58d2-45d0-bfc6-eaded6da20f0",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  },
   {
    "cell_type": "markdown",
    "id": "1ed56724-adc5-49c6-a33b-4552b619cb07",
@@ -266,7 +282,7 @@
        "        "
       ],
       "text/plain": [
-       "<IPython.lib.display.IFrame at 0x155c7fc90>"
+       "<IPython.lib.display.IFrame at 0x338a8d820>"
       ]
      },
      "execution_count": 6,
@@ -320,10 +336,10 @@
     {
      "data": {
       "text/latex": [
-       "$\\displaystyle \\left[\\begin{matrix}{ r \\hspace{ 0.0pt } } & { \\theta \\hspace{ 0.01pt } } & { \\phi \\hspace{ 0.02pt } }\\end{matrix}\\right]$"
+       "$\\displaystyle \\left[\\begin{matrix}r & \\theta & \\phi\\end{matrix}\\right]$"
       ],
       "text/plain": [
-       "Matrix([[{ r \\hspace{ 0.0pt } }, { \\theta \\hspace{ 0.01pt } }, { \\phi \\hspace{ 0.02pt } }]])"
+       "Matrix([[r, \\theta, \\phi]])"
       ]
      },
      "metadata": {},
@@ -381,34 +397,45 @@
      "text": [
       "\n",
       "\n",
-      "Mesh # 0: .meshes/uw_cubed_spherical_shell_ro1.0_ri0.547_elts8_plexFalse.msh\n",
+      "Mesh # 0: .meshes/uw_cubed_spherical_shell_ro1.0_ri0.547_elts8_plexTrue.msh\n",
+      "\n"
+     ]
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "2fe9b56bf1674abc9ec058d5c23de562",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Widget(value='<iframe src=\"http://localhost:53921/index.html?ui=P_0x33e147c50_1&reconnect=auto\" class=\"pyvista…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Number of cells: 7615\n",
       "\n",
       "No variables are defined on the mesh\n",
       "\n",
-      "| Boundary Name            | ID    | Min Size | Max Size |\n",
-      "| ------------------------------------------------------ |\n",
-      "| Lower                    | 1     | 678      | 678      |\n",
-      "| Upper                    | 2     | 678      | 678      |\n",
-      "| All_Boundaries           | 1001  | 768      | 768      |\n",
-      "| UW_Boundaries            | --    | 1356     | 1356     |\n",
-      "| ------------------------------------------------------ |\n",
+      "| Boundary Name            | ID    |\n",
+      "| -------------------------------- |\n",
+      "| Lower                    | 1     |\n",
+      "| Upper                    | 2     |\n",
+      "| Null_Boundary            | 666   |\n",
+      "| All_Boundaries           | 1001  |\n",
+      "| All_Boundaries           | 1001  |\n",
+      "| UW_Boundaries            | --    |\n",
+      "| -------------------------------- |\n",
       "\n",
       "\n",
-      "DM Object: uw_.meshes/uw_cubed_spherical_shell_ro1.0_ri0.547_elts8_plexFalse.msh 1 MPI process\n",
-      "  type: plex\n",
-      "uw_.meshes/uw_cubed_spherical_shell_ro1.0_ri0.547_elts8_plexFalse.msh in 3 dimensions:\n",
-      "  Number of 0-cells per rank: 3474\n",
-      "  Number of 1-cells per rank: 10000\n",
-      "  Number of 2-cells per rank: 9600\n",
-      "  Number of 3-cells per rank: 3072\n",
-      "Labels:\n",
-      "  depth: 4 strata with value/size (0 (3474), 1 (10000), 2 (9600), 3 (3072))\n",
-      "  All_Boundaries: 1 strata with value/size (1001 (768))\n",
-      "  Elements: 1 strata with value/size (99999 (5130))\n",
-      "  Lower: 1 strata with value/size (1 (678))\n",
-      "  Upper: 1 strata with value/size (2 (678))\n",
-      "  celltype: 4 strata with value/size (0 (3474), 1 (10000), 4 (9600), 7 (3072))\n",
-      "  UW_Boundaries: 2 strata with value/size (1 (678), 2 (678))\n"
+      "Use view(1) to view detailed mesh information.\n",
+      "\n"
      ]
     }
    ],
@@ -454,9 +481,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "Python (Pixi)",
    "language": "python",
-   "name": "python3"
+   "name": "pixi-kernel-python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -468,7 +495,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.10"
+   "version": "3.12.11"
   }
  },
  "nbformat": 4,

docs/user/Notebooks/4-Solvers.ipynb

@@ -48,7 +48,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 12,
+   "execution_count": 2,
    "id": "042970c2-ab87-4483-b68c-3fe6b8e633a2",
    "metadata": {
     "editable": true,
@@ -85,36 +85,46 @@
       "\n",
       "\n",
       "Mesh # 0: .meshes/uw_simplexbox_minC(0.0, 0.0)_maxC(1.0, 1.0)_csize0.08333333333333333_regFalse.msh\n",
+      "\n"
+     ]
+    },
+    {
+     "data": {
+      "application/vnd.jupyter.widget-view+json": {
+       "model_id": "6880c7554aa44bf686d534271771e287",
+       "version_major": 2,
+       "version_minor": 0
+      },
+      "text/plain": [
+       "Widget(value='<iframe src=\"http://localhost:54175/index.html?ui=P_0x34f4d36b0_0&reconnect=auto\" class=\"pyvista…"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Number of cells: 346\n",
       "\n",
       "No variables are defined on the mesh\n",
       "\n",
-      "| Boundary Name            | ID    | Min Size | Max Size |\n",
-      "| ------------------------------------------------------ |\n",
-      "| Bottom                   | 11    | 23       | 23       |\n",
-      "| Top                      | 12    | 23       | 23       |\n",
-      "| Right                    | 13    | 23       | 23       |\n",
-      "| Left                     | 14    | 23       | 23       |\n",
-      "| All_Boundaries           | 1001  | 48       | 48       |\n",
-      "| UW_Boundaries            | --    | 92       | 92       |\n",
-      "| ------------------------------------------------------ |\n",
+      "| Boundary Name            | ID    |\n",
+      "| -------------------------------- |\n",
+      "| Bottom                   | 11    |\n",
+      "| Top                      | 12    |\n",
+      "| Right                    | 13    |\n",
+      "| Left                     | 14    |\n",
+      "| Null_Boundary            | 666   |\n",
+      "| All_Boundaries           | 1001  |\n",
+      "| All_Boundaries           | 1001  |\n",
+      "| UW_Boundaries            | --    |\n",
+      "| -------------------------------- |\n",
       "\n",
       "\n",
-      "DM Object: uw_.meshes/uw_simplexbox_minC(0.0, 0.0)_maxC(1.0, 1.0)_csize0.08333333333333333_regFalse.msh 1 MPI process\n",
-      "  type: plex\n",
-      "uw_.meshes/uw_simplexbox_minC(0.0, 0.0)_maxC(1.0, 1.0)_csize0.08333333333333333_regFalse.msh in 2 dimensions:\n",
-      "  Number of 0-cells per rank: 198\n",
-      "  Number of 1-cells per rank: 543\n",
-      "  Number of 2-cells per rank: 346\n",
-      "Labels:\n",
-      "  depth: 3 strata with value/size (0 (198), 1 (543), 2 (346))\n",
-      "  All_Boundaries: 1 strata with value/size (1001 (48))\n",
-      "  Bottom: 1 strata with value/size (11 (23))\n",
-      "  Elements: 1 strata with value/size (99999 (496))\n",
-      "  Left: 1 strata with value/size (14 (23))\n",
-      "  Right: 1 strata with value/size (13 (23))\n",
-      "  Top: 1 strata with value/size (12 (23))\n",
-      "  celltype: 3 strata with value/size (0 (198), 1 (543), 3 (346))\n",
-      "  UW_Boundaries: 4 strata with value/size (11 (23), 12 (23), 13 (23), 14 (23))\n"
+      "Use view(1) to view detailed mesh information.\n",
+      "\n"
      ]
     }
    ],
@@ -186,7 +196,7 @@
        "$$\n",
        "\\nabla \\cdot\n",
        "        \\color{Blue}{\\underbrace{\\Bigl[ \\boldsymbol\\kappa \\nabla u \\Bigr]}_{\\mathbf{F}}} =\n",
-       "        \\color{Maroon}{\\underbrace{\\Bigl[ f \\Bigl] }_{\\mathbf{f}}}\n",
+       "        \\color{Maroon}{\\underbrace{\\Bigl[ f \\Bigl] }_{\\mathbf{h}}}\n",
        "$$\n",
        "\n",
        "The term $\\mathbf{F}$ relates the flux to gradients in the unknown $u$\n",
@@ -234,9 +244,9 @@
        "The projection implemented by creating a solver for this problem\n",
        "\n",
        "$$\n",
-       "\\nabla \\cdot\n",
+       "-\\nabla \\cdot\n",
        "        \\color{Blue}{\\underbrace{\\Bigl[ \\boldsymbol\\alpha \\nabla u \\Bigr]}_{\\mathbf{F}}} -\n",
-       "        \\color{Maroon}{\\underbrace{\\Bigl[ u - \\tilde{f} \\Bigl] }_{\\mathbf{f}}} = 0\n",
+       "        \\color{Maroon}{\\underbrace{\\Bigl[ u - \\tilde{f} \\Bigl] }_{\\mathbf{h}}} = 0\n",
        "$$\n",
        "\n",
        "Where the term $\\mathbf{F}$ provides a smoothing regularization. $\\alpha$ can be zero.\n"
@@ -395,12 +405,12 @@
     {
      "data": {
       "text/latex": [
-       "$\\displaystyle \\left[\\begin{matrix}- 3 {T}_{,0}^{ 2 }(\\mathbf{x}) - {T}_{,1}^{ 2 }(\\mathbf{x}) + 1 & - 2 {T}_{,0}(\\mathbf{x}) {T}_{,1}(\\mathbf{x})\\\\- 2 {T}_{,0}(\\mathbf{x}) {T}_{,1}(\\mathbf{x}) & - {T}_{,0}^{ 2 }(\\mathbf{x}) - 3 {T}_{,1}^{ 2 }(\\mathbf{x}) + 1\\end{matrix}\\right]$"
+       "$\\displaystyle \\left[\\begin{matrix}- 3 { \\hspace{ 0.02pt } {T} }_{,0}^{ 2 }(\\mathbf{x}) - { \\hspace{ 0.02pt } {T} }_{,1}^{ 2 }(\\mathbf{x}) + 1 & - 2 { \\hspace{ 0.02pt } {T} }_{,0}(\\mathbf{x}) { \\hspace{ 0.02pt } {T} }_{,1}(\\mathbf{x})\\\\- 2 { \\hspace{ 0.02pt } {T} }_{,0}(\\mathbf{x}) { \\hspace{ 0.02pt } {T} }_{,1}(\\mathbf{x}) & - { \\hspace{ 0.02pt } {T} }_{,0}^{ 2 }(\\mathbf{x}) - 3 { \\hspace{ 0.02pt } {T} }_{,1}^{ 2 }(\\mathbf{x}) + 1\\end{matrix}\\right]$"
       ],
       "text/plain": [
        "Matrix([\n",
-       "[-3*{T}_{,0}(N.x, N.y)**2 - {T}_{,1}(N.x, N.y)**2 + 1,             -2*{T}_{,0}(N.x, N.y)*{T}_{,1}(N.x, N.y)],\n",
-       "[            -2*{T}_{,0}(N.x, N.y)*{T}_{,1}(N.x, N.y), -{T}_{,0}(N.x, N.y)**2 - 3*{T}_{,1}(N.x, N.y)**2 + 1]])"
+       "[-3*{ \\hspace{ 0.02pt } {T} }_{,0}(N.x, N.y)**2 - { \\hspace{ 0.02pt } {T} }_{,1}(N.x, N.y)**2 + 1,             -2*{ \\hspace{ 0.02pt } {T} }_{,0}(N.x, N.y)*{ \\hspace{ 0.02pt } {T} }_{,1}(N.x, N.y)],\n",
+       "[            -2*{ \\hspace{ 0.02pt } {T} }_{,0}(N.x, N.y)*{ \\hspace{ 0.02pt } {T} }_{,1}(N.x, N.y), -{ \\hspace{ 0.02pt } {T} }_{,0}(N.x, N.y)**2 - 3*{ \\hspace{ 0.02pt } {T} }_{,1}(N.x, N.y)**2 + 1]])"
       ]
      },
      "metadata": {},
@@ -494,7 +504,7 @@
        "        "
       ],
       "text/plain": [
-       "<IPython.lib.display.IFrame at 0x157b68bd0>"
+       "<IPython.lib.display.IFrame at 0x372d715e0>"
       ]
      },
      "execution_count": 11,
@@ -528,9 +538,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3 (ipykernel)",
+   "display_name": "Python (Pixi)",
    "language": "python",
-   "name": "python3"
+   "name": "pixi-kernel-python3"
   },
   "language_info": {
    "codemirror_mode": {
@@ -542,7 +552,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.10"
+   "version": "3.12.11"
   }
  },
  "nbformat": 4,