Polytopes

Often in mineral physics, solutions are subject to a set of linear constraints. For example, the set of valid site-occupancies in solution models are constrained by positivity and fixed sum constraints (the amount of each chemical species must be greater than or equal to zero, the sites in the structure are present in fixed ratios). Similarly, the phase amounts in a composite must be more than or equal to zero, and the compositions of each phase must sum to the bulk composition of the composite.

Geometrically, linear equality and inequality constraints can be visualised as a polytope (an n-dimensional) polyhedron. There are several situations where it is convenient to be able to interrogate such objects to understand the space of validity. In BurnMan, we make use of the module pycddlib to create polytope objects. We also provide a number of tools for common chemically-relevant operations.

Base class

class burnman.MaterialPolytope(equalities, inequalities, return_fractions=False, independent_endmember_occupancies=None)

Bases: object

A class for creating and manipulating polytope objects using pycddlib.

This class is available as burnman.polytope.MaterialPolytope.

set_return_type(return_fractions=False)

Sets the return_type for the polytope object. Also deletes the cached endmember_occupancies property.

Parameters:

return_fractions (bool) – Choose whether the generated polytope object should return fractions or floats.

property raw_vertices

Returns a list of the vertices of the polytope without any postprocessing. See also endmember_occupancies.

property limits

Return the limits of the polytope (the set of bounding inequalities).

property n_endmembers

Return the number of endmembers (the number of vertices of the polytope).

property endmember_occupancies

Return the endmember occupancies (a processed list of all of the vertex locations).

property independent_endmember_occupancies

Return an independent set of endmember occupancies (a linearly-independent set of vertex locations)

property endmembers_as_independent_endmember_amounts

Return a list of all the endmembers as a linear sum of the independent endmembers.

property independent_endmember_polytope

Returns the polytope expressed in terms of proportions of the independent endmembers. The polytope involves the first n-1 independent endmembers. The last endmember proportion makes the sum equal to one.

property independent_endmember_limits

Gets the limits of the polytope as a function of the independent endmembers.

subpolytope_from_independent_endmember_limits(limits)

Returns a smaller polytope by applying additional limits to the amounts of the independent endmembers.

subpolytope_from_site_occupancy_limits(limits)

Returns a smaller polytope by applying additional limits to the individual site occupancies.

grid(points_per_edge=2, unique_sorted=True, grid_type='independent endmember proportions', limits=None)

Create a grid of points which span the polytope.

Parameters:

• points_per_edge (int) – Number of points per edge of the polytope.

• unique_sorted (bool) – The gridding is done by splitting the polytope into a set of simplices. This means that points will be duplicated along vertices, faces etc. If unique_sorted is True, this function will sort and make the points unique. This is an expensive operation for large polytopes, and may not always be necessary.

• grid_type (str) – Whether to grid the polytope in terms of independent endmember proportions or site occupancies. Choices are ‘independent endmember proportions’ or ‘site occupancies’

• limits (numpy.array (2D)) – Additional inequalities restricting the gridded area of the polytope.

Returns:

A list of points gridding the polytope.

Return type:

numpy.array (2D)

Polytope tools

burnman.tools.polytope.solution_polytope_from_charge_balance(charges, charge_total, return_fractions=False)

Creates a polytope object from a list of the charges for each species on each site and the total charge for all site-species.

Parameters:

• charges (2D list of floats) – 2D list containing the total charge for species j on site i, including the site multiplicity. So, for example, a solution with the site formula [Mg,Fe]3[Mg,Al,Si]2Si3O12 would have the following list: [[6., 6.], [4., 6., 8.]].

• charge_total (float) – The total charge for all site-species per formula unit. The example given above would have charge_total = 12.

• return_fractions (bool) – Determines whether the created polytope object returns its attributes (such as endmember occupancies) as fractions or as floats. Default is False.

Returns:

A polytope object corresponding to the parameters provided.

Return type:

burnman.polytope.MaterialPolytope object

burnman.tools.polytope.solution_polytope_from_endmember_occupancies(endmember_occupancies, return_fractions=False)

Creates a polytope object from a list of independent endmember occupancies.

Parameters:

• endmember_occupancies (2D numpy array) – 2D list containing the site-species occupancies j for endmember i. So, for example, a solution with independent endmembers [Mg]3[Al]2Si3O12, [Mg]3[Mg0.5Si0.5]2Si3O12, [Fe]3[Al]2Si3O12 might have the following array: [[1., 0., 1., 0., 0.], [1., 0., 0., 0.5, 0.5], [0., 1., 1., 0., 0.]], where the order of site-species is Mg_A, Fe_A, Al_B, Mg_B, Si_B.

• return_fractions (bool) – Determines whether the created polytope object returns its attributes (such as endmember occupancies) as fractions or as floats.

Returns:

A polytope object corresponding to the parameters provided.

Return type:

burnman.polytope.MaterialPolytope object

burnman.tools.polytope.composite_polytope_at_constrained_composition(composite, composition, return_fractions=False)

Creates a polytope object from a Composite object and a composition. This polytope describes the complete set of valid composite endmember amounts that satisfy the compositional constraints.

Parameters:

• composite (burnman.Composite object) – A composite containing one or more Solution and Mineral objects.

• composition (dict) – A dictionary containing the amounts of each element.

• return_fractions (bool) – Determines whether the created polytope object returns its attributes (such as endmember occupancies) as fractions or as floats.

Returns:

A polytope object corresponding to the parameters provided.

Return type:

burnman.polytope.MaterialPolytope object

burnman.tools.polytope.reorder_to_echelon(A)

Reorders the rows of a matrix A so that it is in echelon form. :param A: The input matrix. :type A: 2D numpy array :returns: The reordered matrix. :rtype: 2D numpy array

burnman.tools.polytope.simplify_composite_with_composition(composite, composition)

Takes a composite and a composition, and returns the simplest composite object that spans the solution space at the given composition.

For example, if the composition is given as {‘Mg’: 2., ‘Si’: 1.5, ‘O’: 5.}, and the composite is given as a mix of Mg,Fe olivine and pyroxene solutions, this function will return a composite that only contains the Mg-bearing endmembers.

If the solutions have endmember proportions that are consistent with the bulk composition, the site occupancies of the new solution models are set to the values in the original models.

Parameters:

• composite (burnman.Composite object) – The initial Composite object.

• composition (dict) – A dictionary containing the amounts of each element.

Returns:

The simplified Composite object

Return type:

burnman.Composite object

burnman.tools.polytope.greedy_independent_endmember_selection(endmember_site_occupancies, site_occupancies, small_fraction_tol=0.0, norm_tol=1e-12)

Greedy algorithm to select independent endmembers from a solution to approximate given site occupancies through a non-negative linear combination of endmember site occupancies.

This function starts with the full site occupancies and then iteratively selects endmembers to approximate those site occupancies. It loops through all possible endmembers in a number of steps. At each step the algorithm selects the endmember that can be subtracted in the largest amount from the current residual site occupancies without making any site occupancy negative. The process continues until either no endmember can be subtracted in an amount greater than fraction_tol, or the norm of the residual site occupancies is less than tol.

Parameters:

• endmember_site_occupancies (np.ndarray) – A 2D array of shape (m, n), where m is the number of endmembers and n is the number of sites. Each row corresponds to the site occupancies of an endmember.

• site_occupancies (np.ndarray) – A 1D array of length n, representing the target site occupancies to approximate.

• small_fraction_tol (float, optional, default 0.0) – Algorithm stops if no endmember can be added with a molar fraction larger than this value.

• norm_tol (float, optional, default 1e-12) – Algorithm stops if the norm of the residual site occupancies is less than this value.

Returns:

indices of selected endmembers, their fractions, and the final residual site occupancies.

Return type:

tuple(list[int], list[float], np.ndarray)