~nickpapior/siesta/trunk-k-file

Merge the 'offsite spin-orbit' implementation by Ramon Cuadrado.

Reference:

R. Cuadrado and J. I. Cerda,
"Fully relativistic pseudopotential formalism under an atomic orbital
basis: spin–orbit splittings and magnetic anisotropies",
J. Phys.: Condens. Matter 24, 086005, (2012)
(DOI:10.1088/0953-8984/24/8/086005)

The new 'offsite' implementation is now the default when

   Spin  { SO, SOC, S+O }
   SpinOrbit T    (deprecated)

is specified in the input fdf file.  To request the 'onsite' approximation,
use

   Spin { SO+onsite, SOC+onsite, S+O+onsite}
   
In this 'offsite' implementation the introduction of a fully
relativistic Hamiltonian is done by using fully non-local operators
for the pseudopotentials. In this way it is possible to avoid the
'onsite' approximation needed to reduce the computational effort
required when explicitly computing the LS term.

The construction of a fully relativistic Hamiltonian involves the use
of a full set of lj KB projectors. These are constructed by new code
in 'atom', and processed in the new routine 'nlefsm_SO_off', which has
roughly the same structure as 'nlefsm', but constructs at the same
time the 'ion' and 'SO' pieces from the relativistic projectors.

This routine calls 'calc_Vj_offsiteSO', where VSO and Vion and the
corresponding forces are computed using the Clebsch–Gordan
coefficients needed to change from the basis |l,m,sigma> to |j,mj>.

The conventions for structure and signs in H and the DM are the same
as in the existing 'onsite' implementation, so there are no changes in
the diagonalization routines, or in the analysis routines and tools.

Eventually, the 'offsite' qualifier might be removed, as this is a
full spin-orbit implementation which involves a similar computational
effort using less drastic approximations.

Note that this merge focuses on the core electronic-structure
functionality of full spin-orbit coupling, and does not provide any
spin-orbit enhancements to the analysis tools.