Tools¶
Burnman has a number of highlevel tools to help achieve common goals.

burnman.tools.
copy_documentation
(copy_from)[source]¶ Decorator @copy_documentation(another_function) will copy the documentation found in a different function (for example from a base class). The docstring applied to some function a() will be
(copied from BaseClass.some_function): <documentation from BaseClass.some_function> <optionally the documentation found in a()>

burnman.tools.
unit_normalize
(a, order=2, axis=1)[source]¶ Calculates the L2 normalized array of numpy array a of a given order and along a given axis.

burnman.tools.
pretty_print_values
(popt, pcov, params)[source]¶ Takes a numpy array of parameters, the corresponding covariance matrix and a set of parameter names and prints the parameters and principal 1s.d.uncertainties (np.sqrt(pcov[i][i])) in a nice text based format.

burnman.tools.
pretty_print_table
(table, use_tabs=False)[source]¶ Takes a 2d table and prints it in a nice text based format. If use_tabs=True then only is used as a separator. This is useful for importing the data into other apps (Excel, ...). The default is to pad the columns with spaces to make them look neat. The first column is left aligned, while the remainder is right aligned.

burnman.tools.
pretty_plot
()[source]¶ Makes pretty plots. Overwrites the matplotlib default settings to allow for better fonts. Slows down plotting

burnman.tools.
linear_interpol
(x, x1, x2, y1, y2)[source]¶ Linearly interpolate to point x, between the points (x1,y1), (x2,y2)

burnman.tools.
array_from_file
(filename)[source]¶ Generic function to read a file containing floats and commented lines into a 2D numpy array.
Commented lines are prefixed by the characters # or %.

burnman.tools.
molar_volume_from_unit_cell_volume
(unit_cell_v, z)[source]¶ Converts a unit cell volume from Angstroms^3 per unitcell, to m^3/mol.
Parameters: unit_cell_v : float
Unit cell volumes [A^3/unit cell]
z : float
Number of formula units per unit cell
Returns: V : float
Volume [m^3/mol]

burnman.tools.
equilibrium_pressure
(minerals, stoichiometry, temperature, pressure_initial_guess=100000.0)[source]¶ Given a list of minerals, their reaction stoichiometries and a temperature of interest, compute the equilibrium pressure of the reaction.
Parameters: minerals : list of minerals
List of minerals involved in the reaction.
stoichiometry : list of floats
Reaction stoichiometry for the minerals provided. Reactants and products should have the opposite signs [mol]
temperature : float
Temperature of interest [K]
pressure_initial_guess : optional float
Initial pressure guess [Pa]
Returns: pressure : float
The equilibrium pressure of the reaction [Pa]

burnman.tools.
equilibrium_temperature
(minerals, stoichiometry, pressure, temperature_initial_guess=1000.0)[source]¶ Given a list of minerals, their reaction stoichiometries and a pressure of interest, compute the equilibrium temperature of the reaction.
Parameters: minerals : list of minerals
List of minerals involved in the reaction.
stoichiometry : list of floats
Reaction stoichiometry for the minerals provided. Reactants and products should have the opposite signs [mol]
pressure : float
Pressure of interest [Pa]
temperature_initial_guess : optional float
Initial temperature guess [K]
Returns: temperature : float
The equilibrium temperature of the reaction [K]

burnman.tools.
invariant_point
(minerals_r1, stoichiometry_r1, minerals_r2, stoichiometry_r2, pressure_temperature_initial_guess=[1000000000.0, 1000.0])[source]¶ Given a list of minerals, their reaction stoichiometries and a pressure of interest, compute the equilibrium temperature of the reaction.
Parameters: minerals : list of minerals
List of minerals involved in the reaction.
stoichiometry : list of floats
Reaction stoichiometry for the minerals provided. Reactants and products should have the opposite signs [mol]
pressure : float
Pressure of interest [Pa]
temperature_initial_guess : optional float
Initial temperature guess [K]
Returns: temperature : float
The equilibrium temperature of the reaction [K]

burnman.tools.
hugoniot
(mineral, P_ref, T_ref, pressures, reference_mineral=None)[source]¶ Calculates the temperatures (and volumes) along a Hugoniot as a function of pressure according to the Hugoniot equation U2U1 = 0.5*(p2  p1)(V1  V2) where U and V are the internal energies and volumes (mass or molar) and U = F + TS
Parameters: mineral : mineral
Mineral for which the Hugoniot is to be calculated.
P_ref : float
Reference pressure [Pa]
T_ref : float
Reference temperature [K]
pressures : numpy array of floats
Set of pressures [Pa] for which the Hugoniot temperature and volume should be calculated
reference_mineral : mineral
Mineral which is stable at the reference conditions Provides an alternative U_0 and V_0 when the reference mineral transforms to the mineral of interest at some (unspecified) pressure.
Returns: temperatures : numpy array of floats
The Hugoniot temperatures at pressure
volumes : numpy array of floats
The Hugoniot volumes at pressure

burnman.tools.
convert_fractions
(composite, phase_fractions, input_type, output_type)[source]¶ Takes a composite with a set of user defined molar, volume or mass fractions (which do not have to be the fractions currently associated with the composite) and converts the fractions to molar, mass or volume.
Conversions to and from mass require a molar mass to be defined for all phases. Conversions to and from volume require set_state to have been called for the composite.
Parameters: composite : Composite
Composite for which fractions are to be defined.
phase_fractions : list of floats
List of input phase fractions (of type input_type)
input_type : string
Input fraction type: ‘molar’, ‘mass’ or ‘volume’
output_type : string
Output fraction type: ‘molar’, ‘mass’ or ‘volume’
Returns: output_fractions : list of floats
List of output phase fractions (of type output_type)

burnman.tools.
bracket
(fn, x0, dx, args=(), ratio=1.618, maxiter=100)[source]¶ Given a function and a starting guess, find two inputs for the function that bracket a root.
Parameters: fn : function
The function to bracket
x0 : float
The starting guess
dx : float
Small step for starting the search
args : parameter list
Additional arguments to give to fn
ratio :
The step size increases by this ratio every step in the search. Defaults to the golden ratio.
maxiter : int
The maximum number of steps before giving up.
Returns: xa, xb, fa, fb: floats
xa and xb are the inputs which bracket a root of fn. fa and fb are the values of the function at those points. If the bracket function takes more than maxiter steps, it raises a ValueError.

burnman.tools.
check_eos_consistency
(m, P=1000000000.0, T=300.0, tol=0.0001, verbose=False)[source]¶ Compute numerical derivatives of the gibbs free energy of a mineral under given conditions, and check these values against those provided analytically by the equation of state
Parameters: m : mineral
The mineral for which the equation of state is to be checked for consistency
P : float
The pressure at which to check consistency
T : float
The temperature at which to check consistency
tol : float
The fractional tolerance for each of the checks
verbose : boolean
Decide whether to print information about each check
Returns: consistency: boolean
If all checks pass, returns True

burnman.tools.
smooth_array
(array, grid_spacing, gaussian_rms_widths, truncate=4.0, mode='inverse_mirror')[source]¶ Creates a smoothed array by convolving it with a gaussian filter. Grid resolutions and gaussian RMS widths are required for each of the axes of the numpy array. The smoothing is truncated at a userdefined number of standard deviations. The edges of the array can be padded in a number of different ways given by the ‘mode’ parameter.
Parameters: array : numpy ndarray
The array to smooth
grid_spacing : numpy array of floats
The spacing of points along each axis
gaussian_rms_widths : numpy array of floats
The Gaussian RMS widths/standard deviations for the Gaussian convolution.
truncate : float (default=4.)
The number of standard deviations at which to truncate the smoothing.
mode : {‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’, ‘inverse_mirror’}
The mode parameter determines how the array borders are handled either by scipy.ndimage.filters.gaussian_filter. Default is ‘inverse_mirror’, which uses burnman.tools._pad_ndarray_inverse_mirror().
Returns: smoothed_array: numpy ndarray
The smoothed array

burnman.tools.
interp_smoothed_array_and_derivatives
(array, x_values, y_values, x_stdev=0.0, y_stdev=0.0, truncate=4.0, mode='inverse_mirror', indexing='xy')[source]¶ Creates a smoothed array on a regular 2D grid. Smoothing is achieved using burnman.tools.smooth_array(). Outputs scipy.interpolate.interp2d() interpolators which can be used to query the array, or its derivatives in the x and y directions.
Parameters: array : 2D numpy array
The array to smooth. Each element array[i][j] corresponds to the position x_values[i], y_values[j]
x_values : 1D numpy array
The gridded x values over which to create the smoothed grid
y_values : 1D numpy array
The gridded y_values over which to create the smoothed grid
x_stdev : float
The standard deviation for the Gaussian filter along the x axis
y_stdev : float
The standard deviation for the Gaussian filter along the x axis
truncate : float (optional)
The number of standard deviations at which to truncate the smoothing (default = 4.).
mode : {‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’, ‘inverse_mirror’}
The mode parameter determines how the array borders are handled either by scipy.ndimage.filters.gaussian_filter. Default is ‘inverse_mirror’, which uses burnman.tools._pad_ndarray_inverse_mirror().
indexing : {‘xy’, ‘ij’}, optional
Cartesian (‘xy’, default) or matrix (‘ij’) indexing of output. See numpy.meshgrid for more details.
Returns: interps: tuple of three interp2d functors
interpolation functions for the smoothed property and the first derivatives with respect to x and y.

burnman.tools.
attribute_function
(m, attributes, powers=[])[source]¶ Function which returns a function which can be used to evaluate material properties at a point. This function allows the user to define the property returned as a string. The function can itself be passed to another function (such as nonlinear_fitting.confidence_prediction_bands()).
Properties can either be simple attributes (e.g. K_T) or a product of attributes, each raised to some power.
Parameters: m : Material
The material instance evaluated by the output function.
attributes : list of strings
The list of material attributes / properties to be evaluated in the product
powers : list of floats
The powers to which each attribute should be raised during evaluation
Returns
——
f : function(x)
Function which returns the value of product(a_i**p_i) as a function of condition (x = [P, T, V])