The Perple_**X**
programs BUILD, VERTEX, FRENDLY, MEEMUM, WERAMI and PSSECT look for a
computational option file. The file contains keywords that control output and
data processing options. This file is specified in the problem definition file
generated by BUILD and defaults to perplex_option.dat. If no computational option file is found,
then Perple_**X** uses the default settings for each
option.

Entries in the option file take the general form

keyword value1 value2 ....

where the keyword identifies an option and the associated values (e.g.,
**on,** **off** or a number) characterize the option. Comments may be placed
anywhere in the file provided they are preceded by a "|" character.

This page
documents the options. Perple_**X **
solution model and thermodynamic data files (e.g., solution_model.dat)
may also contain optional keywords that control how data is
treated. These keywords are partially documented here as well.

**
NOTE:** Perple_**X **
PostScript plotting programs (e.g., PSSECT, PSVDRAW, PSPTS,
PSTABLE) read an additional option file. The
second option file, named**
perplex_plot_option.dat, **specifies plot options,
see
** Perple_X
plot options **for details.

**NOTE:** **abbreviation** is a not a perplex_option
file
keyword, the abbreviation keyword is an option that applies to a specific
solution model. To implement this keyword modify the solution model by
adding the keyword and its value on a line after the solution model name.

The
**abbreviation** keyword specifies the abbreviation used by Perple_**X
**on output if solution_names
is set to **abb**[reviation]. The abbreviation must be < 7 characters, it
need not be unique to the solution model.

This keyword is only relevant for WERAMI, PSSECT, and MEEMUM.

Other keywords relevant to solution model names: solution_names,
full_name**.**

The
**Anderson-Gruneisen** keyword controls the parameterization of high pressure polythermal equations of state (Murnaghan, Birch-Murnaghan).

This keyword may take values: **T** (true) or **F **(false). The default is
**T**.

If
the keyword is **T** [true], then the temperature derivative of the bulk
modulus is computed as a function of the pressure derivative of the bulk modulus
and the expansivity at the reference pressure as described by Helffrich &
Connolly (2009). If the keyword is **F**, then
the temperature derivative of the bulk modulus is assumed to be an independent
model parameter.

The utility of this option it corrects a tendency of certain thermodynamic
formulations (notably Holland & Powell 1998) to generate unrealistic physical
properties. This correction is particularly important for seismic velocity
calculations, but has the unfortunate consequence that it may influence
calculated phase equilibria. A means of implementing this correction for
purposes of seismic velocity calculations without affecting computed phase
relations is to set
**Anderson-Gruneisen ** to
** F** for the calculation of phase equilibria in VERTEX
and subsequently set
**Anderson-Gruneisen **to** T** for the calculation of seismic velocities with
WERAMI. This method is not thermodynamically consistent, but the inconsistency
is unlikely to be of significance.

Other keywords relevant to seismic velocity calculations: vrh/hs_weighting,
bounds,
explicit_bulk_modulus,
poisson_ratio,
melt_is_fluid,
interpolation,
seismic_output**.**

The
**approx_alpha** keyword controls whether the approximation exp(x)-> 1+x is
used to evaluate volume at the reference pressure for phases described by EoS
choices (1-4).

This keyword may take values: **T** (true) or **F **(false). The default is
**T**.

If
the keyword is **T** [true], then the approximation

* V*(*T,P*_{r}) ≈ *V*(*T*_{r}*,P*_{r})·[1
+ integral(α(*T,P*_{r}),T=Tr..T)]

is used, otherwise the exact form

* V*(*T,P*_{r}) = *V*(*T*_{r}*,P*_{r})·exp[integral(α(*T,P*_{r}),T=Tr..T)]

is used. Although the approximate form is inaccurate at high temperature it has been assumed during the derivation of certain data bases (most notably that of Holland & Powell 1998), therefore the approximation should be used with such data bases to ensure consistency.

The
**aqueous_output** keyword controls whether back-calculated
aqueous speciation calculations are done by WERAMI and MEEMUM. The
speciation is output only if a recognized solvent phase is stable and data for
aqueous species is present in the thermodynamic data file used for the
calculation.

This keyword may take values: **T** (true) or **F **(false). The default is
**T**.

See also: aqueous_species, aq_solvent_composition, aq_solute_composition, lagged_aq_speciation

The
**aqueous_species** keyword controls the number of aqueous species, ranked by
abundance, output for back-calculated
aqueous speciation calculations done by MEEMUM and WERAMI (computational
mode 1). All aqueous species are output, without ranking, in WERAMI mode 2-4
calculations.

This keyword takes positive integer values. The default is **20**.

The
**aq_solute_composition** keyword controls whether the concentrations of
solute species in back-calculated
aqueous speciation calculations are output in molal units (mole/kg-solvent)
or as mole fractions.

This keyword may take values: **m** (molar) or **y **(mole fractions). The default is
**m**.

The
**aq_solvent_composition** keyword controls whether the concentrations of
solvent species in back-calculated
aqueous speciation calculations are output in molal units (mole/kg-solvent)
or as mole fractions.

This keyword may take values: **m** (molar) or **y **(mole fractions). The default is
**y**.

The **auto_refine**
keyword group controls whether VERTEX uses results from an "exploratory"
calculation to refine a subsequent recalculation of the same problem, i.e., an "auto-refined" calculation. The exploratory calculation is used to establish
the stable solution compositions.
This information is saved (even if auto_refine
is off) in a file named by concatenating the project name with the "arf"
file type suffix. For example, if the project
is named **in**, VERTEX generates a file named **in.arf** and,
if the **option_list_files** keyword is **T**, a
legible version named **in_auto_refine.txt**.

In the auto-refine stage of a calculation, VERTEX:

1) Eliminates solutions that were not stable in the exploratory calculation.

2) Restricts compositional ranges of solutions to the ranges established in the exploratory calculation.

3) Increases resolution of compositions within these restricted ranges (

auto_refine_factor_I, auto_refine_factor_II, orauto_refine_factor_IIIdepending on the type of calculation).

4) Changes mapping parameters for gridded minimization and phase fractionation calculations or changes variance and search increment specifications for Schreinemakers and mixed-variable diagram calculations.

The **auto_refine**
keyword group consists of four keywords, each of which is associated with one
value:

auto_refinemay beoff,man, oraut;the default isman. Ifauto_refine=man, VERTEX must be run independently for the exploratory and auto-refine stages of a calculation. This manual mode allows users to examine results from the exploratory stage before undertaking the more time intensive auto-refine stage. Ifauto_refine=aut, VERTEX automatically does both the exploratory and auto-refine stages in a single run.

auto_refine_factor_Iis an integer > 0; the default is 2. This factor determines the increase in compositional resolution (point 3 above) between the exploratory and auto-refinement stages of adaptive minimization (i.e., gridded minimization and phase fractionation) calculations with VERTEX or MEEMUM, i.e., the final resolution is as described for the iteration parameter.

auto_refine_factor_IIis an integer > 0; the default is 10. This factor is the increase in compositional resolution (point 3 above) between the exploratory and auto-refinement stages for mixed-variable and composition diagram calculations with VERTEX, i.e., the final resolution is initial_resolution/auto_refine_factor_II.

auto_refine_factor_IIIis an integer > 0; the default is 3. This factor is the increase in compositional resolution (point 3 above) between the exploratory and auto-refinement stages for Schreinemakers diagram calculations with VERTEX, i.e., the final resolution is initial_resolution/auto_refine_factor_III.

Excessive values of the

auto_refine_factorcauseerror ver041during the auto-refine stage of calculations with VERTEX.

These keywords are only relevant for VERTEX.

The **auto_refine_file** controls whether the range of solution compositions
discovered during an auto_refine calculation are output to a text file. If **
auto_refine_file = T**, then the file is output and named
my_project_auto_refine.txt, where my_project is the project name.

This keyword may take values: **T** (true) or **F **(false). The default is
**F**.

This keyword affects VERTEX.

The bad_number keyword determines the value assigned to missing data or bad numerical results (usually caused by floating point errors). Depending on the physical property of interest it may be useful to change this value so that bad results can be distinguished during post-processing (e.g., if seismic velocities are of interest, assigning a negative bad_number allows identification of erroneous velocities).

As of Perple_**X**
revision 6.6.5.9, bad_number may be set to **NaN** (not-a-number). The
advantage of setting bad_number to NaN is that advanced plotting programs such
as MatLab and, to a certain extent, PyWerami (i.e., in contour mode) treat NaNs
correctly as missing data. For example, if phase
composition is contoured as a function of pressure and temperature with bad_number set to NaN,
then the data will be only contoured where the phase is stable.
In contrast, if bad_number is set to zero, zeroes will be reported for the
composition wherever the phase is not stable; the zero
values (usually) imply a range of composition that is much greater than the true
range and consequently the default contour interval chosen by a contouring
program will not resolve the data well. The Perple_**X**
contour plot program PSTABLE is not capable of treating missing data and
replaces NaNs with zeroes; thus there is no advantage to setting bad_number to
NaN unless the data is to be processed with MatLab or PyWerami.

This keyword takes numeric values or **NaN** (< 12 characters), 0 is the default
value.

This keyword affects WERAMI, FRENDLY and VERTEX.

Because the time scale for seismic
wave propagation is short compared to the time scales for thermal and chemical
equilibration, the elastic moduli (i.e., adiabatic bulk and shear moduli)
relevant for the calculation of seismic wave speeds are not identical to the
isostatic (Voigt) limit assumed for thermodynamic calculations. In the absence
of detailed textural information, the moduli are estimated as the weighted
average of upper and lower bounds on the moduli. Two methods for the
estimation of these bounds are the Hashin-Shtrikman (HS) and Voigt-Reuss-Hill (VRH)
methods (Berryman,
AGU Handbook of Physical Constants, 1995). The value of the **bounds**
keyword (**HS** or **VRH**) determines method is used.
HS bounds are narrower than the VRH bounds and are theoretically justified;
thus, they are to be preferred. Despite this advantage, the VRH bound is more
widely used in geoscience, presumably because it is simpler to compute.

If **bounds = VRH**, the lower
bound *Z*_{-} (i.e., Reuss limit) on the modulus *Z* of an
aggregate is the harmonic mean of the corresponding moduli of its *p*
constituent phases

*Z*_{-} = 1/[sum(*x*_{i}/*Z*_{i},i=1..*p*)],
[1]

where *x*_{i} is the
volume fraction of phase i; and the upper bound *Z*_{+} (i.e.,
Voigt limit) is the arithmetic mean

*Z*_{+} = sum(*x*_{i}**Z*_{i},i=1..*p*).
[2]

If **bounds = HS**, the lower and
upper bounds *Z*_{-/+} are

*Z*_{-/+} = 1/[sum(*x*_{i}/[*Z*_{i}-*Y*_{-/+}],i=1..*p*)].
[3]

In Equation 3: for the adiabatic shear modulus μ

*Y*_{-/+} = 4/3 μ_{min/max},
[4]

where μ_{min} and μ_{max}
are, respectively, the minimum and maximum shear moduli of the constituent phases;
and for the
adiabatic bulk modulus *K*

*Y*_{-/+} = μ_{min/max}([9*K*_{min/max}+8μ_{min/max}]/[*K*_{min/max}+2μ_{min/max}])/6.
[5]

In Equations 3-5, the lower bound *Z*_{-}
is computed with *Y*_{-},* K*_{min}* *and* *
μ_{min}; whereas the upper bound *Z*_{+} is computed with
*Y*_{+},* K*_{max}* *and* *μ_{max}.

For either value of **bounds**, the
aggregate modulus is

*Z* = (1-χ)**Z*_{-} + χ**Z*_{+},
[6]

where the weighting factor χ is specified by the vrh/hs_weighting keyword.

By
default **bounds** = **VRH**.

This option affects WERAMI, MEEMUM and FRENDLY. For calculations analyzed with WERAMI, changing this keyword does not necessitate repeating the primary calculation with VERTEX.

Other keywords relevant to seismic velocity calculations: vrh/hs_weighting,
explicit_bulk_modulus,
poisson_ratio,
Anderson-Gruneisen,
melt_is_fluid,
interpolation,
seismic_output**.**

The **closed_c_space** keyword controls whether compositional variables for
gridded minimization calculations define a closed or open composition space. In
gridded minimization calculations as a function of *k* compositional
variables *X*(*C*_{1})...*X*(*C _{k}*), the
user specifies

C= sum{X(C)*_{i}C,_{i}i=1...k} +C_{0}*[1-sum{X(C),_{i}i=1...k}],

whereas if **closed_c_space** = **F**, then

C= sum{X(C)*_{i}C,_{i}i=1...k} +C_{0}.

This keyword may take values: **T** (true) or **F **(false). The default is **
T**.

This keyword is only affects VERTEX.

The **composition_constant** keyword controls whether the terms in user
defined phase compositions may include a constant.

This keyword may take values: **T** (true) or **F **(false). The default is
**F**.

This option only affects WERAMI.

See also: composition_phase, composition_system, proportions

The **composition_phase** keyword controls whether phase compositions are output in
molar units or as weight fractions (percentage).

This keyword may take values: **wt**, **mol**. The default is **mol**.

This option only affects WERAMI.

See also: composition_constant, composition_system, proportions

The **composition_system** keyword controls whether the amounts of a systems
components are output in
molar units or as weight fractions (percentage).

This keyword may take values: **wt**, **mol**. The default is **wt**.

This option only affects WERAMI.

See also: composition_constant, composition_phase, proportions

The **
console_messages**
keyword controls whether messages to the user console are output (provided a
print file is requested) during Schreinemakers and mixed variable diagram
calculations.

This keyword may take values:
**on**, **off**. The default is **on**.

This keyword affects VERTEX.

If the **cumulative_modes** keyword is set to **on**, then cumulative
phase modes (by volume or weight as determined by the **
proportions** keyword) are output if the "modes of all phases" property is selected
in WERAMI. Given a list of phases, the cumulative mode of a phase is the
mode of the phase plus the modes of all the phases that precede it in the list.
This form of output is useful for constructing diagrams in which the variation
in the proportions of the phases are plotted as a function of a third variable,
e.g., pressure along a geotherm (see
Example #24).

This keyword may take values:
**on**, **off**. The default is **off**.

**NOTE:** As of 12/20/08 keyword is no longer
read from the computational option file, rather it is set interactively if the
"modes of all phases" property is selected in WERAMI.

The **
dependent_potentials** keyword controls whether dependent chemical potentials
are output when chemographic data is output (provided a print file is requested)
during non-adaptive minimization calculations. In adaptive minimization
calculations the dependent potentials are output to my_project.plt and can be analyzed with WERAMI.

**WARNING:**
the VERTEX output file format depends on the dependent_potential keyword value,
consequently output generated by the VERTEX with the keyword set to off cannot
be read by WERAMI or PSSECT if the keyword is changed to on, and vice versa.
There is no check for the consistency of the keyword value between programs,
thus any inconsistency will cause a "hard" crash (I/O errors).

This keyword may take values:
**on**, **off**. The default is **off**.

The **efficiency**
keyword specifies the level of redundant testing done during Schreinemakers
diagram calculations.

This keyword takes
integer values **1**->**5**, the default is **3**. High values increase
computational efficiency, but also increase the probability that a [pseudo-]univariant
curve may be skipped or incompletely traced.

This keyword affects VERTEX.

The adiabatic bulk modulus *
K*_{S}(*T,P*) is an implicit function of the Gibbs energy
used to compute phase equilibria
(Equation 4 of Connolly &
Kerrick 2002). By default, Perple_**X**
exploits this dependence to compute *
K*_{S}(*T,P*). This method has the virtue that the modulus is consistent
with the equation of state used to compute phase relations. The importance of
this consistency for seismic velocity calculations is debatable because phase
relations depend directly on the Gibbs energy, whereas *
K*_{S}(*T,P*) is dependent primarily on second order
derivatives of the Gibbs energy. Thus, it can be argued that empirically calibrated expressions for *
K*_{S}(*T,P*) are more accurate than the values obtained
from an EoS intended only for phase equilibrium calculations (e.g., Holland &
Powell 1998). To accommodate this case, the **explicit_bulk_modulus** keyword
permits the use of empirical expressions for *
K*_{S}(*T,P*).

If **explicit_bulk_modulus** = **T** (true), *
K*_{S}(*T,P*) of any pure phase or endmember is computed
from the expression

*
K*_{S}(*T,P*) = k0 + k1·(*T*-*T*_{r})
+ k2·(*P*-*P*_{r})

provided that the parameters {k0, k1, k2} are
specified for the phase in
the thermodynamic data file. If **explicit_bulk_modulus** = **T** (true),*
K*_{S}(*T,P*) for a solution phase is computed as the
volumetrically weighted mean of the endmember properties provided the parameters
{k0, k1, k2}. Under any other circumstances *
K*_{S}(*T,P*) is computed by differentiation of the Gibbs
energy function for the phase.

This keyword takes the character values **T**
or **F**. The default value is **F**.

This option affects WERAMI, MEEMUM and FRENDLY. For calculations analyzed with WERAMI, changing this keyword does not necessitate repeating the primary calculation done by VERTEX.

Other keywords relevant to seismic velocity calculations: vrh/hs_weighting,
bounds, poisson_ratio, Anderson-Gruneisen,
melt_is_fluid,
interpolation, seismic_output**.**

The **extrapolation** keyword is only relevant for gridded minimization and
has no effect unless **interpolation** (see
below) is also **on**.

This keyword may take values: **on**, **off. **The default is **on.**

This option only affects WERAMI, extrapolation may cause floating point errors
in Perple_**X** 07.

The
**fd_expansion_factor** keyword is the factor by which the finite difference
increment used to compute high order derivatives increases with order. These
derivatives are used in Perple_**X** to compute
physical properties during post-processing.

This keyword takes a real value. The default value is 2.

If
the first order finite difference increment for a variable is **dv1**, then
the increment used to compute nth order finite difference increment **dvn** =
**dv1** * **fd_expansion_factor**^(n-1).

See finite_difference_p for related information.

This keyword affects WERAMI, FRENDLY, and MEEMUM.

The **final_resolution** keyword determines the (molar) precision with which
phase compositions are calculated during adaptive minimization (Connolly 2009).
Because resolution is discretized in Perple_**X**,
the effective final resolution of adaptive minimization calculations is
determined by finding the minimum number of iterations that yield precision
below final_resolution. The effective final resolution is computed as outlined
in the iteration keyword description. See Example
1 of the adaptive
minimization keyword group discussion for additional information on the
effect of this keyword.

The **
final_resolution** keyword takes two values between 0 and 1. The first value
applies during the exploratory stage of auto-refined calculations and the second
value applies in the final (auto-refined) stage of the calculation. If only one
value is present it is applied for both stages, if the keyword is absent the
default targets for the final resolution in the exploratory and auto-refine
stages are 2e-2 and 2e-4 (mol), respectively. If final_resolution > initial_resolution, then there is no iterative
refinement of phase compositions and the effective resolution is determined by
the initial_resolution keyword.

The
value of final_resolution does not affect memory consumption, but small values
may significantly increase computational time. The minimum value of is limited
by the conditions at which the requested resolution causes numerical instability
(i.e., **warning ver058**, failed optimizations). These conditions depend on many factors, but, as a
rule of thumb, on 32-bit machines final_resolution should not be << 10^{-4}
mol.

This keyword affects VERTEX and MEEMUM.

See also: iteration, reach_increment, initial_resolution, output_iteration_G, adaptive minimization keyword group discussion.

The
**finite_difference_p** keyword controls the magnitude of the finite
difference increment on pressure for first order derivatives. These derivatives
are used in Perple_**X** to compute physical
properties during post-processing.

The
keyword takes two real values, **threshold** and **fraction**. The default
value for **threshold** is 10000 and that of **fraction** is 0.01.

If
the pressure for a calculation is greater than **threshold** then the
pressure increment dp1 = pressure * **fraction**, otherwise the pressure
increment is dp1 = **threshold *** **fraction. **

See fd_expansion_factor for related information.

This keyword affects WERAMI, FRENDLY, and MEEMUM.

**NOTE:**
**full_name** is a not a perplex_option file keyword, the full_name keyword is an option that applies to a specific
solution model. To implement this keyword modify the solution model by
adding the full_name keyword and its value on a line after the solution model
name.

The
**full_name** keyword specifies the full name used by Perple_**X
**on output if solution_names
is set to **ful**[l]. The full_name must be < 23 characters, it need not be
unique to the solution model. The full_name tag is also used by BUILD to group
solution models, e.g., to have BUILD group all orthopyroxene models together
after the solution model prompt, all orthopyroxene models should be given the
same full_name, e.g., 'orthopyroxene'.

This keyword affects BUILD, WERAMI, PSSECT, and MEEMUM.

Other keywords relevant to solution model names: solution_names,
abbreviation**.**

The
**
global_reach_increment** specifies an incremental increase in the range over which
the compositional variables of solutions are allowed to vary between successive
iterations during adaptive minimization.

Experience suggests that except for immiscible solution models there is no benefit to increasing this range beyond the default (see iteration, eq [1]) and because such an increase is costly in terms of memory, it is preferable to apply such increases only for specific solution models via the solution model file reach_increment keyword. If global_reach_increment > reach_increment, its value overrides reach_increment, otherwise the value of reach_increment is retained.

See reach_increment for further details.

This keyword affects VERTEX and MEEMUM.

See also: final_resolution, reach_increment, initial_resolution, solvus_tolerance, adaptive minimization keyword group discussion.

For gridded minimization VERTEX uses a multilevel grid refinement strategy in
which phase relations are mapped on an initial grid of resolution **x_nodes**
* **y_nodes**. This grid is refined **grid_levels** **- 1** times by
bisection (Connolly 2005). The **x_nodes**, **y_nodes**, **grid_levels
**parameters are set by keywords of the same name. Each keyword takes two
integer values. The first value is used for the exploratory stage of gridded
minimization calculations, while the second value is used for the **
auto-refine** stage. The effective resolution
of a multilevel grid is equivalent to a single grid with (x_nodes - 1) * 2**(grid_levels
- 1) + 1 in the x-direction and (y_nodes - 1) * 2**(grid_levels - 1) + 1 nodes
in the y-direction.

The danger of using low values for **x_nodes** and **y_nodes** and a high
number of **grid_levels** is that a
small phase field that protrudes into a larger phase field will not be
identified if the protrusion occurs between two nodes of the low resolution grid
at which the larger field is stable. There is no simple rule for the best
choices for **x_nodes** or **y_nodes** as they depend on the scale of the
diagram and the heterogeneity of its phase fields, the default values are 20 and
40 for exploratory and auto-refinement stages of a calculation. The default
values of **grid_levels** are 1 and 4 for exploratory and auto-refinement
stages.

**y_nodes** is used for 1-d gridded minimization calculations.

For 1-d phase fractionation calculations the **1d_path** keyword indicates
the number of nodes taken to define the path in the exploratory and auto-refine
stages of the calculation. The default values for 1d_path are 20 and 150 for the
exploratory and auto-refinement stages of a phase fractionation calculation. As
a rule of thumb, the latter value should be chosen such that the results do not
change significantly if it is varied by a factor of two.

This keyword affects VERTEX.

If the **hard_limits** keyword is set to **off**, then unnatural
composition limits (i.e., X < 1 or X > 0) specified in the solution model file
(e.g., solut_07.dat) may be relaxed during adaptive minimization calculations. This
behavior permits users to specify restricted compositional ranges for complex
(costly) models, yet allows VERTEX to learn new limits in the course of a
calculation. **hard_limits** should be set to **on** if a solution model
is duplicated in the solution model file in order to represent distinct
compositional ranges of the solution. For example, if a model for Na-K mica is
duplicated to distinguish Na- and K-rich micas. In this case it is conceivable
that if calculations were done under conditions where the mica is fully
miscible, VERTEX might expand the composition limit of Na-rich mica into the
range of K-rich mica, or vice versa, resulting in confusing output.

This keyword may take values:
**on**, **off**. The default is **off**.

This keyword affects VERTEX and MEEMUM.

The
**hybrid_EoS_XXX** keyword, where **XXX** may be **H2O**, **CO2**,
or **CH4**, determines the internal molecular fluid equation of state to be
associated with a pure XXX species fluid. The keyword may take integer values:

0 - MRK, Modified Redlich-Kwong EoS, DeSantis et al. 1974

1 - HSMRK, Kerrick & Jacobs 1981

2 - CORK, Holland & Powell 1998, valid only for H2O and CO2

3 - BRMRK, Bottinga & Richet 1981, valid only for CO2

4 - PSEoS, PSEoS Pitzer & Sterner 1994, valid only for H2O and CO2

5 - Steam Table EoS, Haar et al 1982 valid only for H2O

The
default values for **hybrid_EoS_H2O**, **hybrid_EoS_CO2**, and **hybrid_EoS_CH4**
are 4, 4, and 1, respectively.

The increment keyword specifies the default search/trace variable increments for Schreinemakers and mixed-variable diagram calculations. Two values are specified, these are applied, respectively, for the exploratory and autorefine stages of calculation. The values of increment are relative, absolute increments are computed by mutliplying the increment value by the variable range.

This keyword affects VERTEX.

The **initial_resolution** keyword determines the default (molar) compositional
resolution used for solution models. If initial_resolution is greater than zero,
its value over-rides the resolutions specified for individual phases in the
solution model file. For the adaptive minimization calculations (calculations
with MEEMUM or gridded minimization and phase fractionation calculations in
VERTEX) the effective initial resolution (d0) is initial_resolution/auto_refine_factor_I.
and the final precision is specified by the final_resolution
keyword. For unconstrained minimization calculations (calculations of
composition, Schreinemakers and
mixed-variable diagrams in VERTEX), initial_resolution is the effective initial
resolution and the final resolution is **initial_resolution**/auto_refine_factor.

Fine
**
initial_resolution** (i.e., small values) generally improves accuracy, but is
costly in terms of both memory and computer time. The diagnostic ****error ver041****
during the exploratory stage of a calculation in VERTEX indicates that **initial_resolution** is
too small. It is usually preferable to
improve accuracy by adjusting the iteration (*i*_{1})
and reach_increment
keywords rather than by adjusting initial_resolution.

This keyword may take values between 0 and 1 and may be specified as an integer
fraction (e.g., 1/15) or real number. If ** initial_resolution** = 0,
then Perple_**X** will use the resolutions
specified in the solution model file. Optimally, **initial_resolution**
should be specified as an integer fraction of 1. other choices lead to
asymmetric resolution with a widow composition near one that can be costly in
calculations involving complex solution models. Experience suggests that the optimal values for ** initial_resolution** (with
auto refine on) are between 1/20 and 1/5.

This keyword affects VERTEX and MEEMUM.

The iteration keyword takes two values, ** i_{1}** and

*d*_{0} = initial resolution
/ auto_refine_factor_I.

The specific resolution formulae given below assume Cartesian subdivision.

In iteration *n *of an adaptive minimization, the compositional variable of a
phase is allowed to vary discretely over the range ±*r* around the
estimated composition *x*_{n-1}. The first value of the iteration keyword ** i_{1}**,
in combination with

and the actual resolution of the discretization

* *
*d*_{n} = 2*r*_{min}/*i*_{1}.
[2]

For a
calculation with a single, miscible, solution phase, at iteration *n*-1, a composition of
the solution phase *x*_{n-1} is determined with precision ±d_{n}_{-1}.
Thus at iteration *n*, the refined composition *x _{n}*
will lie within the interval

*
r _{n} * =

The number of discretization points for the compositional variable is then

*
p * = 1+*i*_{1}(2+reach_increment)/4
[4]

Large values of *i*_{1} increase the time and memory required for
each iteration, but because the rate at which resolution increases with each
iteration also improves with *i*_{1}, fewer
iterations are required to achieve the target precision (final_resolution).
Calculations done with larger values of *i*_{1} are slightly more
precise. *i*_{1} must be an integer
> 1, its default value is 3, experience suggests that this value is usually optimal.
Changing the value of *i*_{1} to *i*_{1}' changes the
total number of compositions evaluated by a factor of roughly as (*i*_{1}/*i*_{1}')* ^{c}*;
for a nine component solution this implies reducing

The
second value of the iteration keyword ** i_{2}**
is the number of
metastable phase compositions to be refined during the first iteration of an adaptive minimization, its default is
4 (the number of refined metastable compositions for subsequent iterations is
set by refinement_points_II). The retention of metastable phase compositions is important
because in the vicinity of a phase boundary the small changes in compositions
caused by iteration may affect the perceived phase stabilities. Thus,

This keyword affects VERTEX and MEEMUM.

See also: final_resolution, reach_increment, initial_resolution, auto_refine_factor_I, refinement_points_II, output_iteration_G, solvus_tolerance, adaptive minimization keyword group discussion.

The **interpolation**
keyword is only relevant for gridded minimization and is currently only used for
mode 2 calculations (sampling on a grid) in WERAMI.

**
WARNING:** turning interpolation **"on"** slows data processing.

The interpolation
keyword takes 2 values, **value1** and **value2**

value1isonoroff, the default ison

value2is an integer, the default is2

When **value1** is
on WERAMI
computes physical properties by interpolation/extrapolation of the properties of
an assemblage at a sampling point by linear interpolation and/or extrapolation
from the 3 closest grid nodes of the computational grid at which this assemblage is known to be
stable. For this purpose WERAMI uses an algorithm that tries
to locate 3 nodes bounding the sampling point, when this not possible
extrapolation is used if the **extrapolation** keyword value is on.
Figure 1 illustrates some consequences of interpolation
and/or extrapolation. The primary danger of interpolation as currently
implemented (i.e., this will change) is that it may homogenize nodes that
represent 2 or more compositions of a phase separated by a solvus.

**Value2**
specifies the the range of nodes around the sampling point searched with the
triangulation algorithm. For a multilevel grid with JLEV levels, the number of
nodes on around the sampling point is **value2***(2**(JLEV-1)).
Figure 2
illustrates the effect of increasing **value2**, **value2** = 0 is
equivalent to turning interpolation off, small values increase the probability
that WERAMI cannot find bounding interpolation points (in which case no
interpolation done around the sample point), whereas large values reduce the
accuracy of linear interpolation.

Figure 1. Water content of mineral+melt (i.e., excluding free water) assemblages for a calculation as a function of temperature (T) and the compositional variable X(C2) which represents the bulk water content of the system (from 0 to 5 wt%). The calculation was done on a low resolution (single level 20x20) grid, for plotting purposes this grid was sampled on a 50x50 grid with WERAMI. At high temperature all H2O component is dissolved in the melt phase and therefore the water content of the mineral+melt assemblage should vary linearly from 0 to 5 wt % as a function of X(C2), this is not the case if interpolation is turned off (first plot, "

interpolation off") because the water content of the system is identified with discrete nodes of the grid. The advantage of viewing the data with interpolation off is that it provides an unambiguous picture of the raw data. Continued...

If interpolation is turned on, and extrapolation turned off (second plot, "

interpolation on 2" and "extrapolation off"), the plot is smoothed, but discontinuities persist where WERAMI was unable to obtain identify three grid points representing the phase assemblage bounding the sampling points. Continued...

If both interpolation and extrapolation are on (third plot, "

interpolation on 2" and "extrapolation on") the required smooth variation in water content at low temperature is obtained, although artificial plateaus persist where a particular phase assemblage is stable only at one node (e.g. at T~1050 K, X(C2)~0.6) or along a one-dimensional path (e.g., T<950 K, X(C2)~0.2). A disadvantage of allowing extrapolation, particularly in the case of sections with compositional variables, is that physically unrealistic values can be obtained, as at T~950 K, X(C2)~1 where the water content depicted is greater than the maximum possible for the system. The undesirable artifacts of extrapolation and interpolation depicted here become less significant and less frequent as resolution of the grid is increased.

Figure 2. Plots of bulk density for a high pressure phase transformation as a function of interpolation range (

value2), the calculation was done in VERTEX on a 4 level grid (JLEV=4) with 20x20 nodes at the lowest level of resolution and refinement of only true phase boundaries (the default grid refinement mode). The data was sampled on a 150x150 grid in WERAMI to create the plots. All plots were made with both interpolation and extrapolationon. The first plot shows results obtained forvalue2=0 (equivalent to "interpolation off") in which the underlying structure of the multilevel grid is clearly visible. Continued...

The second plot shows results obtained for

value2=1, for JLEV=4 a unit increment invalue2corresponds to 8 grid nodes at the highest level of the computational grid. Continued...

The third plot shows results obtained for

value2=2 (the default value), with this choice the continuous variation in density is reasonably well represented. Although the surface appears eroded in places, probably a result of extrapolation. Continued...

The fourth plot shows results obtained for

value2=3, here the relatively long interpolation/extrapolation distances cause undesirable artifacts.

This keyword affects WERAMI.

The
**lagged_aq_speciation** keyword controls whether lagged
aqueous speciation calculations are done by WERAMI and MEEMUM. The
speciation is output only if a recognized solvent phase is stable and data for
aqueous species is present in the thermodynamic data file used for the
calculation.

This keyword may take values: **T** (true) or **F **(false). The default is
**T**.

See also: aq_solvent_composition, aq_solute_composition, output_iteration_G, species_output

If the **linear_model** keyword is **
on** phase boundaries are assumed to be linear between grid nodes at the
active level and next sublevel of a multilevel grid during gridded minimization
calculations. This assumption, which was used
in the original gridded minimization strategy (Connolly 2005), results in a reduction in
the number of calculations because it implies that if the same assemblage is
present at two adjacent nodes at the current level of resolution, then the
assemblage must also be present at the intervening node at the next sublevel.
The assumption is not rigorous and may result in step-like boundaries, a problem
that can be avoided by setting the keyword value to **off**. When **
linear_model** is **off**, the multilevel gridding strategy
is identical to the wavelet strategy described by Gerya et al. (EPSL, 2004). For
2-dimensional grids, setting **linear_model** to **off** increases
computation time and output file size roughly twofold.

This keyword affects VERTEX.

The
**logarithmic_p** keyword controls whether the nominal value of the pressure
variable is interpreted as pressure or its base 10 log. If **logarithmic_p** is
**T**, the thermodynamic pressure for calculations is computed as log_{10}*P*;
thus for a calculation with pressures ranging from 10^{-5} to 10^{2}
bar, the user enters values of -5 and 2 for the minimum and maximum pressure.
Note that if **logarithmic_p** is **T **is true, the Perple_**X**
variable name is unchanged, i.e., the program prompts for a variable named *P*,
but interprets it as log_{10}*P*.

This keyword may take values: **T** (true) or **F **(false). The default is
**F**.

This keyword affects WERAMI, MEEMUM, and gridded minimization calculations in VERTEX.

The
**melt_is_fluid** keyword controls whether WERAMI considers silicate melts to
be fluids on output. If **melt_is_fluid** is **F**, then properties for
the "solid" aggregate inlcude melts.

This keyword may take values: **T** (true) or **F **(false). The default is
**F**.

This keyword affects WERAMI and MEEMUM.

The **option_list_files** controls whether VERTEX, MEEMUM and WERAMI output a
text file that summarizes the option settings relevant for a calculation. If **
option_list_files = T**, then files are output and named
my_project_PROGRAM_options.txt, where "my_project" is the project name and
PROGRAM is the name of the relevant program.

This keyword may take values: **T** (true) or **F **(false). The default is
**F**.

This keyword affects VERTEX, MEEMUM and WERAMI.

The isobaric-isothermal Gibbs energy of a solution model with non-convergent
ordering may have several minima as a function of the model order parameters.
These minima correspond to different equilibrium ordering states, the stable
state being that with the lowest Gibbs energy. For such models, Perple_**X**
is programmed to seek the minima corresponding to the most ordered state. If **order_check**
is **on**, the energy of this state is compared to the fully disordered
state, and the lowest energy is used for calculations. Under most conditions,
this strategy
gives the stable state of ordering for all conditions with a single solution
model, but it has the disadvantage that the discontinuous transition between
partially ordered and completely disordered phases (e.g., the tri-critical
curve) is not shown explicitly. If **order_check** is **off**, the phase
is always assigned the energy of the maximum order state; therefore in calculations
were an order-disorder model and its fully disordered equivalent are both
present (e.g., omphacite and clinopyroxene), Perple_**X**
will explicitly delineate discontinuous order-disorder transitions.

If you do not understand the foregoing paragraph, then use the following rules:

1) If **order_check** = **on** and the calculation includes an
order-disorder model, then it should **NOT** include the fully disordered
equivalent (i.e., a calculation including omphacite, should **NOT** include
clinopyroxene).

2) If **order_check** is **off** and the calculation includes an
order-disorder model, then it **SHOULD** include the fully disordered
equivalent (i.e., a calculation including omphacite, should include
clinopyroxene).

This keyword affects VERTEX, WERAMI, and MEEMUM.

If **output_iteration_G** is true (**T**), then MEEMUM and VERTEX write
the free energy of the system (per mole of the systems components) and the
chemical potentials of its components after each iteration of adaptive
minimization calculations. This output provides diagnostic information on
the quality of minimization results and resolution precision.

Specifically:

1) The total free energy should converge smoothly to a minimum, increasing the number of iterations (e.g., by decreasing final_resolution) beyond this minimum does not improve the quality of the minimization.

2) Oscillation or increasing total free energy during iteration is an indication of a poor choice of optimization parameters (e.g., over-refinement).

3) If the free energies of the possible phases of the system are taken to be perfectly known, then the magnitude of a significant change in the total free energy of the system is comparable to the round-off error on the reference state Gibbs energies. Typical round-off error is ~100 J/mol. In general, the true error on reference state Gibbs energies is ~1000-10000 J/mol.

4) The precision of minimization may improve significantly even if the improvement in the total free energy of the solution is insignificant. This precision can be judged by comparing the variation in the chemical potentials during iteration to the precision of the data. Chemical potential variations can also be used to identify well- or poorly-resolved components.

To illustrate by example, the following output was generated from the bl478_benchmark, at 1050.15 K and 4000 bar, by increasing final_resolution to 1e-8 mole:

Iteration G(J/mol) H2O MgO Al2O3 K2O CaO TiO2 FeO O2 Na2O SiO2 0 -926202.1570 -390238 -688844 -1794082 -956488 -804320 -1030145 -369515 -512236 -872061 -977953 1 -926270.5179 -391218 -689244 -1794209 -956888 -804224 -1030236 -369536 -511872 -871984 -977953 2 -926284.1030 -390927 -689271 -1794410 -963451 -804091 -1029920 -369108 -525225 -871658 -977953 3 -926288.8551 -391376 -689223 -1794364 -956204 -804244 -1030109 -369072 -522614 -871797 -977953 4 -926289.1760 -391263 -689187 -1794402 -958435 -804194 -1030001 -369150 -522853 -871746 -977953 5 -926289.2590 -391231 -689123 -1794436 -958964 -804152 -1029899 -369190 -523849 -871721 -977953 6 -926289.2753 -391253 -689107 -1794437 -958629 -804150 -1029890 -369180 -524257 -871728 -977953 7 -926289.2797 -391256 -689108 -1794437 -958608 -804151 -1029893 -369179 -524208 -871726 -977953 8 -926289.2811 -391255 -689109 -1794437 -958620 -804152 -1029894 -369179 -524190 -871726 -977953 9 -926289.2816 -391255 -689108 -1794437 -958620 -804151 -1029893 -369179 -524204 -871726 -977953 10 -926289.2817 -391255 -689108 -1794437 -958620 -804152 -1029893 -369179 -524207 -871726 -977953 11 -926289.2818 -391255 -689108 -1794437 -958620 -804152 -1029893 -369179 -524204 -871727 -977953 12 -926289.2818 -391255 -689108 -1794437 -958619 -804152 -1029893 -369179 -524207 -871727 -977953 13 -926289.2818 -391255 -689109 -1794437 -958620 -804152 -1029893 -369179 -524204 -871727 -977953 14 -926289.2818 -391255 -689109 -1794437 -958621 -804152 -1029893 -369179 -524204 -871727 -977953 15 -926289.2818 -391255 -689109 -1794437 -958621 -804152 -1029893 -369179 -524204 -871727 -977953 16 -926289.2818 -391255 -689109 -1794437 -958621 -804152 -1029893 -369179 -524203 -871727 -977953

The
variation in total free energy indicates that the accuracy of the thermodynamic data does not
justify more than 2-3 iterations (as obtained with initial resolution = 0.1 and
final_resolution = 1e-2 mole). The variations in the chemical potentials
indicate that O2 is the most poorly resolved component. Its variation
becomes comparable to its precision after 6 iterations (as obtained with initial
resolution = 0.1 and final_resolution = 1e-3 mole). To put these variations in
perspective, a variation of 50 J/mol in the chemical potential of O2 corresponds
to a variation in oxygen fugacity of 2e-3 log10 units (50 J/mol /(2.303*R**T*)).

The default value of **output_iteration_G** is **F**. This keyword is
intended primarily for interactive analysis with MEEMUM, setting **output_iteration_G** to **F**
will substantially slow calculations with VERTEX because of the volume of output
written to the user console.

See also: iteration, initial_resolution, final_resolution, adaptive minimization keyword group discussion.

The
**pause_on_error** (**T** or **F**) keyword determines whether Perple_**X**
programs terminate upon encountering an anticipated error (**F**) or pause
and wait for user interaction (**T**).

The default value of **pause_on_error** is **T**.

If
a Perple_**X** program is being run via a
script, or as a subroutine of another program, then **pause_on_error** should
be set to ensure that in the event of an error Perple_**X**
returns control to the calling script/program.

In Schreinemakers and mixed-variable diagram calculations (i.e., unconstrained
optimization) compositional degeneracies among the pseudocompounds of different
solutions (e.g., that pseudocompounds of different solutions may have exactly
the same Fe/Mg ratio) may make it impossible for Perple_**X**
to determine the true variance of pseudo-univariant and -invariant equilibria.
To avoid this problem a small perturbation to the compositions of the
pseudocompounds generated for each solution is introduced. The magnitude of the
perturbation is proportional to the value assigned to the **pc_perturbation**
keyword.

The default value of **pc_perturbation **is **5d-3**. The sensitivity of
Perple_**X** to this parameter has not been
tested. The perturbation for each solution is calculated as **delta** =
**pc_perturbation * cst * initial_resolution / auto_refine_factor**, where
cst is a random number between 1 and 10. It is expected that this method of
eliminating degeneracies will be effective if delta is greater than the
numerical resolution for compositions (~1d-5).

This keyword affects VERTEX.

The **poisson_ratio** keyword controls whether, and under what circumstances,
a default value for the Poisson ratio is used to calculate shear moduli and
seismic wave velocities.

The
poisson_ratio
keyword takes 2 values, **value1** and **value2**

value1may beon,offorall. The default ison

value2is the value for the Poisson ratio, the default is0.35

If **value1 = off** and no shear modulus is available for a phase, then the
shear modulus and seismic velocities of the phase are assigned the bad_number value.

If **value1 = on** and no shear modulus is available for a phase,
the shear modulus is computed as 3*K*(1-2ν)/(ν+1)/2,
where the Poisson ratio **ν = value2** and *K* is the bulk modulus. If no bulk
modulus is available, then the shear modulus and seismic velocities of the phase
are assigned the bad_number value.

If **value1 = all**, then the shear modulus of any phase is computed as 3*K*(1-2ν)/(ν+1)/2 regardless of whether other data
are available for the
shear modulus. If no bulk modulus is available, then the shear modulus and
seismic velocities of the phase are assigned the bad_number value.

This option affects WERAMI, MEEMUM and FRENDLY. For calculations analyzed with WERAMI, changing this keyword does not necessitate repeating the primary calculation with VERTEX.

Other keywords relevant to seismic
velocity calculations: vrh/hs_weighting,
bounds,
explicit_bulk_modulus, Anderson-Gruneisen, melt_is_fluid,
interpolation**.**

The
**poisson_test** (**T** or **F**, default ** F**) keyword activates an error trap that
checks whether the poisson_ratio of a phase is negative. The most common cause
of negative Poisson ratios in Perple_**X**
is a data base configuration in which bulk moduli are computed from an
isostatic EoS while shear moduli are computed from empirical functions.

In general it is expected that the error trap will only be useful for applications where seismic wavespeeds are of primary concern. For such applications, running WERAMI with the error trap activated will identify conditions where the computed seismic wavespeeds are dubious.

This option affects WERAMI, MEEMUM and FRENDLY. For calculations analyzed with WERAMI, changing this keyword does not necessitate repeating the primary calculation with VERTEX.

The **proportions** keyword controls whether the relative proportions of
phases (i.e., modes) are determined on the basis of weight or volume.

This keyword may take values: **vol**, **wt**. The default is **vol**.

This option affects WERAMI.

See also: composition_constant, composition_phase, composition_system

The **pseudocompound_file** controls whether VERTEX outputs a text file that
summarizes the static pseudocompound compositions used for a calculation. If **
pseudocompound_file = T**, then the file is output and named
my_project_pseudocompound_list.txt, where my_project is the project name and
PROGRAM is the name of the relevant program.

This keyword may take values: **T** (true) or **F **(false). The default is
**F**.

This keyword affects VERTEX and MEEMUM.

**NOTE:**
**reach_increment** is a not a perplex_option.dat
keyword, the reach_increment keyword is an option that applies to a specific
solution model. To implement this keyword modify the solution model file by
adding the keyword and its value on the line prior to the end_of_model keyword
(e.g., see Figure
4 in the adaptive
minimization keyword group discussion).

The
**reach_increment **specifies an incremental increase in the range over which
the compositional variables of a specific solution phase are allowed to vary between successive
iterations during adaptive minimization. The increase may improve the resolution
of phase relations involving two or more solutions with extraordinarily flat
free-energy composition surfaces. This circumstance is problematic, because a small error in the composition of one phase
may cause a large error in the
other phase. Most commonly this occurs when
two or more coexisting phases are related by a solvus. This kind of error is
manifest by spurious solvi, which typically have irregular or patchy boundaries.
This issue is addressed in the adaptive
minimization keyword group discussion.

To
a good approximation, if at iteration *n*-1 the estimated composition of a
phase is *x*_{n-1}±d_{n-1},
then in the subsequent iteration the composition will be allowed to vary
approximately over
the interval *x*_{n-1}±reach_increment*d_{n-1}.
(see iteration, eq [3]). The
number of compositions considered during the iterative refinement of the
composition of a solution with c compositional variables is proportional to

*
*[1+*i*_{1}(1+reach_increment)/2]^{c-1}

where
*i*_{1} is the first value of the iteration
keyword (usually 3). Thus, large reach_increment values
are particularly expensive in terms of both memory and time for complex
solutions (e.g., silicate melts).

The default value for reach_increment is 0. If reach_increment for a specific solution model is > global_reach_increment, then the local value overrides the global value. Experience suggests that a value of 6 is adequate to accurately resolve phase relations involving silicate solvi if the initial resolution for adaptive minimization is ~1e-1.

This keyword affects VERTEX and MEEMUM.

See also: final_resolution, iteration, initial_resolution, auto_refine_factor_I, solvus_tolerance, adaptive minimization keyword group discussion.

The
**reach_increment_switch** keyword controls how reach increments specified by
the
reach_increment and/or global_reach_increment
keywords are implemented.

The
**reach_increment_switch** keyword may
take the following values:

off- all reach increments are set to zero

on- reach increments are applied only during the auto-refine stage of calculations with VERTEX

all- reach increments are applied during both the exploratory and auto-refine stage of calculations with VERTEX

The default is
**on**.

Setting
**reach_increment_switch **to **all** improves the compositional
resolution obtained during the exploratory stage, in general this improvement is
expected to be insignificant and increases both the time and memory required for
the exploratory stage.

For
calculations with MEEMUM reach increments are used regardless of whether
auto-refine data is being used unless **reach_increment_switch** is set to
off.

This keyword affects VERTEX and MEEMUM.

The **
reaction_format**
keyword controls the output format for reactions identified in Schreinemakers
and mixed variable diagram calculations.

This keyword may take the following values:

minimum- only phases in the thermodynamic composition space are output

full- phases in the saturated component composition space are also output

stoich- stoichiometric coefficients are also output

S+V- entropy and volume are also output

everything- everything is output

The default is **
minimum**.

WARNING: full reaction equations vary as a function of the independent variables as these variables may cause the entropy and volume of a reaction and the identity of stable saturated phases to change. The equations output are those at the first equilibrium condition found.

This keyword affects VERTEX.

The **
reaction_list**
keyword controls whether a spreadsheet formatted list of reactions found during
Schreinemakers and mixed variable diagram calculations.

This keyword may take values:
**on**, **off**. The default is **off**.

This keyword affects VERTEX.

**NOTE:** **refine_endmembers** is not a perplex_option
file
keyword, rather it is an option that applies to a
specific solution model. To implement this keyword modify the solution model by
adding the keyword before the **end_of_model** keyword.

If
the **refine_endmembers** keyword is present in a solution model, then the solution model is evaluated to compute the properties of the solution at its
endmember bulk compositions.

Prior
to version 6.7.8, Perple_**X** did not evaluate
solution models for the composition of a pure endmember, the assumption being
that the properties predicted by
the solution model at the endmember bulk composition would be identical to the
those of the pure endmember. This assumption is not valid
for order-disorder models in which order-disorder is possible at an endmember
bulk composition. In such cases, if **refine_endmembers** is not specified Perple_**X**
will return the property of the fully ordered endmember at the endmember
composition, rather than the property of the endmember with the stable state of
order. For example, the Ilm(WPH) model represents order-disorder in terms of an
ordered endmember (oilm) and a disordered endmember (dilm). If no **refine_endmembers**
keyword is present in the model, Perple_**X** returns the properties of oilm for the
pure ilmenite bulk composition, but if the **refine_endmembers** keyword is
added to the model, then the properties obtained for the pure ilmenite bulk composition correspond to an equilibrium mixture of
ordered (oilm) and disordered
ilmenite (dilm) species.

Currently (in 6.7.8) there are only two solution
models [Ilm(WPH) and Cpx(G)] in the standard solution model file (solution_model.dat)
where order-disorder occurs in the limit of an endmember bulk composition. The **refine_endmembers
**keyword has been added to the **Ilm(WPH)**
model and it must be added to the **Cpx(G)**
model if Cpx(G) is to be used to compute properties at the bulk Ca-Tschermaks
endmember composition.

The ** refinement_points_II** keyword specifies the number of metastable compositions
that are to be refined after the first iteration of an adaptive optimization
calculation. Reducing the value of this keyword substantially reduces the cost
(in both memory and time) of calculations, but ultimately may lead to poorly
resolved phase boundaries. Prior to the 6.7.6 revision, the number of metastable
refinement points was equal to the number of thermodynamic components. In tests,
a value of 5 appears to be adequate.

Unnecessarily large values of this keyword may substantially increase the cost of calculations in both time and memory, while small values may lead to poorly resolved phase boundaries and/or numerical instability.

This keyword takes a integer value (< 12 characters):
>0, and defaults to 5. If the value is greater than the number of
thermodynamic components (*c*) + 2 for a calculation, then its value is
automatically reset to * c* + 2.

This keyword affects VERTEX and MEEMUM.

See also: final_resolution, reach_increment, initial_resolution, iteration, auto_refine_factor_I, solvus_tolerance, adaptive minimization keyword group discussion.

The
refinement_threshold keyword can be used to specify a threshold in Gibbs energy
beyond which metastable phase compositions will be eliminated during adaptive
optimization. Specifically, if *g _{i}* - sum(

Setting the refinement threshold to near zero (e.g., 1e-4 J) may result in a several orders of magnitude reduction in the amount of memory required during adaptive optimization, but causes only minor reduction in computation time. The fraction of the total number of compositions eliminated by application of the threshold is indicated by the console message:

Metastability filtering eliminated XX.XXX% of the trial compositions prior
to optimization.

written when VERTEX finishes a calculation. Small values may lead to numeric instability that is manifest by splotchy phase diagram sections and failed optimizations. The value that qualifies as "small" is problem specific and for that reason it is not recommended for inexperienced users.

This keyword takes a numeric value (< 12 characters): >0, and defaults to 1d4. If refinement_threshold > 1d4, then the threshold is deactivated.

This keyword affects VERTEX and MEEMUM.

See also: final_resolution, reach_increment, initial_resolution, iteration, auto_refine_factor_I, solvus_tolerance, adaptive minimization keyword group discussion.

The
**seismic_output**
keyword controls the amount of information relevant to seismic wave propagation
that is output by the programs WERAMI (in computational mode 1), MEEMUM and
FRENDLY.

This keyword may take values:
**all**, **some, none**. The default is **some**, in which case the
aforementioned programs output wave speeds and adiabatic shear and bulk moduli. If **seismic_output** = **all**, then the partial derivatives of wave
speed and elastic moduli with respect to temperature and pressure are also
output. These derivatives do not account for variations in the equilibrium
mineralogy as a function of temperature or pressure.

The **short_print**
keyword controls whether equilibrium conditions of reactions found during
Schreinemakers and mixed variable diagram calculations are output (provided a
print file is requested).

This keyword may take values:
**on**, **off**. The default is **on**.

This keyword affects VERTEX.

The
**site_check** keyword controls whether Perple_**X** rejects solution model
compositions that yield negative site fractions.

This keyword may take values: **T** (true) or **F **(false). The default is
**T**, i.e., negative site fractions are rejected.

The site populations of a valid solution model must be both positive and a
linear combination of the site populations of its independent endmembers. A
number of solution models implemented by Holland & Powell (JMG 1998, and various
coworkers) in
THERMOCALC, most commonly models involving Tschermaks substitutions, assume
endmembers that are inconsistent with these requirements. To remedy this
inconsistency Holland & Powell impose an ad-hoc correction, referred to as "equipartition",
to the site fractions used to compute configurational entropy. Such ad-hoc corrections are not possible in Perple_**X**, therefore Perple_**X**
and THERMOCALC may give different results. These differences can be reduced by
setting
**site_check** = **F** (false).

If
**site_check** = **F** ,then Perple_**X** allows solution compositions that
imply negative site fractions. For such compositions the configurational entropy is computed using only the positive site fractions generated by
the invalid model. Thus in this case, Perple_**X**
allows the same range of solution compositions as THERMOCALC, but does not necessarily compute the same
configurational entropy. If **site_check** = **T**, the compositional
range of the solution in Perple_**X** is
restricted compared to the range allowed in THERMOCALC. With **site_check** = **F** results obtained using Perple_**X** tend to be more
similar to those obtained with THERMOCALC than they are when **site_check** = **T**.
Before April 2009, Perple_**X** operated as though
**site_check** = **F**. Therefore Perple_**X**
results obtained before that date can only be reduced with the current version
if site_check is set explicitly to **F**.

**WARNING:** Setting **site_check** =
**F** prevents Perple_**X** from testing for invalid site fractions
that arise for reasons unrelated to the equipartition assumption.

**NOTE:** **site_check_override** is not a perplex_option
file
keyword, rather it is an option that applies to a
specific solution model. To implement this keyword modify the solution model by
adding the keyword before the **end_of_model** keyword.

If
the **site_check_override** keyword is present in a solution model, then
the tests for invalid dependent endmember site populations introduced in Perple_**X**
6.7.7 (see Perple_**X**
6.7.7 for explanation) are overridden and the solution model is treated
in earlier versions of Perple_**X**.
Specifically, if **site_check_override** is present in a model, then
dependent endmember properties are computed according to their stoichiometric
definitions in the solution model file and the only constraint on their
concentration in the solution is that no atomic site fraction can be less than
zero.

The
**site_check_override** is useful for solution models in which
order-disorder effects are partially or entirely accounted for by ad-hoc
assumptions (e.g., Holland & Powell's, 2007, equipartition
assumption).

Currently
(6.7.8) **site_check_override** has been added to the following solution
models in the standard solution model file (solution_model.dat):
Atg(PN), Amph(DHP), Amph(DPW), Bio(TCC), Chl(HP), GlTrTsPg, GlTrTsMr, Na-Amph.

The
**solution_names** keyword determines whether Perple_**X**
uses solution model names, abbreviations, or full_names on output.

This
keyword may take the value **mod**[el], **abb**[reviation], or **ful**[l],
the default is **mod**. The keyword has no effect for solution models that do
not include the optional abbreviation and full_name keywords.

This keyword affects WERAMI, PSSECT, and MEEMUM.

The ** solvus_tolerance** keyword specifies the
minimum distance (in
normalized composition
space) between two compositions of a solution phase at which the compositions
are considered to represent distinct (immiscible) phases of the solution.
Compositions that are separated by a distance less than ** solvus_tolerance**
are considered to represent a single phase whose composition is computed as the
weighted average of the different compositions of the solution.

This keyword takes the character value **aut
**(automatic) or numeric values between 0 and 1, it defaults to aut. If
** solvus_tolerance** = **aut**, then if auto_refine is on the solvus
tolerance is 3/2 * initial_resolution / auto_refine_factor_X,
where X is I, II, or III depending on type of calculation; otherwise
the tolerance is equated to initial_resolution.

** solvus_tolerance** = **aut** is almost
always optimal. For adaptive minimization calculations the most common problems,
i.e., spurious
and stepped solvi, that occur during the calculation of solvus phase
relations can resolved, respectively, via the reach_increment
and solvus_tolerance_II keywords.

The default value for ** solvus_tolerance**
(auto), results in a much coarser resolution for adaptive minimization than
specified by final_resolution. The reason this coarse resolution
is used as the default is
that Perple_**X** may have difficulty
converging to the correct compositions of coexisting immicible phases. These
difficulties (see Figure 2b
of the adaptive
minimization keyword group discussion) arise because the
algorithm assumes that if phase compositions have been discretized with
resolution
*d*_{n}, then the accuracy
for any compositional variable *x*_{n} is ±*d _{n}*.
Therefore during iterative refinement the compositional estimate is not allowed
to move outside the interval

Set **solvus_tolerance **=** 0** to prevent VERTEX from
homogenizing stable pseudocompounds that represent a miscible phase (all phase
assemblages will consist of p=c pseudocompounds). Set **solvus_tolerance **=** 1**
to make VERTEX homogenize all stable pseudocompounds of a given solution into a
single phase regardless of whether or not the pseudocompounds represent distinct
immiscible compositions.

This keyword affects VERTEX and MEEMUM.

If you do not understand what this keyword does, then do not change it.

This parameter can be adjusted to eliminate "stepped" solvus boundaries along which the compositions of the coexisting phases change by increments more closely related to the initial_resolution than to the final_resolution keyword values.

The solvus_tolerance_II keyword sets an internal
parameter that is used to select metastable phase compositions for subsequent
refinement during adaptive minimization. If in an iteration of an adaptive
minimization calculation, a composition of a solution phase is found to be
stable, then metastable compositions of the solution will only be considered in
the subsequent iteration if the metastable composition is separated from the
stable composition by a distance greater than the value of solvus_tolerance_II.
The idea behind this keyword is that if a solution is immiscible, forcing
Perple_**X** to consider phases far from a
composition of perceived stability increases the likelihood that the algorithm
will identify the multiple stable phases of a solution. This strategy does seem
to improve the resolution of phase boundaries involving solvi, but for reasons
that are unclear to me it also seems to improve the resolution of phase
boundaries in general. The optimal
value for this keyword should be problem specific, but experience with silicate
solutions seems to suggest that the optimal value for this parameter is
0.25+/-0.05 regardless of the phases under consideration.

A disadvantage of using the relatively large
default value for solvus_tolerance_II is that it may give rise to a numerical
artifact in
Perple_**X** referred to here as stepped solvi
(See Figure 7 of the adaptive
minimization keyword group discussion for an illustration of a stepped
solvus). This problem occurs when the distance between the limbs
of a solvus are less than the value of solvus_tolerance_II, in this limit
the tolerance prevents the adaptive minimization algorithm from refining
compositions of immiscible phases that are perceived to be metastable. As a
consequence the limbs of the solvus are only located accurately when the
compositions generated at the lowest level of resolution (i.e., as determined by
the effective initial resolution) are
fortuitously close to stable compositions on the limbs of a solvus. As a
consequence of this behavior, the limbs of a solvus effected by this problem
typically change in abrupt steps that correspond to steps in the compositions of
the immiscible phases that are comparable to the initial_resolution.
An additional disadvantage of setting solvus_tolerance_II to values greater than the effective initial resolution is that it limits the range over
which a stable phase composition may change during adaptive refinement (this limitation can be overcome by using
reach_increment).

Perple_**X**'s adaptive minimization algorithm is such that
it is expected that non-zero values for this keyword improve the resolution of solvi,
but degrade the resolution of normal
phase boundaries by limiting the range over which phases may change their
composition between iterations.

This keyword affects VERTEX and MEEMUM.

See also: final_resolution, iteration, initial_resolution, reach_increment.

The ** speciation_max_it** keyword specifies the maximum number of iterations
permitted for the solution of speciation (aka order-disorder) calculations.

This keyword takes an integer value (>0) and defaults to 40.

This keyword affects VERTEX, FLUIDS, FRENDLY, WERAMI and MEEMUM.

The
**
speciation_factor** keyword determines the precision of speciation calculations,
this precision is computed as the effective final
resolution divided by the speciation_factor. A value of 100 is usually
adequate. The optimal value of this keyword can be determined by calculating the
total Gibbs energy (with MEEMUM) of a system at a fixed pressure-temperature
condition as a function of the speciation_factor. The smallest value of the
speciation_factor at which no significant variation in the total Gibbs energy
occurs is the optimal value.

Unnecessarily large values of this keyword may substantially slow calculations, while small values may lead to numerical instability.

This keyword takes a numeric value (< 12 characters): >10, and defaults to 100.

This keyword affects VERTEX, FLUIDS, FRENDLY, WERAMI and MEEMUM.

This keyword is obsolete in post 6.7.5 Perple_**X**
versions, see
speciation_factor.

The speciation_tolerance keyword specifies the
precision of speciation calculations for order-disorder models, i.e., the
permitted error in the molar fraction of an ordered species. Prior to Perple_**X**
version 6.6, the value (10^{-5}) of this tolerance was specified
internally. Typical enthalpies of ordering are in the range 10^{3}-10^{4}
J/mol; thus a tolerance 10^{-5} of implies error of <10^{-1}
J/mol in the computed energy of phases described by order-disorder speciation
models. Given that input energies are typically rounded to the nearest 10^{2}
J/mol, a speciation_tolerance of 10^{-2} may be adequate for most
purposes. The advantage of using a large tolerance is that it may accelerate
calculations involving multiple order parameter solution models (e.g., Diener et
al. 2007; Green et al., 2008), the disadvantage of specifying a large tolerance
is that it may increase the roughness of computed properties.

This keyword takes numeric values (< 12 characters):
>0, <1, and defaults to 10^{-3}.

This keyword affects VERTEX, FLUIDS, FRENDLY, WERAMI and MEEMUM.

The **species_Gibbs_energies** keyword controls whether endmember Gibbs
energies are output by MEEMUM and WERAMI.

This keyword may take values: **T** (true) or **F **(false). The default is
**F**.

This keyword only affects WERAMI and MEEMUM.

The **species_output** keyword controls whether phase speciation is output by
WERAMI in computational mode 1.

This keyword may take values: **T** (true) or **F **(false). The default is
**T**.

This option only affects WERAMI and MEEMUM.

The **
spreadsheet** keyword controls whether WERAMI includes the independent
variables of a calculation in tabulated output. Setting **spreadsheet** = **
T** (true) results in larger output files, but is useful if the data is to be
imported into a spreadsheet program (e.g., Excel).

This keyword may take values: **T** (true) or **F **(false). The default is
**F**.

This keyword affects mode 2 calculations in WERAMI.

The post-3/21/07 version of Perple_**X** '07
allows four different models for discretizing the composition of a solution
phase. These models, designated "subdivision
schemes" are specified by a line in the solution model
file for
each independently variable endmember consisting of four numbers, XMIN, XMIN,
XINC, and IMOD: XMIN and XMAX are the compositional limits of the solution; the
(initial) number of discrete compositions (i.e., pseudocompounds) is calculated
from XINC (if the initial_resolution keyword
is specified, then the initial_resolution
overrides the value of XINC specified locally in the solution model) as (XMAX-XMIN)/XINC
+ 1; and the spacing of these compositions is determined by IMOD as follows:

IMOD = 0 - Cartesian subdivision, XINC is the (initial) compositional spacing for the discretization.

IMOD = 1 - asymmetric transform subdivision, compositions are closely spaced towards XMIN.

IMOD = 2 - symmetric transform subdivision, compositions are closely spaced towards both XMIN and XMAX.

IMOD = 3 - double symmetric transform subdivision, compositions are closely spaced towards XMIN and XMAX and a third composition that is specified on the line following IMOD.

IMOD = 4 - asymmetric transform subdivision, compositions are closely spaced towards XMAX.

For IMOD=1-4, if the compositional domain is normalized so that W=0 and W=1 represent,
respectively, the compositions at which compositions are closest and furthest apart, compositions
are computed as W =
([1 - Z]***stretch_factor** + 2)/(1 + Z) where Z = (**stretch_factor** +
2)**(1-Y) and Y = 0...1 at constant intervals of dY ~ XINC/(XMAX-XMIN). The exact relation between X and the composition generated depends on
the way W is mapped to X, but to a first approximation, if the **stretch_factor**
is 0.0164 the resolution of the solution will be improved by an order of
magnitude where the spacing is smallest compared to Cartesian subdivision (IMOD=0).
A consequence of this improvement, is that the resolution of the solution
becomes worse (by more than a factor 2) where the spacing is largest. Increasing
the stretch_factor to values > 1, results in a discretization scheme that is
effectively Cartesian, whereas decreasing the stretch_factor by a factor of 2
increases the maximal compositional
resolution by roughly an order of magnitude. Thus, values <<
0.0164 may destabilize adaptive minimization, while values >> 0.0164 are unlikely
to offer any advantage over the more straightforward Cartesian scheme (IMOD=0).

**Pros and cons of non-linear subdivision (IMOD=1-3):** The main advantage of
using non-linear subdivision (in particular IMOD=1), is that it permits high
resolution of minor elements (typically Mn, Cr, and Ti) that may strongly
influence the location of phase boundaries. Presently IMOD=1 is specified for
all Mn, Cr, and Ti endmembers in the solution model file
solut_07.dat.
Calculations of solvi are often sensitive to extremal compositions of a
solution, thus the accuracy of such calculations is improved by specifying IMOD=2
for the relevant solutions, the price paid for this choice is that the
calculation has lower resolution far from the compositional extremes. In view of
this cost, at least
for the moment, this scheme is only specified for two solution models (MuPa and
San). The major disadvantage of non-linear subdivision is that it has the
potential to generate much larger numbers of compositions (pseudocompounds) for
multicomponent solutions resulting in high costs in terms of computational time
and memory.

The **stretch_factor** keyword value cannot be < 0, the default value is
0.0164.

This keyword affects VERTEX and MEEMUM.

The **
subdivision_override** keyword allows users to override the
subdivision schemes specified locally in the
solution model
file with a single global choice.

**
subdivision_override** may take the value: **off**, **stretch**, or**
linear. **The default is **off.**

If **
subdivision_override** = **linear**, the local values of XMAX, XMIN, and
XINC are interpreted as would be the case if IMOD = 0.

If **
subdivision_override** = **stretch** and IMOD = 0, the local values of XMAX,
XMIN, and XINC are interpreted as would be the case if IMOD = 2. If IMOD = 2 or
3 the local values XMAX, XMIN, and XINC are interpreted according to the value
of IMOD.

This keyword affects VERTEX and MEEMUM.

The **T_melt** keyword specifies a temperature (K) threshold below which the
endmembers of a melt solution model, e.g., melt(HP) and pMELTS(G), are
arbitrarily destabilized. This is sometimes helpful because the thermodynamic
properties of the melt endmembers do not extrapolate to low temperature. This
option only affects melt endmembers that are used by a solution solution model;
thus problematic endmembers that are
present in the data base being used but not included in a model for a stable
melt phase must be excluded explicitly in the problem definition file (the file
created by BUILD). The disadvantage of using **T_melt **> 0 is that it may
result in an artificial "solidus" at T = T_melt.

The default value
of T_melt is **873**.

This keyword affects VERTEX and MEEMUM.

The **T_stop** keyword specifies a temperature (K) threshold below which chemical
equilibration is assumed to cease. If the temperature for a calculation is below
the threshold, then the chemical equilibrium is computed at **T_stop**, but
physical properties for the resulting phase assemblage are computed at the
nominal temperature.

The default value
of T_stop is **0**.

This keyword affects VERTEX and MEEMUM.

The variance keyword specifies the maximum true variance of pseudo-univariant equilibria to be traced during Schreinemakers diagram calculations. Two values are specified, these are applied, respectively, for the exploratory and auto-refine stages of calculation.

This keyword affects VERTEX.

The value of the **vrh/hs_weighting** keyword is
the weighting (χ) used to compute aggregate adiabatic elastic moduli for
seismic wave-speed calculations according
to the averaging scheme

*Z* = (1-χ)**Z*_{-} + χ**Z*_{+}

where *Z*_{-} and *Z*_{+ }
are the lower and upper bounds on the aggregate modulus. The method (VRH or HS)
of computing the bounds is specified by the bounds
keyword. For calculations analyzed with WERAMI, changing this keyword does not
necessitate repeating the primary calculation with VERTEX.

This keyword takes numeric values (< 12 characters): 0 -> 1. The default value is 0.5.

This option affects WERAMI, MEEMUM and FRENDLY.

Other keywords relevant to seismic velocity calculations: bounds,
explicit_bulk_modulus,
poisson_ratio,
Anderson-Gruneisen,
melt_is_fluid,
interpolation, seismic_output**.**

The **zero_bulk** keyword specifies the threshold below which a the bulk
composition of a component is considered to be zero. This option is useful
for processing fractionation calculations because in such calculations the
amount of a component may become negligible and destabilize the
calculations. Under these conditions, if zero_bulk is set to a finite value, then
VERTEX will warn of the potential problem. If zero_bulk is assigned a value of zero the option is
effectively off.

This keyword takes numeric values (< 12 characters), 1e-6 is the default value.

This keyword only affects VERTEX.

The **zero_mode** keyword determines whether stable phases present in zero amount
are eliminated from the assemblage on output. This option is particularly useful
for processing fractionation calculations because in such calculations the
amount of one or more components may become zero. The numerical value assigned
to zero_mode defines the tolerance for determining zero amount. If zero_mode is
assigned a negative value the option is turned off.

This keyword takes numeric values (< 12 characters): 0 -> 1, 1e-6 is the default value.

This keyword only affects VERTEX.

For phase fractionation calculations the **1d_path** keyword indicates
the number of nodes taken to define the path in the exploratory and auto-refine
stages of the calculation. The default values for 1d_path are 20 and 150 for the
exploratory and auto-refinement stages of a phase fractionation calculation. As
a rule of thumb, the latter value should be chosen such that the results do not
change significantly if it is varied by a factor of two.

This keyword affects VERTEX.