Sphinx manual user manual basic starter tutorial #489

MFraters · 2023-05-25T22:42:49Z

This pull request add a starter tutorial to the new manual. This is the last new major addition before the next release of the world builder.

The new manual is not complete in the sense that there are many more section I would like to add, but it is already a lot better and more up to date that the pdf manual, so after this is it ready to replace that and start the process of incrementally improving and extending it.

I also found that the 2D chunk is not working well, so I disabled it for now.

github-actions · 2023-05-25T23:15:31Z

Benchmark	Main	Feature	Difference (99.9% CI)
Slab interpolation simple none	1.254 ± 0.003 (s=354)	1.257 ± 0.003 (s=365)	+0.2% .. +0.3%
Slab interpolation curved simple none	1.384 ± 0.015 (s=322)	1.391 ± 0.016 (s=329)	+0.3% .. +0.9%
Spherical slab interpolation simple none	1.661 ± 0.081 (s=264)	1.653 ± 0.077 (s=282)	-1.9% .. +0.8%
Slab interpolation simple curved CMS	1.527 ± 0.015 (s=298)	1.533 ± 0.016 (s=293)	+0.1% .. +0.7%
Spherical slab interpolation simple CMS	2.339 ± 0.014 (s=179)	2.339 ± 0.004 (s=208)	-0.1% .. +0.2%
Spherical fault interpolation simple none	1.499 ± 0.004 (s=312)	1.509 ± 0.005 (s=289)	+0.5% .. +0.7%
Cartesian min max surface	3.363 ± 0.023 (s=123)	3.369 ± 0.029 (s=147)	-0.1% .. +0.5%
Spherical min max surface	9.681 ± 0.222 (s=49)	9.721 ± 0.152 (s=46)	-1.0% .. +1.8%

codecov · 2023-05-25T23:28:49Z

Codecov Report

Merging #489 (35465eb) into main (ed80f78) will increase coverage by 1.09%.
The diff coverage is n/a.

❗ Current head 35465eb differs from pull request most recent head 5175f9d. Consider uploading reports for the commit 5175f9d to get more accurate results

@@            Coverage Diff             @@
##             main     #489      +/-   ##
==========================================
+ Coverage   90.76%   91.86%   +1.09%     
==========================================
  Files          91       91              
  Lines        6446     6441       -5     
==========================================
+ Hits         5851     5917      +66     
+ Misses        595      524      -71

Impacted Files	Coverage Δ
source/gwb-grid/main.cc	`39.94% <ø> (+7.69%)`	⬆️
source/world_builder/features/continental_plate.cc	`100.00% <ø> (ø)`
source/world_builder/features/fault.cc	`99.63% <ø> (ø)`
source/world_builder/features/mantle_layer.cc	`100.00% <ø> (ø)`
source/world_builder/features/oceanic_plate.cc	`100.00% <ø> (ø)`
source/world_builder/features/subducting_plate.cc	`99.64% <ø> (ø)`

... and 2 files with indirect coverage changes

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ed80f78...5175f9d. Read the comment docs.

rfildes

Reviewed through it through 13_subducting_slab_adding_a_segement.md

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

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

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

doc/sphinx/user_manual/basic_starter_tutorial/12_subducting_plate_temperatures.md

doc/sphinx/user_manual/basic_starter_tutorial/13_subducting_slab_adding_a_segment.md

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

rfildes · 2023-05-29T18:33:18Z

doc/sphinx/user_manual/basic_starter_tutorial/14_different_models_in_segments.md

+Different models in segments
+============================
+
+Slabs and faults can be heterogeneous in depth, and this is very easy to represent in the world builder. The segments we just added allow for defining temperature and compositional models, which overwrite the temperature and compositional models for the whole feature. You can think of it this way: you set the default models for each segment in the feature (line 54 and 55) and then you overwrite that default model in the segments where you want something else. 


I think using the word default here is a little confusing since earlier you use the word default to talk about defaults built into GWB itself, not as something you set. Maybe "you set the general models that apply to all the segments in the feature (line 54 and 55), and then you overwrite that general model in the segments where you want to use something else."

I see what you mean, but I don't really like the term general models. I will think about how to reword this.

Yeah I agree general isn't great either. I was having a hard time finding the right word for this since general didn't feel correct either. I'm not sure if "overall" or "broad", "universal" is better?

what about "feature" model? Since it is the the (temperature/composition) model of the feature which is actually set as the "default" which you can overwrite.

Yeah I think that makes sense!

doc/sphinx/user_manual/basic_starter_tutorial/14_different_models_in_segments.md

doc/sphinx/user_manual/basic_starter_tutorial/15_different_segments_in_sections.md

rfildes · 2023-05-29T18:53:00Z

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

+2D models
+=========
+
+2D models in the world builder are nothing more than a cross section through a 3D model. This means that you need to do to be able to create a 2D model is to state in the world builder file the origin of the cross section (where x=0) and in what direction the cross section should go (the positive y direction). You can set this with the global parameter `cross section`. It takes two points. The first point is the origin, and the second point is the direction of the cross section. 


Suggested change

2D models in the world builder are nothing more than a cross section through a 3D model. This means that you need to do to be able to create a 2D model is to state in the world builder file the origin of the cross section (where x=0) and in what direction the cross section should go (the positive y direction). You can set this with the global parameter `cross section`. It takes two points. The first point is the origin, and the second point is the direction of the cross section.

2D models in the world builder are nothing more than a cross section through a 3D model. This means that what you need to do to be able to create a 2D model is to state in the world builder file the origin of the cross section (where x=0) and in what direction the cross section should go (the positive y direction). You can set this with the global parameter `cross section`. It takes two points. The first point is the origin, and the second point is the direction of the cross section.

I think this could be clearer if either you label the coordinates on your figure to show the cross section coordinates or if you had values in parentheses to your text description. I remember a figure Magali made one time showing the 3D model, and then the cross section line through the 3D model that the 2D model was being made for. This could be helpful for visualizing too what points the cross section is being pulled from. Since you already have the 3D model figures made I imagine this might be a fairly quick edit of just adding a line across the 3D model domain showing where this 2D profile comes from and adding that figure to this page? I am confused here how the first point is supposed to be the origin, but it is listed as 0, 200e3 in the file.

I agree, I don't know if I have time to do that before the release though.

rfildes · 2023-05-29T18:57:51Z

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

+
+To make this change two changes need to be made:
+
+1. The coordinate system should be set to spherical and a depth method need to be set.


Suggested change

1. The coordinate system should be set to spherical and a depth method need to be set.

1. The coordinate system should be set to spherical and a depth method needs to be set.

MFraters

Thanks for the through review, it is really appreciated!

MFraters · 2023-05-29T19:41:17Z

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

+2D models
+=========
+
+2D models in the world builder are nothing more than a cross section through a 3D model. This means that you need to do to be able to create a 2D model is to state in the world builder file the origin of the cross section (where x=0) and in what direction the cross section should go (the positive y direction). You can set this with the global parameter `cross section`. It takes two points. The first point is the origin, and the second point is the direction of the cross section. 


I agree, I don't know if I have time to do that before the release though.

doc/sphinx/user_manual/basic_starter_tutorial/15_different_segments_in_sections.md

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

doc/sphinx/user_manual/basic_starter_tutorial/07_subducting_plate_oceanic_part.md

doc/sphinx/user_manual/basic_starter_tutorial/12_subducting_plate_temperatures.md

MFraters · 2023-05-29T19:47:57Z

doc/sphinx/user_manual/basic_starter_tutorial/14_different_models_in_segments.md

+Different models in segments
+============================
+
+Slabs and faults can be heterogeneous in depth, and this is very easy to represent in the world builder. The segments we just added allow for defining temperature and compositional models, which overwrite the temperature and compositional models for the whole feature. You can think of it this way: you set the default models for each segment in the feature (line 54 and 55) and then you overwrite that default model in the segments where you want something else. 


I see what you mean, but I don't really like the term general models. I will think about how to reword this.

Co-authored-by: Rebecca Fildes <[email protected]>

MFraters · 2023-05-31T22:39:15Z

Alright, I think this looks good enough to start out with. Thanks for the reviews @rfildes and @alarshi!

MFraters added 2 commits May 11, 2023 12:18

WIP basic starter tutorial.

3ee67ed

WIP: finished text and code up to BST 10, figuers still missing.

47e6ea7

MFraters added the documentation enhancement Requests for improvements to the documentation label May 25, 2023

MFraters force-pushed the sphinx_manual_User_manual_basic_starter_tutorial_v2 branch from 5e20ef6 to 96f167f Compare May 25, 2023 22:48

rfildes reviewed May 27, 2023

View reviewed changes

rfildes reviewed May 29, 2023

View reviewed changes

MFraters commented May 29, 2023

View reviewed changes

MFraters force-pushed the sphinx_manual_User_manual_basic_starter_tutorial_v2 branch 3 times, most recently from ed6206b to a50f04a Compare May 30, 2023 21:14

MFraters and others added 12 commits May 31, 2023 17:31

Finish initial version of Basic Starter tutorial.

ddcabd5

Spell fixes.

ad3d82f

Disable the 2D chunk due to found issues.

c8e0e4a

fix BST_17 resolution.

f104eff

fix sphinx references in basic starter tutorial.

4b90c58

Apply suggestions from code review from Becky

be92f1f

Co-authored-by: Rebecca Fildes <[email protected]>

Further adress comments Becky.

899749e

Adress comments Arushi.

72a3b04

Fix some typos and reduce resolution of BST grid files.

482c32c

Improving figures based on Becky's comments.

6def1c8

Small improvements to the documentation.

d4302ea

Add changelog entry for the new documentation.

5175f9d

MFraters force-pushed the sphinx_manual_User_manual_basic_starter_tutorial_v2 branch from a50f04a to 5175f9d Compare May 31, 2023 21:48

MFraters merged commit 5cc75e1 into GeodynamicWorldBuilder:main May 31, 2023

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Sphinx manual user manual basic starter tutorial #489

Sphinx manual user manual basic starter tutorial #489

MFraters commented May 25, 2023

github-actions bot commented May 25, 2023 •

edited

Loading

codecov bot commented May 25, 2023 •

edited

Loading

rfildes left a comment

rfildes May 29, 2023

MFraters May 29, 2023

rfildes May 29, 2023

MFraters May 29, 2023

rfildes May 30, 2023

rfildes May 29, 2023

rfildes May 29, 2023

MFraters May 29, 2023

rfildes May 29, 2023

MFraters left a comment

MFraters May 29, 2023

MFraters May 29, 2023

MFraters commented May 31, 2023


		To make this change two changes need to be made:

		1. The coordinate system should be set to spherical and a depth method need to be set.

Sphinx manual user manual basic starter tutorial #489

Sphinx manual user manual basic starter tutorial #489

Conversation

MFraters commented May 25, 2023

github-actions bot commented May 25, 2023 • edited Loading

codecov bot commented May 25, 2023 • edited Loading

Codecov Report

rfildes left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MFraters left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

MFraters commented May 31, 2023

github-actions bot commented May 25, 2023 •

edited

Loading

codecov bot commented May 25, 2023 •

edited

Loading