Add mass conserving temperature model chapter to BST

doc/sphinx/_static/gwb_input_files/BST_16_mass_conserving.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_16_mass_conserving.wb

@@ -0,0 +1,69 @@
+{
+  "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}]
+    }
+  ]
+}

doc/sphinx/bibliography.bib

@@ -133,6 +133,7 @@ @Article{Fraters_Thieulot_etal_2019
 URL = {https://se.copernicus.org/articles/10/1785/2019/},
 DOI = {10.5194/se-10-1785-2019}
 }
+
 @article{Stein_Stein_1992,
 	author = {C. A. Stein and S. A. Stein},
 	date-added = {2014-07-29 05:28:36 +0000},
@@ -141,4 +142,14 @@ @article{Stein_Stein_1992
 	number = {123-129},
 	title = {A model for the global variation in oceanic depth and heat flow with lithospheric age},
 	volume = {359},
-	year = {1992}}
+	year = {1992}
+  }
+
+
+@article{Billen_Fraters_AGU_2023,
+  title={A New Method for Assigning Thermal Structure to 2D and 3D Present-day Geodynamic and Seismological Models of Subduction Zones},
+  author={Billen, Magali I and Fraters, Menno},
+  journal={AGU23},
+  year={2023},
+  publisher={AGU}
+}

doc/sphinx/user_manual/basic_starter_tutorial/16_mass_conserving.md

@@ -0,0 +1,125 @@
+(part:user_manual:chap:basic_starter_tutorial:sec:16_mass_conserving)=
+Changing to a mass conserving slab temperature
+===============================
+
+In [the section on slab temperature](part:user_manual:chap:basic_starter_tutorial:sec:12_subducting_plate_temp), we added the {cite:t}`McKenzie_1970` (that is the plate model) slab temperature structure. Although this is a good first order approximation of a slab temperature, the recently develop {cite:t}`Billen_Fraters_AGU_2023` temperature model has many advantages over it, with the downside that is it a bit more involved to use. In this chapter we will just switch out the plate model with mass conserving, without going too much into the detail of how to actually use it in practice. If you plan to use the mass conserving temperature model, please first read through both the [Simple Subduction Model: 2D Cartesian](part:user_manual:chap:cookbooks:sec:simple_subduction_2d_cartesian)and [Simple Subduction Model: 2D Chunk](part:user_manual:chap:cookbooks:sec:simple_subduction_2d_chunk) cookbooks.
+
+## Changing the Subducting oceanic plate temperature
+One of the advantages of useing the mass conserving slab temperature model is that it doesn't assume a linear temperature structure at the trench. This means we can seamlessly connect a half space cooling model or a plate model to the mass conseving slab. But for that to make sense, we need to change the subucting oceanic plate to a half space cooling model (the default for the mass conserving temperature model). In this case we will put the ridge far away. Because the half space model can affect the temperature at much deeper depths, we also need to change the max depth for the feature and models. Note that we will want to keep the max depth of the composition 100km, so we now need to set a max depth in the lowest layer of the composition model.
+
+
+::::::{tab-set}
+
+:::::{tab-item} Important lines
+:sync: Partial
+
+```{literalinclude} ../../_static/gwb_input_files/BST_16_mass_conserving.wb
+:language: json
+:lineno-start: 36
+:lines: 36-43
+:emphasize-lines: 2,4,5,7
+```
+::::{grid} 3
+:::{grid-item-card} BST_16_mass_conserving.wb
+:link: ../../_static/gwb_input_files/BST_16_mass_conserving.wb
+:::
+:::{grid-item-card} BST_16_mass_conserving.grid
+:link: ../../_static/gwb_input_files/BST_16_mass_conserving.grid
+:::
+:::{grid-item-card} Paraview 2D state file 
+:link: ../../_static/paraview_state_files/BST_2D.pvsm
+:::
+::::
+:::::
+
+:::::{tab-item} Full file
+:sync: Full
+
+
+```{literalinclude} ../../_static/gwb_input_files/BST_16_mass_conserving.wb
+:language: json
+:lineno-start: 1
+:emphasize-lines: 37,39,40,42
+```
+
+::::{grid} 3
+:::{grid-item-card} BST_16_mass_conserving.wb
+:link: ../../_static/gwb_input_files/BST_16_mass_conserving.wb
+:::
+:::{grid-item-card} BST_16_mass_conserving.grid
+:link: ../../_static/gwb_input_files/BST_16_mass_conserving.grid
+:::
+:::{grid-item-card} Paraview V3 state file 
+:link: ../../_static/paraview_state_files/BST_v3.pvsm
+:::
+::::
+:::::
+
+::::::
+
+## Changing to a mass conserving temperature model
+
+One of the main idea's behind the mass consering model is that the the slab not just warms up, but that the surrounding material cools down as well, thus conserving energy/mass. This means that the subducting plate feature needs to be able to change the temperature outside the slab. Given that a feature can only change the temperature inside it's defined area we need to expand that area. This means we need to increase the thickness, which we set to 300 km. But this only extends the slab feature downwards, while we also want to cool down the material above the slab. For this we can use the `top truncation` parameter. The `top truncation` paramameter is designed to make the slab thinner from above, but when set to a negative value we can actually make it thicker! In this case we will set it to -100 km. 
+
+Now that all the preparatory work is done, we can finally add the mass conserving model itself. The two most important new paramter are the `ridge coordinates`, which should be the same as the subducting oceanic plate ridge coordinates in this case and a parameter called `coupling depth`. The `coupling depth` defines the depth at wich the slab surface first comes in contact with the hot mantle wedge.
+
+::::::{tab-set}
+
+:::::{tab-item} Important lines
+:sync: Partial
+
+```{literalinclude} ../../_static/gwb_input_files/BST_16_mass_conserving.wb
+:language: json
+:lineno-start: 44
+:lines: 44-67
+:emphasize-lines: 6,9,10,15,16,20,21,22,23
+```
+::::{grid} 3
+:::{grid-item-card} BST_16_mass_conserving.wb
+:link: ../../_static/gwb_input_files/BST_16_mass_conserving.wb
+:::
+:::{grid-item-card} BST_16_mass_conserving.grid
+:link: ../../_static/gwb_input_files/BST_16_mass_conserving.grid
+:::
+:::{grid-item-card} Paraview 2D state file 
+:link: ../../_static/paraview_state_files/BST_2D.pvsm
+:::
+::::
+:::::
+
+:::::{tab-item} Full file
+:sync: Full
+
+
+```{literalinclude} ../../_static/gwb_input_files/BST_16_mass_conserving.wb
+:language: json
+:lineno-start: 1
+:emphasize-lines: 49,52,53,58,59,63,64,65,66
+```
+
+::::{grid} 3
+:::{grid-item-card} BST_16_mass_conserving.wb
+:link: ../../_static/gwb_input_files/BST_16_mass_conserving.wb
+:::
+:::{grid-item-card} BST_16_mass_conserving.grid
+:link: ../../_static/gwb_input_files/BST_16_mass_conserving.grid
+:::
+:::{grid-item-card} Paraview V3 state file 
+:link: ../../_static/paraview_state_files/BST_v3.pvsm
+:::
+::::
+:::::
+
+::::::
+
+
+
+```{figure} ../../../../doc/sphinx/_static/images/user_manual/basic_starter_tutorial/BST_16.png
+:name: BST_16
+:alt: Basic Starter Tutorial section 18 highres result. 
+:align: center
+
+Basic Starter Tutorial section 16 high resolution result, were a mass conserving slab temperature is used. This has 8 times the resolution then the grid file above.
+```
+
+These are only the very basics of what the mass conserving temperature model can do. If you are interested in using this temperature model, please read the [Simple Subduction Model: 2D Cartesian](part:user_manual:chap:cookbooks:sec:simple_subduction_2d_cartesian)and [Simple Subduction Model: 2D Chunk](part:user_manual:chap:cookbooks:sec:simple_subduction_2d_chunk) cookbooks.

doc/sphinx/user_manual/basic_starter_tutorial/index.md

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