pymatgen-analysis-alloys Library

Common errors

• ModuleNotFoundError: No module named 'pymatgen_analysis_alloys'

  cause The `pymatgen-analysis-alloys` library has not been installed in your Python environment.
  fix Install the library using pip: `pip install pymatgen-analysis-alloys`

• ImportError: cannot import name 'DisorderedComposition' from 'pymatgen_analysis_alloys'

  cause The specific class `DisorderedComposition` is located within a submodule (`composition`) of the `pymatgen_analysis_alloys` package, not directly under the top-level package.
  fix Use the correct import path: `from pymatgen_analysis_alloys.composition import DisorderedComposition`

• TypeError: 'dict' object is not callable

  cause Attempting to call a dictionary object as if it were a function, commonly occurring when trying to pass arguments to a constructor without using the correct syntax or input type.
  fix Ensure that inputs to constructors like `DisorderedComposition` or `DisorderedStructure` match the expected type (e.g., a dictionary for composition, or specific Pymatgen objects and site definitions for structures).

Warnings

• gotcha Compatibility with `pymatgen` versions is crucial. This library requires `pymatgen>=2022.0.8`. Using an older `pymatgen` version may lead to `ImportError`s, `TypeError`s, or unexpected behavior.
  Fix: Ensure your `pymatgen` installation meets the minimum version requirement: `pip install --upgrade pymatgen`.
• gotcha Objects from `pymatgen-analysis-alloys` (e.g., `DisorderedComposition`, `DisorderedStructure`) are specialized extensions of `pymatgen`'s core objects. While they often inherit similar methods, they may not be fully compatible with all functions expecting a pure `pymatgen.Composition` or `pymatgen.Structure` without explicit handling.
  Fix: Always refer to the specific documentation or source code for `pymatgen-analysis-alloys` objects when integrating them into workflows, especially if passing them to other Pymatgen-based tools.
• gotcha The library primarily focuses on the *description* and representation of disordered systems. While it provides useful data structures, it does not inherently offer advanced simulation or analysis capabilities (e.g., Monte Carlo, DFT calculations) beyond what Pymatgen itself provides, without further integration with other tools.
  Fix: Understand the scope of `pymatgen-analysis-alloys` as a foundational descriptive tool for disordered materials, and plan to integrate it with other computational packages for advanced simulations.

Install

• pip install pymatgen-analysis-alloys Install stable version

Imports

• DisorderedComposition

  from pymatgen_analysis_alloys.composition import DisorderedComposition

• DisorderedStructure
  wrong:

  from pymatgen_analysis_alloys import DisorderedStructure

  correct:

  from pymatgen_analysis_alloys.disordered_systems import DisorderedStructure

  Classes are typically nested in submodules like 'composition' or 'disordered_systems'.

Quickstart

This example demonstrates how to create a `DisorderedComposition` object for an alloy system and access its basic properties. It also shows the distinction between a `DisorderedComposition` and a standard Pymatgen `Composition`.

from pymatgen_analysis_alloys.composition import DisorderedComposition
from pymatgen.core.composition import Composition

# Create a simple disordered composition, e.g., Cu_0.5 Ni_0.5
disordered_comp = DisorderedComposition({"Cu": 0.5, "Ni": 0.5})

print(f"Disordered composition: {disordered_comp}")
print(f"Formula: {disordered_comp.reduced_formula}")

# Compare with a standard pymatgen Composition
standard_comp = Composition({"Cu": 0.5, "Ni": 0.5})
print(f"Standard composition: {standard_comp}")

# Accessing properties
print(f"Atomic fractions: {disordered_comp.as_dict()}")