MAGEMin v1.3.0

- Added metapelite database with MnO (White et al., 2014), use the flag --db=ig or --db=mp to change database from igneous to metapelite
- Improved GUI (PlotPseudosection.mlapp): added option to change database; added panel to plot isocontour (mode and end-member fractions); added option to save pseudosection with isocontour in vector format (eps)
- Updated python scripts to translate database from TC to MAGEMin (check ./python/SS_Analytical_multi_DB.ipynb)
- Documentation udpate

README.md

@@ -4,12 +4,15 @@
 <img src="./pics/GUI.png" alt="drawing" width="640" alt="centered image"/>
 
 # Mineral Assemblage Gibbs Energy Minimization (MAGEMin)
-MAGEMin is a Gibbs energy minimization solver package, which computes the thermodynamically most stable assemblage for a given bulk rock composition and pressure/temperature condition. It also returns parameters such as melt fraction or density, which can be combined with geodynamic/petrological tools to simulate, for example, the evolving chemistry of a crystallising melt.
+`MAGEMin` is a Gibbs energy minimization solver package, which computes the thermodynamically most stable assemblage for a given bulk rock composition and pressure/temperature condition. It also returns parameters such as melt fraction or density, which can be combined with geodynamic/petrological tools to simulate, for example, the evolving chemistry of a crystallising melt.
 
-MAGEMin is written as a parallel C library and uses a combination of linear programming, the extended Partitioning Gibbs free Energy approach and gradient-based local minimization to compute the most stable mineral assemblage. In this, it differs from existing approaches which makes it particularly suitable to utilize modern multicore processors.
+`MAGEMin` is written as a parallel C library and uses a combination of linear programming, the extended Partitioning Gibbs free Energy approach and gradient-based local minimization to compute the most stable mineral assemblage. In this, it differs from existing approaches which makes it particularly suitable to utilize modern multicore processors.
 
 We also provide a MATLAB-based graphical user interface to help computing pseudosections for given bulk rock composition and a [julia interface].
 
+## Documentation
+Full support to install and use MAGEMin is available here: https://computationalthermodynamics.github.io/MAGEMin/index.html
+
 ## Installing MAGEMin
 
 **Quick start**
@@ -24,23 +27,27 @@ Follow these steps:
 
 **Julia interface**
 
-To make it easier to interface MAGEMin with other (geodynamic) codes, we provide a [julia interface](https://github.com/ComputationalThermodynamics/MAGEMin_C.jl) to the MAGEMin C library, with which you can perform pointwise calculations. 
+To make it easier to interface `MAGEMin` with other (geodynamic) codes, we provide a [julia interface](https://github.com/ComputationalThermodynamics/MAGEMin_C.jl) to the `MAGEMin` C library, with which you can perform pointwise calculations. 
 
 **Manual compilation**
 
 if you wish, you can also compile MAGEMin yourself, which requires you to install these packages as well:
 - MPICH (to allow parallel computations)
 - LAPACKE (C version of LAPACK)
 - NLopt (https://nlopt.readthedocs.io/)
-
+
+Details and guidelines are given in the extended documentation: https://computationalthermodynamics.github.io/MAGEMin/index.html  
+
 In addition, we make use of [uthash](https://troydhanson.github.io/uthash/) and [ketopt](https://github.com/attractivechaos/klib/blob/master/ketopt.h).
 
-## Documentation
-Full support to install and use MAGEMin is available here: https://computationalthermodynamics.github.io/MAGEMin/index.html
+
+## Available thermodynamic datasets
+The MAGEMin algorithm is general and can be used with any thermodynamic database that are hardcoded for speed reasons. Presently the igneous (Holland et al., 2018) and the metapelite (White et al., 2014) database are available.
 
 
-## Available thermodynamic dataset
-The MAGEMin algorithm is general and can in principle be used with any thermodynamic database. Yet, for speed reasons, the current implementation hardcoded the hydrous mafic melting model of Holland et al. 2018 which is callibrated for hydrous mafic melts and can be used to simulate the fractional crystallisation from a hydrous basalt to a felsic melt. 
+**Igneous database**
+
+The hydrous mafic melting model of Holland et al. 2018 can be used to simulate the fractional crystallisation from a hydrous basalt to a felsic melt. 
 
 The details of this thermodynamic solid solution and endmember database are:
 - Holland et al., 2018 (see http://hpxeosandthermocalc.org)
@@ -50,7 +57,19 @@ The details of this thermodynamic solid solution and endmember database are:
 	- Solution phases spinel (spn), biotite (bi), cordierite (cd), clinopyroxene (cpx), orthopyroxene (opx), epidote (ep), garnet (g), hornblende (hb), ilmenite (ilm), silicate melt (liq), muscovite (mu), olivine (ol), ternary feldspar (pl4T), and aqueous fluid (fl).
 
 
-Please keep in mind that the dataset we use is only calibrated for a limited range of `P`,`T` and `bulk rock` conditions. If you go too far outside those ranges, `MAGEMin` (or most other thermodynamic software packages for that matter) may not converge or give bogus results. 
+**Metapelite database**
+
+The metapelitic model (extended with MnO, White et al., 2014) allows to compute the mineral assemblage from low temperature to supra-solidus conditions.
+
+- Added March 2023, `MAGEMin v1.3.0` 
+- White et al., 2014a, 2014b (see http://hpxeosandthermocalc.org)
+- K2O-Na2O-CaO-FeO-MgO-Al2O3-SiO2-H2O-TiO2-O-MnO chemical system
+- Equations of state for
+	- Pure stoichiometric phases quartz (q), cristobalite (crst), tridymite (trd), coesite (coe), stishovite (stv), kyanite (ky), sillimanite (sill), andalusite (and), rutile (ru) and sphene (sph). 
+	- Solution phases spinel (spn), biotite (bi), cordierite (cd), orthopyroxene (opx), epidote (ep), garnet (g),  ilmenite (ilm), silicate melt (liq), muscovite (mu),  ternary feldspar (pl4T), sapphirine (sa), staurolite (st), magnetite (mt), chlorite (chl), chloritoid (ctd) and margarite (ma).
+
+
+Please keep in mind that the datasets are only calibrated for a limited range of `P`,`T` and `bulk rock` conditions. If you go too far outside those ranges, `MAGEMin` (or most other thermodynamic software packages for that matter) may not converge or give bogus results. 
 Developing new, more widely applicable, thermodynamic datasets is a huge research topic, which will require funding to develop the models themselves, as well as to perform targeted experiments to calibrate those models.
 
 ## Citation

doc_raw/ckbk/Commands.rst

@@ -32,6 +32,8 @@ The list of valid command line arguments is the following
 +-----------------+-----------------------------------------------+
 | -\-solver=x     | Legacy, 0. PGE, 1 (default)                   |
 +-----------------+-----------------------------------------------+
+| -\-db=""        | database, "ig" or "mp", default is ig         |
++-----------------+-----------------------------------------------+
 | -\-sys_in=""    | system comp "mol" or "wt", default is "mol"   |
 +-----------------+-----------------------------------------------+
 | -\-out_matlab=x | Matlab output, 0. inactive, 1. active         |
@@ -56,15 +58,15 @@ Using previously defined arguments, a valid command to run a single point calcul
 
 .. code-block:: shell
 
-	./MAGEMin --Verb=1 --Temp=718.750 --Pres=30.5000 --test=0 >&log.txt
+	./MAGEMin --Verb=1 --Temp=718.750 --Pres=30.5000 --db=ig --test=0 >&log.txt
 
-Here, the verbose is active and the bulk rock composition of *test 0* is selected. The output of the verbose is saved as a log file *log.txt*.
+Here, the verbose is active, the selected database is "ig" (Igneous) and the bulk rock composition of *test 0* is selected. The output of the verbose is saved as a log file *log.txt*.
 
 If you want to do a computation using a different bulk rock composition you can pass the custom bulk such as:
 
 .. code-block:: shell
 
-	./MAGEMin --Verb=1 --Temp=488.750 --Pres=3.5000 --Bulk=41.49,1.57,3.824,50.56,5.88,0.01,0.25,0.10,0.1,0.0 --sys_in=mol
+	./MAGEMin --Verb=1 --Temp=488.750 --Pres=3.5000 --db=ig --Bulk=41.49,1.57,3.824,50.56,5.88,0.01,0.25,0.10,0.1,0.0 --sys_in=mol
 	
 |
 
@@ -75,7 +77,7 @@ To run multiple points at once you can pass an input file containing the list of
 
 .. code-block:: shell
 
-	./MAGEMin --Verb=1 --File=path_to_file --n_points=x
+	./MAGEMin --Verb=1 --File=path_to_file --n_points=x --db=ig 
 	
 where "path_to_file" is the location of the file and "x" is an integer corresponding to the total number of points contained in the file. The file must have one point per line using the following structure
 
@@ -102,7 +104,7 @@ You can compute the list of points using:
 
 .. code-block:: shell
 
-	./MAGEMin --File=/path_to_file/MAGEMin_input.dat --n_points=4 --test=0
+	./MAGEMin --File=/path_to_file/MAGEMin_input.dat --n_points=4 --test=0 --db=ig 
 
 Note that verbose should be deactivated in parallel (--Verb=0 or --Verb=-1), however matlab output can be generated in parallel (--out_matlab=1). To compute a custom list of bulk-rock compositions you have to provide the oxide composition and replace the "0.0" such as:
 
@@ -120,7 +122,7 @@ Then compute the list of points while indicating the system composition unit (:l
 
 .. code-block:: shell
 
-	./MAGEMin --File=/path_to_file/MAGEMin_input.dat --n_points=4 --sys_in=mol 
+	./MAGEMin --File=/path_to_file/MAGEMin_input.dat --n_points=4 --sys_in=mol  --db=ig 
 |
 
 Multiple points in parallel 
@@ -130,8 +132,8 @@ To run a list of points in parallel, you simply need to call "MPI" before MAGEMi
 
 .. code-block:: shell
 
-	mpirun -np 8 ./MAGEMin --File=/path_to_file/MAGEMin_input.dat --n_points=4 --test=0 --out_matlab=1
-	mpiexec -n 8 ./MAGEMin --File=/path_to_file/MAGEMin_input.dat --n_points=4 --test=0 --out_matlab=1
+	mpirun -np 8 ./MAGEMin --File=/path_to_file/MAGEMin_input.dat --n_points=4 --db=ig --test=0 --out_matlab=1
+	mpiexec -n 8 ./MAGEMin --File=/path_to_file/MAGEMin_input.dat --n_points=4 --db=ig --test=0 --out_matlab=1
 
 where 8 is the desired number of cores. Here the results will be stored in an output file gathering the results of all points (see :ref:`MATLAB output <MATLAB-target>`).
 

doc_raw/index.rst

@@ -10,7 +10,7 @@
 
 |
 
-**MAGEMin v1.2.8**
+**MAGEMin v1.3.0**
 ==================
 
 MAGEMin (Mineral Assemblage Gibbs Energy Minimization) is a parallel C library callable from any petrological/geodynamic tool. For a given set of pressure, temperature and bulk-rock composition MAGEMin uses a combination of linear programming, extended Partitioning Gibbs free Energy and gradient-based local minimization to compute the most stable mineral assemblage     
@@ -32,7 +32,18 @@ Igneous thermodynamic dataset
 - Equations of state for
 	- Pure stoichiometric phases quartz (q), cristobalite (crst), tridymite (trd), coesite (coe), stishovite (stv), kyanite (ky), sillimanite (sill), andalusite (and), rutile (ru) and sphene (sph). 
 	- Solution phases spinel (spn), biotite (bi), cordierite (cd), clinopyroxene (cpx), orthopyroxene (opx), epidote (ep), garnet (g), hornblende (hb), ilmenite (ilm), silicate melt (liq), muscovite (mu), olivine (ol), ternary feldspar (pl4T), and aqueous fluid (fl).
-
+
+Metapelite thermodynamic dataset
+********************************
+
+- White et al., 2014a, 2014b (see http://hpxeosandthermocalc.org)
+- K2O-Na2O-CaO-FeO-MgO-Al2O3-SiO2-H2O-TiO2-O-MnO chemical system
+- Equations of state for
+	- Pure stoichiometric phases quartz (q), cristobalite (crst), tridymite (trd), coesite (coe), stishovite (stv), kyanite (ky), sillimanite (sill), andalusite (and), rutile (ru) and sphene (sph). 
+	- Solution phases spinel (spn), biotite (bi), cordierite (cd), orthopyroxene (opx), epidote (ep), garnet (g),  ilmenite (ilm), silicate melt (liq), muscovite (mu),  ternary feldspar (pl4T), sapphirine (sa), staurolite (st), magnetite (mt), chlorite (chl), chloritoid (ctd) and margarite (ma).
+- added March 2023
+
+
 Imported libraries                       
 ==================
 

doc_raw/issues.rst

@@ -56,14 +56,16 @@ Reduced chemical systems
 Low temperature stabilization
 ******************************
 
-* In a number of cases, mainly water under-saturated cases, and at temperature below 600-650°C, the current version of the solver fails to provide consistent minimizations. We are working on an algorithm upgrade in order to fix this issue. 
+* In a number of cases using the Igneous database, mainly water under-saturated cases, and at temperature below 600-650°C, the PGE solver fails to provide consistent minimizations. 
 
-* While a working alternative approach is already being tested, we are further improving the performances before releasing it.
+* In nearly all of these cases, the Gibbs-Duhem constraint cannot be enforced by the PGE (which relies on being able to enforce it), and an alternative "legacy" has now been added. The "legacy" solver uses the approach presented by de Capitani & Brown (1987). This approach enforces the Gibbs-Duhem constraint only on the effective composition of the solution phase and not on each constitutive endmember of the solution phase such as in the PGE. When the PGE method fails the "legacy" solution can be seen as a relaxed Gibbs-Duhem constraint solution. 
+
+* Note that in the cases of non PGE failure, the PGE and the "legacy" solvers yield identical results, which points out to thermodynamic database limitation outside calibration range.
 
 
 HP-LT melt prediction
 *********************
 
 * For water-saturated composition, we found that at pressure > 20 kbar and temperature < 650°C melt is predicted to be stable. 
 
-* This is a known problem from the THERMOCALC developer community, and a fix should be provided in the following versions of the igenous thermodynamic dataset.
+* This is a known problem from the THERMOCALC developer community, and a fix should be provided in a future version of the igneous thermodynamic dataset.