Soc PROCAR handling and more

[kavanase]

This is mainly a fix to update the PROCAR handling in easyunfold (also updating to make the Procar object JSON serializable), and in particular updating to handle SOC (ncl) PROCARs. This is now dynamically determined within the Procar parsing code, so when plotting via the CLI the user doesn't need to specify --ncl (previously this information wasn't passed on to the PROCAR parsing anyway).

This fixes the cases I found where plotting failed due to crashes when trying to parse SOC PROCARs, now fixed, giving some nice plots like this:

I've also checked through with previous example cases (NaBiS$_2$, MgO) to confirm the code is working as expected.

This also implements some other fixes:

• Removing all x/y ticks in the sumo DOS plots.
• Using the sumo orbital colour settings if atom projections aren't used and the user doesn't specify
• Docs updates
• Deprecation notices for vscale

[kavanase]

Hi @zhubonan!
So when plotting the atom projections for my Cs$_2$(Sn/Ti)X$_6$ alloys, I realised something a little odd. If you look at the Sn s - Br -p conduction band in this GIF:

or static plot below, you can see that intensity of this band appears quite weak (and doesn't look like a mix between green/blue, just faded grey), and also in the pure Cs$_2$SnBr$_6$ material, it looks basically just blue, despite it being a 50/50 mix of Sn s (green) and Br p (blue) as you can see from the DOS:

But if I swap the colour choice, so that Ti is green and Sn is red, then the colour looks more reasonable/intuitive and more intense/visible:

I dug around for a long while trying to find the origin of this, and how it could be improved. Basically it's related to how the interpolation is done in the transformed LAB space, which can result in some non-intuitive behaviour like this, depending on the colours being mixed (as you end up interpolating into the 'white' origin centre in LAB). I checked and this is similarly the case in sumo (which uses the same interpolation strategy), though the lack of additional transparency (due to the spectral function intensity) and underlying black line makes it much less severe in their case (though still not totally intuitive that 50/50 green/blue gives you that colour I think):

Colorspace	Red-Green-Blue	Pastel
LAB
HSV
RGB
XYZ
LABlch
LUVlch

So I did a systematic check through the different possible colourspaces, using either red-green-blue or pastel red-green-blue as the basis, with these weight choices (covering the typical mixing spectrum)

    weights = np.array([
        [1.0, 0.0, 0.0],
        [1.0, 0.5, 0.0],
        [0.5, 0.5, 0.0],
        [1.0, 1.0, 0.0],
        [0.5, 1.0, 0.0],
        [0.0, 1.0, 0.0],
        [0.0, 1.0, 0.5],
        [0.0, 0.5, 0.5],
        [0.0, 1.0, 1.0],
        [0.0, 0.5, 1.0],
        [0.0, 0.0, 1.0],
        [0.5, 0.0, 1.0],
        [0.5, 0.0, 0.5],
        [1.0, 0.0, 1.0],
        [1.0, 0.0, 0.5],
        [0.5, 0.5, 0.5]])

Using the red-green-blue basis:

Using the pastel basis:

My conclusions/opinions would be that (1) pastel colours are nicer, (2) RGB/XYZ/LAB make intuitive sense mostly, so suggest sticking with LAB as the default colourspace, using the pastel colours if the number of projected species is <= 3 (else red, green, blue, purple, orange, yellow as suggested by colorbrewer.org) and (3) making colorspace an optional parameter at the CLI level.
I've added these updates to the code here. If you're happy with all this then I'll update the atom/orbital-projected plots in MgO and NaBiS2 examples, and we can get this merged! 😃

[kavanase]

Jupyter notebook for testing and plotting these colours here if useful:
easyunfold_colourmap_testing.ipynb.zip

[zhubonan]

Fantastic! Thanks for making such a detailed investigation and tweaking. I am happy with the changes.
Overall, I think it would be unrealistic to expect the colour mixing being able to quantitatively represent the composition of the spectral functions (limited to RGBA channels displayed as RGB). So it makes sense to prioritize having a nicer representation 😄 .

[kavanase]

Ok great! I'll update the docs to match the new defaults, and add the 'example outputs' mini section discussed offline, and then this is ready to be merged ✌️ 🏎️

[kavanase]

All final bits discussed now implemented @zhubonan, this is ready to be merged! 🚀

[kavanase]

Some last formatting changes added there @zhubonan.
The example outputs mini-section can be seen here: https://github.com/SMTG-UCL/easyunfold/tree/SOC-procar-handling
All ready to go.

[zhubonan]

Thanks for the improvements!

Just one minor comment regarding closing file object in _read - I think with clause if not needed. If Procar receives file objects (can be streams) rather than file names/paths, we should keep these objects open .

[zhubonan]

Also, now Procar is MSONable, we should be able to store it inside the easyunfold.json file and/or as a separate file? This way people can get rid of the PROCAR, but I am not sure the space-saving would be much if everything is compressed.

[kavanase]

Hi @zhubonan!
Have now removed the with statement from the _read method as requested.

About saving the PROCAR info to JSON, I was thinking this as well and tried it, but it turned out from testing a few cases that the IO speed from saving/loading the JSON was basically the same as reading the PROCAR from scratch, so there was no benefit in speedup from saving the PROCAR info to JSON. Also the file size was essentially the same as the PROCAR file size, so no file size reduction benefit either.
A disadvantage to this as well is that if it was saved in the easyunfold.json file then it would cause normal plotting functions (without projections) to be much slower as it would take much longer to load the large JSON file.

That said, something related I was going to mention, I think the loops in PROCAR parsing and spectral_function_from_weight_sets could be significantly sped up by only parsing bands with energies within the emin - emax range. Currently they parse all bands and then subselect from there.
I noticed this with the Cs$_2$Sn/TiX$_6$ alloys when trying to debug the colour projections, where I was looking at the eng and sf_rgb arrays directly, and realised they stretched from -37 to +8 eV, even though only plotting from -5 to +5 eV. This is typical of most VASP calculations, so might be worth keeping in mind as a potential route to speeding up parsing for heavier cases (like atom-projected SOC supercells). Can def wait till after the JOSS submission though! 😅

[zhubonan]

All good!

[zhubonan]

I think the loops in PROCAR parsing and spectral_function_from_weight_sets could be significantly sped up by only parsing bands with energies within the emin - emax range. Currently they parse all bands and then subselect from there.

Good point 👍 , can probably implement it later!

Yeah , I agree there is not much point to save PROCAR in JSON for now.

[zhubonan]

Merged! Thanks again for fixing the PROCAR SOC bug and adding secondary axis DOS plot 🎊