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 and 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, at variance with the StructureData, no strict validation checks are performed. Moreover, StructureDataMutable will have additional setter methods. The properties are stored under the properties attribute of the structure, which is a pydantic BaseModel subclass, particularly convenient 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 set of keyword arguments describing the properties. These can be easily organized in a python dictionary. This dictionary and the data stored in the AiiDA database have a 1-to1 correspondence:

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

The structure can be dumped into a dictionary using the to_dict method of the structure, which is nothing else than a wrapper for the pydantic BaseModel model_dump method of the properties attribute:

Useful methods are provided to help the user modify the structure. As a rule, sites cannot be modified directly (these are derived from the list of properties). In general, we can modify a site just using the update_site method of the structure class:

Other methods to update specific properties are: set_pbc, set_cell, set_charges, set_magmoms, set_automatic_kinds, set_site_property and so on. You can see them using tab-completion.

Print defined and supported set of properties¶

To print the supported properties, use the get_supported_properties method of the structure class. List of the defined properties for the structure can be accessed using the get_defined_properties.

An additional way to define a structure: a sites list¶

We can also provide the dictionary containing the sites as list of dictionaries, each of them describing a site. This is useful when we want to provide additional information for each site, such as the occupancy or the magnetic moment. In this case, the dictionary should have the following structure:

structure_dict = {
    'cell':[[2.75,2.75,0],[0,2.75,2.75],[2.75,0,2.75]],
    'pbc': [True,True,True],
    'sites':[
        {
            'symbols':'Si',
            'positions':[3/4, 3/4, 3/4],
        },
        {
            'symbols':'Si',
            'positions':[1/2, 1/2, 1/2],
        },
    ],
}

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.

Mutation of a StructureDataMutable 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 like the Hubbard U, is not supported in ASE and Pymatgen.

Conversion from StructureData to StructureDataMutable and viceversa¶

We provide two methods to convert back and forth between StructureData and StructureDataMutable. This is useful if we start with a StructureData and we need to modify it:

Methods to update properties¶

StructureDataMutable properties can be modified directly, but also the class contains several setter (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):

To remove properties, we can use the clear_property method, providing as input parameter the string representing the name of the property: mutable_structure.clear_property("magmoms")

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 for a given structure. This is done by default 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. This is valid also for the get_value, from_mutable methods. In summary, we can control automatic kind detection in the initialization of our StructureData/StructureDataMutable:

1. new_structuredata = StructureData.from_ase(ase_structure, detect_kinds=False) # default is True
2. new_structuredata = StructureData.from_pymatgen(pymatgen_structure, detect_kinds=False) # default is True
3. new_structuredata = StructureData(**old_structuredata.to_dict(detect_kinds=True)) # default is False
4. new_structuredata = StructureData.from_mutable(mutable_structure, detect_kinds=True) # default is False

To return the list of sites with the automatically generated kinds, you can also invoke the get_kinds method in this way

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. We can provide the alloy in two ways:

• a unique string, e.g. ‘CuAl’;
• a list of strings, e.g. [‘Cu’, ‘Al’]; elements of the list should be valid chemical symbols;

it is mandatory to also provide the corresponding weights tuple.

In the structure data object, the symbols and the kinds will always be stored as (and if necessary converted to) strings, even if we provide the list of elements of a given alloy site. In a separated section we will explain in more detail how to efficiently query alloys. We can verifiy that the site represents an alloy and we can access the list of its elements:

Also the structure itself will have the is_alloy property:

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). These are defined as properties which are not officially supported in the atomistic package. 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¶

As minimal backward compatibility (which will be dropped in future versions), we implemented the to_atomistic method in the old orm.StructureData, so that it is possible to start from an old structure and dump the corresponding instance of the new data type.