API changes in dft_tools

[mferrero]

This is an issue to discuss small API changes in the dft_tools.

[pseth]

Summary of changes made in 1.2-dev branch:

The changes made help enforce/maintain the following guiding principles for dft_tools:

• make everything in dft_tools independent of the impurity solver,
• converters take in dft input and create single hdf5 archive with all the relevant info,
• make sumk_lda and sumk_lda_tools completely independent of the dft code provided,
• avoid function repetition (and hence reduce amount of code to maintain).

Major

• given that sumk_lda is independent of the xc potential, change all instances of lda -> dft!
• functionality provided in solver_multiband.py is now separated: -- pytriqs.operators.hamiltonians: construct common Hamiltonians (density-density, Kanamori, Slater), -- pytriqs.applications.dft.U_matrix: construct appropriate U matrices for different types of Hamiltonians and bases, for greater clarity and to allow users to quickly change solver type in their script without changing the dft_tools sources.
• h5 changes: -- all information from converted dft inputs is now stored in the groups 'dftinput' or 'dft_input' for symm/bands/parproj/etc., -- these input groups should NOT ever be modified after conversion, -- information users wish to save should go in a separate group, e.g. 'dmft_output' , -- some new pieces of information are now saved during conversion instead of recomputed in sumk_dft, -- functions common to wien2k_converter.py and hk_converter.py have been moved to converter_tools.py.
• The following two scripts are provided to help with archive management: -- update_archive.py: update dft_tools v1.0 output file to be compatible with v1.2. Note: this script does not move/rename user-set groups such as Sigma, G, etc., -- clear_h5_output.py: remove dft_output and dmft_output fields, ie. revert state of h5 to the original converter output.

Minor/internal

• Small API changes (e.g. shells/corr_shells are list of dicts with keys ['atom','sort','l','dim','SO','irep'])
• Separated a certain number of functions that are not used and will not be documented
• Merged simple_point_dens_mat and density_gf into a single function density_matrix
• Generally, made indices more uniform, removed redundancies/repeated chunks of code, added comments, etc, to make code simpler, shorter and more legible
• Merged lattice_gf_matsubara and lattice_gf_realfreq into a single function lattice_gf. This will require distinguishing G_latt_w, G_latt_iw, Sigma_imp_w, Sigma_imp_iw, and so more changes elsewhere.
• Merged downfold_pc, rotloc_all with downfold and rotloc.

To do still

• Documentation
• Generalise computation of quantities to allow for these three cases where possible: -- mu = 0, with_Sigma = F ('non-interacting'), -- mu /= 0, with_Sigma = F, -- mu /= 0, with_Sigma = T ('interacting').
• Tidy up sumk_dft_tools.py: -- merge check_input_dos, dos_partial and partial_charges?

[opeil]

At the moment, none of the API methods read the information about the band range for each k-point (e.g. file 'case.oubwin' as produced by dmftproj). I think the user should have a possibility to access this information in order, for instance, to build explicitly an upfolded lattice GF (I know at least one scenario when it is needed).

• My suggestion: Add an additional array or list to the h5-file and require from all converters to generate it from their input files (e.g. in case of Wien2k, read in '*.oubwin' and store the data into the h5-file).

[opeil]

• Use the same convention for the parameter list of methods 'total_density()', 'extract_G_loc()', 'lattice_GF_matsubara()': in all three cases, parameter 'mu' should be optional (if mu=None then mu is set to self.chemical_potential).

[opeil]

• The method 'total_density()' should have an additional parameter 'withSigma' (similar to 'extract_G_loc()' and 'lattice_GF_matsubara()').

[opeil]

I agree with Pri that we should

• Merge 'check_input_dos()' and 'dos_partial()' (where we add an option 'withSigma').
• Also, DOS should be returned from the function and output to text files should be optional (parameter 'save_to_file=True'). This can be useful when one wants to do some extra manipulations with partial DOSes.

[leopo]

Some points:

• in converters one should have an option of chosing a different name for *.h5 compared to the one of input from DFT. In 1.0 those are forced to be the same
• "- these *input groups should NOT ever be modified after conversion" I guess, this means in the course of a normal calculation. Sometimes one needs to change them "by hand"
• "Adapt U_matrix for wien2k cubic convention" Not only cubic. One should also have the possibility to apply any unitary transformation to the U matrix, which we had in 0.8 and 1.0
• "-- merge check_input_dos, dos_partial and partial_charges?" I think dos_partial and partial_charges will be hard (and probably, useless) to merge, they work on different axes (matsubara vs. real) and produce different type of output

[pseth]

Leonid,

in converters one should have an option of chosing a different name for *.h5 compared to the one of input from DFT. In 1.0 those are forced to be the same.

I have done this already.

"- these *input groups should NOT ever be modified after conversion" I guess, this means in the course of a normal calculation. Sometimes one needs to change them "by hand"

Yes, you can change them yourself but they should not change during the calculation.

"Adapt U_matrix for wien2k cubic convention" Not only cubic. One should also have the possibility to apply any unitary transformation to the U matrix, which we had in 0.8 and 1.0

Any generic transformation is already handled, but given that we often use Wien2k, I will build in the specific unitary matrix there.

[edererc]

Just a few comments from our (ETH) side. We looked mainly at the information that should be written to the h5 file if one wants to build a new converter. I think more or less everything is clear except for the following few things:

• there seems to be an inconsistency in the description of density_required/charge_below between what is written in doc/reference/h5structure.rst and how it is used in the code. In h5structure.rst it says that density_required-charge_below is the density of the correlated electrons. However from sumk_dft.py it seems that density_required-charge_below should rather be the total number of electrons in the full energy window (i.e. eventually including also uncorrelated bands). By the way, I don't see why charge_below is needed at all. The code seems to only use density_below-charge_required?
• In h5structure.rst it is said that index values for 'sort' or 'atom' in variables shell or corr_shells should start from 0 (which seems natural within python). However, in the example for the simple H(k) converter they start from 1.

Another thing: where has the multiband_solver gone? Will this now be part of the new cthyb or did I miss something? It used to be part of the old sumk_lda, right?

Ok, that's all for now. Maybe we'll have more questions/suggestions once we start writing the new converter.

[pseth]

Hi Claude,

Another thing: where has the multiband_solver gone? Will this now be part of the new cthyb or did I miss something?

See "Major", point 2 in my comment above. So the functionality is still there, though packaged differently.

It used to be part of the old sumk_lda, right?

It wasn't technically part of the sum_lda, but it shipped with dft_tools.

Pri

[pseth]

@edererc We have updated the doc for both the points that you raised. Thanks!

[pseth]

I think everything here is resolved, closing.