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

# pymatgen.io.lobster.future.outputs package

Module for reading Lobster output 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 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 BWDFCOHP(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `BWDF`

  Parser for BWDFCOHP.lobster files.

  Returns:

    None

  Parameters:

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

  classmethod get_default_filename() → str

    Get the default filename for the BWDFCOHP class.

    Returns:

      Default filename.

    Return type:

      str

  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 COXXCAR(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterInteractionsHolder`

  Reader for COXXCAR-style files (COOPCAR, COHPCAR, COBICAR).

  Parses LOBSTER’s COXXCAR outputs and organizes bond and orbital-resolved interaction data.

  filename

    Input file path.

    Type:

      PathLike

  num_bonds

    Number of bond interactions reported.

    Type:

      int

  num_data

    Number of energy/data points.

    Type:

      int

  efermi

    Fermi energy from the file.

    Type:

      float

  spins

    Present spin channels.

    Type:

      list[Spin]

  interactions

    Parsed interaction metadata.

    Type:

      list[dict]

  data

    Raw numerical table parsed from the file.

    Type:

      np.ndarray

  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]
  property energies: NDArray[np.floating]

    Return the energy grid.

    Returns:

      Energies (first column of self.data).

    Return type:

      NDArray[np.floating]

  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, data_type: Literal['coxx', 'icoxx'] | None = None) → NDArray[np.floating]

    Return the data columns matching the provided interaction properties.

    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.

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

      - data_type (Literal["coxx", "icoxx"] | None) – Restrict column type.

    Returns:

      Array with shape (n_energies, n_selected_columns).

    Return type:

      np.ndarray

  get_data_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, spins: list[Literal[1, -1]] | None = None, data_type: Literal['coxx', 'icoxx'] | None = None) → list[int]

    Return data-column indices matching the provided interaction properties.

    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.

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

      - data_type (Literal["coxx", "icoxx"] | None) – Restrict column type.

    Returns:

      Sorted list of data column indices that match the filters.

    Return type:

      list[int]

  interaction_indices_to_data_indices_mapping(interaction_indices: int | list[int], spins: Literal[1, -1] | list[Literal[1, -1]] | None = None, data_type: Literal['coxx', 'icoxx'] | None = None) → list[int]

    Map interaction indices to column indices in self.data.

    Parameters:

      - interaction_indices (int | list[int]) – Single index or list of interaction indices.

      - spins (Spin | list[Spin] | None) – Spin(s) to include.

      - data_type (Literal["coxx", "icoxx"] | None) – Select columns of that type.

    Returns:

      Sorted list of integer column indices into self.data.

    Return type:

      list[int]

    Raises:

      ValueError – If an invalid Spin is requested.

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

    Parse the bonds/interactions header block.

    Parameters:

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

  parse_data() → None

    Parse the numerical data block into self.data and validate shape.

    Parameters:

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

    Raises:

      ValueError – If the parsed data array shape does not match the expected shape.

  parse_file() → None

    Parse the full COXXCAR file (header and data).

  parse_header() → None

    Parse the file header and set metadata attributes.

    Parameters:

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

  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 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

  integrated_total_dos: Dos
  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.

  projected_dos: dict[str, dict[str, Dos]]
  total_dos: Dos
  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 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”.

## Submodules

## pymatgen.io.lobster.future.outputs.bands module

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 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. –

## pymatgen.io.lobster.future.outputs.coxxcar module

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 COXXCAR(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `LobsterInteractionsHolder`

  Reader for COXXCAR-style files (COOPCAR, COHPCAR, COBICAR).

  Parses LOBSTER’s COXXCAR outputs and organizes bond and orbital-resolved interaction data.

  filename

    Input file path.

    Type:

      PathLike

  num_bonds

    Number of bond interactions reported.

    Type:

      int

  num_data

    Number of energy/data points.

    Type:

      int

  efermi

    Fermi energy from the file.

    Type:

      float

  spins

    Present spin channels.

    Type:

      list[Spin]

  interactions

    Parsed interaction metadata.

    Type:

      list[dict]

  data

    Raw numerical table parsed from the file.

    Type:

      np.ndarray

  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]
  property energies: NDArray[np.floating]

    Return the energy grid.

    Returns:

      Energies (first column of self.data).

    Return type:

      NDArray[np.floating]

  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, data_type: Literal['coxx', 'icoxx'] | None = None) → NDArray[np.floating]

    Return the data columns matching the provided interaction properties.

    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.

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

      - data_type (Literal["coxx", "icoxx"] | None) – Restrict column type.

    Returns:

      Array with shape (n_energies, n_selected_columns).

    Return type:

      np.ndarray

  get_data_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, spins: list[Literal[1, -1]] | None = None, data_type: Literal['coxx', 'icoxx'] | None = None) → list[int]

    Return data-column indices matching the provided interaction properties.

    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.

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

      - data_type (Literal["coxx", "icoxx"] | None) – Restrict column type.

    Returns:

      Sorted list of data column indices that match the filters.

    Return type:

      list[int]

  interaction_indices_to_data_indices_mapping(interaction_indices: int | list[int], spins: Literal[1, -1] | list[Literal[1, -1]] | None = None, data_type: Literal['coxx', 'icoxx'] | None = None) → list[int]

    Map interaction indices to column indices in self.data.

    Parameters:

      - interaction_indices (int | list[int]) – Single index or list of interaction indices.

      - spins (Spin | list[Spin] | None) – Spin(s) to include.

      - data_type (Literal["coxx", "icoxx"] | None) – Select columns of that type.

    Returns:

      Sorted list of integer column indices into self.data.

    Return type:

      list[int]

    Raises:

      ValueError – If an invalid Spin is requested.

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

    Parse the bonds/interactions header block.

    Parameters:

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

  parse_data() → None

    Parse the numerical data block into self.data and validate shape.

    Parameters:

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

    Raises:

      ValueError – If the parsed data array shape does not match the expected shape.

  parse_file() → None

    Parse the full COXXCAR file (header and data).

  parse_header() → None

    Parse the file header and set metadata attributes.

    Parameters:

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

  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 COXXCAR.parse_file>}

## pymatgen.io.lobster.future.outputs.doscar module

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

  integrated_total_dos: Dos
  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.

  projected_dos: dict[str, dict[str, Dos]]
  total_dos: Dos
  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>}

## pymatgen.io.lobster.future.outputs.icoxxlist module

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 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>}

## pymatgen.io.lobster.future.outputs.lobsterout module

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>}

## pymatgen.io.lobster.future.outputs.misc module

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 BWDFCOHP(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)

  Bases: `BWDF`

  Parser for BWDFCOHP.lobster files.

  Returns:

    None

  Parameters:

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

  classmethod get_default_filename() → str

    Get the default filename for the BWDFCOHP class.

    Returns:

      Default filename.

    Return type:

      str

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

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 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 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”.

get_orb_from_str(orbs: list[str]) → tuple[str, list[tuple[int, Orbital]]]

  Get Orbitals from string representations.

  Parameters:

    orbs (list[str]) – Orbitals, e.g. [“2p_x”, “3s”].

  Returns:

    Orbital label and list of orbitals.

  Return type:

    tuple[str, list[tuple[int, Orbital]]]

## pymatgen.io.lobster.future.outputs.populations module

Classes for parsing LOBSTER population analysis output files.

Provides classes to read and parse population analysis files generated by LOBSTER, such as CHARGE.lobster, CHARGE.LCFO.lobster, GROSSPOP.lobster, and GROSSPOP.LCFO.lobster. Extracts Mulliken and Loewdin charges and gross populations for further analysis.

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 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>}