# pymatgen.io.pwmat package

This package implements modules for input and output to and from PWmat.

## Submodules

## pymatgen.io.pwmat.inputs module

class ACExtractor(file_path: PathLike)

  Bases: `ACExtractorBase`

  Extract information contained in atom.config : number of atoms, lattice, types, frac_coords, magmoms

  Initialization function

  Args

    file_path (str): The absolute path of atom.config file.

  get_coords() → ndarray

    Return the fractional coordinates in structure.

    Returns:

      Fractional coordinates.

    Return type:

      np.ndarray

  get_lattice() → ndarray

    Return the lattice of structure.

    Returns:

      np.ndarray, shape = (9,)

    Return type:

      lattice

  get_magmoms() → ndarray

    Return the magenetic moments of atoms in structure.

    Returns:

      The magnetic moments of individual atoms.

    Return type:

      np.ndarray

  get_n_atoms() → int

    Return the number of atoms in the structure.

  get_types() → ndarray

    Return the atomic number of atoms in structure.

    Returns:

      Atomic numbers in order corresponding to sites

    Return type:

      np.ndarray

class ACExtractorBase

  Bases: `ABC`

  A parent class of ACExtractor and ACstrExtractor, ensuring that they are as consistent as possible

  abstract get_coords() → ndarray

    Get fractional coordinates of atoms in structure defined by atom.config file

  abstract get_lattice() → ndarray

    Get the lattice of structure defined by atom.config file

  abstract get_magmoms() → ndarray

    Get atomic magmoms of atoms in structure defined by atom.config file

  abstract get_n_atoms() → int

    Get the number of atoms in structure defined by atom.config file.

  abstract get_types() → ndarray

    Get atomic number of atoms in structure defined by atom.config file

class ACstrExtractor(atom_config_str: str)

  Bases: `ACExtractorBase`

  Extract information from atom.config file. You can get str by slicing the MOVEMENT.

  Initialization function.

  Parameters:

    atom_config_str (str) – A string describing the structure in atom.config file.

  get_atom_energies() → ndarray | None

    Return the energies of individual atoms in material system.

    Returns:

      The energies of individual atoms within the material system.

    Return type:

      np.ndarray | None

    Description:

      When turn on ENERGY DEPOSITION, PWmat will output energy per atom.

  get_atom_forces() → ndarray

    Return the force on atoms in material system.

    Returns:

      Forces acting on individual atoms of shape=(num_atoms*3,)

    Return type:

      np.ndarray

  get_coords() → ndarray

    Return the fractional coordinate of atoms in structure.

    Returns:

      Fractional coordinates of atoms of shape=(num_atoms*3,)

    Return type:

      np.ndarray

  get_e_tot() → ndarray

    Return the total energy of structure.

    Returns:

      The total energy of the material system.

    Return type:

      np.ndarray

  get_lattice() → ndarray

    Return the lattice of structure.

    Returns:

      Lattice basis vectors of shape=(9,)

    Return type:

      np.ndarray

  get_magmoms() → ndarray

    Return the magnetic moments of atoms in structure.

    Returns:

      Atomic magnetic moments.

    Return type:

      np.ndarray

  get_n_atoms() → int

    Return the number of atoms in structure.

    Returns:

      The number of atoms

    Return type:

      int

  get_types() → ndarray

    Return the atomic number of atoms in structure.

    Returns:

      Types of elements.

    Return type:

      np.ndarray

  get_virial() → ndarray | None

    Return the virial tensor of material system.

    Returns:

      Virial tensor of shape=(9,)

    Return type:

      np.ndarray | None

class AtomConfig(structure: Structure, sort_structure: bool = False)

  Bases: `MSONable`

  Object for representing the data in a atom.config or final.config file.

  Initialization function.

  Parameters:

    - structure (Structure) – Structure object

    - sort_structure (bool, optional) – Whether to sort the structure. Useful if species are not grouped properly together. Defaults to False.

  as_dict()
    Returns:

      dict

  classmethod from_dict(dct: dict) → AtomConfig

    Returns a AtomConfig object from a dictionary.

    Parameters:

      dct – dict containing atom.config data

    Returns:

      AtomConfig object.

  classmethod from_file(filename: PathLike, mag: bool = False) → AtomConfig

    Returns a AtomConfig from a file

    Parameters:

      - filename (PathLike) – File name containing AtomConfig data

      - mag (bool, optional) – Whether to read magnetic moments. Defaults to True.

    Returns:

      AtomConfig object.

  classmethod from_str(data: str, mag: bool = False) → AtomConfig

    Reads a atom.config from a string.

    Parameters:

      - data (str) – string containing atom.config data

      - mag (bool, optional) – Whether to read magnetic moment information.

    Returns:

      AtomConfig object

  get_str() → str

    Return a string describing the structure in atom.config format.

    Returns:

      String representation of atom.config

    Return type:

      str

  write_file(filename: PathLike, **kwargs)

    Writes AtomConfig to a file.

class GenKpt(reciprocal_lattice: ndarray, kpoints: dict[str, ndarray], path: list[list[str]], density: float = 0.01)

  Bases: `MSONable`

  GenKpt object for reading and writing gen.kpt. This file just generate line-mode kpoints.

  Initialization function.

  Parameters:

    - reciprocal_lattice (np.array) – Reciprocal lattice with factor of 2*pi.

    - kpoints (dict[str, np.array]) – Kpoints and their corresponding fractional coordinates.

    - kpath (list[list[str]]) – All kpaths, with each list representing one kpath.

    - density (float) – The density of kpoints mesh with factor of 2*pi.

  static from_structure(structure: Structure, dim: int, density: float = 0.01) → GenKpt

    Obtain a AtomConfig object from Structure object.

    Parameters:

      - strutcure (Structure) – A structure object.

      - dim (int) – The dimension of the material system (2 or 3).

      - density (float) – Kpoints mesh without factor with 2*pi. Program will automatically convert it with 2*pi.

  get_str()

    Returns a string to be written as a gen.kpt file.

  write_file(filename: PathLike)

    Writes gen.kpt to a file.

    Parameters:

      filename (PathLike) – The absolute path of file to be written.

class HighSymmetryPoint(reciprocal_lattice: ndarray, kpts: dict[str, list], path: list[list[str]], density: float)

  Bases: `MSONable`

  HighSymmetryPoint object for reading and writing HIGH_SYMMETRY_POINTS file which generate line-mode kpoints.

  Initialization function.

  Parameters:

    - reciprocal_lattice (np.array) – Reciprocal lattice.

    - kpts (dict[str, list[float]]) – Kpoints and their corresponding fractional coordinates.

    - path (list[list[str]]) – All k-paths, with each list representing one k-path.

    - density (float) – Density of kpoints mesh with factor of 2*pi.

  static from_structure(structure: Structure, dim: int, density: float = 0.01) → HighSymmetryPoint

    Obtain HighSymmetry object from Structure object.

    Parameters:

      - structure (Structure) – A structure object.

      - dim (int) – Dimension of the material system (2 or 3).

      - density (float, optional) – Density of kpoints mesh without factor of 2*pi. Defaults to 0.01. The program will automatically convert it to with factor of 2*pi.

  get_str() → str

    Returns a string describing high symmetry points in HIGH_SYMMETRY_POINTS format.

  write_file(filename: PathLike)

    Write HighSymmetryPoint to a file.

class LineLocator

  Bases: `MSONable`

  Find the line indices (starts from 1) of a certain paragraph of text from the file.

  static locate_all_lines(file_path: PathLike, content: str) → list[int]

    Locate the line in file where a certain paragraph of text is located (return all indices)

    Parameters:

      - file_path (PathLike) – Absolute path to file.

      - content (str) – Certain paragraph of text that needs to be located.

class ListLocator

  Bases: `MSONable`

  Find the element indices (starts from 0) of a certain paragraph of text from the list.

  static locate_all_lines(strs_lst: list[str], content: str) → list[int]

    Locate the elements in list where a certain paragraph of text is located (return all indices)

    Parameters:

      - strs_lst (list[str]) – List of strings.

      - content (str) – Certain paragraph of text that needs to be located.

## pymatgen.io.pwmat.outputs module

class DosSpin(filename: PathLike)

  Bases: `MSONable`

  Extract information of DOS from DOS_SPIN file: - DOS.totalspin, DOS.totalspin_projected - DOS.spinup, DOS.spinup_projected - DOS.spindown, DOS.spindown_projected

  property dos: ndarray

    Returns value of density of state.

  get_partial_dos(part: str) → ndarray

    Get partial dos for give element or orbital.

    Parameters:

      part (str) –

      The name of partial dos. e.g. ‘Energy’, ‘Total’, ‘Cr-3S’, ‘Cr-3P’,

      > ’Cr-4S’, ‘Cr-3D’, ‘I-4D’, ‘I-5S’, ‘I-5P’, ‘Cr-3S’, ‘Cr-3Pz’, ‘Cr-3Px’, ‘Cr-3Py’, ‘Cr-4S’, ‘Cr-3Dz2’,’Cr-3Dxz’, ‘Cr-3Dyz’, ‘Cr-3D(x^2-y^2)’, ‘Cr-3Dxy’, ‘I-4Dz2’, ‘I-4Dxz’, ‘I-4Dyz’, ‘I-4D(x^2-y^2)’, ‘I-4Dxy’, ‘I-5S’, ‘I-5Pz’, ‘I-5Px’, ‘I-5Py’

    Returns:

      np.array

    Return type:

      partial_dos

  property labels: list[str]

    Returns the name of the partial density of states

class Movement(filename: PathLike, ionic_step_skip: int | None = None, ionic_step_offset: int | None = None)

  Bases: `MSONable`

  Parser for data in MOVEMENT which records trajectory during MD.

  Initialization function.

  Parameters:

    - filename (PathLike) – The path of MOVEMENT

    - ionic_step_skip (int | None, optional) – If ionic_step_skip is a number > 1, only every ionic_step_skip ionic steps will be read for structure and energies. This is very useful if you are parsing very large MOVEMENT files. Defaults to None.

    - ionic_step_offset (int | None, optional) – Used together with ionic_step_skip. If set, the first ionic step read will be offset by the amount of ionic_step_offset. Defaults to None.

  property atom_configs: list[Structure]

    Returns AtomConfig object for structures contained in MOVEMENT.

    Returns:

      List of Structure objects for the structure at each ionic step.

    Return type:

      list[Structure]

  property atom_forces: ndarray

    Returns forces on atoms in each structures contained in MOVEMENT.

    Returns:

      The forces on atoms of each ionic step structure,

        with shape of (n_ionic_steps, n_atoms, 3).

    Return type:

      np.ndarray

  property e_atoms: ndarray

    Returns individual energies of atoms in each ionic step structures contained in MOVEMENT.

    Returns:

      The individual energy of atoms in each ionic step structure,

        with shape of (n_ionic_steps, n_atoms).

    Return type:

      np.ndarray

  property e_tots: ndarray

    Returns total energies of each ionic step structures contained in MOVEMENT.

    Returns:

      Total energy of of each ionic step structure,

        with shape of (n_ionic_steps,).

    Return type:

      np.ndarray

  property virials: ndarray

    Returns virial tensor of each ionic step structure contained in MOVEMENT.

    Returns:

      The virial tensor of each ionic step structure,

        with shape of (n_ionic_steps, 3, 3)

    Return type:

      np.ndarray

class OutFermi(filename: PathLike)

  Bases: `MSONable`

  Extract fermi energy (eV) from OUT.FERMI

  Initialization function

  Parameters:

    filename (PathLike) – The absolute path of OUT.FERMI file.

  property e_fermi: float

    Returns the fermi energy level.

    Returns:

      Fermi energy level.

    Return type:

      float

class Report(filename: PathLike)

  Bases: `MSONable`

  Extract information of spin, kpoints, bands, eigenvalues from REPORT file.

  Initialization function.

  Parameters:

    filename (PathLike) – The absolute path of REPORT file.

  property eigenvalues: ndarray

    Returns the eigenvalues.

    Returns:

      The first index represents spin, the second index

        represents kpoint, the third index represents band.

    Return type:

      np.ndarray

  property hsps: dict[str, ndarray]

    Return the high symmetry points.

    Returns:

      The label and fractional coordinate of

        high symmetry points. Return empty dict when task is not line-mode kpath.

    Return type:

      dict[str, np.ndarray]

  property kpoints: ndarray

    Returns the fractional coordinates of kpoints.

  property kpoints_weight: ndarray

    Returns the weight of kpoints.

  property n_bands: int

    Returns the number of bands.

  property n_kpoints: int

    Returns the number of k-points.

  property spin: int

    Return the spin switches.

    Returns:

      Spin switches. 1 represents turn on spin, 2 represents turn down spin.

    Return type:

      int