BurnMan – a Python toolkit for planetary geophysics, geochemistry and thermodynamics

Many branches of physics, chemistry and Earth sciences build complex materials from simpler constructs: rocks are composites made up of one or more phases; phases are solutions of more than one endmember; and endmembers are usually mixtures of more than one element. The properties of the endmember building blocks at different pressures and temperatures can be modelled using a wide array of different equations of state. There are also many models for the
averaging of endmember properties within solutions and composite materials. Once calculated, the physical properties of composite materials can be used in many different ways. BurnMan is an open source, extensible mineral physics module written in Python. It implements several different methods to calculate the physical properties of natural materials. The toolbox has a class-based, modular design that allows users to calculate many low-level properties that
are not easily accessed using existing codes, and to combine various tools in novel, creative ways. The module includes:
• over a dozen static and thermal equations of state for pure phases;
• commonly-used solution model formalisms (ideal, (a)symmetric, subregular) and a formalism that allows users to define their own excess energy functions;
• popular endmember and solution datasets for solids and melts, including Holland & Powell (2011), de Koker et al. (2013) and Stixrude & Lithgow-Bertelloni (2021);
• an anisotropic equation of state (Myhill, 2022);
• a consistent method for combining phases into a composite assemblage, with seismic
averaging schemes including Voigt, Reuss, Voigt-Reuss-Hill and the Hashin-Shtrikman
bounds;
• a common set of methods to output thermodynamic and thermoelastic properties for all
materials;
• a solver to chemically equilibrate composite materials;
• optimal least squares fitting routines for multivariate experimental data with (potentially
correlated) errors. These allow (for example) simultaneous fitting of pure phase and
solution model parameters to experimental volumes, seismic velocities and enthalpies of
formation;
• “Planet” and “Layer” classes that self-consistently calculate gravity, pressure, density, mass, moment of inertia and seismic velocity profiles given chemical, thermal and dynamic constraints;
• geothermal profiles from the literature as well as the option to calculate adiabatic profiles based on mineral assemblage;
• a set of high-level functions which create files readable by seismological and geodynamic software, including: Mineos (Masters et al., 2011), AxiSEM (Nissen-Meyer et al., 2014) and ASPECT (Bangerth et al., 2022a, 2022b; Kronbichler et al., 2012); and a Composition class, which provides a framework to convert between mass, molar, and elemental compositions, convert to different chemical component systems, and add or subtract components.

The project includes over 40 annotated examples, an extensive suite of unit tests and benchmarks, and a directory containing user-contributed code from published papers. A multipart tutorial illustrates key functionality, including the functions required to create the figures in this paper (https://burnman.readthedocs.io/en/latest/tutorial.html). Using BurnMan requires only moderate Python skills, and its modular nature means that it can easily be customised.