{"id":10274,"library":"sumo","title":"Sumo","description":"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`.","status":"active","version":"2.4.0.post1","language":"en","source_language":"en","source_url":"https://github.com/SMTG-Bham/sumo","tags":["materials science","DFT","solid-state physics","plotting","band structure","density of states","phonons","crystallography"],"install":[{"cmd":"pip install sumo","lang":"bash","label":"Install Sumo"}],"dependencies":[{"reason":"Core dependency for parsing DFT outputs and providing data structures for plotting (e.g., BandStructure, Dos objects).","package":"pymatgen"},{"reason":"Required for phonon calculations and plotting phonon band structures/DOS.","package":"phonopy"},{"reason":"The underlying plotting library used by Sumo.","package":"matplotlib"},{"reason":"Numerical computing foundation.","package":"numpy"}],"imports":[{"note":"Plotting functions are typically found within the `sumo.plotting` submodule.","wrong":"import sumo.plot_band","symbol":"plot_band","correct":"from sumo.plotting import plot_band"},{"note":"Plotting functions are typically found within the `sumo.plotting` submodule.","wrong":"import sumo.plot_dos","symbol":"plot_dos","correct":"from sumo.plotting import plot_dos"}],"quickstart":{"code":"import os\nfrom pymatgen.electronic_structure.band_structure import BandStructure, Kpoint\nfrom pymatgen.electronic_structure.dos import Dos, CompleteDos\nfrom sumo.plotting import plot_band, plot_dos\nimport matplotlib.pyplot as plt\nimport numpy as np\n\n# --- Create dummy data for demonstration --- #\n# In a real scenario, these would come from parsing DFT output (e.g., Vasprun.from_xml)\n\n# Dummy BandStructure object\nkpoints = [Kpoint([0,0,0], 0, '$\\Gamma$'), Kpoint([0.5,0,0], 0.5, 'X')]\neig_val = {('spin_up', 0): np.array([[-1.0, -0.5], [0.5, 1.0]]), \n           ('spin_down', 0): np.array([[-1.1, -0.6], [0.4, 0.9]])}\nefermi = 0.0\nbs = BandStructure(kpoints, eig_val, efermi, structure=None, labels_dict={'G': [0,0,0], 'X': [0.5,0,0]})\n\n# Dummy Dos object\nenergies = np.linspace(-2.0, 2.0, 200)\ntotal_densities = np.exp(-(energies - 0.5)**2 / 0.5) + np.exp(-(energies + 0.5)**2 / 0.5)\ntdos = Dos(efermi, energies, total_densities)\ncdos = CompleteDos(None, tdos.energies, {'total': tdos.densities})\n\nprint(\"Plotting dummy band structure...\")\nfig_bs, ax_bs = plot_band(bs, dpi=150)\n# To save: fig_bs.savefig(\"band_structure.png\")\nplt.close(fig_bs) # Close figure to avoid display issues in non-interactive environments\nprint(\"Dummy band structure plot generated and closed.\")\n\nprint(\"Plotting dummy density of states...\")\nfig_dos, ax_dos = plot_dos(cdos, dpi=150)\n# To save: fig_dos.savefig(\"dos.png\")\nplt.close(fig_dos)\nprint(\"Dummy DOS plot generated and closed.\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.10 or later (`python -m pip install --upgrade python` or use `pyenv`/`conda`).","message":"Sumo v2.4.0 and later requires Python 3.10 or newer. Older Python versions are no longer supported.","severity":"breaking","affected_versions":">=2.4.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions, especially with major `pymatgen`/`phonopy` updates."},{"fix":"Upgrade `sumo` to version 2.4.0 or newer to use an updated `phonopy` API (`pip install --upgrade sumo`).","message":"The `phonopy.PhonopyAtoms.get_number_of_atoms()` method was deprecated and removed in recent `phonopy` versions, leading to errors in older `sumo` versions.","severity":"deprecated","affected_versions":"<2.4.0 with `phonopy` >=2.7.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All post-releases"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Upgrade Sumo to version 2.4.0 or newer (`pip install --upgrade sumo`), which has updated its `phonopy` API calls.","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.","error":"TypeError: get_number_of_atoms() takes 0 positional arguments but 1 was given"},{"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`).","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`.","error":"AttributeError: 'BandStructure' object has no attribute 'get_bands'"},{"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`).","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.","error":"ModuleNotFoundError: No module named 'sumo.cli'"}]}