FleurinpModifier

Description

The FleurinpModifier class has to be used if you want to change anything in a stored FleurinpData. It will store and validate all the changes you wish to do and produce a new FleurinpData node after you are done making changes and apply them.

FleurinpModifier provides a user with methods to change the Fleur input. In principle a user can do everything, since he could prepare a FLEUR input himself and create a FleurinpData object from that input.

Note

In the open provenance model nodes stored in the database cannot be changed (except extras and comments). Therefore, to modify something in a stored inp.xml file one has to create a new FleurinpData which is not stored, modify it and store it again. However, this node would pop into existence unlinked in the database and this would mean we loose the origin from what data it comes from and what was done to it. This is the task of FleurinpModifier.

Usage

To modify an existing FleurinpData, a FleurinpModifier instance has to be initialised staring from the FleurinpData instance. After that, a user should register certain modifications which will be cached and can be previewed. They will be applied on a new FleurinpData object when the freeze method is executed. A code example:

from aiida_fleur.data.fleurinpmodifier import  FleurinpModifier

F = FleurinpData(files=['inp.xml'])
fm = FleurinpModifier(F)                                # Initialise FleurinpModifier class
fm.set_inpchanges({'dos' : True, 'Kmax': 3.9 })         # Add changes
fm.show()                                               # Preview
new_fleurinpdata = fm.freeze()                          # Apply

The figure below illustrates the work of the FleurinpModifier class.

User Methods

General methods

• validate(): Tests if the changes in the given list are validated.
• freeze(): Applies all the changes in the list, calls modify_fleurinpdata() and returns a new FleurinpData object.
• changes(): Displays the current list of changes.
• show(): Applies the modifications and displays/prints the resulting inp.xml file. Does not generate a new FleurinpData object.

Modification registration methods

The registration methods can be separated into two groups. First of all, there are XML methods that require deeper knowledge about the structure of an inp.xml file. All of them require an xpath input:

• xml_set_attribv_occ(): Set an attribute of a specific occurrence of xml elements
• xml_set_first_attribv(): Set an attribute of first occurrence of xml element
• xml_set_all_attribv(): Set attributes of all occurrences of the xml element
• xml_set_text(): Set the text of first occurrence of xml element
• xml_set_text_occ(): Set an attribute of a specific occurrence of xml elements
• xml_set_all_text(): Set the text of all occurrences of the xml element
• create_tag(): Insert an xml element in the xml tree.
• delete_att(): Delete an attribute for xml elements from the xpath evaluation.
• delete_tag(): Delete an xml element.
• replace_tag(): Replace an xml element.
• add_num_to_att(): Adds a value or multiplies on it given attribute.

On the other hand, there are shortcut methods that already know some paths:

• set_species(): Specific user-friendly method to change species parameters.
• set_atomgr_att(): Specific method to change atom group parameters.
• set_species_label(): Specific user-friendly method to change a specie of an atom with a certain label.
• set_atomgr_att_label(): Specific method to change atom group parameters of an atom with a certain label.
• set_inpchanges(): Specific user-friendly method for easy changes of attribute key value type.
• shift_value(): Specific user-friendly method to shift value of an attribute.
• shift_value_species_label(): Specific user-friendly method to shift value of an attribute of an atom with a certain label.
• set_nkpts(): Specific method to set the number of kpoints.
• set_nmmpmat(): Specific method for initializing or modifying the density matrix file for a LDA+U calculation (details see below)

The figure below shows a comparison between the use of XML and shortcut methods.

Modifying the density matrix for LDA+U calculations

The above mentioned set_nmmpmat() takes a special role in the modification registration methods, as the modifications are not done on the inp.xml file but the density matrix file n_mmp_mat used by Fleur for LDA+U calculations. The resulting density matrix file is stored next to the inp.xml in the new FleurinpData instance produced by calling the freeze() method and will be used as the initial density matrix if a calculation is started from this FleurinpData instance.

The code example below shows how to use this method to add a LDA+U procedure to an atom species and provide an initial guess for the density matrix.

from aiida_fleur.data.fleurinpmodifier import  FleurinpModifier

F = FleurinpData(files=['inp.xml'])
fm = FleurinpModifier(F)                                             # Initialise FleurinpModifier class
fm.set_species('Nd-1', {'ldaU':                                      # Add LDA+U procedure
                       {'l': 3, 'U': 6.76, 'J': 0.76, 'l_amf': 'F'}})
fm.set_nmmpmat('Nd-1', orbital=3, spin=1, occStates=[1,1,1,1,0,0,0]) # Initialize n_mmp_mat file with the states
                                                                     # m = -3 to m = 0 occupied for spin up
                                                                     # spin down is initialized with 0 by default
new_fleurinpdata = fm.freeze()                                       # Apply

Note

The n_mmp_mat file is a simple text file with no knowledge of which density matrix block corresponds to which LDA+U procedure. They are read in the same order as they appear in the inp.xml. For this reason the n_mmp_mat file can become invalid if one adds/removes a LDA+U procedure to the inp.xml after the n_mmp_mat file was initialized. To circumvent these problems always remove any existing n_mmp_mat file from the FleurinpData instance, before adding/removing or modifying the LDA+U configuration. Furthermore the set_nmmpmat() should always be called after any modifications to the LDA+U configuration.