🚀 Big News: Socket Acquires Coana to Bring Reachability Analysis to Every Appsec Team.Learn more →

Book a Demo Install Sign in

pymatviz

Package Overview

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

pymatviz

A toolkit for visualizations in materials informatics

0.16.0

PyPI

Maintainers: 1

pymatviz

A toolkit for visualizations in materials informatics.

If you use pymatviz in your research, see how to cite. Check out 23 existing papers using pymatviz for inspiration!

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.ipynb		Launch Codespace
mp_bimodal_e_form.ipynb		Launch Codespace
matbench_perovskites_eda.ipynb		Launch Codespace
mprester_ptable.ipynb		Launch Codespace

Periodic Table

See pymatviz/ptable/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)`

`ptable_hists_plotly(data)`	`ptable_scatter_plotly(data, mode="markers")`

`ptable_heatmap_splits_plotly(2_vals_per_elem)`	`ptable_heatmap_splits_plotly(3_vals_per_elem)`

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)`	`phonon_dos(doses_dict)`

`phonon_bands_and_dos(bands_dict, doses_dict)`	`phonon_bands_and_dos(single_bands, single_dos)`

Composition Clustering

`cluster_compositions(compositions, properties, embedding_method, projection_method, n_components=2)`	`cluster_compositions(compositions, properties, embedding_method, projection_method, n_components=3)`

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_viz/plotly.py.

`structure_3d_plotly(hea_structure)`	`structure_3d_plotly(lco_supercell)`

`structure_2d_plotly(six_structs)`	`structure_3d_plotly(six_structs)`

Brillouin Zone

See pymatviz/brillouin.py.

`brillouin_zone_3d(cubic_struct)`	`brillouin_zone_3d(hexagonal_struct)`

`brillouin_zone_3d(monoclinic_struct)`	`brillouin_zone_3d(orthorhombic_struct)`

X-Ray Diffraction

See pymatviz/xrd.py.

`xrd_pattern(pattern)`	`xrd_pattern({key1: patt1, key2: patt2})`

`xrd_pattern(struct_dict, stack="horizontal")`	`xrd_pattern(struct_dict, stack="vertical")`

Radial Distribution Functions

See pymatviz/rdf/plotly.py.

`element_pair_rdfs(pmg_struct)`	`element_pair_rdfs({"A": struct1, "B": struct2})`

Coordination

See pymatviz/coordination/plotly.py.

`coordination_hist(struct_dict)`	`coordination_hist(struct_dict, by_element=True)`

`coordination_vs_cutoff_line(struct_dict, strategy=None)`	`coordination_vs_cutoff_line(struct_dict, strategy=None)`

Sunburst

See pymatviz/sunburst.py.

`spacegroup_sunburst([65, 134, 225, ...])`	`chem_sys_sunburst(["FeO", "Fe2O3", "LiPO4", ...])`

Treemap

See pymatviz/treemap/chem_sys.py.

`chem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...])`	`chem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...], group_by="formula")`

`py_pkg_treemap("pymatviz")`	`py_pkg_treemap(["pymatviz", "torch_sim", "pymatgen"])`

Rainclouds

See pymatviz/rainclouds.py.

`rainclouds(two_key_dict)`	`rainclouds(three_key_dict)`

Sankey

See pymatviz/sankey.py.

`sankey_from_2_df_cols(df_perovskites)`	`sankey_from_2_df_cols(df_space_groups)`

Bar Plots

See pymatviz/bar.py.

`spacegroup_bar([65, 134, 225, ...], backend="plotly")`	`spacegroup_bar(["C2/m", "P-43m", "Fm-3m", ...], backend="plotly")`

Histograms

See pymatviz/histogram.py.

`elements_hist(compositions, log=True, bar_values='count')`	`histogram({'key1': values1, 'key2': values2})`

Scatter Plots

See pymatviz/scatter.py.

`density_scatter_plotly(df, x=x_col, y=y_col, ...)`	`density_scatter_plotly(df, x=x_col, y=y_col, ...)`

`density_scatter(xs, ys, ...)`	`density_scatter_with_hist(xs, ys, ...)`

`density_hexbin(xs, ys, ...)`	`density_hexbin_with_hist(xs, ys, ...)`

Uncertainty

See pymatviz/uncertainty.py.

`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_plotly(targets, probs_positive)`	`precision_recall_curve_plotly(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 2025-03-25. Auto-generated from Google Scholar. Manual additions via PR welcome.

C Zeni, R Pinsler, D Zügner et al. (2023). Mattergen: a generative model for inorganic materials design (cited by 123)
J Riebesell, REA Goodall, P Benner et al. (2023). Matbench Discovery--A framework to evaluate machine learning crystal stability predictions (cited by 45)
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 36)
L Barroso-Luque, M Shuaibi, X Fu et al. (2024). Open materials 2024 (omat24) inorganic materials dataset and models (cited by 31)
M Giantomassi, G Materzanini (2024). Systematic assessment of various universal machine‐learning interatomic potentials (cited by 15)
AA Naik, C Ertural, P Benner et al. (2023). A quantum-chemical bonding database for solid-state materials (cited by 12)
K Li, AN Rubungo, X Lei et al. (2025). Probing out-of-distribution generalization in machine learning for materials (cited by 8)
N Tuchinda, CA Schuh (2025). Grain Boundary Segregation and Embrittlement of Aluminum Binary Alloys from First Principles (cited by 2)
A Onwuli, KT Butler, A Walsh (2024). Ionic species representations for materials informatics (cited by 2)
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 1)
Aaron D. Kaplan, Runze Liu, Ji Qi et al. (2025). A Foundational Potential Energy Surface Dataset for Materials
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
A Peng, MY Guo (2025). The OpenLAM Challenges
F Therrien, JA Haibeh (2025). OBELiX: A Curated Dataset of Crystal Structures and Experimentally Measured Ionic Conductivities for Lithium Solid-State Electrolytes
N Tuchinda, CA Schuh (2025). A Grain Boundary Embrittlement Genome for Substitutional Cubic Alloys
K Yan, M Bohde, A Kryvenko (2025). A Materials Foundation Model via Hybrid Invariant-Equivariant Architectures
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
HH Li, Q Chen, G Ceder (2024). Voltage Mining for (De) lithiation-Stabilized Cathodes and a Machine Learning Model for Li-Ion Cathode Voltage
Janosh Riebesell, Ilyes Batatia, Philipp Benner 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

Keywords

chemistry

data visualization

materials discovery

materials informatics

matplotlib

plotly

FAQs

What is pymatviz?

Is pymatviz well maintained?

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

pymatviz

.css-128vlc0{object-fit:cover;display:inline;height:60px;} pymatviz

Installation

API Docs

Usage

Periodic Table

Dash app using ptable_heatmap_plotly()

Phonons

Composition Clustering

Structure Clustering

Structure

Brillouin Zone

X-Ray Diffraction

Radial Distribution Functions

Coordination

Sunburst

Treemap

Rainclouds

Sankey

Bar Plots

Histograms

Scatter Plots

Uncertainty

Classification

How to cite pymatviz

Papers using pymatviz

Keywords

Related posts

Potemkin Understanding in LLMs: New Study Reveals Flaws in AI Benchmarks

Django Joins curl in Pushing Back on AI Slop Security Reports

pymatviz

Dash app using `ptable_heatmap_plotly()`

How to cite `pymatviz`

Papers using `pymatviz`