pymatviz
A toolkit for visualizations in materials informatics.
If you usepymatviz in your research, see how to cite.Installation
pip install pymatviz
See pyproject.toml for available extras like pip install 'pymatviz[export]' for static image export.
API Docs
See the /api page.
Usage
See the Jupyter notebooks under examples/ for how to use pymatviz. PRs with additional examples are welcome! đ
| matbench_dielectric_eda.ipynb | Launch Codespace | |
| matbench_perovskites_eda.ipynb | Launch Codespace |
Periodic Table
See pymatviz/ptable/figures.py. The module supports heatmaps, heatmap splits (multiple values per element), histograms, scatter plots and line plots. All visualizations are interactive MatterViz widgets: hovering a tile shows its plot enlarged with axes.
Phonons
band_structure(band_structs=bands_dict) | phonon_dos(doses_dict) |
|---|---|
bands_and_dos(band_structs=bands_dict, doses=doses_dict) | bands_and_dos(band_structs=single_bands, doses=single_dos) |
![]() | ![]() |
Composition Clustering
Visualize 2D or 3D relationships between compositions and properties using multiple embedding and dimensionality reduction techniques:
Embedding methods: One-hot encoding of element fractions, Magpie features (elemental properties), Matscholar element embeddings, MEGNet element embeddings
Dimensionality reduction methods: PCA (linear), t-SNE (non-linear), UMAP (non-linear), Isomap (non-linear), Kernel PCA (non-linear)
Example usage:
import pandas as pd
import pymatviz as pmv
df_comp = pd.DataFrame(
{"composition": ["Fe2O3", "Al2O3", "SiO2", "TiO2"], "property": [1.0, 2.0, 3.0, 4.0]}
)
widget = pmv.cluster_compositions(
df_comp,
prop_name="property", # optional property to color points by
embedding_method="one-hot", # or "magpie", "matscholar_el", "megnet_el", etc.
projection="pca", # or "tsne", "umap", "isomap", "kernel_pca", etc.
show_chem_sys="shape", # "color" | "shape" | "color+shape" | None
n_components=2, # or 3 for 3D plots
)
widget.show()
Structure Clustering
On the roadmap but no ETA yet.
Structure
See pymatviz/widgets/structure.py.
structure(structure=hea_structure) | structure(structure=lco_supercell) |
|---|---|
![]() | ![]() |
structure(structure=batio3) | structure(structure=mos2) |
![]() | ![]() |
Interactive Widgets
See pymatviz/widgets. Interactive 3D structure, molecular dynamics trajectory and composition visualization widgets for Jupyter, Marimo, and VSCode notebooks, powered by anywidget and MatterViz (https://github.com/janosh/matterviz). Supports pymatgen Structure, ASE Atoms, and PhonopyAtoms, as well as ASE, pymatgen and plain Python trajectory formats.
import pymatviz as pmv
from pymatgen.core import Structure, Composition
# Interactive 3D structure visualization
struct_widget = pmv.structure(Structure.from_file("structure.cif"))
# Interactive composition visualization
comp_widget = pmv.composition(Composition("Fe2O3"))
# Interactive trajectory visualization from structures or dicts of structure and properties
traj_widget1 = pmv.trajectory([struct1, struct2, struct3])
traj_widget2 = pmv.trajectory([{"structure": struct1, "energy": 1.0}, {"structure": struct2, "energy": 2.0}])
All widgets support export and inspection APIs that work in plain Python scripts, CI, and agent workflows â no notebook frontend required:
widget.to_html("structure.html") # standalone interactive HTML page (pan/zoom/rotate work)
widget.to_img("structure.png", dpi=150) # PNG/JPEG/SVG/PDF via headless Chromium
widget.describe() # machine-readable facts: counts, ranges, formula, chemical system
widget.render_report() # headless render health check: blank fraction, warnings
widget.to_json("structure.json") # save the widget; pmv.from_json("structure.json") restores it
pmv.export_widgets({name: widget, ...}, "figures/", fmt="png") exports many widgets at once (SVG only works for 2D plots, not 3D viewers like structure), rendering up to 4 concurrently in one headless browser (about 2.4x faster than calling to_img on each).
Lay out several widgets with widget_grid({title: widget, ...}, n_cols=3), e.g. one structure widget per structure. It returns an ipywidgets.GridBox of titled cells: export each widget from its .children.
to_img and render_report require Playwright: pip install pymatviz[export] && playwright install chromium (on Linux CI runners without Chromium system libraries, use playwright install --with-deps chromium). Exports render in headless Chromium. Set the PYMATVIZ_STATIC env var to make widget.show() render static PNGs instead of live widgets (useful for CI notebook execution).
Each MatterViz component has a pymatviz function of the same name in snake_case (ScatterPlot â pmv.scatter_plot, BrillouinZone â pmv.brillouin_zone), returning its widget. The widget classes live in pymatviz.widgets for type hints and isinstance checks. The generic charts also take DataFrame columns, e.g. pmv.scatter_plot(df, x="volume", y="energy", color="crystal_system") draws one labeled series per crystal system, and pmv.heatmap_matrix(df) plots a DataFrame matrix. Their keyword arguments mirror the props of the matching MatterViz component one-to-one (e.g. band_structure(band_structs=...), dos(doses=...), heatmap_matrix(color_scale={"type": "log"})), every widget takes show_controls, and those whose component has a control pane (e.g. scatter_plot, bar_plot, histogram, dos) also controls_open, controls_toggle_props and controls_pane_props. The frontend is the prebuilt matterviz-anywidget bundle selected by MATTERVIZ_ANYWIDGET_VERSION in pymatviz/widgets/matterviz.py: "main" between releases (matterviz mainâs bundle from matterviz.janosh.dev/anywidget/, re-fetched each session), a published npm version in releases (fetched from jsDelivr and cached on disk); set MATTERVIZ_ANYWIDGET_DIR to a local matterviz/extensions/anywidget/build to develop against an unreleased MatterViz.
Examples:
[!TIP] Checkout the â MatterViz VSCode extension for using the same viewers directly in VSCode/Cursor editor tabs for rendering local and remote files: marketplace.visualstudio.com/items?itemName=janosh.matterviz
In Jupyter, VS Code and marimo, importing pymatviz renders pymatgen, ASE and phonopy objects (structures, band structures, DOS, XRD patterns, phase diagrams, compositions) as their widgets. Toggle it with notebook_mode(on=False).
Brillouin Zone
See pymatviz/widgets/brillouin_zone.py. MatterViz standardizes any input cell, so the zone and its high-symmetry k-path labels match the Setyawan-Curtarolo convention.
brillouin_zone(structure=cubic_struct) | brillouin_zone(structure=hexagonal_struct) |
|---|---|
![]() | ![]() |
brillouin_zone(structure=monoclinic_struct) | brillouin_zone(structure=orthorhombic_struct) |
![]() | ![]() |
X-Ray Diffraction
See pymatviz/xrd.py.
xrd_plot(pattern) | xrd_plot({key1: patt1, key2: patt2}) |
|---|---|
Radial Distribution Functions
rdf_plot(pmg_struct) | rdf_plot({"A": struct1, "B": struct2}, element_pairs=[...]) |
|---|---|
Coordination
See pymatviz/coordination/figures.py.
coordination_bar_plot(struct_dict) | coordination_bar_plot(struct_dict, split_mode="by_element") |
|---|---|
coordination_vs_cutoff_line(struct_dict) | coordination_vs_cutoff_line(struct_dict) |
Sunburst
chem_sys_hierarchy and chem_env_hierarchy draw interactive MatterViz sunbursts by default, or treemaps with kind="treemap". Pass your own nested data to pmv.sunburst or pmv.treemap. Use widget.to_html("hierarchy.html", inline=True) for a self-contained interactive file (the default to_html loads the MatterViz bundle from the network) or widget.to_img("hierarchy.svg") for a vector figure.
spacegroup_sunburst([65, 134, 225, ...]) | chem_sys_hierarchy(["FeO", "Fe2O3", "LiPO4", ...]) |
|---|---|
chem_env_hierarchy(single_struct) | chem_env_hierarchy(structures, normalize=True) |
Treemap
Chemical-system and coordination-environment treemaps return MatterViz treemap widgets. max_systems limits systems per arity. Set overflow="drop" to omit the remaining systems or use the default "other" to retain their combined count.
For coverage coloring, pass a color_by dictionary mapping file paths to coverage percentages. Use color_range=(0, 100) for a fixed percentage scale. The gallery script shows how to read a coverage.py JSON report.
Rainclouds
rainclouds(two_key_dict) | rainclouds(three_key_dict) |
|---|---|
Sankey
See pymatviz/sankey.py.
sankey(df_space_groups, crystal_system, spg_num) |
|---|
Bar Plots
See pymatviz/bar.py.
spacegroup_bar_plot([65, 134, 225, ...]) | spacegroup_bar_plot(["C2/m", "P-43m", "Fm-3m", ...]) |
|---|---|
Histograms
elements_hist(compositions, log_y=True, show_values='count') | histogram({'key1': values1, 'key2': values2}) |
|---|---|
Scatter Plots
See pymatviz/scatter.py.
density_scatter(xs, ys, ...) | density_hexbin(xs, ys, bin_px=1.5, marginal_bins=100) |
|---|---|
density_hexbin(xs, ys, ...) | density_hexbin(xs, ys, bin_px=8, marginal_bins=100) |
Uncertainty
qq_gaussian(y_true, y_pred, y_std) | qq_gaussian(y_true, y_pred, y_std: dict) |
|---|---|
error_decay_with_uncert(y_true, y_pred, y_std) | error_decay_with_uncert(y_true, y_pred, y_std: dict) |
Classification
See pymatviz/classify/confusion_matrix.py.
confusion_matrix(conf_mat, ...) | confusion_matrix(y_true, y_pred, ...) |
|---|---|
See pymatviz/classify/curves.py.
roc_curve(targets, probs_positive) | precision_recall_curve(targets, probs_positive) |
|---|---|
How to cite pymatviz
See citation.cff or cite the Zenodo record using the following BibTeX entry:
@software{riebesell_pymatviz_2022,
title = {Pymatviz: visualization toolkit for materials informatics},
author = {Riebesell, Janosh and Yang, Haoyu and Goodall, Rhys and Baird, Sterling G.},
date = {2022-10-01},
year = {2022},
doi = {10.5281/zenodo.7486816},
url = {https://github.com/janosh/pymatviz},
note = {10.5281/zenodo.7486816 - https://github.com/janosh/pymatviz},
urldate = {2023-01-01}, % optional, replace with your date of access
version = {0.8.2}, % replace with the version you use
}
Papers using pymatviz
Sorted by number of citations, then year. Last updated 2026-02-25. Auto-generated from Google Scholar. Manual additions via PR welcome.
- L Barroso-Luque, M Shuaibi, X Fu et al. (2024). Open materials 2024 (omat24) inorganic materials dataset and models (cited by 230)
- C Zeni, R Pinsler, D ZĂŒgner et al. (2023). Mattergen: a generative model for inorganic materials design (cited by 166)
- C Chen, DT Nguyen, SJ Lee et al. (2024). Accelerating computational materials discovery with machine learning and cloud high-performance computing: from large-scale screening to experimental validation (cited by 131)
- J Riebesell, REA Goodall, P Benner et al. (2023). Matbench DiscoveryâA framework to evaluate machine learning crystal stability predictions (cited by 106)
- H Yu, M Giantomassi, G Materzanini (2024). Systematic assessment of various universal machineâlearning interatomic potentials (cited by 69)
- M Gibaldi, A Kapeliukha, A White et al. (2025). MOSAEC-DB: a comprehensive database of experimental metalâorganic frameworks with verified chemical accuracy suitable for molecular simulations (cited by 34)
- AA Naik, C Ertural, N Dhamrait et al. (2023). A quantum-chemical bonding database for solid-state materials (cited by 28)
- F Therrien, J Abou Haibeh, D Sharma et al. (2026). OBELiX: A curated dataset of crystal structures and experimentally measured ionic conductivities for lithium solid-state electrolytes (cited by 9)
- K Li, AN Rubungo, X Lei et al. (2024). Probing out-of-distribution generalization in machine learning for materials (cited by 9)
- Y Zhou, X He, Z Li (2025). Scientistsâ First Exam: Probing Cognitive Abilities of MLLM via Perception, Understanding, and Reasoning (cited by 6)
- HH Li, Q Chen, G Ceder (2024). Voltage Mining for (De) lithiation-Stabilized Cathodes and a Machine Learning Model for Li-Ion Cathode Voltage (cited by 5)
- A Peng, X Liu, MY Guo et al. (2025). The openlam challenges (cited by 3)
- J Nam, S Liu, G Winter et al. (2025). Flow matching for accelerated simulation of atomic transport in crystalline materials (cited by 3)
- A Onwuli, KT Butler, A Walsh (2024). Ionic species representations for materials informatics (cited by 3)
- N Tuchinda, CA Schuh (2025). Grain Boundary Segregation and Embrittlement of Aluminum Binary Alloys from First Principles (cited by 2)
- R Nduma, H Park, A Walsh (2025). Crystalyse: a multi-tool agent for materials design (cited by 2)
- N Tuchinda, CA Schuh (2025). A grain boundary embrittlement genome for substitutional cubic alloys (cited by 1)
- A Giunto, Y Fei, P Nevatia et al. (2025). Harnessing Automated SEM-EDS and Machine Learning to Unlock High-Throughput Compositional Characterization of Powder Materials (cited by 1)
- T Cavignac, J Schmidt, PP De Breuck et al. (2025). AI-Driven Expansion and Application of the Alexandria Database (cited by 1)
- J Riebesell, H Yang, R Goodall et al. (2024). janosh/pymatviz: v0. 11.0 (cited by 1)
- T Warford, FL Thiemann, GÄÄ CsÄÄnyi (2026). Better without U: Impact of Selective Hubbard U Correction on Foundational MLIPs
- Mohammed Al-Fahdi, Riccardo Rurali, Jianjun Hu et al. (2025). Accelerated discovery of extreme lattice thermal conductivity by crystal graph attention networks and chemical bonding
- Omar Allam, Brook Wander, SungYeon Kim et al. (2025). AQCat25: Unlocking spin-aware, high-fidelity machine learning potentials for heterogeneous catalysis
- Giulio Benedini, Antoine Loew, Matti Hellstrom et al. (2025). Universal Machine Learning Potential for Systems with Reduced Dimensionality
- Yuan Chiang, Tobias Kreiman, Elizabeth Weaver et al. (2025). MLIP Arena: Advancing Fairness and Transparency in Machine Learning Interatomic Potentials through an Open and Accessible Benchmark Platform
- Orion Archer Cohen, Janosh Riebesell, Rhys Goodall et al. (2025). TorchSim: An efficient atomistic simulation engine in PyTorch
- Alin Marin Elena, Prathami Divakar Kamath, ThĂ©o Jaffrelot Inizan et al. (2025). Machine learned potential for high-throughput phonon calculations of metalâorganic frameworks
- Matthew K. Horton, Patrick Huck, Ruo Xi Yang et al. (2025). Accelerated data-driven materials science with the Materials Project
- Aaron D. Kaplan, Runze Liu, Ji Qi et al. (2025). A Foundational Potential Energy Surface Dataset for Materials
- Matthew C. Kuner, Aaron D. Kaplan, Kristin A. Persson et al. (2025). MP-ALOE: An r2SCAN dataset for universal machine learning interatomic potentials
- Anyang Peng, Xinzijian Liu, Ming-Yu Guo et al. (2025). The OpenLAM Challenges: LAM Crystal Philately competition
- Ali Ramlaoui, Martin Siron, Inel Djafar et al. (2025). LeMat-Traj: A Scalable and Unified Dataset of Materials Trajectories for Atomistic Modeling
- Fei Shuang, Zixiong Wei, Kai Liu et al. (2025). Universal machine learning interatomic potentials poised to supplant DFT in modeling general defects in metals and random alloys
- Yingheng Tang, Wenbin Xu, Jie Cao et al. (2025). MatterChat: A Multi-Modal LLM for Material Science
- Liming Wu, Wenbing Huang, Rui Jiao et al. (2025). Siamese Foundation Models for Crystal Structure Prediction
- K Yan, M Bohde, A Kryvenko (2025). A Materials Foundation Model via Hybrid Invariant-Equivariant Architectures
- M Gibaldi, J Luo, AJ White et al. (2025). Generalizable classification of crystal structure error types using graph attention networks
- Daniel W. Davies, Keith T. Butler, Adam J. Jackson et al. (2024). SMACT: Semiconducting Materials by Analogy and Chemical Theory
- Hui Zheng, Eric Sivonxay, Rasmus Christensen et al. (2024). The ab initio non-crystalline structure database: empowering machine learning to decode diffusivity
- Ilyes Batatia, Philipp Benner, Yuan Chiang et al. (2023). A foundation model for atomistic materials chemistry
- Jack Douglas Sundberg (2022). A New Framework for Material Informatics and Its Application Toward Electride-Halide Material Systems










