Sumo

2.4.0.post1 · active · verified Fri Apr 17

Sumo provides heavy-weight plotting tools specifically designed for analyzing ab initio solid-state calculations. It focuses on generating high-quality visualizations for electronic band structures, density of states (DOS), and phonon properties, often integrating seamlessly with `pymatgen` objects. The current version is 2.4.0.post1, and the library maintains an active release cadence, frequently addressing compatibility with its core dependencies like `pymatgen` and `phonopy`.

Common errors

```
TypeError: get_number_of_atoms() takes 0 positional arguments but 1 was given
```
cause This error occurs when an older version of Sumo attempts to call the `get_number_of_atoms()` method from `phonopy.PhonopyAtoms`, but the method signature has changed in newer `phonopy` versions.

fix Upgrade Sumo to version 2.4.0 or newer (`pip install --upgrade sumo`), which has updated its `phonopy` API calls.
```
AttributeError: 'BandStructure' object has no attribute 'get_bands'
```
cause This often indicates that a `sumo` plotting function is expecting a `pymatgen` `BandStructure` object with an older API, or vice-versa, due to version mismatch between `sumo` and `pymatgen`.

fix Ensure both `sumo` and `pymatgen` are up-to-date and compatible. Check `sumo`'s GitHub for recent changes impacting `pymatgen` compatibility (`pip install --upgrade sumo pymatgen`).
```
ModuleNotFoundError: No module named 'sumo.cli'
```
cause Users sometimes try to import command-line interface (CLI) tools like `sumo-bandplot` programmatically using `from sumo import cli` or similar. Sumo's CLI tools are installed as entry points and are not meant for direct module import.

fix Use the CLI tools directly from your terminal (e.g., `sumo-bandplot --help`) or, for programmatic access to plotting, import functions from `sumo.plotting` (e.g., `from sumo.plotting import plot_band`).

Warnings

breaking Sumo v2.4.0 and later requires Python 3.10 or newer. Older Python versions are no longer supported.
Fix: Upgrade your Python environment to 3.10 or later (`python -m pip install --upgrade python` or use `pyenv`/`conda`).
breaking Compatibility issues frequently arise with specific versions of `pymatgen` and `phonopy` due to their own API changes. Sumo updates often patch these, but staying up-to-date is crucial.
Fix: Ensure you are using a `sumo` version compatible with your `pymatgen` and `phonopy` versions. Check `sumo`'s `setup.py` or release notes for dependency requirements. Upgrade `sumo` and its dependencies regularly.
deprecated The `phonopy.PhonopyAtoms.get_number_of_atoms()` method was deprecated and removed in recent `phonopy` versions, leading to errors in older `sumo` versions.
Fix: Upgrade `sumo` to version 2.4.0 or newer to use an updated `phonopy` API (`pip install --upgrade sumo`).
gotcha Post-release suffixes like `.post1` (e.g., v2.4.0.post1) typically indicate packaging or metadata fixes, not new features or critical bug fixes to the core functionality.
Fix: Treat `2.4.0.post1` as functionally identical to `2.4.0` in terms of code behavior. There's no need to downgrade or worry about functional differences unless specifically mentioned in release notes.

Install

pip install sumo Install Sumo

Imports

plot_band
wrong:
```
import sumo.plot_band
```
correct:
```
from sumo.plotting import plot_band
```
Plotting functions are typically found within the `sumo.plotting` submodule.
plot_dos
wrong:
```
import sumo.plot_dos
```
correct:
```
from sumo.plotting import plot_dos
```
Plotting functions are typically found within the `sumo.plotting` submodule.

Quickstart

This quickstart demonstrates how to use `sumo.plotting` functions for a band structure and density of states. In a real application, the `BandStructure` and `Dos` objects would typically be loaded from DFT calculation outputs using `pymatgen` parsers (e.g., `pymatgen.io.vasp.Vasprun`). Sumo then takes these `pymatgen` objects to generate publication-quality plots. Note that `matplotlib.pyplot.close()` is used to prevent figures from blocking execution in environments without an active GUI.

import os
from pymatgen.electronic_structure.band_structure import BandStructure, Kpoint
from pymatgen.electronic_structure.dos import Dos, CompleteDos
from sumo.plotting import plot_band, plot_dos
import matplotlib.pyplot as plt
import numpy as np

# --- Create dummy data for demonstration --- #
# In a real scenario, these would come from parsing DFT output (e.g., Vasprun.from_xml)

# Dummy BandStructure object
kpoints = [Kpoint([0,0,0], 0, '$\Gamma$'), Kpoint([0.5,0,0], 0.5, 'X')]
eig_val = {('spin_up', 0): np.array([[-1.0, -0.5], [0.5, 1.0]]), 
           ('spin_down', 0): np.array([[-1.1, -0.6], [0.4, 0.9]])}
efermi = 0.0
bs = BandStructure(kpoints, eig_val, efermi, structure=None, labels_dict={'G': [0,0,0], 'X': [0.5,0,0]})

# Dummy Dos object
energies = np.linspace(-2.0, 2.0, 200)
total_densities = np.exp(-(energies - 0.5)**2 / 0.5) + np.exp(-(energies + 0.5)**2 / 0.5)
tdos = Dos(efermi, energies, total_densities)
cdos = CompleteDos(None, tdos.energies, {'total': tdos.densities})

print("Plotting dummy band structure...")
fig_bs, ax_bs = plot_band(bs, dpi=150)
# To save: fig_bs.savefig("band_structure.png")
plt.close(fig_bs) # Close figure to avoid display issues in non-interactive environments
print("Dummy band structure plot generated and closed.")

print("Plotting dummy density of states...")
fig_dos, ax_dos = plot_dos(cdos, dpi=150)
# To save: fig_dos.savefig("dos.png")
plt.close(fig_dos)
print("Dummy DOS plot generated and closed.")

view raw JSON →