BurnMan comes with a small tutorial in the tutorial/ folder, and large
collection of example programs under examples/. Below you can find a summary
of the different examples. They are grouped into *Tutorial*,
*Simple Examples*, and *More Advanced Examples*. We suggest
starting with the tutorial before moving on to the simpler examples,
especially if you are new to using BurnMan.

Finally, we also include the scripts that were used for all computations and
figures in the 2014 BurnMan paper in the misc/ folder, see
*Reproducing Cottaar, Heister, Rose and Unterborn (2014)*.

In this first part of the tutorial we will acquaint ourselves with a basic script for calculating the elastic properties of a mantle mineralogical model.

In general, there are three portions of this script:

1) Define a set of pressures and temperatures at which we want to calculate elastic properties

2) Setup a composite of minerals (or “rock”) and calculate its elastic properties at those pressures and temperatures.

3) Plot those elastic properties, and compare them to a seismic model, in this case PREM

The script is basically already written, and should run as is by typing:

python step_1.py

on the command line. However, the mineral model for the rock is not very realistic, and you will want to change it to one that is more in accordance with what we think the bulk composition of Earth’s lower mantle is.

When run (without putting in a more realistic composition), the program produces the following image:

Your goal in this tutorial is to improve this awful fit...

In this second part of the tutorial we try to get a closer fit to our 1D seismic reference model. In the simple Mg, Si, and O model that we used in step 1 there was one free parameter, namely phase_1_fraction, which goes between zero and one.

In this script we want to explore how good of a fit to PREM we can get by varying this fraction. We create a simple function that calculates a misfit between PREM and our mineral model as a function of phase_1_fraction, and then plot this misfit function to try to find a best model.

This script may be run by typing

python step_2.py

Whithout changing any input, the program should produce the following image showing the misfit as a function of perovskite content:

In the previous two steps of the tutorial we tried to find a very simple mineralogical model that best fit the 1D seismic model PREM. But we know that there is consideral uncertainty in many of the mineral physical parameters that control how the elastic properties of minerals change with pressure and temperature. In this step we explore how uncertainties in these parameters might affect the conclusions you draw.

The strategy here is to make many different “realizations” of the rock that you determined was the closest fit to PREM, where each realization has its mineral physical parameters perturbed by a small amount, hopefully related to the uncertainty in that parameter. In particular, we will look at how perturbations to \(K_{0}^{'}\) and \(G_{0}^{'}\) (the pressure derivatives of the bulk and shear modulus, respectively) change the calculated 1D seismic profiles.

This script may be run by typing

python step_3.py

After changing the standard deviations for \(K_{0}^{'}\) and \(G_{0}^{'}\) to 0.2, the following figure of velocities for 1000 realizations is produced:

- The following is a list of simple examples:

This example script is intended for absolute beginners to BurnMan. We cover importing BurnMan modules, creating a composite material, and calculating its seismic properties at lower mantle pressures and temperatures. Afterwards, we plot it against a 1D seismic model for visual comparison.

*Uses:*

*Mineral database*`burnman.composite.Composite``burnman.seismic.PREM``burnman.geotherm.brown_shankland()``burnman.material.Material.evaluate()`

*Demonstrates:*

- creating basic composites
- calculating thermoelastic properties
- seismic comparison

*Resulting figure:*

This example shows how to create different solid solution models and output thermodynamic and thermoelastic quantities.

There are four main types of solid solution currently implemented in BurnMan:

- Ideal solid solutions
- Symmmetric solid solutions
- Asymmetric solid solutions
- Subregular solid solutions

These solid solutions can potentially deal with:

- Disordered endmembers (more than one element on a crystallographic site)
- Site vacancies
- More than one valence/spin state of the same element on a site

*Uses:*

*Demonstrates:*

- Different ways to define a solid solution
- How to set composition and state
- How to output thermodynamic and thermoelastic properties

*Resulting figures:*

This example shows each of the geotherms currently possible with BurnMan. These are:

- Brown and Shankland, 1981 [BS81]
- Anderson, 1982 [And82a]
- Watson and Baxter, 2007 [WB07]
- linear extrapolation
- Read in from file from user
- Adiabatic from potential temperature and choice of mineral

*Uses:*

`burnman.geotherm.brown_shankland()``burnman.geotherm.anderson()`- input geotherm file
*input_geotherm/example_geotherm.txt*(optional) `burnman.composite.Composite`for adiabat

*Demonstrates:*

- the available geotherms

*Resulting figure:*

Shows the various ways to input seismic models (\(V_s, V_p, V_{\phi}, \rho\)) as a function of depth (or pressure) as well as different velocity model libraries available within Burnman:

This example will first calculate or read in a seismic model and plot the model along the defined pressure range. The example also illustrates how to import a seismic model of your choice, here shown by importing AK135 [KEB95].

*Uses:*

*Demonstrates:*

- Utilization of library seismic models within BurnMan
- Input of user-defined seismic models

*Resulting figures:*

This example shows how to create different minerals, how to compute seismic velocities, and how to compare them to a seismic reference model.

There are many different ways in BurnMan to combine minerals into a composition. Here we present a couple of examples:

- Two minerals mixed in simple mole fractions. Can be chosen from the BurnMan libraries or from user defined minerals (see example_user_input_material)
- Example with three minerals
- Using preset solid solutions
- Defining your own solid solution

To turn a method of mineral creation “on” the first if statement above the method must be set to True, with all others set to False.

Note: These minerals can include a spin transition in (Mg,Fe)O, see example_spintransition.py for explanation of how to implement this

*Uses:*

*Mineral database*`burnman.composite.Composite``burnman.mineral.Mineral``burnman.solidsolution.SolidSolution`

*Demonstrates:*

- Different ways to define a composite
- Using minerals and solid solutions
- Compare computations to seismic models

*Resulting figure:*

This example shows the effect of different averaging schemes. Currently four averaging schemes are available:

- Voight-Reuss-Hill
- Voight averaging
- Reuss averaging
- Hashin-Shtrikman averaging

See [WDOConnell76] Journal of Geophysics and Space Physics for explanations of each averaging scheme.

*Specifically uses:*

`burnman.averaging_schemes.VoigtReussHill``burnman.averaging_schemes.Voigt``burnman.averaging_schemes.Reuss``burnman.averaging_schemes.HashinShtrikmanUpper``burnman.averaging_schemes.HashinShtrikmanLower`

*Demonstrates:*

- implemented averaging schemes

*Resulting figure:*

This example shows how to use the chemical potentials library of functions.

*Demonstrates:*

- How to calculate chemical potentials
- How to compute fugacities and relative fugacities

*Resulting figure:*

- Advanced examples:

This example shows the different minerals that are implemented with a spin transition. Minerals with spin transition are implemented by defining two separate minerals (one for the low and one for the high spin state). Then a third dynamic mineral is created that switches between the two previously defined minerals by comparing the current pressure to the transition pressure.

*Specifically uses:*

`burnman.mineral_helpers.HelperSpinTransition()``burnman.minerals.Murakami_etal_2012.fe_periclase()``burnman.minerals.Murakami_etal_2012.fe_periclase_HS()``burnman.minerals.Murakami_etal_2012.fe_periclase_LS()`

*Demonstrates:*

- implementation of spin transition in (Mg,Fe)O at user defined pressure

*Resulting figure:*

Shows user how to input a mineral of his/her choice without usint the library and which physical values need to be input for BurnMan to calculate \(V_P, V_\Phi, V_S\) and density at depth.

*Specifically uses:*

*Demonstrates:*

- how to create your own minerals

Vary the amount perovskite vs. ferropericlase and compute the error in the seismic data against PREM. For more extensive comments on this setup, see tutorial/step_2.py

*Uses:*

*Mineral database*`burnman.composite.Composite``burnman.seismic.PREM``burnman.geotherm.brown_shankland()``burnman.material.Material.evaluate()``burnman.main.compare_l2()`

*Demonstrates:*

- compare errors between models
- loops over models

*Resulting figure:*

For Earth we have well-constrained one-dimensional density models. This allows us to calculate pressure as a funcion of depth. Furthermore, petrologic data and assumptions regarding the convective state of the planet allow us to estimate the temperature.

For planets other than Earth we have much less information, and in particular we know almost nothing about the pressure and temperature in the interior. Instead, we tend to have measurements of things like mass, radius, and moment-of-inertia. We would like to be able to make a model of the planet’s interior that is consistent with those measurements.

However, there is a difficulty with this. In order to know the density of the planetary material, we need to know the pressure and temperature. In order to know the pressure, we need to know the gravity profile. And in order to the the gravity profile, we need to know the density. This is a nonlinear problem which requires us to iterate to find a self-consistent solution.

Here we show an example that does this, using the planet Mercury as motivation.

*Uses:*

*Resulting figure:*

This example demonstrates how to call each of the individual calculation methodologies that exist within BurnMan. See below for current options. This example calculates seismic velocity profiles for the same set of minerals and a plot of \(V_s, V_\phi\) and \(\rho\) is produce for the user to compare each of the different methods.

*Specifically uses:*

*Demonstrates:*

- Each method for calculating velocity profiles currently included within BurnMan

*Resulting figure:*

In this section we include the scripts that were used for all computations and figures in the 2014 BurnMan paper: Cottaar, Heister, Rose & Unterborn (2014) [CHRU14]

This script reproduces [CHRU14], Figure 2.

This example shows the effect of different averaging schemes. Currently four averaging schemes are available: 1. Voight-Reuss-Hill 2. Voight averaging 3. Reuss averaging 4. Hashin-Shtrikman averaging

See [WDOConnell76] for explanations of each averaging scheme.

requires: - geotherms - compute seismic velocities

teaches: - averaging

This script reproduces [CHRU14] Figure 4.

This example demonstrates BurnMan’s functionality to fit thermoelastic data to both 2nd and 3rd orders using the EoS of the user’s choice at 300 K. User’s must create a file with \(P, T\) and \(V_s\). See input_minphys/ for example input files.

requires: - compute seismic velocities

teaches: - averaging

This script reproduces [CHRU14], Figure 5. Attempt to reproduce Figure 6.12 from [Mur13]

This script reproduces [CHRU14], Figure 6. Vary the amount perovskite vs. ferropericlase and compute the error in the seismic data against PREM.

requires: - creating minerals - compute seismic velocities - geotherms - seismic models - seismic comparison

teaches: - compare errors between models - loops over models

This example shows you how to create two materials from wt% determines the optimum mixing between the two to match the seismic model of your choice. Currently it compares two end member meteorite groups among the chondrites: carbonaceous and enstatite. Velocities are calculated for each set of minerals and plotted for comparison.

requires: - geotherms - seismic models - compute seismic velocities - creating minerals

teaches: - weight percent materials

This example shows how to vary the distribution coefficient of the perovskite/ferropericlase system. The user sets \(K_{d0}\) and BurnMan scales \(K_{d}\) as a function of \(P\) and \(T\) adopting the formalism of [NFR12]. Specifically we adopt equation 5 of [NFR12] with \(\Delta V_0\) = 0.2 cc/mol, and calculating the partition coefficient of Fe in each phase from stoichiometry.

This example will calculate mineral input parameters from Mg and Fe endmembers from Stixrude and Lithgow-bertelloni, 2005 with weighting determined by the calculated partition coefficients. Finally, output plots of \(X_{Fe}\) in pv and \(X_{Fe}\) in fp our output as well as the user’s choice of geotherm

requires: - geotherms -input distribution coefficient \(K_{d0}\)

teaches: - creating varying proportions of Fe and its effect on seismic velocities

This example demonstrates BurnMan’s functionality to fit thermoelastic data to both 2nd and 3rd orders using the EoS of the user’s choice at 300 K. User’s must create a file with \(P, T\) and \(V_s\). See input_minphys/ for example input files.

requires: - compute seismic velocities

teaches: - averaging

This example shows how to evaluate seismic quantities on a \(P,T\) grid.

This example explains how to perform the basic i/o of BurnMan. A method of calculation is chosen, a composite mineral/material (see example_composition.py for explanation of this process) is created in the class “rock,” finally a geotherm is created and seismic velocities calculated.

Post-calculation, the results are written to a simple text file to plot/manipulate at the user’s whim.

requires: - creating minerals - compute seismic velocities - geotherms

teaches: - output computed seismic data to file