.. _ref-materials-solution-models:

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 :class:`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:

.. math::
    \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 :math:`\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 :math:`\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 :cite:`Temkin1945`, and is useful for modelling phases
where the site multiplicities are not fixed by crystal structure, such as glasses or
melts.

Implemented solution models
^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. include:: autogenerated/solution_models.rst