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)[source]¶ 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
bulk_comp
Bulk composition of the system as moles of elements
CTf
Stoichiometric vectors of element concentrations that embody the
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
eps_linear
Convergence criteria for the norm of the linear projection phase of the
eps_minimal_energy
Tolerance for establishing criteria for a minimum in the system potential.
eps_quad_optimal
Convergence criteria for the norm of the quadratic projection phase of
eps_quad_suboptimal
Relaxed convergence criteria for the norm of the quadratic projection
eps_rank
Tolerance for establishing the rank of the projected Hessian, which is
equil_cycle_max
Number of addition/removal cycles allowed for a phase before it is
equil_linear_min
Number of successful linear minimization attempts that do not result in a subsequent dimunition of the quadratic norm after which convergence is accepted as a “minimal energy” condition.
lagrange_list
A list of tuples characterizing the Lagrange transformation of the
lagrange_moles
Moles of chemical potential entities stipulated in dictionaries,
lagrange_no_mol_deriv
Produces a simplified gradient and hessian of the generalized
lagrange_use_omni
If set to True, the algorithm uses the omnicomponent phase exclusively to balance non-linear constraint reactions.
max_linear_iters
Maximum number of linear search steps associated with each quadratic
max_quad_iters
Maximum number of Newton quadratic minimization steps allowed in
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
use_numpy_lstsq
Flag to toggle method used to solve for quadratic search direction
volume
Indicates if volume is an independent variable of the minimal potential
VT_null
Orthogonal projection operator obtained from constraints on chemical
-
property
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
-
property
CTf
¶ Stoichiometric vectors of element concentrations that embody the Lagrange constraints
Default is None
readonly
- Returns
- np_array or None
-
property
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
-
property
bulk_comp
¶ Bulk composition of the system as moles of elements
readwrite
- Returns
- numpy array
-
property
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
-
property
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)
-
property
eps_linear
¶ Convergence criteria for the norm of the linear projection phase of the equilibrium calculation
readwrite
- Returns
- Convergence tolerance (number)
-
property
eps_minimal_energy
¶ Tolerance for establishing criteria for a minimum in the system potential.
Successive linear minimization attempts (equil_linear_min) that do not result in a subsequent dimunition of the quadratic norm within this tolerance result in convergence as a “minimal energy” condition.
readwrite
- Returns
- Tolerance (number)
-
property
eps_quad_optimal
¶ Convergence criteria for the norm of the quadratic projection phase of the equilibrium calculation
readwrite
- Returns
- Convergence tolerance (number)
-
property
eps_quad_suboptimal
¶ Relaxed convergence criteria for the norm of the quadratic projection phase of the equilibrium calculation
readwrite
- Returns
- Convergence tolerance (number)
-
property
eps_rank
¶ Tolerance for establishing the rank of the projected Hessian, which is needed to compute a valid quadratic search direction
readwrite
- Returns
- Tolerance (number)
-
property
equil_cycle_max
¶ Number of addition/removal cycles allowed for a phase before it is suppressed from the equilibrium assemblage
readwrite
- Returns
- Iteration limit (int)
-
property
equil_linear_min
¶ Number of successful linear minimization attempts that do not result in a subsequent dimunition of the quadratic norm after which convergence is accepted as a “minimal energy” condition.
readwrite
- Returns
- Iteration limit (int)
-
execute
(self, t=1000.0, p=1000.0, bulk_comp=None, state=None, con_deltaNNO=None, debug=0, stats=False)[source]¶ Calculates an equilibrium assemblage, returning the results as an instance of the EquilState class
- Parameters
- tfloat, default 1000.0
Temperature in Kelvins
- pfloat, default 1000.0
Pressure in bars
- bulk_compnumpy array, default None
Bulk composition of the system. Array of element concentrations, of the length and order of self.element_list
- stateEquilState, 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.
- con_deltaNNOfloat or None
A non-None value for this parameter is ignored unless the system contains an omnicomponnet liquid phase of either 15 or 16 endmember components modeled after Ghiorso and Sack (1995) or Ghiorso and Gualda (2015), i.e. a MELTS silicate liquid thermodynamic model. If a value is set, the liquid is constrained to follow the nickel- nickel oxide oxygen buffer plus the offset value, con_deltaNNO, which is specified in log 10 fO2 units. For example, a value of 1.0 will force the system to equilibrate on the NNO+1 oxygen buffer by adjusting the ratio of ferric and ferrous iron according to the Kress and Carmichael (1991) calibration. Setting a value permits the system to be open to oxygen transfer; the bulk moles of oxygen in the system is no longer constrained by input bulk composition.
- debugint, 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
- statsbool, default False
Toggle printing of statistics associated with calculation progress
- 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.
-
kc_ferric_ferrous
(self, t, p, m, mtype='components', compute='logfO2', deltaNNO=0.0, debug=0)[source]¶ Calculates oxygen fugacity or ferric-ferrous ratio for silicate melts using the Kress and Carmichael (1991) calibration
- Parameters
- tfloat
Temperature in Kelvins
- pfloat
Pressure in bars
- mnumpy ndarray
An array of moles of endmember liquid components correcponding to the model of Ghiorso and Sack (1995) (m has length 15) or the model of Ghiorso and Gualda (2015) (m has length 16)
- mtypestr, default ‘components’
Type of values in m.
- computestr, default ‘logfO2’
Type of output requested, see Returns.
- deltaNNOfloat, default 0.0
If ferric-ferrous computation if requested (see compute), the ratio will be computed at log 10 f O2 = nickel-nickel oxide + deltaNNO
- debugint, 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
- resultfloat
log 10 f O2, if compute is set to ‘logfO2’ (default) excess chemical potential of O2, if compute is set to ‘chem_pot’
- resultnumpy ndarray
array of oxide values, with the computed ferric-ferrous ratio appropriate to the imposed log f O2. The oxides are in standard order: SiO2, TiO2, Al2O3, Fe2O3, Cr2O3, FeO, MnO, MgO, NiO, CoO, CaO, Na2O, K2O, P2O5, H2O, [CO2]
-
kc_print_state
(self, state=None, silent=False)[source]¶ Prints information about the current system state in terms of the Kress and Carmichael (1991) ferrous-ferric equilibrium model
- Parameters
- stateEquilState, 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.
- silentbool, default False
Flag to silence printing
- Returns
- resulttuple or None
Returns None if state is None or the system does not contain an omnicomponent phase name ‘Liquid’, else returns a tuple with the computer log 10 fO2 of the liquid phase relative to the NNO oxygen buffer, the value of log 10 fO2 on the buffer, and the total number of moles of oxygen in the system
-
property
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:
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.
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
-
property
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
-
property
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)
-
property
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)
-
log10NNO
(self, t, p)[source]¶ Calculates the base 10 logarithm of oxygen fugacity along the nickel- nickel oxide buffer
- Parameters
- tfloat
Temperature in Kelvins
- pfloat
Pressure in bars
- Returns
- resultfloat
log (10) f O2
Notes
Algorithm from O’Neill and Pownceby (1993, Contributions to Mineralogy and Petrology, 114, 296-314) using the pressure correction suggested by Frost (1991, Mineralogical Society of America, Reviews in Mineralogy, v. 25, 1-9)
-
property
max_linear_iters
¶ Maximum number of linear search steps associated with each quadratic iteration
readwrite
- Returns
- Number of linear search steps (int)
-
property
max_quad_iters
¶ Maximum number of Newton quadratic minimization steps allowed in computation
readwrite
- Returns
- Number of steps allowed (int)
-
property
moles_in
¶ Moles of phase added to the system on detection of saturation
readwrite
- Returns
- Number of moles added (number)
-
property
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)
-
mu0O2
(self, t, p)[source]¶ Calculates the chemical potential of oxygen gas in the standard state of unit fugacity at one bar and any tenperature
- Parameters
- tfloat
Temperature in Kelvins
- pfloat
Pressure in bars
- Returns
- resultfloat
standard state chemical potential in Joules/mole of O2 gas
Notes
Algorithm from Berman (1988).
-
muNNO
(self, t, p, delta=0.0)[source]¶ Calculates the excess chemical potential of oxygen along the nickel- nickel oxide (+ delta offset) buffer
- Parameters
- tfloat
Temperature in Kelvins
- pfloat
Pressure in bars
- deltafloat, default 0.0
Offset in base 10 log units relative to the nickel-nickel oxide oxygen buffer
- Returns
- resultfloat
Excess chemical potential of oxygen in Joules/mole of O2
Notes
See definition of function log10NNO(t, p)
-
property
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
-
property
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)
-
property
reactions
¶ Balanced reactions pertaining to the Lagrange constraints
Default is None
readonly
- Returns
- np.array or None
-
property
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)
-
property
use_numpy_lstsq
¶ Flag to toggle method used to solve for quadratic search direction
The quadratic search direction, dn, is computed by solving a system of equations given by H dn = -g, where H is the projected Hessian and g the projected gradient of the system potential (e.g., the system Gibbs free energy). If use_numpy_lstsq is True (default), the solution method is numpy’s linalg.lstsq method. If False, a QR decomposition method from the Python package statsmodels is utilized. The numpy method uses SVD decomposition and is slower, but more tolerant of rank deficient solutions (e.g., near phase rule violations).
- Returns
- Flag (bool)
-
property
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)[source]¶ 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
-
affinities
(self, phase_name=None)[source]¶ Returns affinity of phases in the system
- Parameters
- phase_namestr, 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.
-
property
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
(self, phase_name)[source]¶ Returns a slice of c_matrix relevant to the specified phase_name
- Parameters
- phase_namestr
Name of a system phase
-
property
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
-
property
c_omni_qr
¶ Tuple of Numpy matrices of the Q,R decomposition of c_omni
- Returns
- tuple
-
property
c_qr_decomp
¶ Tuple of Numpy matrices of the Q,R decomposition of the c_matrix
- Returns
- tuple
-
compositions
(self, phase_name=None, ctype='components', units='moles')[source]¶ Returns compositions of phases in the system
- Parameters
- phase_namestr, default None
Name of phase in system
- ctypestr, default ‘components’
Compositional descriptor. Permitted: ‘components’, ‘oxides’, ‘elements’
- unitsstr, default ‘moles’
Units of composition. Permitted: ‘moles’, ‘mole_frac’, ‘wt%’
- Returns
- resultnumpy 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
(self, t=1000.0, p=1000.0)[source]¶ 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
(self, t=1000.0, p=1000.0)[source]¶ Returns the second derivative of G of the system with respect to pressure and mole numbers; a 1-D numpy array
-
d2GdT2
(self, t=1000.0, p=1000.0)[source]¶ 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
(self, t=1000.0, p=1000.0)[source]¶ 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
(self, t=1000.0, p=1000.0)[source]¶ Returns the second derivative of G of the system with respect to temperature and mole numbers; a 1-D numpy array
-
d2Gdn2
(self, t=1000.0, p=1000.0, element_basis=True)[source]¶ Returns the second molar derivative of G of system; a 2-D numpy array
- Parameters
- element_basisbool, def True
If True, returns a projected Hessian on an element basis
-
d3GdP2dn
(self, t=1000.0, p=1000.0)[source]¶ Returns the third derivative of G of the system with respect to pressure twice and mole numbers once; a 1-D numpy array
-
d3GdP3
(self, t=1000.0, p=1000.0)[source]¶ Returns the third pressure derivative of the Gibbs free energy of the system; a scalar
-
d3GdPdn2
(self, t=1000.0, p=1000.0)[source]¶ Returns the first pressure and second molar derivative of G of system; a 2-D numpy array
-
d3GdT2dP
(self, t=1000.0, p=1000.0)[source]¶ Returns the third pressure derivative of the Gibbs free energy of the system; a scalar
-
d3GdT2dn
(self, t=1000.0, p=1000.0)[source]¶ 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
(self, t=1000.0, p=1000.0)[source]¶ Returns the third temperature derivative of the Gibbs free energy of the system; a scalar
-
d3GdTdP2
(self, t=1000.0, p=1000.0)[source]¶ Returns the third pressure derivative of the Gibbs free energy of the system; a scalar
-
d3GdTdPdn
(self, t=1000.0, p=1000.0)[source]¶ Returns the third derivative of G of the system with respect to temperature, pressure and mole numbers; a 1-D numpy array
-
d3GdTdn2
(self, t=1000.0, p=1000.0)[source]¶ Returns the first temperature and second molar derivative of G of system; a 2-D numpy array
-
d3Gdn3
(self, t=1000.0, p=1000.0, phase=None, cmp=None)[source]¶ Returns the third molar derivative of G system for the cmp component of the phase named phase as a 2-D numpy array
- Parameters
- phasestr, def None
- cmpint, def None
for the phase named phase d3Gdn3[cmp][*][*] is returned
-
dGdP
(self, t=1000.0, p=1000.0)[source]¶ Returns the pressure derivative of the Gibbs free energy of the system; a scalar, and the system volume
-
dGdT
(self, t=1000.0, p=1000.0)[source]¶ Returns the temperature derivative of the Gibbs free energy of the system; a scalar, and the negative of the system entropy
-
dGdn
(self, t=1000.0, p=1000.0, element_basis=True, full_output=False, use_omni_phase=False)[source]¶ Returns the first molar derivative of G of the system; a 1-D numpy array
- Parameters
- element_basisbool, def True
If True, returns a projected array of element chemical potentials
- full_outputbool, def False
If True, returns a tuple with full output from numpy lstlq method
- use_omni_phasebool, 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.
-
property
element_l
¶ List of atomic numbers of elements in the system
- Returns
- A Python list
-
moles_elements
(self, phase_name)[source]¶ Returns array of moles of elements in phase
- Parameters
- phase_namestr
Name of a system phase
- Returns
- resultnp_array
Numpy array of mole numbers of the reduced set of elements in the phase
-
moles_v
(self, reaction_v)[source]¶ 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_vndarray
Array of reaction coefficients
- Returns
- molesfloat
Moles of reaction product
-
oxide_comp
(self, phase_name, output='wt%', prune_list=True)[source]¶ Returns a dictionary of concentrations of oxides in phase
- Parameters
- phase_namestr
Name of a system phase
- outputstr, default “wt%”
Units of output: ‘wt%’ (default), ‘moles’, ‘grams’
- prune_listbool, default True
Remove zeroed valued entries
- Returns
- resultcollections.OrderedDict
Dictionary of oxide concentration values, keyed by oxide
-
property
phase_d
¶ A dictionary of dictionaries that holds properties of system phases
- Returns
- Dictionary of phases in the system (dict)
-
property
pressure
¶ Pressure of the assemblage, in bars
- Returns
- float
-
print_state
(self, level='summary', wt_as_oxides=True)[source]¶ Prints results about the system state
- Parameters
- levelstr
Level of detail to be printed
- wt_as_oxidesbool, default True
Print wt% values on an oxide basis; otherwise print wt% of endmember components.
-
properties
(self, phase_name=None, props=None, units=False)[source]¶ Returns properties of phases in the system
- Parameters
- phase_namestr, 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.
- propsstr, default None
Name of property to be retrieved. If None, a list of valid properties is returned.
- unitsbool, default False
Property units are provided as the second entry of a returned tuple.
-
set_phase_comp
(self, phase_name, cmp, input_as_elements=False)[source]¶ Sets the endmember moles and total moles a phase in the system
- Parameters
- phase_namestr
Name of a system phase
- cmpndarray
1-D Numpy array with compositional data
- input_as_elementsbool, def False
If True, convert input array from moles of elements to moles of endmember components.
- Returns
- validbool
True if input composition is valid for phase
-
property
temperature
¶ Temperature of the assemblage, in Kelvins
- Returns
- float
-
tot_grams_phase
(self, phase_name)[source]¶ Returns total grams of phase
- Parameters
- phase_namestr
Name of a system phase
-
class
equilibrate.
MELTSmodel
(version='1.0.2')[source]¶ 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
(self, wb, sheetName)[source]¶ Creates a new sheet in an existing Excel workbook.
- Parameters
- wbtype Workbook
A pointer to an existing Excel workbook
- sheetNamestring
New sheet name in the specified Excel workbook
- Returns
- wstype Worksheet
A pointer to an Excel worksheet in the specified workbook,
wb
Notes
Part of the Excel workbook functions subpackage
-
equilibrate_sp
(self, S_a, P_a, initialize=False)[source]¶ 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_afloat 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_afloat 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
andp_a
are arrays, then they must both be the same length.- initializebool, 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_aan 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
(self, S_a, V_a, initialize=False)[source]¶ 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_afloat 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_afloat 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
andp_a
are arrays, then they must both be the same length.- initializebool, 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_aan 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
(self, T_a, P_a, initialize=False)[source]¶ 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_afloat or numpy array of floats
Temperature in degrees centigrade. Either a scaler values or a numpy array of float values must be provided.
- p_afloat 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
andp_a
are arrays, then they must both be the same length.- initializebool, 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_aan 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
(self, T_a, V_a, initialize=False)[source]¶ 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_afloat or numpy array of floats
Temperature in degrees centigrade. Either a scaler values or a numpy array of float values must be provided.
- V_afloat 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
andp_a
are arrays, then they must both be the same length.- initializebool, 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_aan 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
(self, root, frac_coeff)[source]¶ Fractionates phases from the system. Partitions and maintains an internal dictionary of fractionates and automatically modifies system bulk composition to reflect fractionation.
- Parameters
- roottype xml.etree.ElementTree
An xml document tree returned by the function
equilibrate_xx
- frac_coeffdictionary
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
- dictdictionary
A dictionary keyed on phase names with values corresponding to a dictionary of phase properties. Keys are property names.
-
get_composition_of_phase
(self, root, phase_name='System', mode='oxide_wt')[source]¶ Returns the composition of a phase in the specified equilibrium assemblage as a dictionary, with composition tabluated in the specified mode.
- Parameters
- roottype xml.etree.ElementTree
An xml document tree returned by the function
equilibrate_xx
- phase_namestring, 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’.
- modestring, 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 allphase_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
- dictdictionary
A dictionary describing the composition of
phase_name
according to themode
specified. The dictionary will be empty ifphase_name
is not present in the equilibrium assemblage. It will also be empty for certain cases described above undermode
.
-
get_dictionary_of_affinities
(self, root, sort=True)[source]¶ Returns an ordered dictionary of tuples of chemical affinity and phase formulae for undersaturated phases in the system.
- Parameters
- roottype xml.etree.ElementTree
An xml document tree returned by the function
equilibrate_xx
- sortboolean
A flag when set to sort the dictionary in order of ascending affinities
- Returns
- dictOrderedDict
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
(self, fracLiq=False, fracSolid=True, fracFluid=True, fracCoeff=1.0)[source]¶ 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
- fracLiqbool, optional
Flag to indicate if liquid phases should be fractionated from the system. Default is False.
- fracSolidsbool, optional
Flag to indicate if solid phases should be fractionated from the system. Default is True.
- fracFluidsbool, optional
Flag to indicate if fluid phases should be fractionated from the system. Default is True.
- fracCoefffloat, 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
- dictdictionary
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
(self, root)[source]¶ Returns a list of phases in the specified equilibrium assemblage.
- Parameters
- roottype xml.etree.ElementTree
An xml document tree returned by the function
equilibrate_xx
- Returns
- listlist
A Python list of all phases in the equilibrium assemblage
-
get_list_of_properties
(self)[source]¶ Returns a list of properties reported for each phase in an equilibrium assemblage.
- Returns
- listlist
A Python list of all properties of phases in an equilibrium assemblage
-
get_mass_of_phase
(self, root, phase_name='System')[source]¶ Returns the mass of a phase in the specified equilibrium assemblage.
- Parameters
- roottype xml.etree.ElementTree
An xml document tree returned by the function
equilibrate_xx
- phase_namestring, 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
- valuefloat
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
(self, phase_name)[source]¶ 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
(self)[source]¶ Retrieves a list of system oxides
Composition of the system can be expressed in terms of these oxides.
- Returns
- arraystrings
An array of strings naming system components in terms of oxides
-
get_phase_inclusion_status
(self)[source]¶ Retrieves a dictionary of the inclusion status of each phase
- Returns
- dictdictionary
A dictionary of boolean values indicating the inclusion status of each phase (key) known to the system
-
get_phase_names
(self)[source]¶ Retrieves a list of system phases
Names of phases known to the system
- Returns
- arraystrings
An array of strings naming system phases
-
get_properties_of_DEWFluid
(self, property_name='species', T=1000, P=1000)[source]¶ 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.
- Tfloat optional
Temperature in degrees centigrade (default is 1000°C)
- Pfloat 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
(self, root, phase_name='System', property_name='Mass')[source]¶ Returns the specified property of a phase in the specified equilibrium assemblage.
- Parameters
- roottype xml.etree.ElementTree
An xml document tree returned by the function
equilibrate_xx
- phase_namestring, 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_namestring, optional
The name of the property to be returned. Default value is ‘Mass’.
- Returns
- valuefloat
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
(self, root, phase_name, mode='mu')[source]¶ Returns a dictionary of the specified component thermodynamic properties of the designated phase.
- Parameters
- roottype xml.etree.ElementTree
An xml document tree returned by the function
equilibrate_xx
.- phase_namestring
The name of the phase whose abundance is requested.
- modestring, 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
- dictdictionary
A dictionary describing the thermodynamic properties of components in
phase_name
according to themode
specified. The dictionary will be empty ifphase_name
is not present in the equilibrium assemblage.
-
get_units_of_property
(self, prop='Mass')[source]¶ Returns the units of a specified property.
- Returns
- stringstring
The units of the specified property. Returns ‘none’ if property is invalid.
-
output_summary
(self, root, printT=True, printP=True, printMass=False, printSysWt=False, printSysM=False, printPhs=True, printPhsWt=False, printPhsM=False)[source]¶ Prints information about the specified equilibrium phase assemblage.
- Parameters
- roottype xml.etree.ElementTree
An xml document tree returned by the function
equilibrate_tp
- printTbool, optional, default=True
Print the system temperature in degrees centigrade
- printPbool, optional, default=True
Print the system pressure in mega-Pascals
- printMass ; bool, optional, default=False
Print the mass of the system in grams
- printSysWtbool, optional, default=False
Print the composition of the system in wt% oxides
- printSysMbool, optional, default=False
Print the composition of the system in moles of elements
- printPhsbool, optional, default=True
Print the phases present in the system, their masses (in grams) and their chemical formulas
- printPhsWtbool, optional, default=False
Print the composition of each phase in wt% oxides (most often used in conjunction with printPhs=True)
- printPhsMbool, optional, default=False
Print the composition of each phase in moles of endmember components (most often used in conjunction with printPhs=True)
-
set_bulk_composition
(self, oxide_d={})[source]¶ 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_da python dictionary
A dictionary of oxide names and values, e.g. {‘SiO2’:77.8, ‘Al2O3’:12.0, …, ‘H2O’:3.74}
- Returns
- booleanTrue 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
(self, debugS=False, debugV=False)[source]¶ Sets debug output level for Equilibrate class and subclasses
- Parameters
- debugSboolean, optional
Sets on or off low level debug output. Default is off (False).
- debugVboolean, optional
Sets on or off high level debug output. Default is off (False).
-
set_entropy
(self, s)[source]¶ Sets the entropy of the system and reinitializes a calculation sequence
- Parameters
- sfloat
Float value to set the system entropy in J/K.
-
set_phase_inclusion_status
(self, status_d)[source]¶ Sets the inclusion status of specified phases
- Parameters
- status_ddictionary
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
(self, p_mpa=200.0)[source]¶ Sets the pressure of the system and reinitializes a calculation sequence
- Parameters
- p_mpafloat optional
Float value to set the system pressure in mega-Pascals. Default is 200 MPa.
-
set_temperature
(self, t_c=800.0)[source]¶ Sets the temperature of the system and reinitializes a calculation sequence
- Parameters
- t_cfloat optional
Float value to set the system temperature in degrees centigrade. Default is 800 °C.
-
set_volume
(self, v)[source]¶ Sets the volume of the system and reinitializes a calculation sequence
- Parameters
- vfloat
Float value to set the system volume in J/bar
-
start_excel_workbook_with_sheet_name
(self, sheetName='Summary')[source]¶ Create an Excel workbook with one named sheet.
- Parameters
- sheetNamestring
Sheet name in the new empty Excel workbook
- Returns
- wbtype Workbook
A pointer to an Excel workbook
Notes
Part of the Excel workbook functions subpackage
-
update_excel_workbook
(self, wb, root)[source]¶ Writes the specified equilibrium system state to the specified Excel workbook.
- Parameters
- wbtype Workbook
A pointer to an existing Excel workbook
- roottype 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
(self, wb, fileName='junk.xlsx')[source]¶ Writes the specified Excel workbook to disk.
- Parameters
- wbtype Workbook
A pointer to an existing Excel workbook
- fileNamestring, 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
(self, ws, col, row, value, format='general')[source]¶ Writes information into the specified row, col on the specified worksheet.
- Parameters
- wstype Worksheet
A pointer to a previously created Excel worksheet (see add_sheet_to_workbook_named)
- colint
Column number to write entry to. Numbering starts at column one.
- rowint
Row number to write entry to. Numbering starts at row one.
- valuefloat
Value to place at entry
- formatstring, 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
-