MatterViz for JupyterLab

Open crystal structures, MD trajectories, band structures and volumetric data directly from the JupyterLab file browser — double-click a .cif, or right-click → Open With → MatterViz. The counterpart to the MatterViz VS Code extension, for people whose file browser lives inside JupyterHub.

Install

pip install matterviz-jupyterlab

That's it — the wheel ships prebuilt assets, so there is no jupyter labextension install step and no Node.js on the user's machine. Restart JupyterLab and verify with:

jupyter labextension list

Requires JupyterLab 4.

Supported formats

Extensionless VASP names (POSCAR, CONTCAR, XDATCAR and the volumetric ones above) are matched by filename. Every format is also recognized with a .gz suffix. Structure JSON (pymatgen/ASE as_dict() output) is available under Open With without displacing Lab's built-in JSON viewer.

A .dump file opens as a structure showing its first frame only, not as an animated trajectory. .xtc, .trr and .dcd are deliberately not registered — MatterViz has no decoder for them, so claiming them would replace another application's handler with an error message.

Limits

Files above 100 MB refuse to parse (transfer already happened; parse in the kernel instead, e.g. with pymatviz's TrajectoryWidget). No host-side streaming like the VS Code extension, so very large trajectories can't be paged frame by frame. Open viewers also don't auto-refresh on external writes — JupyterLab has no filesystem watcher; use File → Reload from Disk.

Development

pnpm install --ignore-workspace --config.strict-dep-builds=false
pnpm build   # vite build && jupyter labextension build . (needs jupyter on PATH)
uv build --wheel

uv_build packages whatever is already on disk — run pnpm build first or you will ship an empty extension. The install flags are needed because this package is outside the monorepo workspace and @jupyterlab/application depends on fontawesome, whose install script pnpm declines to run unattended and then exits non-zero over.

The process devDependency is not imported by anything here. @jupyterlab/builder's webpack config carries an unconditional ProvidePlugin({ process: 'process/browser' }), which has to resolve from this package under pnpm's strict layout. Don't delete it as unused.

The build runs in two stages, which is load-bearing:

1. Vite compiles src/index.ts plus the MatterViz Svelte component graph into plain ESM under lib/. All @jupyterlab/* and @lumino/* imports stay external so JupyterLab supplies the shared singleton instances — bundling a private copy would produce plugin tokens that never match the ones in the application registry.
2. jupyter labextension build webpacks lib/index.js into a federated module under data/share/jupyter/labextensions/matterviz-jupyterlab/, which uv_build copies into the wheel's data directory so pip unpacks it over {sys.prefix}/share.

Webpack cannot build MatterViz directly: the source relies on Vite-only features (import.meta.glob, .json.gz imports) and Svelte compilation. Feeding it already-compiled ESM sidesteps both. Vite's dynamic-import chunks survive the second pass, so HDF5 support stays a ~4.6 MB chunk fetched only when someone actually opens an .h5 file.

jupyter labextension build emits an asset-size warning for the three-dimensional viewer chunks. That is expected for a bundle carrying three.js.