ENKI

Phases package

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

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_classnmstr

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’, ‘’]

abbrevstr

Official abbreviation of phase (regardless of implementation).

calibbool, default True

Indicates whether sample phase should be calibration ready.

sourcestr

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_modulestr

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

property MOLWTS

Array of molecular weights of oxides

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

Array of oxide names

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

Official unique abbreviation for phase

Returns
Abbreviation (str)
activity(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=True, endmember=None, const=None, species=None)[source]

Calculate activity (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

endmemberNone or int scalar or int array

If None, retrieve an array of chemical potentials; else chemical potential for endmber index or index set in array

Returns
valuearray-like

Activity (or derivatives in deriv units).

bulk_mod(T, P, mol=None, V=None, const='T', deriv=None, deriv_param=None, mol_deriv_qty=True, endmember=None, species=None)[source]

Calculate bulk modulus (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

const[‘T’, ‘S’], optional

Defines constant path for derivative (yielding K_T vs K_S)

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Bulk modulus in bars (or derivatives in deriv units).

property calib

Indicates whether phase calibration is enabled

Returns
Value of calib (bool)
chem_potential(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=True, endmember=None, species=False, const=None)[source]

Calculate chemical potential (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

endmemberNone or int scalar or int array

If None, retrieve an array of chemical potentials, else chemical potential for endmember index or index set in array

speciesboolean

If False, returned value is for components of the solution. If True, returned value is for species in the solution.

Returns
valuearray-like

Chemical potential in J (or derivative in deriv units).

property class_name

Name of class

Returns
Name of class (str)
compressibility(T, P, mol=None, V=None, const='T', deriv=None, deriv_param=None, mol_deriv_qty=True, endmember=None, species=None)[source]

Calculate compressibility (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

const[‘T’, ‘S’], optional

Defines constant path for derivative (yielding Beta_T vs Beta_S)

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Bulk modulus in 1/bars (or derivatives in deriv units).

density(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=None, endmember=None, const=None, species=None)[source]

Calculate density (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Density in g*bar/J (or derivative in deriv units).

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.

property endmember_ids

ID number of each endmember in phase

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

Name of each endmember

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

Number of endmembers in phase

Returns
Number of endmembers in phase (int)
enthalpy(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=None, endmember=None, const=None, species=None)[source]

Calculate enthalpy (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin

Parray-like

Pressure in bars

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Enthalpy in J (or derivative in deriv units).

entropy(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=None, endmember=None, const=None, species=None)[source]

Calculate entropy (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Entropy in J/K (or derivative in deriv units).

property exchange_equil

Exchange equilibrium object responsible for calculating metastable equilibrium properties of the phase

Returns
Exchange Equilibrium object
property formula

Formula of phase

Returns
Formula of phase (str)
fugacity(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=True, endmember=None, const=None, species=None)[source]

Calculate activity (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Fugacity in bars (or derivatives in deriv units).

gamma(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=True, endmember=None, const=None, species=None)[source]

Calculate grüneisen parameter (or derivatives) for phase.

NOT IMPLEMENTED

get_param_values(param_names=[], all_params=False)[source]

Get current values for listed parameters.

Parameters
param_namesstr array

List of parameter names

all_paramsbool, default False

If true, returns units for all parameters

Returns
valuesdouble 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
elementsdouble array

Number of each element

kind{‘mass’,’moles’}

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

Returns
amountdouble

Amount of phase (expressed according to kind)

gibbs_energy(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=None, endmember=None, const=None, species=None)[source]

Calculate Gibbs energy (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin

Parray-like

Pressure in bars

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (Default is zero for all params.)

deriv_paramarray of strs

Parameter names that identify returned derivatives (Default is None.)

Returns
valuearray-like

Gibbs energy in J (or derivative in deriv units)

heat_capacity(T, P, mol=None, V=None, const='P', deriv=None, deriv_param=None, mol_deriv_qty=True, endmember=None, species=None)[source]

Calculate heat capacity (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

const[‘P’, ‘V’], optional

Defines constant path for derivative (yielding C_P vs C_V)

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Thermal expansion in J/K (or derivatives in deriv units).

helmholtz_energy(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=None, endmember=None, const=None, species=None)[source]

Calculate helmholtz energy (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Helmholtz energy in J (or derivative in deriv units).

property identifier

Identifier of phase

Returns
Identifier of phase (str)
internal_energy(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=None, endmember=None, const=None, species=None)[source]

Calculate internal energy (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Internal energy in J (or derivative in deriv units).

property module

Python module attribute for coder generated functions

Returns
module

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

property param_names

Array of parameter names

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

Dictionary of phase model parameters

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

supports_calibbool

Flag indicating whether phase allows calibration

param_numint

Number of parameters

param_namesstr array

Name of each parameter

param_unitsstr array

Units for each parameter

param0double 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_namesstr array

List of parameter names

all_paramsbool, default False

If true, returns units for all parameters

Returns
unitsdouble array

List of units for selected parameters

property phase_name

Name of phase

Returns
Name of phase (str)
property phase_obj

Instance of the phase object

Returns
Object instance
property phase_type

Phase type

Returns
Phase type (str)

Permissible values are ‘pure’ or ‘solution’.

property props

Dictionary of phase properties

The dictionary defines phase properties with these keys:

abbrevstr

Official unique phase abbreviation

namestr

Name of phase (implementation dependent)

class_namestr

Official class name for phase (implemented in src code)

formulastr

Formula of phase

natomint

Number of atoms in formula unit

molwtdouble

Molecular weight of phase (in g/mol-formula-unit)

elemental_entropydouble

Estimated entropy from elemental formula (from Robie et al. 1979)

element_symbolsstr array

Symbol array string

element_compint 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_namesstr array

List of parameter names

param_valuesdouble 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
Trdouble, default 298.15

Reference temperature in Kelvin

Prdouble, default 1.0

Reference pressure in bars

Trldouble, default 298.15

Reference temperature for lambda heat capacity correction in Kelvin

property source

Indicates origin of source code implementation

Returns
String indicating origin of source code for implementation

Permissible values ‘objc’ or ‘coder’.

thermal_exp(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=True, endmember=None, const=None, species=None)[source]

Calculate heat capacity (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Thermal expansion in 1/K (or derivatives in deriv units).

volume(T, P, mol=None, V=None, deriv=None, deriv_param=None, mol_deriv_qty=None, endmember=None, const=None, species=None)[source]

Calculate volume (or derivatives) for phase.

Parameters
Tarray-like

Temperature in Kelvin.

Parray-like

Pressure in bars.

molarray-like, optional

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

Varray-like, optional (default None)

Volume in J/bar. Overrides pressure if not None.

derivdict of ints

Derivative order for each parameter (default is zero for all params).

Returns
valuearray-like

Volume in J/bar (or derivative in deriv units).

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

Pure stoichiometric phases.

Implements the Phase interface.

Parameters
phase_classnmstr

Official class name for phase (implemented in src code)

abbrevstr

Official abbreviation of phase (regardless of implementation)

calibbool, 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

property Berman_formula

Representation of formula using Berman format

Returns
Chemical formula of phase (str)
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_objsarray of Phase Objects

Defines which phases participate in the reaction.

endmember_idsint 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_coefsdouble 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
Tarray-like

Temperature in Kelvin

Parray-like

Pressure in bars

moldict of arrays, optional

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

Returns
valuearray-like

Reaction affinity in J

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

Calculate net chemical potential change of the reaction

Parameters
Tarray-like

Temperature in Kelvin

Parray-like

Pressure in bars

moldict of arrays, optional

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

Returns
valuearray-like

Chemical potential in J for the net change of the reaction

property endmember_ids

ID number of each endmember in phase

Returns
Array of ids, [int,…]
property 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
Tarray-like

Temperature in Kelvin

Parray-like

Pressure in bars

moldict of arrays, optional

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

Returns
valuearray-like

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

property phase_num

Number of phases

Returns
Number of phases (int)
property phase_symbols

Phase symbols

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

Phase objects used in the reaction

Returns
Array of phase objects used in the reaction
property product_phases

Product phases

Returns
Array of product phase objects
property reactant_phases

Reactant phases

Returns
Array of reactant phase objects
property 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
Tarray-like

Temperature in Kelvin

Parray-like

Pressure in bars

moldict of arrays, optional

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

Returns
valuearray-like

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

class phases.SolutionPhase(phase_classnm, abbrev, XTOL=1e-12, calib=True, source='objc', coder_module=None)[source]

Solid solution phases.

Implements the Phase interface.

Parameters
phase_classnmstr

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

abbrevstr

Official abbreviation of phase (regardless of implementation).

calibbool, 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_compdouble array

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

decimalsint, default 10

Number of decimals to round result to

methodstr, 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_compdouble array

Best-fit molar composition in terms of endmembers

mol_oxide_comp_residualdouble 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
Tdouble

Temperature in Kelvins

Pdouble

Pressure in bars

mol_compdouble array

Mole numbers of each component in the solution

Returns
formulastr

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_elmdouble array

Mole numbers of elements in the standard order

outputstr, 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
resultdouble or double array

The computed quantity as double or double array

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

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

Parameters
mol_compdouble array

Mole numbers of each component in the solution

outputstr, 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)

  • ‘moles_species’ - pandas series or array w/ accepted order

Returns
resultdouble or double array/pandas series

The computed quantity as double or double array (or series)

convert_species_to_comp(mol_species, method='linear')[source]

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

Parameters
mol_speciesdouble array

Mole numbers of each species in the solution

method{‘linear’, ‘source’}

Default is ‘linear’, using basic dot-product. Otherwise, optimized methods can be used from source code by selecting ‘source’.

Returns
resultdouble array

Moles of endmember components

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

Deprecated since version 1.0: This will be removed in 2.0. This legacy function name has a typo. Use convert_endmember_comp instead.

property endmember_elem_comp

Endmember elemental composition (compact)

Returns
Dataframe (or matrix) with elemental composition (cols)
for each endmember (rows). Only includes elements that are part of the
solution phase.
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_compdouble array

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

TOLdouble, default 1e-6

Allowed tolerance for mismatch to defined composition

get_endmember_compbool, default False

If true, also return endmember composition array.

Returns
endmember_indint

Index of best-fit endmember

endmember_compdouble array, optional

Composition array in terms of endmembers.

Return if get_endmember_comp==True

property species_elem_comp

Species elemental composition (compact)

Returns
Dataframe (or matrix) with elemental composition (cols)
for each species(rows). Only includes elements that are part of the
solution phase.
property species_stoic

Species Stoichiometry

Returns
Dataframe (or matrix) with molar endmember stoichiometry (cols)
for each species (rows). Expresses species in terms of independent
endmembers.
property species_stoic_T

Species Stoichiometry Transpose

Returns
Dataframe (or matrix) with molar endmember stoichiometry (rows)
for each species (cols). Expresses species in terms of independent
endmembers.
test_endmember_comp(mol_comp)[source]

Tests validity of endmember component moles array

Parameters
mol_compdouble array

Mole numbers of each component in the solution

Returns
flagboolean

True is composition is valid, otherwise False.