Select projections

[jimustafa]

These changes are an attempt to address #131.

The primary change is the addition of some logic to remove the restriction that the number of projections must be equal to the number of Wannier functions. Now the projections block can define more than num_wann projections, as long as num_proj is defined. When the AMN file is being read, select_projections determines which elements enter in the construction of the projection matrices.

A few ancillary changes have also been made:

1. added a "standard" TeX gitignore file for the documentation source tree
2. added magic comments to the user guide source TeX files to enable IDEs with TeX support to compile the document from any of the source files (eg, Sublime Text using LaTeXTools)

Additional remarks:

• specifying the num_proj parameter is a bit of a quiz for the user; it may be better to implement projections counting in param_get_projections (like in param_get_range_vector)

[codecov]

Codecov Report

Merging #200 into develop will increase coverage by 0.35%.
The diff coverage is 82.5%.

@@             Coverage Diff             @@
##           develop     #200      +/-   ##
===========================================
+ Coverage    60.93%   61.28%   +0.35%     
===========================================
  Files           29       29              
  Lines        16971    17098     +127     
===========================================
+ Hits         10341    10479     +138     
+ Misses        6630     6619      -11

Impacted Files	Coverage Δ
src/kmesh.F90	60.93% <42.85%> (+0.74%)	⬆️
src/overlap.F90	76.61% <80%> (-0.03%)	⬇️
src/parameters.F90	81.04% <85.18%> (+0.67%)	⬆️
src/wannierise.F90	77.32% <0%> (+0.06%)	⬆️
src/disentangle.F90	79.14% <0%> (+0.35%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ea4017b...30c66b3. Read the comment docs.

[jryates]

Jamal - thanks for the interesting contribution. I can certainly see the logic in what you propose. I would like to talk through the implications with the other developers and will do so next time we have developers' call (we do this roughly every 6 weeks).
Jonathan

[giovannipizzi]

Dear Jamal,
thanks a lot for your contribution, that looks very interesting.
We've discussed this at our developers' meeting and we would like to ask you to do a few changes before we merge. Could you do the following?

• rebase on develop (or merge and solve conflicts). The tricky part here is that we've introduced in Added pre-commit hooks to fix indentation and trailing whitespace #203 (see also Trailing Whitespace #190) fixes for the indentation that changed most of the files. Luckily your changes to the .F90 files are not extensive so in the worst case you can re-apply them on top of develop. After this, you'll find instructions on how to run the fprettify command to indent according to our code style here: https://github.com/wannier-developers/wannier90/wiki/ContributorsGuide#automatic-pre-commits-spaces-indentation- (sorry for the hassle...)
• print the output of the selected projections in the header: now only all of them are printed - good to print both all and the selected ones only

  wannier90/src/parameters.F90

  Lines 2582 to 2600 in e233ffe

  	! Projections
  	if (iprint > 1 .and. allocated(proj_site)) then
  	write (stdout, '(32x,a)') '-----------'
  	write (stdout, '(32x,a)') 'PROJECTIONS'
  	write (stdout, '(32x,a)') '-----------'
  	write (stdout, *) ' '
  	write (stdout, '(1x,a)') '+----------------------------------------------------------------------------+'
  	write (stdout, '(1x,a)') '| Frac. Coord. l mr r z-axis x-axis Z/a |'
  	write (stdout, '(1x,a)') '+----------------------------------------------------------------------------+'
  	do nsp = 1, num_proj
  	write (stdout, '(1x,a1,3(1x,f5.2),1x,i2,1x,i2,1x,i2,3(1x,f6.3),3(1x,f6.3),2x,f4.1,1x,a1)')&
  	& '|', proj_site(1, nsp), proj_site(2, nsp), &
  	proj_site(3, nsp), proj_l(nsp), proj_m(nsp), proj_radial(nsp), &
  	proj_z(1, nsp), proj_z(2, nsp), proj_z(3, nsp), proj_x(1, nsp), &
  	proj_x(2, nsp), proj_x(3, nsp), proj_zona(nsp), '|'
  	end do
  	write (stdout, '(1x,a)') '+----------------------------------------------------------------------------+'
  	write (stdout, *) ' '
  	end if

  )
• currently, some parts of the code will not work/be compatible with your changes, because (e.g. in guiding centres and other places like selectively-localised WFs) the codes expects that proj_site (and the other projection-related arrays) have length num_bands. We suggest the following:
  • Read the arrays in new arrays (e.g. input_proj_site, input_proj_l, ...)
  • after checking select_projections, fill in proj_site and all other projection-related arrays as expected by the rest of the code
  • in a few places, you will still need to use, instead, input_proj_*, like when printing the header (see point above) and in the functions in kmesh.F90 when running in -pp mode to generate the .nnkp file.
• remove the num_proj from the input - as you note, it's redundant and potentially confusing. This can be set internally from the select_projections input.

Thanks a lot in advance!

[jimustafa]

Thanks for the feedback! I see your points and have tried to make the appropriate changes.

The last point is something that I still have been unable to address. Since the input_proj_* arrays are allocated within param_get_projections, it is not clear to me how to know the number of projections beforehand. It seems that counting the number of projections within param_get_projections, and then calling the routine again after num_proj has been set, is not that straightforward.

Please advise me on how to best determine num_proj before a call to param_get_projections. Much appreciated!

[giovannipizzi]

There a few ways that come to my mind to do this.
The approach that to me looks closer to what is done for other parts in the code (e.g. when reading blocks) is the following:

• add a boolean flag to param_get_projections (count, that if True will just return the value), and an additional integer that will be set when count = .true. (or actually could always be set to num_proj - but you still need the count=True boolean flag to avoid allocation in the first round).
• Add a few 'if' statements in the param_get_projections routine to skip parts that would allocate the proj_* arrays at the beginning (so that this is not done when count = True), and of setting the arrays. In the meantime keep a counter of how many projections there are.
• As soon as possible, if count = True, set the additional integer parameter to the detected value on num_proj and return (e.g. skipping the final normalisation).

Actually, the additional flag could have an intent inout and be used in the second call, with count=False, to pass in the value of num_proj.

[giovannipizzi]

Hi @jimustafa, just to update on our internal timeline:

• we met today for a Wannier90 coding day
• we will meet again end of November, so if you have the chance to do the remaining changes before Nov 25 it would be great, so we have the time to review and merge it. If you don't think you'll manage, please let us know so next month we'll merge your PR in a branch and continue working on it
• we plan to release 3.0 around mid-December

Thanks!

[jimustafa]

With the most recent commit, I believe the feature has been completed. If there are any additional items identified during the next Wannier90 coding day, please let me know and I will try to have them complete by mid-December. Any feedback from @greschd would be appreciated, regarding whether the feature helps with the use cases that led to #131.

[greschd]

Hi @jimustafa. I haven't had the chance to try this out yet, but from what I see it does indeed seem to solve the use case for #131. Thanks a lot!

[giovannipizzi]

Thanks! This looks great!