Band structure and DOS format

Ouro renders any file ending in .bandstructure as an interactive electronic band structure, and any file ending in .dos as an interactive density of states. The formats are open: any service, script, or agent that writes a file following this page gets the same viewer that Ouro's DFT routes use.

Both files carry energies you already computed. The viewer plots them as given and derives only what follows directly from them, such as the band gap.

What the viewer shows

A .bandstructure file draws its bands along the high-symmetry path, with labeled k-points and the Fermi level marked. When the file also carries a density of states, the DOS is drawn beside the bands on the same energy axis. Spin-polarized bands are drawn in two colors, one per spin channel.

The viewer reports whether the structure is metallic, a half-metal, or gapped. For a gapped structure it gives the gap, whether it is direct or indirect, and marks the band edges, and it measures energies from the valence band maximum rather than the Fermi level. It estimates carrier effective masses at the band edges along each path direction that leaves them. With a spin-polarized DOS it gives the magnetic moment, and for metals the spin polarization at the Fermi level.

Readers can hover a band to read its energy and, with band projections, the orbital character of that state. Projections also let readers choose an element or orbital and see the bands thicken where it sits. Readers can narrow the energy window and break the DOS down by element or by orbital.

A .dos file on its own is drawn with energy along the horizontal axis, spin down mirrored below spin up. Embedded in a post, either file shows with a compact hover card.

Encoding

Both files are a single UTF-8 JSON object. Upload them with the .bandstructure or .dos extension; the content type is application/json.

• Energies are absolute, in eV, as your code reports them. Each file gives its own Fermi level, and the viewer plots energies relative to it, or to the valence band maximum when there is a gap.
• Arrays with a spin dimension have one entry for a non-spin-polarized calculation and two, spin up then spin down, for a spin-polarized one.

Band structure files

Each band is a list with one energy per k-point, in path order. Bands may cross; the viewer draws each band index as one line and doesn't reorder them.

Take the Fermi level from a calculation that samples the whole Brillouin zone, such as the self-consistent run the bands started from. Occupations along a path don't.

K-points

distances starts at 0 and never decreases. Its units only set the relative widths of the path's segments, so any consistent convention works, with or without the 2π factor.

The path can jump between points that aren't connected, as the usual FCC path does from U to K. At a jump, the last k-point before it and the first after it share the same distance, and each carries its own label. The viewer breaks the lines there and labels the tick U|K. A point repeated where two segments meet can also be listed twice at one distance with the same label; the viewer shows it once.

index refers into distances. Write labels as readers should see them, such as "Γ", "X", or "Σ₁", rather than as LaTeX.

Band projections

Each projection gives how much of every state lies on one element, or on one orbital of one element, such as the Mulliken weights your code reports.

Normalize each state so that its weights, across one complete breakdown, sum to 1. The orbital projections of all elements are one complete breakdown; the element totals are another. Two decimals are enough and keep the file small. As with the DOS, an element given only by orbital is summed by the viewer.

Density of states files

Every other field is described under Density of states, at the top level of the file.

Density of states

A density of states is the same set of fields wherever it appears: at the top level of a .dos file, or as the dos object of a .bandstructure file.

Write spin down as positive values; the viewer mirrors it. The DOS carries its own Fermi level because it usually comes from a different calculation than the bands, on a denser mesh.

Projections

Each projection is the DOS on one element, or on one orbital of one element, on the same energy grid as total.

Readers can view the DOS by element or by orbital within one element. When an element has orbital projections but no total, the viewer sums its orbitals.

Example

A spin-polarized band structure along a three-point path with one jump, and a DOS beside it. A real file has many more k-points, bands, and energies:

{
  "format": "ouro.band-structure",
  "version": 1,
  "energy_model": "PBE",
  "fermi_energy": 8.12,
  "kpoints": {
    "distances": [0, 0.5, 1.0, 1.0, 1.4],
    "labels": [
      { "index": 0, "label": "Γ" },
      { "index": 2, "label": "U" },
      { "index": 3, "label": "K" },
      { "index": 4, "label": "Γ" }
    ]
  },
  "bands": [
    [
      [5.1, 6.0, 7.2, 7.0, 5.1],
      [9.4, 8.8, 8.6, 8.9, 9.4]
    ],
    [
      [5.9, 6.8, 7.9, 7.7, 5.9],
      [10.0, 9.5, 9.2, 9.6, 10.0]
    ]
  ],
  "dos": {
    "fermi_energy": 8.1,
    "energies": [5.0, 6.0, 7.0, 8.0, 9.0, 10.0],
    "total": [
      [0.4, 1.2, 1.6, 0.3, 1.1, 0.5],
      [0.1, 0.8, 1.4, 0.2, 0.6, 0.9]
    ],
    "projections": [
      {
        "element": "Fe",
        "orbital": "d",
        "values": [
          [0.3, 1.0, 1.3, 0.2, 0.9, 0.3],
          [0.1, 0.6, 1.1, 0.1, 0.4, 0.6]
        ]
      }
    ]
  }
}

Both spin channels have their highest occupied band below 8.12 eV and their lowest empty band above it, so the viewer reports a gap: from the spin-down valence maximum of 7.9 eV at U to the spin-up conduction minimum of 8.6 eV at U, a direct gap of 0.7 eV.

Returning files from a route

A route that produces band structures or densities of states declares its output as a file with the bandstructure or dos extension, and the result renders with the viewer wherever the route's output appears. See route input and output assets for how to declare outputs.

Versioning

The version field changes only for changes that would break existing readers. Readers should reject versions they don't know, as Ouro's viewer does, and ignore fields they don't recognize, so optional fields can be added within a version.