Skip to content
janoshPublic

About

Interactive browser visualizations for materials science: crystal structures/molecules, trajectories, convex hulls, phase diagrams, Fermi surfaces, bands+DOS, Brillouin zones, etc.

Topics

Resources

Contributing

Stars

373 stars

Watchers

3 watching

Forks

Repository files navigation

Logo MatterViz

CI GH Pages npm VSCode Extension Docs DOI

Interactive, GPU-accelerated visualization for materials science, in the browser, your editor and your notebooks. Drop in a CIF, POSCAR, MD trajectory or CHGCAR and explore it in 3D, or build your own web UI from the same components: crystal structures, trajectories, volumetric data, band structures, phase diagrams, convex hulls, periodic tables and a full 2D/3D plotting library.

Try it in your browser →  No install, just drag a file onto any viewer.

Two crystal structures with coordination polyhedra rendered side by side

🧰   Use it where you work

VS Code / Cursor Right-click any structure or trajectory file → MatterViz: Open. Install from the VS Code Marketplace or Open VSX. Works over Remote SSH. Settings and file formats
JupyterLab Double-click files in the JupyterLab file browser (HDF5 and JSON via right-click → Open With → MatterViz): pip install matterviz-jupyterlab. Details
Jupyter / Marimo Notebook widgets for pymatgen and ASE objects via pymatviz
Svelte apps npm add matterviz and import components (quick start below)
React, Vue, HTML Prebuilt custom elements like <mv-structure> and <mv-trajectory>, no build step needed. Guide
Command line pnpm snapshot renders structure images in batch; pnpm movie scripts camera flights through MD trajectories into MP4/WebM. Run either with --help from a repo checkout

🖼️   Gallery

MD trajectory viewer with energy and force plots Trajectories: step through MD runs and relaxations with linked energy, force and volume plots. In the browser, reads multi-GB MD HDF5 trajectories (md-trajectory-v1, TorchSim) on demand without loading them into memory (the VS Code and JupyterLab extensions cap HDF5 at 400 MiB and 100 MiB), plus MSD, VACF, RDF and thermal-hotspot analysis. Fe3O4 charge density isosurfaces with coordination polyhedra Volumetric data: isosurfaces and 2D slices of CHGCAR, ELFCAR, LOCPOT and cube files, meshed off the main thread. Color one field by another, e.g. density by electrostatic potential.
Brillouin zone, phonon bands and DOS from three ML potentials vs DFT Bands, DOS & Brillouin zones: electronic and phonon band structures with linked k-paths and DOS. Overlay ML potentials against DFT, here CHGNet, M3GNet and MACE vs PBE. Binary Ag-Cu phase diagram comparing a model against an assessment, with scored observations Phase diagrams: binary and ternary diagrams with lever-rule tooltips and isopleths. Compare two diagrams with shaded disagreement regions and score predictions against experimental observations.
Quaternary convex hulls of Li-Co-Ni-O and Na-Fe-P-O Convex hulls: binary to quaternary formation-energy hulls colored by energy above hull. Also chemical potential diagrams, temperature-dependent free energies and synthesis planning. Fermi surface of BaFe2As2 Fermi surfaces from BXSF, FRMSF and IFermi JSON files, with per-band colors, spin channels and reciprocal-lattice vectors.
Periodic table heatmap splitting each tile between atomic mass and density Periodic tables: heatmaps of any elemental property, including multiple values per tile, with inset scatter plots and rich element pages.

There's much more in the docs: XRD, IR/Raman spectra, NEB reaction paths, symmetry elements, slab and interface builders, and 2D/3D scatter, histogram, violin, sunburst and Sankey plots.

🚀   Quick start

npm add matterviz
<script>
  import { PeriodicTable, Structure, Trajectory } from 'matterviz'
</script>

<!-- structures: CIF, POSCAR, (ext)XYZ, pymatgen/ASE/OPTIMADE JSON, PDB, ... (also .gz) -->
<Structure source="/structures/TiO2.cif" style="height: 500px" />

<!-- trajectories: extXYZ, ASE .traj, HDF5, LAMMPS, XDATCAR, vasprun.xml, ... -->
<Trajectory source="/traj/md-run.xyz.gz" auto_play />

<!-- heatmap of any elemental property -->
<PeriodicTable heatmap_values={{ H: 10, He: 4, Li: 8, Fe: 3, O: 24 }} />

Every viewer also accepts parsed data (structure, trajectory, band_structs, ...), handles drag-and-drop and has built-in export (PNG, SVG, CIF, POSCAR, JSON, GLB, video). Each viewer lists its keyboard shortcuts in its info pane.

Not using Svelte? The same components ship as custom elements:

<mv-structure source="/TiO2.cif" style="height: 500px"></mv-structure>
<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/matterviz/dist/elements/matterviz-elements.js"
></script>

📚   Learn more

🙏   Acknowledgements

MatterViz builds on three.js, threlte, d3, Svelte and Vite, with element data and photos from many generous sources. See the full acknowledgements.

📝   How to cite

Use citation.cff or cite the Zenodo record:

@software{riebesell_matterviz_2022,
  title = {matterviz: visualization toolkit for materials informatics},
  author = {Riebesell, Janosh and Evans, Matthew},
  date = {2026-11-10},
  year = {2026},
  doi = {10.5281/zenodo.17094509},
  url = {https://github.com/janosh/matterviz},
  note = {10.5281/zenodo.17094509 - https://github.com/janosh/matterviz},
  urldate = {2026-11-10}, % optional, replace with your date of access
  version = {0.9.0}, % replace with the version you use
}

About

Interactive browser visualizations for materials science: crystal structures/molecules, trajectories, convex hulls, phase diagrams, Fermi surfaces, bands+DOS, Brillouin zones, etc.

Topics

Resources

Contributing

Stars

373 stars

Watchers

3 watching

Forks

Releases

Used by

Contributors

Languages