rxn_network.costs#

rxn_network.costs.base#

Basic interface and implementation for a Calculator and CostFunction.

class rxn_network.costs.base.Calculator[source]#

Bases: MSONable

Base definition for a reaction property calculator.

abstract calculate(rxn)[source]#

Evaluates a particular property of a reaction relevant to its cost ranking.

Parameters:

rxn (Reaction) –

Return type:

float

calculate_many(rxns)[source]#

Convenience method for performing calculate() on a list of reactions.

Parameters:

rxns (list[Reaction]) – the list of Reaction objects to be evaluated

Returns:

A list of the reactions’ calculated property values.

Return type:

list[float]

decorate(rxn)[source]#

Returns a copy of the reaction with the calculated property by storing the value within the reaction’s data dictionary.

Parameters:

rxn (Reaction) – The reaction object.

Returns:

A deep copy of the original reaction with a modified data dict.

Return type:

Reaction

decorate_many(rxns)[source]#

Convenience method for performing decorate() on a list of reactions.

Parameters:

rxns (list[Reaction]) – the list of Reaction objects to be decorated

Returns:

A list of new (copied) reactions with modified data containing their calculated properties.

Return type:

list[Reaction]

class rxn_network.costs.base.CostFunction[source]#

Bases: MSONable

Base definition for a cost function.

abstract evaluate(rxn)[source]#

Evaluates the specified cost function equation on a reaction object.

Parameters:

rxn (Reaction) –

Return type:

float

rxn_network.costs.calculators#

A calculator class for determining chemical potential distance of reactions.

class rxn_network.costs.calculators.ChempotDistanceCalculator(cpd, mu_func='sum', name='chempot_distance')[source]#

Bases: Calculator

Calculator for determining the aggregated “chemical potential distance” for a reaction, in units of eV/atom. This is a reaction selectivity metric based on an aggregation function applied to the chemical potential differences of reactant- product and product-product interfaces in a reaction.

If you use this cost metric, please cite the following work:

Todd, P. K.; McDermott, M. J.; Rom, C. L.; Corrao, A. A.; Denney, J. J.; Dwaraknath, S. S.; Khalifah, P. G.; Persson, K. A.; Neilson, J. R. Selectivity in Yttrium Manganese Oxide Synthesis via Local Chemical Potentials in Hyperdimensional Phase Space. J. Am. Chem. Soc. 2021, 143 (37), 15185-15194. https://doi.org/10.1021/jacs.1c06229.

Parameters:

  • cpd (ChemicalPotentialDiagram) – the chemical potential diagram for the phase space in which the reaction(s) exist

  • mu_func (Callable | str) – the function (or string name of the function) used to aggregate the interfacial chemical potential distances into a single value describing the whole reaction. Current options are 1) max, 2) mean, and 3) sum (default).

  • name (str) – the data dictionary key with which to store the calculated value. Defaults to “chempot_distance”.

calculate(rxn)[source]#

Calculates the aggregate chemical potential distance in eV/atom. The mu_func parameter determines how the individual pairwise interface distances are aggregated into a single value describing the overall reaction. When mu_func = “sum” (i.e., the default setting), the total chemical potential distance is returned.

Parameters:

rxn (ComputedReaction) – the ComputedReaction object

Returns:

The aggregate chemical potential distance of the reaction in eV/atom.

Return type:

float

classmethod from_entries(entries, mu_func='sum', name='chempot_distance', **kwargs)[source]#

Convenience constructor which first builds the ChemicalPotentialDiagram object from a list of entry objects.

Parameters:

  • entries (list[PDEntry]) – entry objects used to build the ChemicalPotentialDiagram

  • mu_func (Callable[[Iterable[float]], float] | str) – the name of the function used to process the interfacial chemical potential distances into a single value describing the whole reaction.

  • name (str) – the data dictionary key by which to store the calculated value, defaults to “chempot_distance”

  • **kwargs – optional kwargs passed to ChemicalPotentialDiagram.

Returns:

A ChempotDistanceCalculator object

Return type:

ChempotDistanceCalculator

class rxn_network.costs.calculators.PrimaryCompetitionCalculator(irh, name='primary_competition')[source]#

Bases: Calculator

Calculator for determining the primary competition, C_1, for a reaction (units: eV/atom).

If you use this selectivity metric in your work, please cite the following work:

McDermott, M. J.; McBride, B. C.; Regier, C.; Tran, G. T.; Chen, Y.; Corrao, A. A.; Gallant, M. C.; Kamm, G. E.; Bartel, C. J.; Chapman, K. W.; Khalifah, P. G.; Ceder, G.; Neilson, J. R.; Persson, K. A. Assessing Thermodynamic Selectivity of Solid-State Reactions for the Predictive Synthesis of Inorganic Materials. arXiv August 22, 2023. https://doi.org/10.48550/arXiv.2308.11816.

Parameters:

  • irh (InterfaceReactionHull) – the interface reaction hull containing the target reaction and all competing reactions.

  • name (str) – the data dictionary key with which to store the calculated value. Defaults to “primary_competition”.

calculate(rxn)[source]#

Calculates the competitiveness score for a given reaction by enumerating competing reactions, evaluating their cost with the supplied cost function, and then using the c-score formula, i.e. the _get_c_score() method, to determine the competitiveness score.

Parameters:

rxn (ComputedReaction) – the ComputedReaction object to be evaluated

Returns:

The C1 score

Return type:

float

class rxn_network.costs.calculators.SecondaryCompetitionCalculator(irh, name='secondary_competition')[source]#

Bases: Calculator

Calculator for determining the secondary competition, C_2, for a reaction (in eV/atom).

If you use this selectivity metric in your work, please cite the following work:

McDermott, M. J.; McBride, B. C.; Regier, C.; Tran, G. T.; Chen, Y.; Corrao, A. A.; Gallant, M. C.; Kamm, G. E.; Bartel, C. J.; Chapman, K. W.; Khalifah, P. G.; Ceder, G.; Neilson, J. R.; Persson, K. A. Assessing Thermodynamic Selectivity of Solid-State Reactions for the Predictive Synthesis of Inorganic Materials. arXiv August 22, 2023. https://doi.org/10.48550/arXiv.2308.11816.

Args: irh: the interface reaction hull containing the target reaction and all competing reactions. name: the data dictionary key with which to store the calculated value. Defaults to “secondary_competition”.

Parameters:
calculate(rxn)[source]#

Calculates the secondary competition per its implementation in the InterfaceReactionHull class.

Parameters:

rxn (ComputedReaction) – the ComputedReaction object to be evaluated

Returns:

The C2 score

Return type:

float

class rxn_network.costs.calculators.SecondaryCompetitionWithEhullCalculator(irh, name='secondary_competition_with_ehull')[source]#

Bases: Calculator

WARNING: this is an alternative calculator for secondary competition (C_2) that includes the energy above hull of the target reaciton. It should only be used for testing purposes.

Parameters:

  • irh (InterfaceReactionHull) – the interface reaction hull containing the target reaction and all competing reactions.

  • name (str) – the data dictionary key with which to store the calculated value. Defaults to “secondary_competition_with_ehull”.

calculate(rxn)[source]#

Calculates the secondary competition with e_hull per its implementation in the InterfaceReactionHull class.

Parameters:

rxn (ComputedReaction) – the ComputedReaction object to be evaluated

Returns:

The C2 + e_hull score

Return type:

float

class rxn_network.costs.calculators.SecondaryCompetitionMaxCalculator(irh, name='secondary_competition_max')[source]#

Bases: Calculator

WARNING: this is an alternative calculator for secondary competition (C_2) that defaults to calculation of the maximum secondary reaction energy. It should only be used for testing purposes.

Parameters:

  • irh (InterfaceReactionHull) – the interface reaction hull containing the target reaction and all competing reactions.

  • name (str) – the data dictionary key with which to store the calculated value. Defaults to “secondary_competition_max”.

calculate(rxn)[source]#

Calculates the secondary competition with max energies.

Parameters:

rxn (ComputedReaction) – the ComputedReaction object to be evaluated

Returns:

The C2 score using max energies.

Return type:

float

class rxn_network.costs.calculators.SecondaryCompetitionAreaCalculator(irh, name='secondary_competition_area')[source]#

Bases: Calculator

WARNING: this is an alternative calculator for secondary competition (C_2) that defaults to calculation of the area of the enclosed hull. It should only be used for testing purposes and is quite unstable.

Parameters:

  • irh (InterfaceReactionHull) – the interface reaction hull containing the target reaction and all competing reactions.

  • name (str) – the data dictionary key with which to store the calculated value. Defaults to “secondary_competition_area”.

calculate(rxn)[source]#

Calculates an area for secondary competition.

Parameters:

rxn (ComputedReaction) – the ComputedReaction object to be evaluated

Returns:

Secondary competition as represented by area.

Return type:

float

rxn_network.costs.functions#

Implementation of cost functions used in the package (e.g., Softplus, WeightedSum).

class rxn_network.costs.functions.Softplus(temp=300, params=None, weights=None)[source]#

Bases: CostFunction

The softplus cost function is a smoothed version of the Rectified Linear Unit (ReLU) function commonly used in neural networks. It has the property that the output goes to 0 as the input goes to negative infinity, but the output approaches a linear scaling as the input goes to positive infinity. This is an especially useful mapping for determining a cost ranking of a reaction.

Parameters:

  • temp (float) – temperature in Kelvin [K]. This serves as a scale factor for the output of the function. Higher temperatures -> lower costs. Defaults to 300 K.

  • params (list[str] | None) – List of data dictionary keys for function parameters used as an argument to the softplus function. Defaults to [“energy_per_atom”]

  • weights (list[float] | None) – List of corresponding values by which to weight the function parameters. Defaults to [1.0].

evaluate(rxn)[source]#

Calculates the cost of reaction based on the initialized parameters and weights.

Parameters:

rxn (ComputedReaction) – A ComputedReaction to evaluate.

Returns:

The cost of the reaction.

Return type:

float

class rxn_network.costs.functions.WeightedSum(params=None, weights=None)[source]#

Bases: CostFunction

This a weighted sum of user-specified parameters. cost = param_1*weight_1 + param_2*weight_2 + param_3*weight_3 …

Args: params: List of data dictionary keys for function parameters used as an

argument to the weighted summation. Defaults to [“energy_per_atom”].

weights: List of corresponding values by which to weight the

function parameters. Defaults to [1.0].

Parameters:
evaluate(rxn)[source]#

Calculates the cost of reaction based on the initialized parameters and weights.

Parameters:

rxn (ComputedReaction) – A ComputedReaction to evaluate.

Returns:

The cost of the reaction.

Return type:

float

rxn_network.costs.pareto#

Functions for performing Pareto front analysis.

rxn_network.costs.pareto.get_pareto_front(df, metrics=('energy', 'primary_competition', 'secondary_competition'), maximize=False)[source]#

Get the Pareto Front for a dataframe of reactions over the specified columns.

Parameters:

  • df (DataFrame) – pandas DataFrame containing synthesis reactions

  • metrics (tuple[str, ...]) – Names of columns over which to calculate the Pareto front

  • maximize (bool) – Whether or not maximal metrics are desired. Defaults to False (i.e., desired solution is to minimize the metrics).

rxn_network.costs.pareto.is_pareto_efficient(costs, return_mask=True)[source]#

Directly lifted from @Peter’s numpy-based solution on stackoverflow. Please give him an upvote here: https://stackoverflow.com/a/40239615. Thank you @Peter!

Parameters:

  • costs – An (n_points, n_costs) array

  • return_mask – True to return a mask

Returns:

An array of indices of pareto-efficient points. If return_mask is True, this will be an (n_points, ) boolean array. Otherwise it will be a (n_efficient_points, ) integer array of indices.