pymatgen.io.lobster.future package — pymatgen 2026.3.9 documentation

# pymatgen.io.lobster.future package

Modules for input and output to and from LOBSTER.

This package provides classes and utilities for reading and writing LOBSTER input and output files.

class BWDF(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for BWDF.lobster/BWDFCOHP.lobster files.

  centers

    Bond length centers for the distribution.

    Type:

      NDArray

  bwdf

    Bond weighted distribution function.

    Type:

      dict[Literal[1, -1], NDArray]

  bin_width

    Bin width used for computing the distribution by LOBSTER.

    Type:

      float

  Parameters:

    filename (PathLike) – The BWDF file from LOBSTER, typically “BWDF.lobster” or “BWDFCOHP.lobster”.

  classmethod from_dict(d: dict[str, Any]) → Self

    Deserialize object from dictionary produced by as_dict.

    Parameters:

      d (dict[str, Any]) – Dictionary representation of the object.

    Returns:

      Deserialized BWDF object.

    Return type:

      Self

  classmethod get_default_filename() → str

    Get the default filename for the BWDF class.

    Returns:

      Default filename.

    Return type:

      str

  is_cohp: ClassVar[bool] = False
  parse_file() → None

    Parse BWDF.lobster/BWDFCOHP.lobster file.

    Returns:

      None

  process_data_into_bwdf_centers() → None

    Process data into bwdf and centers.

    Returns:

      None

  version_processors = {('0.0', None): <function BWDF.parse_file>}

class BandOverlaps(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for bandOverlaps.lobster files.

  Parses band overlap information produced by LOBSTER and stores it in a structured dictionary keyed by spin. See the `LobsterBandOverlaps` type for details.

  band_overlaps

    “k_points”, “max_deviations”, and “matrices” holding the corresponding data. - “k_points” (list[list[float]]): List of k-point coordinates. - “max_deviations” (list[float]): List of maximal deviations for each k-point. - “matrices” (list[np.ndarray]): List of overlap matrices for each k-point.

    each holding data for each spin channel.

    Type:

      dict[Spin, dict]

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  classmethod from_dict(d: dict[str, Any]) → Self

    Reconstruct a BandOverlaps instance from a dictionary.

    Parameters:

      d (dict[str, Any]) – Dictionary representation of a BandOverlaps instance.

    Returns:

      Reconstructed instance.

    Return type:

      BandOverlaps

  classmethod get_default_filename() → str

    Get the default filename for the BandOverlaps class.

    Returns:

      Default filename.

    Return type:

      str

  has_good_quality_check_occupied_bands(number_occ_bands_spin_up: int, number_occ_bands_spin_down: int | None = None, spin_polarized: bool = False, limit_deviation: float = 0.1) → bool

    Check if deviation from the ideal overlap for occupied bands is acceptable.

    Parameters:

      - number_occ_bands_spin_up (int) – Number of occupied bands for spin up.

      - number_occ_bands_spin_down (int | None) – Number of occupied bands for spin down. Required if spin_polarized is True.

      - spin_polarized (bool) – Whether the calculation is spin-polarized.

      - limit_deviation (float) – Acceptable absolute tolerance for deviations.

    Raises:

      ValueError – If number_occ_bands_spin_down is not specified for spin-polarized calculations.

    Returns:

      True if all occupied-band submatrices are close to identity within the tolerance.

    Return type:

      bool

  has_good_quality_max_deviation(limit_max_deviation: float = 0.1) → bool

    Check if the maxDeviation values are within a given limit.

    Parameters:

      limit_max_deviation (float) – Upper limit for acceptable max_deviation.

    Returns:

      True if all recorded max_deviation values are <= limit_max_deviation.

    Return type:

      bool

  parse_file(spin_numbers: list[int]) → None

    Read all lines of the file and populate self.band_overlaps.

    Parameters:

      spin_numbers (list[int]) – Two integers indicating the spin numbering used in the file (e.g., [0, 1] for legacy or [1, 2] for newer versions).

    Raises:

      ValueError – If no data is found for a key in the bandOverlaps file.

  parse_file_v3_2_legacy() → None

    Parse bandOverlaps.lobster file for LOBSTER versions ≤3.2.

    Uses legacy spin numbering [0, 1] for parsing.

  parse_file_v4_0() → None

    Parse bandOverlaps.lobster file for LOBSTER versions ≥4.0.

    Uses updated spin numbering [1, 2] for parsing.

  version_processors = {('0.0', '3.2'): <function BandOverlaps.parse_file_v3_2_legacy>, ('4.0', None): <function BandOverlaps.parse_file_v4_0>}

class CHARGE(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for CHARGE.lobster and CHARGE.LCFO.lobster files.

  is_lcfo

    Whether the CHARGE file is from LCFO analysis.

    Type:

      bool

  centers

    Atom labels with indices.

    Type:

      list[str]

  mulliken

    Mulliken charges for each atom.

    Type:

      list[float]

  loewdin

    Loewdin charges for each atom.

    Type:

      list[float]

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  charge_regex: ClassVar[str] = '(\\d+)\\s+([a-zA-Z]+)\\s+(\\S+)\\s+(\\S+)'
  classmethod get_default_filename() → str

    Get the default filename for CHARGE files.

    Returns:

      Default filename for the CHARGE file, depending on LCFO mode.

    Return type:

      str

  is_lcfo: ClassVar[bool] = False
  parse_file() → None

    Parse the CHARGE file and extract Mulliken and Loewdin charges.

    Populates the centers, mulliken, and loewdin attributes with data extracted from the file.

    Returns:

      None

  version_processors = {('0.0', None): <function CHARGE.parse_file>}

class CHARGE_LCFO(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `CHARGE`

  Parser for CHARGE.LCFO.lobster files.

  is_lcfo

    Whether the CHARGE file is from LCFO analysis.

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  charge_regex: ClassVar[str] = '(\\d+)\\s+([a-zA-Z]+)\\s+(\\S+)'
  is_lcfo: ClassVar[bool] = True
  version_processors = {('0.0', None): <function CHARGE.parse_file>}

class COBICAR(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `COXXCAR`

  Reader for COBICAR.lobster files.

  coxxcar_type

    Type of COXXCAR file (“COBICAR”).

    Type:

      str

  is_lcfo

    Whether the file is in LCFO format.

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  coxxcar_type: ClassVar[str] = 'COBICAR'
  classmethod get_default_filename() → str

    Return the default filename for COBICAR.

  is_lcfo: ClassVar[bool] = False
  version_processors = {('5.1', None): <function COXXCAR.parse_file>}

class COBICAR_LCFO(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `COBICAR`

  Reader for COBICAR.LCFO.lobster files.

  is_lcfo

    Always True for LCFO format.

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  is_lcfo: ClassVar[bool] = True
  version_processors = {('5.1', None): <function COXXCAR.parse_file>}

class COHPCAR(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `COXXCAR`

  Reader for COHPCAR.lobster files.

  coxxcar_type

    Type of COXXCAR file (“COHPCAR”).

    Type:

      str

  is_lcfo

    Whether the file is in LCFO format.

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  coxxcar_type: ClassVar[str] = 'COHPCAR'
  classmethod get_default_filename() → str

    Return the default filename for COOPCAR.

  is_lcfo: ClassVar[bool] = False
  version_processors = {('5.1', None): <function COXXCAR.parse_file>}

class COHPCAR_LCFO(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `COHPCAR`

  Reader for COHPCAR.LCFO.lobster files.

  is_lcfo

    Always True for LCFO format.

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  is_lcfo: ClassVar[bool] = True
  version_processors = {('5.1', None): <function COXXCAR.parse_file>}

class COOPCAR(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `COXXCAR`

  Reader for COOPCAR.lobster files.

  coxxcar_type

    Type of COXXCAR file (“COOPCAR”).

    Type:

      str

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  coxxcar_type: ClassVar[str] = 'COOPCAR'
  classmethod get_default_filename() → str

    Return the default filename for COOPCAR.

  version_processors = {('5.1', None): <function COXXCAR.parse_file>}

class DOSCAR(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Represents LOBSTER’s projected DOS and local projected DOS.

  This class parses and stores data from the DOSCAR file generated by LOBSTER, which contains information about the total and projected density of states (DOS) for a quantum-chemical calculation performed with VASP.

  completedos

    Complete DOS data.

    Type:

      LobsterCompleteDos

  pdos

    Projected DOS data. Access as pdos[atomindex][‘orbitalstring’][Spin.up/Spin.down].

    Type:

      list[dict[str, dict[Spin, np.ndarray]]]

  tdos

    Total density of states.

    Type:

      Dos

  energies

    Energies at which the DOS was calculated (in eV, relative to Efermi).

    Type:

      np.ndarray

  tdensities

    Total density arrays for each spin channel.

    Type:

      dict[Spin, np.ndarray]

  itdensities

    Integrated total density arrays for each spin channel.

    Type:

      dict[Spin, np.ndarray]

  is_spin_polarized

    Whether the system is spin polarized.

    Type:

      bool

  Initialize a DOSCAR object.

  Parameters:

    - filename (PathLike | None) – Path to the DOSCAR file, typically “DOSCAR.lobster”.

    - process_immediately (bool) – Whether to process the file immediately upon initialization.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

  Raises:

    ValueError – If neither structure_file nor structure is provided.

  property efermi: float

    Fermi energy in eV.

  property energies: NDArray[floating]

    Energies at which the DOS was calculated (in eV, relative to efermi).

  classmethod get_default_filename() → str

    Get the default filename for the DOSCAR.

    Returns:

      Default filename string. “DOSCAR.lobster” for regular DOSCAR, “DOSCAR.LCFO.lobster” for LCFO analysis.

    Return type:

      str

  is_lcfo: ClassVar[bool] = False
  property is_spin_polarized: bool

    Whether the system is spin polarized.

    Returns:

      True if the system is spin polarized, False otherwise.

    Return type:

      bool

  process() → None

    Process the DOSCAR file and extract DOS data.

    Parses the DOSCAR file to extract total DOS, projected DOS, energies, and integrated densities. Sets the appropriate attributes based on whether the calculation is spin-polarized.

    Raises:

      ValueError – If the DOSCAR file format is invalid or spin polarization cannot be determined.

  version_processors = {('0.0', None): <function DOSCAR.process>}

class DOSCAR_LCFO(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `DOSCAR`

  Represents LOBSTER’s projected DOS and local projected DOS for LCFO analysis.

  This class handles DOSCAR files generated from LCFO analysis, which have a different format than regular DOSCAR files.

  is_lcfo

    Class variable indicating this is for LCFO analysis. Always True.

    Type:

      bool

  Initialize a DOSCAR object.

  Parameters:

    - filename (PathLike | None) – Path to the DOSCAR file, typically “DOSCAR.lobster”.

    - process_immediately (bool) – Whether to process the file immediately upon initialization.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

  Raises:

    ValueError – If neither structure_file nor structure is provided.

  is_lcfo: ClassVar[bool] = True
  version_processors = {('0.0', None): <function DOSCAR.process>}

class Fatband(filename: PathLike, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for a single FATBAND_*.lobster file.

  Parses a single FATBAND file and stores:

    center (str): Central atom/species label parsed from filename. orbital (str): Orbital descriptor parsed from filename. nbands (int): Number of bands in the FATBAND file. fatband (LobsterFatband): Parsed fatband data dictionary. Please see `LobsterFatband` for details.

  The parsed data is available in the fatband attribute after parse_file().

  Initialize a Fatband parser.

  Parameters:

    - filename (PathLike) – Path to the FATBAND file to parse.

    - process_immediately (bool) – If True, parse the file during initialization.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  Raises:

    ValueError – If the orbital name cannot be parsed from the filename.

  convert_to_numpy_arrays() → None

    Convert lists in band_overlaps to numpy arrays.

  classmethod from_dict(d: dict[str, Any]) → Self

    Reconstruct a Fatband instance from a dictionary.

    Parameters:

      d (dict[str, Any]) – Dictionary representation of a Fatband instance.

    Returns:

      Reconstructed instance.

    Return type:

      Fatband

  classmethod get_default_filename() → str

    Get the default filename for the Fatband class.

    Returns:

      Default filename pattern.

    Return type:

      str

  parse_file() → None

    Parse the FATBAND file and populate the fatband attribute.

  version_processors = {('0.0', None): <function Fatband.parse_file>}

class Fatbands(directory: PathLike = '.', structure: IStructure | None = None, kpoints_file: PathLike = 'KPOINTS', vasprun_file: PathLike = 'vasprun.xml', process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `MSONable`

  Reader for multiple FATBAND_*.lobster files in a directory.

  Collects FATBAND files, reads VASP outputs for the Fermi level and kpoints, and aggregates per-file parsed data.

  efermi

    Fermi level read from vasprun.xml.

    Type:

      float

  spins

    Spins present in the FATBAND files.

    Type:

      list[Spin]

  kpoints

    Parsed KPOINTS used for the lobster FatBand calculations.

    Type:

      Kpoints

  filenames

    Sorted list of matched filenames.

    Type:

      list[Path]

  structure

    Structure object used for projections.

    Type:

      Structure

  reciprocal_lattice

    Reciprocal lattice of the structure.

    Type:

      Lattice

  lobster_version

    LOBSTER version string used for parsing.

    Type:

      str

  fatbands

    Aggregated parsed fatband data after process() is called.

    Type:

      list[dict]

  Initialize the Fatbands reader.

  Parameters:

    - directory (PathLike) – Path to directory containing FATBAND files.

    - structure (IStructure | None) – Structure object. If None, POSCAR.lobster is read from directory.

    - kpoints_file (PathLike) – Name of the KPOINTS file to be read in the directory.

    - vasprun_file (PathLike) – Name of the vasprun.xml file to be read in the directory.

    - process_immediately (bool) – If True, process FATBAND files immediately after initialization.

    - lobster_version (str | None) – Optional LOBSTER version string. If None, the default LOBSTER_VERSION is used.

  Raises:

    - FileNotFoundError – If required files are missing in the directory.

    - ValueError – If no FATBAND files are found or KPOINTS file lacks weights.

  as_dict() → dict[str, Any]

    Serializes the LobsterFile object to a dictionary. Spin keys in dictionaries are converted to strings for JSON compatibility.

    Returns:

      Dictionary with keys “@module”, “@class”, “@version”, and all attributes of the object.

    Return type:

      dict[str, Any]

  fatbands: list[LobsterFatband]
  property has_spin: bool

    Indicates whether the file could contain spin-polarized data.

    Returns:

      True if this file type supports spin, False otherwise.

    Return type:

      bool

  property is_spin_polarized: bool

    Indicates whether the file contains spin-polarized data.

    Returns:

      True if multiple spins are present, False otherwise.

    Return type:

      bool

  process() → None

    Parse all FATBAND files and aggregate fatband data.

    Raises:

      - ValueError – If the number of kpoints does not match or if there is a mix of spin-polarized and

      - non-spin-polarized files. –

class GROSSPOP(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for GROSSPOP.lobster and GROSSPOP.LCFO.lobster files.

  is_lcfo

    Whether the GROSSPOP file is from LCFO analysis.

    Type:

      bool

  populations

    Population dictionaries for each atom.

    Type:

      LobsterPopulations

  spins

    List of spins present in the file.

    Type:

      list[Spin]

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  classmethod get_default_filename() → str

    Get the default filename for GROSSPOP files.

    Returns:

      Default filename for the GROSSPOP file, depending on LCFO mode.

    Return type:

      str

  is_lcfo: ClassVar[bool] = False
  parse_file() → None

    Parse the GROSSPOP file and extract gross population data.

    Populates the populations attribute with a nested dictionary structure containing Mulliken and Loewdin populations for each atom and orbital.

  version_processors = {('0.0', None): <function GROSSPOP.parse_file>}

class GROSSPOP_LCFO(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `GROSSPOP`

  Parser for GROSSPOP.LCFO.lobster files.

  is_lcfo

    Whether the GROSSPOP file is in LCFO format.

    Type:

      bool

  populations

    Population dictionaries for each atom.

    Type:

      LobsterPopulations

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  is_lcfo: ClassVar[bool] = True
  version_processors = {('0.0', None): <function GROSSPOP.parse_file>}

class ICOBILIST(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `ICOXXLIST`

  Reader for ICOBILIST.lobster files.

  icoxxlist_type

    Type of ICOXXLIST file (“COBI”).

    Type:

      str

  is_lcfo

    Whether the file is in LCFO format.

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  classmethod get_default_filename() → str

    Return the default filename for ICOBILIST.

  icoxxlist_type: ClassVar[str] = 'COBI'
  is_lcfo: ClassVar[bool] = False
  version_processors = {('0.0', '5.1'): <function ICOXXLIST.parse_file_legacy>, ('5.1', None): <function ICOXXLIST.parse_file>}

class ICOBILIST_LCFO(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `ICOBILIST`

  Reader for ICOBILIST.LCFO.lobster files.

  is_lcfo

    Always True for LCFO format.

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  is_lcfo: ClassVar[bool] = True
  version_processors = {('0.0', '5.1'): <function ICOXXLIST.parse_file_legacy>, ('5.1', None): <function ICOXXLIST.parse_file>}

class ICOHPLIST(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `ICOXXLIST`

  Reader for ICOHPLIST.lobster files.

  icoxxlist_type

    Type of ICOXXLIST file (“COHP”).

    Type:

      str

  is_lcfo

    Whether the file is in LCFO format.

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  classmethod get_default_filename() → str

    Return the default filename for ICOHPLIST.

  icoxxlist_type: ClassVar[str] = 'COHP'
  is_lcfo: ClassVar[bool] = False
  version_processors = {('0.0', '5.1'): <function ICOXXLIST.parse_file_legacy>, ('5.1', None): <function ICOXXLIST.parse_file>}

class ICOHPLIST_LCFO(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `ICOHPLIST`

  Reader for ICOHPLIST.LCFO.lobster files.

  is_lcfo

    Always True for LCFO format.

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  is_lcfo: ClassVar[bool] = True
  version_processors = {('0.0', '5.1'): <function ICOXXLIST.parse_file_legacy>, ('5.1', None): <function ICOXXLIST.parse_file>}

class ICOOPLIST(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `ICOXXLIST`

  Reader for ICOOPLIST.lobster files.

  icoxxlist_type

    Type of ICOXXLIST file (“COOP”).

    Type:

      str

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  classmethod get_default_filename() → str

    Return the default filename for ICOOPLIST.

  icoxxlist_type: ClassVar[str] = 'COOP'
  version_processors = {('0.0', '5.1'): <function ICOXXLIST.parse_file_legacy>, ('5.1', None): <function ICOXXLIST.parse_file>}

class ICOXXLIST(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterInteractionsHolder`

  Reader for ICOXX data files (ICOHPLIST, ICOOPLIST, ICOBILIST).

  Parses interaction data from ICOXXLIST files, including spin-resolved values.

  interactions

    List of parsed interactions.

    Type:

      list[LobsterInteractionData]

  spins

    List of spins present in the file.

    Type:

      list[Spin]

  data

    Array of ICOXX values for each interaction and spin.

    Type:

      NDArray[np.floating]

  icoxxlist_type

    Type of ICOXXLIST file (“COHP”, “COOP”, “COBI”).

    Type:

      str

  is_lcfo

    Whether the file is in LCFO format (if applicable).

    Type:

      bool

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  get_data_by_properties(indices: list[int] | None = None, centers: list[str] | None = None, cells: list[list[int]] | None = None, orbitals: list[str] | None = None, length: tuple[float, float] | None = None, spins: list[Literal[1, -1]] | None = None) → NDArray[np.floating]

    Get the data for bonds matching specified properties.

    Parameters:

      - indices (list[int] | None) – Indices of bonds to retrieve.

      - centers (list[str] | None) – Centers of bonds to retrieve.

      - cells (list[list[int]] | None) – Cells of bonds to retrieve.

      - orbitals (list[str] | None) – Orbitals of bonds to retrieve.

      - length (tuple[float, float] | None) – Length range to filter.

      - spins (list[Spin] | None) – Spins to retrieve.

    Returns:

      Array of data for specified bonds.

    Return type:

      NDArray[np.floating]

  icoxxlist_type: ClassVar[str]
  interactions_regex: ClassVar[str] = '(?i)\\s*(\\d+)\\s+(\\S+\\s+\\S+)\\s+(\\d+\\.\\d+)\\s+(\\-?\\d+\\s+\\-?\\d+\\s+\\-?\\d+)?\\s+(\\-?\\d+\\.\\d+)(?:\\s+(\\-?\\d+\\.\\d+))?'
  parse_file() → None

    Parse ICOXXLIST file using modern format (versions ≥5.1).

    Extracts interaction data, including spin-resolved values, and populates the interactions, spins, and data attributes.

    Raises:

      ValueError – If the file contains invalid spin values or cannot parse interaction lines.

  parse_file_legacy() → None

    Parse ICOXXLIST file using legacy format (versions ≤5.1).

    Extracts interaction data, including spin-resolved values, and populates the interactions, spins, and data attributes.

    Raises:

      ValueError – If the file contains invalid spin values or cannot parse interaction lines.

  process_data_into_interactions() → None

    Populate each interaction dict with ‘coxx’ and ‘icoxx’ views.

    Assigns numpy views into self.data for each spin channel.

  version_processors = {('0.0', '5.1'): <function ICOXXLIST.parse_file_legacy>, ('5.1', None): <function ICOXXLIST.parse_file>}

class LobsterIn(settingsdict: dict)

  Bases: `UserDict`, `MSONable`

  Handles and generates lobsterin files for LOBSTER calculations.

  This class provides methods to create, modify, and write lobsterin files, which are input files for the LOBSTER program. It also includes utilities for generating related files such as INCAR, KPOINTS, and POSCAR, and for comparing different lobsterin configurations.

  Reminder: LOBSTER input keywords are not case-sensitive.

  FLOAT_KEYWORDS

    Keywords requiring float values.

    Type:

      ClassVar[dict[str, str]]

  STRING_KEYWORDS

    Keywords requiring string values.

    Type:

      ClassVar[dict[str, str]]

  BOOLEAN_KEYWORDS

    Keywords that are boolean flags.

    Type:

      ClassVar[dict[str, str]]

  LIST_KEYWORDS

    Keywords requiring lists of strings.

    Type:

      ClassVar[dict[str, str]]

  AVAILABLE_KEYWORDS

    All known keywords mapped to their canonical forms.

    Type:

      ClassVar[dict[str, str]]

  Initializes a LobsterIn object with the given settings.

  Parameters:

    settingsdict (dict) – Dictionary of settings to initialize the LobsterIn object.

  Raises:

    KeyError – If there are duplicate keywords (case-insensitive).

  AVAILABLE_KEYWORDS: ClassVar[dict[str, str]] = {'autorotate': 'autoRotate', 'bandwisespilling': 'bandwiseSpilling', 'basisfunctions': 'basisfunctions', 'basisrotation': 'basisRotation', 'basisset': 'basisSet', 'bwdf': 'BWDF', 'bwdfcohp': 'BWDFCOHP', 'cobibetween': 'cobiBetween', 'cohpbetween': 'cohpbetween', 'cohpendenergy': 'COHPendEnergy', 'cohpgenerator': 'cohpGenerator', 'cohpstartenergy': 'COHPstartEnergy', 'cohpsteps': 'COHPSteps', 'createfatband': 'createFatband', 'customstoforatom': 'customSTOforAtom', 'densityofenergy': 'DensityOfEnergy', 'donotignoreexcessivebands': 'doNotIgnoreExcessiveBands', 'donotorthogonalizebasis': 'doNotOrthogonalizeBasis', 'donotuseabsolutespilling': 'doNotUseAbsoluteSpilling', 'ewaldsum': 'EwaldSum', 'forceenergyrange': 'forceEnergyRange', 'forcev1hmatrix': 'forceV1HMatrix', 'gaussiansmearingwidth': 'gaussianSmearingWidth', 'gridbufferforprinting': 'gridBufferForPrinting', 'griddensityforprinting': 'gridDensityForPrinting', 'kpointwisespilling': 'kpointwiseSpilling', 'kspacecohp': 'kSpaceCOHP', 'loadprojectionfromfile': 'loadProjectionFromFile', 'lsodos': 'LSODOS', 'nofftforvisualization': 'noFFTforVisualization', 'nomemorymappedfiles': 'noMemoryMappedFiles', 'onlyreadvasprun.xml': 'onlyReadVasprun.xml', 'printlcaorealspacewavefunction': 'printLCAORealSpaceWavefunction', 'printlmosonatoms': 'printLmosOnAtoms', 'printlmosonatomswriteatomicdensities': 'printLmosOnAtomswriteAtomicDensities', 'printmofeatomwise': 'printMofeAtomWise', 'printmofemoleculewise': 'printMofeMoleculeWise', 'printpawrealspacewavefunction': 'printPAWRealSpaceWavefunction', 'printtotalspilling': 'printTotalSpilling', 'realspacehamiltonian': 'realspaceHamiltonian', 'realspaceoverlap': 'realspaceOverlap', 'rmsp': 'RMSp', 'saveprojectiontofile': 'saveProjectionToFile', 'skipcar': 'skipCar', 'skipcobi': 'skipcobi', 'skipcohp': 'skipcohp', 'skipcoop': 'skipcoop', 'skipdos': 'skipdos', 'skipgrosspopulation': 'skipGrossPopulation', 'skipmadelungenergy': 'skipMadelungEnergy', 'skipmofe': 'skipMOFE', 'skipmolecularorbitals': 'skipMolecularOrbitals', 'skippaworthonormalitytest': 'skipPAWOrthonormalityTest', 'skippopulationanalysis': 'skipPopulationAnalysis', 'skipprojection': 'skipProjection', 'skipreorthonormalization': 'skipReOrthonormalization', 'usedecimalplaces': 'useDecimalPlaces', 'useoriginaltetrahedronmethod': 'useOriginalTetrahedronMethod', 'userecommendedbasisfunctions': 'userecommendedbasisfunctions', 'writeatomicorbitals': 'writeAtomicOrbitals', 'writebasisfunctions': 'writeBasisFunctions', 'writematricestofile': 'writeMatricesToFile'}
  BOOLEAN_KEYWORDS: ClassVar[dict[str, str]] = {'autorotate': 'autoRotate', 'bandwisespilling': 'bandwiseSpilling', 'bwdf': 'BWDF', 'bwdfcohp': 'BWDFCOHP', 'densityofenergy': 'DensityOfEnergy', 'donotignoreexcessivebands': 'doNotIgnoreExcessiveBands', 'donotorthogonalizebasis': 'doNotOrthogonalizeBasis', 'donotuseabsolutespilling': 'doNotUseAbsoluteSpilling', 'forceenergyrange': 'forceEnergyRange', 'forcev1hmatrix': 'forceV1HMatrix', 'kpointwisespilling': 'kpointwiseSpilling', 'loadprojectionfromfile': 'loadProjectionFromFile', 'lsodos': 'LSODOS', 'nofftforvisualization': 'noFFTforVisualization', 'nomemorymappedfiles': 'noMemoryMappedFiles', 'onlyreadvasprun.xml': 'onlyReadVasprun.xml', 'printlmosonatoms': 'printLmosOnAtoms', 'printmofeatomwise': 'printMofeAtomWise', 'printmofemoleculewise': 'printMofeMoleculeWise', 'printtotalspilling': 'printTotalSpilling', 'rmsp': 'RMSp', 'saveprojectiontofile': 'saveProjectionToFile', 'skipcar': 'skipCar', 'skipcobi': 'skipcobi', 'skipcohp': 'skipcohp', 'skipcoop': 'skipcoop', 'skipdos': 'skipdos', 'skipgrosspopulation': 'skipGrossPopulation', 'skipmadelungenergy': 'skipMadelungEnergy', 'skipmofe': 'skipMOFE', 'skipmolecularorbitals': 'skipMolecularOrbitals', 'skippaworthonormalitytest': 'skipPAWOrthonormalityTest', 'skippopulationanalysis': 'skipPopulationAnalysis', 'skipprojection': 'skipProjection', 'skipreorthonormalization': 'skipReOrthonormalization', 'useoriginaltetrahedronmethod': 'useOriginalTetrahedronMethod', 'userecommendedbasisfunctions': 'userecommendedbasisfunctions', 'writeatomicorbitals': 'writeAtomicOrbitals', 'writebasisfunctions': 'writeBasisFunctions', 'writematricestofile': 'writeMatricesToFile'}
  FLOAT_KEYWORDS: ClassVar[dict[str, str]] = {'basisrotation': 'basisRotation', 'cohpendenergy': 'COHPendEnergy', 'cohpstartenergy': 'COHPstartEnergy', 'cohpsteps': 'COHPSteps', 'gaussiansmearingwidth': 'gaussianSmearingWidth', 'gridbufferforprinting': 'gridBufferForPrinting', 'griddensityforprinting': 'gridDensityForPrinting', 'usedecimalplaces': 'useDecimalPlaces'}
  LIST_KEYWORDS: ClassVar[dict[str, str]] = {'basisfunctions': 'basisfunctions', 'cobibetween': 'cobiBetween', 'cohpbetween': 'cohpbetween', 'createfatband': 'createFatband', 'customstoforatom': 'customSTOforAtom', 'printlmosonatomswriteatomicdensities': 'printLmosOnAtomswriteAtomicDensities'}
  STRING_KEYWORDS: ClassVar[dict[str, str]] = {'basisset': 'basisSet', 'cohpgenerator': 'cohpGenerator', 'ewaldsum': 'EwaldSum', 'kspacecohp': 'kSpaceCOHP', 'printlcaorealspacewavefunction': 'printLCAORealSpaceWavefunction', 'printpawrealspacewavefunction': 'printPAWRealSpaceWavefunction', 'realspacehamiltonian': 'realspaceHamiltonian', 'realspaceoverlap': 'realspaceOverlap'}
  as_dict() → dict

    Converts the LobsterIn object to a dictionary.

    Returns:

      A dictionary representation of the LobsterIn object.

    Return type:

      dict

  diff(other: Self) → dict[str, dict[str, Any]]

    Compares two LobsterIn objects and identifies differences.

    Parameters:

      other (LobsterIn) – The other LobsterIn object to compare.

    Returns:

      A dictionary with keys “Same” and “Different”,

        containing the same and differing parameters, respectively.

    Return type:

      dict[str, dict[str, Any]]

  classmethod from_dict(dct: dict) → Self

    Creates a LobsterIn object from a dictionary.

    Parameters:

      dct (dict) – A dictionary representation of a LobsterIn object.

    Returns:

      The created LobsterIn object.

    Return type:

      LobsterIn

  classmethod from_file(lobsterin: PathLike) → Self

    Creates a LobsterIn object from a lobsterin file.

    Parameters:

      lobsterin (PathLike) – Path to the lobsterin file.

    Returns:

      The created LobsterIn object.

    Return type:

      LobsterIn

    Raises:

      - RuntimeError – If the lobsterin file contains no data.

      - ValueError – If invalid keywords are found or if there are duplicate keywords.

  static get_all_possible_basis_functions(structure: Structure | IStructure, potcar_symbols: list[str], address_basis_file_min: PathLike | None = None, address_basis_file_max: PathLike | None = None) → list[dict]
    Parameters:

      - structure – Structure object

      - potcar_symbols – list of the potcar symbols

      - address_basis_file_min – path to file with the minimum required basis by the POTCAR

      - address_basis_file_max – path to file with the largest possible basis of the POTCAR.

    Returns:

      Can be used to create new Lobsterin objects in

        standard_calculations_from_vasp_files as dict_for_basis

    Return type:

      list[dict]

  static get_basis(structure: Structure | IStructure, potcar_symbols: list[str], address_basis_file: PathLike | None = None) → list[str]

    Retrieves basis functions for the given structure and POTCAR symbols.

    Parameters:

      - structure (Structure | IStructure) – The structure object.

      - potcar_symbols (list[str]) – List of POTCAR symbols.

      - address_basis_file (PathLike | None) – Path to the basis file. Defaults to None.

    Returns:

      List of basis functions.

    Return type:

      list[str]

    Raises:

      ValueError – If the POSCAR does not match the POTCAR or if basis information is missing.

  classmethod standard_calculations_from_vasp_files(POSCAR_input: PathLike = 'POSCAR', INCAR_input: PathLike = 'INCAR', POTCAR_input: PathLike | None = None, Vasprun_output: PathLike = 'vasprun.xml', dict_for_basis: dict | None = None, option: str = 'standard') → Self

    Generate lobsterin with standard settings.

    Parameters:

      - POSCAR_input (PathLike) – path to POSCAR

      - INCAR_input (PathLike) – path to INCAR

      - POTCAR_input (PathLike) – path to POTCAR

      - Vasprun_output (PathLike) – path to vasprun.xml

      - dict_for_basis (dict) – can be provided: it should look the following: dict_for_basis={“Fe”:’3p 3d 4s 4f’, “C”: ‘2s 2p’} and will overwrite all settings from POTCAR_input

      - option (str) – ‘standard’ will start a normal LOBSTER run where COHPs, COOPs, DOS, CHARGE etc. will be calculated ‘standard_with_energy_range_from_vasprun’ will start a normal LOBSTER run for entire energy range of VASP static run. vasprun.xml file needs to be in current directory. ‘standard_from_projection’ will start a normal LOBSTER run from a projection ‘standard_with_fatband’ will do a fatband calculation, run over all orbitals ‘onlyprojection’ will only do a projection ‘onlydos’ will only calculate a projected dos ‘onlycohp’ will only calculate cohp ‘onlycoop’ will only calculate coop ‘onlycohpcoop’ will only calculate cohp and coop

    Returns:

      Lobsterin with standard settings

  write_INCAR(incar_input: PathLike = 'INCAR', incar_output: PathLike = 'INCAR.lobster', poscar_input: PathLike = 'POSCAR', isym: Literal[-1, 0] = 0, further_settings: dict | None = None) → None

    Writes a modified INCAR file for LOBSTER calculations.

    Parameters:

      - incar_input (PathLike) – Path to the input INCAR file.

      - incar_output (PathLike) – Path to the output INCAR file.

      - poscar_input (PathLike) – Path to the input POSCAR file.

      - isym (Literal[-1, 0]) – ISYM value to set. Defaults to 0.

      - further_settings (dict | None) – Additional settings to include in the INCAR file.

    Raises:

      ValueError – If isym is not -1 or 0.

  static write_KPOINTS(POSCAR_input: PathLike = 'POSCAR', KPOINTS_output: PathLike = 'KPOINTS.lobster', reciprocal_density: int = 100, isym: Literal[-1, 0] = 0, from_grid: bool = False, input_grid: tuple[int, int, int] = (5, 5, 5), line_mode: bool = True, kpoints_line_density: int = 20, symprec: float = 0.01) → None

    Write a gamma-centered KPOINTS file for LOBSTER.

    Parameters:

      - POSCAR_input (PathLike) – path to POSCAR

      - KPOINTS_output (PathLike) – path to output KPOINTS

      - reciprocal_density (int) – Grid density

      - isym (-1 | 0) – ISYM value.

      - from_grid (bool) – If True KPOINTS will be generated with the help of a grid given in input_grid. Otherwise, they will be generated from the reciprocal_density

      - input_grid (tuple) – grid to generate the KPOINTS file

      - line_mode (bool) – If True, band structure will be generated

      - kpoints_line_density (int) – density of the lines in the band structure

      - symprec (float) – precision to determine symmetry

  static write_POSCAR_with_standard_primitive(POSCAR_input: PathLike = 'POSCAR', POSCAR_output: PathLike = 'POSCAR.lobster', symprec: float = 0.01) → None

    Writes a POSCAR file with the standard primitive cell.

    Parameters:

      - POSCAR_input (PathLike) – Path to the input POSCAR file.

      - POSCAR_output (PathLike) – Path to the output POSCAR file.

      - symprec (float) – Precision for symmetry determination. Defaults to 0.01.

  write_lobsterin(path: PathLike = 'lobsterin', overwritedict: dict | None = None) → None

    Writes the LobsterIn object to a lobsterin file.

    Parameters:

      - path (PathLike) – The output file path. Defaults to “lobsterin”.

      - overwritedict (dict | None) – A dictionary of settings to overwrite before writing.

class LobsterMatrices(filename: PathLike | None = None, matrix_type: str | None = None, efermi: float | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for LOBSTER matrix files.

  matrix_type

    Type of matrix (hamilton, coefficient, transfer, overlap).

    Type:

      str

  centers

    Atom centers.

    Type:

      list[str]

  orbitals

    Orbitals.

    Type:

      list[str]

  matrices

    Matrix data for each k-point and spin.

    Type:

      LobsterMatrixData

  efermi

    Fermi energy (for Hamilton matrices).

    Type:

      float

  Initialize LOBSTER matrices parser.

  Parameters:

    - filename – Path to the matrix file

    - matrix_type – Type of matrix. If None, inferred from filename

    - efermi – Fermi level in eV (required for Hamilton matrices)

    - process_immediately – Whether to parse the file immediately

  as_dict() → dict[str, Any]

    Serialize object to a dictionary.

    Returns:

      Dictionary representation of the object.

    Return type:

      dict[str, Any]

  centers: list[str]
  classmethod from_dict(d: dict[str, Any]) → Self

    Deserialize from dictionary.

  classmethod get_default_filename() → str

    Get the default filename for the LobsterMatrices class.

    Returns:

      Default filename.

    Return type:

      str

  get_matrix_type() → str

    Infer matrix type from filename.

    Returns:

      Matrix type.

    Return type:

      str

  get_onsite_values(center: str | None = None, orbital: str | None = None) → dict | float | floating

    Get onsite values for specific centers/orbitals.

    Parameters:

      - center (str | None) – Specific center or None for all.

      - orbital (str | None) – Specific orbital or None for all.

    Returns:

      Dict of values or single value if both specified.

    Return type:

      dict | float | floating

  matrices: LobsterMatrixData
  matrix_types: ClassVar[set[str]] = {'coefficient', 'hamilton', 'overlap', 'transfer'}
  orbitals: list[str]
  parse_file() → None

    Parse matrix data and set instance attributes.

    Returns:

      None

  version_processors = {('0.0', None): <function LobsterMatrices.parse_file>}

class LobsterOut(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for lobsterout file from LOBSTER.

  This class reads the lobsterout file and extracts information about basis functions, spillings, warnings, timing, and file presence. It supports parsing for different LOBSTER versions and provides attributes to access the parsed data.

  basis_functions

    Basis functions used in the LOBSTER run.

    Type:

      list[str]

  basis_type

    Basis types used in the LOBSTER run.

    Type:

      list[str]

  charge_spilling

    Charge spilling for each spin channel.

    Type:

      list[float]

  dft_program

    DFT program used for the calculation.

    Type:

      str

  elements

    Elements present in the calculation.

    Type:

      list[str]

  has_charge

    Whether CHARGE.lobster is present.

    Type:

      bool

  has_cohpcar

    Whether COHPCAR.lobster and ICOHPLIST.lobster are present.

    Type:

      bool

  has_madelung

    Whether SitePotentials.lobster and MadelungEnergies.lobster are present.

    Type:

      bool

  has_coopcar

    Whether COOPCAR.lobster and ICOOPLIST.lobster are present.

    Type:

      bool

  has_cobicar

    Whether COBICAR.lobster and ICOBILIST.lobster are present.

    Type:

      bool

  has_doscar

    Whether DOSCAR.lobster is present.

    Type:

      bool

  has_doscar_lso

    Whether DOSCAR.LSO.lobster is present.

    Type:

      bool

  has_projection

    Whether projectionData.lobster is present.

    Type:

      bool

  has_bandoverlaps

    Whether bandOverlaps.lobster is present.

    Type:

      bool

  has_density_of_energies

    Whether DensityOfEnergy.lobster is present.

    Type:

      bool

  has_fatbands

    Whether fatband calculation was performed.

    Type:

      bool

  has_grosspopulation

    Whether GROSSPOP.lobster is present.

    Type:

      bool

  has_polarization

    Whether POLARIZATION.lobster is present.

    Type:

      bool

  info_lines

    Additional information on the run.

    Type:

      list[str]

  info_orthonormalization

    Information on orthonormalization.

    Type:

      list[str]

  is_restart_from_projection

    Whether calculation was restarted from a projection file.

    Type:

      bool

  lobster_version

    The LOBSTER version.

    Type:

      str

  number_of_spins

    Number of spins.

    Type:

      int

  number_of_threads

    Number of threads used.

    Type:

      int

  timing

    Timing information.

    Type:

      dict[str, float]

  total_spilling

    Total spilling for each spin channel.

    Type:

      list[float]

  warning_lines

    All warning messages.

    Type:

      list[str]

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  classmethod get_default_filename() → str

    Get the default filename for LobsterOut.

    Returns:

      The default filename.

    Return type:

      str

  static get_lobster_version(lines: list[str]) → str

    Get the LOBSTER version from the lobsterout lines.

    Parameters:

      lines (list[str]) – Lines of the lobsterout file.

    Returns:

      The LOBSTER version.

    Return type:

      str

    Raises:

      RuntimeError – If the version line is not found.

  process() → None

    Parse the lobsterout file and populate attributes.

    This method determines the LOBSTER version and invokes the appropriate version-specific processing method.

    Raises:

      RuntimeError – If the LOBSTER version cannot be determined.

  version_processors = {('0.0', '5.0'): <function LobsterOut._process_legacy>, ('5.1', None): <function LobsterOut._process_v5_1>}

class MadelungEnergies(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for MadelungEnergies.lobster files.

  madelung_energies_mulliken

    Madelung energy (Mulliken).

    Type:

      float

  madelung_energies_loewdin

    Madelung energy (Loewdin).

    Type:

      float

  ewald_splitting

    Ewald splitting parameter.

    Type:

      float

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  classmethod get_default_filename() → str

    Get the default filename for MadelungEnergies.

    Returns:

      Default filename.

    Return type:

      str

  parse_file() → None

    Parse MadelungEnergies.lobster file.

    Extracts the Ewald splitting parameter and Madelung energies.

    Returns:

      None

  version_processors = {('0.0', None): <function MadelungEnergies.parse_file>}

class NcICOBILIST(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterInteractionsHolder`

  Reader for NcICOBILIST.lobster files.

  Parses non-conventional ICOBI interaction data.

  interactions

    List of parsed interactions.

    Type:

      list

  spins

    List of spins present in the file.

    Type:

      list[Spin]

  data

    Array of ICOXX values for each interaction and spin.

    Type:

      NDArray[np.floating]

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  get_data_by_properties(indices: list[int] | None = None, centers: list[str] | None = None, cells: list[list[int]] | None = None, orbitals: list[str] | None = None, length: tuple[float, float] | None = None, spins: list[Literal[1, -1]] | None = None) → NDArray[np.floating]

    Get the data for bonds matching specified properties.

    Parameters:

      - indices (list[int] | None) – Indices of bonds to retrieve.

      - centers (list[str] | None) – Centers of bonds to retrieve.

      - cells (list[list[int]] | None) – Cells of bonds to retrieve.

      - orbitals (list[str] | None) – Orbitals of bonds to retrieve.

      - length (tuple[float, float] | None) – Length range to filter.

      - spins (list[Spin] | None) – Spins to retrieve.

    Returns:

      Array of data for specified bonds.

    Return type:

      NDArray[np.floating]

  classmethod get_default_filename() → str

    Return the default filename for NcICOBILIST.

  interactions_regex: ClassVar[str] = '(?i)([a-z]+\\d*(?:\\_\\d+)?)(?:\\[(\\-?\\d+\\s+\\-?\\d+\\s+\\-?\\d+)\\])?(?:\\[([^]\\s]*)\\])?(?:\\(([^)]*)\\))?'
  parse_file() → None

    Parse the NcICOBILIST file.

    Extracts interaction data, including spin-resolved values, and populates the interactions, spins, and data attributes.

    Raises:

      ValueError – If the file contains invalid spin values or cannot parse interaction lines.

  process_data_into_interactions() → None

    Populate each interaction dict with ‘coxx’ and ‘icoxx’ views.

    Assigns numpy views into self.data for each spin channel.

  version_processors = {('5.1', None): <function NcICOBILIST.parse_file>}

class POLARIZATION(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for POLARIZATION.lobster file.

  rel_mulliken_pol_vector

    Relative Mulliken polarization vector.

    Type:

      dict[str, float]

  rel_loewdin_pol_vector

    Relative Loewdin polarization vector.

    Type:

      dict[str, float]

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  classmethod get_default_filename() → str

    Get the default filename for the Polarization class.

    Returns:

      Default filename.

    Return type:

      str

  parse_file() → None

    Parse POLARIZATION.lobster file.

    Returns:

      None

  version_processors = {('0.0', None): <function POLARIZATION.parse_file>}

class SitePotentials(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for SitePotentials.lobster files.

  centers

    Atom centers.

    Type:

      list[str]

  site_potentials_mulliken

    Mulliken site potentials.

    Type:

      list[float]

  site_potentials_loewdin

    Loewdin site potentials.

    Type:

      list[float]

  madelung_energies_mulliken

    Madelung energy (Mulliken).

    Type:

      float

  madelung_energies_loewdin

    Madelung energy (Loewdin).

    Type:

      float

  ewald_splitting

    Ewald splitting parameter.

    Type:

      float

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  classmethod get_default_filename() → str

    Get the default filename for SitePotentials.

    Returns:

      Default filename.

    Return type:

      str

  parse_file() → None

    Parse SitePotentials.lobster file.

    Extracts site potentials, Madelung energies, and Ewald splitting parameter.

    Returns:

      None

  version_processors = {('0.0', None): <function SitePotentials.parse_file>}

class Wavefunction(filename: PathLike, structure: Structure, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Parser for wave function files from LOBSTER.

  Reads wave function files and creates VolumetricData objects.

  grid

    Grid for the wave function [Nx+1, Ny+1, Nz+1].

    Type:

      tuple[int, int, int]

  points

    Points in real space.

    Type:

      list[tuple[float, float, float]]

  reals

    Real parts of the wave function.

    Type:

      list[float]

  imaginaries

    Imaginary parts of the wave function.

    Type:

      list[float]

  distances

    Distances to the first point in the wave function file.

    Type:

      list[float]

  structure

    Structure object associated with the calculation.

    Type:

      Structure

  Initialize the Wavefunction parser.

  Parameters:

    - filename (PathLike) – The wavecar file from LOBSTER.

    - structure (Structure) – The Structure object.

    - process_immediately (bool) – Whether to parse the file immediately. Defaults to True.

  classmethod from_dict(d: dict[str, Any]) → Self
  get_volumetricdata_density() → VolumetricData

    Get VolumetricData object for the density part of the wave function.

    Returns:

      Density volumetric data.

    Return type:

      VolumetricData

  get_volumetricdata_imaginary() → VolumetricData

    Get VolumetricData object for the imaginary part of the wave function.

    Returns:

      Imaginary part volumetric data.

    Return type:

      VolumetricData

  get_volumetricdata_real() → VolumetricData

    Get VolumetricData object for the real part of the wave function.

    Returns:

      Real part volumetric data.

    Return type:

      VolumetricData

  parse_file() → None

    Parse wave function file.

    Reads the wave function file and extracts grid, points, real and imaginary parts, and distances.

    Raises:

      ValueError – If the number of real or imaginary parts does not match the expected grid size.

  set_volumetric_data(grid: tuple[int, int, int], structure: Structure) → None

    Create VolumetricData instances for real, imaginary, and density parts.

    Parameters:

      - grid (tuple[int, int, int]) – Grid on which wavefunction was calculated.

      - structure (Structure) – Structure object.

    Raises:

      ValueError – If the wavefunction file does not contain all relevant points.

  version_processors = {('0.0', None): <function Wavefunction.parse_file>}
  write_file(filename: PathLike = 'WAVECAR.vasp', part: Literal['real', 'imaginary', 'density'] = 'real') → None

    Save the wave function in a file readable by VESTA.

    Parameters:

      - filename (PathLike) – Output file name. Defaults to “WAVECAR.vasp”.

      - part (Literal["real", "imaginary", "density"]) – Which part to save. Defaults to “real”.

    Raises:

      ValueError – If the specified part is not “real”, “imaginary”, or “density”.

## Subpackages

- pymatgen.io.lobster.future.outputs package
  - `BWDF`
    - `BWDF.centers`
    - `BWDF.bwdf`
    - `BWDF.bin_width`
    - `BWDF.from_dict()`
    - `BWDF.get_default_filename()`
    - `BWDF.is_cohp`
    - `BWDF.parse_file()`
    - `BWDF.process_data_into_bwdf_centers()`
    - `BWDF.version_processors`
  - `BWDFCOHP`
    - `BWDFCOHP.get_default_filename()`
    - `BWDFCOHP.version_processors`
  - `BandOverlaps`
    - `BandOverlaps.band_overlaps`
    - `BandOverlaps.from_dict()`
    - `BandOverlaps.get_default_filename()`
    - `BandOverlaps.has_good_quality_check_occupied_bands()`
    - `BandOverlaps.has_good_quality_max_deviation()`
    - `BandOverlaps.parse_file()`
    - `BandOverlaps.parse_file_v3_2_legacy()`
    - `BandOverlaps.parse_file_v4_0()`
    - `BandOverlaps.version_processors`
  - `CHARGE`
    - `CHARGE.is_lcfo`
    - `CHARGE.centers`
    - `CHARGE.mulliken`
    - `CHARGE.loewdin`
    - `CHARGE.charge_regex`
    - `CHARGE.get_default_filename()`
    - `CHARGE.is_lcfo`
    - `CHARGE.parse_file()`
    - `CHARGE.version_processors`
  - `CHARGE_LCFO`
    - `CHARGE_LCFO.is_lcfo`
    - `CHARGE_LCFO.charge_regex`
    - `CHARGE_LCFO.is_lcfo`
    - `CHARGE_LCFO.version_processors`
  - `COBICAR`
    - `COBICAR.coxxcar_type`
    - `COBICAR.is_lcfo`
    - `COBICAR.coxxcar_type`
    - `COBICAR.get_default_filename()`
    - `COBICAR.is_lcfo`
    - `COBICAR.version_processors`
  - `COBICAR_LCFO`
    - `COBICAR_LCFO.is_lcfo`
    - `COBICAR_LCFO.is_lcfo`
    - `COBICAR_LCFO.version_processors`
  - `COHPCAR`
    - `COHPCAR.coxxcar_type`
    - `COHPCAR.is_lcfo`
    - `COHPCAR.coxxcar_type`
    - `COHPCAR.get_default_filename()`
    - `COHPCAR.is_lcfo`
    - `COHPCAR.version_processors`
  - `COHPCAR_LCFO`
    - `COHPCAR_LCFO.is_lcfo`
    - `COHPCAR_LCFO.is_lcfo`
    - `COHPCAR_LCFO.version_processors`
  - `COOPCAR`
    - `COOPCAR.coxxcar_type`
    - `COOPCAR.coxxcar_type`
    - `COOPCAR.get_default_filename()`
    - `COOPCAR.version_processors`
  - `COXXCAR`
    - `COXXCAR.filename`
    - `COXXCAR.num_bonds`
    - `COXXCAR.num_data`
    - `COXXCAR.efermi`
    - `COXXCAR.spins`
    - `COXXCAR.interactions`
    - `COXXCAR.data`
    - `COXXCAR.coxxcar_type`
    - `COXXCAR.energies`
    - `COXXCAR.get_data_by_properties()`
    - `COXXCAR.get_data_indices_by_properties()`
    - `COXXCAR.interaction_indices_to_data_indices_mapping()`
    - `COXXCAR.interactions_regex`
    - `COXXCAR.parse_bonds()`
    - `COXXCAR.parse_data()`
    - `COXXCAR.parse_file()`
    - `COXXCAR.parse_header()`
    - `COXXCAR.process_data_into_interactions()`
    - `COXXCAR.version_processors`
  - `DOSCAR`
    - `DOSCAR.completedos`
    - `DOSCAR.pdos`
    - `DOSCAR.tdos`
    - `DOSCAR.energies`
    - `DOSCAR.tdensities`
    - `DOSCAR.itdensities`
    - `DOSCAR.is_spin_polarized`
    - `DOSCAR.efermi`
    - `DOSCAR.energies`
    - `DOSCAR.get_default_filename()`
    - `DOSCAR.integrated_total_dos`
    - `DOSCAR.is_lcfo`
    - `DOSCAR.is_spin_polarized`
    - `DOSCAR.process()`
    - `DOSCAR.projected_dos`
    - `DOSCAR.total_dos`
    - `DOSCAR.version_processors`
  - `DOSCAR_LCFO`
    - `DOSCAR_LCFO.is_lcfo`
    - `DOSCAR_LCFO.is_lcfo`
    - `DOSCAR_LCFO.version_processors`
  - `Fatband`
    - `Fatband.convert_to_numpy_arrays()`
    - `Fatband.from_dict()`
    - `Fatband.get_default_filename()`
    - `Fatband.parse_file()`
    - `Fatband.version_processors`
  - `Fatbands`
    - `Fatbands.efermi`
    - `Fatbands.spins`
    - `Fatbands.kpoints`
    - `Fatbands.filenames`
    - `Fatbands.structure`
    - `Fatbands.reciprocal_lattice`
    - `Fatbands.lobster_version`
    - `Fatbands.fatbands`
    - `Fatbands.as_dict()`
    - `Fatbands.fatbands`
    - `Fatbands.has_spin`
    - `Fatbands.is_spin_polarized`
    - `Fatbands.process()`
  - `GROSSPOP`
    - `GROSSPOP.is_lcfo`
    - `GROSSPOP.populations`
    - `GROSSPOP.spins`
    - `GROSSPOP.get_default_filename()`
    - `GROSSPOP.is_lcfo`
    - `GROSSPOP.parse_file()`
    - `GROSSPOP.version_processors`
  - `GROSSPOP_LCFO`
    - `GROSSPOP_LCFO.is_lcfo`
    - `GROSSPOP_LCFO.populations`
    - `GROSSPOP_LCFO.is_lcfo`
    - `GROSSPOP_LCFO.version_processors`
  - `ICOBILIST`
    - `ICOBILIST.icoxxlist_type`
    - `ICOBILIST.is_lcfo`
    - `ICOBILIST.get_default_filename()`
    - `ICOBILIST.icoxxlist_type`
    - `ICOBILIST.is_lcfo`
    - `ICOBILIST.version_processors`
  - `ICOBILIST_LCFO`
    - `ICOBILIST_LCFO.is_lcfo`
    - `ICOBILIST_LCFO.is_lcfo`
    - `ICOBILIST_LCFO.version_processors`
  - `ICOHPLIST`
    - `ICOHPLIST.icoxxlist_type`
    - `ICOHPLIST.is_lcfo`
    - `ICOHPLIST.get_default_filename()`
    - `ICOHPLIST.icoxxlist_type`
    - `ICOHPLIST.is_lcfo`
    - `ICOHPLIST.version_processors`
  - `ICOHPLIST_LCFO`
    - `ICOHPLIST_LCFO.is_lcfo`
    - `ICOHPLIST_LCFO.is_lcfo`
    - `ICOHPLIST_LCFO.version_processors`
  - `ICOOPLIST`
    - `ICOOPLIST.icoxxlist_type`
    - `ICOOPLIST.get_default_filename()`
    - `ICOOPLIST.icoxxlist_type`
    - `ICOOPLIST.version_processors`
  - `ICOXXLIST`
    - `ICOXXLIST.interactions`
    - `ICOXXLIST.spins`
    - `ICOXXLIST.data`
    - `ICOXXLIST.icoxxlist_type`
    - `ICOXXLIST.is_lcfo`
    - `ICOXXLIST.get_data_by_properties()`
    - `ICOXXLIST.icoxxlist_type`
    - `ICOXXLIST.interactions_regex`
    - `ICOXXLIST.parse_file()`
    - `ICOXXLIST.parse_file_legacy()`
    - `ICOXXLIST.process_data_into_interactions()`
    - `ICOXXLIST.version_processors`
  - `LobsterMatrices`
    - `LobsterMatrices.matrix_type`
    - `LobsterMatrices.centers`
    - `LobsterMatrices.orbitals`
    - `LobsterMatrices.matrices`
    - `LobsterMatrices.efermi`
    - `LobsterMatrices.as_dict()`
    - `LobsterMatrices.centers`
    - `LobsterMatrices.from_dict()`
    - `LobsterMatrices.get_default_filename()`
    - `LobsterMatrices.get_matrix_type()`
    - `LobsterMatrices.get_onsite_values()`
    - `LobsterMatrices.matrices`
    - `LobsterMatrices.matrix_types`
    - `LobsterMatrices.orbitals`
    - `LobsterMatrices.parse_file()`
    - `LobsterMatrices.version_processors`
  - `LobsterOut`
    - `LobsterOut.basis_functions`
    - `LobsterOut.basis_type`
    - `LobsterOut.charge_spilling`
    - `LobsterOut.dft_program`
    - `LobsterOut.elements`
    - `LobsterOut.has_charge`
    - `LobsterOut.has_cohpcar`
    - `LobsterOut.has_madelung`
    - `LobsterOut.has_coopcar`
    - `LobsterOut.has_cobicar`
    - `LobsterOut.has_doscar`
    - `LobsterOut.has_doscar_lso`
    - `LobsterOut.has_projection`
    - `LobsterOut.has_bandoverlaps`
    - `LobsterOut.has_density_of_energies`
    - `LobsterOut.has_fatbands`
    - `LobsterOut.has_grosspopulation`
    - `LobsterOut.has_polarization`
    - `LobsterOut.info_lines`
    - `LobsterOut.info_orthonormalization`
    - `LobsterOut.is_restart_from_projection`
    - `LobsterOut.lobster_version`
    - `LobsterOut.number_of_spins`
    - `LobsterOut.number_of_threads`
    - `LobsterOut.timing`
    - `LobsterOut.total_spilling`
    - `LobsterOut.warning_lines`
    - `LobsterOut.get_default_filename()`
    - `LobsterOut.get_lobster_version()`
    - `LobsterOut.process()`
    - `LobsterOut.version_processors`
  - `MadelungEnergies`
    - `MadelungEnergies.madelung_energies_mulliken`
    - `MadelungEnergies.madelung_energies_loewdin`
    - `MadelungEnergies.ewald_splitting`
    - `MadelungEnergies.get_default_filename()`
    - `MadelungEnergies.parse_file()`
    - `MadelungEnergies.version_processors`
  - `NcICOBILIST`
    - `NcICOBILIST.interactions`
    - `NcICOBILIST.spins`
    - `NcICOBILIST.data`
    - `NcICOBILIST.get_data_by_properties()`
    - `NcICOBILIST.get_default_filename()`
    - `NcICOBILIST.interactions_regex`
    - `NcICOBILIST.parse_file()`
    - `NcICOBILIST.process_data_into_interactions()`
    - `NcICOBILIST.version_processors`
  - `POLARIZATION`
    - `POLARIZATION.rel_mulliken_pol_vector`
    - `POLARIZATION.rel_loewdin_pol_vector`
    - `POLARIZATION.get_default_filename()`
    - `POLARIZATION.parse_file()`
    - `POLARIZATION.version_processors`
  - `SitePotentials`
    - `SitePotentials.centers`
    - `SitePotentials.site_potentials_mulliken`
    - `SitePotentials.site_potentials_loewdin`
    - `SitePotentials.madelung_energies_mulliken`
    - `SitePotentials.madelung_energies_loewdin`
    - `SitePotentials.ewald_splitting`
    - `SitePotentials.get_default_filename()`
    - `SitePotentials.parse_file()`
    - `SitePotentials.version_processors`
  - `Wavefunction`
    - `Wavefunction.grid`
    - `Wavefunction.points`
    - `Wavefunction.reals`
    - `Wavefunction.imaginaries`
    - `Wavefunction.distances`
    - `Wavefunction.structure`
    - `Wavefunction.from_dict()`
    - `Wavefunction.get_volumetricdata_density()`
    - `Wavefunction.get_volumetricdata_imaginary()`
    - `Wavefunction.get_volumetricdata_real()`
    - `Wavefunction.parse_file()`
    - `Wavefunction.set_volumetric_data()`
    - `Wavefunction.version_processors`
    - `Wavefunction.write_file()`
  - Submodules
  - pymatgen.io.lobster.future.outputs.bands module
    - `BandOverlaps`
      - `BandOverlaps.band_overlaps`
      - `BandOverlaps.from_dict()`
      - `BandOverlaps.get_default_filename()`
      - `BandOverlaps.has_good_quality_check_occupied_bands()`
      - `BandOverlaps.has_good_quality_max_deviation()`
      - `BandOverlaps.parse_file()`
      - `BandOverlaps.parse_file_v3_2_legacy()`
      - `BandOverlaps.parse_file_v4_0()`
      - `BandOverlaps.version_processors`
    - `Fatband`
      - `Fatband.convert_to_numpy_arrays()`
      - `Fatband.from_dict()`
      - `Fatband.get_default_filename()`
      - `Fatband.parse_file()`
      - `Fatband.version_processors`
    - `Fatbands`
      - `Fatbands.efermi`
      - `Fatbands.spins`
      - `Fatbands.kpoints`
      - `Fatbands.filenames`
      - `Fatbands.structure`
      - `Fatbands.reciprocal_lattice`
      - `Fatbands.lobster_version`
      - `Fatbands.fatbands`
      - `Fatbands.as_dict()`
      - `Fatbands.fatbands`
      - `Fatbands.has_spin`
      - `Fatbands.is_spin_polarized`
      - `Fatbands.process()`
  - pymatgen.io.lobster.future.outputs.coxxcar module
    - `COBICAR`
      - `COBICAR.coxxcar_type`
      - `COBICAR.is_lcfo`
      - `COBICAR.coxxcar_type`
      - `COBICAR.get_default_filename()`
      - `COBICAR.is_lcfo`
      - `COBICAR.version_processors`
    - `COBICAR_LCFO`
      - `COBICAR_LCFO.is_lcfo`
      - `COBICAR_LCFO.is_lcfo`
      - `COBICAR_LCFO.version_processors`
    - `COHPCAR`
      - `COHPCAR.coxxcar_type`
      - `COHPCAR.is_lcfo`
      - `COHPCAR.coxxcar_type`
      - `COHPCAR.get_default_filename()`
      - `COHPCAR.is_lcfo`
      - `COHPCAR.version_processors`
    - `COHPCAR_LCFO`
      - `COHPCAR_LCFO.is_lcfo`
      - `COHPCAR_LCFO.is_lcfo`
      - `COHPCAR_LCFO.version_processors`
    - `COOPCAR`
      - `COOPCAR.coxxcar_type`
      - `COOPCAR.coxxcar_type`
      - `COOPCAR.get_default_filename()`
      - `COOPCAR.version_processors`
    - `COXXCAR`
      - `COXXCAR.filename`
      - `COXXCAR.num_bonds`
      - `COXXCAR.num_data`
      - `COXXCAR.efermi`
      - `COXXCAR.spins`
      - `COXXCAR.interactions`
      - `COXXCAR.data`
      - `COXXCAR.coxxcar_type`
      - `COXXCAR.energies`
      - `COXXCAR.get_data_by_properties()`
      - `COXXCAR.get_data_indices_by_properties()`
      - `COXXCAR.interaction_indices_to_data_indices_mapping()`
      - `COXXCAR.interactions_regex`
      - `COXXCAR.parse_bonds()`
      - `COXXCAR.parse_data()`
      - `COXXCAR.parse_file()`
      - `COXXCAR.parse_header()`
      - `COXXCAR.process_data_into_interactions()`
      - `COXXCAR.version_processors`
  - pymatgen.io.lobster.future.outputs.doscar module
    - `DOSCAR`
      - `DOSCAR.completedos`
      - `DOSCAR.pdos`
      - `DOSCAR.tdos`
      - `DOSCAR.energies`
      - `DOSCAR.tdensities`
      - `DOSCAR.itdensities`
      - `DOSCAR.is_spin_polarized`
      - `DOSCAR.efermi`
      - `DOSCAR.energies`
      - `DOSCAR.get_default_filename()`
      - `DOSCAR.integrated_total_dos`
      - `DOSCAR.is_lcfo`
      - `DOSCAR.is_spin_polarized`
      - `DOSCAR.process()`
      - `DOSCAR.projected_dos`
      - `DOSCAR.total_dos`
      - `DOSCAR.version_processors`
    - `DOSCAR_LCFO`
      - `DOSCAR_LCFO.is_lcfo`
      - `DOSCAR_LCFO.is_lcfo`
      - `DOSCAR_LCFO.version_processors`
  - pymatgen.io.lobster.future.outputs.icoxxlist module
    - `ICOBILIST`
      - `ICOBILIST.icoxxlist_type`
      - `ICOBILIST.is_lcfo`
      - `ICOBILIST.get_default_filename()`
      - `ICOBILIST.icoxxlist_type`
      - `ICOBILIST.is_lcfo`
      - `ICOBILIST.version_processors`
    - `ICOBILIST_LCFO`
      - `ICOBILIST_LCFO.is_lcfo`
      - `ICOBILIST_LCFO.is_lcfo`
      - `ICOBILIST_LCFO.version_processors`
    - `ICOHPLIST`
      - `ICOHPLIST.icoxxlist_type`
      - `ICOHPLIST.is_lcfo`
      - `ICOHPLIST.get_default_filename()`
      - `ICOHPLIST.icoxxlist_type`
      - `ICOHPLIST.is_lcfo`
      - `ICOHPLIST.version_processors`
    - `ICOHPLIST_LCFO`
      - `ICOHPLIST_LCFO.is_lcfo`
      - `ICOHPLIST_LCFO.is_lcfo`
      - `ICOHPLIST_LCFO.version_processors`
    - `ICOOPLIST`
      - `ICOOPLIST.icoxxlist_type`
      - `ICOOPLIST.get_default_filename()`
      - `ICOOPLIST.icoxxlist_type`
      - `ICOOPLIST.version_processors`
    - `ICOXXLIST`
      - `ICOXXLIST.interactions`
      - `ICOXXLIST.spins`
      - `ICOXXLIST.data`
      - `ICOXXLIST.icoxxlist_type`
      - `ICOXXLIST.is_lcfo`
      - `ICOXXLIST.get_data_by_properties()`
      - `ICOXXLIST.icoxxlist_type`
      - `ICOXXLIST.interactions_regex`
      - `ICOXXLIST.parse_file()`
      - `ICOXXLIST.parse_file_legacy()`
      - `ICOXXLIST.process_data_into_interactions()`
      - `ICOXXLIST.version_processors`
    - `NcICOBILIST`
      - `NcICOBILIST.interactions`
      - `NcICOBILIST.spins`
      - `NcICOBILIST.data`
      - `NcICOBILIST.get_data_by_properties()`
      - `NcICOBILIST.get_default_filename()`
      - `NcICOBILIST.interactions_regex`
      - `NcICOBILIST.parse_file()`
      - `NcICOBILIST.process_data_into_interactions()`
      - `NcICOBILIST.version_processors`
  - pymatgen.io.lobster.future.outputs.lobsterout module
    - `LobsterOut`
      - `LobsterOut.basis_functions`
      - `LobsterOut.basis_type`
      - `LobsterOut.charge_spilling`
      - `LobsterOut.dft_program`
      - `LobsterOut.elements`
      - `LobsterOut.has_charge`
      - `LobsterOut.has_cohpcar`
      - `LobsterOut.has_madelung`
      - `LobsterOut.has_coopcar`
      - `LobsterOut.has_cobicar`
      - `LobsterOut.has_doscar`
      - `LobsterOut.has_doscar_lso`
      - `LobsterOut.has_projection`
      - `LobsterOut.has_bandoverlaps`
      - `LobsterOut.has_density_of_energies`
      - `LobsterOut.has_fatbands`
      - `LobsterOut.has_grosspopulation`
      - `LobsterOut.has_polarization`
      - `LobsterOut.info_lines`
      - `LobsterOut.info_orthonormalization`
      - `LobsterOut.is_restart_from_projection`
      - `LobsterOut.lobster_version`
      - `LobsterOut.number_of_spins`
      - `LobsterOut.number_of_threads`
      - `LobsterOut.timing`
      - `LobsterOut.total_spilling`
      - `LobsterOut.warning_lines`
      - `LobsterOut.get_default_filename()`
      - `LobsterOut.get_lobster_version()`
      - `LobsterOut.process()`
      - `LobsterOut.version_processors`
  - pymatgen.io.lobster.future.outputs.misc module
    - `BWDF`
      - `BWDF.centers`
      - `BWDF.bwdf`
      - `BWDF.bin_width`
      - `BWDF.from_dict()`
      - `BWDF.get_default_filename()`
      - `BWDF.is_cohp`
      - `BWDF.parse_file()`
      - `BWDF.process_data_into_bwdf_centers()`
      - `BWDF.version_processors`
    - `BWDFCOHP`
      - `BWDFCOHP.get_default_filename()`
      - `BWDFCOHP.version_processors`
    - `LobsterMatrices`
      - `LobsterMatrices.matrix_type`
      - `LobsterMatrices.centers`
      - `LobsterMatrices.orbitals`
      - `LobsterMatrices.matrices`
      - `LobsterMatrices.efermi`
      - `LobsterMatrices.as_dict()`
      - `LobsterMatrices.centers`
      - `LobsterMatrices.from_dict()`
      - `LobsterMatrices.get_default_filename()`
      - `LobsterMatrices.get_matrix_type()`
      - `LobsterMatrices.get_onsite_values()`
      - `LobsterMatrices.matrices`
      - `LobsterMatrices.matrix_types`
      - `LobsterMatrices.orbitals`
      - `LobsterMatrices.parse_file()`
      - `LobsterMatrices.version_processors`
    - `MadelungEnergies`
      - `MadelungEnergies.madelung_energies_mulliken`
      - `MadelungEnergies.madelung_energies_loewdin`
      - `MadelungEnergies.ewald_splitting`
      - `MadelungEnergies.get_default_filename()`
      - `MadelungEnergies.parse_file()`
      - `MadelungEnergies.version_processors`
    - `POLARIZATION`
      - `POLARIZATION.rel_mulliken_pol_vector`
      - `POLARIZATION.rel_loewdin_pol_vector`
      - `POLARIZATION.get_default_filename()`
      - `POLARIZATION.parse_file()`
      - `POLARIZATION.version_processors`
    - `SitePotentials`
      - `SitePotentials.centers`
      - `SitePotentials.site_potentials_mulliken`
      - `SitePotentials.site_potentials_loewdin`
      - `SitePotentials.madelung_energies_mulliken`
      - `SitePotentials.madelung_energies_loewdin`
      - `SitePotentials.ewald_splitting`
      - `SitePotentials.get_default_filename()`
      - `SitePotentials.parse_file()`
      - `SitePotentials.version_processors`
    - `Wavefunction`
      - `Wavefunction.grid`
      - `Wavefunction.points`
      - `Wavefunction.reals`
      - `Wavefunction.imaginaries`
      - `Wavefunction.distances`
      - `Wavefunction.structure`
      - `Wavefunction.from_dict()`
      - `Wavefunction.get_volumetricdata_density()`
      - `Wavefunction.get_volumetricdata_imaginary()`
      - `Wavefunction.get_volumetricdata_real()`
      - `Wavefunction.parse_file()`
      - `Wavefunction.set_volumetric_data()`
      - `Wavefunction.version_processors`
      - `Wavefunction.write_file()`
    - `get_orb_from_str()`
  - pymatgen.io.lobster.future.outputs.populations module
    - `CHARGE`
      - `CHARGE.is_lcfo`
      - `CHARGE.centers`
      - `CHARGE.mulliken`
      - `CHARGE.loewdin`
      - `CHARGE.charge_regex`
      - `CHARGE.get_default_filename()`
      - `CHARGE.is_lcfo`
      - `CHARGE.parse_file()`
      - `CHARGE.version_processors`
    - `CHARGE_LCFO`
      - `CHARGE_LCFO.is_lcfo`
      - `CHARGE_LCFO.charge_regex`
      - `CHARGE_LCFO.is_lcfo`
      - `CHARGE_LCFO.version_processors`
    - `GROSSPOP`
      - `GROSSPOP.is_lcfo`
      - `GROSSPOP.populations`
      - `GROSSPOP.spins`
      - `GROSSPOP.get_default_filename()`
      - `GROSSPOP.is_lcfo`
      - `GROSSPOP.parse_file()`
      - `GROSSPOP.version_processors`
    - `GROSSPOP_LCFO`
      - `GROSSPOP_LCFO.is_lcfo`
      - `GROSSPOP_LCFO.populations`
      - `GROSSPOP_LCFO.is_lcfo`
      - `GROSSPOP_LCFO.version_processors`

## Submodules

## pymatgen.io.lobster.future.constants module

Constants for LOBSTER input and output parsing.

LOBSTER_VERSION: str = '5.1.1'

  A tuple of possible orbitals that LOBSTER can handle and their string representations in LOBSTER output files.

## pymatgen.io.lobster.future.core module

class LobsterFile(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `MSONable`

  Representation of a LOBSTER file.

  This class provides a framework for parsing and processing LOBSTER output files. It supports version-specific processing through a registry of version processors.

  filename

    Name or path of the file. Defaults to the class default.

    Type:

      PathLike

  lobster_version

    Version string parsed from the file or the default LOBSTER_VERSION.

    Type:

      str

  version_processors

    Registry of version processors.

    Type:

      ClassVar[dict[tuple[str, str | None], Callable]]

  spins

    List of Spin objects if the file contains spin-polarized data, else None.

    Type:

      list[Spin] | None

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  as_dict() → dict[str, Any]

    Serializes the LobsterFile object to a dictionary. Spin keys in dictionaries are converted to strings for JSON compatibility.

    Returns:

      Dictionary with keys “@module”, “@class”, “@version”, and all attributes of the object.

    Return type:

      dict[str, Any]

  static check_version(actual: str, minimum: str, maximum: str | None) → bool

    Checks whether a version string falls within a min/max inclusive range.

    Parameters:

      - actual (str) – Version string to check (e.g., “1.2.3”).

      - minimum (str) – Minimum acceptable version string (exclusive).

      - maximum (str | None) – Maximum acceptable version string (exclusive) or None for no upper bound.

    Returns:

      True if actual is > minimum and < maximum (if provided), otherwise False.

    Return type:

      bool

  classmethod from_dict(d: dict[str, Any]) → Self

    Deserializes a LobsterFile object from a dictionary. Spin keys in dictionaries are restored from strings.

    Parameters:

      d (dict[str, Any]) – Dictionary produced by as_dict or similar serialization.

    Returns:

      Instance of LobsterFile with attributes populated from the dictionary.

    Return type:

      LobsterFile

  abstractmethod classmethod get_default_filename() → str

    Returns the default filename for this LobsterFile subclass.

    Returns:

      The default filename.

    Return type:

      str

  get_file_version() → str | None

    Retrieves the file version. Override in subclasses to extract version from file content if possible.

    Returns:

      Version string (e.g., “1.2.3”) if found, else None.

    Return type:

      str | None

  property has_spin: bool

    Indicates whether the file could contain spin-polarized data.

    Returns:

      True if this file type supports spin, False otherwise.

    Return type:

      bool

  property is_spin_polarized: bool

    Indicates whether the file contains spin-polarized data.

    Returns:

      True if multiple spins are present, False otherwise.

    Return type:

      bool

  iterate_lines() → Generator[str]

    Iterates over lines in the file, yielding each line as a string.

    Yields:

      str – Each line in the file, stripped of whitespace.

  property lines: list[str]

    Returns all lines from the file as a list of strings.

    Returns:

      Lines from the file.

    Return type:

      list[str]

    Raises:

      ValueError – If the file is empty.

  process() → None

    Processes the file using the appropriate version processor.

    Selects the best matching version processor from the version_processors registry and invokes it.

    Raises:

      - ValueError – If no processor matches the file version.

      - RuntimeError – If the selected processor raises an exception.

  spins: list[Spin] | None = None
  version_processors: ClassVar[dict[tuple[str, str | None], Callable]]

class LobsterInteractionsHolder(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterFile`

  Container for LOBSTER interaction data. This class holds interaction metadata. It provides methods for filtering and retrieving interaction data based on various criteria.

  interactions

    List of interaction metadata dicts.

    Type:

      list[LobsterInteractionData]

  Initialize a LobsterFile instance.

  Parameters:

    - filename (PathLike | None) – Path to the file. If None, uses the default filename.

    - process_immediately (bool) – Whether to process the file immediately upon initialization. Defaults to True.

    - lobster_version (str | None) – LOBSTER version string to use for parsing. If None, attempts to detect

    - default. (from file or falls back to)

  data: NDArray[np.float64]
  classmethod from_dict(d: dict[str, Any]) → Self

    Deserialize object from dictionary produced by as_dict.

    Parameters:

      d (dict) – Dictionary produced by as_dict.

    Returns:

      Reconstructed instance.

    Return type:

      COXXCAR

  get_interaction_indices_by_properties(indices: list[int] | None = None, centers: list[str] | None = None, cells: list[list[int]] | None = None, orbitals: list[str] | None = None, length: tuple[float, float] | None = None) → list[int]

    Returns indices of interactions that match provided property filters.

    Parameters:

      - indices (list[int] | None) – Optional sequence of interaction indices to match.

      - centers (list[str] | None) – Optional sequence of center name substrings; interaction must contain each

      - times. (orbital substring the required number of)

      - cells (list[list[int]] | None) – Optional sequence of cell vectors to match against interaction cells.

      - orbitals (list[str] | None) – Optional sequence of orbital name substrings; interaction must contain each

      - times.

      - length (tuple[float, float] | None) – Optional (min, max) tuple to filter interactions by length inclusive.

    Returns:

      Sorted list of interaction indices that match all supplied filters. If no filters are supplied, returns an empty list.

    Return type:

      list[int]

  get_interactions_by_properties(indices: list[int] | None = None, centers: list[str] | None = None, cells: list[list[int]] | None = None, orbitals: list[str] | None = None, length: tuple[float, float] | None = None) → list[LobsterInteractionData]

    Return interaction metadata dicts that match the provided filters.

    Parameters:

      - indices (list[int] | None) – Interaction indices to filter.

      - centers (list[str] | None) – Atom centers to filter.

      - cells (list[list[int]] | None) – Unit cell indices to filter.

      - orbitals (list[str] | None) – Orbitals to filter.

      - length (tuple[float, float] | None) – Length range to filter.

    Returns:

      List of interaction dictionaries matching the filters.

    Return type:

      list[dict]

  static get_label_from_interaction(interaction: LobsterInteraction, include_centers: bool = True, include_orbitals: bool = True, include_cells: bool = False, include_length: bool = False) → str

    Generates a label string for a given interaction.

    Parameters:

      interaction (LobsterInteraction) – Interaction metadata dictionary.

    Returns:

      Formatted label string representing the interaction.

    Return type:

      str

  interactions: list[LobsterInteractionData]
  abstractmethod process_data_into_interactions() → None

    Abstract method to process raw data into structured interaction metadata. Must be implemented by subclasses. This method should populate the interactions attribute based on the raw data and any other relevant attributes. The exact processing logic will depend on the specific format and content of the data in the subclass.

  version_processors = {}

## pymatgen.io.lobster.future.inputs module

Module for reading LOBSTER input files. For more information on LOBSTER see www.cohp.de.

If you use this module, please cite: J. George, G. Petretto, A. Naik, M. Esters, A. J. Jackson, R. Nelson, R. Dronskowski, G.-M. Rignanese, G. Hautier, “Automated Bonding Analysis with Crystal Orbital Hamilton Populations”, ChemPlusChem 2022, e202200123, DOI: 10.1002/cplu.202200123.

class LobsterIn(settingsdict: dict)

  Bases: `UserDict`, `MSONable`

  Handles and generates lobsterin files for LOBSTER calculations.

  This class provides methods to create, modify, and write lobsterin files, which are input files for the LOBSTER program. It also includes utilities for generating related files such as INCAR, KPOINTS, and POSCAR, and for comparing different lobsterin configurations.

  Reminder: LOBSTER input keywords are not case-sensitive.

  FLOAT_KEYWORDS

    Keywords requiring float values.

    Type:

      ClassVar[dict[str, str]]

  STRING_KEYWORDS

    Keywords requiring string values.

    Type:

      ClassVar[dict[str, str]]

  BOOLEAN_KEYWORDS

    Keywords that are boolean flags.

    Type:

      ClassVar[dict[str, str]]

  LIST_KEYWORDS

    Keywords requiring lists of strings.

    Type:

      ClassVar[dict[str, str]]

  AVAILABLE_KEYWORDS

    All known keywords mapped to their canonical forms.

    Type:

      ClassVar[dict[str, str]]

  Initializes a LobsterIn object with the given settings.

  Parameters:

    settingsdict (dict) – Dictionary of settings to initialize the LobsterIn object.

  Raises:

    KeyError – If there are duplicate keywords (case-insensitive).

  AVAILABLE_KEYWORDS: ClassVar[dict[str, str]] = {'autorotate': 'autoRotate', 'bandwisespilling': 'bandwiseSpilling', 'basisfunctions': 'basisfunctions', 'basisrotation': 'basisRotation', 'basisset': 'basisSet', 'bwdf': 'BWDF', 'bwdfcohp': 'BWDFCOHP', 'cobibetween': 'cobiBetween', 'cohpbetween': 'cohpbetween', 'cohpendenergy': 'COHPendEnergy', 'cohpgenerator': 'cohpGenerator', 'cohpstartenergy': 'COHPstartEnergy', 'cohpsteps': 'COHPSteps', 'createfatband': 'createFatband', 'customstoforatom': 'customSTOforAtom', 'densityofenergy': 'DensityOfEnergy', 'donotignoreexcessivebands': 'doNotIgnoreExcessiveBands', 'donotorthogonalizebasis': 'doNotOrthogonalizeBasis', 'donotuseabsolutespilling': 'doNotUseAbsoluteSpilling', 'ewaldsum': 'EwaldSum', 'forceenergyrange': 'forceEnergyRange', 'forcev1hmatrix': 'forceV1HMatrix', 'gaussiansmearingwidth': 'gaussianSmearingWidth', 'gridbufferforprinting': 'gridBufferForPrinting', 'griddensityforprinting': 'gridDensityForPrinting', 'kpointwisespilling': 'kpointwiseSpilling', 'kspacecohp': 'kSpaceCOHP', 'loadprojectionfromfile': 'loadProjectionFromFile', 'lsodos': 'LSODOS', 'nofftforvisualization': 'noFFTforVisualization', 'nomemorymappedfiles': 'noMemoryMappedFiles', 'onlyreadvasprun.xml': 'onlyReadVasprun.xml', 'printlcaorealspacewavefunction': 'printLCAORealSpaceWavefunction', 'printlmosonatoms': 'printLmosOnAtoms', 'printlmosonatomswriteatomicdensities': 'printLmosOnAtomswriteAtomicDensities', 'printmofeatomwise': 'printMofeAtomWise', 'printmofemoleculewise': 'printMofeMoleculeWise', 'printpawrealspacewavefunction': 'printPAWRealSpaceWavefunction', 'printtotalspilling': 'printTotalSpilling', 'realspacehamiltonian': 'realspaceHamiltonian', 'realspaceoverlap': 'realspaceOverlap', 'rmsp': 'RMSp', 'saveprojectiontofile': 'saveProjectionToFile', 'skipcar': 'skipCar', 'skipcobi': 'skipcobi', 'skipcohp': 'skipcohp', 'skipcoop': 'skipcoop', 'skipdos': 'skipdos', 'skipgrosspopulation': 'skipGrossPopulation', 'skipmadelungenergy': 'skipMadelungEnergy', 'skipmofe': 'skipMOFE', 'skipmolecularorbitals': 'skipMolecularOrbitals', 'skippaworthonormalitytest': 'skipPAWOrthonormalityTest', 'skippopulationanalysis': 'skipPopulationAnalysis', 'skipprojection': 'skipProjection', 'skipreorthonormalization': 'skipReOrthonormalization', 'usedecimalplaces': 'useDecimalPlaces', 'useoriginaltetrahedronmethod': 'useOriginalTetrahedronMethod', 'userecommendedbasisfunctions': 'userecommendedbasisfunctions', 'writeatomicorbitals': 'writeAtomicOrbitals', 'writebasisfunctions': 'writeBasisFunctions', 'writematricestofile': 'writeMatricesToFile'}
  BOOLEAN_KEYWORDS: ClassVar[dict[str, str]] = {'autorotate': 'autoRotate', 'bandwisespilling': 'bandwiseSpilling', 'bwdf': 'BWDF', 'bwdfcohp': 'BWDFCOHP', 'densityofenergy': 'DensityOfEnergy', 'donotignoreexcessivebands': 'doNotIgnoreExcessiveBands', 'donotorthogonalizebasis': 'doNotOrthogonalizeBasis', 'donotuseabsolutespilling': 'doNotUseAbsoluteSpilling', 'forceenergyrange': 'forceEnergyRange', 'forcev1hmatrix': 'forceV1HMatrix', 'kpointwisespilling': 'kpointwiseSpilling', 'loadprojectionfromfile': 'loadProjectionFromFile', 'lsodos': 'LSODOS', 'nofftforvisualization': 'noFFTforVisualization', 'nomemorymappedfiles': 'noMemoryMappedFiles', 'onlyreadvasprun.xml': 'onlyReadVasprun.xml', 'printlmosonatoms': 'printLmosOnAtoms', 'printmofeatomwise': 'printMofeAtomWise', 'printmofemoleculewise': 'printMofeMoleculeWise', 'printtotalspilling': 'printTotalSpilling', 'rmsp': 'RMSp', 'saveprojectiontofile': 'saveProjectionToFile', 'skipcar': 'skipCar', 'skipcobi': 'skipcobi', 'skipcohp': 'skipcohp', 'skipcoop': 'skipcoop', 'skipdos': 'skipdos', 'skipgrosspopulation': 'skipGrossPopulation', 'skipmadelungenergy': 'skipMadelungEnergy', 'skipmofe': 'skipMOFE', 'skipmolecularorbitals': 'skipMolecularOrbitals', 'skippaworthonormalitytest': 'skipPAWOrthonormalityTest', 'skippopulationanalysis': 'skipPopulationAnalysis', 'skipprojection': 'skipProjection', 'skipreorthonormalization': 'skipReOrthonormalization', 'useoriginaltetrahedronmethod': 'useOriginalTetrahedronMethod', 'userecommendedbasisfunctions': 'userecommendedbasisfunctions', 'writeatomicorbitals': 'writeAtomicOrbitals', 'writebasisfunctions': 'writeBasisFunctions', 'writematricestofile': 'writeMatricesToFile'}
  FLOAT_KEYWORDS: ClassVar[dict[str, str]] = {'basisrotation': 'basisRotation', 'cohpendenergy': 'COHPendEnergy', 'cohpstartenergy': 'COHPstartEnergy', 'cohpsteps': 'COHPSteps', 'gaussiansmearingwidth': 'gaussianSmearingWidth', 'gridbufferforprinting': 'gridBufferForPrinting', 'griddensityforprinting': 'gridDensityForPrinting', 'usedecimalplaces': 'useDecimalPlaces'}
  LIST_KEYWORDS: ClassVar[dict[str, str]] = {'basisfunctions': 'basisfunctions', 'cobibetween': 'cobiBetween', 'cohpbetween': 'cohpbetween', 'createfatband': 'createFatband', 'customstoforatom': 'customSTOforAtom', 'printlmosonatomswriteatomicdensities': 'printLmosOnAtomswriteAtomicDensities'}
  STRING_KEYWORDS: ClassVar[dict[str, str]] = {'basisset': 'basisSet', 'cohpgenerator': 'cohpGenerator', 'ewaldsum': 'EwaldSum', 'kspacecohp': 'kSpaceCOHP', 'printlcaorealspacewavefunction': 'printLCAORealSpaceWavefunction', 'printpawrealspacewavefunction': 'printPAWRealSpaceWavefunction', 'realspacehamiltonian': 'realspaceHamiltonian', 'realspaceoverlap': 'realspaceOverlap'}
  as_dict() → dict

    Converts the LobsterIn object to a dictionary.

    Returns:

      A dictionary representation of the LobsterIn object.

    Return type:

      dict

  diff(other: Self) → dict[str, dict[str, Any]]

    Compares two LobsterIn objects and identifies differences.

    Parameters:

      other (LobsterIn) – The other LobsterIn object to compare.

    Returns:

      A dictionary with keys “Same” and “Different”,

        containing the same and differing parameters, respectively.

    Return type:

      dict[str, dict[str, Any]]

  classmethod from_dict(dct: dict) → Self

    Creates a LobsterIn object from a dictionary.

    Parameters:

      dct (dict) – A dictionary representation of a LobsterIn object.

    Returns:

      The created LobsterIn object.

    Return type:

      LobsterIn

  classmethod from_file(lobsterin: PathLike) → Self

    Creates a LobsterIn object from a lobsterin file.

    Parameters:

      lobsterin (PathLike) – Path to the lobsterin file.

    Returns:

      The created LobsterIn object.

    Return type:

      LobsterIn

    Raises:

      - RuntimeError – If the lobsterin file contains no data.

      - ValueError – If invalid keywords are found or if there are duplicate keywords.

  static get_all_possible_basis_functions(structure: Structure | IStructure, potcar_symbols: list[str], address_basis_file_min: PathLike | None = None, address_basis_file_max: PathLike | None = None) → list[dict]
    Parameters:

      - structure – Structure object

      - potcar_symbols – list of the potcar symbols

      - address_basis_file_min – path to file with the minimum required basis by the POTCAR

      - address_basis_file_max – path to file with the largest possible basis of the POTCAR.

    Returns:

      Can be used to create new Lobsterin objects in

        standard_calculations_from_vasp_files as dict_for_basis

    Return type:

      list[dict]

  static get_basis(structure: Structure | IStructure, potcar_symbols: list[str], address_basis_file: PathLike | None = None) → list[str]

    Retrieves basis functions for the given structure and POTCAR symbols.

    Parameters:

      - structure (Structure | IStructure) – The structure object.

      - potcar_symbols (list[str]) – List of POTCAR symbols.

      - address_basis_file (PathLike | None) – Path to the basis file. Defaults to None.

    Returns:

      List of basis functions.

    Return type:

      list[str]

    Raises:

      ValueError – If the POSCAR does not match the POTCAR or if basis information is missing.

  classmethod standard_calculations_from_vasp_files(POSCAR_input: PathLike = 'POSCAR', INCAR_input: PathLike = 'INCAR', POTCAR_input: PathLike | None = None, Vasprun_output: PathLike = 'vasprun.xml', dict_for_basis: dict | None = None, option: str = 'standard') → Self

    Generate lobsterin with standard settings.

    Parameters:

      - POSCAR_input (PathLike) – path to POSCAR

      - INCAR_input (PathLike) – path to INCAR

      - POTCAR_input (PathLike) – path to POTCAR

      - Vasprun_output (PathLike) – path to vasprun.xml

      - dict_for_basis (dict) – can be provided: it should look the following: dict_for_basis={“Fe”:’3p 3d 4s 4f’, “C”: ‘2s 2p’} and will overwrite all settings from POTCAR_input

      - option (str) – ‘standard’ will start a normal LOBSTER run where COHPs, COOPs, DOS, CHARGE etc. will be calculated ‘standard_with_energy_range_from_vasprun’ will start a normal LOBSTER run for entire energy range of VASP static run. vasprun.xml file needs to be in current directory. ‘standard_from_projection’ will start a normal LOBSTER run from a projection ‘standard_with_fatband’ will do a fatband calculation, run over all orbitals ‘onlyprojection’ will only do a projection ‘onlydos’ will only calculate a projected dos ‘onlycohp’ will only calculate cohp ‘onlycoop’ will only calculate coop ‘onlycohpcoop’ will only calculate cohp and coop

    Returns:

      Lobsterin with standard settings

  write_INCAR(incar_input: PathLike = 'INCAR', incar_output: PathLike = 'INCAR.lobster', poscar_input: PathLike = 'POSCAR', isym: Literal[-1, 0] = 0, further_settings: dict | None = None) → None

    Writes a modified INCAR file for LOBSTER calculations.

    Parameters:

      - incar_input (PathLike) – Path to the input INCAR file.

      - incar_output (PathLike) – Path to the output INCAR file.

      - poscar_input (PathLike) – Path to the input POSCAR file.

      - isym (Literal[-1, 0]) – ISYM value to set. Defaults to 0.

      - further_settings (dict | None) – Additional settings to include in the INCAR file.

    Raises:

      ValueError – If isym is not -1 or 0.

  static write_KPOINTS(POSCAR_input: PathLike = 'POSCAR', KPOINTS_output: PathLike = 'KPOINTS.lobster', reciprocal_density: int = 100, isym: Literal[-1, 0] = 0, from_grid: bool = False, input_grid: tuple[int, int, int] = (5, 5, 5), line_mode: bool = True, kpoints_line_density: int = 20, symprec: float = 0.01) → None

    Write a gamma-centered KPOINTS file for LOBSTER.

    Parameters:

      - POSCAR_input (PathLike) – path to POSCAR

      - KPOINTS_output (PathLike) – path to output KPOINTS

      - reciprocal_density (int) – Grid density

      - isym (-1 | 0) – ISYM value.

      - from_grid (bool) – If True KPOINTS will be generated with the help of a grid given in input_grid. Otherwise, they will be generated from the reciprocal_density

      - input_grid (tuple) – grid to generate the KPOINTS file

      - line_mode (bool) – If True, band structure will be generated

      - kpoints_line_density (int) – density of the lines in the band structure

      - symprec (float) – precision to determine symmetry

  static write_POSCAR_with_standard_primitive(POSCAR_input: PathLike = 'POSCAR', POSCAR_output: PathLike = 'POSCAR.lobster', symprec: float = 0.01) → None

    Writes a POSCAR file with the standard primitive cell.

    Parameters:

      - POSCAR_input (PathLike) – Path to the input POSCAR file.

      - POSCAR_output (PathLike) – Path to the output POSCAR file.

      - symprec (float) – Precision for symmetry determination. Defaults to 0.01.

  write_lobsterin(path: PathLike = 'lobsterin', overwritedict: dict | None = None) → None

    Writes the LobsterIn object to a lobsterin file.

    Parameters:

      - path (PathLike) – The output file path. Defaults to “lobsterin”.

      - overwritedict (dict | None) – A dictionary of settings to overwrite before writing.

get_all_possible_basis_combinations(min_basis: list, max_basis: list) → list[list[str]]

  Get all possible basis combinations.

  Parameters:

    - min_basis – list of basis entries: e.g., [“Si 3p 3s”]

    - max_basis – list of basis entries: e.g., [“Si 3p 3s”].

  Returns:

    all possible combinations of basis functions, e.g. [[“Si 3p 3s”]]

  Return type:

    list[list[str]]

## pymatgen.io.lobster.future.lobsterenv module

Deprecated class for analyzing NearNeighbors using ICOHPs/ICOOPs/ICOBIs.

class LobsterNeighbors(*args, **kwargs)

  Bases: `object`

  Deprecated LobsterNeighbors class for analyzing NearNeighbor interactions using ICOHPs/ICOOPs/ICOBIs.

## pymatgen.io.lobster.future.types module

class LobsterBandOverlaps

  Bases: `TypedDict`

  Dictionary representing band overlaps in LOBSTER.

  k_points

    List of k-points for each spin.

    Type:

      dict[Spin, list[list[float]]]

  matrices

    List of matrices for each spin.

    Type:

      dict[Spin, list[NDArray[floating]]]

  max_deviations

    List of maximal deviations for each spin.

    Type:

      dict[Spin, list[float]]

  k_points: dict[Spin, list[list[float]]]
  matrices: dict[Spin, list[NDArray[floating]]]
  max_deviations: dict[Spin, list[float]]

class LobsterFatband

  Bases: `TypedDict`

  Dictionary representing fatband data in LOBSTER.

  center

    Atom associated with the fatband.

    Type:

      str

  orbital

    Orbital associated with the fatband.

    Type:

      str

  energies

    Energies at each k-point for each spin.

    Type:

      dict[Spin, NDArray[floating]]

  projections

    Weights/projections at each k-point for each spin.

    Type:

      dict[Spin, NDArray[floating]]

  center: str
  energies: dict[Spin, NDArray[floating]]
  orbital: str
  projections: dict[Spin, NDArray[floating]]

class LobsterFatbands

  Bases: `TypedDict`

  Dictionary representing multiple fatbands in LOBSTER.

  k_points

    List of k-points.

    Type:

      list[list[float]]

  bands

    List of fatband dictionaries.

    Type:

      list[LobsterFatband]

  bands: list[LobsterFatband]
  k_points: list[list[float]]

class LobsterInteraction

  Bases: `TypedDict`

  Dictionary representing a chemical interaction in LOBSTER.

  This dictionary stores information about a specific interaction between atoms in a structure.

  index

    The index of the interaction.

    Type:

      int

  centers

    List of strings representing the centers of the interaction (e.g., “Fe1”, “O2”).

    Type:

      list[str]

  cells

    List of lists of integers representing the cells of the interaction

    Type:

      list[list[int]] | NDArray[integer]

  (e.g., [0, 0, 0]).
  orbitals

    List of strings representing the orbitals involved in the interaction

    Type:

      list[str | None]

  (e.g., "2s", "2p_x").
  length

    The length of the interaction, representing the distance between the centers.

    Type:

      float | None

  cells: list[list[int]] | NDArray[integer]
  centers: list[str]
  index: int
  length: float | None
  orbitals: list[str | None]

class LobsterInteractionData

  Bases: `dict`

  Dictionary representing a chemical interaction in LOBSTER with additional COXX/ICOXX data.

  Extends LobsterInteraction by adding COXX and ICOXX values for each spin.

  coxx

    COXX values for each spin.

    Type:

      dict[Spin, NDArray[floating] | float]

  icoxx

    ICOXX values for each spin.

    Type:

      dict[Spin, NDArray[floating] | float]

  cells: list[list[int]] | NDArray[integer]
  centers: list[str]
  coxx: dict[Spin, NDArray[floating] | float]
  icoxx: dict[Spin, NDArray[floating] | float]
  index: int
  length: float | None
  orbitals: list[str | None]

## pymatgen.io.lobster.future.utils module

convert_spin_keys(obj: Any) → Any

  Convert an object to a JSON-compatible format recursively.

  This function ensures that the input object is converted into a format that can be serialized into JSON. It handles lists, tuples, dictionaries, and enums.

  Parameters:

    obj (Any) – Input object to convert.

  Returns:

    JSON-compatible representation of the input object.

  Return type:

    Any

  Example

      >>> make_json_compatible({"key": Enum("Example", "value")})
      {'key': 'value'}

natural_sort(list_to_sort: str) → list[Any]

  Sort a list of strings in human order.

  This function sorts strings in a way that humans would expect, taking into account numerical values within the strings.

  Parameters:

    list_to_sort (str) – List of strings to sort.

  Returns:

    Sorted list of strings in human order.

  Return type:

    list[Any]

  Example

      >>> natural_sort(["file10", "file2", "file1"])
      ['file1', 'file2', 'file10']

parse_orbital_from_text(text: str) → str | None

  Parse the orbital from a text string of an ICOXXLIST file.

  This function extracts the orbital information from a given text string. It checks for valid orbital patterns and returns the matched orbital.

  Parameters:

    text (str) – Text string to parse the orbital from.

  Returns:

    Parsed orbital string if a valid orbital is found, otherwise None.

  Return type:

    str | None

  Example

      >>> parse_orbital_from_text("1s_2p_x")
      '2p_x'

restore_spin_keys(obj: Any) → Any

  Restore Spin enum keys from JSON-serialized format.

  This function recursively processes an object and converts string keys “1” and “-1” back to Spin.up and Spin.down enum values. It handles nested lists, tuples, and dictionaries.

  Parameters:

    obj (Any) – Input object with potential Spin keys as strings.

  Returns:

    Object with Spin enum keys restored.

  Return type:

    Any

  Example

      >>> restore_spin_keys({"1": [1, 2], "-1": [3, 4]})
      {<Spin.up: 1>: [1, 2], <Spin.down: -1>: [3, 4]}

## pymatgen.io.lobster.future.versioning module

version_processor(min_version: str = '0.0', max_version: str | None = None) → Callable[[F], F]

  Decorator to mark a method as a version processor.

  Parameters:

    - min_version (str) – Minimum version for which the processor is valid.

    - max_version (str | None) – Maximum version for which the processor is valid.

  Returns:

    Decorator for versioned processor methods.

  Return type:

    Callable[[F], F]