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, include_elemental_electrodes=False, **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

chempots

dictionary mapping formula of chemical potential to the value of the chemical potential used to construct the hull.

Type:

dict

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.

• include_elemental_electrodes (bool) – whether to count elemental materials as starting materials for an electrode when constructing ternary voltage curves.

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: 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: 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, include_elemental_electrodes=False, **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

chempots

dictionary mapping formula of chemical potential to the value of the chemical potential used to construct the hull.

Type:

dict

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.

• include_elemental_electrodes (bool) – whether to count elemental materials as starting materials for an electrode when constructing ternary voltage curves.

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: 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: 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