Fermi Surface

The Fermi-surface plugin renders isosurfaces from volumetric band data in the frontend (JavaScript marching cubes). This makes Fermi-energy updates fast because the mesh is generated on the client.

Quick start

// 1) Provide volumetric data
const fermiData = {
  datasets: [
    {
      name: "Band-1",
      dims: [nx, ny, nz],
      values: bandValues, // length = nx * ny * nz, z-fastest
      cell: [
        [b1x, b1y, b1z],
        [b2x, b2y, b2z],
        [b3x, b3y, b3z],
      ],
      origin: [0, 0, 0],
    },
  ],
  // Optional: Brillouin-zone planes and/or mesh
  // bzPlanes: [{ normal: [x, y, z], constant: d }, ...],
  // bzMesh: { vertices: [...], faces: [...], color: [0, 0, 0.5], opacity: 0.1 },
};
viewer.setFermiSurfaceData(fermiData);

// 2) Configure Fermi-surface settings
viewer.state.set({
  plugins: {
    fermiSurface: {
      settings: {
        "Band-1": {
          isovalue: 0.0,
          color: "#00ff00",
          opacity: 0.6,
          step_size: 1,
          clipToBZ: true,
          bzCropMargin: 1,
        },
      },
    },
  },
});

Data format

• datasets: array of volumetric grids. Each dataset includes: - name: dataset key referenced by settings. - dims: [nx, ny, nz] grid dimensions. - values: flat array of length nx * ny * nz in x-major order with z fastest. - cell: 3x3 reciprocal lattice vectors. - origin: lattice origin (usually [0, 0, 0]).

• bzPlanes (optional): clipping planes for the first Brillouin zone.

• bzMesh (optional): mesh data for displaying the Brillouin zone.

Settings

Each entry in plugins.fermiSurface.settings defines a mesh:

• dataset or datasets: dataset key(s) to use.

• isovalue: Fermi energy for the isosurface.

• color: hex color or [r, g, b] in 0–1 range.

• opacity: 0–1.

• step_size: marching-cubes stride (integer).

• clipToBZ: clip to Brillouin-zone planes (if provided) and crop to the BZ bounding box (if bzMesh is provided).

• bzCropMargin: padding in grid points around the BZ bounding box (default 1).

• materialType: "Standard" or other supported material type.

Notes

• The marching-cubes supercell is fixed to 2 in the current implementation.

• Clipping does not add caps on the Brillouin-zone boundary.