Post-entrapment crystallization (PEC) correction program documentation

Author: Victor Kress
Date: 12/12/04
Documentation revision: $Revision: 1.1 $ 
Software revision: 1.38

Executables built by: Paula Antoshechkina
Date: 07/05/2020

1. Introduction

This is the documentation file for software described in:

Kress, VC and Ghiorso, MS (2004) Thermodynamic modeling of pos-entrapment crystallization in igneous phases. Journal of Volcanology and Geothermal Research, 137:247-260.

Please consult the published reference for details on what the software does and how it works. This document only covers how to install and use the software.

[ Notes in brackets, like these, added for these 64-bit builds. Apart from updating the Supplemental Calculator link, the documentation has not been changed. -Paula Antoshechkina, 07/05/2020 ]

2. Installation

All versions of the PEC correction programs will be available via links from http://ctserver.ess.washington.edu. As of this writing versions are available for 32-bit linux and Mac OSX. In principle, it is possible to make a version for Microsoft operating systems, but minor differences in how Microsoft handles filenames, text files, ANSI c++ standard etc. would make maintenance of a separate of a windows branch a nightmare. Sorry.

[ Note: recent developments with the Windows Subsystem for Linux mean that is now possible to build a native Windows version, and that some problems (e.g. with line endings) are no longer an issue. ]

We eventually plan on offering this program as an online web-based graphical applet. For now we are only offering a text-based application. This has the advantage of being very portable, but you will need to learn to deal with a text shell under linux or OSX. Text shells should be second nature to most linux users, but this may be new for many Mac users. Under OSX, the text shell is called Terminal in the /Applications/Utilities/ folder. This is a very useful program. You should keep a link on your toolbar :).

[ Note: On Windows you should run cmd.exe. I recommend you do that by installing Windows Terminal from the Microsoft Store. ]

The linux application will be called textEntrapment.linux. At this point it is only compiled for 32 bit, but it would be trivial to compile 64-bit if there is sufficient demand. Download this file into the directory you plan to work in, or into a bin directory that is in the executable path.

[ Note: the file posted here is 64-bit, built on Ubutnu 18.04 LTS, but should work on other systems. In VM alphaMELTS a link has been set up in a bin directory in the exectuable path. ]

The Mac application is called textEntrapment.osx. As far as I know, it should run as is on any OSX machine, but please let me know if there are problems. As in the linux case, download this file into the directory you plan to work in, or into a bin directory that is in the executable path.

[ Note: the file posted here is 64-bit, built on Catalina, but should work on Mojave. ]

From this point on, both os's will work the same. For simplicity, I will assume you renamed textEntrapment.linux or textEntrapment.osx to textEntrapment. This is not necessary, but if you don't make the name change instructions below will have to be modified accordingly.

[ Note: Substitute "textEntrapment.exe" for "textEntrapment" in the next sections for Windows. Only run chmod on Mac/Linux; this has already been done for you in VM alphaMELTS, and the link set up means you do not need to rename the file. ]

You will have to run: chmod +x textEntrapment to make the file executable.

3. Running the program

At this point, you should be able to run the program. Note that if your system is set up for proper security, you can't run the program if it is in the current directory unless you precede it with a ./ (i.e. “./textEntrapment”). I won't go into why it is set up this way. Take my word for it, there is a good reason.

[ Note: You do not need the './' on Windows. In VM alphaMELTS you do not need the './' and you also do not need to be in the same directory as the textEntrapment executable. ]

textEntrapment can be run with either manual input or data from a properly formatted flat-text data file. I will cover manual input first and file formatting later.

3.1 Manual operation

When textEntrapment is run without arguments, it will prompt the user for all the information it needs to run.

You will first be prompt for the host crystal. Options at this point are olivine, clinopyroxene and orthopyroxene. For some reason we have failed to discover, clinopyroxene-hosted inclusions act very strange, with the low-Ca variety being excessively stable. Be particularly skeptical of results for inclusions in cpx. At the prompt, enter the integer value corresponding to the appropriate host phase.

You will next be prompted for temperature in C. It matters very little what you choose here, as temperature will be controlled primarily by the host saturation surface. This is mainly a seed value.

The next prompt is for final equilibration pressure in bars. This will generally be less than the pressure of the inclusion at the time of entrapment. See Kress and Ghiorso (2004) for explanation.

You will be prompted for the final oxygen fugacity in log10 units relative to the nickel- nickel oxide buffer assemblage.

The program will prompt for inclusion volume in cubic centimeters. In fact, this makes little difference in the result, but a reasonable guess keeps values scaled to a reasonable level. If you get strange number overflows, you might try varying this value.

Next you will be prompted whether you want host composition to be input in weight percent of mole fraction. Either should work, but for reasons that will be obvious in the next paragraph I feel safer with mole input.

You will then be prompted for each of the host phase components. This is using Ghiorso's MELTS components, so you will have to convert any components you use into these components. The best way to do this is using the Melts Supplemental Calculator (http://melts.ofm-research.org/calcForms.html). Don't be alarmed if this program gives you negative moles for some components (pyroxenes in particular). This is a mathematical artifact of the set of components Mark has chosen. textEntrapment expects compositions in these components, negative sign and all. When determining a composition to use here, chose an area of the crystal that is in about the right growth zone for the inclusion in question, but remote enough from the inclusion that PEC can not have affected analysis.

The next option is whether you want mole or weight input for the inclusion oxide composition. In this case, both mole and weight inputs are acceptable. This is the measured composition of the inclusion. You will be prompted for each oxide in turn.

Finally, you will be prompted for the mass fraction to be added in each PEC iteration. This is the fraction of inclusion mass that the program will re-add from the host crystal at each iteration as the program works its way backwards up the PEC path. Too small a value and the program will take a long time and may get lost in roundoff error. Too large a value and accuracy will be sacrificed. 0.001 is a good value to start with.

3.2 Operation from input file

To operate the program from an input file, simply use the file name as the first argument in the command line. Input files have the “.incl” extension. Two example files are included.

As you might expect, All information described in the manual input section above are required in the input file. The input file is a flat text ASCII file that can be edited with your favorite text editor. Do not use Word! There is little flexibility in the file format, it is probably wise to base your file on one of the example files.

4. Program Output

Once the program has all the information it needs, the first thing is will do is find the temperature at which the host phase is first saturated with respect to the input liquid composition at the specified pressure. The program will print this temperature and prompt for a target final temperature for iterations.

After the final temperature is input, iterations will proceed until the estimated temperature matches the input final temperature. With each iteration, the program outputs T(C),P(bar),delNNO,total fraction added, the difference in chemical potential for each component between the incremental host added and the bulk host, and a cumulative objective function.

It is up to you to judge the entrapment temperature on the basis of output data (see Kress and Ghiorso, 2004). If the delta-mu's don't cross 0 at roughly the same temperature, you might try adjusting the initial pressure or redox guesses and re-run. In principle, all delta-mu's should be zero at the entrapment temperature.

5. Questions or comments?

Contact the first author at kress@u.washington.edu

[ Problems with the new builds? Contact Paula at psmith@gps.caltech.edu ]