Metadata-Version: 2.3
Name: pymatviz
Version: 0.17.6
Summary: A toolkit for visualizations in materials informatics
Keywords: chemistry,crystallography,data analysis,data visualization,materials informatics,plotly
Author: Janosh Riebesell
Author-email: Janosh Riebesell <janosh.riebesell@gmail.com>
License: MIT License
         
         Copyright (c) 2021 Janosh Riebesell
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         The software is provided "as is", without warranty of any kind, express or
         implied, including but not limited to the warranties of merchantability,
         fitness for a particular purpose and noninfringement. In no event shall the
         authors or copyright holders be liable for any claim, damages or other
         liability, whether in an action of contract, tort or otherwise, arising from,
         out of or in connection with the software or the use or other dealings in the
         software.
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: anywidget>=0.9.18
Requires-Dist: moyopy[interface]>=0.8
Requires-Dist: numpy>=2
Requires-Dist: pandas[output-formatting,xml]>=2.2
Requires-Dist: plotly>=6.4
Requires-Dist: pymatgen>=2025.10.7
Requires-Dist: pyyaml>=6
Requires-Dist: scikit-learn>=1.5
Requires-Dist: scipy>=1.14
Requires-Dist: seekpath>=2.1 ; extra == 'brillouin'
Requires-Dist: matminer>=0.9 ; extra == 'cluster'
Requires-Dist: kaleido>=1.2.0 ; extra == 'export'
Requires-Dist: playwright>=1.40 ; extra == 'export'
Requires-Dist: jupyter>=1.1 ; extra == 'gh-pages'
Requires-Dist: lazydocs>=0.4 ; extra == 'gh-pages'
Requires-Dist: nbconvert>=7.16 ; extra == 'gh-pages'
Requires-Dist: matminer>=0.9 ; extra == 'make-assets'
Requires-Dist: phonopy>=2.31 ; extra == 'phonons'
Requires-Dist: kaleido>=1.2.0 ; extra == 'test'
Requires-Dist: pymatviz[cluster,phonons] ; extra == 'test'
Requires-Dist: pytest-cov>=6 ; extra == 'test'
Requires-Dist: pytest-split>=0.9 ; extra == 'test'
Requires-Dist: pytest>=8 ; extra == 'test'
Requires-Dist: umap-learn>=0.5 ; python_full_version < '3.13' and extra == 'umap'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/janosh/pymatviz
Provides-Extra: brillouin
Provides-Extra: cluster
Provides-Extra: export
Provides-Extra: gh-pages
Provides-Extra: make-assets
Provides-Extra: phonons
Provides-Extra: test
Provides-Extra: umap
Description-Content-Type: text/markdown

<h1 align="center">
<img src="https://github.com/janosh/pymatviz/raw/main/site/static/favicon.svg" alt="Logo" height="60px">
<br class="hide-in-docs">
pymatviz
</h1>

<h4 align="center" class="toc-exclude">

A toolkit for visualizations in materials informatics.

[![Tests](https://github.com/janosh/pymatviz/actions/workflows/test.yml/badge.svg)](https://github.com/janosh/pymatviz/actions/workflows/test.yml)
[![This project supports Python 3.11+](https://img.shields.io/badge/Python-3.11+-blue.svg?logo=python&logoColor=white)](https://python.org/downloads)
[![PyPI](https://img.shields.io/pypi/v/pymatviz?logo=pypi&logoColor=white)](https://pypi.org/project/pymatviz)
[![codecov](https://codecov.io/gh/janosh/pymatviz/graph/badge.svg?token=7BG2TZVOBH)](https://codecov.io/gh/janosh/pymatviz)
[![PyPI Downloads](https://img.shields.io/pypi/dm/pymatviz?logo=icloud&logoColor=white)](https://pypistats.org/packages/pymatviz)
[![Zenodo](https://img.shields.io/badge/DOI-10.5281/zenodo.10456384-blue?logo=Zenodo&logoColor=white)](https://zenodo.org/records/10456384)

</h4>

[fig-icon]: https://api.iconify.design/lsicon:scatter-diagram-outline.svg?color=%234c8bf5&height=16 "View example code"

<slot name="how-to-cite">

> If you use `pymatviz` in your research, [see how to cite](#how-to-cite-pymatviz). Check out [41 existing papers using `pymatviz`](#papers-using-pymatviz) for inspiration!

</slot>

## Installation

```sh
pip install pymatviz
```

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

## API Docs

See the [/api][/api] page.

[/api]: https://janosh.github.io/pymatviz/api

## Usage

See the Jupyter notebooks under [`examples/`](examples) for how to use `pymatviz`. PRs with additional examples are welcome! 🙏

|                                                                           |                                                                                                                                                             |                                   |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| [matbench_dielectric_eda.ipynb](examples/matbench_dielectric_eda.ipynb)   | [![Open in Google Colab][Open in Google Colab]](https://colab.research.google.com/github/janosh/pymatviz/blob/main/examples/matbench_dielectric_eda.ipynb)  | [Launch Codespace][codespace url] |
| [mp_bimodal_e_form.ipynb](examples/mp_bimodal_e_form.ipynb)               | [![Open in Google Colab][Open in Google Colab]](https://colab.research.google.com/github/janosh/pymatviz/blob/main/examples/mp_bimodal_e_form.ipynb)        | [Launch Codespace][codespace url] |
| [matbench_perovskites_eda.ipynb](examples/matbench_perovskites_eda.ipynb) | [![Open in Google Colab][Open in Google Colab]](https://colab.research.google.com/github/janosh/pymatviz/blob/main/examples/matbench_perovskites_eda.ipynb) | [Launch Codespace][codespace url] |
| [mprester_ptable.ipynb](examples/mprester_ptable.ipynb)                   | [![Open in Google Colab][Open in Google Colab]](https://colab.research.google.com/github/janosh/pymatviz/blob/main/examples/mprester_ptable.ipynb)          | [Launch Codespace][codespace url] |

[Open in Google Colab]: https://colab.research.google.com/assets/colab-badge.svg
[codespace url]: https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=340898532

## Periodic Table

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

|                                        [`ptable_heatmap_plotly(atomic_masses)`](pymatviz/ptable/figures.py#L54)                                         | [`ptable_heatmap_plotly(compositions, log=True)`](pymatviz/ptable/figures.py#L54) [![fig-icon]](assets/scripts/ptable/ptable_heatmap_plotly.py) |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                        ![ptable-heatmap-plotly-more-hover-data]                                                         |                                                          ![ptable-heatmap-plotly-log]                                                           |
|               [`ptable_hists_plotly(data)`](pymatviz/ptable/figures.py#L441) [![fig-icon]](assets/scripts/ptable/ptable_hists_plotly.py)                | [`ptable_scatter_plotly(data, mode="markers")`](pymatviz/ptable/figures.py#L1595) [![fig-icon]](assets/scripts/ptable/ptable_scatter_plotly.py) |
|                                                                 ![ptable-hists-plotly]                                                                  |                                                        ![ptable-scatter-plotly-markers]                                                         |
| [`ptable_heatmap_splits_plotly(2_vals_per_elem)`](pymatviz/ptable/figures.py#L857) [![fig-icon]](assets/scripts/ptable/ptable_heatmap_splits_plotly.py) |                               [`ptable_heatmap_splits_plotly(3_vals_per_elem)`](pymatviz/ptable/figures.py#L857)                                |
|                                                            ![ptable-heatmap-splits-plotly-2]                                                            |                                                        ![ptable-heatmap-splits-plotly-3]                                                        |

[ptable-heatmap-plotly-log]: https://github.com/janosh/pymatviz/raw/main/assets/svg/ptable-heatmap-plotly-log.svg
[ptable-heatmap-plotly-more-hover-data]: https://github.com/janosh/pymatviz/raw/main/assets/svg/ptable-heatmap-plotly-more-hover-data.svg
[ptable-heatmap-splits-plotly-2]: https://github.com/janosh/pymatviz/raw/main/assets/svg/ptable-heatmap-splits-plotly-2.svg
[ptable-heatmap-splits-plotly-3]: https://github.com/janosh/pymatviz/raw/main/assets/svg/ptable-heatmap-splits-plotly-3.svg
[ptable-hists-plotly]: https://github.com/janosh/pymatviz/raw/main/assets/svg/ptable-hists-plotly.svg
[ptable-scatter-plotly-markers]: https://github.com/janosh/pymatviz/raw/main/assets/svg/ptable-scatter-plotly-markers.svg

### Dash app using `ptable_heatmap_plotly()`

See [`examples/mprester_ptable.ipynb`](examples/mprester_ptable.ipynb).

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

## Phonons

| [`phonon_bands(bands_dict)`](pymatviz/phonons/figures.py#L43) [![fig-icon]](assets/scripts/phonons/phonon_bands.py) |                  [`phonon_dos(doses_dict)`](pymatviz/phonons/figures.py#L366) [![fig-icon]](assets/scripts/phonons/phonon_dos.py)                  |
| :-----------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                   ![phonon-bands]                                                   |                                                                   ![phonon-dos]                                                                    |
|                 [`phonon_bands_and_dos(bands_dict, doses_dict)`](pymatviz/phonons/figures.py#L606)                  | [`phonon_bands_and_dos(single_bands, single_dos)`](pymatviz/phonons/figures.py#L606) [![fig-icon]](assets/scripts/phonons/phonon_bands_and_dos.py) |
|                                           ![phonon-bands-and-dos-mp-2758]                                           |                                                          ![phonon-bands-and-dos-mp-23907]                                                          |

[phonon-bands]: https://github.com/janosh/pymatviz/raw/main/assets/svg/phonon-bands-mp-2758.svg
[phonon-dos]: https://github.com/janosh/pymatviz/raw/main/assets/svg/phonon-dos-mp-2758.svg
[phonon-bands-and-dos-mp-2758]: https://github.com/janosh/pymatviz/raw/main/assets/svg/phonon-bands-and-dos-mp-2758.svg
[phonon-bands-and-dos-mp-23907]: https://github.com/janosh/pymatviz/raw/main/assets/svg/phonon-bands-and-dos-mp-23907.svg

### Composition Clustering

| [`cluster_compositions(compositions, properties, embedding_method, projection_method, n_components=2)`](pymatviz/cluster/composition/plot.py#L363) [![fig-icon]](assets/scripts/cluster/composition/cluster_compositions_matbench.py) | [`cluster_compositions(compositions, properties, embedding_method, projection_method, n_components=3)`](pymatviz/cluster/composition/plot.py#L363) |
| :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                                                                 ![matbench-perovskites-magpie-pca-2d]                                                                                                 |                                                       ![matbench-perovskites-magpie-tsne-3d]                                                       |

[matbench-perovskites-magpie-pca-2d]: https://github.com/janosh/pymatviz/raw/main/assets/svg/matbench-perovskites-magpie-pca-2d.svg
[matbench-perovskites-magpie-tsne-3d]: https://github.com/janosh/pymatviz/raw/main/assets/svg/matbench-perovskites-magpie-tsne-3d.svg

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:

```py
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/figures.py`](pymatviz/structure/figures.py).

|                            [`structure_3d(hea_structure)`](pymatviz/structure/figures.py)                            | [`structure_3d(lco_supercell)`](pymatviz/structure/figures.py) [![fig-icon]](assets/scripts/structure/structure_3d.py) |
| :------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------: |
|                                                 ![hea-structure-3d]                                                  |                                                  ![lco-structure-3d]                                                   |
| [`structure_2d(six_structs)`](pymatviz/structure/figures.py) [![fig-icon]](assets/scripts/structure/structure_2d.py) |  [`structure_3d(six_structs)`](pymatviz/structure/figures.py) [![fig-icon]](assets/scripts/structure/structure_3d.py)  |
|                                          ![matbench-phonons-structures-2d]                                           |                                           ![matbench-phonons-structures-3d]                                            |

[matbench-phonons-structures-2d]: https://github.com/janosh/pymatviz/raw/main/assets/svg/matbench-phonons-structures-2d.svg
[matbench-phonons-structures-3d]: https://github.com/janosh/pymatviz/raw/main/assets/svg/matbench-phonons-structures-3d.svg
[hea-structure-3d]: https://github.com/janosh/pymatviz/raw/main/assets/svg/hea-structure-3d.svg
[lco-structure-3d]: https://github.com/janosh/pymatviz/raw/main/assets/svg/lco-structure-3d.svg

## Interactive Widgets

See [`pymatviz/widgets`](pymatviz/widgets). Interactive 3D structure, molecular dynamics trajectory and composition visualization widgets for [Jupyter](https://jupyter.org), [Marimo](https://marimo.io), and VSCode notebooks, powered by [anywidget](https://anywidget.dev) and [MatterViz](https://matterviz.janosh.dev) (<https://github.com/janosh/matterviz>). Supports pymatgen `Structure`, ASE `Atoms`, and `PhonopyAtoms`, as well as ASE, `pymatgen` and plain Python trajectory formats.

```py
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:**

- [Jupyter notebook demo](examples/widgets/jupyter_demo.ipynb)
- [Marimo demo](examples/widgets/marimo_demo.py)
- [VSCode interactive demo](examples/widgets/vscode_interactive_demo.py)

> [!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](https://marketplace.visualstudio.com/items?itemName=janosh.matterviz)

Importing `pymatviz` auto-registers all widgets for their respective sets of supported objects via [`register_matterviz_widgets()`](pymatviz/widgets/mime.py).

## Brillouin Zone

See [`pymatviz/brillouin.py`](pymatviz/brillouin.py).

|   [`brillouin_zone_3d(cubic_struct)`](pymatviz/brillouin.py#L16) [![fig-icon]](assets/scripts/brillouin/brillouin_zone_3d.py)    |  [`brillouin_zone_3d(hexagonal_struct)`](pymatviz/brillouin.py#L16)   |
| :------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------: |
|                                                   ![brillouin-cubic-mp-10018]                                                    |                   ![brillouin-hexagonal-mp-862690]                    |
| [`brillouin_zone_3d(monoclinic_struct)`](pymatviz/brillouin.py#L16) [![fig-icon]](assets/scripts/brillouin/brillouin_zone_3d.py) | [`brillouin_zone_3d(orthorhombic_struct)`](pymatviz/brillouin.py#L16) |
|                                                ![brillouin-monoclinic-mp-1183089]                                                |                      ![brillouin-volumes-3-cols]                      |

[brillouin-cubic-mp-10018]: https://github.com/janosh/pymatviz/raw/main/assets/svg/brillouin-cubic-mp-10018.svg
[brillouin-hexagonal-mp-862690]: https://github.com/janosh/pymatviz/raw/main/assets/svg/brillouin-hexagonal-mp-862690.svg
[brillouin-monoclinic-mp-1183089]: https://github.com/janosh/pymatviz/raw/main/assets/svg/brillouin-monoclinic-mp-1183089.svg
[brillouin-orthorhombic-mp-1183085]: https://github.com/janosh/pymatviz/raw/main/assets/svg/brillouin-orthorhombic-mp-1183085.svg
[brillouin-volumes-3-cols]: https://github.com/janosh/pymatviz/raw/main/assets/svg/brillouin-volumes-3-cols.svg

## X-Ray Diffraction

See [`pymatviz/xrd.py`](pymatviz/xrd.py).

|             [`xrd_pattern(pattern)`](pymatviz/xrd.py#L45) [![fig-icon]](assets/scripts/xrd/xrd_pattern.py)             |  [`xrd_pattern({key1: patt1, key2: patt2})`](pymatviz/xrd.py#L45)   |
| :--------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------: |
|                                                     ![xrd-pattern]                                                     |                       ![xrd-pattern-multiple]                       |
| [`xrd_pattern(struct_dict, stack="horizontal")`](pymatviz/xrd.py#L45) [![fig-icon]](assets/scripts/xrd/xrd_pattern.py) | [`xrd_pattern(struct_dict, stack="vertical")`](pymatviz/xrd.py#L45) |
|                                            ![xrd-pattern-horizontal-stack]                                             |                    ![xrd-pattern-vertical-stack]                    |

[xrd-pattern]: https://github.com/janosh/pymatviz/raw/main/assets/svg/xrd-pattern.svg
[xrd-pattern-multiple]: https://github.com/janosh/pymatviz/raw/main/assets/svg/xrd-pattern-multiple.svg
[xrd-pattern-horizontal-stack]: https://github.com/janosh/pymatviz/raw/main/assets/svg/xrd-pattern-horizontal-stack.svg
[xrd-pattern-vertical-stack]: https://github.com/janosh/pymatviz/raw/main/assets/svg/xrd-pattern-vertical-stack.svg

## Radial Distribution Functions

See [`pymatviz/rdf/figures.py`](pymatviz/rdf/figures.py).

| [`element_pair_rdfs(pmg_struct)`](pymatviz/rdf/figures.py#L34) | [`element_pair_rdfs({"A": struct1, "B": struct2})`](pymatviz/rdf/figures.py#L34) [![fig-icon]](assets/scripts/rdf/element_pair_rdfs.py) |
| :------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------: |
|                 ![element-pair-rdfs-Na8Nb8O24]                 |                                                ![element-pair-rdfs-crystal-vs-amorphous]                                                |

[element-pair-rdfs-Na8Nb8O24]: https://github.com/janosh/pymatviz/raw/main/assets/svg/element-pair-rdfs-Na8Nb8O24.svg
[element-pair-rdfs-crystal-vs-amorphous]: https://github.com/janosh/pymatviz/raw/main/assets/svg/element-pair-rdfs-crystal-vs-amorphous.svg

## Coordination

See [`pymatviz/coordination/figures.py`](pymatviz/coordination/figures.py).

|              [`coordination_hist(struct_dict)`](pymatviz/coordination/figures.py#L35)              |            [`coordination_hist(struct_dict, by_element=True)`](pymatviz/coordination/figures.py#L35) [![fig-icon]](assets/scripts/coordination/coordination_hist.py)             |
| :------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                    ![coordination-hist-single]                                     |                                                                  ![coordination-hist-by-structure-and-element]                                                                   |
| [`coordination_vs_cutoff_line(struct_dict, strategy=None)`](pymatviz/coordination/figures.py#L366) | [`coordination_vs_cutoff_line(struct_dict, strategy=None)`](pymatviz/coordination/figures.py#L366) [![fig-icon]](assets/scripts/coordination/coordination_vs_cutoff_line.py#L52) |
|                                  ![coordination-vs-cutoff-single]                                  |                                                                        ![coordination-vs-cutoff-multiple]                                                                        |

[coordination-hist-single]: https://github.com/janosh/pymatviz/raw/main/assets/svg/coordination-hist-single.svg
[coordination-hist-by-structure-and-element]: https://github.com/janosh/pymatviz/raw/main/assets/svg/coordination-hist-by-structure-and-element.svg
[coordination-vs-cutoff-single]: https://github.com/janosh/pymatviz/raw/main/assets/svg/coordination-vs-cutoff-single.svg
[coordination-vs-cutoff-multiple]: https://github.com/janosh/pymatviz/raw/main/assets/svg/coordination-vs-cutoff-multiple.svg

## Sunburst

See [`pymatviz/sunburst.py`](pymatviz/sunburst).

| [`spacegroup_sunburst([65, 134, 225, ...])`](pymatviz/sunburst/spacegroup.py) [![fig-icon]](assets/scripts/sunburst/spacegroup_sunburst.py) | [`chem_sys_sunburst(["FeO", "Fe2O3", "LiPO4", ...])`](pymatviz/sunburst/chem_sys.py) [![fig-icon]](assets/scripts/sunburst/chem_sys_sunburst.py) |
| :-----------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                             ![spg-num-sunburst]                                                             |                                                          ![chem-sys-sunburst-ward-bmg]                                                           |
|                                     [`chem_env_sunburst(single_struct)`](pymatviz/sunburst/chem_env.py)                                     |                                      [`chem_env_sunburst(multiple_structs)`](pymatviz/sunburst/chem_env.py)                                      |
|                                                         ![chem-env-sunburst-basic]                                                          |                                                          ![chem-env-sunburst-mp-carbon]                                                          |

[spg-num-sunburst]: https://github.com/janosh/pymatviz/raw/main/assets/svg/spg-num-sunburst.svg
[chem-sys-sunburst-ward-bmg]: https://github.com/janosh/pymatviz/raw/main/assets/svg/chem-sys-sunburst-ward-bmg.svg
[chem-env-sunburst-basic]: https://github.com/janosh/pymatviz/raw/main/assets/svg/chem-env-sunburst-basic.svg
[chem-env-sunburst-mp-carbon]: https://github.com/janosh/pymatviz/raw/main/assets/svg/chem-env-sunburst-mp-carbon.svg

## Treemap

See [`pymatviz/treemap/chem_sys.py`](pymatviz/treemap/chem_sys.py).

| [`chem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...])`](pymatviz/treemap/chem_sys.py#L36) [![fig-icon]](assets/scripts/treemap/chem_sys_treemap.py) | [`chem_sys_treemap(["FeO", "Fe2O3", "LiPO4", ...], group_by="formula")`](pymatviz/treemap/chem_sys.py#L36) |
| :----------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------: |
|                                                           ![chem-sys-treemap-formula]                                                            |                                        ![chem-sys-treemap-ward-bmg]                                        |
|           [`chem_env_treemap(structures)`](pymatviz/treemap/chem_env.py#L50) [![fig-icon]](assets/scripts/treemap/chem_env_treemap.py)           |     [`chem_env_treemap(structures, max_cells_cn=3, max_cells_ce=4)`](pymatviz/treemap/chem_env.py#L50)     |
|                                                            ![chem-env-treemap-basic]                                                             |                                     ![chem-env-treemap-large-dataset]                                      |
|             [`py_pkg_treemap("pymatviz")`](pymatviz/treemap/py_pkg.py#L705) [![fig-icon]](assets/scripts/treemap/py_pkg_treemap.py)              |           [`py_pkg_treemap(["pymatviz", "flame", "pymatgen"])`](pymatviz/treemap/py_pkg.py#L36)            |
|                                                            ![py-pkg-treemap-pymatviz]                                                            |                                         ![py-pkg-treemap-multiple]                                         |
|   [`py_pkg_treemap("pymatviz", color_by="coverage")`](pymatviz/treemap/py_pkg.py#L705) [![fig-icon]](assets/scripts/treemap/py_pkg_treemap.py)   | [`py_pkg_treemap("pymatgen", color_by="coverage", color_range=(0, 100))`](pymatviz/treemap/py_pkg.py#L705) |
|                                                       ![py-pkg-treemap-pymatviz-coverage]                                                        |                                    ![py-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`).

[chem-sys-treemap-formula]: https://github.com/janosh/pymatviz/raw/main/assets/svg/chem-sys-treemap-formula.svg
[chem-sys-treemap-ward-bmg]: https://github.com/janosh/pymatviz/raw/main/assets/svg/chem-sys-treemap-ward-bmg.svg
[py-pkg-treemap-pymatviz]: https://github.com/janosh/pymatviz/raw/main/assets/svg/py-pkg-treemap-pymatviz.svg
[py-pkg-treemap-multiple]: https://github.com/janosh/pymatviz/raw/main/assets/svg/py-pkg-treemap-multiple.svg
[py-pkg-treemap-pymatgen-coverage]: https://github.com/janosh/pymatviz/raw/main/assets/svg/py-pkg-treemap-pymatgen-coverage.svg
[py-pkg-treemap-pymatviz-coverage]: https://github.com/janosh/pymatviz/raw/main/assets/svg/py-pkg-treemap-pymatviz-coverage.svg
[chem-env-treemap-large-dataset]: https://github.com/janosh/pymatviz/raw/main/assets/svg/chem-env-treemap-large-dataset.svg
[chem-env-treemap-basic]: https://github.com/janosh/pymatviz/raw/main/assets/svg/chem-env-treemap-basic.svg

## Rainclouds

See [`pymatviz/rainclouds.py`](pymatviz/rainclouds.py).

| [`rainclouds(two_key_dict)`](pymatviz/rainclouds.py#L22) [![fig-icon]](assets/scripts/rainclouds/rainclouds.py) | [`rainclouds(three_key_dict)`](pymatviz/rainclouds.py#L22) |
| :-------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------: |
|                                              ![rainclouds-bimodal]                                              |                   ![rainclouds-trimodal]                   |

[rainclouds-bimodal]: https://github.com/janosh/pymatviz/raw/main/assets/svg/rainclouds-bimodal.svg
[rainclouds-trimodal]: https://github.com/janosh/pymatviz/raw/main/assets/svg/rainclouds-trimodal.svg

## Sankey

See [`pymatviz/sankey.py`](pymatviz/sankey.py).

| [`sankey_from_2_df_cols(df_perovskites)`](pymatviz/sankey.py#L18) [![fig-icon]](assets/scripts/sankey/sankey_from_2_df_cols.py) | [`sankey_from_2_df_cols(df_space_groups)`](pymatviz/sankey.py#L18) |
| :-----------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------: |
|                                              ![sankey-spglib-vs-aflow-spacegroups]                                              |                ![sankey-crystal-sys-to-spg-symbol]                 |

[sankey-spglib-vs-aflow-spacegroups]: https://github.com/janosh/pymatviz/raw/main/assets/svg/sankey-spglib-vs-aflow-spacegroups.svg
[sankey-crystal-sys-to-spg-symbol]: https://github.com/janosh/pymatviz/raw/main/assets/svg/sankey-crystal-sys-to-spg-symbol.svg

## Bar Plots

See [`pymatviz/bar.py`](pymatviz/bar.py).

| [`spacegroup_bar([65, 134, 225, ...])`](pymatviz/bar.py#L29) [![fig-icon]](assets/scripts/bar/spacegroup_bar.py) | [`spacegroup_bar(["C2/m", "P-43m", "Fm-3m", ...])`](pymatviz/bar.py#L29) |
| :--------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------: |
|                                              ![spg-num-hist-plotly]                                              |                        ![spg-symbol-hist-plotly]                         |

[spg-symbol-hist-plotly]: https://github.com/janosh/pymatviz/raw/main/assets/svg/spg-symbol-hist-plotly.svg
[spg-num-hist-plotly]: https://github.com/janosh/pymatviz/raw/main/assets/svg/spg-num-hist-plotly.svg

## Histograms

See [`pymatviz/histogram.py`](pymatviz/histogram.py).

| [`elements_hist(compositions, log=True, bar_values='count')`](pymatviz/histogram.py#L21) [![fig-icon]](assets/scripts/histogram/elements_hist.py) | [`histogram({'key1': values1, 'key2': values2})`](pymatviz/histogram.py#L89) [![fig-icon]](assets/scripts/histogram/histogram.py) |
| :-----------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------: |
|                                                                 ![elements-hist]                                                                  |                                                         ![histogram-ecdf]                                                         |

[histogram-ecdf]: https://github.com/janosh/pymatviz/raw/main/assets/svg/histogram-ecdf.svg

## Scatter Plots

See [`pymatviz/scatter.py`](pymatviz/scatter.py).

| [`density_scatter(xs, ys, ...)`](pymatviz/scatter.py) [![fig-icon]](assets/scripts/scatter/density_scatter.py) | [`density_scatter_with_hist(xs, ys, ...)`](pymatviz/scatter.py) [![fig-icon]](assets/scripts/scatter/density_scatter.py) |
| :------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------: |
|                                               ![density-scatter]                                               |                                               ![density-scatter-with-hist]                                               |
|  [`density_hexbin(xs, ys, ...)`](pymatviz/scatter.py) [![fig-icon]](assets/scripts/scatter/density_hexbin.py)  |  [`density_hexbin_with_hist(xs, ys, ...)`](pymatviz/scatter.py) [![fig-icon]](assets/scripts/scatter/density_hexbin.py)  |
|                                               ![density-hexbin]                                                |                                               ![density-hexbin-with-hist]                                                |

[density-hexbin-with-hist]: https://github.com/janosh/pymatviz/raw/main/assets/svg/density-hexbin-with-hist.svg
[density-hexbin]: https://github.com/janosh/pymatviz/raw/main/assets/svg/density-hexbin.svg
[density-scatter-with-hist]: https://github.com/janosh/pymatviz/raw/main/assets/svg/density-scatter-with-hist.svg
[density-scatter]: https://github.com/janosh/pymatviz/raw/main/assets/svg/density-scatter.svg

## Uncertainty

See [`pymatviz/uncertainty.py`](pymatviz/uncertainty.py).

|             [`qq_gaussian(y_true, y_pred, y_std)`](pymatviz/uncertainty.py#L22) [![fig-icon]](assets/scripts/uncertainty/qq_gaussian.py)              |       [`qq_gaussian(y_true, y_pred, y_std: dict)`](pymatviz/uncertainty.py#L22)        |
| :---------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------: |
|                                                                    ![qq-gaussian]                                                                     |                                ![qq-gaussian-multiple]                                 |
| [`error_decay_with_uncert(y_true, y_pred, y_std)`](pymatviz/uncertainty.py#L119) [![fig-icon]](assets/scripts/uncertainty/error_decay_with_uncert.py) | [`error_decay_with_uncert(y_true, y_pred, y_std: dict)`](pymatviz/uncertainty.py#L119) |
|                                                              ![error-decay-with-uncert]                                                               |                          ![error-decay-with-uncert-multiple]                           |

## Classification

See [`pymatviz/classify/confusion_matrix.py`](pymatviz/classify/confusion_matrix.py).

| [`confusion_matrix(conf_mat, ...)`](pymatviz/classify/confusion_matrix.py#L14) | [`confusion_matrix(y_true, y_pred, ...)`](pymatviz/classify/confusion_matrix.py#L14) [![fig-icon]](assets/scripts/classify/confusion_matrix.py) |
| :----------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------: |
|                         ![stability-confusion-matrix]                          |                                                       ![crystal-system-confusion-matrix]                                                        |

See [`pymatviz/classify/curves.py`](pymatviz/classify/curves.py).

| [`roc_curve_plotly(targets, probs_positive)`](pymatviz/classify/curves.py#L83) [![fig-icon]](assets/scripts/classify/roc_curve.py) | [`precision_recall_curve_plotly(targets, probs_positive)`](pymatviz/classify/curves.py#L183) [![fig-icon]](assets/scripts/classify/precision_recall_curve.py) |
| :--------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------: |
|                                                    ![roc-curve-plotly-multiple]                                                    |                                                           ![precision-recall-curve-plotly-multiple]                                                           |

[roc-curve-plotly-multiple]: https://github.com/janosh/pymatviz/raw/main/assets/svg/roc-curve-plotly-multiple.svg
[precision-recall-curve-plotly-multiple]: https://github.com/janosh/pymatviz/raw/main/assets/svg/precision-recall-curve-plotly-multiple.svg
[stability-confusion-matrix]: https://github.com/janosh/pymatviz/raw/main/assets/svg/stability-confusion-matrix.svg
[crystal-system-confusion-matrix]: https://github.com/janosh/pymatviz/raw/main/assets/svg/crystal-system-confusion-matrix.svg
[error-decay-with-uncert-multiple]: https://github.com/janosh/pymatviz/raw/main/assets/svg/error-decay-with-uncert-multiple.svg
[error-decay-with-uncert]: https://github.com/janosh/pymatviz/raw/main/assets/svg/error-decay-with-uncert.svg
[elements-hist]: https://github.com/janosh/pymatviz/raw/main/assets/svg/elements-hist.svg
[qq-gaussian-multiple]: https://github.com/janosh/pymatviz/raw/main/assets/svg/qq-gaussian-multiple.svg
[qq-gaussian]: https://github.com/janosh/pymatviz/raw/main/assets/svg/qq-gaussian.svg

## How to cite `pymatviz`

See [`citation.cff`](citation.cff) or cite the [Zenodo record](https://zenodo.org/badge/latestdoi/340898532) using the following BibTeX entry:

```bib
@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](https://scholar.google.com/scholar?q=pymatviz). Manual additions [via PR](https://github.com/janosh/pymatviz/edit/main/readme.md) welcome.

1. L Barroso-Luque, M Shuaibi, X Fu et al. (2024). [Open materials 2024 (omat24) inorganic materials dataset and models](https://arxiv.org/abs/2410.12771) (cited by 230)
1. C Zeni, R Pinsler, D Zügner et al. (2023). [Mattergen: a generative model for inorganic materials design](https://arxiv.org/abs/2312.03687) (cited by 166)
1. 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](https://pubs.acs.org/doi/abs/10.1021/jacs.4c03849) (cited by 131)
1. J Riebesell, REA Goodall, P Benner et al. (2023). [Matbench Discovery--A framework to evaluate machine learning crystal stability predictions](https://arxiv.org/abs/2308.14920) (cited by 106)
1. H Yu, M Giantomassi, G Materzanini (2024). [Systematic assessment of various universal machine‐learning interatomic potentials](https://onlinelibrary.wiley.com/doi/abs/10.1002/mgea.58) (cited by 69)
1. 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](https://pubs.rsc.org/en/content/articlehtml/2025/sc/d4sc07438f) (cited by 34)
1. AA Naik, C Ertural, N Dhamrait et al. (2023). [A quantum-chemical bonding database for solid-state materials](https://www.nature.com/articles/s41597-023-02477-5) (cited by 28)
1. 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](https://pubs.rsc.org/en/content/articlehtml/2026/dd/d5dd00441a) (cited by 9)
1. K Li, AN Rubungo, X Lei et al. (2024). [Probing out-of-distribution generalization in machine learning for materials](https://arxiv.org/abs/2406.06489) (cited by 9)
1. Y Zhou, X He, Z Li (2025). [Scientists' First Exam: Probing Cognitive Abilities of MLLM via Perception, Understanding, and Reasoning](https://arxiv.org/abs/2506.10521) (cited by 6)
1. HH Li, Q Chen, G Ceder (2024). [Voltage Mining for (De) lithiation-Stabilized Cathodes and a Machine Learning Model for Li-Ion Cathode Voltage](https://pubs.acs.org/doi/abs/10.1021/acsami.4c15742) (cited by 5)
1. A Peng, X Liu, MY Guo et al. (2025). [The openlam challenges](https://arxiv.org/abs/2501.16358) (cited by 3)
1. J Nam, S Liu, G Winter et al. (2025). [Flow matching for accelerated simulation of atomic transport in crystalline materials](https://www.nature.com/articles/s42256-025-01125-4) (cited by 3)
1. A Onwuli, KT Butler, A Walsh (2024). [Ionic species representations for materials informatics](https://pubs.aip.org/aip/aml/article/2/3/036112/3313198) (cited by 3)
1. N Tuchinda, CA Schuh (2025). [Grain Boundary Segregation and Embrittlement of Aluminum Binary Alloys from First Principles](https://arxiv.org/abs/2502.01579) (cited by 2)
1. R Nduma, H Park, A Walsh (2025). [Crystalyse: a multi-tool agent for materials design](https://arxiv.org/abs/2512.00977) (cited by 2)
1. N Tuchinda, CA Schuh (2025). [A grain boundary embrittlement genome for substitutional cubic alloys](https://pubs.aip.org/aip/apl/article/126/17/171602/3345390) (cited by 1)
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](https://www.researchsquare.com/article/rs-7837297/latest) (cited by 1)
1. T Cavignac, J Schmidt, PP De Breuck et al. (2025). [AI-Driven Expansion and Application of the Alexandria Database](https://arxiv.org/abs/2512.09169) (cited by 1)
1. J Riebesell, H Yang, R Goodall et al. (2024). [janosh/pymatviz: v0. 11.0](https://ui.adsabs.harvard.edu/abs/2024zndo..13624216R/abstract) (cited by 1)
1. T Warford, FL Thiemann, GĂĄ CsĂĄnyi (2026). [Better without U: Impact of Selective Hubbard U Correction on Foundational MLIPs](https://arxiv.org/abs/2601.21056)
1. 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](https://www.nature.com/articles/s41524-025-01871-4)
1. Omar Allam, Brook Wander, SungYeon Kim et al. (2025). [AQCat25: Unlocking spin-aware, high-fidelity machine learning potentials for heterogeneous catalysis](http://arxiv.org/abs/2510.22938)
1. Giulio Benedini, Antoine Loew, Matti Hellstrom et al. (2025). [Universal Machine Learning Potential for Systems with Reduced Dimensionality](https://arxiv.org/abs/2508.15614v1)
1. 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](https://openreview.net/forum?id=ysKfIavYQE)
1. Orion Archer Cohen, Janosh Riebesell, Rhys Goodall et al. (2025). [TorchSim: An efficient atomistic simulation engine in PyTorch](http://iopscience.iop.org/article/10.1088/3050-287X/ae1799)
1. 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](https://www.nature.com/articles/s41524-025-01611-8)
1. Matthew K. Horton, Patrick Huck, Ruo Xi Yang et al. (2025). [Accelerated data-driven materials science with the Materials Project](https://www.nature.com/articles/s41563-025-02272-0)
1. Aaron D. Kaplan, Runze Liu, Ji Qi et al. (2025). [A Foundational Potential Energy Surface Dataset for Materials](http://arxiv.org/abs/2503.04070)
1. Matthew C. Kuner, Aaron D. Kaplan, Kristin A. Persson et al. (2025). [MP-ALOE: An r2SCAN dataset for universal machine learning interatomic potentials](http://arxiv.org/abs/2507.05559)
1. Anyang Peng, Xinzijian Liu, Ming-Yu Guo et al. (2025). [The OpenLAM Challenges: LAM Crystal Philately competition](https://doi.org/10.1088/2632-2153/add3bf)
1. Ali Ramlaoui, Martin Siron, Inel Djafar et al. (2025). [LeMat-Traj: A Scalable and Unified Dataset of Materials Trajectories for Atomistic Modeling](http://arxiv.org/abs/2508.20875)
1. 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](http://arxiv.org/abs/2502.03578)
1. Yingheng Tang, Wenbin Xu, Jie Cao et al. (2025). [MatterChat: A Multi-Modal LLM for Material Science](http://arxiv.org/abs/2502.13107)
1. Liming Wu, Wenbing Huang, Rui Jiao et al. (2025). [Siamese Foundation Models for Crystal Structure Prediction](http://arxiv.org/abs/2503.10471)
1. K Yan, M Bohde, A Kryvenko (2025). [A Materials Foundation Model via Hybrid Invariant-Equivariant Architectures](https://arxiv.org/abs/2503.05771)
1. M Gibaldi, J Luo, AJ White et al. (2025). [Generalizable classification of crystal structure error types using graph attention networks](https://pubs.rsc.org/en/content/articlehtml/2025/ta/d5ta05426e)
1. Daniel W. Davies, Keith T. Butler, Adam J. Jackson et al. (2024). [SMACT: Semiconducting Materials by Analogy and Chemical Theory](https://github.com/WMD-group/SMACT)
1. Hui Zheng, Eric Sivonxay, Rasmus Christensen et al. (2024). [The ab initio non-crystalline structure database: empowering machine learning to decode diffusivity](https://www.nature.com/articles/s41524-024-01469-2)
1. Ilyes Batatia, Philipp Benner, Yuan Chiang et al. (2023). [A foundation model for atomistic materials chemistry](https://arxiv.org/abs/2401.00096v1)
1. Jack Douglas Sundberg (2022). [A New Framework for Material Informatics and Its Application Toward Electride-Halide Material Systems](https://cdr.lib.unc.edu/concern/dissertations/r494vw405)
