Mutation Module

Contains tools for determining substitution probability of different species and for mutating instances of SmactStructure to predict new structures.

Tools for handling ion mutation.

class smact.structure_prediction.mutation.CationMutator(lambda_df: pd.DataFrame, alpha: Callable[[str, str], float] | None = <function CationMutator.<lambda>>)

Bases: object

Handles cation mutation of SmactStructures based on substitution probability.

Based on the algorithm presented in:

Hautier, G., Fischer, C., Ehrlacher, V., Jain, A., and Ceder, G. (2011) Data Mined Ionic Substitutions for the Discovery of New Compounds. Inorganic Chemistry, 50(2), 656-663. doi:10.1021/ic102031h

complete_cond_probs() → DataFrame

Generate a DataFrame with all the conditional substitution probabilities.

complete_pair_corrs() → DataFrame

Generate a DataFrame with all the pair correlations.

complete_sub_probs() → DataFrame

Generate a DataFrame with all the substitution probabilities.

cond_sub_prob(s1: str, s2: str) → float

Calculate the probability of substitution of one species with another.

cond_sub_probs(s1: str) → Series

Calculate the probabilities of substitution of a given species.

Calculates probabilities of substitution of given species with all others in the lambda table.

static from_json(lambda_json: str | None = None, alpha: Callable[[str, str], float] | None = <function CationMutator.<lambda>>) → CationMutator

Create a CationMutator instance from a DataFrame.

Args:

lambda_json (str, optional): JSON-style representation of the

lambda table. This is a list of entries, containing pairs and their associated lambda values. Each entry is a list of [species1, species2, lambda]. If not supplied, defaults to the lambda table included with pymatgen.

alpha: See __init__().

Returns:

A CationMutator instance.

get_lambda(s1: str, s2: str) → float

Get lambda values corresponding to a pair of species.

Args:

s1 (str): One of the species. s2 (str): The other species.

Returns:

lambda (float): The lambda value, if it exists

in the table. Otherwise, the alpha value for the two species.

get_lambdas(species: str) → Series

Get all the lambda values associated with a species.

Args:

species (str): The species for which to get the

lambda values.

Returns:

A pandas Series, with index-labelled lambda entries.

pair_corr(s1: str, s2: str) → float

Determine the pair correlation of two ionic species.

same_spec_cond_probs() → Series

Calculate the same species conditional substitution probabilities.

same_spec_probs() → Series

Calculate the same species substitution probabilities.

sub_prob(s1: str, s2: str) → float

Calculate the probability of substitution of two species.

sub_probs(s1: str) → Series

Determine the substitution probabilities of a species with others.

Determines the probability of substitution of the species with every species in the lambda table.

unary_substitute(structure: SmactStructure, thresh: float | None = 1e-05) → Generator[tuple[SmactStructure, float, str, str], None, None]

Find all structures with 1 substitution with probability above a threshold.

Args:

structure: A SmactStructure instance from which to generate compounds. thresh (float): The probability threshold; discard all substitutions that have

a probability to generate a naturally-occuring compound less than this.

Yields:

Tuples of (SmactStructure, probability, original species, new species).