Compositions¶

Base class¶

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

Bases: object

The Composition class 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.

Composition can parse dictionaries of components, rather than only elements. Components are given as strings (e.g. ‘MgSiO3’, ‘Fe2O3’, etc). The Composition class breaks these components down into their elemental constituents internally.

Example:

from burnman.composition import Composition

comp_dict = {'MgSiO3': 0.5, 'FeSiO3': 0.5}
comp = Composition(comp_dict, unit_type='molar', normalize=True)
print(comp.atomic_composition)

# Renormalize to 1 kg of material
comp.renormalize(unit_type='mass', normalization_component='total', normalization_amount=1.0)
print(comp.mass_composition)

# Add 0.1 moles of Al2O3 to the composition
comp.add_components({'Al2O3': 0.1}, unit_type='molar')
print(comp.molar_composition)

# Change the component set to only oxides
comp.change_component_set(['MgO', 'SiO2', 'FeO', 'Al2O3'])
print(comp.molar_composition)

# Remove components with less than 1.e-10 moles
comp.remove_null_components(tol=1.e-10)
print(comp.molar_composition)

# Pretty-print the molar composition, normalized to 100 moles total
comp.print(unit_type='molar', significant_figures=3, normalization_component='total', normalization_amount=100.0)

Parameters:

composition_dictionary (dictionary) – Dictionary of components (given as a string) and their amounts.
unit_type (str) – ‘mass’, ‘weight’ or ‘molar’ (optional, ‘mass’ as default) Specify whether the input composition is given as mass or molar amounts.
normalize (bool) – If False, absolute numbers of kilograms/moles of component are stored, otherwise the component amounts of returned compositions will sum to one (until Composition.renormalize() is used).

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.

remove_null_components(tol=1e-12)[source]¶

Removes components with absolute concentrations less than a given tolerance.

Parameters:: tol (float, optional) – zero tolerance, defaults to 1.e-12

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 (bool) – 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).

Returns:

A list of Composition objects and a list of comments.

Return type:

list of Composition, list of list of str

Fitting functions¶

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

Fit a set of molar fractions to a solution model that best matches observed compositional variables (in a least-squares sense).

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, default=True) – Whether to normalize the molar fractions to sum to one.

Returns:

(molar_fractions, covariance_matrix, weighted_residual):

molar_fractions: Optimized molar fractions of each endmember.
covariance_matrix: Covariance matrix of the optimized molar
fractions, computed from the pseudo-inverse of the weighted design matrix.
weighted_residual: The weighted residual of the fit, representing
the square root of the weighted sum of squared differences between observed and modeled variables.

Return type:

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