Extensive properties for composites

[bobmyhill]

BurnMan currently:

• outputs extensive properties as quantities per mole
• defines materials in terms of molar fractions

When we originally wrote the various material classes, this made sense. However, BurnMan now has reasonably mature equilibration routines. This creates a problem because mole amounts are not conserved during reactions:

e.g. Mg2SiO4 -> MgSiO3 + MgO

Up until now, I've worked around the problem by allowing equilibrate to set a new attribute, n_moles, such that composition is conserved during equilibration. But this means that extensive properties must be multiplied by this parameter by the user, e.g.:

V = assemblage.V * assemblage.n_moles

This is frustrating both to remember and to write every time.

There are several solutions to this problem, and I'd like to discuss possibilities before we release BurnMan 3.0:

• We keep behaviour the same, but make the n_moles parameter more prominent in the documentation

• Extensive properties for composites are output per mole of atoms. I don't like this because endmembers, solution models and composites will behave very differently.

• We make extensive properties a function of the n_moles attribute. This means that:

  • we should remove the molar_ prefix to extensive properties.
  • By default, n_moles = 1, but this can be changed by the equilibrate routines.
  • n_moles ?should be made a protected variable that can only be changed by a set_number_of_moles variable.

  This breaks the codebase, but in a minimal way for most users. I think this is my favoured solution.

• We change the Composite class so that molar_fractions is changed to molar_amounts. Then we don't need the n_moles attribute. This is similar to the above, but would remove an assert that we thought quite carefully about ~10 years ago.

• Something else I haven't thought about.

Thoughts and suggestions very welcome!

[bobmyhill]

I thought about this some more, and I think there's only one choice that makes sense, which I've implemented in #709.

The vast majority of users will not see any changes to their code - the PR preserves behaviour in the vast majority of cases. The major exceptions:

• The user manually used or set the attribute n_moles in their code. The new code no longer uses this property.
• The user asked for abbreviated properties (V, S, H, C_p, C_v), or the formula of Composite materials after using equilibrate. The old code output molar properties, the new code outputs extensive properties.