Add water content composition to subducting plates and oceanic plates

[danieldouglas92]

Add a new composition to the subducting plate and oceanic plate features that returns the value of the water content within that feature based on the temperature and pressure. Temperature is queried within the feature and pressure is estimated by the lithostatic pressure of a user given reference density. The water content is calculated from parametrized phase diagrams for four different lithologies from a study by Tian et. al., (2019). This study approximates PerPleX phase diagrams for sediments, Mid Ocean Ridge Basalt (MORB), gabbro, and peridotite. An example phase diagram is shown below for MORB.

A user defined initial water content provides an upper bound on the water within the feature, and taking the minimum of the upper bound with the calculated water content at a point yields a reasonable approximation for the water distribution within a subducting slab.

List of tasks:

• Implement the equations for calculating the water content from Tian et. al., (2019).
• Add the water content composition as an option in the oceanic plate feature
• Add the water content composition as an option in the subducting plate feature
• Create a test that shows a smooth distribution of water in the unsubducted oceanic plate and the subducted plate

[codecov]

Codecov Report

Attention: 155 lines in your changes are missing coverage. Please review.

Comparison is base (d9c2f64) 92.82% compared to head (e7274e6) 90.84%.
Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #661      +/-   ##
==========================================
- Coverage   92.82%   90.84%   -1.98%     
==========================================
  Files         105      107       +2     
  Lines        7176     7354     +178     
==========================================
+ Hits         6661     6681      +20     
- Misses        515      673     +158     

Files	Coverage Δ
...bducting_plate_models/composition/water_content.cc	12.79% <12.79%> (ø)
.../oceanic_plate_models/composition/water_content.cc	12.08% <12.08%> (ø)

... 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 d9c2f64...e7274e6. Read the comment docs.

[danieldouglas92]

I've reopened this Pull Request because this now seems like the better approach over #690.

I abandoned this approach because there was an issue where the water content would not monotonically decrease downdip of the trench, but would actually spike to large values at depth. I thought this issue would be resolved if instead of simply calculating the pointwise water content, we track the water from the trench to the point where we were calculating the water, thereby ensuring that it would never increase. This was computationally very expensive, and it turns out that the increase in water at depth was actually largely due to the fact that the parameterized phase diagrams used to determine the water content breaks down at large pressures. By capping the pressure before the parameterization breaks downs, the resulting water distribution is smooth, and largely decreases monotonically downdip.

Below I show an example:

First, this is the temperature distribution for the example slab:

This is what the water content (Composition 0, in wt%) USED to look like, before limiting the pressure:

Notice the sudden jump in water content in the vertical portion of the slab. And with the limited pressure, this is what the water content (Composition 0, in wt%) distribution looks like now:

This increase in water content is now gone.

[github-actions]

Benchmark	Main	Feature	Difference (99.9% CI)
Slab interpolation simple none	0.988 ± 0.002 (s=449)	0.989 ± 0.004 (s=464)	+0.0% .. +0.2%
Slab interpolation curved simple none	0.990 ± 0.004 (s=467)	0.992 ± 0.013 (s=444)	+0.0% .. +0.4%
Spherical slab interpolation simple none	1.164 ± 0.007 (s=375)	1.166 ± 0.007 (s=400)	-0.0% .. +0.3%
Slab interpolation simple curved CMS	1.034 ± 0.005 (s=450)	1.036 ± 0.004 (s=422)	+0.1% .. +0.3%
Spherical slab interpolation simple CMS	1.571 ± 0.010 (s=298)	1.570 ± 0.012 (s=278)	-0.2% .. +0.1%
Spherical fault interpolation simple none	1.167 ± 0.008 (s=407)	1.167 ± 0.007 (s=367)	-0.2% .. +0.2%
Cartesian min max surface	2.364 ± 0.021 (s=185)	2.324 ± 0.039 (s=202)	-2.2% .. -1.3%
Spherical min max surface	7.018 ± 0.027 (s=68)	7.024 ± 0.031 (s=63)	-0.2% .. +0.3%

[danieldouglas92]

This is ready for a look through whenever you find time for a review :) @MFraters

[MFraters]

Thanks for the (reactivated) pull request! Very cool plugin, and the code itself looks to be in great shape.

My main question is related to use use of the different fixed lithologies. These seem to be determined by the parameterization in the Tian paper. But how likely is it that someone might want to use slightly different values, or a different formulation for computing water?

If you would say that for this Tian formulation, you always want to use these values for sediment, periodite, etc, then it makes sense to the way you have done it now and just give users the enum values to choose. This is similar to what happens in the mass conserving temperature model. If you say that people would want to play a lot with these values, then we might want to make them available.

The second part of this is the question how likely it is that someone might want to use a different water content model. I think it would be good to rename the plugin to make clear that this is the Tian 2019 water content, or add/rearrange parameters within the model to make it flexable. But I am happy to be convinced otherwise or of an other solution.

[danieldouglas92]

@MFraters Thanks for the feedback! For the Tian parameterization I would say people would not want to vary the lithologies and the corresponding polynomial coefficients as these values are explicitly defined in the Tian et al., 2019 publication. However, I could certainly see someone wanting to compute the initial water content in a slab using something other than the Tian parameterization defined here (i.e. a Perplex lookup table). At the very least I can rename things to make it clear it is using the Tian parameterization, but I'll try to see if theres a way to make it more flexible to accommodate other methods such as thermodynamic lookup tables!

[danieldouglas92]

@MFraters I cleaned up the code and fleshed out the documentation in places. I ended up rewording the composition name to make it explicit that this uses the parameterized phase diagrams unique to the Tian et al., 2019 publication. I decided not to try to make it generalized because unless we include thermodynamic lookup tables within the worldbuilder git repo, its not trivial to me how we would allow any user-created thermodynamic lookup table to be compatible with the code that I had already created. However, I did add another parameter, the cutoff pressure, because while the polynomial coefficients are explicitly defined in the publicaion, the pressures at which the parameterization breaks down is not. In the description of the parameter I put the recommended values (from my experience).

[MFraters]

Thanks for the changes, it looks much better this way. I think it was a good call to make the pressure cutoff variable. (And a coverage of almost 98%, nice!)

There is on thing which I am a bit worried about, and that is all the vector copying you are doing inside the calculation. I think the following would make the code easier to read and more efficient since the if statement block and vector copying goes away:

header file:

std::array<std::vector<double>,4> LR_poly = 
{
 {-19.0609, 168.983, -630.032, 1281.84, -1543.14, 1111.88, -459.142, 95.4143, 1.97246},
{...},
{...},
{...}
}

This way you can access them in the .cpp file with LR_poly[periodite] or LR_poly[sediment].

so this:

          // Calculate the LR value from Tian et al., 2019
          for (unsigned int LR_coeff_index = 0; LR_coeff_index < LR_polynomial_coeffs.size(); ++LR_coeff_index)
            ln_LR_value += LR_polynomial_coeffs[LR_coeff_index] * (std::pow(1/pressure, LR_polynomial_coeffs.size() - 1 - LR_coeff_index));

would become:

          // Calculate the LR value from Tian et al., 2019
          for (unsigned int LR_coeff_index = 0; LR_coeff_index < LR_polynomial_coeffs.size(); ++LR_coeff_index)
            ln_LR_value += LR_poly[lithology_type][LR_coeff_index] * (std::pow(1/pressure, LR_poly[lithology_type].size() - 1 - LR_coeff_index));

bwt, what does LR, c and Td stand for. Can you write it out or document it? Or are those just the symbols they use in the paper?

[danieldouglas92]

@MFraters I didn't know you could index with an enum! Very cool, I made the changes.

[MFraters]

This looks great, thanks for the quick changes! I think this is ready to merge, but lets see what the testers say :)

I was doubting over one thing, and I want to document my doubt. I was not sure about whether tian water content be Tian water content or not, given that it is a name. I looked through the codebase and the only other place I could find was the gaussian temperature model (https://github.com/GeodynamicWorldBuilder/WorldBuilder/blob/main/source/world_builder/features/plume_models/temperature/gaussian.cc), where we also use a lower case. So I guess it is what we go with now :)

@MFraters I didn't know you could index with an enum! Very cool, I made the changes.

enums in c and c++ are just integers and can be used as such (except maybe class enum). Here is a quick example: https://onecompiler.com/cpp/42prjdbr4 .