WIP basic starter tutorial.

doc/sphinx/_static/gwb_input_files/BST_12_sections.grid

@@ -0,0 +1,18 @@
+# ouput variables
+grid_type = cartesian
+dim = 3
+compositions = 4
+vtu_output_format = ASCII
+
+# domain of the grid
+x_min = 0e3
+x_max = 2000e3 
+y_min = 0e3
+y_max = 1000e3 
+z_min = 0 
+z_max = 500e3 
+
+# grid properties
+n_cell_x = 640 #160 
+n_cell_y = 320 #80
+n_cell_z = 160 #40

doc/sphinx/_static/gwb_input_files/BST_3_limit_depth.wb

@@ -6,11 +6,11 @@
     {
        "model":"oceanic plate", "name":"Overriding Plate", "max depth":100e3, 
        "coordinates":[[0,0],[0,1000e3],[1500e3,1000e3],[1600e3,350e3],[1500e3,0]],
-       "temperature models":
+       "temperature models":[{"model":"uniform", "temperature":293}],
+       "composition models":
          [
-           {"model":"uniform", "temperature":293, "max depth":50e3}
-         ],
-       "composition models":[{"model":"uniform", "compositions":[0]}]
+           {"model":"uniform", "compositions":[0], "max depth":50e3}
+         ]
     }
   ]
 }

doc/sphinx/_static/gwb_input_files/BST_4_oceanic_plate_temperature.grid

@@ -0,0 +1,18 @@
+# ouput variables
+grid_type = cartesian
+dim = 3
+compositions = 3
+vtu_output_format = ASCII
+
+# domain of the grid
+x_min = 0e3
+x_max = 2000e3 
+y_min = 0e3
+y_max = 1000e3 
+z_min = 0 
+z_max = 500e3 
+
+# grid properties
+n_cell_x = 16 
+n_cell_y = 8
+n_cell_z = 4

doc/sphinx/_static/gwb_input_files/BST_4_oceanic_plate_temperature.wb

@@ -0,0 +1,20 @@
+{
+  "version":"0.5",
+  "coordinate system":{"model":"cartesian"},
+  "features":
+  [
+    {
+       "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}
+         ]
+    }
+  ]
+}

doc/sphinx/_static/gwb_input_files/BST_5_subducting_plate_oceanic_part.grid

@@ -0,0 +1,18 @@
+# ouput variables
+grid_type = cartesian
+dim = 3
+compositions = 3
+vtu_output_format = ASCII
+
+# domain of the grid
+x_min = 0e3
+x_max = 2000e3 
+y_min = 0e3
+y_max = 1000e3 
+z_min = 0 
+z_max = 500e3 
+
+# grid properties
+n_cell_x = 16 
+n_cell_y = 8
+n_cell_z = 4

doc/sphinx/_static/gwb_input_files/BST_5_subducting_plate_oceanic_part.wb

@@ -0,0 +1,27 @@
+{
+  "version":"0.5",
+  "coordinate system":{"model":"cartesian"},
+  "features":
+  [
+    {
+       "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":"oceanic plate", "name":"Subducting Oceanic plate", "max depth":100e3, 
+      "coordinates":[[2000e3,0],[2000e3,1000e3],[1500e3,1000e3],[1600e3,350e3],[1500e3,0]],
+      "temperature models":[{"model":"linear", "max depth":100e3}],
+       "composition models":[{"model":"uniform", "compositions":[3], "max depth":50e3},
+                             {"model":"uniform", "compositions":[1], "min depth":50e3}]
+    }
+  ]
+}

doc/sphinx/_static/gwb_input_files/BST_6_adding_mantle_layer.grid

@@ -0,0 +1,18 @@
+# ouput variables
+grid_type = cartesian
+dim = 3
+compositions = 3
+vtu_output_format = ASCII
+
+# domain of the grid
+x_min = 0e3
+x_max = 2000e3 
+y_min = 0e3
+y_max = 1000e3 
+z_min = 0 
+z_max = 500e3 
+
+# grid properties
+n_cell_x = 16 
+n_cell_y = 8
+n_cell_z = 4

doc/sphinx/_static/gwb_input_files/BST_6_adding_mantle_layer.wb

@@ -0,0 +1,32 @@
+{
+  "version":"0.5",
+  "coordinate system":{"model":"cartesian"},
+  "features":
+  [
+    {
+       "model":"mantle layer", "name":"upper mantle", "max depth":660e3,
+       "coordinates":[[0,0],[0,1000e3],[2000e3,1000e3],[2000e3,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":"oceanic plate", "name":"Subducting Oceanic plate", "max depth":100e3, 
+      "coordinates":[[2000e3,0],[2000e3,1000e3],[1500e3,1000e3],[1600e3,350e3],[1500e3,0]],
+      "temperature models":[{"model":"linear", "max depth":100e3}],
+       "composition models":[{"model":"uniform", "compositions":[3], "max depth":50e3},
+                             {"model":"uniform", "compositions":[1], "min depth":50e3}]
+    }
+  ]
+}

doc/sphinx/_static/gwb_input_files/BST_7_passive_margin_variable_depth.grid

@@ -0,0 +1,18 @@
+# ouput variables
+grid_type = cartesian
+dim = 3
+compositions = 3
+vtu_output_format = ASCII
+
+# domain of the grid
+x_min = 0e3
+x_max = 2000e3 
+y_min = 0e3
+y_max = 1000e3 
+z_min = 0 
+z_max = 500e3 
+
+# grid properties
+n_cell_x = 16 
+n_cell_y = 8
+n_cell_z = 4

doc/sphinx/_static/gwb_input_files/BST_7_passive_margin_variable_depth.wb

@@ -0,0 +1,32 @@
+{
+  "version":"0.5",
+  "coordinate system":{"model":"cartesian"},
+  "features":
+  [
+    {
+       "model":"mantle layer", "name":"upper mantle", "max depth":660e3,
+       "coordinates":[[0,0],[0,1000e3],[2000e3,1000e3],[2000e3,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":"oceanic plate", "name":"Subducting Oceanic plate", "max depth":100e3, 
+      "coordinates":[[2000e3,0],[2000e3,1000e3],[1500e3,1000e3],[1600e3,350e3],[1500e3,0]],
+      "temperature models":[{"model":"linear", "max depth":100e3}],
+       "composition models":[{"model":"uniform", "compositions":[3], "max depth":50e3},
+                             {"model":"uniform", "compositions":[1], "min depth":50e3}]
+    }
+  ]
+}

doc/sphinx/user_manual/basic_starter_tutorial/01_input_design.md

@@ -2,6 +2,4 @@
 World Builder input file design
 =====================================
 
-```{todo}
-Go through the high level input file design
-```
+GWB input files are plain text files using the JSON format. This means you can use any text editor to view and edit the files. If you are not familair with the JSON format, it might be useful to familiarise yourself with it before continuing, although it is not nesseary. The basic idea is that it allows data to be unambigously structured to be readable by both humans and computers. 

doc/sphinx/user_manual/basic_starter_tutorial/02_your_first_input_file.md

@@ -2,10 +2,8 @@
 Your first input file
 =====================
 
+GWB input files are plain-text files, which generally have the extension `.wb`. At minimum, the world builder input file should contain a object (indicated by `{}` in JSON) containing a version number (JSON key: `version`) and a list (indicated by `[]` in JSON) of features (JSON key: `features`). This results in the following input file:  
 
-```{todo}
-Explaining the minimum wb input file (and what it produces) and include a picture of the final result for both composition and temperature.
-```
 
 
 ```{literalinclude} ../../_static/gwb_input_files/BST_1_minimal_box.wb
@@ -21,3 +19,11 @@ Explaining the minimum wb input file (and what it produces) and include a pictur
 :link: ../../_static/gwb_input_files/BST_1_minimal_box.grid
 :::
 ::::
+
+```{note}
+You can copy the text in the box by selecting it, or by hovering over the box and clicking the copy symbol in the top right corner. The file can also be downloaded by clicking on the `Download BST_1_minimal_box.wb` button below the textbox. 
+
+If you want to inspect the result yourself, you can also download the corresponding `.grid` file and use the `gwb-grid` application (`gwb-grid BST_1_minimal_box.wb BST_1_minimal_box.grid`) to create a vtk output (`BST_1_minimal_box.vtk`) and view it in for example Paraview.
+```
+
+Congratulations on creating your first world builder input file! If you visualize the result you will notice that you are getting an adiabatic temperature profile and that every compositional field is zero everywhere. This is the background, or our canvas, if we want to stay in the painting analogy. Now, before we are going to get our brushes, we should first discuss the shape of our canvas a bit more.

doc/sphinx/user_manual/basic_starter_tutorial/03_optional_coordinate_system.md

@@ -2,18 +2,60 @@
 Optional parameter: coordinate system
 =====================================
 
-```{todo}
-Explain that the coordinate system is an optional parameter which by default is set to Cartesian.
+
+When the minimal example on the previous page is passed to the world builder, the world builder fills in anything else it needs with default values. The default values can be viewed in the Parameter listing part of this manual in {ref}`part:GWB_parameter_listings:chap:world_builer_file:sec:index`.
+
+One of the optional parameters which can most fundentaly change what the resulting world looks like is the {ref}`open_coordinate-system`. Reading this document for the first (or even 10th time) is going to probably make you feel a bit overwelmed and it is not needed to continue. If you want to know more, you can open the dropbox below of a detailed explanation of how to read this part of the parameter section.
+
+:::::{dropdown} Coordiante system parameter listing explanation
+:name: part:user_manual:chap:concepts:sec:03_coordinate_system:parameter_explanation
+ For now I will just explain what you need to know to read this part of that document.
+
+The parameter listing is a very big collapsable tree, which in the heading has the path. `/` is the root of the tree, and `/coordinate system` is a object directly on the root. You can collapse everything below `/coordinate system` by clicking the upward arrow on the right, and click it again (now poiting downward) to expand it back. These entries contain information about them, such as the type, default value and documation. The default is set to Cartesian, so of your model is in Cartesian coordiantes, you don't need to do anything.
+
+In our case the coordinate system is an object, which means we need to write something like `"coordinate system": {}` in our input file. 
+
+The next dropbox has the path `/coordinate system/oneOf`. You can collapse it to see that it is the only one dropbox in the `/coordinate system` dropbox. The oneOf subpath indicates you need to choose one object out of a few options. They are listed in the oneOf box. The paths of these dropboxes in the oneOf dropbox are numbered and not named, unfortunatly. This means we will have to look into them to see what they actually represent.
+
+ In this case there are two dropboxes, so let's start with number 1 (path `/coordinate system/oneOf/1`). We can see that this is an object which has one requried key/parameter: `model`. The documentation already states that this is a Cartesian coordinate system. When we look into the model dropbox (`/coordinate system/oneOf/1/model`) we see that thatis an enum with only one possible value: `cartesian`. 
+
+ This is a very long winded way to say that if we want a Cartesian coordinate system, we need to provide a coordiante system object which has a key called model and as a value an enum `cartesian`: `"coordinate system": {"model":cartesian}`.
+
+```{code-block} json
+---
+lineno-start: 3
+---
+    "coordinate system": {"model":"cartesian"}, 
 ```
 
+ Now see if you can find out from the documantion how to create a spherical model.
+
+::::{dropdown} Solution
+:name: part:user_manual:chap:concepts:sec:03_coordinate_system:parameter_explanation:spherical
+
+If you managed to do it in one go, great, well done! If you just tried adding changing `cartesian` to `spherical` you will get an error. It is a nice change to learn how to read the error messages, so take a good look at it. The problem here is that when we look at therequired parameteres in `/coordinate system/oneOf/2`, we see that it also requires a key `depth method`. Please see {ref}`part:user_manual:chap:concepts:sec:const_angle_spherical` for more info on why this is needed. The last option in this section is radius. This key has a default value, so it is optional. The default is set to 6371000.0, which should be fine for most models.
+
+So a spherical model with a user defined radius of 1.0 would look like this:
+
+```{code-block} json
+---
+lineno-start: 3
+---
+    "coordinate system":{"model":"spherical", "depth model":"begin segment", "radius":1.0}, 
+```
+
+::::
+
+
+:::::
 
 This is what we had in our minimal example.
 ```{code-block} json
 ---
 lineno-start: 1
 ---
 {
-    "version":"0.3",
+    "version":"0.5",
     "features":[ ]
 }
 ```
@@ -25,8 +67,27 @@ And now we add one line and set it to the default value. There is no difference
 lineno-start: 1
 ---
 {
-    "version":"0.3",
+    "version":"0.5",
     "coordinate system":{"model":"cartesian"},
     "features":[ ]
 }
-```
+```
+
+````{note}
+If you want to have a spherical model, please see {ref}`part:user_manual:chap:concepts:sec:const_angle_spherical` first. An input file for a spherical model could like somthing like this:
+
+```{code-block} json
+---
+lineno-start: 1
+---
+{
+    "version":"0.5",
+    "coordinate system":{"model":"spherical", "depth model":"begin segment"}, 
+    "features":[ ]
+}
+```
+
+This should be a good default spherical coordiante system. For more information on how to derive this from the paramter listing and what the options are, please expand and read the dropbox above.
+
+In the following sections we will continue using the Cartesian coordinate system. We will also show this in  {ref}`part:user_manual:chap:concepts:sec:16_spherical_models`, where we show how easy it is to switch between cartesian an spherical coordiante systems in our finished subdction example.
+````