.. _ref-property-modifiers:

Mineral Property Modifiers
~~~~~~~~~~~~~~~~~~~~~~~~~~

Standard thermal equations of state typically consider the effects of strain and
quasiharmonic lattice vibrations on the energies of minerals at given temperatures and
pressures. There are a number of additional processes, such as isochemical
order-disorder and magnetic effects which also contribute to the total energy
of a phase, which are not typically included in standard equations of state.
Corrections for these additional processes can, to first order,
be applied as additive modifiers, ignoring any explicit coupling with the equation of state.

Burnman currently includes implementations of the following:

.. contents::
    :local:
    :class: this-will-duplicate-information-and-it-is-still-useful-here
    :depth: 2

In all cases, the excess Gibbs energy :math:`\mathcal{G}`
and first and second partial derivatives with respect to
pressure and temperature are calculated.
The effective thermodynamic properties of each phase are then modified in
a self-consistent manner; specifically:

.. math::
    \mathcal{G} = \mathcal{G}_{\text{o}} + \mathcal{G}_{\text{m}}, \\
    S = S_{\text{o}} - \left(\frac{\partial \mathcal{G}}{\partial T}\right)_{\text{m}}, \\
    V = V_{\text{o}} + \left(\frac{\partial \mathcal{G}}{\partial P}\right)_{\text{m}}, \\
    K_T = V / \left( \left(\frac{V_{\text{o}}}{K_{T\text{o}}}\right) - \left(\frac{\partial^2\mathcal{G}}{\partial P^2}\right)_{\text{m}} \right), \\
    C_p = C_{p\text{o}} - T \left(\frac{\partial ^2 \mathcal{G}}{\partial T^2}\right)_{\text{m}}, \\
    \alpha = \left( \alpha_{\text{o}} V_{\text{o}}  + \left(\frac{\partial^2 \mathcal{G}}{\partial P \partial T}\right)_{\text{m}} \right) / V

where the subscript "o" refers to properties calculated from the underlying equation of state,
and the subscript "m" refers to contributions from the property modifier.
Other derived properties are then calculated from these modified
thermodynamic properties using standard thermodynamic relationships:

.. math::
    \mathcal{H} = \mathcal{G} + T S, \\
    \mathcal{F} = \mathcal{G} - P V, \\
    C_v = C_p - V T \alpha^2 K_T, \\
    \gamma = \frac{\alpha K_T V}{C_v}, \\
    K_S = K_T \frac{C_p}{C_v}

Importantly, this allows us to stack modifications such as multiple Landau transitions
in a simple and straightforward manner. In the burnman code, we add property modifiers as an attribute to each
mineral as a list. For example:

.. code-block:: python

    from burnman.minerals import SLB_2011

    stv = SLB_2011.stishovite()

    stv.property_modifiers = [["landau", {"Tc_0": -4250.0, "S_D": 0.012, "V_D": 1e-09}],
                              ["linear", {"delta_E": 1.e3, "delta_S": 0., "delta_V": 0.}]]


Each modifier is a list with two elements, first the name of the modifier type, and second a dictionary with
the required parameters for that model. A list of parameters for each model is given in the following sections.

.. include:: autogenerated/property_modifiers.rst