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)

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)

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)

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)

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)

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)

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()

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()

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)

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)

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)

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)

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

NOT IMPLEMENTED

get_param_values(param_names=[], all_params=False)

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')

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)

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)

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)

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)

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)

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=[])

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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)

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')

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')

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')

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')

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)

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)

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.