Logo
pymatviz

A toolkit for visualizations in materials informatics.

Tests This project supports Python 3.11+ PyPI codecov PyPI Downloads Zenodo

If you use pymatviz in your research, see how to cite.

Installation

pip install pymatviz

See pyproject.toml for available extras like pip install 'pymatviz[brillouin]' to render 3d Brillouin zones.

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.ipynbOpen in Google ColabLaunch Codespace
mp_bimodal_e_form.ipynbOpen in Google ColabLaunch Codespace
matbench_perovskites_eda.ipynbOpen in Google ColabLaunch Codespace
mprester_ptable.ipynbOpen in Google ColabLaunch Codespace

Periodic Table

See pymatviz/ptable/plotly.py. The module supports heatmaps, heatmap splits (multiple values per element), histograms, scatter plots and line plots. All visualizations are interactive through Plotly and support displaying additional data on hover.

[!WARNING] Version 0.16.0 of pymatviz dropped the matplotlib-based functions in ptable_matplotlib.py in https://github.com/janosh/pymatviz/pull/270. Please use the plotly-based functions shown below instead which have feature parity, interactivity and better test coverage.

ptable_heatmap_plotly(atomic_masses)ptable_heatmap_plotly(compositions, log=True) fig-icon
ptable-heatmap-plotly-more-hover-dataptable-heatmap-plotly-log
ptable_hists_plotly(data) fig-iconptable_scatter_plotly(data, mode="markers") fig-icon
ptable-hists-plotlyptable-scatter-plotly-markers
ptable_heatmap_splits_plotly(2_vals_per_elem) fig-iconptable_heatmap_splits_plotly(3_vals_per_elem)
ptable-heatmap-splits-plotly-2ptable-heatmap-splits-plotly-3

Dash app using ptable_heatmap_plotly()

See examples/mprester_ptable.ipynb.

https://user-images.githubusercontent.com/30958850/181644052-b330f0a2-70fc-451c-8230-20d45d3af72f.mp4

Phonons

phonon_bands(bands_dict) fig-iconphonon_dos(doses_dict) fig-icon
phonon-bandsphonon-dos
phonon_bands_and_dos(bands_dict, doses_dict)phonon_bands_and_dos(single_bands, single_dos) fig-icon
phonon-bands-and-dos-mp-2758phonon-bands-and-dos-mp-23907

Composition Clustering

cluster_compositions(compositions, properties, embedding_method, projection_method, n_components=2) fig-iconcluster_compositions(compositions, properties, embedding_method, projection_method, n_components=3)
matbench-perovskites-magpie-pca-2dmatbench-perovskites-magpie-tsne-3d

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 pymatviz as pmv
from pymatgen.core import Composition

compositions = ("Fe2O3", "Al2O3", "SiO2", "TiO2")

# Create embeddings
embeddings = pmv.cluster.composition.one_hot_encode(compositions)
comp_emb_map = dict(zip(compositions, embeddings, strict=True))

# Plot with optional property coloring
fig = pmv.cluster_compositions(
    compositions=comp_emb_map,
    properties=[1.0, 2.0, 3.0, 4.0],  # Optional property values
    prop_name="Property",  # Optional property label
    embedding_method="one-hot",  # or "magpie", "matscholar_el", "megnet_el", etc.
    projection_method="pca",  # or "tsne", "umap", "isomap", "kernel_pca", etc.
    show_chem_sys="shape",  # works best for small number of compositions; "color" | "shape" | "color+shape" | None
    n_components=2,  # or 3 for 3D plots
)
fig.show()

Structure Clustering

On the roadmap but no ETA yet.

Structure

See pymatviz/structure/plotly.py.

structure_3d(hea_structure)structure_3d(lco_supercell) fig-icon
hea-structure-3dlco-structure-3d
structure_2d(six_structs) fig-iconstructure_3d(six_structs) fig-icon
matbench-phonons-structures-2dmatbench-phonons-structures-3d

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.

from pymatviz import StructureWidget, CompositionWidget, TrajectoryWidget
from pymatgen.core import Structure, Composition

# Interactive 3D structure visualization
structure = Structure.from_file("structure.cif")
struct_widget = StructureWidget(structure=structure)

# Interactive composition visualization
composition = Composition("Fe2O3")
comp_widget = CompositionWidget(composition=composition)

# Interactive trajectory visualization
trajectory1 = [struct1, struct2, struct3]  # List of structures
traj_widget1 = TrajectoryWidget(trajectory=trajectory1)

trajectory2 = [{"structure": struct1, "energy": 1.0}, {"structure": struct2, "energy": 2.0}, {"structure": struct3, "energy": 3.0}]  # dicts with "structure" and property values
traj_widget2 = TrajectoryWidget(trajectory=trajectory2)

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

Importing pymatviz auto-registers all widgets for their respective sets of supported objects via register_matterviz_widgets(). To customize the registration, use set_renderer().

Brillouin Zone

See pymatviz/brillouin.py.

brillouin_zone_3d(cubic_struct) fig-iconbrillouin_zone_3d(hexagonal_struct)
brillouin-cubic-mp-10018brillouin-hexagonal-mp-862690
brillouin_zone_3d(monoclinic_struct) fig-iconbrillouin_zone_3d(orthorhombic_struct)
brillouin-monoclinic-mp-1183089brillouin-volumes-3-cols

X-Ray Diffraction

See pymatviz/xrd.py.

xrd_pattern(pattern) fig-iconxrd_pattern({key1: patt1, key2: patt2})
xrd-patternxrd-pattern-multiple
xrd_pattern(struct_dict, stack="horizontal") fig-iconxrd_pattern(struct_dict, stack="vertical")
xrd-pattern-horizontal-stackxrd-pattern-vertical-stack

Radial Distribution Functions

See pymatviz/rdf/plotly.py.

element_pair_rdfs(pmg_struct)element_pair_rdfs({"A": struct1, "B": struct2}) fig-icon
element-pair-rdfs-Na8Nb8O24element-pair-rdfs-crystal-vs-amorphous

Coordination

See pymatviz/coordination/plotly.py.

coordination_hist(struct_dict)coordination_hist(struct_dict, by_element=True) fig-icon
coordination-hist-singlecoordination-hist-by-structure-and-element
coordination_vs_cutoff_line(struct_dict, strategy=None)coordination_vs_cutoff_line(struct_dict, strategy=None) fig-icon
coordination-vs-cutoff-singlecoordination-vs-cutoff-multiple

Sunburst

See pymatviz/sunburst.py.

spacegroup_sunburst([65, 134, 225, ...]) fig-iconchem_sys_sunburst(["FeO", "Fe2O3", "LiPO4", ...]) fig-icon
spg-num-sunburstchem-sys-sunburst-ward-bmg
chem_env_sunburst(single_struct)chem_env_sunburst(multiple_structs)
chem-env-sunburst-basicchem-env-sunburst-mp-carbon

Treemap

See pymatviz/treemap/chem_sys.py.

chem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...]) fig-iconchem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...], group_by="formula")
chem-sys-treemap-formulachem-sys-treemap-ward-bmg
chem_env_treemap(structures) fig-iconchem_env_treemap(structures, max_cells_cn=3, max_cells_ce=4)
chem-env-treemap-basicchem-env-treemap-large-dataset
py_pkg_treemap("pymatviz") fig-iconpy_pkg_treemap(["pymatviz", "flame", "pymatgen"])
py-pkg-treemap-pymatvizpy-pkg-treemap-multiple
py_pkg_treemap("pymatviz", color_by="coverage") fig-iconpy_pkg_treemap("pymatgen", color_by="coverage", color_range=(0, 100))
py-pkg-treemap-pymatviz-coveragepy-pkg-treemap-pymatgen-coverage

Note: For color_by="coverage" the package must have coverage data (e.g. run pytest --cov=<pkg> --cov-report=xml and pass the resulting .coverage file to coverage_data_file).

Rainclouds

See pymatviz/rainclouds.py.

rainclouds(two_key_dict) fig-iconrainclouds(three_key_dict)
rainclouds-bimodalrainclouds-trimodal

Sankey

See pymatviz/sankey.py.

sankey_from_2_df_cols(df_perovskites) fig-iconsankey_from_2_df_cols(df_space_groups)
sankey-spglib-vs-aflow-spacegroupssankey-crystal-sys-to-spg-symbol

Bar Plots

See pymatviz/bar.py.

spacegroup_bar([65, 134, 225, ...]) fig-iconspacegroup_bar(["C2/m", "P-43m", "Fm-3m", ...])
spg-num-hist-plotlyspg-symbol-hist-plotly

Histograms

See pymatviz/histogram.py.

elements_hist(compositions, log=True, bar_values='count') fig-iconhistogram({'key1': values1, 'key2': values2}) fig-icon
elements-histhistogram-ecdf

Scatter Plots

See pymatviz/scatter.py.

density_scatter(xs, ys, ...) fig-icondensity_scatter_with_hist(xs, ys, ...) fig-icon
density-scatterdensity-scatter-with-hist
density_hexbin(xs, ys, ...) fig-icondensity_hexbin_with_hist(xs, ys, ...) fig-icon
density-hexbindensity-hexbin-with-hist

Uncertainty

See pymatviz/uncertainty.py.

qq_gaussian(y_true, y_pred, y_std) fig-iconqq_gaussian(y_true, y_pred, y_std: dict)
qq-gaussianqq-gaussian-multiple
error_decay_with_uncert(y_true, y_pred, y_std) fig-iconerror_decay_with_uncert(y_true, y_pred, y_std: dict)
error-decay-with-uncerterror-decay-with-uncert-multiple

Classification

See pymatviz/classify/confusion_matrix.py.

confusion_matrix(conf_mat, ...)confusion_matrix(y_true, y_pred, ...) fig-icon
stability-confusion-matrixcrystal-system-confusion-matrix

See pymatviz/classify/curves.py.

roc_curve_plotly(targets, probs_positive) fig-iconprecision_recall_curve_plotly(targets, probs_positive) fig-icon
roc-curve-plotly-multipleprecision-recall-curve-plotly-multiple

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 2025-10-12. Auto-generated from Google Scholar. Manual additions via PR welcome.

  1. C Zeni, R Pinsler, D ZĂŒgner et al. (2023). Mattergen: a generative model for inorganic materials design (cited by 166)
  2. L Barroso-Luque, M Shuaibi, X Fu et al. (2024). Open materials 2024 (omat24) inorganic materials dataset and models (cited by 136)
  3. J Riebesell, REA Goodall, P Benner et al. (2023). Matbench Discovery—A framework to evaluate machine learning crystal stability predictions (cited by 117)
  4. 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 81)
  5. M Giantomassi, G Materzanini (2024). Systematic assessment of various universal machine‐learning interatomic potentials (cited by 44)
  6. K Li, AN Rubungo, X Lei et al. (2025). Probing out-of-distribution generalization in machine learning for materials (cited by 29)
  7. AA Naik, C Ertural, P Benner et al. (2023). A quantum-chemical bonding database for solid-state materials (cited by 22)
  8. A Kapeliukha, RA Mayo (2025). MOSAEC-DB: a comprehensive database of experimental metal–organic frameworks with verified chemical accuracy suitable for molecular simulations (cited by 15)
  9. Y Zhou, X He, Z Li (2025). Scientists’ First Exam: Probing Cognitive Abilities of MLLM via Perception, Understanding, and Reasoning (cited by 6)
  10. 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 4)
  11. F Therrien, JA Haibeh, D Sharma (2025). OBELiX: A curated dataset of crystal structures and experimentally measured ionic conductivities for lithium solid-state electrolytes (cited by 3)
  12. A Onwuli, KT Butler, A Walsh (2024). Ionic species representations for materials informatics (cited by 3)
  13. N Tuchinda, CA Schuh (2025). Grain Boundary Segregation and Embrittlement of Aluminum Binary Alloys from First Principles (cited by 2)
  14. A Peng, MY Guo (2025). The OpenLAM Challenges (cited by 1)
  15. N Tuchinda, CA Schuh (2025). A grain boundary embrittlement genome for substitutional cubic alloys (cited by 1)
  16. Giulio Benedini, Antoine Loew, Matti Hellstrom et al. (2025). Universal Machine Learning Potential for Systems with Reduced Dimensionality
  17. 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
  18. Orion Cohen, Janosh Riebesell, Rhys Goodall et al. (2025). TorchSim: An efficient atomistic simulation engine in PyTorch
  19. 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
  20. Matthew K. Horton, Patrick Huck, Ruo Xi Yang et al. (2025). Accelerated data-driven materials science with the Materials Project
  21. Aaron D. Kaplan, Runze Liu, Ji Qi et al. (2025). A Foundational Potential Energy Surface Dataset for Materials
  22. Matthew C. Kuner, Aaron D. Kaplan, Kristin A. Persson et al. (2025). MP-ALOE: An r2SCAN dataset for universal machine learning interatomic potentials
  23. Anyang Peng, Xinzijian Liu, Ming-Yu Guo et al. (2025). The OpenLAM Challenges: LAM Crystal Philately competition
  24. Ali Ramlaoui, Martin Siron, Inel Djafar et al. (2025). LeMat-Traj: A Scalable and Unified Dataset of Materials Trajectories for Atomistic Modeling
  25. 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
  26. Yingheng Tang, Wenbin Xu, Jie Cao et al. (2025). MatterChat: A Multi-Modal LLM for Material Science
  27. Liming Wu, Wenbing Huang, Rui Jiao et al. (2025). Siamese Foundation Models for Crystal Structure Prediction
  28. K Yan, M Bohde, A Kryvenko (2025). A Materials Foundation Model via Hybrid Invariant-Equivariant Architectures
  29. RA Mayo (2025). Generalizable classification of crystal structure error types using graph attention networks
  30. Daniel W. Davies, Keith T. Butler, Adam J. Jackson et al. (2024). SMACT: Semiconducting Materials by Analogy and Chemical Theory
  31. Hui Zheng, Eric Sivonxay, Rasmus Christensen et al. (2024). The ab initio non-crystalline structure database: empowering machine learning to decode diffusivity
  32. Ilyes Batatia, Philipp Benner, Yuan Chiang et al. (2023). A foundation model for atomistic materials chemistry
  33. Jack Douglas Sundberg (2022). A New Framework for Material Informatics and Its Application Toward Electride-Halide Material Systems