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.
_colormap.svg)
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.
Smoothing: adjust smoothing tension from 0 to 1; use 0 for no smoothing and 1 for maximum smoothing. ECharts applies smooth line interpolation (Bezier-style) using this factor.
Plain and filtered bands can be enabled together for overlay comparisons.
Line/Marker Panel
The Line/Marker panel in General Options controls the style of plain-band traces. If a spin-polarized simulation is loaded, a second Line/Marker tile is shown automatically for the spin-down channel.
Line: choose the line style (Solid,
Dashed, or Dotted).
Width: customize the plot lines line width by modifying this field. The units are pixels.
Marker: choose the marker type (None,
Circle, Rect, RoundRect,
Triangle, or Diamond).
Size: set marker size in pixels.
Color: customize the line and marker 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.
Opacity: set the opacity of line and marker style to any value between 0 and 1, where 0 means fully transparent and 1 means fully opaque.
Plot Order: control drawing stack priority; higher values are
drawn on top of lower values, while auto keeps default ordering.
Legend Panel
The Legend Panel in General Options controls the legend label text and label style for plain-band traces. If a spin-polarized simulation is loaded, a second legend-label tile is shown automatically for the spin-down channel.
Label: set the legend label text for the trace.
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.
Fermi Level Panel
The Fermi level panel in General Options controls the horizontal Fermi reference line drawn in the plot.
Show fermi: enable or disable the Fermi reference line.
Shift: apply an additional energy offset before plotting.
The displayed energy reference follows
E - (EF + shift), and the shift unit follows the selected
energy unit in the Units panel.
In EBS, the base Fermi reference comes from the Fermi Energy value entered in the input section before parsing.
Line, Width, Color: control the visual style of the Fermi line.
Opacity: set the opacity of fermi line to any value between 0 and 1, where 0 means fully transparent and 1 means fully opaque.
Plot Order: control rendering priority relative to other traces and overlays.
Bandgap Panel
The Bandgap panel in General Options controls the guide lines and annotations used to visualize the gap.
Show bandgap: enable or disable bandgap guides and labels.
Color, Line, Width: control the style of the bandgap guide lines.
Length: set guide extent to none,
partial, or full.
Fill: choose how the gap region is rendered:
none, hash, or solid.
Arrow: show or hide directional arrow markers.
Value: show or hide the numeric gap label in the selected energy unit.
In EBS, bandgap guides are derived from the valence-band maximum and conduction-band minimum found in the plotted band data.
Filtered Bands Workflow #
Filtered plotting requires projected data and at least one filter card. If projected data is unavailable, adding filters is disabled.
+ Add Filter: add a new filter card with projection-table selection and style controls.
First filter behavior: first-time filter creation enables filtered mode; plain and filtered curves can still be rendered together 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 Panels #
Each filter has a set of control panels that map directly to options consumed by the plotting pipeline.
Coloring Panel
Color / Colormap: choose between a single solid color and colormap-based rendering for each filter.
Color: when Color is selected, use the color picker to set the filter color.
Colormap: when Colormap is selected, choose the palette used to map projected values.
Reverse: reverse the colormap direction.
Opacity: control filter transparency from 0 to 1.
Plot Order: control drawing stack priority; higher values are drawn on top.
Line and Marker Panel
Line: select line style from None, Solid, Dashed, and Dotted.
Width: set line width in pixels. This field is disabled when Line is None.
Marker: select marker type from None, Circle, Rect, RoundRect, Triangle, and Diamond.
Size: set marker size in pixels. This field is disabled when Marker is None.
Value-scaled width/size: in electronic band structure filters, scale line width and marker size using projected values.
Spins/Values Panel
Spin ↑ / Spin ↓: select which spin channels are included for this filter. These checkboxes are shown when spin-resolved projected data is available.
vmin: set the lower bound for colormap normalization.
vmax: set the upper bound for colormap normalization.
Normalize: this does not perform a quantum-mechanical normalization. It only rescales the selected projection values so they add up to one for plotting. Projection values depend on the selected projection basis and projection radii, and the selected set may be incomplete.
Legend Panel
Legend Label: enter custom legend text for the filter. Leave this field empty to use the auto-generated label from your projection selection.
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.