Previous topic

Next topic

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_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(self, 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(self, 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(self, 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(self, 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.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)

affinity_and_comp(self, t, p, mu, debug=False, method='generic')[source]¶

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

Parameters

t,pfloat

Temperature (K) and pressure (bars)

mundarray

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

debugbool, def False

Print iteration details

methodstr, def ‘generic’

Algorithm used: ‘generic’ - generic algorithm on components, ‘species’ - generic algorithm on species (> = components), ‘special’ - algorthmic specifically coded in the phase instance,

currently, only Objective-C coded methods are utilized, see _tailored_affinity_and_comp()

Returns

——-

A, Xtuple

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

property calib¶

Indicates whether phase calibration is enabled

Returns

Value of calib (bool)

property class_name¶

Name of class

Returns

Name of class (str)

disable_gibbs_energy_reference_state(self)[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(self)[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)

property formula¶

Formula of phase

Returns

Formula of phase (str)

get_param_values(self, 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(self, 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)

property identifier¶

Identifier of phase

Returns

Identifier of phase (str)

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(self, 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(self, 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(self, 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’.

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.SolutionPhase(phase_classnm, abbrev, 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(self, 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(self, 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(self, 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_species_to_comp(self, mol_species)[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

Returns

resultdouble array: Moles of endmember components

covert_endmember_comp(self, 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)

Returns

resultdouble or double array: The computed quantity as double or double array

get_endmember_ind(self, 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

test_endmember_comp(self, 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.