smact.screening module

smact.screening module#

Tools for screening chemical compositions based on SMACT rules.

class smact.screening.ICSD24FilterConfig(include_zero: bool = False, consensus: int = 3, commonality: str | float = 'medium')[source]#

Bases: object

Parameters for ICSD24 oxidation state filtering.

include_zero#

Include oxidation state of zero. Default is False.

Type:

bool

consensus#

Minimum number of literature occurrences for an ion to be considered valid. Default is 3.

Type:

int

commonality#

Excludes species below a certain proportion of appearances. “low”, “medium”, “high”, “main”, or a float/int threshold.

Type:

str | float

commonality: str | float = 'medium'#
consensus: int = 3#
include_zero: bool = False#
class smact.screening.SmactFilterOutputs(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)[source]#

Bases: StrEnum

Allowed outputs of the smact_filter function.

composition_dict = 'composition_dict'#
default = 'default'#
formula = 'formula'#
smact.screening.eneg_states_test(ox_states: Sequence[int], enegs: Sequence[float | None]) → bool[source]#

Internal function for checking electronegativity criterion.

This implementation is fast as it ‘short-circuits’ as soon as it finds an invalid combination. However it may be that in some cases redundant comparisons are made. Performance is very close between this method and alternatives.

Args:#

ox_states (list): oxidation states corresponding to species

in compound

enegs (list): Electronegativities corresponding to species in

compound

Returns:#

boolTrue if anions are more electronegative than

cations, otherwise False

smact.screening.eneg_states_test_threshold(ox_states: Sequence[int], enegs: Sequence[float | None], threshold: float = 0) → bool[source]#

Internal function for checking electronegativity criterion.

This implementation is fast as it ‘short-circuits’ as soon as it finds an invalid combination. However it may be that in some cases redundant comparisons are made. Performance is very close between this method and alternatives.

A ‘threshold’ option is added so that this constraint may be relaxed somewhat.

Args:#

ox_states (list): oxidation states corresponding to species

in compound

enegs (list): Electronegativities corresponding to species in

compound

threshold (Option(float)): a tolerance for the allowed deviation from

the Pauling criterion

Returns:#

boolTrue if anions are more electronegative than

cations, otherwise False

smact.screening.ml_rep_generator(composition: list[Element] | list[str], stoichs: list[int] | None = None) → list[float][source]#

Function to take a composition of Elements and return a list of values.

Values are between 0 and 1 that describes the composition, useful for machine learning.

The list is of length 103 as there are 103 elements considered in total in SMACT.

e.g. Li2O –> [0, 0, 2/3, 0, 0, 0, 0, 1/3, 0 ….]

Inspired by the representation used by Legrain et al. DOI: 10.1021/acs.chemmater.7b00789

Args:#

composition (list): Element objects in composition OR symbols of elements in composition stoichs (list): Corresponding stoichiometries in the composition

Returns:#

norm (list): List of floats representing the composition that sum

to one

smact.screening.pauling_test(oxidation_states: Sequence[int], electronegativities: Sequence[float | None], symbols: Sequence[str] | None = None, repeat_anions: bool = True, repeat_cations: bool = True, threshold: float = 0.0) → bool[source]#

Check if a combination of ions makes chemical sense.

(i.e. positive ions should be of lower electronegativity).

Args:#

oxidation_states (list): oxidation states of elements in the compound electronegativities (list): the corresponding Pauling electronegativities

of the elements in the compound

symbols (list) : chemical symbols of each site threshold (float): a tolerance for the allowed deviation from

the Pauling criterion

repeat_anionsboolean, allow an anion to repeat in different

oxidation states in the same compound

repeat_cations : as above, but for cations

Returns:#

bool:

True if anions are more electronegative than cations, otherwise False

smact.screening.smact_filter(els: tuple[Element, ...] | list[Element], threshold: int | None = 8, stoichs: list[list[int]] | None = None, species_unique: bool = True, oxidation_states_set: str = 'icsd24', return_output: SmactFilterOutputs = SmactFilterOutputs.default) → list[tuple[tuple[str, ...], tuple[int, ...], tuple[int, ...]]] | list[tuple[tuple[str, ...], tuple[int, ...]]] | list[str] | list[dict][source]#

Function that applies the charge neutrality and electronegativity tests.

Applied in one go for simple application in external scripts that wish to apply the general ‘smact test’.

Warning

For backwards compatibility in SMACT >=2.7, explicitly set oxidation_states_set to ‘smact14’ if you wish to use the 2014 SMACT default oxidation states. In SMACT 3.0, the smact_filter function will be set to use a new default oxidation states set.

Args:#

els (tuple/list): A list of smact.Element objects. threshold (int): Threshold for stoichiometry limit, default = 8. stoichs (list[list[int]]): A selection of valid stoichiometric

ratios for each site.

species_unique (bool): Whether or not to consider elements in

different oxidation states as unique in the results.

oxidation_states_set (string): A string to choose which set of

oxidation states should be chosen. Options are ‘smact14’, ‘icsd16’, “icsd24”, ‘pymatgen_sp’ and ‘wiki’ for the 2014 SMACT default, 2016 ICSD, 2024 ICSD, pymatgen structure predictor and Wikipedia oxidation states respectively. A filepath to an oxidation states text file can also be supplied as well.

return_output (SmactFilterOutputs): If set to ‘default’, the

function will return a list of tuples containing the tuples of symbols, oxidation states and stoichiometry values. “formula” returns a list of formulas and “composition_dict” returns a list of dictionaries.

Returns:#

allowed_comps (list): Allowed compositions for that chemical system in the form [(elements), (oxidation states), (ratios)] if species_unique=True and tuple=False or in the form [(elements), (ratios)] if species_unique=False and tuple=False.

Example usage:
>>> from smact.screening import smact_filter
>>> from smact import Element
>>> els = (Element("Cs"), Element("Pb"), Element("I"))
>>> comps = smact_filter(els, threshold=5)
>>> for comp in comps:
...     print(comp)
[('Cs', 'Pb', 'I'), (1, -4, -1), (5, 1, 1)]
[('Cs', 'Pb', 'I'), (1, 2, -1), (1, 1, 3)]
[('Cs', 'Pb', 'I'), (1, 2, -1), (1, 2, 5)]
[('Cs', 'Pb', 'I'), (1, 2, -1), (2, 1, 4)]
[('Cs', 'Pb', 'I'), (1, 2, -1), (3, 1, 5)]
[('Cs', 'Pb', 'I'), (1, 4, -1), (1, 1, 5)]
Example (using stoichs):
>>> from smact.screening import smact_filter
>>> from smact import Element
>>> comps = smact_filter(els, stoichs=[[1], [1], [3]])
>>> for comp in comps:
...     print(comp)
[('Cs', 'Pb', 'I'), (1, 2, -1), (1, 1, 3)]
smact.screening.smact_validity(composition: Composition | str, use_pauling_test: bool = True, include_alloys: bool = True, check_metallicity: bool = False, metallicity_threshold: float = 0.7, oxidation_states_set: str | None = None, icsd_filter: ICSD24FilterConfig | None = None, mixed_valence: bool = False) → bool[source]#

Check if a composition is valid according to SMACT rules.

  1. Passes charge neutrality.

  2. Passes (optional) Pauling electronegativity test, or is considered an alloy or metal if so chosen.

This function short-circuits, returning True as soon as a valid combination is found.

Parameters:

  • composition (Composition or str) – Composition to check.

  • use_pauling_test (bool) – Whether to apply the Pauling EN test.

  • include_alloys (bool) – Consider pure metals valid automatically.

  • check_metallicity (bool) – If True, consider high metallicity valid.

  • metallicity_threshold (float) – Score threshold for metallicity validity.

  • oxidation_states_set (str) – Which set of oxidation states to use. If specified it overrides the ICSD24 filter.

  • icsd_filter (ICSD24FilterConfig) – Configuration for ICSD24 oxidation state filtering. Only used when oxidation_states_set is None. Defaults to ICSD24FilterConfig() (consensus=3, commonality=”medium”).

  • mixed_valence (bool) – If True, allow mixed valence elements to be treated as separate species. Default is False.

Returns:

True if the composition is valid, False otherwise.

Return type:

bool