Equilibrate package

The equilibrate module implements a Python interface to the Equilibrate and EquilState classes. It also implements a Python class called MELTSmodel that wraps the objective-C classes: EquilibrateUsingMELTSv102, EquilibrateUsingMELTSv110, EquilibrateUsingMELTSv120, EquilibrateUsingpMELTSv561, EquilibrateUsingMELTSwithDEW, and EquilibrateUsingStixrude.

The Equilibrate class provides methods to calculate an equilibrium phase assemblage given a list of Phase class instances.

You can calculate equilibrium in closed thermodynamic systems under a variety of constraints:

• Temperature and pressure (Gibbs free energy minimization)
• Entropy and pressure (enthalpy minimization)
• Temperature and volume (Helmholtz free energy minimization)
• Entropy and volume (internal energy minimization)

You can also calculate equilibrium under constraints of fixed temperature and pressure in open thermodynamic systems by specifying one or more fixed elemental chemical potentials.

For details of the underlying theory and algorithms implemented in the Equilibrate class, see the notebooks in the PublicNotebooks/Equilibrate folder on the ENKI server.

class equilibrate.Equilibrate(element_l=None, phase_l=None, lagrange_l=None)

Class for minimizing a generic thermodynamic potential in order to calculate an equilibrium phase assemblage.

The default potential is the Gibbs free energy.

Parameters:

element_l : [], default None

See documentation for element_list attribute.

phase_l : [], default None

See documentation for phase_list attribute.

lagrange_l : [], default None

See documentation for lagrange_list attribute.

Notes

Alternate potentials are specified by stipulating appropriate Lagrange transformations of the Gibbs potential.

Attributes

A_omni_inv	A matrix that transforms an array/matrix of mole numbers of elements to an array/matrix of mole numbers of components of the omnicomponent phase
bulk_comp	Bulk composition of the system as moles of elements
CTf	Stoichiometric vectors of element concentrations that embody the Lagrange constraints
element_list	A list of strings that identify the element basis for the system
entropy	Indicates if entropy is an independent variable of the minimal potential and if temperature is a dependent variable
lagrange_list	A list of tuples characterizing the Lagrange transformation of the Gibbs free energy to form the operative thermodynamic potential
lagrange_moles	Moles of chemical potential entities stipulated in dictionaries, which are contained in the lagrange_list constraints
lagrange_no_mol_deriv	Produces a simplified gradient and hessian of the generalized Khorzhinskii potential
lagrange_use_omni	If set to True, the algorithm uses the omnicomponent phase exclusively to balance non-linear constraint reactions.
max_linear	Maximum number of linear search steps associated with each quadratic iteration
max_quad	Maximum number of Newton quadratic minimization steps allowed in computation
moles_in	Moles of phase added to the system on detection of saturation
moles_out	Minimum total moles of phase allowed in system
phase_list	A list of class instances for phases that are permitted to form
phase_separ_threshold	Minimum energy in Joules for phase separation
reactions	Balanced reactions pertaining to the Lagrange constraints
rotate_orthog_proj	Prevents creation of a search direction for potential minimization that has unwanted coupling of oxygen-bearing components
volume	Indicates if volume is an independent variable of the minimal potential and if pressure is a dependent variable
VT_null	Orthogonal projection operator obtained from constraints on chemical potentials derived from the lagrange_list entries

A_omni_inv

A matrix that transforms an array/matrix of mole numbers of elements to an array/matrix of mole numbers of components of the omnicomponent phase

This matrix is the inverse of a matrix that maps elemental abundances to component mole numbers for the omnicomponent phase. This property is available only if chemical potential constraints are specified in lagrange_list and if there is an omnicomponent phase in the system.

Default is None

readonly

Returns:2-d nd_array

CTf

Stoichiometric vectors of element concentrations that embody the Lagrange constraints

Default is None

readonly

Returns:np_array or None

VT_null

Orthogonal projection operator obtained from constraints on chemical potentials derived from the lagrange_list entries

Default is None

readonly

Returns:np array or None

bulk_comp

Bulk composition of the system as moles of elements

readwrite

Returns:numpy array

element_list

A list of strings that identify the element basis for the system

For example,[‘H’,’C’,’O’,’Na’,’Mg’,’Al’,’Si’,’P’,’K’,’Ca’,’Ti’,’Cr’, ‘Mn’,’Fe’,’Co’,’Ni’]

readonly

Returns:A Python list

entropy

Indicates if entropy is an independent variable of the minimal potential and if temperature is a dependent variable

True if yes; False if reverse.

readonly

Returns:Flag (bool)

execute(t=1000.0, p=1000.0, bulk_comp=None, state=None, debug=0)

Calculates an equilibrium assemblage, returning the results as an instance of the EquilState class

Parameters:

t : float, default 1000.0

Temperature in Kelvins

p : float, default 1000.0

Pressure in bars

bulk_comp : numpy array, default None

Bulk composition of the system. Array of element concentrations, of the length and order of self.element_list

state : EquilState, default None

An instance of the EquilState class generated by this method. This parameter is only specified for a sequence of equilibrium calculations where the state of the system is initialized from a previous computation.

debug : int, default 0

Level of detail printed by the method:

• 0, no information
• 1, minimal progress information
• 2, normal debugint output level
• 3, verbose debuging output level

Returns:

state: EquilState

An instance of the EquilState class that contains the equilibrium state of the system

Notes

Both the bulk_comp and state parameters cannot be set simultaneously.

lagrange_list

A list of tuples characterizing the Lagrange transformation of the Gibbs free energy to form the operative thermodynamic potential

Each tuple has two terms:

1. Either of the following:

   • A string with content ‘T’ or ‘P’
   • A dictionary keyed on element symbols with values corresponding to stoichiometric coefficients of element chemical potentials. These linear combinations of potentials are fixed by the constraint.

2. A function to compute values for the constraints specified in (1)

The function has a signature func(T, P, state), where T is temperature in K, P is pressure in bars, and state is an instance of the EquilState class.

readonly

Returns:A Python list of tuples

lagrange_moles

Moles of chemical potential entities stipulated in dictionaries, which are contained in the lagrange_list constraints

Default is None

readonly

Returns:np.array or None

lagrange_no_mol_deriv

Produces a simplified gradient and hessian of the generalized Khorzhinskii potential

Assume that the generalized Khorzhinkii potential is constructed so that the imposed chemical potential is not a function of mole numbers of any phase in the system. Alternatively, the imposed potential is stoichiometrically assembled using reaction coefficients involving equilibrium phases in the assemblage. This option produces a simplified gradient and hessian of the generalized Khorzhinskii potential, but does not affect construction of the equality constraint matrix nor the Lagrange multiplier terms in the hessian of the Lagrangian function. It is seldom necessary to set this flag to True.

Default is False

readwrite

Returns:Flag (bool)

lagrange_use_omni

If set to True, the algorithm uses the omnicomponent phase exclusively to balance non-linear constraint reactions.

Default is True

readwrite

Returns:Flag (bool)

max_linear

Maximum number of linear search steps associated with each quadratic iteration

readwrite

Returns:Number of linear search steps (int)

max_quad

Maximum number of Newton quadratic minimization steps allowed in computation

readwrite

Returns:Number of steps allowed (int)

moles_in

Moles of phase added to the system on detection of saturation

readwrite

Returns:Number of moles added (number)

moles_out

Minimum total moles of phase allowed in system

If there is less than this quantity, the phase is discarded.

readwrite

Returns:Minimum moles allowed (number)

phase_list

A list of class instances for phases that are permitted to form

These instances must derive from the PurePhase or SolutionPhase classes, which are defined in the phases module.

readonly

Returns:A Python list

phase_separ_threshold

Minimum energy in Joules for phase separation

Gibbs free energy threshold that must be attained in order to add another instance of a phase to the equilibrium assemblage. In the phase unmixing (immiscibility) algorithm, candidate compositions are tested and if one is found with a Gibbs free energy below the projected tangent plane to the input composition by this amount, then the new phase instance is added to the system. The value is in Joules and should always be negative. Values larger than the default will likely encourage the detection of false unmixing events; values more negative will likely prevent the detection of unmixing and result in metastable assemblages. Use caution when altering the default value.

Default is -0.1

readwrite

Returns:Threshold value (number)

reactions

Balanced reactions pertaining to the Lagrange constraints

Default is None

readonly

Returns:np.array or None

rotate_orthog_proj

Prevents creation of a search direction for potential minimization that has unwanted coupling of oxygen-bearing components

The basis vectors of the orthogonal projection matrix, VT_null, generated from the lagrange_list attribute, are rotated to zero to minimize the contribution of oxygen to the null space. This flag is enabled to avoid creating a search direction for potential minimization that has unwanted coupling of oxygen-bearing components (for more information, see method _compute_null_space(…)). This option is seldom needed and can be applied only if no omnicomponent phase is present in the system.

Default is False

readwrite

Returns:Flag (bool)

volume

Indicates if volume is an independent variable of the minimal potential and if pressure is a dependent variable

True if yes; False if reverse.

readonly

Returns:Flag (bool)

class equilibrate.EquilState(elements_l, phases_l)

Class for holding the phase state for an equilibrium model determined

by Equilibrate

Parameters:

elements_l : []

A list of strings identifying the chemical elements present in the system

phases_l : []

A list of class instances for phases that are in the system. These instances must derive from the PurePhase or SolutionPhase classes, which are defined in the phases module.

Attributes

c_matrix	Numpy matrix that maps elements to moles of endmembers
c_omni	Numpy conversion matrix for the omnicomponent phase (if one exists)
c_omni_qr	Tuple of Numpy matrices of the Q,R decomposition of c_omni
c_qr_decomp	Tuple of Numpy matrices of the Q,R decomposition of the c_matrix
element_l	List of atomic numbers of elements in the system
phase_d	A dictionary of dictionaries that holds properties of system phases
pressure	Pressure of the assemblage, in bars
temperature	Temperature of the assemblage, in Kelvins

G(t=1000.0, p=1000.0)

Returns Gibbs free energy of the system; a scalar

affinities(phase_name=None)

Returns affinity of phases in the system

Parameters:

phase_name : str, default None

Name of phase in system. If None, returns a dictionary of system phases, with names as keys and ‘stable’ or ‘unstable’ as values.

c_matrix

Numpy matrix that maps elements to moles of endmembers

Moles of endmembers are indexed by row, and moles of elements are indexed by column.

Returns:Numpy 2-D array

c_matrix_for_phase(phase_name)

Returns a slice of c_matrix relevant to the specified phase_name

Parameters:

phase_name : str

Name of a system phase

c_omni

Numpy conversion matrix for the omnicomponent phase (if one exists)

Moles of endmembers are indexed by row, and moles of elements are indexed by column.

Returns:np 2-D array

c_omni_qr

Tuple of Numpy matrices of the Q,R decomposition of c_omni

Returns:tuple

c_qr_decomp

Tuple of Numpy matrices of the Q,R decomposition of the c_matrix

Returns:tuple

compositions(phase_name=None, ctype='components', units='moles')

Returns compositions of phases in the system

Parameters:

phase_name : str, default None

Name of phase in system

ctype : str, default ‘components’

Compositional descriptor. Permitted: ‘components’, ‘oxides’, ‘elements’

units : str, default ‘moles’

Units of composition. Permitted: ‘moles’, ‘mole_frac’, ‘wt%’

Returns:

result : numpy array

One dimensional vector

Notes

If units is set to ‘oxides’ or ‘elements’, results are returned in an array of standard length and order.

d2GdP2(t=1000.0, p=1000.0)

Returns the second pressure derivative of the Gibbs free energy of the system; a scalar, and the negative of the volume times the system’s coefficient of isothermal compressibility

d2GdPdn(t=1000.0, p=1000.0)

Returns the second derivative of G of the system with respect to pressure and mole numbers; a 1-D numpy array

d2GdT2(t=1000.0, p=1000.0)

Returns the second temperature derivative of the Gibbs free energy of the system; a scalar, and the negative of the temperature times the system heat capacity

d2GdTdP(t=1000.0, p=1000.0)

Returns the cross temperature-pressure derivative of the Gibbs free energy of the system; a scalar, and the volume times the system’s coefficient of isothermal expansion

d2GdTdn(t=1000.0, p=1000.0)

Returns the second derivative of G of the system with respect to temperature and mole numbers; a 1-D numpy array

d2Gdn2(t=1000.0, p=1000.0, element_basis=True)

Returns the second molar derivative of G of system; a 2-D numpy array

Parameters:

element_basis : bool, def True

If True, returns a projected Hessian on an element basis

d3GdP2dn(t=1000.0, p=1000.0)

Returns the third derivative of G of the system with respect to pressure twice and mole numbers once; a 1-D numpy array

d3GdP3(t=1000.0, p=1000.0)

Returns the third pressure derivative of the Gibbs free energy of the system; a scalar

d3GdPdn2(t=1000.0, p=1000.0)

Returns the first pressure and second molar derivative of G of system; a 2-D numpy array

d3GdT2dP(t=1000.0, p=1000.0)

Returns the third pressure derivative of the Gibbs free energy of the system; a scalar

d3GdT2dn(t=1000.0, p=1000.0)

Returns the third derivative of G of the system twice with respect to temperature and once with respect to mole numbers; a 1-D numpy array

d3GdT3(t=1000.0, p=1000.0)

Returns the third temperature derivative of the Gibbs free energy of the system; a scalar

d3GdTdP2(t=1000.0, p=1000.0)

Returns the third pressure derivative of the Gibbs free energy of the system; a scalar

d3GdTdPdn(t=1000.0, p=1000.0)

Returns the third derivative of G of the system with respect to temperature, pressure and mole numbers; a 1-D numpy array

d3GdTdn2(t=1000.0, p=1000.0)

Returns the first temperature and second molar derivative of G of system; a 2-D numpy array

d3Gdn3(t=1000.0, p=1000.0, phase=None, cmp=None)

Returns the third molar derivative of G system for the cmp component of the phase named phase as a 2-D numpy array

Parameters:

phase : str, def None

cmp : int, def None

for the phase named phase d3Gdn3[cmp][*][*] is returned

dGdP(t=1000.0, p=1000.0)

Returns the pressure derivative of the Gibbs free energy of the system; a scalar, and the system volume

dGdT(t=1000.0, p=1000.0)

Returns the temperature derivative of the Gibbs free energy of the system; a scalar, and the negative of the system entropy

dGdn(t=1000.0, p=1000.0, element_basis=True, full_output=False, use_omni_phase=False)

Returns the first molar derivative of G of the system; a 1-D numpy array

Parameters:

element_basis : bool, def True

If True, returns a projected array of element chemical potentials

full_output : bool, def False

If True, returns a tuple with full output from numpy lstlq method

use_omni_phase : bool, def False

If True, returns a projected array of element chemical potentials using the omnicomponent phase as a basis. The system must have an omnicomponent phase, and element_basis must be set to True for this keyword to have effect.

element_l

List of atomic numbers of elements in the system

Returns:A Python list

moles_elements(phase_name)

Returns array of moles of elements in phase

Parameters:

phase_name : str

Name of a system phase

Returns:

result : np_array

Numpy array of mole numbers of the reduced set of elements in the phase

moles_v(reaction_v)

Computes of a reaction product

moles (scalar) = (mole vector of all endmembers of all active phases in the system) x (input mole vector of reaction coefficients)

Parameters:

reaction_v : ndarray

Array of reaction coefficients

Returns:

moles : float

Moles of reaction product

omni_phase()

Returns first omnicomponent phase in the phase dictionary

oxide_comp(phase_name, output='wt%', prune_list=True)

Returns a dictionary of concentrations of oxides in phase

Parameters:

phase_name : str

Name of a system phase

output : str, default “wt%”

Units of output: ‘wt%’ (default), ‘moles’, ‘grams’

prune_list : bool, default True

Remove zeroed valued entries

Returns:

result : collections.OrderedDict

Dictionary of oxide concentration values, keyed by oxide

phase_d

A dictionary of dictionaries that holds properties of system phases

Returns:Dictionary of phases in the system (dict)

pressure

Pressure of the assemblage, in bars

Returns:float

print_state(level='summary', wt_as_oxides=True)

Prints results about the system state

Parameters:

level : str

Level of detail to be printed

wt_as_oxides : bool, default True

Print wt% values on an oxide basis; otherwise print wt% of endmember components.

properties(phase_name=None, props=None, units=False)

Returns properties of phases in the system

Parameters:

phase_name : str, default None

Name of phase in system. If None, returns a dictionary of system phases, with names as keys and ‘stable’ or ‘unstable’ as values.

props : str, default None

Name of property to be retrieved. If None, a list of valid properties is returned.

units : bool, default False

Property units are provided as the second entry of a returned tuple.

set_phase_comp(phase_name, cmp, input_as_elements=False)

Sets the endmember moles and total moles a phase in the system

Parameters:

phase_name : str

Name of a system phase

cmp : ndarray

1-D Numpy array with compositional data

input_as_elements : bool, def False

If True, convert input array from moles of elements to moles of endmember components.

Returns:

valid : bool

True if input composition is valid for phase

temperature

Temperature of the assemblage, in Kelvins

Returns:float

tot_grams_phase(phase_name)

Returns total grams of phase

Parameters:

phase_name : str

Name of a system phase

tot_moles_elements()

Returns array of moles of elements in system

Returns:

result : np_array

Numpy array of mole numbers of the reduced set of elements in the system

tot_moles_phase(phase_name)

Returns total moles of phase

Parameters:

phase_name : str

Name of a system phase

class equilibrate.MELTSmodel(version='1.0.2')

Class for creating an instance of the Equilibrate PhaseObjC class that is tailored to calculate equilibrium phase assemblages using one of the MELTS calibrations.

Valid initializers are version=‘1.0.2’, ‘1.1.0’, ‘1.2.0’, ‘5.6.1’, ‘DEW’, ‘OnlyDEW’

add_sheet_to_workbook_named(wb, sheetName)

Creates a new sheet in an existing Excel workbook.

Parameters:

wb : type Workbook

A pointer to an existing Excel workbook

sheetName : string

New sheet name in the specified Excel workbook

Returns:

ws : type Worksheet

A pointer to an Excel worksheet in the specified workbook, wb

Notes

Part of the Excel workbook functions subpackage

equilibrate_sp(S_a, P_a, initialize=False)

Determines the equilibrium phase assemblage at an entropy-pressure point or along a series of S-P points.

The bulk composition of the system must first be set by calling the function:

set_bulk_composition

Parameters:

S_a : float or numpy array of floats

Entropy in Joules per Kelvins. Either a scaler values or a numpy array of float values must be provided.

P_a : float or numpy array of floats

Pressure in mega-Pascals. Either a scaler values or a numpy array of float values must be provided.

NOTE: If both t_a and p_a are arrays, then they must both be the same length.

initialize : bool, optional

True if this is a S-, P-point that starts a sequence of calculations.

False if this is a continuation S-,P-pair or series of pairs.

Returns:

output_a : an array of tuples

tuple = (status, T, P, xmlout):

• status is a string indicating the status of the calculation: success/failiure, Reason for success/failure.
• T is a float value corresponding to the temperature in degrees centigrade.
• P is a float value corresponding to the pressure in mega-Pascals.
• xmlout is an xml document tree of the type xml.etree.ElementTree. The xml tree contains information on the masses and abundances of all phases in the system. xmlout is utilized as input for a number of functions in this package that retrieve properties of the equilibrium assemblage.

Notes

The xmlout document tree will be expanded to include thermodynamic properties of the phases and chemical affinities of phases not present in the equilibrium assemblage.

equilibrate_sv(S_a, V_a, initialize=False)

Determines the equilibrium phase assemblage at an entropy-volume point or along a series of S-V points.

The bulk composition of the system must first be set by calling the function:

set_bulk_composition

Parameters:

S_a : float or numpy array of floats

Entropy in Joules per Kelvins. Either a scaler values or a numpy array of float values must be provided.

V_a : float or numpy array of floats

Volume in Joules per bar. Either a scaler values or a numpy array of float values must be provided.

NOTE: If both t_a and p_a are arrays, then they must both be the same length.

initialize : bool, optional

True if this is a S-, V-point that starts a sequence of calculations.

False if this is a continuation S-,V-pair or series of pairs.

Returns:

output_a : an array of tuples

tuple = (status, T, P, xmlout):

• status is a string indicating the status of the calculation: success/failiure, Reason for success/failure.
• T is a float value corresponding to the temperature in degrees centigrade.
• P is a float value corresponding to the pressure in mega-Pascals.
• xmlout is an xml document tree of the type xml.etree.ElementTree. The xml tree contains information on the masses and abundances of all phases in the system. xmlout is utilized as input for a number of functions in this package that retrieve properties of the equilibrium assemblage.

Notes

The xmlout document tree will be expanded to include thermodynamic properties of the phases and chemical affinities of phases not present in the equilibrium assemblage.

equilibrate_tp(T_a, P_a, initialize=False)

Determines the equilibrium phase assemblage at a temperature-pressure point or along a series of T-P points.

The bulk composition of the system must first be set by calling the function:

set_bulk_composition

Parameters:

t_a : float or numpy array of floats

Temperature in degrees centigrade. Either a scaler values or a numpy array of float values must be provided.

p_a : float or numpy array of floats

Pressure in mega-Pascals. Either a scaler values or a numpy array of float values must be provided.

NOTE: If both t_a and p_a are arrays, then they must both be the same length.

initialize : bool, optional

True if this is a T-, P-point that starts a sequence of calculations.

False if this is a continuation T-,P-pair or series of pairs.

Returns:

output_a : an array of tuples

tuple = (status, T, P, xmlout):

• status is a string indicating the status of the calculation: success/failiure, Reason for success/failure.
• T is a float value corresponding to the temperature in degrees centigrade.
• P is a float value corresponding to the pressure in mega-Pascals.
• xmlout is an xml document tree of the type xml.etree.ElementTree. The xml tree contains information on the masses and abundances of all phases in the system. xmlout is utilized as input for a number of functions in this package that retrieve properties of the equilibrium assemblage.

Notes

The xmlout document tree will be expanded to include thermodynamic properties of the phases and chemical affinities of phases not present in the equilibrium assemblage.

equilibrate_tv(T_a, V_a, initialize=False)

Determines the equilibrium phase assemblage at a temperature-volume point or along a series of T-V points.

The bulk composition of the system must first be set by calling the function:

set_bulk_composition

Parameters:

T_a : float or numpy array of floats

Temperature in degrees centigrade. Either a scaler values or a numpy array of float values must be provided.

V_a : float or numpy array of floats

Volume in Joules per bar. Either a scaler values or a numpy array of float values must be provided.

NOTE: If both t_a and p_a are arrays, then they must both be the same length.

initialize : bool, optional

True if this is a T-, V-point that starts a sequence of calculations.

False if this is a continuation T-,V-pair or series of pairs.

Returns:

output_a : an array of tuples

tuple = (status, T, P, xmlout):

• status is a string indicating the status of the calculation: success/failiure, Reason for success/failure.
• T is a float value corresponding to the temperature in degrees centigrade.
• P is a float value correcponding to the pressure in mega-Pascals.
• xmlout is an xml document tree of the type xml.etree.ElementTree. The xml tree contains information on the masses and abundances of all phases in the system. xmlout is utilized as input for a number of functions in this package that retrieve properties of the equilibrium assemblage.

Notes

The xmlout document tree will be expanded to include thermodynamic properties of the phases and chemical affinities of phases not present in the equilibrium assemblage.

fractionate_phases(root, frac_coeff)

Fractionates phases from the system. Partitions and maintains an internal dictionary of fractionates and automatically modifies system bulk composition to reflect fractionation.

Parameters:

root : type xml.etree.ElementTree

An xml document tree returned by the function equilibrate_xx

frac_coeff : dictionary

A dictionary keyed on phase names with values that indicate the fraction of each phase that should fractionate.

See get_dictionary_of_default_fractionation_coefficients().

Returns:

dict : dictionary

A dictionary keyed on phase names with values corresponding to a dictionary of phase properties. Keys are property names.

get_composition_of_phase(root, phase_name='System', mode='oxide_wt')

Returns the composition of a phase in the specified equilibrium assemblage as a dictionary, with composition tabluated in the specified mode.

Parameters:

root : type xml.etree.ElementTree

An xml document tree returned by the function equilibrate_xx

phase_name : string, optional

The name of the phase whose abundance is requested, or the string ‘System’, which returns the combined mass of all phases in the system. Default value is ‘System’.

mode : string, optional

Controls the contents of the returned dictionary.

• ‘formula’ returns a dictionary with the string ‘formula’ as key and value set to a string representation of the phase formula. For pure component phases, this is the standard phase formula. For solutions, this is the actual formula constructed by weighting the endmember components by their mole fractions.
• ‘oxide_wt’ returns a dictionary of oxide string keys with values in wt%. This is a valid mode for all phase_name entries.
• ‘component’ returns a dictionary of endmember component keys with values in mole fraction. The length of this dictionary will vary dependening on the number of components that describe the solution. Pure phases return an empty dictionary, as does phase_name set to ‘System’.

The default value of mode is ‘oxide_wt’.

Returns:

dict : dictionary

A dictionary describing the composition of phase_name according to the mode specified. The dictionary will be empty if phase_name is not present in the equilibrium assemblage. It will also be empty for certain cases described above under mode.

get_dictionary_of_affinities(root, sort=True)

Returns an ordered dictionary of tuples of chemical affinity and phase formulae for undersaturated phases in the system.

Parameters:

root : type xml.etree.ElementTree

An xml document tree returned by the function equilibrate_xx

sort : boolean

A flag when set to sort the dictionary in order of ascending affinities

Returns:

dict : OrderedDict

A Python ordered dictionary. Dictionary keys are strings naming the phases not in the equilibrium assemblage but known to the system. These phases are by definition undersaturated. Dictionary values are tuples consisting of a float value and a string: (affinity, formula). For a solution phase, the formula is the composition closest to equilibrium with the reported phase assemblage. Dictionary ordering corresponds to array order in get_phase_names(), unless sorted is set to True; then entries are ordered by ascending chemical affinity.

get_dictionary_of_default_fractionation_coefficients(fracLiq=False, fracSolid=True, fracFluid=True, fracCoeff=1.0)

Returns a dictionary of default coefficients for phase fractionation.

These coefficients may be modified by the user. They are used when setting the extent to which a phase will fractionate from the equilibrium assemblage.

Parameters:

fracLiq : bool, optional

Flag to indicate if liquid phases should be fractionated from the system. Default is False.

fracSolids : bool, optional

Flag to indicate if solid phases should be fractionated from the system. Default is True.

fracFluids : bool, optional

Flag to indicate if fluid phases should be fractionated from the system. Default is True.

fracCoeff : float, optional

Fractionation coefficient, which gives the fractional extend to which the mass of the phase is extracted during phase fractionation. Default is 1.0 (100%).

Returns:

dict : dictionary

A Python dictionary keyed on phases with values giving the extent (in fractional units) that a phase will fractionation mass.

Notes

This dictionary is provided as input to the function fractionate_phases(). The default configuration fractionates all solid/fluid phases and retains liquid.

get_list_of_phases_in_assemblage(root)

Returns a list of phases in the specified equilibrium assemblage.

Parameters:

root : type xml.etree.ElementTree

An xml document tree returned by the function equilibrate_xx

Returns:

list : list

A Python list of all phases in the equilibrium assemblage

get_list_of_properties()

Returns a list of properties reported for each phase in an equilibrium assemblage.

Returns:

list : list

A Python list of all properties of phases in an equilibrium assemblage

get_mass_of_phase(root, phase_name='System')

Returns the mass of a phase in the specified equilibrium assemblage.

Parameters:

root : type xml.etree.ElementTree

An xml document tree returned by the function equilibrate_xx

phase_name : string, optional

The name of the phase whose abundance is requested, or the string ‘System’, which returns the combined mass of all phases in the system. Default value is ‘System’.

Returns:

value : float

The mass of the phase in the equilibrium assemblage specified by root, in grams. If the specified phase is not in the equilibrium assemblage, a value of zero is retuned.

get_object_for_phase(phase_name)

Retrieve an object instance for the named phase.

Parameters:

phase_name: string

Name of phase

Returns:

object: instance of a phase class

null if the phase is not in the stable assemblage

get_oxide_names()

Retrieves a list of system oxides

Composition of the system can be expressed in terms of these oxides.

Returns:

array : strings

An array of strings naming system components in terms of oxides

get_phase_inclusion_status()

Retrieves a dictionary of the inclusion status of each phase

Returns:

dict : dictionary

A dictionary of boolean values indicating the inclusion status of each phase (key) known to the system

get_phase_names()

Retrieves a list of system phases

Names of phases known to the system

Returns:

array : strings

An array of strings naming system phases

get_properties_of_DEWFluid(property_name='species', T=1000, P=1000)

Retrieves a dictionary of properties of the specified type

DEWFluid must exist in the equilibrium assemblage; otherwise an empty dictionary is returned.

Parameters:

property_name: string, optional

‘species’ (default) returns a dictionary of species mole fractions in the equilibrated solution.

‘mu’ returns a dictionary of species chemical potentials in the equilibrated solution.

‘activity’ returns a dictionary of species activities in the equilibrated solution.

T : float optional

Temperature in degrees centigrade (default is 1000°C)

P : float optional

Pressure in bars (default is 1000 bars)

Returns:

dictionary: a python dictionary

Keys are species names (strings).

Values are species concentrations in mole fraction, or chemical potential, or thermodynamic activity, depending on the value of property_name.

get_property_of_phase(root, phase_name='System', property_name='Mass')

Returns the specified property of a phase in the specified equilibrium assemblage.

Parameters:

root : type xml.etree.ElementTree

An xml document tree returned by the function equilibrate_xx

phase_name : string, optional

The name of the phase whose property is requested, or the string ‘System’, which returns the combined property of all phases in the system. Default value is ‘System’.

property_name : string, optional

The name of the property to be returned. Default value is ‘Mass’.

Returns:

value : float

The property of the phase in the equilibrium assemblage specified by root, in standard units. If the specified phase is not in the equilibrium assemblage, a value of zero is returned. If the property is not in the standard list, a value of zero is returned.

get_thermo_properties_of_phase_components(root, phase_name, mode='mu')

Returns a dictionary of the specified component thermodynamic properties of the designated phase.

Parameters:

root : type xml.etree.ElementTree

An xml document tree returned by the function equilibrate_xx.

phase_name : string

The name of the phase whose abundance is requested.

mode : string, optional

Controls the contents of the returned dictionary.

• ‘mu’ returns a dictionary of endmember component keys with values of chemical potential. The length of this dictionary will vary depending on the number of components that describe the solution. Pure phases return a dictionary of unit length, with the phase name as key and their specific Gibbs free energy as value (J/g).
• ‘excess’ returns a dictionary of endmember component keys with values of excess chemical potential. The length of this dictionary will vary depending on the number of components that describe the solution. Pure phases return a dictionary of unit length, with the phase name as key and zero as value.
• ‘activity’ returns a dictionary of endmember component keys with values of component activity. The length of this dictionary will vary depending on the number of components that describe the solution. Pure phases return a dictionary of unit length, with the phase name as key and unity as value.

Returns:

dict : dictionary

A dictionary describing the thermodynamic properties of components in phase_name according to the mode specified. The dictionary will be empty if phase_name is not present in the equilibrium assemblage.

get_units_of_property(prop='Mass')

Returns the units of a specified property.

Returns:

string : string

The units of the specified property. Returns ‘none’ if property is invalid.

output_summary(root, printT=True, printP=True, printMass=False, printSysWt=False, printSysM=False, printPhs=True, printPhsWt=False, printPhsM=False)

Prints information about the specified equilibrium phase assemblage.

Parameters:

root : type xml.etree.ElementTree

An xml document tree returned by the function equilibrate_tp

printT : bool, optional, default=True

Print the system temperature in degrees centigrade

printP : bool, optional, default=True

Print the system pressure in mega-Pascals

printMass ; bool, optional, default=False

Print the mass of the system in grams

printSysWt : bool, optional, default=False

Print the composition of the system in wt% oxides

printSysM : bool, optional, default=False

Print the composition of the system in moles of elements

printPhs : bool, optional, default=True

Print the phases present in the system, their masses (in grams) and their chemical formulas

printPhsWt : bool, optional, default=False

Print the composition of each phase in wt% oxides (most often used in conjunction with printPhs=True)

printPhsM : bool, optional, default=False

Print the composition of each phase in moles of endmember components (most often used in conjunction with printPhs=True)

print_default_settings()

Prints list of options and tolerance settings for algorithm.

set_bulk_composition(oxide_d={})

Sets the bulk composition of the system

This function first tests if the composition is feasible before setting the bulk composition of the system. You should check to make sure that the composition is feasible before proceeding.

Parameters:

oxide_d : a python dictionary

A dictionary of oxide names and values, e.g. {‘SiO2’:77.8, ‘Al2O3’:12.0, …, ‘H2O’:3.74}

Returns:

boolean : True or False

True if the composition is feasible, in which case the composition of the system is defined.

False if the composition is infeasible, in which case the composition of the system is undefined.

Notes

Feasibility call has yet to be implemented: (Objective-C method call:) -(BOOL)compositionIsFeasible:(NSArray *)compositionInWtPercentOxides forSolution:(id <SolutionPhaseProtocol>)omniComponentPhase;

set_debug_state(debugS=False, debugV=False)

Sets debug output level for Equilibrate class and subclasses

Parameters:

debugS : boolean, optional

Sets on or off low level debug output. Default is off (False).

debugV : boolean, optional

Sets on or off high level debug output. Default is off (False).

set_entropy(s)

Sets the entropy of the system and reinitializes a calculation sequence

Parameters:

s : float

Float value to set the system entropy in J/K.

set_phase_inclusion_status(status_d)

Sets the inclusion status of specified phases

Parameters:

status_d : dictionary

A dictionary of phase name keys and boolean values. True sets inclusion, and False prevents inclusion of a phase in the equilibrium assemblage. Note that the chemical affinity of the phase will still be calculated even if the inclusion level is set to False.

set_pressure(p_mpa=200.0)

Sets the pressure of the system and reinitializes a calculation sequence

Parameters:

p_mpa : float optional

Float value to set the system pressure in mega-Pascals. Default is 200 MPa.

set_temperature(t_c=800.0)

Sets the temperature of the system and reinitializes a calculation sequence

Parameters:

t_c : float optional

Float value to set the system temperature in degrees centigrade. Default is 800 °C.

set_volume(v)

Sets the volume of the system and reinitializes a calculation sequence

Parameters:

v : float

Float value to set the system volume in J/bar

start_excel_workbook_with_sheet_name(sheetName='Summary')

Create an Excel workbook with one named sheet.

Parameters:

sheetName : string

Sheet name in the new empty Excel workbook

Returns:

wb : type Workbook

A pointer to an Excel workbook

Notes

Part of the Excel workbook functions subpackage

update_excel_workbook(wb, root)

Writes the specified equilibrium system state to the specified Excel workbook.

Parameters:

wb : type Workbook

A pointer to an existing Excel workbook

root : type xml.etree.ElementTree

An xml document tree returned by the function equilibrate_tp

Notes

The workbook is structured with a Summary worksheet and one worksheet for each equilibrium phase. The evolution of the system is recorded in successive rows. Row integrity is maintained across all sheets. This function may be called repeatedly using different root objects. Part of the Excel workbook functions subpackage.

write_excel_workbook(wb, fileName='junk.xlsx')

Writes the specified Excel workbook to disk.

Parameters:

wb : type Workbook

A pointer to an existing Excel workbook

fileName : string, optional

Name of the file that will contain the specified Excel notebook. Default file name is ‘junk.xlsx’.

Notes

Part of the Excel workbook functions subpackage

write_to_cell_in_sheet(ws, col, row, value, format='general')

Writes information into the specified row, col on the specified worksheet.

Parameters:

ws : type Worksheet

A pointer to a previously created Excel worksheet (see add_sheet_to_workbook_named)

col : int

Column number to write entry to. Numbering starts at column one.

row : int

Row number to write entry to. Numbering starts at row one.

value : float

Value to place at entry

format : string, optional

Format to use for value

• ‘general’ is the default; no formatting applied
• ‘number’ formats as ‘0.00’
• ‘scientific’ formats as ‘0.00E+00’

Notes

Part of the Excel workbook functions subpackage