NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI · #4512 most downloaded on PyPI
Python Materials Genomics is a robust materials analysis code that defines core object representations for structures and molecules with support for many electronic structure codes. It is currently the core analysis code powering the Materials Project (https://materialsproject.org).
Last release 11 days ago
23 Sep 2026
Release timing varies
gaps range from 9 days to 6 months
Nearly every release is documented
notes for 59 of the last 60 stable releases
9 versions withdrawn
withdrawn after publishing
15 years old
414 releases · first in 2011
Drop deprecated SubstrateAnalyzer + ZSLGenerator reexports by @janosh in https://github.com/materialsproject/pymatgen/pull/2981
user_potcar_settings now defaults to {"W": "W_sv"} in all VASP input sets if user_potcar_functional == "PBE_54" (since the 5.4 POTCARs dropped W_pv) (see https://github.com/materialsproject/pymatgen/pull/3022 for details)
pymatgen.io.vasp.optics by @kavanase in https://github.com/materialsproject/pymatgen/pull/2989pymatgen.io.ase module by @arosen93 in https://github.com/materialsproject/pymatgen/pull/2991if TYPE_CHECKING by @janosh in https://github.com/materialsproject/pymatgen/pull/2992SiteCollection + DummySpecies from pymatgen.core by @janosh in https://github.com/materialsproject/pymatgen/pull/2995Species parse oxi state from symbol str by @janosh in https://github.com/materialsproject/pymatgen/pull/2998ce_and_neighbors is None by @janosh in https://github.com/materialsproject/pymatgen/pull/3002MPRester API key in settings if None provided as arg by @ml-evs in https://github.com/materialsproject/pymatgen/pull/3004.pytest-split-durations by @janosh in https://github.com/materialsproject/pymatgen/pull/3005ValueError when structure.selective_dynamics has type np.array by @janosh in https://github.com/materialsproject/pymatgen/pull/3012class PymatgenTest by @janosh in https://github.com/materialsproject/pymatgen/pull/3014ruff PD011 by @janosh in https://github.com/materialsproject/pymatgen/pull/3020user_potcar_settings to {"W": "W_sv"} in all input sets if user_potcar_functional == "PBE_54" by @janosh in https://github.com/materialsproject/pymatgen/pull/3022Full Changelog: https://github.com/materialsproject/pymatgen/compare/v2023.5.10...v2023.05.31
One column per quarter.
3e3c31c <https://github.com/materialsproject/pymatgen/commit/3e3c31c8d342c84f2c6bbb961c321e458b9accb9>_c0ec534 <https://github.com/materialsproject/pymatgen/commit/c0ec53452c3dc87c6cca5edc1c6b2b6218f15569>_Fix mem leak in pbc_shortest_vector cython code. (@stichri)
Fix breaking changes from pandas v2 by @janosh in https://github.com/materialsproject/pymatgen/pull/2935
Yb_2 deprecation release ❗This release changes the Ytterbium (Yb) pseudo-potential (PSP) from Yb_2 to Yb_3 for all PBE_54 VASP input sets.
Background: The A-lab revealed that as a result of using Yb_2 the energy on Yb compounds is off by a lot, resulting in supposedly stable things being unsynthesizable. While an unfortunate mistake, it's also great to see how experiment can help surface simulation errors.
On pre-PBE_54 input sets, we now issue a warning that Yb_2 will give bad results for most systems since Yb is most often in oxidation state Yb3+.
Reason: The better fix Yb_3 only became available in the PBE_54 PSP set. Requiring it on pre-PBE_54 input sets would mean you can't run Yb compounds.
For more details see #2968 and #2969.
find_points_in_spheres() pbc kwarg by @janosh in https://github.com/materialsproject/pymatgen/pull/2907VolumetricData.to_cube() not preserving structure dimensions by @janosh in https://github.com/materialsproject/pymatgen/pull/2909formal_chempots option to ChemicalPotentialDiagram to plot the formal chemical potentials rather than the DFT energies by @kavanase in https://github.com/materialsproject/pymatgen/pull/2916Cp2kOutput.spin_polarized() likely not doing what author intended by @janosh in https://github.com/materialsproject/pymatgen/pull/2954self.assertArrayEqual->assert by @janosh in https://github.com/materialsproject/pymatgen/pull/2955selective_dynamics to Poscar by @chiang-yuan in https://github.com/materialsproject/pymatgen/pull/2951Yb pseudo-potential on all VASP input sets from Yb_2 to Yb_3 by @janosh in https://github.com/materialsproject/pymatgen/pull/2969Yb_2 on pre-PBE_54 input sets by @janosh in https://github.com/materialsproject/pymatgen/pull/2972flake8-pytest-style via ruff by @janosh in https://github.com/materialsproject/pymatgen/pull/2975Full Changelog: https://github.com/materialsproject/pymatgen/compare/v2023.3.23...v2023.5.8
❗ The Yb_2 deprecation release ❗
This release changes the Ytterbium (Yb) pseudo-potential (PSP) from Yb_2 to Yb_3 for all PBE_54 VASP input sets.
Background: The A-lab <https://newscenter.lbl.gov/2023/04/17/meet-the-autonomous-lab-of-the-future> revealed that as a result of using Yb_2 the energy on Yb compounds is off by a lot, resulting in supposedly stable things being unsynthesizable. While an unfortunate mistake, it's also great to see how experiment can help surface simulation errors.
On pre-PBE_54 input sets, we now issue a warning that Yb_2 will give bad results for most systems since Yb is most often in oxidation state Yb3+.
Reason: The better fix Yb_3 only became available in the PBE_54 PSP set. Requiring it on pre-PBE_54 input sets would mean you can't run Yb compounds.
For more details see #2968and #2969.
What's Changed
Enable Structure relaxations with TrajectoryObserver (@janosh)
gen_sl_transform_matrices->gen_sl_transform_matrices (#2894)PR #2882 substrate-optimizations for speed up (@mkhorton)
First release (in a while) with pre-built Linux wheels thanks to @njzjz! 🎉
First release (in a while) with pre-built Linux wheels thanks to @njzjz! 🎉
cibuildwheel to build linux wheels by @njzjz in https://github.com/materialsproject/pymatgen/pull/2800Full Changelog: https://github.com/materialsproject/pymatgen/compare/v2023.2.22...v2023.2.28
cibuildwheel to build linux wheels by @njzjz in https://github.com/materialsproject/pymatgen/pull/2800Full Changelog: https://github.com/materialsproject/pymatgen/compare/v2023.2.22...v2023.2.28
cibuildwheel to build linux wheels (#2800)Fix pre-commit.ci isort error by @janosh in https://github.com/materialsproject/pymatgen/pull/2825
check_stable to False in PatchedPhaseDiagram.get_decomp_and_e_above_hull() for speed by @janosh in https://github.com/materialsproject/pymatgen/pull/2842python-version 3.11 to GH action matrix strategy by @janosh in https://github.com/materialsproject/pymatgen/pull/2714Full Changelog: https://github.com/materialsproject/pymatgen/compare/v2023.1.30...v2023.2.22
OptimadeRester defaults to an outdated list of OPTIMADE database URLs (several of which fail) and the design of the class is such that refreshing these aliases can only be done post-init which means they will not be used if the user provides their own filtered list of aliases, without doing some extra work.
This PR refreshes the vendored list of aliases (which should be much more stable now since their initial addition 2 years ago), and also adds the option to refresh the aliases on initialization of the class.
This currently affects the pymatgen OPTIMADE tutorials at https://github.com/Materials-Consortia/optimade-tutorial-exercises.Major changes to Q-Chem IO (inputs.py and outputs.py) to accommodate differences and new features in version 6+
Passthrough kwargs support for Structure.from_file and Structure.from_str
frac_tolerance to be specified for rounding coordinates in CifParser.frac_tolerance to be specified for rounding coordinates in CifParser.Fix failing piezo tests by @janosh in https://github.com/materialsproject/pymatgen/pull/2729
build to build packages by @njzjz in https://github.com/materialsproject/pymatgen/pull/2735pymatgen/util/serialization.py by @janosh in https://github.com/materialsproject/pymatgen/pull/2736MANIFEST.in by @janosh in https://github.com/materialsproject/pymatgen/pull/2739requirements{,optional}.txt by @janosh in https://github.com/materialsproject/pymatgen/pull/2741dependabot for pip by @janosh in https://github.com/materialsproject/pymatgen/pull/2742NEBPathfinder.string_relax() by @janosh in https://github.com/materialsproject/pymatgen/pull/2740setup.py project_urls by @janosh in https://github.com/materialsproject/pymatgen/pull/2771coord_list_mapping_pbc() by @janosh in https://github.com/materialsproject/pymatgen/pull/2782isort auto insert __future__ annotations import by @janosh in https://github.com/materialsproject/pymatgen/pull/2797Full Changelog: https://github.com/materialsproject/pymatgen/compare/v2022.11.7...v2023.1.9
Fix release workflow by @janosh in https://github.com/materialsproject/pymatgen/pull/2717
copy() methods to ComputedEntry and ComputedStructureEntry by @janosh in https://github.com/materialsproject/pymatgen/pull/2719Full Changelog: https://github.com/materialsproject/pymatgen/compare/v2022.11.1...v2022.11.7
scf_final_print or scf_print), outputs.py now allows parsing both these quantities.Order of kwargs fmt and filename in Structure.to() swapped for ease of use (note: this can break codes that do not use these options as kwargs).
fmt and filename in Structure.to() swapped for ease of use (note: this can break codes that do not use these options as kwargs).m3gnet_relax or m3gnet_static options.Allow env settings to override .pmgrc.yaml (@janosh)
@chunweizhu fix the bugs when runing TEMCalculator
TEMCalculatorTEMCalculator@janosh Add AirssProvider.as_dict
AttributeError currently raised when passing disordered structures to methods like get_cn() and get_bonded_structure() of CrystalNN and other NearNeighbors subclasses.AttributeError currently raised when passing disordered structures to methods like get_cn() and get_bonded_structure() of CrystalNN and other NearNeighbors subclasses.standard_with_comp_range for generating lobsterin files using vaspStructure Graphs from Lobster Data (@JaGeo)
Implemented sufficient methods for new MPRester to cover about 70-80% of common use cases.
Initial implementation of an MPRester2 with new API support. Basic functionality for now.
Note that a further announcement will be made about the future of MPRester. Until then, users of MPRester are advised to consult the Materials Project documentation: https://docs.materialsproject.org/downloading-data/differences-between-new-and-legacy-api
Initial implementation of an MPRester2 with new API support. Basic functionality for now.
Note that a further announcement will be made about the future of MPRester. Until then, users of MPRester are advised to consult the Materials Project documentation: https://docs.materialsproject.org/downloading-data/differences-between-new-and-legacy-api
This will be the final release with the pymatgen.analysis.defects module included in the standard pymatgen package. This release will include the olde
This will be the final release with the pymatgen.analysis.defects module included in the standard pymatgen package. This release will include the older defects code by default, but can also be replaced with the newer defects code through installation of pymatgen-analysis-defects.
Subsequent versions of pymatgen will require the additional installation of pymatgen-analysis-defects for all defect-related functionality via pip install pymatgen-analysis-defects.
Relevant imports will still be from the pymatgen.analysis.defects namespace but the code will now be maintained and developed in this separate repository.
There will be significant changes to the defects code to support new functionality. Existing PyCDT users should use this version of pymatgen or older. Any questions about this change should be directed to Jimmy-Xuan Shen, @jmmshn.
For more information about other pymatgen "add-on" packages, please see this page in our documentation.
…in the future, see pymatgen-analysis-defects and deprecation notice in the code for more information.
Welcome to new contributors @naveensrinivasan, @xivh, @dgaines2, @yang-ruoxi, @cajfisher and @mjwen!
AseAtomsAdaptor, PR #2545 by @arosen93Composition.replace with complex mappings, PR #2555 by @jacksundFunctionality from pymatgen.analysis.defects will be incorporated into a separate add-on package in the future, see pymatgen-analysis-defects and deprecation notice in the code for more information.
Q-Chem updates to NBO and new geometry optimizer, PR #2521 by @samblau
Added option for addtional criteria to be passed to MPRester.get_entries_in_chemsys (@shyuep).
Initial support for parsing ML MD runs from vasprun.xml (@shyuep).
Bug fix for sulfide_type. Sometimes symmetry analysis fails because of tolerance issues. A fallback to analyze all sites.
PR #2518 from @JaGeo. Fixed wrong line in ICOHPLIST.lobster being read to assess whether orbitalwise interactions are included in these files.
PointGroupAnalyzer: the rotational symmetry number.Fix dipole units in recent vasp versions (at least 6.3, maybe even before) (@@fraricci)
Misc bug fixes and deprecation fixes.
pylint in .pre-commit-config.yaml.Major update to CP2K module, PR #2475 from @nwinner
Emergency bugfix release to fix circular import (@janosh)
Support kwargs for ASE adaptor. (@arosen93)
Add VASP WSWQ file parsing, PR #2439 from @jmmshn
This release was previously intended for v2022.2.25.
Important note: an update to a library that pymatgen depends upon has led to the ~/.pmgrc.yml configuration file being corrupted for many users. If you are affected, you may need to re-generate this file. This issue should now be fixed and not re-occur.
Require Cython during setup. (@jonringer)
Critical bug fix for pmgrc.yaml being overwritten in MPRester in a non-standard way.
Vasprun('vasprun.xml').complete_dos.spin_polarization.Cleanup of deprecated methods. (@janosh)
Entry.__repr__() now ouputs name where available. (@janosh)e_0_energy (the desired energy quantity) for VASP 6+. (@arosen93)Outcar().final_energy now prints out e_0_energy (also called "energy(sigma->0)" in the OUTCAR) rather than energy_fr_energy (also called "free energy TOTEN" in the OUTCAR). This is to be consistent with Vasprun().final_energy and because it is generally the desired quantity. Outcar now has two new attributes: .final_energy_wo_entrp and final_fr_energy, which correspond to e_wo_entrp and e_fr_energy, respectively. (@arosen93)Misc bug fixes, e.g., handling of yaml files and type check for MAGMOM flag.
YAML deprecation fixes. (@janosh)
keep_site_properties) in various structure.symmetry.analyzer functions to keep the site properties on the sites after a transformation. (@arosen93)mixing_scheme.py and is implemented as a Compatibility class.Formal support for Python 3.10.
First proper new release of 2022 formalizes the switch back to date-based versioning introduced as a temporary measure last year.
automatic_density_by_lengths, which allows the user to specify a density of k-points in each dimension (rather than just for the entire volume). @Andrew-S-RosenWelcome to new contributor @e-kwsm!
Welcome to new contributor @e-kwsm!
Improvements
Fixes
Documentation
Fix to allow PhaseDiagram to be JSON serializable with computed data cached (@mkhorton, #2276)
Breaking change in PhaseDiagram serialization which will affect any users of BasePhaseDiagram which has now been removed (@shyuep, 2b9911d)
Welcome to new contributors @blokhin, @pzarabadip, @ml-evs, @wuxiaohua1011, @janssenhenning and @penicillin0.
A reminder to all new contributors to ensure your information is accurate at https://pymatgen.org/team.html so that you are acknowledged appropriately by filling out the linked form.
Breaking change in PhaseDiagram serialization which will affect any users of BasePhaseDiagram which has now been removed (@shyuep, 2b9911d)
Speed up nearest-neighbor routines & structure graph generation (@ltalirz, #2239)
Add two more pre-defined OPTIMADE aliases (@blokhin, #2242)
Refactor interface_reactions module, adding support for Plotly (@mattmcdermott, #2233)
Update NOMAD access in MPRester (@wuxiaohua1011, #1958)
General improvements to Phase Diagram code (@CompyRhys, #2263, #2264, #2268)
Improve appearance of periodic table heatmap (@penicillin0, #2272)
Small improvements to battery classes (@jmmshn, #2262)
Fix for Composition.chemical_system to match expected behaviour for compositions with oxidation states (@CompRhys, #2249)
Fix for bad param in OPTIMADE reponse fields (@ml-evs, #2244)
Fix for issue in parsing bandOverlaps.lobster file (@pzarabadip, #2237)
Fix for Moladaptor (@orioncohen, #2269)
Fix for incorrect Potcar hash warnings (@mkhorton, #2273)
Type hint and correct documentation of Structure.remove_site_properties (@kmu, #2256)
Type hint improvements across pymatgen (@janosh, #2241, #2247, #2261)
Add pymatgen-io-fleur addon to addons page (@janssenhenning, #2232)
Update OPTIMADE interface to allow querying multiple providers (@mkhorton, #2238)
New feature to plot chemical potential diagrams (@mattmcdermott, #2218), see ArXiv:2104.05986 for example
@chc273 Major bugfix for cython handling of fractional coordinates wrapping.
New features to handle Grüneisen parameters (@JaGeo, @ab5424, @gpetretto, #2190)
Add spin-dependent eigenvalue band properties (@arosen93, #2187)
Significant new functionality for handling interfaces between structures (@shyamd, #2149)
Features
SymmetrizedStructure (@CompRhys, #2139)Changes
Fixes
FermiDos, NOTE: this can result in significant changes in some instances (@nwinner, #2109)Documentation
PR #2130 @rkingsbury ensures that energy corrections applied to each anion have unique names (e.g., N vs. Cl vs. Br).
QCInput and
QChemDictSet. These radii are used in the construction of PCM cavities and
when calculating charges.get_conventional_standard_structure
method of the SpacegroupAnalyzer for triclinic crystals.QCInput and
QChemDictSet. These radii are used in the construction of PCM cavities and
when calculating charges.get_conventional_standard_structure
method of the SpacegroupAnalyzer for triclinic crystals.Improved Gaussian Cube I/O (@nwinner, #2121)
MaterialsProject2020Compatibility for multi-anion systems (@rkingsbury, #2128)MaterialsProject2020Compatibility (@CompRhys, #2124)Feature to calculate Selling vectors and distances between Lattices (@bwjustus, #1888)
Bug fix to remove possibility of duplicate edges in StructureGraph (@mkhorton, #2095)
StructureGraph (@mkhorton, #2095)Element now has ionization_energies, ionization_energy and electron_affinity properties.
ionization_energies, ionization_energy and
electron_affinity properties.Another bug fix release! Now SETTINGS have been moved to pymatgen.core.
pymatgen, pymatgen.ext, pymatgen.io and pymatgen.analysis are now namespace packages. Note that this does not affect normal usage of pymatgen from v20
pymatgen, pymatgen.ext, pymatgen.io and pymatgen.analysis are now
namespace packages. Note that this does not affect normal usage of pymatgen
from v2022.0.0. All imports remain the same. However, it does allow developerspymatgen, pymatgen.ext, pymatgen.io and pymatgen.analysis are now namespace packages. Note that this does not affect normal usage of pymatgen from v20
pymatgen, pymatgen.ext, pymatgen.io and pymatgen.analysis are now namespace packages. Note that this does not affect normal usage of pymatgen from v2022.0.0. All imports remain the same. However, it does allow developers to write "add-ons" to these subpackages. A full documentation with examples and templates is in the works to guide developers on how to write these packages.
Remove root-level imports in preparation for a transition to a namespace packaging system for pymatgen.
Element now has ionization_energies, ionization_energy and electron_affinity properties.
Element now has ionization_energies, ionization_energy and electron_affinity properties.
Extensive documentation has been added on pymatgen compatibility and the new namespace architecture! We have also released a template repo <https://github.com/materialsproject/pymatgen-addon-template>_ to help new developers write add-ons for pymatgen! Check out our contributing page for details.
Reverts breaking change of removing root imports introduced in version 2021.3.4.
Backwards incompatible Pymatgen root imports have been removed from v2021.3.4 in preparation for a change to a more modular, extensible architecture t…
from pymatgen import <something>, you will need to make
modifications. The easiest way is to use an IDE to run a Search and Replace.
First, replace any from pymatgen import MPRester with
from pymatgen.ext.matproj import MPRester. Then, replace
from pymatgen import with from pymatgen.core import. Alternative, if you
are using a Mac command line, you can do::Backwards incompatible: Pymatgen root imports have been removed from v2021.3.4 in preparation for a change to a more modular, extensible architecture that will allow more developers to contribute.
If your existing code uses from pymatgen import <something>, you will need to make
modifications. The easiest way is to use an IDE to run a Search and Replace.
First, replace any from pymatgen import MPRester with
from pymatgen.ext.matproj import MPRester. Then, replace
from pymatgen import with from pymatgen.core import. Alternatively, if you
are using a Mac command line, you can do::
find . -name '.py' | xargs sed -i "" 's/from pymatgen import MPRester/from pymatgen.ext.matproj import MPRester/g' find . -name '.py' | xargs sed -i "" 's/from pymatgen import/from pymatgen.core import/g'
From a Linux command line, you can do::
find . -name '.py' | xargs sed -i 's/from pymatgen import MPRester/from pymatgen.ext.matproj import MPRester/g' find . -name '.py' | xargs sed -i 's/from pymatgen import/from pymatgen.core import/g'
This should resolve most import errors and only a few more modifications may need to be done by hand.
Specifically, the following "convenience imports" have been removed in favor of their canonical import::
from pymatgen import Composition # now "from pymatgen.core.composition import Composition" from pymatgen import Lattice # now "from pymatgen.core.lattice import Lattice" from pymatgen import SymmOp # now "from pymatgen.core.operations import SymmOp" from pymatgen import DummySpecie, DummySpecies, Element, Specie, Species # now "from pymatgen.core.periodic_table ..." from pymatgen import PeriodicSite, Site # now "from pymatgen.core.sites ..." from pymatgen import IMolecule, IStructure, Molecule, Structure # now "from pymatgen.core.structure ..." from pymatgen import ArrayWithUnit, FloatWithUnit, Unit # now "from pymatgen.core.units ..." from pymatgen import Orbital, Spin # now "from pymatgen.electronic_structure.core ..." from pymatgen import MPRester # now "from pymatgen.ext.matproj ..."
Your coding agent can read these notes before it upgrades. Set up the MCP server →