ENKI

Phases package

This module provides Python wrappers to individual and collections of phases.

class phases.Rxn(phase_objs, endmember_ids, rxn_coefs, coefs_per_atom=False)[source]

Class that defines identity/properties of a specific phase reaction.

Reactions occur between phases (either pure or solution) and are defined in terms of the participating endmembers, indicating which atoms are exchanged between phases during the reaction.

Parameters:

phase_objs : array of Phase Objects

Defines which phases participate in the reaction.

endmember_ids : int array

Indicates the endmember of each phase that participates in the reaction. This array must have the same order as the phase array (phase_objs).

rxn_coefs : double array

Defines the stoichiometric rxn coefficient, where negative values are reactants and positive values are products. The reaction must be balanced (obeying mass conservation). This array must have the same order as the phase array (phase_objs).

Notes

  • The phases themselves may be pure or have realistic intermediate compositions (if they are solution phases).
  • The reaction is defined in terms of the exchange of endmembers between the participating phases.
  • Reaction coefficients correspond to a balanced stoichiometric reaction.

Attributes

endmember_ids ID number of each endmember in phase
endmember_names Name of each endmember
phase_num Number of phases
phase_symbols Phase symbols
phases Phase objects used in the reaction
product_phases Product phases
reactant_phases Reactant phases
rxn_coefs Reaction coefficients
affinity(T, P, mols=None)[source]

Calculate reaction affinity

Parameters:

T : array-like

Temperature in Kelvin

P : array-like

Pressure in bars

mol : dict of arrays, optional

Composition of each phase in terms of mols of endmembers (unneeded for pure phases)

Returns:

value : array-like

Reaction affinity in J

chem_potential(T, P, mols=None)[source]

Calculate net chemical potential change of the reaction

Parameters:

T : array-like

Temperature in Kelvin

P : array-like

Pressure in bars

mol : dict of arrays, optional

Composition of each phase in terms of mols of endmembers (unneeded for pure phases)

Returns:

value : array-like

Chemical potential in J for the net change of the reaction

endmember_ids

ID number of each endmember in phase

Returns:Array of ids, [int,…]
endmember_names

Name of each endmember

Returns:List of endmember names for this solution phase, [str,…]
entropy(T, P, mols=None, peratom=False)[source]

Calculate net entropy change of the reaction

Parameters:

T : array-like

Temperature in Kelvin

P : array-like

Pressure in bars

mol : dict of arrays, optional

Composition of each phase in terms of mols of endmembers (unneeded for pure phases).

Returns:

value : array-like

Entropy in J/K for the net change of the reaction.

phase_num

Number of phases

Returns:Number of phases (int)
phase_symbols

Phase symbols

Returns:Array of phase symbols used in the reaction (str)
phases

Phase objects used in the reaction

Returns:Array of phase objects used in the reaction
product_phases

Product phases

Returns:Array of product phase objects
reactant_phases

Reactant phases

Returns:Array of reactant phase objects
rxn_coefs

Reaction coefficients

Returns:Array of reaction coefficients (double)
volume(T, P, mols=None, peratom=False)[source]

Calculate net volume change of the reaction

Parameters:

T : array-like

Temperature in Kelvin

P : array-like

Pressure in bars

mol : dict of arrays, optional

Composition of each phase in terms of mols of endmembers (unneeded for pure phases)

Returns:

value : array-like

Volume in J/bar for the net change of the reaction

class phases.Phase(phase_classnm, abbrev, calib=True, source='objc', coder_module=None)[source]

Abstract parent class defining generic phase properties.

The user must use a subclass, like PurePhase or SolutionPhase, which implements the Phase interface.

Parameters:

phase_classnm : str

Official class name for phase (implemented in src code). String has the form classname if source is objc, else:

  • if !calib [‘cy’, ‘phase name’, ‘module name’, ‘’]
  • if calib [‘cy’, ‘phase name’, ‘module name’, ‘calib’, ‘’]

abbrev : str

Official abbreviation of phase (regardless of implementation).

calib : bool, default True

Indicates whether sample phase should be calibration ready.

source : str

Code source for phase implementation. Default is ‘objc’ (code in objective-C that is part of the original code base). Alternative is ‘coder’ (code generated by the coder module).

coder_module : str

Name of the coder module that contains the phase classes. See documentation for model.Database for additional information and examples.

Notes

  • This code is highly dependent on implementation and is likely to change dramatically with changes in the underlying code that calculates phase properties.
  • The pure water phase, “H2O”, is very complex and thus not available for calibration. The water phase will force its calib flag to False, regardless of input value.

Attributes

abbrev Official unique abbreviation for phase
calib Indicates whether phase calibration is enabled
class_name Name of class
endmember_ids ID number of each endmember in phase
endmember_names Name of each endmember
endmember_num Number of endmembers in phase
formula Formula of phase
identifier Identifier of phase
module Python module attribute for coder generated functions
MOLWTS Array of molecular weights of oxides
OXIDES Array of oxide names
param_names Array of parameter names
param_props Dictionary of phase model parameters
phase_name Name of phase
phase_obj Instance of the phase object
phase_type Phase type
props Dictionary of phase properties
source Indicates origin of source code implementation
MOLWTS

Array of molecular weights of oxides

Returns:Numpy array of molecular weights, (nparray)
OXIDES

Array of oxide names

Returns:Array of oxide names, [str,…]
abbrev

Official unique abbreviation for phase

Returns:Abbreviation (str)
affinity_and_comp(t, p, mu, debug=False)[source]

Given a temperature, pressure and chemical potential(s), compute and return a chemical affinity and phase composition.

Parameters:

t,p : float

Temperature (K) and pressure (bars)

mu : ndarray

Chemical potential(s) of endmember components in phase

  • For a stoichiometric phase, a 1-component 1-D numpy array
  • For a solution phase, a 1-D numpy array of length equal to the number of endmember components in the phase

debug : bool, def False

Print iteration details

Returns:

A, X : tuple

A is a scalar equal to the chemical affinity of the phase relative to mu.

X is a numpy array of mole fractions of endmember components in the phase. X is the same length as mu.

Notes

The algorithm used is from Ghiorso (2013) and is a globally convergent saturation state algorithm applicable to thermodynamic systems with a stable or metastable omni-component phase. Geochimica et Cosmochimica Acta, 103, 295-300

calib

Indicates whether phase calibration is enabled

Returns:Value of calib (bool)
class_name

Name of class

Returns:Name of class (str)
disable_gibbs_energy_reference_state()[source]

Unset Gibbs energy of the reference state.

Notes

Call method on any phase class, and it automatically applies to all.

enable_gibbs_energy_reference_state()[source]

Set Gibbs energy of the reference state.

Notes

Call method on any phase class, and it automatically applies to all.

endmember_ids

ID number of each endmember in phase

Returns:Array of ids, [int,…]
endmember_names

Name of each endmember

Returns:List of endmember names for this solution phase, [str,…]
endmember_num

Number of endmembers in phase

Returns:Number of endmembers in phase (int)
formula

Formula of phase

Returns:Formula of phase (str)
get_param_values(param_names=[], all_params=False)[source]

Get current values for listed parameters.

Parameters:

param_names : str array

List of parameter names

all_params : bool, default False

If true, returns units for all parameters

Returns:

values : double array

List of values for selected parameters

get_phase_amount_from_elements(elements, kind='mass')[source]

Convert list of elements to quantity of phase.

Parameters:

elements : double array

Number of each element

kind : {‘mass’,’moles’}

Determines how phase amount is determined (mass vs. moles)

Returns:

amount : double

Amount of phase (expressed according to kind)

identifier

Identifier of phase

Returns:Identifier of phase (str)
module

Python module attribute for coder generated functions

Returns:

module

Module attribute returned from importlib.import_module, else None if source is ‘objc’

param_names

Array of parameter names

Returns:Array of names for each parameter of the phase model, [str,…]
param_props

Dictionary of phase model parameters

This dictionary defines parameter properties for the phase, using these keys:

supports_calib : bool
Flag indicating whether phase allows calibration
param_num : int
Number of parameters
param_names : str array
Name of each parameter
param_units : str array
Units for each parameter
param0 : double array
Initial parameter values
Returns:Dictionary of phase model parameters (dict)
param_units(param_names=[], all_params=False)[source]

Get units for listed parameters.

Parameters:

param_names : str array

List of parameter names

all_params : bool, default False

If true, returns units for all parameters

Returns:

units : double array

List of units for selected parameters

phase_name

Name of phase

Returns:Name of phase (str)
phase_obj

Instance of the phase object

Returns:Object instance
phase_type

Phase type

Returns:

Phase type (str)

Permissible values are ‘pure’ or ‘solution’.

props

Dictionary of phase properties

The dictionary defines phase properties with these keys:

abbrev : str
Official unique phase abbreviation
name : str
Name of phase (implementation dependent)
class_name : str
Official class name for phase (implemented in src code)
formula : str
Formula of phase
natom : int
Number of atoms in formula unit
molwt : double
Molecular weight of phase (in g/mol-formula-unit)
elemental_entropy : double
Estimated entropy from elemental formula (from Robie et al. 1979)
element_symbols : str array
Symbol array string
element_comp : int array
Phase formula in terms of number of each element
Returns:A Python dictionary (dict)

Notes

Need to update these dictionary values to be vectors for solution phases

set_param_values(param_names=[], param_values=[])[source]

Set new values for listed parameters.

Parameters:

param_names : str array

List of parameter names

param_values : double array

List of parameter values

set_ref_state(Tr=298.15, Pr=1.0, Trl=298.15)[source]

Set reference state P/T conditions.

Parameters:

Tr : double, default 298.15

Reference temperature in Kelvin

Pr : double, default 1.0

Reference pressure in bars

Trl : double, default 298.15

Reference temperature for lambda heat capacity correction in Kelvin

source

Indicates origin of source code implementation

Returns:

String indicating origin of source code for implementation

Permissible values ‘objc’ or ‘coder’.

class phases.PurePhase(phase_classnm, abbrev, calib=True, source='objc', coder_module=None)[source]

Pure stoichiometric phases.

Implements the Phase interface.

Parameters:

phase_classnm : str

Official class name for phase (implemented in src code)

abbrev : str

Official abbreviation of phase (regardless of implementation)

calib : bool, default True

Indicates whether sample phase should be calibration ready

Notes

  • This code is highly dependent on implementation and is likely to change dramatically with changes in the underlying code that calculates phase properties.
  • The pure water phase, “H2O”, is very complex and thus not available for calibration. The water phase will force its calib flag to False, regardless of input value.
  • In addition to the attributes listed, this class inherits the Phase class attributes.

Attributes

Berman_formula Representation of formula using Berman format
Berman_formula

Representation of formula using Berman format

Returns:Chemical formula of phase (str)
class phases.SolutionPhase(phase_classnm, abbrev, calib=True, source='objc', coder_module=None)[source]

Solid solution phases.

Implements the Phase interface.

Parameters:

phase_classnm : str

Official class name for phase (implemented in src code).

abbrev : str

Official abbreviation of phase (regardless of implementation).

calib : bool, default True

Indicates whether sample phase should be calibration ready.

Notes

  • This code is highly dependent on implementation and is likely to change dramatically with changes in the underlying code that calculates phase properties.
  • The pure water phase, “H2O”, is very complex and thus not available for calibration. The water phase will force its calib flag to False, regardless of input value.

Attributes

Attributes for this class are inherited from the Phase class.  
calc_endmember_comp(mol_oxide_comp, method='least_squares', output_residual=False, normalize=False, decimals=10)[source]

Get fraction of each endmember given the composition.

Parameters:

mol_oxide_comp : double array

Amounts of each oxide in standard order (defined in OXIDES)

decimals : int, default 10

Number of decimals to round result to

method : str, default ‘least_squares’

Method used to convert oxide composition (in moles) to moles of endmembers ‘intrinsic’ is alternate method, hardcoded by the solution implementation

Returns:

endmember_comp : double array

Best-fit molar composition in terms of endmembers

mol_oxide_comp_residual : double array

Residual molar oxide composition

Notes

  • Eventually, we may want the ability to calculate endmember comp. using a variety of methods for inputing composition:

    • kind : [‘wt_oxide’, ‘mol_oxide’, ‘element’]
      Identifies how composition is defined.
compute_formula(T, P, mol_comp)[source]

Converts an input array of moles of endmember components to the chemical formula of the phase

Parameters:

T : double

Temperature in Kelvins

P : double

Pressure in bars

mol_comp : double array

Mole numbers of each component in the solution

Returns:

formula : str

A string with the formula of the phase

convert_elements(mol_elm, output='moles_end')[source]

Converts an array of mole numbers of elements (in the standard order) to the specified output quantity

Parameters:

mole_elm : double array

Mole numbers of elements in the standard order

output : str, default = ‘moles_end’

Output quantity:
  • ‘moles_end’ - double array of moles of endmembers
  • ‘total_moles’ - double, sum of moles of endmembers
  • ‘total_grams’ - double, sum of grams of solution
Returns:

result : double or double array

The computed quantity as double or double array

convert_species_to_comp(mol_species)[source]

Converts an input array of moles of species to moles of endmember components

Parameters:

mol_species : double array

Mole numbers of each species in the solution

Returns:

result : double array

Moles of endmember components

covert_endmember_comp(mol_comp, output='total_moles')[source]

Converts an input array of moles of endmember components to the specified quantity

Parameters:

mol_comp : double array

Mole numbers of each component in the solution

output : str, default = ‘total_moles’

Output quantity:
  • ‘total_moles’ - double
  • ‘moles_elements’ - double array (standard order and length)
  • ‘mole_fraction’ - double array (same order and length as input)
Returns:

result : double or double array

The computed quantity as double or double array

get_endmember_ind(mol_oxide_comp, get_endmember_comp=False, TOL=1e-06)[source]

Get index of endmember that best matches composition.

Parameters:

mol_oxide_comp : double array

Amounts of each oxide in standard order (defined in OXIDES)

TOL : double, default 1e-6

Allowed tolerance for mismatch to defined composition

get_endmember_comp : bool, default False

If true, also return endmember composition array.

Returns:

endmember_ind : int

Index of best-fit endmember

endmember_comp : double array, optional

Composition array in terms of endmembers.

Return if get_endmember_comp==True

test_endmember_comp(mol_comp)[source]

Tests validity of endmember component moles array

Parameters:

mol_comp : double array

Mole numbers of each component in the solution

Returns:

flag : boolean

True is composition is valid, otherwise False.