Slab effective ages (WIP)

CHANGELOG.md

@@ -16,6 +16,8 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 - Added a cookbook for making a transform fault and using this model in ASPECT. \[Juliane Dannberg; 2024-02-14; [#563](https://github.com/GeodynamicWorldBuilder/WorldBuilder/pull/563)\]
 - Added a system which allows users to tag features. The tag index can then be written out throught the gwb-dat program. \[Menno Fraters and Timo Heister; 2024-02-15; [[#598](https://github.com/GeodynamicWorldBuilder/WorldBuilder/pull/598)]\]
 - Added variable spreading for mid oceanic ridges. \[Daniel Douglas; 2024-02-16; [#617](https://github.com/GeodynamicWorldBuilder/WorldBuilder/pull/617)\]
+- Added a new plume feature. \[Juliane Dannberg; 2024-02-15; [[#620](https://github.com/GeodynamicWorldBuilder/WorldBuilder/pull/620)]\]
+- Added a `--resolution-limit` option to gwb-grid to limit the resolution secified in the .grid file. \[Menno Fraters; 2024-02-16; [#653](https://github.com/GeodynamicWorldBuilder/WorldBuilder/pull/653)\]
 
 ### Changed 
 - Unified the directories `cookbooks/` and `doc/sphinx/user_manual/cookbooks`. All information about cookbooks including the documentation is now bundled in the top-level `cookbooks/` directory. \[Rene Gassmoeller; 2024-02-14; [#558](github.com/GeodynamicWorldBuilder/WorldBuilder/pull/558)\]
@@ -25,6 +27,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 ### Fixed
 - Fixed an issue where the ridge feature in spherical geometries for both the half space cooling and plate cooling models gave a discontinuous spreading center when crossing longitudes at intervals of 90 degrees. \[Daniel Douglas; 2024-01-22; [#520](github.com/GeodynamicWorldBuilder/WorldBuilder/pull/520),[#518](github.com/GeodynamicWorldBuilder/WorldBuilder/issues/518)\]
 - In some cases the bezier curve closest_point_on_curve_segment function would include a half circle around the end point(s) as part of a slab/fault. \[Menno Fraters, reported by Daniel Douglas;2023-12-07; [#522](https://github.com/GeodynamicWorldBuilder/WorldBuilder/issues/522) and [#523](https://github.com/GeodynamicWorldBuilder/WorldBuilder/pull/523)\]
+- In some cases the fault feature would not recognize points as inside the fault if they were exactly on the fault line. This is fixed now. \[Rene Gassmoeller; 2024-02-16; [#640](https://github.com/GeodynamicWorldBuilder/WorldBuilder/pull/640)\]
 
 ## [0.5.0]
 ### Added

doc/sphinx/index.md

@@ -29,6 +29,7 @@ user_manual/how_to_use_the_applications/index
 user_manual/concepts/index
 user_manual/basic_starter_tutorial/index
 user_manual/cookbooks/index
+user_manual/parameter_documentation/index
 ```
 
 

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

@@ -2,4 +2,6 @@
 World Builder 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 familiar with the JSON format, it might be useful to familiarise yourself with it before continuing, although it is not necessary. The basic idea is that it allows data to be unambiguously structured to be readable by both humans and computers. 
+GWB input files are plain text files using the JSON format, which allows data to be unambiguously structured to be readable by both humans and computers. You can use any text editor to view and edit the files. If you are not familiar with the JSON format, it might be useful to familiarise yourself with it before continuing, although it is not necessary. If you use Visual Studio Code, settings are included in the main repository (see /.vscode) to make editing World Builder files easier. 
+
+You may need to select "JSON with comments" as the file type to get proper syntax highlighting.

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

@@ -2,7 +2,7 @@
 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:  
+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 minimal input file:  
 
 
 
@@ -24,18 +24,19 @@ GWB input files are plain-text files, which generally have the extension `.wb`.
 ::::
 
 ```{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. 
+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 `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.
+If you want to inspect the results 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.
+Congratulations on creating your first World Builder input file! If you visualize the result (shown below), you will notice an adiabatic temperature profile and that the compositional field is zero everywhere. This is the background, or our canvas if we want to stay in the painting analogy. Now, before grabbing our brushes, we should first discuss the shape of our canvas.
 
 
 ```{figure} ../../../../doc/sphinx/_static/images/user_manual/basic_starter_tutorial/BST_02.png
 :name: BST_02
 :alt: Basic Starter Tutorial section 16 highres result. 
 :align: center
 
-Basic Starter Tutorial section 2. The top part of the figure shows where the composition has been assigned as object. Since no compositions have been assigned yet, nothing is plotted when we view the composition solution. The bottom part shows the temperature solution that has been assigned. This shows the adiabatic temperature gradient. Unless otherwise stated, all figures are generated with double the resolution as in the above grid file. This is because all tutorials are automatically tested and running them at full resolution for every pull request would take too much computational time. The resolution shown in the figures is commented out under the subsection `shown grid properties`.
-```
+Basic Starter Tutorial section 2. The top part of the figure (blank) shows where the composition has been assigned. Since no compositions have been assigned yet, nothing is plotted when we view the composition solution. The bottom part shows the temperature solution that has been assigned. This shows the adiabatic temperature gradient.
+Unless otherwise stated, all figures are generated with double the resolution given as default in the above grid file. Since all tutorials are automatically tested, running at full resolution for every pull request would take too much computational time. The resolution shown in the figures is commented out under the subsection `shown grid properties`.
+```

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

@@ -3,23 +3,22 @@ Optional parameter: coordinate system
 =====================================
 
 
-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_builder_file:sec:index`.
+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 listings part of this manual in {ref}`part:GWB_parameter_listings:chap:world_builder_file:sec:index`.
 
-One of the optional parameters which can most fundamentally 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 overwhelmed and it is not needed to continue. If you want to know more, you can open the drop box below of a detailed explanation of how to read this part of the parameter section.
+One of the optional parameters which can most fundamentally change what the resulting world looks like is the {ref}`open_coordinate-system`. Its default value is `cartesian`. Reading this document for the first (or even 10th time) is overwhelming. If you want to learn more about `/coordinate system`, open the drop box below for a detailed explanation about how to read this section of the manual.
 
-:::::{dropdown} Coordinate system parameter listing explanation
+:::::{dropdown} Coordinate system Parameter listings 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 collapsible 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 pointing downward) to expand it back. These entries contain information about them, such as the type, default value and documentation. The default is set to Cartesian, so of your model is in Cartesian coordinates, you don't need to do anything.
+Parameter listings is a very big collapsible tree in which each heading contains its path. `/` is the root of the tree, and, for example, `/coordinate system` is an object directly on the root. You can collapse objects below `/coordinate system` by clicking the upward arrow on the right, and click it again (now pointing downward) to expand it back. Each object contains its description, type, default value and additional specifications. Here you see the default value for `/coordinate system` is set to `cartesian`. Hence, if your model is in Cartesian coordinates, 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. 
+Since coordinate system is an object, 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, unfortunately. This means we will have to look into them to see what they actually represent.
+The next dropbox has the path `/coordinate system/oneOf`. This is the only entry beneath the `/coordinate system` dropbox. The oneOf subpath indicates you need to choose one object out of a few options. These are listed in the oneOf box. The paths of these dropboxes in the oneOf dropbox are numbered and unfortunately not named. This means we will have to inspect each 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 required 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 that is an enum with only one possible value: `cartesian`. 
+ In this case there are two dropboxes. Let's look at path number 1 (`/coordinate system/oneOf/1`). We can see that this is an object which has one required 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 there is 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 coordinate system object which has a key called model and as a value an enum `cartesian`: `"coordinate system": {"model":cartesian}`.
+ This is a very long winded way to say that if we want a Cartesian coordinate system, we need to provide a coordinate system object which has a key called `model` and has an enum value `cartesian`: `"coordinate system": {"model":cartesian}`.
 
 ```{code-block} json
 ---
@@ -28,12 +27,12 @@ lineno-start: 3
     "coordinate system": {"model":"cartesian"}, 
 ```
 
- Now see if you can find out from the documentation how to create a spherical model.
+ Now see if you can use the documentation 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 the required parameters 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.
+If you managed to do this in one go, great, well done! If you just tried changing `cartesian` to `spherical`, you will get an error. Take a good look at the error message. The error message indicates that a required parameter is missing. `/coordinate system/oneOf/2` requires a key `depth method`. Please see {ref}`part:user_manual:chap:concepts:sec:const_angle_spherical` for more information 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:
 
@@ -49,7 +48,7 @@ lineno-start: 3
 
 :::::
 
-This is what we had in our minimal example.
+Our previous minimal example looks like this:
 ```{code-block} json
 ---
 lineno-start: 1
@@ -61,7 +60,7 @@ lineno-start: 1
 ```
 
 
-And now we add one line and set it to the default value. There is no difference between this one and the previous code block. 
+We can be more explicit and add one line setting it to the default value. However, there is no difference between this one and the previous code block. 
 ```{code-block} json
 ---
 lineno-start: 1
@@ -89,5 +88,5 @@ lineno-start: 1
 
 This should be a good default spherical coordinate system. For more information on how to derive this from the parameter 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:basic_starter_tutorial:sec:17_spherical_models`, where we show how easy it is to switch between cartesian and spherical coordinate systems in our finished subduction example.
-````
+In the following sections we will continue using the Cartesian coordinate system. We will also show this in  {ref}`part:user_manual:chap:basic_starter_tutorial:sec:17_spherical_models`, where we show how easy it is to switch between Cartesian and spherical coordinate systems in our finished subduction example.
+````

doc/sphinx/user_manual/basic_starter_tutorial/04_adding_first_tectonic_feature.md

@@ -4,15 +4,15 @@ Adding your first tectonic feature
 
 Now we are finally ready to get out our brushes and start coloring in the world. We are going to start by adding an oceanic plate to the feature list. 
 
-Each feature is an object, which means we need to enclose it in curly braces (`{}`). You will need to specify the following keys:
+Each feature is an object and is enclosed in curly braces (`{}`). You will need to specify the following keys:
 
-1. The `model` key always defines which feature is set, which is "oceanic plate" in our case. 
-2. The `name` key should contain a descriptive name. The name can be anything, and is mostly to help keep the input file readable. 
+1. The `model` key always defines which feature is being set. In this case it is "oceanic plate". 
+2. The `name` key should contain a descriptive name. The name can be anything and is used to help keep the input file readable. Here we name it "Overriding Plate".
 3. The `coordinates` key is a list of 2D coordinates: x,y in Cartesian and long,lat in spherical. A list in JSON is indicated by square brackets (`[]`) and the items are separated by commas.
 4. (Optional) The `temperature models` key is a list of temperature models. Each temperature model is an object. For now we will just choose the simplest one: `uniform` where we set the temperature to `293`K.
-5. (Optional) The `compositional models` key is a list of compositional models. Each compositional model is an object. Like with the temperature model, we will just chose the simplest one: `uniform` and set the composition in compositional field 0. We will go into more detail how this works later in the tutorial.
+5. (Optional) The `compositional models` key is a list of compositional models. Each compositional model is an object. Like with the temperature model, we will just chose the simplest one: `uniform` and set the composition in compositional field to 0. We will go into more details about how this works later in the tutorial.
 
-There are some other options, which we will cover later. The file below shows the result. To focus your attention, by default only the lines of interest are shown, but you can always view the full file by clicking on the `Full file` tab.
+There are some other options that will be covered later. The file below shows the result. To focus your attention, by default only the lines of interest are shown but you can always view the full file by clicking on the `Full file` tab.
 
 
 ::::::{tab-set}
@@ -68,5 +68,5 @@ There are some other options, which we will cover later. The file below shows th
 :alt: Basic Starter Tutorial section 16 highres result. 
 :align: center
 
-Basic Starter Tutorial section 04. The top part of the figure shows where the composition as been assigned as an object. Currently it only shows composition 0 as green. The bottom part shows the temperature as seen slightly from below. This shows that the overriding plate with a temperature of 293K goes all the way down to the bottom of the model.
+Basic Starter Tutorial section 04. The top part of the figure shows where the composition has been assigned as an object (green box). Here, the composition has been assigned the value 0. The bottom figure shows the temperature as viewed slightly from below. This shows that the overriding oceanic plate has a temperature of 293K that extends from the surface to the bottom of the model.
 ```