StructureData

In aiida-atomistic we provide two StructureData classes:

1. StructureData, the AiiDA data type used to store a structure in the AiiDA database. It is immutable, i.e. after the initialization we cannot modify it. It is just a container for structure information;
2. StructureDataMutable, a python class used to manipulate a structure object before to transform it into the immutable StructureData;

With respect to orm.StructureData, here we provide additional properties to be attached to the structure, e.g. charges, magmoms. Kind based definition of the sites is dropped, and the kind_name is attached to each site as a property. The two StructureData and StructureDataMutable share the same data structure; the difference is that the latter can be modified by the user after its initialization, and not strict validation checks are done, at variance with the StructureData. Moreover StructureDataMutable will have additional set_* methods to help the user to update the structure. The properties are stored under the properties attribute of the structure, which is a pydantic BaseModel subclass, for data validation.

StructureData(s) initialization¶

As both StructureData and StructureDataMutable share the same data structure, they also share the same inputs for the constructor: a python dictionary. The format of this dictionary exactly reflects how data are stored in the AiiDA database:

As we provide the structure_dict to the constructor of our two structure data classes, it is immediately used to feed the properties model. Each site is store as SiteMutable (SiteImmutable) object for the mutable (immutable) case. Mutability (immutability) is inherited from the corresponding StructureData class used.

The full list of properties can be visualized using the to_dict method of the structure:

We can see that some properties are generated automatically, like kinds, charges, dimensionality and so on, and some other properties are set by default if not provided, e.g. the kind_name of each site.

Initialization from ASE or Pymatgen¶

If we already have an ASE Atoms or a Pymatgen Structure object, we can initialize our StructureData by means of the built-in from_ase and from_pymatgen methods. For ASE:

In the Pymatgen case:

Moreover, we also provide to_ase and to_pymatgen methods to obtain the corresponding instances.

Passing from StructureData to StructureDataMutable and viceversa¶

Mutation of a StructureData instance¶

Let’s suppose you want to update some property in the StructureData before to use it in a calculation. You cannot. The way to go is either to use ASE or Pymatgen to modify your object and store it back into StructureData, or to use the StructureDataMutable and its mutation methods, and then convert it into StructureData. The latter method is the preferred one, as you then have support also for additional properties (to be implemented) like hubbard, which is not supported in ASE and Pymatgen.

StructureDataMutable properties can be modified directly, but also the class contains several set_ methods and more, needed to update a structure. Let’s suppose we start from an immutable StructureData and we want to update the charges (and the corresponding kinds):

It is also possible to add_atom, pop_atom, update_site and so on. Indeed, we can start from and empty StructureDataMutable (i.e., from scratch):

Slicing a structure¶

It is possible to slice a structure, i.e. returning only a part of it (in terms of sites). The method returns a new sliced StructureDataMutable (StructureData) instance.

Automatic kinds generation¶

It is possible to automatically detect kinds when initializing the structure from ASE or Pymatgen. Moreover, the kind can be also generated during the to_dict call, such that our output_dictionary will already have the detected kinds. In summary, we can generate our StructureData/StructureDataMutable with automatic kind detection in these three ways:

1. new_structuredata = StructureData.from_ase(ase_structure, detect_kinds=True)
2. new_structuredata = StructureData.from_pymatgen(pymatgen_structure, detect_kinds=True)
3. new_structuredata = StructureData(**old_structuredata.to_dict(detect_kinds=True))

We can also directly put our new sites in the starting mutable_structure:

How to Query StructureData using properties¶

Thanks to the additional computed properties in our StructureData (formula, symbols, kinds, masses, charges, magmoms, positions, cell_volume, dimensionality), we can easily query for a structure:

How to define alloys and deal with vacancies¶

It is possible to define more than one element for a given site, i.e. to define an alloy. This can be done by providing as symbol the combination of the symbols, and also the corresponding weights tuple:

if not provided, the mass is computed accordingly to the symbols and weights. Vacancies are detected when the sum of the weights is less than 1.

How to add custom properties¶

It is possible to add custom properties at the StructureData level (not at the Site level). To do that, it is sufficient to put the corresponding property under the custom Field, a dictionary which should contain the custom property names as keys, followed by the corresponding value:

Backward compatibility support¶

We can use the to_legacy method to return the corresponding orm.StructureData instance starting from a StructureDataor StructureDataMutable instance, if a given plugin does not yet support the new StructureData.