API

Utilities for working with the alphaMELTS executable and associated tabular data. 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.

Todo

• As it is developed, also make use of python-melts.

• Develop functions for automation over a grid (of P, T, H2O, fO2, X)

• Have an option to aggregate summary data, and options to discard experiment data

• Expansion of documentation

See the alphaMELTS site for more info [1] [2] [3] [4] [5] [6] [7].

References

[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: 10.1007/BF00307281

[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: 10.1029/2001GC000217

[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: 10.1029/2003GC000568

[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: 10.1029/2004GC000816

[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: 10.1093/petrology/egm012

[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.

[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.

pyrolite_meltsutil.automation

This submodule contains functions for automated execution of alphamelts 1.9.

Issues

• names are truncated for modifychem melts files?

• need a timeout so processes can keep going, add unfinished experiments to failed list

class pyrolite_meltsutil.automation.MeltsExperiment(name='MeltsExperiment', title='MeltsExperiment', fromdir='./', meltsfile=None, env=None, timeout=None, executable=None)

Melts Experiment Object. For a single call to melts, with one set of outputs. Autmatically creates the experiment folder, meltsfile and environment file, runs alphaMELTS and collects the results.

Todo

• Automated creation of folders for experiment results (see make_meltsfolder())

• Being able to run melts in an automated way (see MeltsProcess)

• Compressed export/save function

• Post-processing functions for i) validation and ii) plotting

set_meltsfile(meltsfile, **kwargs)

Set the meltsfile for the experiment.

Parameters:

meltsfile (pandas.Series | str | pathlib.Path) – Either a path to a valid melts file, a pandas.Series, or a multiline string representation of a melts file object.

set_envfile(env)

Set the environment for the experiment.

Parameters:

env (str | pathlib.Path) – Either a path to a valid environment file, a pandas.Series, or a multiline string representation of a environment file object.

run(log=False, superliquidus_start=True)

Call ‘run_alphamelts.command’.

cleanup()

pyrolite_meltsutil.automation.process_modifications(cfg)

Process modifications to an configuration composition.

Parameters:

cfg (dict) – Configuratiion dictionary.

Returns:

cfg – Configuratiion dictionary.

Return type:

dict

class pyrolite_meltsutil.automation.MeltsBatch(comp_df, default_config={}, config_grid={}, fromdir=PosixPath('.'), env=None, executable=None, timeout=None, logger=<Logger pyrolite_meltsutil.automation (WARNING)>)

Batch of MeltsExperiment, which may represent evaluation over a grid of parameters or configurations.

Parameters:

• comp_df (pandas.DataFrame) – Dataframe of compositions.

• default_config (dict) – Dictionary of default parameters.

• config_grid (class:dict) – Dictionary of parameters to systematically vary.

• fromdir (str | pathlib.Path) – Directory to run the set of experiments from, and where the results of each of the experiments will be saved.

• env (str | pathlib.Path | pyrolite_meltsutil.env.MELTS_Env) – Environment file to use, if not the default.

• executable (str | pathlib.Path) – Path to an executable to use, if not the default (specifically the path to run_alphamelts.command or run_alphamelts.bat).

• timeout (int) – Timeout in seconds after which to try and terminate an experiment.

• logger (logging.Logger) – Logger to use for logging output, if not the default.

Variables:

• compositions (list of dict) – Compositions to use for the experiments.

• configs (list of dict) – Set of experiment configurations to use.

• experiments (list of dict) – Combination of compositions and configurations to generate a ‘grid’ of experiments.

Todo

• Can start with a single composition or multiple compositions in a dataframe

• Enable grid search for individual parameters

• Improved output logging/reporting

• Calculate relative number of calculations to be performed for the est duration

  This is currently about correct for an isobaric calcuation at 10 degree temperature steps over few hundred degrees - but won’t work for different T steps.

• Does number precision make a difference?

dump(experiments=None, to_dir=None)

Serialize the configuration to a json file.

Parameters:

• experiments (dict) – Dictionary of experiments to be serialized.

• to_dir (str | pathlib.Path) – Directory to export file to.

run(overwrite=False, exclude=[], superliquidus_start=True, timeout=None, log=False)

cleanup()

pyrolite_meltsutil.download

alphaMELTS download and installsation utilities.

pyrolite_meltsutil.download.extract_zip(zipfile, output_dir)

Extracts a zipfile without the uppermost folder.

Parameters:

• zipfile (zipfile object) – Zipfile object to extract.

• output_dir (str | Path) – Directory to extract files to.

pyrolite_meltsutil.download.download_melts(directory, version=None)

Download and extract melts zip file to a given directory.

Parameters:

• directory (str | pathlib.Path) – Directory into which to extract melts.

• version (str) – Which alphamelts version to use. Defaults to latest stable version.

Todo

• Check version, enable update-style overwrite

pyrolite_meltsutil.download.install_melts(install_dir=None, link_dir=None, eg_dir=None, native=True, temp_dir=PosixPath('/home/docs/temp/temp_melts'), keep_tempdir=False, with_readline=True, local=False, version=None)

Parameters:

• install_dir (str | pathlib.Path) – Directory into which to install melts executable.

• link_dir (str | pathlib.Path) – Directory into which to deposit melts links.

• eg_dir (str | pathlib.Path) – Directory into which to deposit melts examples.

• native (bool, True) – Whether to install using python (True) or the perl scripts (windows).

• temp_dir (str | pathlib.Path, $USER$/temp/temp_melts) – Temporary directory for melts file download and install.

• keep_tempdir (bool, False) – Whether to cache tempoary files and preserve the temporary directory.

• with_readline (bool, True) – Whether to also attempt to install with_readline.

• local (bool) – Whether to install a version of melts into an auxiliary pyrolite data folder. This will override

pyrolite_meltsutil.env

alphaMELTS environment managment.

pyrolite_meltsutil.env.output_formatter(value)

Output formatter for environment variable values.

Parameters:

value – Value to format.

Returns:

Formatted value.

Return type:

str

class pyrolite_meltsutil.env.MELTS_Env(prefix='ALPHAMELTS_', variable_model=None)

Melts environment object.

Todo

• Implement use as context manager.

export_default_env()

Parse any environment variables which are already set. Reset environment variables after substituting defaults for unset variables.

dump(unset_variables=True, prefix=False, cast=<function MELTS_Env.<lambda>>)

Export environment configuration to a dictionary.

Parameters:

• unset_variables (bool) – Whether to include variables which are currently unset.

• prefix (bool) – Whether to prefix environment variables (i.e with ALPHAMELTS_).

• cast (callable) – Function to cast environment variable values.

Returns:

Dictionary of environent variables and their values.

Return type:

dict

to_envfile(unset_variables=False)

Create a string representation equivalent to the alphamelts defualt environment file.

Parameters:

unset_variables (bool) – Whether to include unset variables in the output (commented out).

Returns:

String-representation of the environment which can be writen to a file.

Return type:

str

pyrolite_meltsutil.meltsfile

Utilities for reading and writing .melts files.

pyrolite_meltsutil.meltsfile.dict_to_meltsfile(d, linesep='\n', writetraces=True, modes=[], exclude=[], **kwargs)

Converts a dictionary to a MELTSfile text representation. It requires ‘title’ and ‘initial composition’ lines, major elements to be represented as oxides in Wt% and trace elements in µg/g.

Parameters:

• d (dict) – Dictionary to convert to a melts file.

• linesep (str) – Line separation character.

• writetraces (bool) – Whether to include traces in the output file.

• modes (list) – List of modes to use (e.g. ‘isobaric’, ‘fractionate solids’).

• exclude (list) – List of chemical components to exclude from the meltsfile.

Returns:

String representation of the meltsfile, which can be immediately written to a file object.

Return type:

str

Notes

• Some of the parameters are one-to-many, including modes, phase fractionation,

  supression and coexist-limits.

Todo

• Parameter validation.

pyrolite_meltsutil.meltsfile.ser_to_meltsfile(ser, linesep='\n', writetraces=True, modes=[], exclude=[], **kwargs)

Converts a series to a MELTSfile text representation. It requires ‘title’ and ‘initial composition’ lines, major elements to be represented as oxides in Wt% and trace elements in µg/g.

Parameters:

• ser (pandas.Series) – Series to convert to a melts file.

• linesep (str) – Line separation character.

• writetraces (bool) – Whether to include traces in the output file.

• modes (list) – List of modes to use (e.g. ‘isobaric’, ‘fractionate solids’).

• exclude (list) – List of chemical components to exclude from the meltsfile.

Returns:

String representation of the meltsfile, which can be immediately written to a file object.

Return type:

str

Todo

• Parameter validation.

pyrolite_meltsutil.meltsfile.df_to_meltsfiles(df, linesep='\n', **kwargs)

Creates a number of melts files from a dataframe.

Parameters:

• df (pandas.DataFrame) – Dataframe from which to take the rows and create melts files.

• linesep (str) – Line separation character.

Returns:

List of strings which can be written to file objects.

Return type:

list

pyrolite_meltsutil.meltsfile.from_meltsfile(filename)

Read from a meltsfile into a pandas.DataFrame.

Parameters:

filename (str | pathlib.Path | io.BytesIO) – Filename, filepath or bytes object to read from.

Returns:

Dataframe containing meltsfile parameters.

Return type:

pandas.DataFrame

pyrolite_meltsutil.parse

Parsing utilities for use with alphaMELTS.

pyrolite_meltsutil.parse.read_meltsfile(meltsfile, **kwargs)

Read in a melts file from a Series, Path or string.

Parameters:

meltsfile (pandas.Series | str | pathlib.Path) – Either a path to a valid melts file, a pandas.Series, or a multiline string representation of a melts file object.

Returns:

• file (str) – Multiline string representation of a meltsfile.

• path – Path to the original file, if it exists.

Notes

This function deconvolutes the possible ways in which one can pass either a meltsfile, or reference to a meltsfile.

pyrolite_meltsutil.parse.read_envfile(envfile, **kwargs)

Read in a environment file from a MELTS_Env, Path or string.

Parameters:

envfile (MELTS_Env | str | pathlib.Path) – Either a path to a valid environment file, a pandas.Series, or a multiline string representation of a environment file object.

Returns:

• file (str) – Multiline string representation of an environment file.

• path – Path to the original file, if it exists.

pyrolite_meltsutil.parse.from_melts_cstr(composition_str, formula=True)

Parses melts composition strings to dictionaries or formulae.

Parameters:

• composition_str (str) – Composition to parse.

• formula (bool) – Whether to output a periodictable.formula.Formula

Returns:

Dictionary containing components, or alternatively if formula = True, a Formula representation of the composition.

Return type:

dict | periodictable.formulas.Formula

Todo

• Enable parsing of nested brackets in composition.

pyrolite_meltsutil.tables

Utilities for reading alphaMELTS table outputs.

pyrolite_meltsutil.vis

Visualisation utilities for working with alphaMELTS table outputs.

Todo

• Pull out mineral compostional trends

pyrolite_meltsutil.util

Utility functions for pyrolite-meltsutil.