matador.hull package

The hull module provides functionality for creating phase diagrams, voltage curves and volume curves, either directly from a database, or from files.

class matador.hull.QueryConvexHull(query=None, cursor=None, elements=None, species=None, voltage=False, volume=False, subcmd=None, plot_kwargs=None, lazy=False, energy_key='enthalpy_per_atom', client=None, collections=None, db=None, **kwargs)

Bases: object

Construct a binary or ternary phase diagram from a matador.query.DBQuery object, or a list of structures.

cursor

list of all structures used to create phase diagram.

Type

list

hull_cursor

list of all documents within hull_cutoff.

Type

list

chempot_cursor

list of chemical potential documents.

Type

list

structures

all structures used to create hull.

Type

numpy.ndarray

hull_dist

array of distances from hull for each structure.

Type

np.ndarray

species

list of chemical potential symbols.

Type

list

num_elements

number of elements present in the chemical potentials.

Type

int

elements

the elements present in the convex hull.

Type

list

voltage_data

if voltage_curve() has been called, then this is a list of VoltageProfile objects containing Q, x, V and reaction pathways.

Type

list

volume_data

if volume_curve() has been called, then this is a dictionary containing x and volumes per B (in AxBy).

Type

dict

Initialise the class from either a DBQuery or a cursor (list of matador dicts) and construct the appropriate phase diagram.

Keyword Arguments

• query (matador.query.DBQuery) – object containing structures,

• cursor (list(dict)) – alternatively specify list of matador documents.

• species (list(str)) – list of elements/chempots to use, used to provide a useful order,

• voltage (bool) – whether or nto to compute voltages relative for insertion of first entry in species,

• volume (bool) – whether or not to compute volume expansion relative to first entry in species,

• energy_key (str) – key under which the desired energy per atom is stored.

• lazy (bool) – if True, do not create hull until self.create_hull() is called

• chempots (list(float)) – list of chemical potential values to use.

• elements (list(str)) – deprecated form species.

• kwargs (dict) – mostly CLI arguments, see matador hull –help for full options.

• plot_kwargs (dict) – arguments to pass to plot_hull function

• client (pymongo.MongoClient) – optional client to pass to DBQuery.

• collections (dict of pymongo.collections.Collection) – optional dict of collections to pass to DBQuery.

• db (str) – db name to connect to in DBQuery.

create_hull()

Begin the hull creation routines and perform the post-processing specified by initial arguments.

property savefig

True if any figure type argument was passed.

property savefig_ext

Returns the figure extension to save with.

plot_hull(**kwargs)

Hull plot helper function.

plot_voltage_curve(**kwargs)

Voltage plot helper function.

plot_volume_curve(**kwargs)

Volume plot helper function.

fake_chempots(custom_elem=None)

Spoof documents for command-line chemical potentials.

Keyword Arguments

custom_elem (list(str)) – list of element symbols to generate chempots for.

construct_phase_diagram()

Create a phase diagram with arbitrary chemical potentials.

Expects self.cursor to be populated with structures and chemical potential labels to be set under self.species.

set_chempots(energy_key=None)

Search for chemical potentials that match the structures in the query cursor and add them to the cursor. Also set the concentration of chemical potentials in cursor, if not already set.

static filter_cursor_by_chempots(species, cursor)

For the desired chemical potentials, remove any incompatible structures from cursor.

Parameters

• species (list) – list of chemical potential formulae.

• cursor (list) – list of matador documents to filter.

Returns

the filtered cursor.

Return type

list

voltage_curve(cursor=None)

Take a computed convex hull and calculate voltages for either binary or ternary systems. Sets the self.voltage_data attribute with various fields.

Parameters

hull_cursor (list(dict)) – list of structures to include in the voltage curve.

volume_curve()

Take stable compositions and volume and calculate volume expansion per “B” in AB binary.

print_volume_summary()

Prints a volume data summary.

If self.args[‘csv’] is True, save the summary to a file.

get_hull_distances(*args, **kwargs)

Wrapper to PhaseDiagram.get_hull_distances.

class matador.hull.PhaseDiagram(cursor, formation_key, dimension)

Bases: object

This class encapsulates the actual phase data, e.g. the actual energy and compositions found to be stable.

structures

the array passed to init used to make the hull, with the first (num_species-1) columns containing normalised concentrations, and the final column containing formation energy.

Type

numpy.ndarray

convex_hull

the actual convex hull returned by SciPy.

Type

scipy.spatial.ConvexHull

formation_key

index/key specification of formation energy per atom from top level of each document.

Type

list

Compute the convex hull of data passed, to retrieve hull distances and thus stable structures.

Parameters

• cursor (list[dict]) – list of matador documents to make phase diagram from.

• formation_key (str or list) – location of the formation energy inside each document, either a single key or iterable of keys to use with recursive_get.

get_hull_distances(structures, precompute=False, **kwargs)

Returns array of distances to pre-computed binary or ternary hull, from array containing concentrations and energies.

Parameters

structures (numpy.ndarray) – N x n array of concentrations and enthalpies for N structures, with up to 2 columns of concentrations and the last column containing the structure’s formation enthalpy.

Keyword Arguments

precompute (bool) – whether or not to bootstrap hull distances from previously computed values at the same stoichiometry.

Returns

N-dim array storing distances to

the hull for N structures,

Return type

numpy.ndarray

class matador.hull.EnsembleHull(cursor, data_key, energy_key='enthalpy_per_atom', chempot_energy_key=None, num_samples=None, parameter_key=None, species=None, voltage=False, verbosity=None, **kwargs)

Bases: matador.hull.hull.QueryConvexHull

Class to create and store an ensemble of composition vs energy convex hulls from cursor data. The variable energies must be stored under a given key, e.g. doc[‘_beef’][energy_key][beef_index], as specified by init.

Data must be stored in the following way under each document in cursor:

{...,
 data_key: {
    parameter_key: "<list of parameter values>",
    energy_key: "<list of energies at parameter values>",
 },
}

Hull data will be stored as arrays per document under doc[data_key]['hull_distance'] and doc[data_key]['formation_' + energy_key].

Inherits the attributes of matador.hull.QueryConvexHull, with many set to None.

phase_diagrams

list of phase diagram objects for each parameter value.

Type

list of matador.hull.PhaseDiagram

Initialise EnsembleHull from a cursor, with other keywords following QueryConvexHull.

Parameters

• cursor (list[dict]) – list of matador documents containing variable parameter data for energies.

• data_key (str) – the key under which all parameter data is stored to the variable parameter, e.g. _beef or _temperature.

Keyword Arguments

• energy_key (str) – the key under parameter_key to use to create the hulls.

• chempot_energy_key (str) – the key used to create the first convex hull.

• parameter_key (str) – the key pertaining to the variable parameter itself, e.g. temperature or thetas.

• num_samples (int) – use up to this many samples in creating the hull.

• species (list[str]) – list of elements/chempots to use, in the desired order.

• voltage (bool) – whether or not to compute voltage curves.

• plot_kwargs (dict) – arguments to pass to plot_hull function.

• kwargs (dict) – other arguments to pass to QueryConvexHull.

generate_stability_statistics(group_by='structure')

Creates a histogram that counts how many times each structure is found to be stable in the ensemble.

Keyword Arguments

group_by (str) – either ‘structure’ or ‘formula’ for bar groupings.

plot_hull(**kwargs)

Hull plot helper function.

class matador.hull.TemperatureDependentHull(cursor, energy_key='enthalpy_per_atom', temperatures=None, **kwargs)

Bases: matador.hull.hull_ensemble.EnsembleHull

Leverages EnsembleHull to construct temperature dependent hulls from phonon calculations.

Initialise EnsembleHull from a cursor, with other keywords following QueryConvexHull.

Parameters

• cursor (list[dict]) – list of matador documents containing variable parameter data for energies.

• data_key (str) – the key under which all parameter data is stored to the variable parameter, e.g. _beef or _temperature.

Keyword Arguments

• energy_key (str) – the key under parameter_key to use to create the hulls.

• chempot_energy_key (str) – the key used to create the first convex hull.

• parameter_key (str) – the key pertaining to the variable parameter itself, e.g. temperature or thetas.

• num_samples (int) – use up to this many samples in creating the hull.

• species (list[str]) – list of elements/chempots to use, in the desired order.

• voltage (bool) – whether or not to compute voltage curves.

• plot_kwargs (dict) – arguments to pass to plot_hull function.

• kwargs (dict) – other arguments to pass to QueryConvexHull.

data_key = 'temperature'

energy_key = 'free_energy_per_atom'

plot_hull(**kwargs)

Hull plot helper function.

class matador.hull.HullDiff(hull_old, hull_new, **args)

Bases: object

Takes two QueryConvexHull objects and ‘diffs’ them, printing a +/- line for each new/deleted structure within the specified hull cutoff (i.e. compares hull.hull_cursor only).

Initialise difference from two hulls.

Parameters

• hull_old (QueryConvexHull) – older hull object.

• hull_new (QueryConvexHull) – newer hull object.

Keyword Arguments

args – dict, command-line arguments to print results.

print_diff(**args)

Use the display_results function to print the diff.

plot_diff()

Plot the hull with additions ONLY highlighted in green.

matador.hull.diff_hulls(client, collections, **args)

Helper function to diff hulls from cmd-line args.

Parameters

• client (MongoClient) – connection to database

• collections (dict of Collection) – dict of collections to query

Keyword Arguments

args – dict, command-line arguments to select hulls.

Submodules

matador.hull.hull module

This file implements convex hull functionality from database queries.

class matador.hull.hull.QueryConvexHull(query=None, cursor=None, elements=None, species=None, voltage=False, volume=False, subcmd=None, plot_kwargs=None, lazy=False, energy_key='enthalpy_per_atom', client=None, collections=None, db=None, **kwargs)

Bases: object

Construct a binary or ternary phase diagram from a matador.query.DBQuery object, or a list of structures.

cursor

list of all structures used to create phase diagram.

Type

list

hull_cursor

list of all documents within hull_cutoff.

Type

list

chempot_cursor

list of chemical potential documents.

Type

list

structures

all structures used to create hull.

Type

numpy.ndarray

hull_dist

array of distances from hull for each structure.

Type

np.ndarray

species

list of chemical potential symbols.

Type

list

num_elements

number of elements present in the chemical potentials.

Type

int

elements

the elements present in the convex hull.

Type

list

voltage_data

if voltage_curve() has been called, then this is a list of VoltageProfile objects containing Q, x, V and reaction pathways.

Type

list

volume_data

if volume_curve() has been called, then this is a dictionary containing x and volumes per B (in AxBy).

Type

dict

Initialise the class from either a DBQuery or a cursor (list of matador dicts) and construct the appropriate phase diagram.

Keyword Arguments

• query (matador.query.DBQuery) – object containing structures,

• cursor (list(dict)) – alternatively specify list of matador documents.

• species (list(str)) – list of elements/chempots to use, used to provide a useful order,

• voltage (bool) – whether or nto to compute voltages relative for insertion of first entry in species,

• volume (bool) – whether or not to compute volume expansion relative to first entry in species,

• energy_key (str) – key under which the desired energy per atom is stored.

• lazy (bool) – if True, do not create hull until self.create_hull() is called

• chempots (list(float)) – list of chemical potential values to use.

• elements (list(str)) – deprecated form species.

• kwargs (dict) – mostly CLI arguments, see matador hull –help for full options.

• plot_kwargs (dict) – arguments to pass to plot_hull function

• client (pymongo.MongoClient) – optional client to pass to DBQuery.

• collections (dict of pymongo.collections.Collection) – optional dict of collections to pass to DBQuery.

• db (str) – db name to connect to in DBQuery.

create_hull()

Begin the hull creation routines and perform the post-processing specified by initial arguments.

property savefig

True if any figure type argument was passed.

property savefig_ext

Returns the figure extension to save with.

plot_hull(**kwargs)

Hull plot helper function.

plot_voltage_curve(**kwargs)

Voltage plot helper function.

plot_volume_curve(**kwargs)

Volume plot helper function.

fake_chempots(custom_elem=None)

Spoof documents for command-line chemical potentials.

Keyword Arguments

custom_elem (list(str)) – list of element symbols to generate chempots for.

construct_phase_diagram()

Create a phase diagram with arbitrary chemical potentials.

Expects self.cursor to be populated with structures and chemical potential labels to be set under self.species.

set_chempots(energy_key=None)

Search for chemical potentials that match the structures in the query cursor and add them to the cursor. Also set the concentration of chemical potentials in cursor, if not already set.

static filter_cursor_by_chempots(species, cursor)

For the desired chemical potentials, remove any incompatible structures from cursor.

Parameters

• species (list) – list of chemical potential formulae.

• cursor (list) – list of matador documents to filter.

Returns

the filtered cursor.

Return type

list

voltage_curve(cursor=None)

Take a computed convex hull and calculate voltages for either binary or ternary systems. Sets the self.voltage_data attribute with various fields.

Parameters

hull_cursor (list(dict)) – list of structures to include in the voltage curve.

volume_curve()

Take stable compositions and volume and calculate volume expansion per “B” in AB binary.

print_volume_summary()

Prints a volume data summary.

If self.args[‘csv’] is True, save the summary to a file.

get_hull_distances(*args, **kwargs)

Wrapper to PhaseDiagram.get_hull_distances.

matador.hull.hull_diff module

This file implements the diffing of phase diagrams as new structures are added.

Intended usage:

• Compare current hull with 5 days ago

  matador hulldiff -c KSnP -int –compare 5

• Compare hull a month ago to 2 days ago

  matador hulldiff -c KSnP -int –compare 30 2

class matador.hull.hull_diff.HullDiff(hull_old, hull_new, **args)

Bases: object

Takes two QueryConvexHull objects and ‘diffs’ them, printing a +/- line for each new/deleted structure within the specified hull cutoff (i.e. compares hull.hull_cursor only).

Initialise difference from two hulls.

Parameters

• hull_old (QueryConvexHull) – older hull object.

• hull_new (QueryConvexHull) – newer hull object.

Keyword Arguments

args – dict, command-line arguments to print results.

print_diff(**args)

Use the display_results function to print the diff.

plot_diff()

Plot the hull with additions ONLY highlighted in green.

matador.hull.hull_diff.diff_hulls(client, collections, **args)

Helper function to diff hulls from cmd-line args.

Parameters

• client (MongoClient) – connection to database

• collections (dict of Collection) – dict of collections to query

Keyword Arguments

args – dict, command-line arguments to select hulls.

matador.hull.hull_ensemble module

This submodule implements the base class for parameterised phase diagrams.

class matador.hull.hull_ensemble.EnsembleHull(cursor, data_key, energy_key='enthalpy_per_atom', chempot_energy_key=None, num_samples=None, parameter_key=None, species=None, voltage=False, verbosity=None, **kwargs)

Bases: matador.hull.hull.QueryConvexHull

Class to create and store an ensemble of composition vs energy convex hulls from cursor data. The variable energies must be stored under a given key, e.g. doc[‘_beef’][energy_key][beef_index], as specified by init.

Data must be stored in the following way under each document in cursor:

{...,
 data_key: {
    parameter_key: "<list of parameter values>",
    energy_key: "<list of energies at parameter values>",
 },
}

Hull data will be stored as arrays per document under doc[data_key]['hull_distance'] and doc[data_key]['formation_' + energy_key].

Inherits the attributes of matador.hull.QueryConvexHull, with many set to None.

phase_diagrams

list of phase diagram objects for each parameter value.

Type

list of matador.hull.PhaseDiagram

Initialise EnsembleHull from a cursor, with other keywords following QueryConvexHull.

Parameters

• cursor (list[dict]) – list of matador documents containing variable parameter data for energies.

• data_key (str) – the key under which all parameter data is stored to the variable parameter, e.g. _beef or _temperature.

Keyword Arguments

• energy_key (str) – the key under parameter_key to use to create the hulls.

• chempot_energy_key (str) – the key used to create the first convex hull.

• parameter_key (str) – the key pertaining to the variable parameter itself, e.g. temperature or thetas.

• num_samples (int) – use up to this many samples in creating the hull.

• species (list[str]) – list of elements/chempots to use, in the desired order.

• voltage (bool) – whether or not to compute voltage curves.

• plot_kwargs (dict) – arguments to pass to plot_hull function.

• kwargs (dict) – other arguments to pass to QueryConvexHull.

generate_stability_statistics(group_by='structure')

Creates a histogram that counts how many times each structure is found to be stable in the ensemble.

Keyword Arguments

group_by (str) – either ‘structure’ or ‘formula’ for bar groupings.

plot_hull(**kwargs)

Hull plot helper function.

matador.hull.hull_temperature module

This file implements the TemperatureDependentHull class for assessing phase stability from finite temperature free energies.

class matador.hull.hull_temperature.TemperatureDependentHull(cursor, energy_key='enthalpy_per_atom', temperatures=None, **kwargs)

Bases: matador.hull.hull_ensemble.EnsembleHull

Leverages EnsembleHull to construct temperature dependent hulls from phonon calculations.

Initialise EnsembleHull from a cursor, with other keywords following QueryConvexHull.

Parameters

• cursor (list[dict]) – list of matador documents containing variable parameter data for energies.

• data_key (str) – the key under which all parameter data is stored to the variable parameter, e.g. _beef or _temperature.

Keyword Arguments

• energy_key (str) – the key under parameter_key to use to create the hulls.

• chempot_energy_key (str) – the key used to create the first convex hull.

• parameter_key (str) – the key pertaining to the variable parameter itself, e.g. temperature or thetas.

• num_samples (int) – use up to this many samples in creating the hull.

• species (list[str]) – list of elements/chempots to use, in the desired order.

• voltage (bool) – whether or not to compute voltage curves.

• plot_kwargs (dict) – arguments to pass to plot_hull function.

• kwargs (dict) – other arguments to pass to QueryConvexHull.

data_key = 'temperature'

energy_key = 'free_energy_per_atom'

plot_hull(**kwargs)

Hull plot helper function.

voltage_data: List[VoltageProfile]

matador.hull.phase_diagram module

This submodule implements the base PhaseDiagram creator that interfaces with QueryConvexHull and EnsembleHull.

class matador.hull.phase_diagram.PhaseDiagram(cursor, formation_key, dimension)

Bases: object

This class encapsulates the actual phase data, e.g. the actual energy and compositions found to be stable.

structures

the array passed to init used to make the hull, with the first (num_species-1) columns containing normalised concentrations, and the final column containing formation energy.

Type

numpy.ndarray

convex_hull

the actual convex hull returned by SciPy.

Type

scipy.spatial.ConvexHull

formation_key

index/key specification of formation energy per atom from top level of each document.

Type

list

Compute the convex hull of data passed, to retrieve hull distances and thus stable structures.

Parameters

• cursor (list[dict]) – list of matador documents to make phase diagram from.

• formation_key (str or list) – location of the formation energy inside each document, either a single key or iterable of keys to use with recursive_get.

get_hull_distances(structures, precompute=False, **kwargs)

Returns array of distances to pre-computed binary or ternary hull, from array containing concentrations and energies.

Parameters

structures (numpy.ndarray) – N x n array of concentrations and enthalpies for N structures, with up to 2 columns of concentrations and the last column containing the structure’s formation enthalpy.

Keyword Arguments

precompute (bool) – whether or not to bootstrap hull distances from previously computed values at the same stoichiometry.

Returns

N-dim array storing distances to

the hull for N structures,

Return type

numpy.ndarray