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, number_type='fraction', return_fractions=False, independent_endmember_occupancies=None)[source]#

Bases: object

A class that can be instantiated to create pycddlib polytope objects. These objects can be interrogated to provide the vertices satisfying the input constraints.

This class is available as burnman.polytope.MaterialPolytope.

set_return_type(return_fractions=False)[source]#

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[source]#: Returns a list of the vertices of the polytope without any postprocessing. See also endmember_occupancies.

property limits[source]#: Return the limits of the polytope (the set of bounding inequalities).

property n_endmembers[source]#: Return the number of endmembers (the number of vertices of the polytope).

property endmember_occupancies[source]#: Return the endmember occupancies (a processed list of all of the vertex locations).

property independent_endmember_occupancies[source]#: Return an independent set of endmember occupancies (a linearly-independent set of vertex locations)

property endmembers_as_independent_endmember_amounts[source]#: Return a list of all the endmembers as a linear sum of the independent endmembers.

property independent_endmember_polytope[source]#: 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[source]#: Gets the limits of the polytope as a function of the independent endmembers.

subpolytope_from_independent_endmember_limits(limits)[source]#: Returns a smaller polytope by applying additional limits to the amounts of the independent endmembers.

subpolytope_from_site_occupancy_limits(limits)[source]#: 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)[source]#

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)[source]#

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)[source]#

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)[source]#

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.simplify_composite_with_composition(composite, composition)[source]#

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