Add mass conserving temperature model chapter to BST

doc/sphinx/_static/gwb_input_files/BST_17_plume.grid

@@ -0,0 +1,22 @@
+# output variables
+grid_type = cartesian
+dim = 3
+compositions = 4
+
+# domain of the grid
+x_min = -1000e3
+x_max = 2000e3 
+y_min = 0e3
+y_max = 1000e3 
+z_min = 0 
+z_max = 600e3 
+
+# low res grid properties
+n_cell_x = 150 
+n_cell_y = 50
+n_cell_z = 30
+
+# shown grid properties
+# n_cell_x = 1200 
+# n_cell_y = 400
+# n_cell_z = 240

doc/sphinx/_static/gwb_input_files/BST_17_plume.wb

@@ -0,0 +1,90 @@
+{
+  "version": "0.6",
+  "coordinate system":{"model":"cartesian"},
+  "features":
+  [
+    {
+       "model":"mantle layer", "name":"upper mantle", "max depth":660e3,
+       "coordinates":[[-1000e3,0],[-1000e3,1000e3],[3000e3,1000e3],[3000e3,0]],
+       "composition models":[{"model":"uniform", "compositions":[4]}]
+    },
+    {
+       "model":"oceanic plate", "name":"Overriding Plate", "max depth":100e3, 
+       "coordinates":[[0,0],[0,1000e3],[1500e3,1000e3],[1600e3,350e3],[1500e3,0]],
+       "temperature models":
+         [
+           {"model":"half space model", "max depth":100e3, "spreading velocity":0.04, 
+            "ridge coordinates":[[[400e3,-1],[-100e3,2000e3]]]}
+         ],
+       "composition models":[{"model":"uniform", "compositions":[0], "max depth":50e3}]
+    },
+    {
+       "model":"continental plate", "name":"Passive margin", "max depth":[[200e3]], 
+       "coordinates":[[-1000e3,0],[-1000e3,1000e3],[0,1000e3],[0,0]],
+       "temperature models":
+         [
+           {"model":"linear", "max depth":[[100e3],[200e3,[[-250e3,0],[-750e3,1000e3]]]]}
+         ],
+       "composition models":
+         [
+           {"model":"uniform", "compositions":[3], 
+            "max depth":[[100e3],[200e3,[[-250e3,0],[-750e3,1000e3]]]]},
+           {"model":"uniform", "compositions":[1], 
+            "min depth":[[100e3],[200e3,[[-250e3,0],[-750e3,1000e3]]]]}
+         ]
+    },
+    {
+      "model":"oceanic plate", "name":"Subducting Oceanic plate", "max depth":300e3, 
+      "coordinates":[[2000e3,0],[2000e3,1000e3],[1500e3,1000e3],[1600e3,350e3],[1500e3,0]],
+      "temperature models":[{"model":"half space model", "max depth":300e3,"spreading velocity":0.02,
+                             "ridge coordinates":[[[5e6,-1],[5e6,2000e3]]]}],
+       "composition models":[{"model":"uniform", "compositions":[3], "max depth":50e3},
+                             {"model":"uniform", "compositions":[1], "min depth":50e3, "max depth":100e3}]
+    },
+    { 
+      "model":"subducting plate", "name":"Slab", "dip point":[0,0],
+      "coordinates":[[1500e3,1000e3],[1600e3,350e3],[1500e3,0]],
+      "segments":
+        [
+          {"length":300e3, "thickness":[300e3], "top truncation":[-100e3], "angle":[0,60],
+           "composition models":[
+            {"model":"uniform", "compositions":[3], "max distance slab top":50e3},
+            {"model":"uniform", "compositions":[2], "min distance slab top":50e3, "max distance slab top":100e3}]},
+          {"length":500e3, "thickness":[300e3], "top truncation":[-100e3], "angle":[60,20]}
+        ],
+      "sections":
+        [
+          {"coordinate":0,
+          "segments":[{"length":300e3, "thickness":[300e3], "top truncation":[-100e3], "angle":[0,60]},
+          {"length":400e3, "thickness":[300e3], "top truncation":[-100e3], "angle":[60]}],
+          "composition models":[{"model":"uniform", "compositions":[1],"max distance slab top":100e3}]}
+        ],
+      "temperature models":[
+                            {"model":"mass conserving", "density":3300, "plate velocity":0.02,
+                            "ridge coordinates":[[[5e6,-1],[5e6,2000e3]]],"coupling depth":50e3,
+                            "min distance slab top":-200e3, "max distance slab top":300e3}],
+      "composition models":[{"model":"uniform", "compositions":[2], "max distance slab top":100e3}]
+    },
+    {
+      "model":"plume", "name":"Hot spot",
+      "coordinates":[[200e3,450e3],[150e3,450e3],[110e3,450e3],[70e3,450e3],[50e3,450e3],[0e3,450e3]],
+      "cross section depths":[50e3,100e3,200e3,400e3,500e3,600e3],
+      "semi-major axis":[250e3, 150e3, 50e3,50e3,50e3,50e3],
+      "eccentricity":[0.75, 0.75, 0.5, 0.5, 0.5,0.5],
+      "rotation angles":[50, 50, 5, 25, 50, 50],
+      "temperature models":
+      [
+        {
+          "model":"gaussian", "operation":"add",
+          "centerline temperatures":[225, 175, 185, 195, 205, 215],
+          "gaussian sigmas":[0.3, 0.3, 0.3,0.3,0.3,0.3],
+          "depths":[50e3,100e3,200e3,400e3,500e3,600e3]
+        }
+      ], 
+      "composition models":
+      [
+        {"model":"uniform","compositions":[4], "min depth":0}
+      ]
+    }
+  ]
+}

doc/sphinx/user_manual/basic_starter_tutorial/17_plume.md

@@ -0,0 +1,69 @@
+(part:user_manual:chap:basic_starter_tutorial:sec:17_plume)=
+Adding a mantle plume
+===============================
+
+The last feature we will be adding in this tutorial is the `plume`. The plume is defined by a set of coordinates which represent where the plume is at different depths. The depth are set through the `cross section depths` parameter, hich requires as many depths as there are coordinates. Each cross-section is an ellipse, for which the parameters can be set individually. Please see [the plume feature description](part:user_manual:chap:parameter_documentation:sec:features:subsec:plume) for more information on what each of the parameters do. In this case we will increase the eccentricity of the plume at the top.
+
+With the definition of the area the feature plume contains completed, we can now add a temperature and compositional structure. A gaussian is a good first order approximation of the temperature, so we will add that as the temperture model. This temperature model allows you to set change the gausian distribution paramteres for each depth segment. Note that in this case we are not replacing the temperature, but adding to the temperature which was already there.
+
+
+::::::{tab-set}
+
+:::::{tab-item} Important lines
+:sync: Partial
+
+```{literalinclude} ../../_static/gwb_input_files/BST_17_plume.wb
+:language: json
+:lineno-start: 68
+:lines: 68-88
+:emphasize-lines: 4,5,6,7,11,12,13,14
+```
+::::{grid} 3
+:::{grid-item-card} BST_17_plume.wb
+:link: ../../_static/gwb_input_files/BST_17_plume.wb
+:::
+:::{grid-item-card} BST_17_plume.grid
+:link: ../../_static/gwb_input_files/BST_17_plume.grid
+:::
+:::{grid-item-card} Paraview V4 state file 
+:link: ../../_static/paraview_state_files/BST_v4.pvsm
+:::
+::::
+:::::
+
+:::::{tab-item} Full file
+:sync: Full
+
+
+```{literalinclude} ../../_static/gwb_input_files/BST_17_plume.wb
+:language: json
+:lineno-start: 1
+:emphasize-lines: 71,72,73,74,78,79,80,81
+```
+
+::::{grid} 3
+:::{grid-item-card} BST_17_plume.wb
+:link: ../../_static/gwb_input_files/BST_17_plume.wb
+:::
+:::{grid-item-card} BST_17_plume.grid
+:link: ../../_static/gwb_input_files/BST_17_plume.grid
+:::
+:::{grid-item-card} Paraview V4 state file 
+:link: ../../_static/paraview_state_files/BST_v4.pvsm
+:::
+::::
+:::::
+
+::::::
+
+
+```{figure} ../../../../doc/sphinx/_static/images/user_manual/basic_starter_tutorial/BST_17.png
+:name: BST_17
+:alt: Basic Starter Tutorial section 17 highres result. 
+:align: center
+
+Basic Starter Tutorial section 17 high resolution result, were the plume feature is used. In both the top and bottom figure, but area where the plume feature is present is shown. On the top this area is colored red, and on the bottom figure it is colored by temperature. This has 8 times the resolution then the grid file above.
+```
+
+
+This covers the full complexity of the world builder model we are building for this tutorial. Well done for making it this far! You should now be able to start building your own models in the world builder. In the next two tutorials, we are going to take a look at how to create a 2D model from this 3D model and how to make this into a spherical model.

doc/sphinx/user_manual/basic_starter_tutorial/index.md

@@ -31,6 +31,7 @@ Basic Starter Tutorial section will take you step by step to teach you how to cr
 14_different_models_in_segments
 15_different_segments_in_sections
 16_mass_conserving
+17_plume
 18_2D_models
 19_spherical_models
 ```