Band Structure Visualiser

A plotly.js renderer for Bands, DOS, combined Bands/Dos and fatBands.

The BandsVisualiser requires atleast one of two arrays:

- bandDataArray
- dosDataArray

Related repositories:

- https://github.com/osscar-org/widget-bandsplot (A similar Jupyter widget)
- https://github.com/materialscloud-org/bands-widget (outdated version used in legacy)
- https://github.com/materialscloud-org/mc-react-bands (the current implementation on MCXD)

Installation

The bands-visualiser entire source is published as an npm package.
``
npm install bands-visualiser
`

Basic Usage

The bandsVisualiser renders through plotly.js and can be invoked into a html element via:

`JSX
import { BandsVisualiser } from "bands-visualiser";

BandsVisualiser(container, {
bandsDataArray: [test_bands],
});
`

It's expected that each entry into this array will be an object with a "typeData" key and a "traceFormat" key. If no traceFormat is supplied, some basic formatting is applied.

minimum example objects:

`JSX
bandObject = {
bandsData: {
path: [["A", "B"], ["B","C"], ... ],
paths: [{values: [[], [], ...], x:[0, 1, ... ]}]
}
traceFormat: {}
}

dosObject = {
dosData: {x: [], y: []
}
traceFormat: {
name: "Total DOS",
fillcolor: "rgba(180, 20, 20, 0.6)", //
...
}
}
`

aiida discerns spin polarised calculations through indexing. If you would like to render up and down spins with different format some work is needed.

The splitBands utility can split a BandsData (passing along the same path/paths).

`JSX
import { splitBandsData,} from "./lib/utils/dataUtils.js";

const splitBands = splitBandsData(bandsData, nParts=2)
[bandsDown, bandsUp] = splitBands
`

Its then easy to pass traceFormatting information to this these;

`JSX
bandsDataArray = [
{
bandsData: bandsDown,
traceFormat: {
label: "Down Channel",
line: {
color: "blue", dash: "dash"}}},
{
bandsData: bandsUp,
traceFormat: {
label: "Up Channel",
line: {
color: "red", dash: "solid"}}}
]
`

The traceFormat key follows the format of plotly traces; for a full list of possible props see: https://plotly.com/python/reference/scatter/.

Advanced Usage

Projections are embedded inside the bandsDataObject;

`JSX
bDO = {
bandsData: { x: [], y [[]]: path: ..., paths: ...}
traceFormat: {} // formatting for the
projections: [
{
projData: {
weights: [[]],
},
traceFormat: {name: "projection 1"}
},
{
projData: {
weights: [[]],
},
traceFormat: {name: "projection 2", showlegend: false}
},
]
}
`

Calling the BandsVisualiser with this bDO will render projections by default:

`JSX
BandsVisualiser(container, {
bandsDataArray: [bDO],
fermiLevels: [21],
});
``