Spin-orbit documentation

[camelto2]

Please review the developer documentation
on the wiki of this project that contains help and requirements.

Proposed changes

This PR adds some of the needed documentation in order to carry out spin-orbit calculations in QMCPACK for VMC/DMC. I added information in each of the relevant sections (Hamiltonian and Observables, Quantum Monte Carlo methods, etc) as well as a dedicated Spin-Orbit calculations in QMC section. I documented each of the relevant changes in the qmcpack input files in order to carry out one of these calculations, as well as provide some of the theory since this is likely unfamiliar to many users.

What type(s) of changes does this code introduce?

Delete the items that do not apply

• Documentation content changes

Does this introduce a breaking change?

• No

What systems has this change been tested on?

macbook

Checklist

Update the following with a yes where the items apply. If you're unsure about any of them, don't hesitate to ask. This is
simply a reminder of what we are going to look for before merging your code.

• Yes. This PR is up to date with current the current state of 'develop'
• No. Code added or changed in the PR has been clang-formatted
• No. This PR adds tests to cover any new code, or to catch a bug that is being fixed
• Yes. Documentation has been added (if appropriate)

[qmc-robot]

Can one of the admins verify this patch?

[rcclay]

Ok to test.

[ye-luo]

No need to block this PR but after reading the documentation, I feel the current way is error-prone and need to simplify the input.

1. the input of tag of spinor needs to be at particleset input. variable spins can be unique_ptr ParticleScalar_t initialized when activated.
2. spo input doesn't need to have special type="spinorbspline", if particleset can be used to tell spinor.
3. the same logic as 2 applies to hamiltonian and driver.

[camelto2]

.

No need to block this PR but after reading the documentation, I feel the current way is error-prone and need to simplify the input.

1. the input of tag of spinor needs to be at particleset input. variable spins can be unique_ptr ParticleScalar_t initialized when activated.
2. spo input doesn't need to have special type="spinorbspline", if sposet can be used to tell spinor.
3. the same logic as 2 applies to hamiltonian and driver.

I agree that making some simplifications in the input specification is probably needed in the future. Moving the information into particleset seems reasonable, as we can just activate the appropriate builders in the code if the flag is present in particleset as opposed to reading it in multiple places from the xml input.

The only thing I would like to keep in the Hamiltonian is the physicalSO flag, because there are some use cases where we would want to accumulate the spin-orbit as an observable but not have it in the local energy (like the perturbative/downfolding approach of Wagner). I think that particular parameter is more appropriate in the hamiltonian input.

[ye-luo]

@rcclay approve?

[rcclay]

LGTM