Repository files navigation

If you usepymatviz in your research,see how to cite. Check out33 existing papers usingpymatviz for inspiration!

pip install pymatviz

Seepyproject.toml for available extras likepip install 'pymatviz[brillouin]' to render 3d Brillouin zones.

See the/api page.

See the Jupyter notebooks underexamples/ for how to usepymatviz. 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

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

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)

Seeexamples/mprester_ptable.ipynb.

phonon_bands(bands_dict)	phonon_dos(doses_dict)
phonon_bands_and_dos(bands_dict, doses_dict)	phonon_bands_and_dos(single_bands, single_dos)

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:

importpymatvizaspmvfrompymatgen.coreimportCompositioncompositions= ("Fe2O3","Al2O3","SiO2","TiO2")# Create embeddingsembeddings=pmv.cluster.composition.one_hot_encode(compositions)comp_emb_map=dict(zip(compositions,embeddings,strict=True))# Plot with optional property coloringfig=pmv.cluster_compositions(compositions=comp_emb_map,properties=[1.0,2.0,3.0,4.0],# Optional property valuesprop_name="Property",# Optional property labelembedding_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" | Nonen_components=2,# or 3 for 3D plots)fig.show()

On the roadmap but no ETA yet.

Seepymatviz/structure/plotly.py.

structure_3d(hea_structure)	structure_3d(lco_supercell)
structure_2d(six_structs)	structure_3d(six_structs)

Seepymatviz/widgets. Interactive 3D structure, molecular dynamics trajectory and composition visualization widgets forJupyter,Marimo, and VSCode notebooks, powered byanywidget andMatterViz (https://github.com/janosh/matterviz). Supports pymatgenStructure, ASEAtoms, andPhonopyAtoms, as well as ASE,pymatgen and plain Python trajectory formats.

frompymatvizimportStructureWidget,CompositionWidget,TrajectoryWidgetfrompymatgen.coreimportStructure,Composition# Interactive 3D structure visualizationstructure=Structure.from_file("structure.cif")struct_widget=StructureWidget(structure=structure)# Interactive composition visualizationcomposition=Composition("Fe2O3")comp_widget=CompositionWidget(composition=composition)# Interactive trajectory visualizationtrajectory1= [struct1,struct2,struct3]# List of structurestraj_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 valuestraj_widget2=TrajectoryWidget(trajectory=trajectory2)

Examples:

• Jupyter notebook demo
• Marimo demo
• VSCode interactive demo

Importingpymatviz auto-registers all widgets for their respective sets of supported objects viaregister_matterviz_widgets(). To customize the registration, useset_renderer().

Seepymatviz/brillouin.py.

brillouin_zone_3d(cubic_struct)	brillouin_zone_3d(hexagonal_struct)
brillouin_zone_3d(monoclinic_struct)	brillouin_zone_3d(orthorhombic_struct)

Seepymatviz/xrd.py.

xrd_pattern(pattern)	xrd_pattern({key1: patt1, key2: patt2})
xrd_pattern(struct_dict, stack="horizontal")	xrd_pattern(struct_dict, stack="vertical")

Seepymatviz/rdf/plotly.py.

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

Seepymatviz/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)

Seepymatviz/sunburst.py.

spacegroup_sunburst([65, 134, 225, ...])	chem_sys_sunburst(["FeO", "Fe2O3", "LiPO4", ...])
chem_env_sunburst(single_struct)	chem_env_sunburst(multiple_structs)

Seepymatviz/treemap/chem_sys.py.

chem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...])	chem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...], group_by="formula")
chem_env_treemap(structures)	chem_env_treemap(structures, max_cells_cn=3, max_cells_ce=4)
py_pkg_treemap("pymatviz")	py_pkg_treemap(["pymatviz", "flame", "pymatgen"])
py_pkg_treemap("pymatviz", color_by="coverage")	py_pkg_treemap("pymatgen", color_by="coverage", color_range=(0, 100))

Note: Forcolor_by="coverage" the package must have coverage data (e.g. runpytest --cov=<pkg> --cov-report=xml and pass the resulting.coverage file tocoverage_data_file).

Seepymatviz/rainclouds.py.

rainclouds(two_key_dict)	rainclouds(three_key_dict)

Seepymatviz/sankey.py.

sankey_from_2_df_cols(df_perovskites)	sankey_from_2_df_cols(df_space_groups)

Seepymatviz/bar.py.

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

Seepymatviz/histogram.py.

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

Seepymatviz/scatter.py.

density_scatter(xs, ys, ...)	density_scatter_with_hist(xs, ys, ...)
density_hexbin(xs, ys, ...)	density_hexbin_with_hist(xs, ys, ...)

Seepymatviz/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)

Seepymatviz/classify/confusion_matrix.py.

confusion_matrix(conf_mat, ...)	confusion_matrix(y_true, y_pred, ...)

Seepymatviz/classify/curves.py.

roc_curve_plotly(targets, probs_positive)	precision_recall_curve_plotly(targets, probs_positive)

Seecitation.cff or cite theZenodo 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 accessversion ={0.8.2}, % replace with the version you use}

Sorted by number of citations, then year. Last updated 2025-10-12. Auto-generatedfrom Google Scholar. Manual additionsvia 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