pymatgen.io.feff package — pymatgen 2026.3.9 documentation

# pymatgen.io.feff package

This package provides the modules to perform FEFF IO.

FEFF: http://feffproject.org/feffproject-feff.html

## Submodules

## pymatgen.io.feff.inputs module

This module defines classes for reading/manipulating/writing the main sections of FEFF input file(feff.inp), namely HEADER, ATOMS, POTENTIAL and the program control tags.

XANES and EXAFS input files, are available, for non-spin case at this time.

class Atoms(struct, absorbing_atom, radius)

  Bases: `MSONable`

  Atomic cluster centered around the absorbing atom.

  Parameters:

    - struct (Structure) – input structure

    - absorbing_atom (str | int) – Symbol for absorbing atom or site index

    - radius (float) – radius of the atom cluster in Angstroms.

  static atoms_string_from_file(filename)

    Reads atomic shells from file such as feff.inp or ATOMS file The lines are arranged as follows:

    x y z ipot Atom Symbol Distance Number

    with distance being the shell radius and ipot an integer identifying the potential used.

    Parameters:

      filename – File name containing atomic coord data.

    Returns:

      Atoms string.

  property cluster

    The atomic cluster as a Molecule object.

  static cluster_from_file(filename)

    Parse the feff input file and return the atomic cluster as a Molecule object.

    Parameters:

      filename (str) – path the feff input file

    Returns:

      the atomic cluster as Molecule object. The absorbing atom

        is the one at the origin.

    Return type:

      Molecule

  get_lines() → list[list[str | int]]

    Get a list of string representations of the atomic configuration information(x, y, z, ipot, atom_symbol, distance, id).

    Returns:

      lines sorted by the distance from the absorbing atom.

    Return type:

      list[list[str | int]]

  write_file(filename='ATOMS')

    Write Atoms list to file.

    Parameters:

      filename – path for file to be written

exception FeffParseError

  Bases: `ParseError`

  Exception class for Structure. Raised when the structure has problems, e.g. atoms that are too close.

class Header(struct: Structure | Molecule, source: str = '', comment: str = '', spacegroup_analyzer_settings=None)

  Bases: `MSONable`

  Create Header for the FEFF input file.

  Has the following format:

  > - This feff.inp file generated by pymatgen, materialsproject.org

  > TITLE comment: TITLE Source: CoO19128.cif TITLE Structure Summary: (Co2 O2) TITLE Reduced formula: CoO TITLE space group: P1, space number: 1 TITLE abc: 3.297078 3.297078 5.254213 TITLE angles: 90.0 90.0 120.0 TITLE sites: 4 * 1 Co 0.666666 0.333332 0.496324 * 2 Co 0.333333 0.666667 0.996324 * 3 O 0.666666 0.333332 0.878676 * 4 O 0.333333 0.666667 0.378675

  Parameters:

    - struct – Structure or Molecule object. If a Structure, SpaceGroupAnalyzer is used to determine symmetrically-equivalent sites. If a Molecule, there is no symmetry checking.

    - source – User supplied identifier, i.e. for Materials Project this would be the material ID number

    - comment – Comment for first header line

    - spacegroup_analyzer_settings – keyword arguments passed to SpacegroupAnalyzer (only used for Structure inputs).

  property formula

    Formula of structure.

  classmethod from_cif_file(cif_file: str, source: str = '', comment: str = '') → Self

    Create Header object from cif_file.

    Parameters:

      - cif_file – cif_file path and name

      - source – User supplied identifier, i.e. for Materials Project this would be the material ID number

      - comment – User comment that goes in header

    Returns:

      Header Object

  classmethod from_file(filename: str) → Self

    Get Header object from file.

  classmethod from_str(header_str: str) → Self

    Reads Header string and returns Header object if header was generated by pymatgen. Note: Checks to see if generated by pymatgen, if not it is impossible

    > to generate structure object so it is not possible to generate header object and routine ends.

    Parameters:

      header_str – pymatgen generated feff.inp header

    Returns:

      Structure object.

  static header_string_from_file(filename: str = 'feff.inp')

    Reads Header string from either a HEADER file or feff.inp file Will also read a header from a non-pymatgen generated feff.inp file.

    Parameters:

      filename – File name containing the Header data.

    Returns:

      Reads header string.

  property structure_symmetry: tuple[str, int]

    The space group symbol and space number of the structure.

  write_file(filename='HEADER')

    Write Header to file.

    Parameters:

      filename – Filename and path for file to be written to disk

class Paths(atoms, paths, degeneracies=None)

  Bases: `MSONable`

  Set FEFF scattering paths(‘paths.dat’ file used by the ‘genfmt’ module).

  Parameters:

    - atoms (Atoms) – Atoms object

    - paths (list(list)) – list of paths. Each path is a list of atom indices in the atomic cluster(the molecular cluster created by Atoms class). e.g. [[0, 1, 2], [5, 9, 4, 1]] -> 2 paths: one with 3 legs and the other with 4 legs.

    - degeneracies (list) – list of degeneracies, one for each path. Set to 1 if not specified.

  write_file(filename='paths.dat')

    Write paths.dat.

class Potential(struct, absorbing_atom, radius=None)

  Bases: `MSONable`

  FEFF atomic potential.

  Parameters:

    - struct (Structure) – Structure object.

    - absorbing_atom (str | int) – Absorbing atom symbol or site index.

    - radius (float) – radius of the atom cluster in Angstroms.

  static pot_dict_from_str(pot_data)

    Creates atomic symbol/potential number dictionary forward and reverse.

    Parameters:

      pot_data – potential data in string format

    Returns:

      forward and reverse atom symbol and potential number dictionaries.

  static pot_string_from_file(filename='feff.inp')

    Reads Potential parameters from a feff.inp or FEFFPOT file. The lines are arranged as follows:

    > ipot Z element lmax1 lmax2 stoichometry spinph

    Parameters:

      filename – file name containing potential data.

    Returns:

      FEFFPOT string.

  write_file(filename='POTENTIALS')

    Write to file.

    Parameters:

      filename – filename and path to write potential file to.

class Tags(params=None)

  Bases: `dict`

  FEFF control parameters.

  Parameters:

    params – A set of input parameters as a dictionary.

  as_dict()

    Dict representation.

    Returns:

      Dictionary of parameters from fefftags object

  diff(other)

    Diff function. Compares two PARAMETER files and indicates which parameters are the same and which are not. Useful for checking whether two runs were done using the same parameters.

    Parameters:

      other – The other PARAMETER dictionary to compare to.

    Returns:

      has format {“Same”parameters_that_are_the_same,

        ”Different”: parameters_that_are_different} Note that the parameters are return as full dictionaries of values.

    Return type:

      dict[str, dict]

  classmethod from_dict(dct: dict) → Self

    Creates Tags object from a dictionary.

    Parameters:

      dct (dict) – Dict of feff parameters and values.

    Returns:

      Tags object

  classmethod from_file(filename: str = 'feff.inp') → Self

    Creates a Tags dictionary from a PARAMETER or feff.inp file.

    Parameters:

      filename – Filename for either PARAMETER or feff.inp file

    Returns:

      Tags

  get_str(sort_keys: bool = False, pretty: bool = False) → str

    Get a string representation of the Tags. The reason why this method is different from the __str__ method is to provide options for pretty printing.

    Parameters:

      - sort_keys – Set to True to sort the Feff parameters alphabetically. Defaults to False.

      - pretty – Set to True for pretty aligned output. Defaults to False.

    Returns:

      String representation of the Tags.

    Return type:

      str

  static proc_val(key, val)

    Static helper method to convert Feff parameters to proper types, e.g. integers, floats, lists, etc.

    Parameters:

      - key – Feff parameter key

      - val – Actual value of Feff parameter.

  write_file(filename='PARAMETERS')

    Write Tags to a Feff parameter tag file.

    Parameters:

      filename – filename and path to write to.

get_absorbing_atom_symbol_index(absorbing_atom, structure)

  Get the absorbing atom symbol and site index in the given structure.

  Parameters:

    - absorbing_atom (str | int) – symbol or site index

    - structure (Structure)

  Returns:

    symbol and site index

  Return type:

    str, int

get_atom_map(structure, absorbing_atom=None)

  Get a dict that maps each atomic symbol to a unique integer starting from 1.

  Parameters:

    - structure (Structure)

    - absorbing_atom (str) – symbol

  Returns:

    mapping of atomic symbol to integer starting from 1

  Return type:

    dict[str, int]

## pymatgen.io.feff.outputs module

This module defines classes for parsing the FEFF output files.

Currently supports the xmu.dat, ldos.dat output files are for non-spin case.

class Eels(data)

  Bases: `MSONable`

  Parse eels.dat file.

  Parameters:

    data (numpy.ndarray) – data from eels.dat file

  as_dict() → dict

    Get dict representations of Xmu object.

  property atomic_background: ndarray

    The atomic background of EELS.

  property energies

    The energies in eV.

  property fine_structure: ndarray

    The fine structure of EELS.

  classmethod from_file(eels_dat_file: str = 'eels.dat') → Self

    Parse eels spectrum.

    Parameters:

      eels_dat_file (str) – filename and path for eels.dat

    Returns:

      Eels

  property total_spectrum

    The total eels spectrum.

class LDos(complete_dos, charge_transfer)

  Bases: `MSONable`

  Parser for ldos files ldos01, ldos02, …

  Parameters:

    - complete_dos (CompleteDos) – complete dos object

    - charge_transfer (dict) – computed charge transfer between atoms dictionary.

  static charge_transfer_from_file(feff_inp_file, ldos_file)

    Get charge transfer from file.

    Parameters:

      - feff_inp_file (str) – name of feff.inp file for run

      - ldos_file (str) – ldos filename for run, assume consecutive order, i.e., ldos01.dat, ldos02.dat….

    Returns:

      dictionary of dictionaries in order of potential sites ({“p”: 0.154, “s”: 0.078, “d”: 0.0, “tot”: 0.232}, …)

  charge_transfer_to_str()

    Get charge transfer as string.

  classmethod from_file(feff_inp_file: str = 'feff.inp', ldos_file: str = 'ldos') → Self

    Creates LDos object from raw Feff ldos files by by assuming they are numbered consecutively, i.e. ldos01.dat ldos02.dat…

    Parameters:

      - feff_inp_file (str) – input file of run to obtain structure

      - ldos_file (str) – output ldos file of run to obtain dos info, etc.

class Xmu(header, parameters, absorbing_atom, data)

  Bases: `MSONable`

  Parser for data in ‘xmu.dat’ file. The file ‘xmu.dat’ contains XANES, EXAFS or NRIXS data depending on the situation; mu, mu_0, and chi = chi * mu_0 / mu_0 / (edge+50eV) as functions of absolute energy E, relative energy E - E_f and wave number k.

  Default attributes:

    xmu: Photon absorption cross section of absorbing atom in material Energies: Energies of data point relative_energies: E - E_fermi wavenumber: k=sqrt(E -E_fermi) mu: The total absorption cross-section. mu0: The embedded atomic background absorption. chi: fine structure. Edge: Absorption Edge Absorbing atom: Species of absorbing atom Material: Formula of material Source: Source of structure Calculation: Type of Feff calculation performed

  Parameters:

    - header – Header object

    - parameters – Tags object

    - absorbing_atom (str | int) – absorbing atom symbol or index

    - data (numpy.ndarray, Nx6) – cross_sections.

  as_dict()

    Get dict representations of Xmu object.

  property calc

    Type of Feff calculation, XANES or EXAFS.

  property chi

    The normalized fine structure.

  property e_fermi

    The Fermi level in eV.

  property edge

    Excitation edge.

  property energies

    The absolute energies in eV.

  classmethod from_file(xmu_dat_file: str = 'xmu.dat', feff_inp_file: str = 'feff.inp') → Self

    Get Xmu from file.

    Parameters:

      - xmu_dat_file (str) – filename and path for xmu.dat

      - feff_inp_file (str) – filename and path of feff.inp input file

    Returns:

      Xmu object

  property material_formula

    Chemical formula of material from feff.inp file.

  property mu

    The total absorption cross-section.

  property mu0

    The embedded atomic background absorption.

  property relative_energies

    Energy with respect to the Fermi level E - E_f.

  property source

    Source identification from Header file.

  property wavenumber

    Get the wave number in units of AA^-1. k=sqrt(E - E_f) where E is the energy and E_f is the Fermi level computed from electron gas theory at the average interstitial charge density.

## pymatgen.io.feff.sets module

This module defines the FeffInputSet abstract base class and a concrete implementation for the Materials Project. The basic concept behind an input set is to specify a scheme to generate a consistent set of Feff inputs from a structure without further user intervention. This ensures comparability across runs.

class AbstractFeffInputSet

  Bases: `MSONable`, `ABC`

  Abstract base class representing a set of Feff input parameters. The idea is that using a FeffInputSet, a complete set of input files (feffPOT, feffXANES, feffEXAFS, ATOMS, feff.inp)set_ can be generated in an automated fashion for any structure.

  all_input()

    Get all input files as a dict of {filename: feffio object}.

  abstract property atoms

    Get Atoms string from a structure that goes in feff.inp file.

    Returns:

      Atoms object.

  abstractmethod header()

    Get header to be used in feff.inp file from a pymatgen structure.

  abstract property potential

    Get POTENTIAL section used in feff.inp from a structure.

  abstract property tags

    Get standard calculation parameters.

  write_input(output_dir='.', make_dir_if_not_present=True)

    Write a FEFF input set to a directory.

    Parameters:

      - output_dir – Directory to output the FEFF input files

      - make_dir_if_not_present – Set to True if you want the directory ( and the whole path) to be created if it is not present.

class FEFFDictSet(absorbing_atom: str | int, structure: Structure | Molecule, radius: float, config_dict: dict, edge: str = 'K', spectrum: str = 'EXAFS', nkpts=1000, user_tag_settings: dict | None = None, spacegroup_analyzer_settings: dict | None = None)

  Bases: `AbstractFeffInputSet`

  Standard implementation of FeffInputSet, which can be extended by specific implementations.

  Parameters:

    - absorbing_atom (str | int) – absorbing atom symbol or site index

    - structure – Structure or Molecule object. If a Structure, SpaceGroupAnalyzer is used to determine symmetrically-equivalent sites. If a Molecule, there is no symmetry checking.

    - radius (float) – cluster radius

    - config_dict (dict) – control tag settings dict

    - edge (str) – absorption edge

    - spectrum (str) – type of spectrum to calculate, available options : EXAFS, XANES, DANES, XMCD, ELNES, EXELFS, FPRIME, NRIXS, XES. The default is EXAFS.

    - nkpts (int) – Total number of kpoints in the brillouin zone. Used only when feff is run in the reciprocal space mode.

    - user_tag_settings (dict) –

      override default tag settings. To delete tags, set the key ‘_del’ in the user_tag_settings. eg: user_tag_settings={“_del”: [“COREHOLE”, “EXCHANGE”]} To specify a net charge on the structure, pass an “IONS” tag containing a list

      > of tuples where the first element is the unique potential value (ipot value) and the second element is the charge to be applied to atoms associated with that potential, e.g. {“IONS”: [(0, 0.1), (1, 0.1), (2, 0.1)]} will result in.

      > ION 0 0.1 ION 1 0.1 ION 2 0.1

      > being written to the input file.

    - spacegroup_analyzer_settings (dict) – parameters passed to SpacegroupAnalyzer. e.g. {“symprec”: 0.01, “angle_tolerance”: 4}

  property atoms: Atoms

    absorber + the rest.

    Returns:

      Atoms

  classmethod from_directory(input_dir: str) → Self

    Read in a set of FEFF input files from a directory, which is useful when existing FEFF input needs some adjustment.

  header(source: str = '', comment: str = '')

    Creates header string from structure object.

    Parameters:

      - source – Source identifier used to create structure, can be defined however user wants to organize structures, calculations, etc. example would be Materials Project material ID number.

      - comment – comment to include in header

    Returns:

      Header

  property potential: Potential

    FEFF potential.

    Returns:

      Potential

  property tags: Tags

    FEFF job parameters.

    Returns:

      Tags

class MPEELSDictSet(absorbing_atom, structure, edge, spectrum, radius, beam_energy, beam_direction, collection_angle, convergence_angle, config_dict, user_eels_settings=None, nkpts: int = 1000, user_tag_settings: dict | None = None, **kwargs)

  Bases: `FEFFDictSet`

  FeffDictSet for ELNES spectroscopy.

  Parameters:

    - absorbing_atom (str | int) – absorbing atom symbol or site index

    - structure (Structure) – input structure

    - edge (str) – absorption edge

    - spectrum (str) – ELNES or EXELFS

    - radius (float) – cluster radius in Angstroms.

    - beam_energy (float) – Incident beam energy in keV

    - beam_direction (list) – Incident beam direction. If None, the cross section will be averaged.

    - collection_angle (float) – Detector collection angle in mrad.

    - convergence_angle (float) – Beam convergence angle in mrad.

    - user_eels_settings (dict) – override default EELS config. See MPELNESSet.yaml for supported keys.

    - nkpts (int) – Total number of kpoints in the brillouin zone. Used only when feff is run in the reciprocal space mode.

    - user_tag_settings (dict) – override default tag settings

    - **kwargs – Passthrough to FEFFDictSet.

class MPELNESSet(absorbing_atom, structure, edge: str = 'K', radius: float = 10.0, beam_energy: float = 100, beam_direction=None, collection_angle: float = 1, convergence_angle: float = 1, user_eels_settings=None, nkpts: int = 1000, user_tag_settings: dict | None = None, **kwargs)

  Bases: `MPEELSDictSet`

  FeffDictSet for ELNES spectroscopy.

  Parameters:

    - absorbing_atom (str | int) – absorbing atom symbol or site index

    - structure (Structure) – input structure

    - edge (str) – absorption edge

    - radius (float) – cluster radius in Angstroms.

    - beam_energy (float) – Incident beam energy in keV

    - beam_direction (list) – Incident beam direction. If None, the cross section will be averaged.

    - collection_angle (float) – Detector collection angle in mrad.

    - convergence_angle (float) – Beam convergence angle in mrad.

    - user_eels_settings (dict) – override default EELS config. See MPELNESSet.yaml for supported keys.

    - nkpts (int) – Total number of kpoints in the brillouin zone. Used only when feff is run in the reciprocal space mode.

    - user_tag_settings (dict) – override default tag settings

    - **kwargs – Passthrough to FEFFDictSet.

  CONFIG = {'CONTROL': '1 1 1 1 1 1', 'COREHOLE': 'FSR', 'EDGE': 'K', 'ELNES': {'ANGLES': '1 1', 'BEAM_DIRECTION': '0 1 0', 'BEAM_ENERGY': '100 0 1 1', 'ENERGY': '4 0.04 0.1', 'MESH': '50 1', 'POSITION': '0.0 0.0'}, 'EXCHANGE': '0 0.0 0.0 2', 'FMS': '7.5 0', 'LDOS': '-20.0 20.0 0.1', 'PRINT': '1 0 0 0 0 0', 'S02': 0.0, 'SCF': '6.0 0 30 0.2 1'}

class MPEXAFSSet(absorbing_atom, structure, edge: str = 'K', radius: float = 10.0, nkpts: int = 1000, user_tag_settings: dict | None = None, **kwargs)

  Bases: `FEFFDictSet`

  FeffDictSet for EXAFS spectroscopy.

  Parameters:

    - absorbing_atom (str | int) – absorbing atom symbol or site index

    - structure (Structure) – input structure

    - edge (str) – absorption edge

    - radius (float) – cluster radius in Angstroms.

    - nkpts (int) – Total number of kpoints in the brillouin zone. Used only when feff is run in the reciprocal space mode.

    - user_tag_settings (dict) – override default tag settings

    - **kwargs – Passthrough to FEFFDictSet.

  CONFIG = {'CONTROL': '1 1 1 1 1 1', 'COREHOLE': 'FSR', 'EDGE': 'K', 'EXAFS': 20, 'PRINT': '1 0 0 0 0 0', 'RPATH': 10, 'S02': 0.0, 'SCF': '4.5 0 30 .2 1'}

class MPEXELFSSet(absorbing_atom, structure, edge='K', radius: float = 10.0, beam_energy: float = 100, beam_direction=None, collection_angle: float = 1, convergence_angle: float = 1, user_eels_settings=None, nkpts: int = 1000, user_tag_settings: dict | None = None, **kwargs)

  Bases: `MPEELSDictSet`

  FeffDictSet for EXELFS spectroscopy.

  Parameters:

    - absorbing_atom (str | int) – absorbing atom symbol or site index

    - structure (Structure) – input structure

    - edge (str) – absorption edge

    - radius (float) – cluster radius in Angstroms.

    - beam_energy (float) – Incident beam energy in keV

    - beam_direction (list) – Incident beam direction. If None, the cross section will be averaged.

    - collection_angle (float) – Detector collection angle in mrad.

    - convergence_angle (float) – Beam convergence angle in mrad.

    - user_eels_settings (dict) – override default EELS config. See MPEXELFSSet.yaml for supported keys.

    - nkpts (int) – Total number of kpoints in the brillouin zone. Used only when feff is run in the reciprocal space mode.

    - user_tag_settings (dict) – override default tag settings

    - **kwargs – Passthrough to FEFFDictSet.

  CONFIG = {'CONTROL': '1 1 1 1 1 1', 'COREHOLE': 'FSR', 'EDGE': 'K', 'EXCHANGE': '0 0.0 0.0 2', 'EXELFS': {'ANGLES': '1 1', 'BEAM_DIRECTION': '0 1 0', 'BEAM_ENERGY': '100 0 1 1', 'ENERGY': 20, 'MESH': '50 1', 'POSITION': '0.0 0.0'}, 'PRINT': '1 0 0 0 0 0', 'RPATH': 10, 'S02': 0.0, 'SCF': '5.0 0 30 0.2 1'}

class MPXANESSet(absorbing_atom, structure, edge: str = 'K', radius: float = 10.0, nkpts: int = 1000, user_tag_settings: dict | None = None, **kwargs)

  Bases: `FEFFDictSet`

  FeffDictSet for XANES spectroscopy.

  Parameters:

    - absorbing_atom (str | int) – absorbing atom symbol or site index

    - structure (Structure) – input

    - edge (str) – absorption edge

    - radius (float) – cluster radius in Angstroms.

    - nkpts (int) – Total number of kpoints in the brillouin zone. Used only when feff is run in the reciprocal space mode.

    - user_tag_settings (dict) – override default tag settings

    - **kwargs – Passthrough to FEFFDictSet.

  CONFIG = {'CONTROL': '1 1 1 1 1 1', 'COREHOLE': 'FSR', 'EDGE': 'K', 'EXCHANGE': '0 0.0 0.0 2', 'FMS': '7.5 0', 'LDOS': '-30. 15. .1', 'PRINT': '1 0 0 0 0 0', 'S02': 0.0, 'SCF': '4.5 0 30 .2 1', 'XANES': '3.7 .04 .1'}