geodynamics / burnman

BurnMan is a library for modeling mantle thermodynamics and thermoelasticity constrained by mineral physics experiments.
https://geodynamics.github.io/burnman/
GNU General Public License v2.0
54 stars 42 forks source link

Manuscript and DocString: Clarify equilibrate() function #530

Closed kaylai closed 1 year ago

kaylai commented 1 year ago

Issue: The equilibrate() function is described to varying detail in the manuscript, the docstring, and the example jupyter notebook in the tutorial. Some key details are not clear from the manuscript or docstring alone. From the manuscript alone I was confused as to precisely what the equilibrate function was doing and what exactly the inputs and outputs are. The docstrings give a technical description, but I am unclear as to how many constraints are required as inputs and subsequently how many of the unknown constraints are solved for (all of them?).

Suggestion for manuscript: Take some language directly from the jupyter notebook in the tutorial (where the function is best described) and put it into the manuscript. For example, this sentence made things massively clearer for me:

Essentially, one chooses an assemblage (e.g. olivine + garnet + orthopyroxene) and some equality constraints (typically related to bulk composition, pressure, temperature, entropy, volume, phase proportions or phase compositions) and the equilibrate function attempts to find the remaining unknowns that satisfy those constraints.

I would also, however, add how many equality constraints are needed at a minimum. For example, if I have the assemblage, the bulk composition, and the temperature, the rest can be computed?

A list of all possible equality constraints should be added (here you have "typically", but do you actually list all of them? If so, I would remove "typically").

Suggestion for docstring:

In reference to: https://github.com/openjournals/joss-reviews/issues/5389

bobmyhill commented 1 year ago

To Do:

bobmyhill commented 1 year ago

Thanks! Both docstring and manuscript now updated. I've also added more functions to the autodocumentation so that the user can better trace all the calls.