Solution Model Classes¶

Mean-field solution models¶

In BurnMan, all solution models are based on mean-field theories of solutions. These theories, introduced by Bragg and Williams in 1934, assume that each component in the solution experiences an average environment created by all other components, rather than accounting for specific local interactions between different species. This simplification allows for tractable mathematical descriptions of solution behaviour.

Each of the solution models below takes an endmembers argument, which is a list of lists. Each sub-list contains two items. The first is an instance of burnman.Mineral representing an independent endmember (or component) of the solution. The second is a string, which represents the occupancies of different species on distinct sites in the solution. For example, low pressure silicate garnets have two distinct sites on which mixing takes place; a dodecahedral site (of which there are three per unit cell on an eight-cation basis) and octahedral site (of which there are two per unit cell). A third tetrahedral cation site (three per unit cell) is usually assumed to be occupied solely by silicon, and therefore can be ignored in solution calculations. The chemical formula of many low pressure garnets exist within the solution:

\[\textrm{[Mg,Fe,Mn,Ca]}_3\textrm{[Al,Fe}^{\textrm{3+}}\textrm{,Cr]}_2\textrm{Si}_3\textrm{O}_{12}\]

where the dodecahedral site is occupied by Mg, Fe, Mn and Ca, and the octahedral site is occupied by Al, Fe and Cr. The pyrope endmember, composition \(\textrm{Mg}_3\textrm{Al}_2\textrm{Si}_3\textrm{O}_{12}\), would have the corrsponding site occupancy string [Mg]3[Al]2Si3O12, while andradite would have [Ca]3[Fef]2Si3O12. BurnMan also allows for partial occupancies on sites; for example, disordered grandite with composition \(\textrm{Ca}_3\textrm{AlFeSi}_3\textrm{O}_{12}\) would have the site occupancy string [Ca]3[Al0.5Fef0.5]2Si3O12. Note that distinct species do not need to be named as elements; the only requirement is that the names start with a capital letter and are followed by lower-case letters. Atom proportions and site multiplicities can be expressed as decimal numbers or fractions.

In BurnMan, the multiplicities of each site are allowed to vary linearly between endmembers. This is known as a Temkin model [Tem45], and is useful for modelling phases where the site multiplicities are not fixed by crystal structure, such as glasses or melts.

Implemented solution models¶

MechanicalSolution¶

class burnman.classes.solutionmodel.MechanicalSolution(endmembers)[source]

Bases: SolutionModel

An extremely simple class representing a mechanical solution model. A mechanical solution experiences no interaction between endmembers. Therefore, unlike ideal solutions there is no entropy of mixing; the total gibbs free energy of the solution is equal to the dot product of the molar gibbs free energies and molar fractions of the constituent materials.

IdealSolution¶

class burnman.classes.solutionmodel.IdealSolution(endmembers)[source]

Bases: SolutionModel

A solution model representing ideal mixing between endmembers. In ideal solutions, the enthalpy of mixing is equal to zero; i.e. chemical mixing of endmembers at fixed pressure and temperature does not involve the absorption or release of heat. The only contribution to the Gibbs energy of mixing is the configurational entropy \(S_{\textrm{conf}}\):

\[\begin{split}\mathcal{G}_{\textrm{mixing}} = - T \Delta S_{\textrm{conf}}, \\ S_{\textrm{conf}} = R x_c^s \ln \frac{x_c^s}{\sum_{c^s} x_c^s}\end{split}\]

where \(s\) is a site in the lattice, \(c\) are the species mixing on site \(s\). \(x_c^s\) is the absolute number of species \(c\) on site \(s\) in the lattice; it is calculated by multiplying the proportion of the species on the site by the multiplicity of the site per formula unit and the number of moles of formula units. This class allows the site multiplicities to vary linearly between endmembers. This is known as a Temkin model [Tem45].

AsymmetricRegularSolution¶

class burnman.classes.solutionmodel.AsymmetricRegularSolution(endmembers, alphas, energy_interaction, volume_interaction=None, entropy_interaction=None)[source]

Bases: IdealSolution

Solution model implementing the asymmetric regular solution model formulation as described in [HollandPowell03].

The excess nonconfigurational Gibbs energy is given by the expression [DPWH07]:

\[\mathcal{G}_{\textrm{excess}} = \alpha^T p (\phi^T W \phi)\]

\(\alpha\) is a vector of van Laar parameters governing asymmetry in the excess properties.

\[\phi_i = \frac{\alpha_i p_i}{\sum_{k=1}^{n} \alpha_k p_k}, W_{ij} = \frac{2 w_{ij}}{\alpha_i + \alpha_j} \textrm{for i<j}\]

The \(w_{ij}\) terms are a set of interaction terms between endmembers \(i\) and \(j\). If all the \(\alpha\) terms are equal to unity, a non-zero \(w\) yields an excess with a quadratic form and a maximum of \(w/4\) half-way between the two endmembers.

Parameters:

endmembers (list of tuples) – A list of tuples defining the endmembers of the solution. Each tuple contains a burnman.Mineral object and a string defining the site formula of that endmember.
alphas (list of floats) – A list of van Laar parameters governing asymmetry in the excess properties.
energy_interaction (list of lists of floats) – A 2D list of interaction parameters defining the energetic interactions between endmembers. The list should be upper-triangular, such that the first row has n-1 elements (for n endmembers), the second row has n-2 elements, etc.
volume_interaction (list of lists of floats) – (optional) A 2D list of interaction parameters defining the volumetric interactions between endmembers. The list should be upper-triangular, such that the first row has n-1 elements (for n endmembers), the second row has n-2 elements, etc.
entropy_interaction (list of lists of floats) – (optional) A 2D list of interaction parameters defining the entropic interactions between endmembers. The list should be upper-triangular, such that the first row has n-1 elements (for n endmembers), the second row has n-2 elements, etc.

SymmetricRegularSolution¶

class burnman.classes.solutionmodel.SymmetricRegularSolution(endmembers, energy_interaction, volume_interaction=None, entropy_interaction=None)[source]

Bases: AsymmetricRegularSolution

Solution model implementing the Symmetric Regular Solution Model. This is a special case of the burnman.solutionmodel.AsymmetricRegularSolution class where all van Laar parameters are equal to unity.

The excess terms in the Symmetric Regular Solution Model have the matrix form [DPWH07]

\[\mathcal{G}_{\textrm{excess}} = RT \ln \gamma = p^T W p\]

where \(p\) is a vector of molar fractions of each of the \(n\) endmembers and \(W\) is a strictly upper-triangular matrix of interaction terms between endmembers. Excesses within binary systems (\(i\)-\(j\)) have a quadratic form and a maximum of \(W_{ij}/4\) half-way between the two endmembers.

Parameters:

endmembers (list of tuples) – A list of tuples defining the endmembers of the solution. Each tuple contains a burnman.Mineral object and a string defining the site formula of that endmember.
energy_interaction (list of lists of floats) – A 2D list of interaction parameters defining the energetic interactions between endmembers. The list should be upper-triangular, such that the first row has n-1 elements (for n endmembers), the second row has n-2 elements, etc.
volume_interaction (list of lists of floats) – (optional) A 2D list of interaction parameters defining the volumetric interactions between endmembers. The list should be upper-triangular, such that the first row has n-1 elements (for n endmembers), the second row has n-2 elements, etc.
entropy_interaction (list of lists of floats) – (optional) A 2D list of interaction parameters defining the entropic interactions between endmembers. The list should be upper-triangular, such that the first row has n-1 elements (for n endmembers), the second row has n-2 elements, etc.

SubregularSolution¶

class burnman.classes.solutionmodel.SubregularSolution(endmembers, energy_interaction, volume_interaction=None, entropy_interaction=None, energy_ternary_terms=None, volume_ternary_terms=None, entropy_ternary_terms=None)[source]

Bases: IdealSolution

Solution model implementing the subregular solution model formulation as described in [HW89]. The excess nonconfigurational Gibbs energy is given by the expression:

\[\mathcal{G}_{\textrm{excess}} = \sum_i \sum_{j > i} (p_i p_j^2 W_{ij} + p_j p_i^2 W_{ji} + \sum_{k > j > i} p_i p_j p_k W_{ijk})\]

Interaction parameters are inserted into a 3D interaction matrix during initialization to make use of numpy vector algebra.

Parameters:

endmembers (list of lists) – A list of all the independent endmembers in the solution. The first item of each list gives the Mineral object corresponding to the endmember. The second item gives the site-species formula.
energy_interaction (list of list of lists) – The binary endmember interaction energies. Each interaction[i, j-i-1, 0] corresponds to W(i,j), while interaction[i, j-i-1, 1] corresponds to W(j,i).
volume_interaction (list of list of lists) – The binary endmember interaction volumes. Each interaction[i, j-i-1, 0] corresponds to W(i,j), while interaction[i, j-i-1, 1] corresponds to W(j,i).
entropy_interaction (list of list of lists) – The binary endmember interaction entropies. Each interaction[i, j-i-1, 0] corresponds to W(i,j), while interaction[i, j-i-1, 1] corresponds to W(j,i).
energy_ternary_terms (list of lists) – The ternary interaction energies. Each list should contain four entries: the indices i, j, k and the value of the interaction.
volume_ternary_terms (list of lists) – The ternary interaction volumes. Each list should contain four entries: the indices i, j, k and the value of the interaction.
entropy_ternary_terms (list of lists) – The ternary interaction entropies. Each list should contain four entries: the indices i, j, k and the value of the interaction.

FunctionSolution¶

class burnman.classes.solutionmodel.FunctionSolution(endmembers, excess_gibbs_function)[source]

Bases: IdealSolution

Solution model implementing a generalized solution model. The extensive excess nonconfigurational Gibbs energy is provided as a function by the user.

Derivatives are calculated using the autograd module, and so the user-defined excess Gibbs energy function should be defined using autograd-friendly expressions.

Parameters:

endmembers (list of lists) – A list of all the independent endmembers in the solution. The first item of each list gives the Mineral object corresponding to the endmember. The second item gives the site-species formula.
excess_gibbs_function (function) – The nonconfigurational Gibbs energy function with arguments pressure, temperature and molar_amounts, in that order. Note that the function must be extensive; if the molar amounts are doubled, the Gibbs energy must also double.

PolynomialSolution¶

class burnman.classes.solutionmodel.PolynomialSolution(endmembers, ESV_interactions=None, interaction_endmembers=[], endmember_coefficients_and_interactions=None, transformation_matrix=None)[source]

Bases: IdealSolution

Solution model implementing a general polynomial solution model.

Parameters:

endmembers (list of lists) – A list of all the independent endmembers in the solution. The first item of each list gives the Mineral object corresponding to the endmember. The second item gives the site-species formula.
ESV_interactions (list of lists) – A list containing lists where the first three elements are energy, entropy and volume interactions and the rest of the elements are indices of the transformed endmembers to which those interactions correspond, and the proportion exponents. For example, [2., 0., 0., 0, 4, 1, 1] would correspond to an interaction of 2*p’[0]^4*p’[1]^1.
interaction_endmembers (list of burnman.Mineral objects) – A list of minerals involved in the interaction terms.
endmember_coefficients_and_interactions (list of lists) – list of lists A list containing lists where the first n elements are coefficients for each of the interaction_endmembers and the rest of the elements are indices of the transformed endmembers to which those interactions correspond. For example, [1., 0., -1., 0, 4, 1, 1] would correspond to an interaction of (mbr[0].gibbs - mbr[2].gibbs)*p’[0]^4*p’[1]^1.
transformation_matrix (2D numpy array) – The interactions for a given solution may be most compactly expressed not as a polynomial function of the proportions of the endmembers, but a polynomial function of a linearly transformed set. This parameter is a square numpy array A, where p’i = A_ij p_j