diff --git a/docs/user/Installation.qmd b/docs/user/Installation.qmd new file mode 100644 index 000000000..26b01435a --- /dev/null +++ b/docs/user/Installation.qmd @@ -0,0 +1,91 @@ +--- +title: "Installation Guide" +subtitle: "Hints and Tips" +authors: +- name: Underworld Team + +exports: +- format: html +--- + +## Source code build using mamba + +We recommend that you use a `conda` / `mamba` virtual environment to build `underworld3` whenever you want to install on a personal workstation or laptop (linux or macOS).The [`mamba` documentation](https://mamba.readthedocs.io/en/latest/index.html) will help you get started if you are not familiar with the philososphy and practice of this package management system. + +The `underworld3` build / run-time dependencies can be installed using + +```bash + (base) % git clone -b development --single-branch https://github.com/underworldcode/underworld3 /path/to/underworld3 + (base) % cd /path/to/underworld3 + (base) % mamba env create -n uw3 -f environment.yml + (base) % mamba activate uw3 + + (uw3) % pip install . +``` + +## Source code build using mamba and existing PETSc + +If you have an exisiting build of `PETSc` that you need to use, the following +instructions work well. We create the environment as before but remove the pre- +installed `PETSc` and `petsc4py`. + +```bash + (base) % git clone -b development --single-branch https://github.com/underworldcode/underworld3 /path/to/underworld3 + (base) % cd /path/to/underworld3 + (base) % mamba env create -n uw3p -f environment.yml + (base) % mamba activate uw3p + + (uw3p) % mamba remove petsc4py + (uw3p) % mamba remove petsc +``` + +Next set up PETSc as you like it and build it using the tools +within the current mamba virtual environment. Set the `PETSC_ARCH` +environment variable to the name of this virtual environment to keep things +from becoming muddled. See [PETSc Installation]() for details on +how to configure and build what you need. + +```bash + + (uw3p) % export PETSC_DIR=/path/to/petsc + (uw3p) % export PETSC_ARCH="uw3p" + (uw3p) % git clone -b release https://gitlab.com/petsc/petsc.git $PETSC_DIR + (uw3p) % cd $PETSC_DIR + (uw3p) % # Configure & Build step +``` +Next we `pip install` the petsc4py that we just built into the mamba virtual environment. This +ensures that `petsc4py` is available and also that its internal configuration points to the `PETSc` installation we just created. This way we don't need to manage environment variables to point to the build that corresponds to a given virtual environment. + +```bash + (uw3p) % mamba install cmake + (uw3p) % cd $PETSC_DIR/src/binding/petsc4py + (uw3p) % pip install . +``` + +Building `underworld3` against this version of `PETSc` should be identical to the mamba version. + +```bash + (uw3p) % cd /path/to/underworld3 + (uw3p) % pip install . +``` + +#### Did it work ? + +First run the tests: + +```bash + (uw3p) % cd /path/to/underworld3 + (uw3p) % source test.sh +``` + +If you have problems, contact us via the `underworl3` [GitHub issue tracker](https://github.com/underworldcode/underworld3/issues) + +## Docker container + +Windows users, if you don't want to create a linux partition, you can use our containers with `docker` or `podman`. As the code is still in active development, we are not always able to provide containers for each change to the development branch. We ask that you reach out to us on our [GitHub issue tracker](https://github.com/underworldcode/underworld3/issues) to ask for information (use the "question" label). + +## HPC builds + +`Underworld3` is inherently parallel and designed for use in high performance computing environments. The symbolic layer is relatively lightweight and should not adversely affect launch time (drawing down libraries from disk) or execution time (very few calculations are done in python itself). + +In the HPC environment you may find it difficult to control the software stack. You will need to ensure that you can build against PETSc 3.21 or higher, since important functionality that we need is only available from that release onwards. We are happy to provide assistance with builds on specific machines and ask that you contact us through the [GitHub issue tracker](https://github.com/underworldcode/underworld3/issues) so that other people are able to browse the issues and their fixes. diff --git a/docs/user/NextSteps.qmd b/docs/user/NextSteps.qmd index 33c842b42..a90d79a55 100644 --- a/docs/user/NextSteps.qmd +++ b/docs/user/NextSteps.qmd @@ -12,31 +12,86 @@ exports: ### Underworld Documentation and Examples +In addition to the notebooks in this brief set of examples, there are a number of sources of information on using `Underworld3` that you can access: + + - [The Underworld Website / Blog](https://www.underworldcode.org) + + - [The API documentation](https://underworldcode.github.io/underworld3/development_api/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. + + - The [`underworld3` GitHub repository](https://github.com/underworldcode/underworld3) is the most active development community for the code. + ### Benchmarks +The [Underworld3 Benchmarks Repository](https://github.com/underworld-community/UW3-benchmarks) is a useful place to find community benchmarks coded in `underworld3` along with accuracy and convergence analysis. This is an open repository where you can make a pull request with new benchmark submissions once you get the hang of things. ### The Underworld Community -Sharing codes / fixes - -Sharing models +The [Underworld Community](https://github.com/underworld-community) organisation on Github is a collection of contributed repositories from the underworld user community for all versions of the code and now includes scripts for underworld3. ### Parallel Execution -Advise using jupytext to render notebooks at .py files. This is helpful -in shared environments because the files contain no output and play -better with version control. +`Underworld3` is inherently parallel and designed for high performance computing. The symbolic layer is a relatively thin veneer that sits on top of the `PETSc` machinery. A script that has been developed in `jupyter` should be transferrable to an HPC environment with no changes (except that inherently serial operations such as visualisation and model reduction are best left to postprocessing / co-processing). + +We recommend installing `jupytext` which allows either a seamless two-way conversion (or pairing) between the `ipynb` format and an annotated python script, or the ability to work entirely with annoted python scripts and not use `ipynb` at all. The python form does not store the output of notebook cells but there are advantages to this when scripts are under version control. + +Almost all of our notebook examples are annotated python for this reason.An exception is the collection of notebooks in this quick-start guide because we want to show you the rendered output in the static web pages. + +```bash + mpirun -np 1024 python3 Modelling_Script.py -uw_resolution 96 +``` + +The main difference between the notebook development environment and HPC is the lack of interactivity, particularly in sending parameters to the script at launch time. Typically, we expect the HPC version to be running at much higher resolution, or for many more timesteps than the development notebook. We use the `PETSc` command line parsing machinery to generate notebooks that also can ingest run-time parameters from a script (as above). + + +### Advanced capabilities + +Digging a bit deeper into `underworld3`, there are many capabilities that require a clear understanding of the concepts that underlie the implementation. The following examples are not *plug-and-play*, but they do only require python coding using the `underworld3` API and no detailed knowledge of `petsc4py` or `PETSc`. [Get in touch with us](https://github.com/underworldcode/underworld3/issues) if you want to try this sort of thing but can't figure it out for yourself. -Not such a good idea if you want to have a tutorial with outputs (like this one) +#### Deforming meshes + +In [Example 8](Notebooks/8-Particle_Swarms.ipynb), we made small variations to the mesh to conform to basal topography. We did not remesh, so we had to be careful to apply a smooth, analytic displacement to every node. For more general free-surface models, we need to calculate a smooth function using the computed boundary motions (e.g, solving a poisson equation with known boundary displacements as boundary conditions). We need to step through time and it is common to stabilize the surface motions through a surface integral term that accounts for the interface displacement during the timestep. The example below shows an `underworld3` forward model with internal loads timestepped close to isostatic equilibrium. + +![*Stokes flow driven by buoyancy in an annulus defined by two embedded surfaces within an enveloping disk mesh. The surfaces deform in response to the flow. The embedding medium has a very low viscosity but still acts to damp rotational modes. The outer boundary of the disk can be set to a far-field gravitational potential for whole-Earth relaxation models*](media/RelaxingMesh.png){width=50%} + +In a more general case, we need to account to horizontal motions. This is more complicated because the horizontal velocities can be large even when vertical equilibrium is achieved. So we need to solve for the advected component of vertical motion in addition to the local component. Hooray for symbolic algebra ! + +#### Weak / penalty boundary conditions + +[Example 8](Notebooks/8-Particle_Swarms.ipynb) introduced the idea of penalty-based boundary conditions where the constraint is weakly enforced by providing a large penalty for violation of the condition. This is very flexible as the penalizing conditions can be adjusted during the run, including changing which part of the boundary is subject to constraints based on the solution or a coupled problem. The channel flow model shown below has a boundary condition that depends on a externally sourced model for ponded material at the base that is derived from a simple topography filling algorithm. + +```{=html} +
+ +
+``` +*Live Image: Stokes flow in a channel with multiple obstructions. Flow is driven from the inlet (a velocity boundary condition). The geometry was contructed with `gmsh`. This is an example for education which demonstrates the emergence of an large-scale pressure gradient as a result of the presence of the obstructions, and also the dispersion of tracers through the complicated flow geometry* + +The penalty approach does allow the solution to deviate from the exact value of the boundary condition, in a similar way to the iterative solvers delivering a solution to within a specified tolerance. There are some cases, for example, enforcing plate motions at the surface, where there are uncertainties in the applied boundary conditions and that these uncertainties may vary in space and time. + +#### Mesh Adaptation + +It is also possible to use the PETSc mesh adaption capabilities, to refine the resolution of a model where it is most needed and coarsen elsewhere. Dynamically-adapting meshes are possible but the interface is very low level at present, particularly in parallel. + +```{=html} +
+ +
+``` +*Live Image: Static mesh adaptation to the slope of a field. The driving buoyancy term is three plume-like upwellings and the slope of this field is shown in colour (red high, blue low). The adapted mesh is shown in green.* +```python + # t is the driving "temperature". We form an isotropic refinement metric from its slope - diff --git a/docs/user/Notebooks/.jupyter/desktop-settings.json b/docs/user/Notebooks/.jupyter/desktop-settings.json index a170a30c4..1e2f9b63e 100644 --- a/docs/user/Notebooks/.jupyter/desktop-settings.json +++ b/docs/user/Notebooks/.jupyter/desktop-settings.json @@ -1,3 +1,3 @@ { - "pythonPath": "/Users/lmoresi/mambaforge/envs/underworld3p/bin/python3" + "pythonPath": "/Users/lmoresi/mambaforge/envs/underworld3/bin/python" } \ No newline at end of file diff --git a/docs/user/Notebooks/1-Meshes.ipynb b/docs/user/Notebooks/1-Meshes.ipynb index 946eae9a8..3a8328be0 100644 --- a/docs/user/Notebooks/1-Meshes.ipynb +++ b/docs/user/Notebooks/1-Meshes.ipynb @@ -64,7 +64,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 9, "id": "5a4437ff-63ae-4ffa-9f2b-8ec1b8b4baeb", "metadata": { "editable": true, @@ -74,15 +74,7 @@ }, "tags": [] }, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "[esdhcp-137.anu.edu.au:81197] shmem: mmap: an error occurred while determining whether or not /var/folders/tx/95gr762j29z4tt5d1dnqlgth0000gn/T//ompi.esdhcp-137.501/jf.0/1727463424/sm_segment.esdhcp-137.501.66f70000.0 could be created.\n" - ] - } - ], + "outputs": [], "source": [ "#| output: false # Suppress warnings in html version\n", "\n", @@ -274,7 +266,7 @@ " " ], "text/plain": [ - "" + "" ] }, "execution_count": 6, @@ -476,7 +468,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" + "version": "3.11.9" } }, "nbformat": 4, diff --git a/docs/user/Notebooks/2-Variables.ipynb b/docs/user/Notebooks/2-Variables.ipynb index 64aaa51ac..9920ce140 100644 --- a/docs/user/Notebooks/2-Variables.ipynb +++ b/docs/user/Notebooks/2-Variables.ipynb @@ -367,7 +367,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" + "version": "3.11.9" } }, "nbformat": 4, diff --git a/docs/user/Notebooks/3-Symbolic_Forms.ipynb b/docs/user/Notebooks/3-Symbolic_Forms.ipynb index 13e18383e..90c71611b 100644 --- a/docs/user/Notebooks/3-Symbolic_Forms.ipynb +++ b/docs/user/Notebooks/3-Symbolic_Forms.ipynb @@ -37,7 +37,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 23, "id": "5a4437ff-63ae-4ffa-9f2b-8ec1b8b4baeb", "metadata": { "editable": true, @@ -46,15 +46,7 @@ }, "tags": [] }, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "[Lyrebird.local:19272] shmem: mmap: an error occurred while determining whether or not /var/folders/tx/95gr762j29z4tt5d1dnqlgth0000gn/T//ompi.Lyrebird.501/jf.0/95551488/sm_segment.Lyrebird.501.5b20000.0 could be created.\n" - ] - } - ], + "outputs": [], "source": [ "import underworld3 as uw\n", "import numpy as np\n", @@ -329,7 +321,31 @@ { "data": { "text/markdown": [ - "${ \\nabla \\times \\left(\\cal{S} \\mathbf{v}\\right) \\hspace{ 0.0pt } }$" + "**Class**: " + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/latex": [ + "$\\quad$$\\displaystyle { \\nabla \\times \\left(\\cal{S} \\mathbf{v}\\right) \\hspace{ 0.0pt } }$$=$$\\displaystyle - {\\cal{S}}(\\mathbf{x}) {\\mathbf{v}}_{ 0,1}(\\mathbf{x}) + {\\cal{S}}(\\mathbf{x}) {\\mathbf{v}}_{ 1,0}(\\mathbf{x}) + {\\cal{S}}_{,0}(\\mathbf{x}) {\\mathbf{v}}_{ 1 }(\\mathbf{x}) - {\\cal{S}}_{,1}(\\mathbf{x}) {\\mathbf{v}}_{ 0 }(\\mathbf{x})$" + ], + "text/plain": [ + "" + ] + }, + "metadata": {}, + "output_type": "display_data" + }, + { + "data": { + "text/markdown": [ + "$\\quad$**Description:** Curl of {\\mathbf{v}}" ], "text/plain": [ "" @@ -368,10 +384,10 @@ "curl_sv = uw.function.expression(\n", " r\"\\nabla \\times \\left(\\cal{S} \\mathbf{v}\\right)\",\n", " mesh.vector.curl(s.sym * v.sym),\n", - " f\"Curl of {v.symbol}\"\n", + " rf\"Curl of {v.symbol}\"\n", " ) \n", "\n", - "display(curl_sv)\n", + "curl_sv.view()\n", "display(curl_sv.sym) \n", "\n", "curl_sv + 1" @@ -603,7 +619,7 @@ " " ], "text/plain": [ - "" + "" ] }, "execution_count": 15, @@ -810,7 +826,7 @@ }, { "cell_type": "code", - "execution_count": 30, + "execution_count": null, "id": "59a1273d-ee09-479a-9788-d2e6b399e9b8", "metadata": {}, "outputs": [], @@ -833,7 +849,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" + "version": "3.11.9" } }, "nbformat": 4, diff --git a/docs/user/Notebooks/4-Solvers.ipynb b/docs/user/Notebooks/4-Solvers.ipynb index 73b49e442..76963c310 100644 --- a/docs/user/Notebooks/4-Solvers.ipynb +++ b/docs/user/Notebooks/4-Solvers.ipynb @@ -48,7 +48,7 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 12, "id": "042970c2-ab87-4483-b68c-3fe6b8e633a2", "metadata": { "editable": true, @@ -57,15 +57,7 @@ }, "tags": [] }, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "[esdhcp-137.anu.edu.au:75016] shmem: mmap: an error occurred while determining whether or not /var/folders/tx/95gr762j29z4tt5d1dnqlgth0000gn/T//ompi.esdhcp-137.501/jf.0/676069376/sm_segment.esdhcp-137.501.284c0000.0 could be created.\n" - ] - } - ], + "outputs": [], "source": [ "#| output: false # Suppress warnings in html version\n", "\n", @@ -396,7 +388,7 @@ }, { "cell_type": "code", - "execution_count": 16, + "execution_count": 9, "id": "b27c04cd-7192-446b-86e5-3f5a1867045a", "metadata": {}, "outputs": [ @@ -421,7 +413,7 @@ }, { "cell_type": "code", - "execution_count": 9, + "execution_count": 10, "id": "6dccf566-8505-4a6e-94a7-f2869b73e3ff", "metadata": { "editable": true, @@ -477,7 +469,7 @@ }, { "cell_type": "code", - "execution_count": 10, + "execution_count": 11, "id": "4bf2b002-3efd-4f02-907b-c68430f282af", "metadata": { "editable": true, @@ -502,10 +494,10 @@ " " ], "text/plain": [ - "" + "" ] }, - "execution_count": 10, + "execution_count": 11, "metadata": {}, "output_type": "execute_result" } @@ -550,7 +542,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" + "version": "3.11.9" } }, "nbformat": 4, diff --git a/docs/user/Notebooks/5-Solvers.ipynb b/docs/user/Notebooks/5-Solvers.ipynb index 03abaf16c..6dbe677ee 100644 --- a/docs/user/Notebooks/5-Solvers.ipynb +++ b/docs/user/Notebooks/5-Solvers.ipynb @@ -443,7 +443,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" + "version": "3.11.10" } }, "nbformat": 4, diff --git a/docs/user/Notebooks/6-Timestepping.ipynb b/docs/user/Notebooks/6-Timestepping.ipynb index b3defbc6e..5bcf94dce 100644 --- a/docs/user/Notebooks/6-Timestepping.ipynb +++ b/docs/user/Notebooks/6-Timestepping.ipynb @@ -48,18 +48,10 @@ }, { "cell_type": "code", - "execution_count": 2, + "execution_count": 15, "id": "dddf1a25-1d89-4c39-90dc-9ca5a45db5dd", "metadata": {}, - "outputs": [ - { - "name": "stderr", - "output_type": "stream", - "text": [ - "[Lyrebird.local:85742] shmem: mmap: an error occurred while determining whether or not /var/folders/tx/95gr762j29z4tt5d1dnqlgth0000gn/T//ompi.Lyrebird.501/jf.0/960299008/sm_segment.Lyrebird.501.393d0000.0 could be created.\n" - ] - } - ], + "outputs": [], "source": [ "#| output: false # Suppress warnings in html version\n", "\n", @@ -173,7 +165,7 @@ " u_Field=t_soln,\n", " V_fn=v_soln,\n", " solver_name=\"adv_diff\",\n", - " order=1,\n", + " order=2,\n", " verbose=False,\n", ")\n", "\n", @@ -334,15 +326,15 @@ "output_type": "stream", "text": [ "Timestep: 5, time 0.007655378472205266\n", - "Timestep: 10, time 0.014726556792977562\n", - "Timestep: 15, time 0.018483067262087143\n", - "Timestep: 20, time 0.02121125820906285\n", - "Timestep: 25, time 0.023815525765879905\n", - "Timestep: 30, time 0.026692218876534543\n", - "Timestep: 35, time 0.029904104575193727\n", - "Timestep: 40, time 0.03330476637324635\n", - "Timestep: 45, time 0.0367244116173323\n", - "Timestep: 50, time 0.040108815466211735\n" + "Timestep: 10, time 0.01387213547299994\n", + "Timestep: 15, time 0.017197945909787137\n", + "Timestep: 20, time 0.019855789890665786\n", + "Timestep: 25, time 0.02250450167934171\n", + "Timestep: 30, time 0.02546333347384266\n", + "Timestep: 35, time 0.028720014807997008\n", + "Timestep: 40, time 0.032113891988035236\n", + "Timestep: 45, time 0.035501720967277196\n", + "Timestep: 50, time 0.038852418750145654\n" ] } ], @@ -452,7 +444,7 @@ " " ], "text/plain": [ - "" + "" ] }, "execution_count": 14, @@ -473,8 +465,15 @@ "source": [ "## Exercise - Null space\n", "\n", - "Based on our previous notebook, can you see how to remove the rigid-body rotation \n", - "null-space from the solution ?\n", + "Based on our previous notebook, can you see how to calculate and (if necessary) remove rigid-body the rotation \n", + "null-space from the solution ? \n", + "\n", + "The use of a coarse-level singular-value decomposition for the velocity solver should help, here, but it's wise to \n", + "check anyway.\n", + "\n", + "```python\n", + " stokes.petsc_options[\"fieldsplit_velocity_mg_coarse_pc_type\"] = \"svd\"\n", + "```\n", "\n", "## Exercise - Heat flux\n", "\n", @@ -498,23 +497,7 @@ { "cell_type": "code", "execution_count": null, - "id": "9f76dfeb-5c4a-4c4c-a790-14ef030f6256", - "metadata": {}, - "outputs": [], - "source": [] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "94e60f1a-7e7f-447a-9539-66c1a29e8da3", - "metadata": {}, - "outputs": [], - "source": [] - }, - { - "cell_type": "code", - "execution_count": null, - "id": "a237b652-89a0-4aa7-ad07-14c633de9a5a", + "id": "0e5e6ae9-752f-4637-8e8a-9539b6fd2282", "metadata": {}, "outputs": [], "source": [] @@ -536,7 +519,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" + "version": "3.11.9" } }, "nbformat": 4, diff --git a/docs/user/Notebooks/7-Unsteady_Flow.ipynb b/docs/user/Notebooks/7-Unsteady_Flow.ipynb index 865f69b79..1d612f4e0 100644 --- a/docs/user/Notebooks/7-Unsteady_Flow.ipynb +++ b/docs/user/Notebooks/7-Unsteady_Flow.ipynb @@ -471,7 +471,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" + "version": "3.11.9" } }, "nbformat": 4, diff --git a/docs/user/Notebooks/8-ParticleSwarms.ipynb b/docs/user/Notebooks/8-Particle_Swarms.ipynb similarity index 97% rename from docs/user/Notebooks/8-ParticleSwarms.ipynb rename to docs/user/Notebooks/8-Particle_Swarms.ipynb index 6e566ca72..ed4243cb7 100644 --- a/docs/user/Notebooks/8-ParticleSwarms.ipynb +++ b/docs/user/Notebooks/8-Particle_Swarms.ipynb @@ -30,7 +30,7 @@ }, { "cell_type": "code", - "execution_count": 1, + "execution_count": 2, "id": "0974f1a1-60dd-4d52-9855-79e8030450e9", "metadata": {}, "outputs": [], @@ -46,7 +46,7 @@ }, { "cell_type": "code", - "execution_count": 18, + "execution_count": 3, "id": "dddf1a25-1d89-4c39-90dc-9ca5a45db5dd", "metadata": {}, "outputs": [], @@ -195,7 +195,7 @@ { "data": { "application/vnd.jupyter.widget-view+json": { - "model_id": "b567c06831304b4885384029857f9bf3", + "model_id": "16110a6f07c942d28b40970a014d0ba4", "version_major": 2, "version_minor": 0 }, @@ -323,7 +323,7 @@ { "data": { "application/vnd.jupyter.widget-view+json": { - "model_id": "1b5528ee08b945f295f147b2d5f2df21", + "model_id": "ddb5d9712b3c4e82b6e2cd5af8d2aaea", "version_major": 2, "version_minor": 0 }, @@ -520,7 +520,7 @@ }, { "cell_type": "code", - "execution_count": 17, + "execution_count": 1, "id": "4948cff8-89da-4822-aee7-f2207aa513b0", "metadata": {}, "outputs": [ @@ -529,8 +529,8 @@ "text/html": [ "\n", " " + "" ] }, - "execution_count": 17, + "execution_count": 1, "metadata": {}, "output_type": "execute_result" } @@ -550,17 +550,9 @@ "source": [ "#| fig-cap: \"Interactive Image: Convection model output\"\n", "from IPython.display import IFrame\n", - "IFrame(src=f\"html5/terrain_flow_plot.html\", width=1000, height=400)" + "IFrame(src=f\"html5/terrain_flow_plot.html\", width=750, height=300)" ] }, - { - "cell_type": "code", - "execution_count": null, - "id": "811239df-5cb6-4e2e-a7af-7004fa9d3306", - "metadata": {}, - "outputs": [], - "source": [] - }, { "cell_type": "markdown", "id": "c3d1d6ff-68ac-46c0-8a47-e29e95fed462", @@ -615,7 +607,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.7" + "version": "3.11.10" } }, "nbformat": 4, diff --git a/docs/user/Notebooks/Notebook_Index.ipynb b/docs/user/Notebooks/Notebook_Index.ipynb new file mode 100644 index 000000000..43b3ce695 --- /dev/null +++ b/docs/user/Notebooks/Notebook_Index.ipynb @@ -0,0 +1,147 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "3e09bb55-c60c-402f-b24b-251925da5367", + "metadata": {}, + "source": [ + "\n", + "\n", + "
\n", + "\n", + "
\n", + "\n", + "# Tutorials\n", + "\n", + "Underworld is designed to be run in the jupyter notebook environment where you can take advantage of jupyter's rich display capabilities to explore the mathematics of your problem, visualise results and query classes or live objects.\n", + "\n", + "You will find it helpful for developing scripts and analysing results. If you use `jupytext` to write notebooks directly as python scripts, then the same notebook codes will run on a parallel machine with no performance penalty.\n", + "\n", + "The notebooks are rendered as html pages in this guide. They are distributed with the source code on GitHub and can be run on binder.\n", + "\n", + "---\n" + ] + }, + { + "cell_type": "markdown", + "id": "31afe788-d996-48f7-888c-540b88b3bd79", + "metadata": {}, + "source": [ + "#### Notebook 1 - Meshes\n", + "\n", + "**[Meshes](1-Meshes.ipynb)**: Introduces the mesh discretisation that we use in `Underworld3` and how you can build one of the pre-defined meshes. This notebook also show you how to use the `pyvista` visualisation tools for `Underworld3` objects. The mesh holds information on the mesh geometry, boundaries and coordinate systems." + ] + }, + { + "cell_type": "markdown", + "id": "5f8ef25c-5246-4e24-93b7-4e0c59880015", + "metadata": {}, + "source": [ + "#### Notebook 2 - Mesh Variables\n", + "\n", + "**[Variables](2-Variables.ipynb)**: Introduces the concept of `MeshVariables` in `Underworld3`. These are both data containers and `sympy` symbolic objects. We show you how to inspect a `meshVariable`, set the data values in the `MeshVariable` and visualise them." + ] + }, + { + "cell_type": "markdown", + "id": "26b5da69-1292-4988-93e4-591bcf607b32", + "metadata": {}, + "source": [ + "#### Notebook 3 - Symbols and sympy\n", + "\n", + "[Symbols](3-Symbolic_Forms.ipynb): `meshVariables` are `sympy` objects\n", + "that can be composed with other symbolic objects and evaluated numerically when required. They can also be differentiated. Most importantly, `sympy` can manipulate expressions, simplify them and cancel terms." + ] + }, + { + "cell_type": "markdown", + "id": "6d091b23-709b-435c-ade1-9822ad09d567", + "metadata": {}, + "source": [ + "#### Notebook 4 - Example: Diffusion Equation\n", + "\n", + "[Diffusion Solver](4-Solvers.ipynb): Introduces the various solver templates that are available in Underworld, starting with a steady-state diffusion problem. The template requires you to set some constitutive properties and define the unknowns. These are handled through subsitution into symbolic forms and the template equation can be inspected before you need to supply concrete expressions." + ] + }, + { + "cell_type": "markdown", + "id": "eff58d66-8892-4af6-92b0-c18ee9cd2ad2", + "metadata": {}, + "source": [ + "#### Notebook 5 - Example: Stokes Equation\n", + "\n", + "[Stokes Solver](5-Solvers.ipynb): Stokes equation is a more complicated system of equations to solve. This complexity is mostly hidden when you set the problem up. There are some interesting ways to constrain boundary values which are demonstrated using an annulus mesh (curved, free-slip boundaries) and a $\\delta$ function buoyancy source." + ] + }, + { + "cell_type": "markdown", + "id": "0a400f96-5908-4b60-ba0d-ef188c5a66cd", + "metadata": {}, + "source": [ + "#### Notebook 6 - Example: Time Dependence\n", + "\n", + "[Timestepping](6-Timestepping.ipynb): *Coupled* Stokes flow plus thermal advection-diffusion gives a simple convection solver. The timestepping loop is written by hand because usually you will want to do some analysis or output some checkpoints." + ] + }, + { + "cell_type": "markdown", + "id": "3b784a04-823e-4a88-9b18-a57f763dbf56", + "metadata": {}, + "source": [ + "#### Notebook 7 - Example: Navier-Stokes Equation\n", + "\n", + "[Unsteady flow](7-Unsteady_Flow.ipynb) Using a passive swarm to track the pattern of flow developing in a pipe after an impulsive application of a boundary condition at the inflow. Particles need to be added to the passive swarm close to the inflow at each timestep." + ] + }, + { + "cell_type": "markdown", + "id": "42f43817-0e0b-458b-9c5b-34799fb60487", + "metadata": {}, + "source": [ + "#### Notebook 8 - Lagrangian Swarm Variables\n", + "\n", + "[Swarm Variables](8-Particle_Swarms.ipynb) - exploring how they work for specifying material properties with a swarm used to determine element viscosity. We learn how to use swarm variables in expressions generally and for boundary conditions." + ] + }, + { + "cell_type": "markdown", + "id": "a7e39f57-b809-4ba6-821d-7bf57883ef32", + "metadata": {}, + "source": [ + "" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "f485a206-2280-4789-8645-93148511562f", + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.11.9" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/docs/user/Notebooks/html5/annulus_convection_plot.html b/docs/user/Notebooks/html5/annulus_convection_plot.html index 38a7871c4..af9d28606 100644 --- a/docs/user/Notebooks/html5/annulus_convection_plot.html +++ b/docs/user/Notebooks/html5/annulus_convection_plot.html @@ -7,11 +7,11 @@
diff --git a/docs/user/Notebooks/html5/sine_squared.html b/docs/user/Notebooks/html5/sine_squared.html index c373c3a95..e2df08657 100644 --- a/docs/user/Notebooks/html5/sine_squared.html +++ b/docs/user/Notebooks/html5/sine_squared.html @@ -7,11 +7,11 @@
diff --git a/docs/user/Notebooks/html5/spherical_mesh_plot.html b/docs/user/Notebooks/html5/spherical_mesh_plot.html index 8a6bce70b..163d89e2a 100644 --- a/docs/user/Notebooks/html5/spherical_mesh_plot.html +++ b/docs/user/Notebooks/html5/spherical_mesh_plot.html @@ -7,11 +7,11 @@
diff --git a/docs/user/Notebooks/html5/temperature_plot.html b/docs/user/Notebooks/html5/temperature_plot.html index 6888e8a4a..b7f4bdc9b 100644 --- a/docs/user/Notebooks/html5/temperature_plot.html +++ b/docs/user/Notebooks/html5/temperature_plot.html @@ -7,11 +7,11 @@
diff --git a/docs/user/Notebooks/html5/terrain_flow_plot.html b/docs/user/Notebooks/html5/terrain_flow_plot.html index ef922d478..354de9d59 100644 --- a/docs/user/Notebooks/html5/terrain_flow_plot.html +++ b/docs/user/Notebooks/html5/terrain_flow_plot.html @@ -7,11 +7,11 @@
diff --git a/docs/user/Notebooks/media/NotebookScreenshot.png b/docs/user/Notebooks/media/NotebookScreenshot.png new file mode 100644 index 000000000..aadd97498 Binary files /dev/null and b/docs/user/Notebooks/media/NotebookScreenshot.png differ diff --git a/docs/user/Notebooks/ns_flow_at_100.png b/docs/user/Notebooks/ns_flow_at_100.png deleted file mode 100644 index 247186808..000000000 Binary files a/docs/user/Notebooks/ns_flow_at_100.png and /dev/null differ diff --git a/docs/user/Notebooks/ns_flow_at_50.png b/docs/user/Notebooks/ns_flow_at_50.png deleted file mode 100644 index fb80cad05..000000000 Binary files a/docs/user/Notebooks/ns_flow_at_50.png and /dev/null differ diff --git a/docs/user/_quarto.yml b/docs/user/_quarto.yml index f4cb564d4..246d7d696 100644 --- a/docs/user/_quarto.yml +++ b/docs/user/_quarto.yml @@ -8,15 +8,23 @@ book: date: "15/06/2024" bread-crumbs: false chapters: - - index.qmd - - Notebooks/1-Meshes.ipynb - - Notebooks/2-Variables.ipynb - - Notebooks/3-Symbolic_Forms.ipynb - - Notebooks/4-Solvers.ipynb - - Notebooks/5-Solvers.ipynb - - Notebooks/6-Timestepping.ipynb - - Notebooks/7-Unsteady_Flow.ipynb - - NextSteps.qmd + - part: "About UW3" + chapters: + - index.qmd + - NextSteps.qmd + - Installation.qmd + + - part: "Notebooks" + chapters: + - Notebooks/Notebook_Index.ipynb + - Notebooks/1-Meshes.ipynb + - Notebooks/2-Variables.ipynb + - Notebooks/3-Symbolic_Forms.ipynb + - Notebooks/4-Solvers.ipynb + - Notebooks/5-Solvers.ipynb + - Notebooks/6-Timestepping.ipynb + - Notebooks/7-Unsteady_Flow.ipynb + - Notebooks/8-Particle_Swarms.ipynb navbar: search: true @@ -47,7 +55,7 @@ format: other-links: - text: Github Repository icon: github - href: https://github.com/underworld/underworld3 + href: https://github.com/underworldcode/underworld3 # pdf: # documentclass: scrreprt diff --git a/docs/user/index.qmd b/docs/user/index.qmd index e7b05c53f..a1a0b993c 100644 --- a/docs/user/index.qmd +++ b/docs/user/index.qmd @@ -11,55 +11,62 @@ exports: ```{=html}
- +
+ + + Live image: Flow solution in an sphere with prescribed buoyancy + and free slip boundaries. + + ``` --- Welcome to `Underworld3`, a mathematically self-describing, finite-element code for geodynamic modelling. This quick-start guide has basic installation instructions and a brief introduction to some of the concepts in the `Underworld3` code. -It's a good first step after you install the code to look at these notebooks. When you are happy that things are working OK, you can move along to look at the full documentation or the benchmarking repository. +All `Underworld3` source code is released under the LGPL-3 open source licence. This covers all files in `underworld3` constituting the Underworld3 Python module. Notebooks, stand-alone documentation and Python scripts which show how the code is used and run are licensed under the Creative Commons Attribution 4.0 International License. ## Installation Guide -HERE - - -## Notebooks - -Notebook 1 - [Meshes](Notebooks/1-Meshes.html): Introduces the mesh discretisation that we use in `Underworld3` and how you can build one of the pre-defined meshes. This notebook also show you how to use the `pyvista` visualisation tools for `Underworld3` objects. The mesh holds information on the mesh geometry, boundaries and coordinate systems. +The quickest option is **not to install** anything but click on the rocket icon (top right) to launch our notebook examples on mybinder.org. -Notebook 2 - [Variables](Notebooks/2-Variables.html): Introduces the concept of `meshVariables` in `Underworld3`. These are both data containers and `sympy` symbolic objects. We show you how to inspect a `meshVariable`, set the data values in the `meshVariable` and visualise them. +If do you want to install the code on your own machine, we recommend using `miniconda` and `mamba`. Create a separate virtual environment and install the code from source. More details on how to do that are in the [Installation Instructions](Installation.qmd) -Notebook 3 - [Symbols](Notebooks/3-Symbolic_Forms.html): `meshVariables` are `sympy` objects -that can be composed with other symbolic objects and evaluated numerically when required. They can also be differentiated. Most importantly, `sympy` can manipulate expressions, simplify them and cancel terms. +## Sample Code -Notebook 4 - [Diffusion Solver](Notebooks/4-Solvers.html): Introduces the various solver templates that are available in Underworld, starting with a steady-state diffusion problem. The template requires you to set some constitutive properties and define the unknowns. These are handled through subsitution into symbolic forms and the template equation can be inspected before you need to supply concrete expressions. +Underworld is designed to be run in the jupyter notebook environment where you can take advantage of jupyter's rich display capabilities to explore the mathematics of your problem, visualise results and query classes or live objects. -Notebook 5 - [Stokes Solver](Notebooks/5-Solvers.html): Stokes equation is a more complicated system of equations to solve. This complexity is mostly hidden when you set the problem up. There are some interesting ways to constrain boundary values which are demonstrated using an annulus mesh (curved, free-slip boundaries) and a $\delta$ function buoyancy source. +It's a good first step after you install the code to look at the [examples notebooks](Notebooks/Notebook_Index.ipynb). When you are happy that things are working OK, you can move along to look at the full documentation or the benchmarking repository. -Notebook 6 - [Timestepping](Notebooks/6-Timestepping.html): *Coupled* Stokes flow plus thermal advection-diffusion gives a simple convection solver. The timestepping loop is written by hand because usually you will want to do some analysis or output some checkpoints. +The notebooks introduce the concept of meshing to describe the domain and boundary conditions for a model and progress through Eulerian data containers, symbolic operators (functions, compositions, derivatives, evaluations). +The examples move on to the template PDE solvers for scalar and vector problems (in this case the Poisson equation and the Stokes equation) and time dependent, coupled problems (a simple convection example in an annulus geometry). They cover constitutive models, boundary conditions and visualisation. +The final examples deal with Lagrangian data containers (particle swarms), first transporting them in a velocity field, and second, accessing the symbolic forms of their data for use in underworld expressions. -Notebook 7 - Unsteady flow Using a passive swarm to track the pattern of flow developing in a pipe after an impulsive application of a boundary condition at the inflow. Particles need to be added to the passive swarm close to the inflow at each timestep. +## Learn More -Notebook 8 - Swarm variables - exploring how they work for specifying material properties with a swarm used to determine element viscosity. We learn how to use swarm variables in expressions generally and for boundary conditions. +`underworld3` is a research code under continual development and the examples in the notebooks provided with the code only touch upon the extent of its capabilities. Read the [Next Steps](NextSteps.qmd) page to find out how to learn more about `underworld3`, how to get in touch with the development team, and how to become part of the **underworld community**. +## Acknowledgements +The Underworld codes represent more than two decades of programming effort by many developers including a wide community of contributors from the open-source community. +As a community-driven development team, we first acknowledge many contributions made through pull-requests to our repositories and direct submission of codes and examples. The underworldcode organisation on GitHub records all such contributions to the software and the underworld community on GitHub tracks the exchange of information and models. -## Next Steps +Direct funding support has been provided by: -Some of the cool things about UW3 that you can do with a bit of effort (at the moment) + - AuScope provides direct support for the core development team behind the underworld codes and the underworld cloud suite of tools. AuScope is funded by the Australian Government through the National Collaborative Research Infrastructure Strategy, NCRIS. - - gmsh (anything - Pramoda's work) - - deformed meshes, interesting boundary conditions - - free surfaces, relaxation etc - - + - The development and testing of our codes is also supported by computational resources provided by the Australian Government through the National Computing Infrastructure (NCI) under the National Computational Merit Allocation Scheme. -## Documentation + - The Australian Research Council (ARC) supported the development of novel algorithms, computational methods and applications under the Discovery Project and Linkage Project programs. AuScope funding was used to make these methods widely and freely available in the underworld codes. Direct support for Underworld was provided by ARC Industrial Transformation Research Hub Program (The Basin Genesis Hub) +In-kind support has also come from the institution that host Underworld developers including: the Australian National University, Monash University, The University of Melbourne, The University of Sydney and the CSIRO. +## Licensing and re-use +All of our software is released under open source licence and all documentation and worked examples are released with a creative commons licence. We are passionate about having our software used and code reuse is strongly encouraged in the interest of scientific reproducibility and replicability. +The developers are active researchers and scientists whose livelihood depends on their creative talents and the acknowledgement of their work. Please respect the effort that goes into developing software and tutorials by citing our work and collaborating on publication with new applications of our software when you can. ## References diff --git a/docs/user/media/ExplicitGrains_Example.png b/docs/user/media/ExplicitGrains_Example.png new file mode 100644 index 000000000..bcb487acd Binary files /dev/null and b/docs/user/media/ExplicitGrains_Example.png differ diff --git a/docs/user/media/RelaxingMesh.png b/docs/user/media/RelaxingMesh.png new file mode 100644 index 000000000..0af8f4fdf Binary files /dev/null and b/docs/user/media/RelaxingMesh.png differ diff --git a/docs/user/media/pyvista/AdaptedSphere.html b/docs/user/media/pyvista/AdaptedSphere.html new file mode 100644 index 000000000..db031a60f --- /dev/null +++ b/docs/user/media/pyvista/AdaptedSphere.html @@ -0,0 +1,19 @@ + + + + + + + +
+ + + + diff --git a/docs/user/media/pyvista/ChannelFlow.html b/docs/user/media/pyvista/ChannelFlow.html new file mode 100644 index 000000000..1d45e3c77 --- /dev/null +++ b/docs/user/media/pyvista/ChannelFlow.html @@ -0,0 +1,19 @@ + + + + + + + +
+ + + + diff --git a/docs/user/media/pyvista/SphereStreamLinesS.html b/docs/user/media/pyvista/SphereStreamLinesS.html new file mode 100644 index 000000000..1be666b87 --- /dev/null +++ b/docs/user/media/pyvista/SphereStreamLinesS.html @@ -0,0 +1,19 @@ + + + + + + + +
+ + + + diff --git a/src/underworld3/meshing.py b/src/underworld3/meshing.py index d9d681bcf..7d3814fa8 100644 --- a/src/underworld3/meshing.py +++ b/src/underworld3/meshing.py @@ -206,6 +206,8 @@ class boundary_normals_3D(Enum): def box_return_coords_to_bounds(coords): + epsilon = 1.0e-3 + x00s = coords[:, 0] < minCoords[0] x01s = coords[:, 0] > maxCoords[0] x10s = coords[:, 1] < minCoords[1] @@ -215,14 +217,14 @@ def box_return_coords_to_bounds(coords): x20s = coords[:, 2] < minCoords[2] x21s = coords[:, 2] > maxCoords[2] - coords[x00s, 0] = minCoords[0] - coords[x01s, 0] = maxCoords[0] - coords[x10s, 1] = minCoords[1] - coords[x11s, 1] = maxCoords[1] + coords[x00s, 0] = minCoords[0] + epsilon + coords[x01s, 0] = maxCoords[0] - epsilon + coords[x10s, 1] = minCoords[1] + epsilon + coords[x11s, 1] = maxCoords[1] - epsilon if dim == 3: - coords[x20s, 2] = minCoords[2] - coords[x21s, 2] = maxCoords[2] + coords[x20s, 2] = minCoords[2] + epsilon + coords[x21s, 2] = maxCoords[2] - epsilon return coords diff --git a/src/underworld3/swarm.py b/src/underworld3/swarm.py index 60f02ec89..f56fc0029 100644 --- a/src/underworld3/swarm.py +++ b/src/underworld3/swarm.py @@ -1,3 +1,4 @@ +from posixpath import pardir import petsc4py.PETSc as PETSc import numpy as np @@ -1915,6 +1916,7 @@ def __init__( ): self.trackedVariable = trackedVariable self.swarmVariable = None + self.verbose = verbose mesh = trackedVariable.mesh @@ -1935,6 +1937,8 @@ def __init__( nswarm, vtype=trackedVariable.vtype, _proxy=False, + # proxy_degree=trackedVariable.degree, + # proxy_continuous=trackedVariable.continuous, varsymbol=symbol, ) diff --git a/src/underworld3/systems/ddt.py b/src/underworld3/systems/ddt.py index 8173c8e28..1e964293a 100644 --- a/src/underworld3/systems/ddt.py +++ b/src/underworld3/systems/ddt.py @@ -216,7 +216,6 @@ def update_pre_solve( # We use the u_star variable as a working value here so we have to work backwards # so we don't over-write the history terms - # for i in range(self.order - 1, -1, -1): with self._nswarm_psi.access(self._nswarm_psi._X0): @@ -314,7 +313,6 @@ def update_pre_solve( # the data when we put it back onto the nodes with self._nswarm_psi.access(): - orig_index = self._nswarm_psi._nI0.data.copy().reshape(-1) with self.mesh.access(self._workVar):