Tools

Burnman has a number of high-level 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.flatten(arr)[source]
burnman.tools.round_to_n(x, xerr, n)[source]
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 1-s.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.sort_table(table, col=0)[source]

Sort the table according to the column number

burnman.tools.float_eq(a, b)[source]

Test if two floats are almost equal to each other

burnman.tools.linear_interpol(x, x1, x2, y1, y2)[source]

Linearly interpolate to point x, between the points (x1,y1), (x2,y2)

burnman.tools.read_table(filename)[source]
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.cut_table(table, min_value, max_value)[source]
burnman.tools.lookup_and_interpolate(table_x, table_y, x_value)[source]
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_vfloat

Unit cell volumes [A^3/unit cell]

zfloat

Number of formula units per unit cell

Returns
Vfloat

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
mineralslist of minerals

List of minerals involved in the reaction.

stoichiometrylist of floats

Reaction stoichiometry for the minerals provided. Reactants and products should have the opposite signs [mol]

temperaturefloat

Temperature of interest [K]

pressure_initial_guessoptional float

Initial pressure guess [Pa]

Returns
pressurefloat

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
mineralslist of minerals

List of minerals involved in the reaction.

stoichiometrylist of floats

Reaction stoichiometry for the minerals provided. Reactants and products should have the opposite signs [mol]

pressurefloat

Pressure of interest [Pa]

temperature_initial_guessoptional float

Initial temperature guess [K]

Returns
temperaturefloat

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
mineralslist of minerals

List of minerals involved in the reaction.

stoichiometrylist of floats

Reaction stoichiometry for the minerals provided. Reactants and products should have the opposite signs [mol]

pressurefloat

Pressure of interest [Pa]

temperature_initial_guessoptional float

Initial temperature guess [K]

Returns
temperaturefloat

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 U2-U1 = 0.5*(p2 - p1)(V1 - V2) where U and V are the internal energies and volumes (mass or molar) and U = F + TS

Parameters
mineralmineral

Mineral for which the Hugoniot is to be calculated.

P_reffloat

Reference pressure [Pa]

T_reffloat

Reference temperature [K]

pressuresnumpy array of floats

Set of pressures [Pa] for which the Hugoniot temperature and volume should be calculated

reference_mineralmineral

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
temperaturesnumpy array of floats

The Hugoniot temperatures at pressure

volumesnumpy 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
compositeComposite

Composite for which fractions are to be defined.

phase_fractionslist of floats

List of input phase fractions (of type input_type)

input_typestring

Input fraction type: ‘molar’, ‘mass’ or ‘volume’

output_typestring

Output fraction type: ‘molar’, ‘mass’ or ‘volume’

Returns
output_fractionslist 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
fnfunction

The function to bracket

x0float

The starting guess

dxfloat

Small step for starting the search

argsparameter 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.

maxiterint

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, including_shear_properties=True)[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
mmineral

The mineral for which the equation of state is to be checked for consistency

Pfloat

The pressure at which to check consistency

Tfloat

The temperature at which to check consistency

tolfloat

The fractional tolerance for each of the checks

verboseboolean

Decide whether to print information about each check

including_shear_propertiesboolean

Decide whether to check shear information, which is pointless for liquids and equations of state without shear modulus parameterizations

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 user-defined number of standard deviations. The edges of the array can be padded in a number of different ways given by the ‘mode’ parameter.

Parameters
arraynumpy ndarray

The array to smooth

grid_spacingnumpy array of floats

The spacing of points along each axis

gaussian_rms_widthsnumpy array of floats

The Gaussian RMS widths/standard deviations for the Gaussian convolution.

truncatefloat (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
array2D numpy array

The array to smooth. Each element array[i][j] corresponds to the position x_values[i], y_values[j]

x_values1D numpy array

The gridded x values over which to create the smoothed grid

y_values1D numpy array

The gridded y_values over which to create the smoothed grid

x_stdevfloat

The standard deviation for the Gaussian filter along the x axis

y_stdevfloat

The standard deviation for the Gaussian filter along the x axis

truncatefloat (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
mMaterial

The material instance evaluated by the output function.

attributeslist of strings

The list of material attributes / properties to be evaluated in the product

powerslist of floats

The powers to which each attribute should be raised during evaluation

Returns
——-
ffunction(x)

Function which returns the value of product(a_i**p_i) as a function of condition (x = [P, T, V])

burnman.tools.compare_l2(depth, calc, obs)[source]

Computes the L2 norm for N profiles at a time (assumed to be linear between points).

Parameters
  • depths (array of float) – depths. \([m]\)

  • calc (list of arrays of float) – N arrays calculated values, e.g. [mat_vs,mat_vphi]

  • obs (list of arrays of float) – N arrays of values (observed or calculated) to compare to , e.g. [seis_vs, seis_vphi]

Returns

array of L2 norms of length N

Return type

array of floats

burnman.tools.compare_chifactor(calc, obs)[source]

Computes the chi factor for N profiles at a time. Assumes a 1% a priori uncertainty on the seismic model.

Parameters
  • calc (list of arrays of float) – N arrays calculated values, e.g. [mat_vs,mat_vphi]

  • obs (list of arrays of float) – N arrays of values (observed or calculated) to compare to , e.g. [seis_vs, seis_vphi]

Returns

error array of length N

Return type

array of floats

burnman.tools.l2(x, funca, funcb)[source]

Computes the L2 norm for one profile(assumed to be linear between points).

Parameters
  • x (array of float) – depths \([m]\).

  • funca (list of arrays of float) – array calculated values

  • funcb (list of arrays of float) – array of values (observed or calculated) to compare to

Returns

L2 norm

Return type

array of floats

burnman.tools.nrmse(x, funca, funcb)[source]

Normalized root mean square error for one profile :type x: array of float :param x: depths in m. :type funca: list of arrays of float :param funca: array calculated values :type funcb: list of arrays of float :param funcb: array of values (observed or calculated) to compare to

Returns

RMS error

Return type

array of floats

burnman.tools.chi_factor(calc, obs)[source]

\(\chi\) factor for one profile assuming 1% uncertainty on the reference model (obs) :type calc: list of arrays of float :param calc: array calculated values :type obs: list of arrays of float :param obs: array of reference values to compare to

Returns

\(\chi\) factor

Return type

array of floats