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_fractionsboolean (default is False)

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_edgeinteger (default is 2)

Number of points per edge of the polytope.

unique_sortedboolean (default is True)

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‘independent endmember proportions’ (default) or ‘site occupancies’

Whether to grid the polytope in terms of independent endmember proportions or site occupancies.

limits2D numpy array

Additional inequalities restricting the gridded area of the polytope.

Returns
——-
points2D numpy array

A list of points gridding the polytope.

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
charges2D 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_totalfloat

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

return_fractionsboolean

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

Returns
polytopeburnman.polytope.MaterialPolytope object

A polytope object corresponding to the parameters provided.

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_occupancies2D 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_fractionsboolean

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

Returns
polytopeburnman.polytope.MaterialPolytope object

A polytope object corresponding to the parameters provided.

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
compositeburnman.Composite object

A composite containing one or more SolidSolution and Mineral objects.

compositiondictionary

A dictionary containing the amounts of each element.

return_fractionsboolean

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

Returns
polytopeburnman.polytope.MaterialPolytope object

A polytope object corresponding to the parameters provided.

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 solid solutions, this function will return a composite that only contains the Mg-bearing endmembers.

Parameters
compositeburnman.Composite object

The initial Composite object

compositiondictionary

A dictionary containing the amounts of each element

Returns
simple_compositeburnman.Composite object

The simplified Composite object