WIP: Added a matrix plot

[pfebrer]

This plot is something that I commonly use and I figured it would be a good addition for the visualization module.

To test it one can do:

import sisl

dm = sisl.get_sile("waterDZP.fdf").read_density_matrix()

dm.plot()

which is just a simple image, but from there you can ask for many extra features like separators or text, which is specially nice for small matrices and can be useful to debug problems in sisl or SIESTA for example.

dm.plot(atom_lines=True, orbital_lines=True, text=".2f")

Let me know if there is some feature that you think could be useful to add, or if there is some default you would change, etc... and then I'll finish the PR with tests and a demo notebook.

@tfrederiksen also if you have something to say I would be happy to hear your thoughts on it :)
And @juijan if you have some idea for something more complex to visualize spin matrices also it would be nice to hear, right know all I can think of is just plotting each component separately.

Cheers!

[codecov]

Codecov Report

Attention: 58 lines in your changes are missing coverage. Please review.

Comparison is base (317ca3d) 85.77% compared to head (80eece0) 85.74%.
Report is 2 commits behind head on main.

Files	Patch %	Lines
src/sisl/viz/figure/matplotlib.py	15.62%	27 Missing ⚠️
src/sisl/viz/plotters/grid.py	52.94%	24 Missing ⚠️
src/sisl/viz/figure/plotly.py	55.55%	4 Missing ⚠️
src/sisl/viz/plotters/matrix.py	96.25%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #668      +/-   ##
==========================================
- Coverage   85.77%   85.74%   -0.03%     
==========================================
  Files         367      372       +5     
  Lines       43917    44277     +360     
==========================================
+ Hits        37669    37967     +298     
- Misses       6248     6310      +62     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[zerothi]

Looks very cool!

Some ideas

• don't show numbers where there are strictly 0's, i.e. when the DM has no entries.
• does it allow one to only plot single isc components? Instead of the folded matrix?
• allow one to see the Mulliken charge by multipliyng with S (this is equivalent to the COOP matrix)
• for spin, an on-top/below quiver plot with the spin projected onto a plane, optionally the Mulliken spin (multiplied by S)
• For H, one can also be interested in the COHP which is H*S. If I recall, COHP should be -HS, but I'll have to double check.

[pfebrer]

It doesn't show any text or colors in the empty entries. Also, the matrix is not folded, all supercells are shown. See this graphene Hamiltonian:

import sisl

g = sisl.geom.graphene()
H = sisl.Hamiltonian(g)

r = (0.1, 1.44)
t = (0.2, -2.7)
H.construct([r, t])

H.plot(text=".2f", sc_lines=True)

But isc could be a nice argument to have to display only one of the supercells. Maybe also k, to visualize the folded matrix.

for spin, an on-top/below quiver plot with the spin projected onto a plane

Good idea, I will add the possibility of plotting one arrow on each matrix element.

Regarding the comments of multiplying by the overlap (e.g. mulliken), the result of those is not a matrix, no? It would be a different visualization, right?

[pfebrer]

I included the possibility to add arrows. The interface is the same as the one to include arrows in the geometry plot. The arrows are normalized so that all of them fit inside the element's box.

import sisl
import numpy as np

g = sisl.geom.graphene()
H = sisl.Hamiltonian(g, dim=2)

r = (0.1, 1.44)
t = (1.9, -2.7)
H.construct([r, t])

# Second dimension is just random
H._csr.data[:, 1] = H._csr.data[:, 0] * (np.random.random(len(H._csr.data)) * 2 - 1)

plot = H.plot(text=".2f", sc_lines=True, dim=0)

# Without arrows
plot.show()

# With arrows
plot.update_inputs(arrows=[
    {"data": H, "center": "middle", "color": "lightgreen", "opacity": 0.7, "name": "Something"}
])

Does this make sense?

Also I was wondering that data with multiple dimensions could also be displayed with multiple color channels. E.g. RGB. I don't know if that would be helpful in some case.

[zerothi]

It doesn't show any text or colors in the empty entries. Also, the matrix is not folded, all supercells are shown. See this graphene Hamiltonian:

Great, looks good!

Regarding the comments of multiplying by the overlap (e.g. mulliken), the result of those is not a matrix, no? It would be a different visualization, right?

The DM elementwise multiplication with S yields the COOP matrix, it can be used to determine bonding-antibonding states.

It is actually more of an energy resolved quantity, think LDOS DM elementwise multiplied with S and summed over orbitals for an atomic visualization. A positive number is anti-bonding, and negative is bonding (if I remember correctly).

[zerothi]

I included the possibility to add arrows. The interface is the same as the one to include arrows in the geometry plot. The arrows are normalized so that all of them fit inside the element's box.
...
Does this make sense?
So here the arrows are the two components? Hmm... It depends, for DM spin data the arrows you plot doesn't really make sense. For a polarized calculation, I would suspect the arrows to be pointing upwards, with the size of the arrow scaled with the spin-magnitude.

For H, I haven't really thought about that. I mean if the up-down components in H are the same, you would get a diagonal arrow, but that can be confusing since the values are the same. So...
Hmm... How to visualize the H is indeed a bit problematic. perhaps it could be showed in the same way as for the DM? Would this make sense? I.e. an effective H along a spin-direction.... ?!?!?

Also I was wondering that data with multiple dimensions could also be displayed with multiple color channels. E.g. RGB. I don't know if that would be helpful in some case.

Again, I think this depends on the matrix data. For instance, for orbital/bond-current matrices, it could be cool to somehow show the off-diagonal arrows as pointing the current towards the other atom, if current is flowing in that direction.

[pfebrer]

The implementation of the arrows just plots the first two components of the sparse matrix that you pass to arrows['data']. This was not a meaningful example, it was just to show how it plots the arrows.

So the user would have to pass arrows that make sense.

If you know about something that would make sense to plot as arrows we can provide functions for it.

[zerothi]

The implementation of the arrows just plots the first two components of the sparse matrix that you pass to arrows['data']. This was not a meaningful example, it was just to show how it plots the arrows.

So the user would have to pass arrows that make sense.

If you know about something that would make sense to plot as arrows we can provide functions for it.

I think for DM, it would make sense to extract the x,y,z components, then project onto a user-defined plane, and then plot that arrow, of course scaled with the spin-magnitude. When the DM is only polarized, I think it only makes sense to plot up/down arrows according to the spin-magnitude.

For the COOP (DM*S) and COHP (-H*S), the same as DM I would suspect.

Same for bond-currents... For H, I don't know, yet ;)

[zerothi]

Here some comments which I think we could use to finalize this:

• allow showing the arrow with the length as the value it represents,
• allow one to disable the colouring (which makes sense when the numerical value is present, and the arrow is there as well)

Then I think we can ship it in

[pfebrer]

Ok, I added the changes you proposed and now I'm writing the tutorial notebook and some tests

[pfebrer]

Could you have a look at the notebook to see if everything works as you would expect? The one in docs/visualization/viz_module/showcase/AtomicMatrixPlot.ipynb

I have to write some tests and then the PR will be ready

[zerothi]

Could you have a look at the notebook to see if everything works as you would expect? The one in docs/visualization/viz_module/showcase/AtomicMatrixPlot.ipynb

I have to write some tests and then the PR will be ready

Looks really nice! Let me know when the tests are ready, it can then be merged. :)

[pfebrer]

Ok, done!