Charge decorators#

For charge assignment.

Charges will be assigned by magnitudes of magnetic moments.

class ChargeDecorator(labels=None, max_allowed_abs_charge=0)[source]#

Bases: BaseDecorator

Abstract decorators to assign charge.

Initialize.

Parameters:

labels (dict of str or Species to list) – optional A table of labels to decorate each element with. keys are species symbol, values are possible decorated property values, such as oxidation states, magnetic spin directions. Values are sorted such that the corresponding cluster centers of the required property is increasing. For example, in Mn(2, 3, 4)+ (high spin), the magnetic moments is sorted as [Mn4+, Mn3+, Mn2+], thus you should provide labels as {Element(“Mn”):[4, 3, 2]}. Keys can be either Element and Species object, or their string representations. Currently, do not support decoration of Vacancy. If you have multiple required properties, or required properties have multiple dimensions, the labels order must match the sort in the order of self.required_properties. Properties are sorted lexicographically. This argument may not be necessary for some decorator, such as GuessChargeDecorator. Be sure to provide labels for all the species you wish to assign a property to, otherwise, you are responsible for your own error!
max_allowed_abs_charge (float) – optional Maximum allowed absolute value of charge in a decorated structure entry. If the absolute value of structure charge exceeds this value, the entry will be filtered and returned as a NoneType. Default to 0, which means we require absolute charge balance.

as_dict()[source]#: Serialize to dict.

decorated_prop_name = 'oxi_state'#

classmethod from_dict(d)[source]#: De-serialize.

required_prop_names = None#

class FixedChargeDecorator(labels=None, max_allowed_abs_charge=0)[source]#

Bases: ChargeDecorator, NoTrainDecorator

Assign fixed charge to each element from setting.

Warning

This Decorator should never be used on structures with multi-valent elements!

Initialize.

Parameters:

labels (dict of str or Species to list) – optional A table of labels to decorate each element with. keys are species symbol, values are possible decorated property values, such as oxidation states, magnetic spin directions. Values are sorted such that the corresponding cluster centers of the required property is increasing. For example, in Mn(2, 3, 4)+ (high spin), the magnetic moments is sorted as [Mn4+, Mn3+, Mn2+], thus you should provide labels as {Element(“Mn”):[4, 3, 2]}. Keys can be either Element and Species object, or their string representations. Currently, do not support decoration of Vacancy. If you have multiple required properties, or required properties have multiple dimensions, the labels order must match the sort in the order of self.required_properties. Properties are sorted lexicographically. This argument may not be necessary for some decorator, such as GuessChargeDecorator. Be sure to provide labels for all the species you wish to assign a property to, otherwise, you are responsible for your own error!
max_allowed_abs_charge (float) – optional Maximum allowed absolute value of charge in a decorated structure entry. If the absolute value of structure charge exceeds this value, the entry will be filtered and returned as a NoneType. Default to 0, which means we require absolute charge balance.

decorate(entries)[source]#

Decorate entries by guessed charges.

Warning: Do not use this with multi-valent elements, unless you know what you want clearly!!!

Parameters:: entries (List[ComputedStructureEntry]) – Entries of computed structures.
Returns:: Entries with decorated structures or failed structures.
Return type:: list of NoneType or ComputedStructureEntry

decorated_prop_name = 'oxi_state'#

required_prop_names = []#

class MagneticChargeDecorator(labels, cuts=None, max_allowed_abs_charge=0)[source]#

Bases: GpOptimizedDecorator, ChargeDecorator

Assign charges from magnitudes of total magentic moments on sites.

Uses Gaussian process to optimize charge assignment.

Note

Does not support cp2k or force field!

Initialize.

Parameters:

labels (dict of str to list of int}) – A table of species as key, and charges to decorate to the species in the key. Values of a key should be sorted as the decorated species should have increasing magnetic moment. For example, in Mn(2, 3, 4)+ all high spin, the magnetic moments is sorted as [Mn4+, Mn3+, Mn2+], therefore, you should provide labels as {Element(“Mn”):[4, 3, 2]}. Keys can be either Element|Species object, or their string representations. Currently, do not support decoration of Vacancy. This argument may not be necessary for some sub-classes, such as: GuessChargeDecorator. Be sure to provide labels for all the species you wish to assign a property to, otherwise, you are the cause of your own error!
cuts (dict of str to list of int or float}) – optional A table of species and cutting points of the magnetic moments, so that a magnetic moment is compared with each of these cutting values, and decided which charge label it should be assigned with.
max_allowed_abs_charge (float) – optional Maximum allowed absolute value of charge in a decorated structure entry. If the absolute value of structure charge exceeds this value, the entry will be filtered and returned as a NoneType. Default to 0, which means we require absolute charge balance.

decorated_prop_name = 'oxi_state'#

required_prop_names = [('magmom', 'calcs_reversed.0-output.outcar.magnetization.^tot')]#

class PmgGuessChargeDecorator(labels=None, max_allowed_abs_charge=0)[source]#

Bases: ChargeDecorator, NoTrainDecorator

Assign charges from pymatgen automatic guesses.

Note

This class does not need labels.

Warning

This Decorator should never be used on structures with multi-valent elements!

Initialize.

Parameters:

labels (dict of str or Species to list) – optional A table of labels to decorate each element with. keys are species symbol, values are possible decorated property values, such as oxidation states, magnetic spin directions. Values are sorted such that the corresponding cluster centers of the required property is increasing. For example, in Mn(2, 3, 4)+ (high spin), the magnetic moments is sorted as [Mn4+, Mn3+, Mn2+], thus you should provide labels as {Element(“Mn”):[4, 3, 2]}. Keys can be either Element and Species object, or their string representations. Currently, do not support decoration of Vacancy. If you have multiple required properties, or required properties have multiple dimensions, the labels order must match the sort in the order of self.required_properties. Properties are sorted lexicographically. This argument may not be necessary for some decorator, such as GuessChargeDecorator. Be sure to provide labels for all the species you wish to assign a property to, otherwise, you are responsible for your own error!
max_allowed_abs_charge (float) – optional Maximum allowed absolute value of charge in a decorated structure entry. If the absolute value of structure charge exceeds this value, the entry will be filtered and returned as a NoneType. Default to 0, which means we require absolute charge balance.

decorate(entries)[source]#

Decorate entries by guessed charges.

Parameters:: entries (list of ComputedStructureEntry) – The entries of computed structures.
Returns:: Entries with decorated structures or failed structures.
Return type:: list of NoneType or ComputedStructureEntry

decorated_prop_name = 'oxi_state'#

property is_trained#: Always considered trained.

required_prop_names = []#

train(entries=None, reset=False)[source]#

Train the model.

This decorator does not require training at all. Keep this method just for consistency.