Electronic Band Structure (EBS)
This page documents the EBS workflow in detail. It covers required files, parsing behavior, plain and filtered plotting, filter controls, projection tables, axis behavior, and export.
The workflow is code-agnostic: upload the files required by your selected parser/code, parse, configure
plain/filtered rendering, and export. Where useful, this page uses VASP file names
(PROCAR, KPOINTS, POSCAR) as concrete examples.
For full styling controls shared across EBS and DOS (figure, title, axes, grid, legend), see Plot Settings.
Input, Parsing, and Energy Shift #
EBS requires band/projection data and optionally path/structure metadata. The exact file names depend on the DFT code/parser. In the current UI, the visible fields are VASP-style examples: PROCAR, KPOINTS, and POSCAR.
After Parse, the parser returns band/projection arrays and metadata
(spins, bands, ions, k-path, energy limits, and species information when available).
If Fermi Energy is provided, energies are shifted to
E - EF and axis labeling is adjusted accordingly.
Although this section resembles uploading files to a website, your files never leave your computer. Parsing and plotting run locally in your browser.
| File | Required | Purpose |
|---|---|---|
PROCAR |
Yes | Band energies and orbital projections used for plain and filtered plotting (VASP example). |
KPOINTS |
No | Improves k-path/high-symmetry labels and segment interpretation (VASP example). |
POSCAR |
No | Provides species/count metadata for grouped ion tables (species rows, VASP example). |
Required files: required inputs are validated before parsing, and missing files are highlighted in the form.
Fermi Energy: enter a valid numeric value to shift energies by E - EF after parsing.
Parse: click parse to load metadata and projected bands; a processing overlay is shown while parsing.
Status handling: parse success/failure is reported to the UI and logged for telemetry.
General Plot Options #
Plot plain bands: plot unfiltered band lines from parsed eigenvalue data.
Plot filtered bands: plot projected/weighted bands from one or more filters.
Smooth bands: apply line smoothing to improve visual continuity; filtered series use stronger smoothing than plain series.
Plain and filtered bands can be enabled together for overlay comparisons.
Filtered Bands Workflow #
Filtered EBS requires projected data and at least one filter. If filtered plotting is requested without a filter, plotting is blocked with a warning.
+ Add Filter: create a new filter with projection selections and style controls.
First filter behavior: first-time filter creation enables filtered mode, disables plain mode, and enables color maps (plain mode can be re-enabled afterward).
Filter scope: each filter has independent projection selections, label controls, and visual styling.
Filter removal: remove filters individually without affecting other filter cards.
Filter Cards #
Each filter has four control cards. These map directly to options consumed by the plotting pipeline.
Coloring Panel
Color: use a single solid color for the filter curve and legend key.
Colormap: map projection weights to a continuous color scale.
Reverse: reverse the colormap direction.
Line and Marker Panel
Line: select None, Solid, Dashed, or Dotted.
Width: set line width in pixels; disabled when Line is None.
Marker: select None, Circle, Rect, RoundRect, Triangle, or Diamond.
Size: set marker size in pixels; disabled when Marker is None.
Value-scaled width/size: toggles projection-based scaling of both line width and marker size.
Values Panel
vmin: set the lower bound for color-map normalization.
vmax: set the upper bound for color-map normalization.
vmin/vmax pair: provide both values together, or leave both in auto mode.
Opacity: set filter transparency.
Smooth: adjust smoothing for this filter only.
Show Values: show or hide numeric min/max labels on the color map.
Legend Panel
Legend Label: enter a custom label for the filter; if left empty, the label is generated from the selected projections.
Solid filters are shown in the legend using the configured line/marker style.
Color: customize the legend label color using the color picker. The appearance of the color picker is defined by the browser. In Firefox, to select a custom color you need to click on the “+” icon.
Weight: customize the font weight using this dropdown. The options correspond to font-thin, font-extralight, font-light, font-normal, font-medium, font-semibold, font-bold, font-extrabold, and font-black, which map to 100, 200, 300, 400, 500, 600, 700, 800, and 900, respectively. Most fonts only provide a subset of these weights (typically normal and bold). You can see examples of fonts that support all weights in Google Fonts.
Style: customize the font style as normal or italic.
Projection Table (Ions, Orbitals, and Spin Channels) #
For each filter, the projection table controls exactly which site/orbital/spin contributions are included in the sum. The table behavior depends on which structural metadata is available after parsing.
Rows: rows represent ions by default, or species-grouped ions when structure metadata matches parsed ion counts.
Columns: columns include orbital channels (s, p, d) and, for non-collinear data, magnetization channels.
Species controls: species headers are collapsible and include species-level checkbox controls.
All: row-level and species-level selection supports indeterminate states when only part of a group is selected.
When only projection data is available (or structure matching fails), the table is shown as generic ion rows. This is still fully functional, but less chemically expressive.
When structure metadata is present through a structure file (e.g. POSCAR) and is consistent with the projected bands file (e.g. PROCAR), ions are grouped by species. This makes filtering faster for multi-element systems because you can apply selections across an entire species block before refining individual ions.
Additional spin/magnetization columns appear for non-collinear calculations. This enables direction-resolved filtering in the same table workflow used for orbital selection.
Axis and Rendering Behavior #
X axis path labels: high-symmetry labels and boundaries are generated from parsed k-path metadata.
Boundary handling: boundary labels such as K|U are split adaptively at zoom edges.
Minor x ticks: minor x ticks and split lines are disabled in custom EBS axis rendering.
Y range: y-axis limits are auto-expanded when color maps or legends require extra vertical room.
Fermi line: when enabled, a horizontal Fermi reference line is drawn above data series.
Filtered rendering: filtered bands use custom ECharts series for weighted color mapping and performance.
Markers: scatter markers can be layered and optionally scaled by projection weight.
Renderer: plot rendering can use canvas or SVG, with export choosing the appropriate renderer by format.
Export and Output #
Use Plot to render, Reset to clear, and Download to export. Export supports PNG, JPEG, and SVG.
Download behavior uses an export helper that requests the required renderer per format (SVG renderer for SVG export; canvas renderer for PNG/JPEG).
Troubleshooting #
Missing required file: shown when a required parser input is not selected before parsing.
Invalid Fermi energy: shown when the Fermi-energy input is not a valid number.
Parsing required: shown when plotting is requested before a successful parse cycle.
Filtered bands require filters: shown when filtered mode is enabled without at least one filter.
Parser errors: shown when the parsing worker fails to initialize or process the provided files.
Export before plotting: shown when download is requested before any plot is rendered.
For parser-specific input requirements by code, refer to the corresponding code parser documentation.