Merge branch 'release/0.1.13'

.gitignore

@@ -108,4 +108,8 @@ venv.bak/
 
 doc/examples/scratch\.py
 
+# GEOROC Contents - this is automatically updated
 pyrolite/data/georoc/contents\.json
+
+# local alphamelts install folder
+pyrolite/data/alphamelts/localinstall/*

CONTRIBUTING.rst

@@ -1,7 +1,7 @@
 Contributing
 =============
 
-The long-term aim of this project is to be designed, build and supported by and for
+The long-term aim of this project is to be designed, built and supported by (and for)
 the geochemistry community. In the present, the majority of the work involves
 incorporating geological knowledge and frameworks into a practically useful core set of
 tools which can be later be expanded. As such, requests for features and bug reports

README.md

@@ -44,6 +44,6 @@ pip install pyrolite
 
 ### Contributing
 
-The long-term aim of this project is to be designed, build and supported by and for
+The long-term aim of this project is to be designed, built and supported by (and for)
 the geochemistry community. For more information, see the [documentation](https://pyrolite.readthedocs.io/), particularly the [
 Contributing page](https://pyrolite.readthedocs.io/en/latest/contributing.html) and [Code of Conduct](https://pyrolite.readthedocs.io/en/latest/conduct.html).

docs/examples/alphamelts/automation.py

@@ -0,0 +1,44 @@
+import pandas as pd
+from pyrolite.util.alphamelts.meltsfile import to_meltsfile
+from pyrolite.util.alphamelts.automation import MeltsProcess, make_meltsfolder
+# %% testdf
+import numpy as np
+from pyrolite.util.synthetic import test_df
+
+df = test_df(cols=["SiO2", "CaO", "MgO", "FeO", "TiO2", "Na2O", "K2O", "P2O5"])
+df["Sample"] = np.arange(df.index.size)
+# %% setup dataframe
+# taking a dataframe with oxide/element headers, set up experiment info
+df["Title"] = df.Sample
+df["Initial Pressure"] = 7000
+df["Initial Temperature"] = 1350
+df["Final Temperature"] = 1000
+df["Increment Temperature"] = -3
+df["Log fO2 Path"] = "FMQ"
+# %% autorun
+# we can create melts files from each of these data rows, and run an automated experiment
+for ix in df.index:
+    meltsfile = to_meltsfile(  # write
+        df.loc[ix, :],  # take the specific row
+        writetraces=False,  # ignore trace element data
+        modes=[
+            "isobaric",
+            "fractionate solids",
+        ],  # conduct an isobaric experiment where solids are fractionated
+        exclude=["P2O5", "K2O"],  # exclude potassium and phosphorous
+    )
+    # create an experiment folder to work in, add the meltsfile and environment file
+    experiment_folder = make_meltsfolder(
+        meltsfile, df.loc[ix, "Title"], env="pyrolite_envfile.txt"
+    )
+    # set up a melts process to run this automatically
+    process = MeltsProcess(
+        meltsfile=df.loc[ix, "Title"] + ".melts",  #
+        env="pyrolite_envfile.txt",
+        fromdir=str(experiment_folder),
+    )
+    # run some commands as you would in alphaMELTS,
+    # if it errors all hope is lost (for now), and you'll have to run it manually
+    process.write(3, 1, 4, wait=True, log=False)
+    # end the experiment
+    process.terminate()

docs/examples/alphamelts/env.py

@@ -0,0 +1,15 @@
+from pyrolite.util.alphamelts.env import MELTS_Env
+# %% Env
+# set up an environment for an experiment stepping down temperature from 1350 to 1000
+# in 3 degree steps
+env = MELTS_Env()
+env.MINP = 7000
+env.MAXP = 7000
+env.MINT = 1000
+env.MAXT = 1350
+env.DELTAT = -3
+# %% save file
+# you can directly export these parameters to an envrionment file here:
+with open("pyrolite_envfile.txt", "w") as f:
+    f.write(env.to_envfile(unset_variables=False))
+# then pass this to alphamelts using run_alphamelts.command -f pyrolite_envfile.txt

docs/examples/alphamelts/install.py

@@ -0,0 +1,7 @@
+from pyrolite.util.alphamelts.download import install_melts
+from pyrolite.util.meta import pyrolite_datafolder, stream_log
+
+# Here we can do a conditonal install - only downloading alphamelts if it doesnt exist
+if not (pyrolite_datafolder(subfolder="alphamelts") / "localinstall").exists():
+    stream_log("pyrolite.util.alphamelts", level="INFO")  # logger for output info
+    install_melts(local=True)  # install a copy of melts to pyrolite data folder

docs/examples/alphamelts/tables.py

@@ -0,0 +1,30 @@
+import matplotlib.pyplot as plt
+from pyrolite.geochem.ind import __common_oxides__
+from pyrolite.util.alphamelts.tables import MeltsOutput
+
+# %% ---
+# say you have a folder containing melts tables
+output = MeltsOutput(folder, kelvin=False)  # tables in degrees C
+
+# this object has a number of useful attributes
+
+output.tables  # list of tables accessible from the object
+
+{"bulkcomp", "liquidcomp", "phasemass", "phasevol", "solidcomp", "system", "tracecomp"}
+
+output.phasenames  # get the names of phases which appear in the experiment
+
+{"clinopyroxene_0", "feldspar_0", "liquid_0", "olivine_0", "spinel_0"}
+
+output.phases  # dictionary of phasename : phase composition tables (<df>)
+
+{
+    "liquid_0": "<df>",
+    "spinel_0": "<df>",
+    "feldspar_0": "<df>",
+    "clinopyroxene_0": "<df>",
+    "olivine_0": "<df>",
+}
+
+# e.g. access the phase Volume table using:
+output.phasevol

docs/source/index.rst

@@ -8,8 +8,8 @@ geochemical variables (e.g. elements to oxides), functions for common plotting
 tasks (e.g. spiderplots, ternary diagrams, bivariate and ternary density diagrams),
 and numerous auxiliary utilities.
 
-On this site can browse the various `submodules <./submodules.html>`__, or look through
-some of the `usage examples <./usage/examples.html>`__. There's also a quick
+On this site you can browse the various `submodules <./submodules.html>`__, or look
+through some of the `usage examples <./usage/examples.html>`__. There's also a quick
 `installation guide <./installation.html>`__ and some notes on where the project is
 heading in the near `future <./future.html>`__.
 

docs/source/usage/eg/alphamelts/automation.rst

@@ -0,0 +1,18 @@
+Automating alphaMELTS runs
+=============================
+
+pyrolite includes some utilities to help you run alphaMELTS with a little less hassle,
+especially for established workflows or repetitive calculations.
+
+.. literalinclude:: ../../../../examples/alphamelts/automation.py
+  :language: python
+  :end-before: # %% testdf
+
+.. literalinclude:: ../../../../examples/alphamelts/automation.py
+  :language: python
+  :start-after: # %% setup dataframe
+  :end-before: # %% autorun
+
+.. literalinclude:: ../../../../examples/alphamelts/automation.py
+  :language: python
+  :start-after: # %% autorun

docs/source/usage/eg/alphamelts/environment.rst

@@ -0,0 +1,15 @@
+alphaMELTS Environment
+------------------------
+
+.. literalinclude:: ../../../../examples/alphamelts/env.py
+  :language: python
+  :end-before: # %% Env
+
+.. literalinclude:: ../../../../examples/alphamelts/env.py
+  :language: python
+  :start-after: # %% Env
+  :end-before: # %% save file
+
+.. literalinclude:: ../../../../examples/alphamelts/env.py
+  :language: python
+  :start-after: # %% save file

docs/source/usage/eg/alphamelts/localinstall.rst

@@ -0,0 +1,14 @@
+Local Installation of alphaMELTS
+----------------------------------
+
+pyrolite can download and manage its own version of alphaMELTS (without any real
+'installation', *per-se*), and use this for :mod:`~pyrolite.util.alphamelts.automation`
+purposes.
+
+.. literalinclude:: ../../../../examples/alphamelts/install.py
+  :language: python
+
+.. warning:: This 'local install' method still requires that you have Perl installed,
+          as it uses the Perl :code:`run_alphamelts.command` script. If you're on
+          Windows, you can use `Strawberry Perl <http://strawberryperl.com/>`__
+          for this purpose.

docs/source/usage/eg/alphamelts/tables.rst

@@ -0,0 +1,9 @@
+alphaMELTS Tables
+--------------------
+
+To automatically import alphaMELTS tables as :class:`~pandas.DataFrame`s, you can use
+:class:`~pyrolite.util.alphamelts.tables.MeltsOutput`, from which you can then
+develop plots and interrogate data.
+
+.. literalinclude:: ../../../../examples/alphamelts/tables.py
+  :language: python

docs/source/usage/examples.rst

@@ -59,6 +59,21 @@ Indexes
   eg/indexes/*
 
 
+alphaMELTS Utilities
+----------------------
+
+pyrolite includes a set of utilities for working with
+`alphaMELTS <https://magmasource.caltech.edu/alphamelts/>`__. Note that these are
+currently experimental and not affiliated with alphaMELTS. In the future, these
+utilities will likely also make use of the under-development python-melts.
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  eg/alphamelts/*
+
+
 Classification
 -----------------
 .. toctree::

pyrolite/util/alphamelts/__init__.py

@@ -1,11 +1,64 @@
 """
-Utilities for working with the alphaMELTS executable and associated tabular data.
+Utilities for working with the alphaMELTS
+executable and associated tabular data. Note that these are
+currently experimental and not affiliated with alphaMELTS.
+See the `alphaMELTS site <https://magmasource.caltech.edu/alphamelts/>`__ for more info
+[#ref_1]_  [#ref_2]_  [#ref_3]_  [#ref_4]_ [#ref_5]_ [#ref_6]_ [#ref_7]_.
+
+Todo
+-----
+     * As it is developed, also make use of python-melts.
+
+References
+-----------
+.. [#ref_1] Ghiorso M. S. and Sack R. O. (1995). Chemical mass transfer in magmatic
+        processes IV. A revised and internally consistent thermodynamic model for the
+        interpolation and extrapolation of liquid-solid equilibria in magmatic systems
+        at elevated temperatures and pressures. Contributions to Mineralogy and
+        Petrology 119, 197–212.
+        doi: {ghiorso1995}
+.. [#ref_2] Ghiorso M. S., Hirschmann M. M., Reiners P. W. and Kress V. C. (2002).
+        The pMELTS: A revision of MELTS for improved calculation of phase relations
+        and major element partitioning related to partial melting of the mantle to
+        3 GPa. Geochemistry, Geophysics, Geosystems 3, 1–35.
+        doi: {ghiorso2002}
+.. [#ref_3] Asimow P. D., Dixon J. E. and Langmuir C. H. (2004).
+        A hydrous melting and fractionation model for mid-ocean ridge basalts:
+        Application to the Mid-Atlantic Ridge near the Azores. Geochemistry,
+        Geophysics, Geosystems 5.
+        doi: {asimow2004}
+.. [#ref_4] Smith P. M. and Asimow P. D. (2005).
+        Adiabat_1ph: A new public front-end to the MELTS, pMELTS, and pHMELTS models.
+        Geochemistry, Geophysics, Geosystems 6.
+        doi: {smith2005}
+.. [#ref_5] Thompson R. N., Riches A. J. V., Antoshechkina P. M., Pearson D. G.,
+        Nowell G. M., Ottley C. J., Dickin A. P., Hards V. L., Nguno A.-K. and
+        Niku-Paavola V. (2007). Origin of CFB Magmatism: Multi-tiered Intracrustal
+        Picrite–Rhyolite Magmatic Plumbing at Spitzkoppe, Western Namibia, during
+        Early Cretaceous Etendeka Magmatism. J Petrology 48, 1119–1154.
+        doi: {thompson2007}
+.. [#ref_6] Antoshechkina P. M., Asimow P. D., Hauri E. H. and Luffi P. I. (2010).
+        Effect of water on mantle melting and magma differentiation, as modeled using
+        Adiabat_1ph 3.0. AGU Fall Meeting Abstracts 53, V53C-2264.
+.. [#ref_7] Antoshechkina P. M. and Asimow P. D. (2010). Adiabat_1ph 3.0 and the MAGMA
+        website: educational and research tools for studying the petrology and
+        geochemistry of plate margins. AGU Fall Meeting Abstracts 41, ED41B-0644.
 """
 import logging
 
 logging.getLogger(__name__).addHandler(logging.NullHandler())
 logger = logging.getLogger(__name__)
 
+from ..meta import sphinx_doi_link
+
+__doc__ = __doc__.format(
+    ghiorso1995=sphinx_doi_link("10.1007/BF00307281"),
+    ghiorso2002=sphinx_doi_link("10.1029/2001GC000217"),
+    asimow2004=sphinx_doi_link("10.1029/2003GC000568"),
+    smith2005=sphinx_doi_link("10.1029/2004GC000816"),
+    thompson2007=sphinx_doi_link("10.1093/petrology/egm012"),
+)
+__doc__ = str(__doc__).replace("ref", __name__)
 from .download import *
 from .meltsfile import *
 from .parse import *