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:

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:

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).

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;

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;

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:

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