Nexus documentation

[jtkrogel]

There are a wide variety of features in Nexus that are not documented in the QMCPACK or Nexus manuals. This issue page serves as a space to communicate which Nexus features, workflows, or associated tools should be prioritized for documentation.

User documentation:

• [x] How to perform excited state calculations with QMCPACK
• [ ] Tutorial/walk through for research level calculation (by @prckent and @eneuscamman )
• [ ] Details of automated optimal Jastrow selection (by @kayahans )
• [ ] In code documentation of major user facing functions (generate_qmcpack, etc), accessible via help() (@mcbennet )

Developer documentation:

• [ ] How to add a new machine
• [ ] How to contribute to the testing system

Examples:

• [ ] Examples demonstrating use of QMCPACK observables (by @kylanpaa )
• [ ] Example illustrating automatic QE restarts (by Ron Cohen)

Requested user meeting topics:

• [ ] Detailed design/use of the Structure class (by @lshulen and @Paul-St-Young )
• [ ] Use of PWSCF and QMCPACK analyzer classes (by @Paul-St-Young and @mcbennet )
• [ ] How to use the testing system and add new tests (by @jtkrogel and @markdewing )
• [ ] How to add a new machine (multiple interest)

See also #322 (Nexus features) and #158 (Nexus tests)

[prckent]

I would like to read a detailed walk through of a research level calculation. "How this paper was done". "Figure 1 come from ... ". etc. Hopefully this can be recycled from a recent paper and can make use of data on materialsdatafacility.org

[eneuscamman]

I agree. Even for the simplest case, like DFT -> Simple VMC for Jastrow -> DMC, would be great. Especially if there were both a solid state and a molecular example.

[Paul-St-Young]

I would like to read tutorials on ways to build on existing calculations. Namely, tutorials that answer questions such as:

1. I have a folder of 100 DFT calculations. How do I run DMC on top?
2. I have an example DMC calculation. How do I add observables? How do I check the dependence of my results on parameters A,B,C ...?
3. I have a wavefunction for system in condition A. How do I check the quality of this wavefunction for the same system in condition B? ...

[kayahans]

I also wanted to add a few points in addition to some of the points that are already discussed:

1. I think Nexus has several utilities to select the best supercell given the volume multiplier and the unit cell. It would be nice if this is mentioned in the manual in addition to discussing what is the criteria to choose each supercell matrices. This may already be a part of the workflows in Nexus, but I didn’t check. It would also be nice to discuss a complete example where extrapolation to infinite supercell is performed (as suggested already). It would also be nice to show how additional observables (such as charge density, dipole moments etc.) can be accumulated and then analyzed (via qmca?).

2. To me it was not very clear how the jastrows are transferred from VMC-opt to DMC calculation. For example, after an energy minimization calculation, does Nexus pick the Jastrow parameters that provide the minimum energy in that loop (or similarly the one with the minimum variance in a varmin calculation)? Or does it transfer the Jastrow parameters from the last step?

3. I think how to set up 3-body Jastrow parameters should be mentioned both in Nexus and QMCPACK manuals. As I learned from the QMCPACK Google forum, QMCPACK is using the same 3-body parameters in Neil Drummond’s paper, PRB 70 235119, (2004). By default, Nexus setups different parameters for antiparallel and parallel spin electrons, but it would be nice to see how one can use the same parameters for all of them.

[ye-luo]

@kayahans 2) My experience with OneShiftOnly optimizer, If the VMC energy of the last few blocks are within the error bar of each other, you can take any of them. I always take the last. Minimum energy is not a safe choice because you might have a lower energy in the very beginning due to not equilibrated samples especially when you restart a run. I would recommend Nexus to use my way.

[kayahans]

@ye-luo Thanks Ye for the suggestions, I agree with you. But the manual says that for OneShiftOnly optimizer (pg. 101):

If the VMC energy of the last optimization iterations grows signicantly, increase minwalkers closer to 1 and make the optimization stable.

Although I didn't have any such problems, I thought that the last step of the optimization may not be safe as well. If you have a DFT->VMC->DMC routine and such a problem is not picked up, then you can waste a lot of computation time.

[ye-luo]

@kayahans I wrote that line in the manual just in case. It's good that you don't see that case and neither do I. I think Nexus can inspect the last few iterations and see if the energy values are within the error bar of each other and decide whether to stop or pick the last one and go for DMC.

[kylanpaa]

I believe that following could attract new users for both Nexus and QMCPACK (there is some overlap with the above suggestions):

• Complete workflow with relaxation, DFT (scf) with the relaxed structure, DFT (nscf) to get the orbitals, Jastrow optimization, VMC, DMC, and how to post-process the relevant observables.

• Example of optical gap calculations, and perhaps even of the gap on a few points along some specific direction.

• Example on how to determine proper supercell: tiling and Wigner radius study.

• Example of inclusion of relevant observables, e.g. momentum distribution, and of finite size corrections.

• Description on how to ensure that one gets correct wave functions (referring to k-grid) from DFT if the simulation cells are of different size.

• Description of analysis commands and related thresholds that would be good to reach, such as variance to energy ratio etc. in the Jastrow optimization.