Compositions#

Base class#

class burnman.Composition(composition_dictionary, unit_type='mass', normalize=False)[source]#

Bases: object

Class for a composition object, which can be used to store, modify and renormalize compositions, and also convert between mass, molar and atomic amounts. Weight is provided as an alias for mass, as we assume that only Earthlings will use this software.

This class is available as burnman.Composition.

renormalize(unit_type, normalization_component, normalization_amount)[source]#

Change the total amount of material in the composition to satisfy a given normalization condition (mass, weight, molar, or atomic)

Parameters:

  • unit_type (str) – ‘mass’, ‘weight’, ‘molar’ or ‘atomic’ Unit type with which to normalize the composition

  • normalization_component (str) – Component/element on which to renormalize. String must either be one of the components/elements already in the composition, or have the value ‘total’.

  • normalization_amount (float) – Amount of component in the renormalised composition.

add_components(composition_dictionary, unit_type)[source]#

Add (or remove) components from the composition. The components are added to the current state of the (mass, weight or molar) composition; if the composition has been renormalised, then this should be taken into account.

Parameters:

  • composition_dictionary (dictionary) – Components to add, and their amounts.

  • unit_type (str) – ‘mass’, ‘weight’ or ‘molar’. Unit type of the components to be added.

change_component_set(new_component_list)[source]#

Change the set of basis components without changing the bulk composition.

Will raise an exception if the new component set is invalid for the given composition.

Parameters:

new_component_list (list of strings) – New set of basis components.

property weight_composition#

An alias for mass composition [kg].

property molar_composition#

Returns the molar composition as a counter [moles]

property atomic_composition#

Returns the atomic composition as a counter [moles]

composition(unit_type)[source]#

Helper function to return the composition in the desired type.

Parameters:

unit_type (str) – One of ‘mass’, ‘weight’, ‘molar’ and ‘atomic’.

Returns:

Mass (weight), molar or atomic composition.

Return type:

OrderedCounter

print(unit_type, significant_figures=1, normalization_component='total', normalization_amount=None)[source]#

Pretty-print function for the composition This does not renormalize the Composition object itself, only the printed values.

Parameters:

  • unit_type (str) – ‘mass’, ‘weight’, ‘molar’ or ‘atomic’ Unit type in which to print the composition.

  • significant_figures (int) – Number of significant figures for each amount.

  • normalization_component (str) – Component/element on which to renormalize. String must either be one of the components/elements already in composite, or have the value ‘total’. (default = ‘total’)

  • normalization_amount (float) – Amount of component in the renormalised composition. If not explicitly set, no renormalization will be applied.

Utility functions#

burnman.classes.composition.file_to_composition_list(fname, unit_type, normalize)[source]#

Takes an input file with a specific format and returns a list of compositions (and associated comments) contained in that file.

Parameters:

  • fname (str) – Path to ascii file containing composition data. Lines beginning with a hash are not read. The first read-line of the datafile contains a list of tab or space-separated components (e.g. FeO or SiO2), followed by the word Comment. Following lines are lists of floats with the amounts of each component. After the component amounts, the user can write anything they like in the Comment section.

  • unit_type (str) – ‘mass’, ‘weight’ or ‘molar’ Specify whether the compositions in the file are given as mass (weight) or molar amounts.

  • normalize – If False, absolute numbers of moles/grams of component are stored, otherwise the component amounts of returned compositions will sum to one (until Composition.renormalize() is used).

:type normalize : bool

Fitting functions#

burnman.optimize.composition_fitting.fit_composition_to_solution(solution, fitted_variables, variable_values, variable_covariances, variable_conversions=None, normalize=True)[source]#

Takes a Solution object and a set of variable names and associates values and covariances and finds the molar fractions of the solution which provide the best fit (in a least-squares sense) to the variable values.

The fitting applies appropriate non-negativity constraints (i.e. no species can have a negative occupancy on a site).

Parameters:

  • solution (burnman.Solution) – The solution to use in the fitting procedure.

  • fitted_variables (list of str) – A list of the variables used to find the best-fit molar fractions of the solution. These should either be elements such as “Fe”, site_species such as “Fef_B” which would correspond to a species labelled Fef on the second site, or user-defined variables which are arithmetic sums of elements and/or site_species defined in “variable_conversions”.

  • variable_values (numpy.array) – Numerical values of the fitted variables. These should be given as amounts; they do not need to be normalized.

  • variable_covariances (2D numpy.array) – Covariance matrix of the variables.

  • variable_conversions (dict of dict, or None) – A dictionary converting any user-defined variables into an arithmetic sum of element and site-species amounts. For example, {‘Mg_equal’: {‘Mg_A’: 1., ‘Mg_B’: -1.}}, coupled with Mg_equal = 0 would impose a constraint that the amount of Mg would be equal on the first and second site in the solution.

  • normalize (bool) – If True, normalizes the optimized molar fractions to sum to unity.

Returns:

Optimized molar fractions, corresponding covariance matrix and the weighted residual.

Return type:

tuple of 1D numpy.array, 2D numpy.array and float

burnman.optimize.composition_fitting.fit_phase_proportions_to_bulk_composition(phase_compositions, bulk_composition)[source]#

Performs weighted constrained least squares on a set of phase compositions to find the amount of those phases that best-fits a given bulk composition.

The fitting applies appropriate non-negativity constraints (i.e. no phase can have a negative abundance in the bulk).

Parameters:

  • phase_compositions (2D numpy.array) – The composition of each phase. Can be in weight or mole amounts.

  • bulk_composition (numpy.array) – The bulk composition of the composite. Must be in the same units as the phase compositions.

Returns:

Optimized molar fractions, corresponding covariance matrix and the weighted residual.

Return type:

tuple of 1D numpy.array, 2D numpy.array and float