How to deal with kinds

• specific thresholds
• standard thresholds
• example on how properties are changing (ex. classification of magmoms wrt threshold and so on)

In this section we will go deeply into the kinds property and we will explain how to set them both manually and automatically. We suggest the user to use the automatic kinds generation function in the StructureDataMutable and then check the results before storing the actual AiiDA StructureData node.
The manual kinds re-assignement should be done only for simple cases (i.e. few atoms), and can be done easily (using the mutable StructureData):

structure.properties.kinds = ['Fe1', 'Fe2']

Automatic kinds generation¶

In the following, it is shown how to generate kinds in an automatic fashion. This routine considers only site properties (charges, magmoms and so on), not global ones (e.g. pbc, Hubbard and so on). For now, we don’t consider the weights property.

Let’s suppose to start from magnetic iron unit cell:

This structure contains two Fe atoms with a different magnetic moment (the magmoms property). They should correspond to two different kinds. As already mentioned above, we can set this manually:

such that now the sites (derived) property will be:

Another possibility is to do it automatically using the built-in routine, the get_kinds method of the structure instance. Let’s suppose we just want to generate the kinds, to check that the classification is done correctly. Directly invoking the get_kinds method will returns a dictionary containing all the properties and, in particular, the kinds. In particular, the value of the properties will be the one assigned by the classification algorithm.

We find indeed two kinds, with two the same properties but the magmoms. These dictionary can be directly used to build a new instance of the structure: new_structure = StructureData(**structure.get_kinds())

In the explanation of the classification algorithm, we mentioned that some default thresholds for the properties are used. The corresponding values are contained in the _DEFAULT_THRESHOLDS variable, as defined in the package:

we see that for magmoms, the threshold is 1e-4 for each component. These are reasonable thresholds, which however can be overridden, as show in the following.

Defining custom thresholds for the properties¶

We can provide a dictionary of custom threshold to the get_kinds method. This can be done easily, providing the custom_thr dictionary input, where the keys are the properties, the values being the new thresholds. Let’s suppose to impose a larger threshold for magnetic moments, so that we find only one kind in our iron lattice.

We find, indeed, only one kind. Moreover, we see that the magmoms values is now the same, indicating that they are of the same kind. This value is chosen to be the upper value of the given box in the property space (see the explanation on the classification algorithm for more details).

This works also for multiple properties at the same time. Let’s suppose to have also charges:

Excluding some properties in the kinds determination¶

It is also possible to ignore some property in the kinds determination. This should be used with particular attention, as using directly its results can lead to inconsistencies in calculations. To exclude a property in the analysis, we can just put it in the exclude input list (where the elements are strings of names for the properties):

Automatically updating the kinds for a given (mutable) StructureData¶

It is possible to automatically update the kinds of a given StructureDataMutable, without the need of returning the dictionary or list with the new kinds (i.e., without invoking directly the get_kinds method). We provide the set_automatic_kinds method to do it:

This will automatically populate the structure instance with the correct kind names and value of the properties.

The classification algorithm explained¶

The classification algorithm is basically is composed of two steps:

1 - for each property, compute the kinds; 2 - considering the whole set of properties, compute the unique set of kinds.

the main part is the first step. Basically, for each property, we divide the property space into sectors, where each sector corresponds to regions where the property value for two atoms is to be considered the same, within the threshold. The lowest value between these sites is taken as representative value of the property.

Below, we show the example for the kinds determination with respect to the charge property. We suppose to have four iron sites with, respectively, charges 0, 0.05, 0.12 and 0.19. A graphical representation of the algorithm follows:

In this case, two kinds are determined. The first kind (site 0 and 1) will have charge = 0, the second one (site 2 and 3) will have charge = 0.12 (the value of site 2). Indeed: