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)[source]

Bases: LobsterFile

Parser for BWDF.lobster/BWDFCOHP.lobster files.

centers[source]

Bond length centers for the distribution.

Type:: NDArray

bwdf[source]

Bond weighted distribution function.

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

bin_width[source]

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[source]

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[source]

Get the default filename for the BWDF class.

Returns:: Default filename.
Return type:: str

is_cohp: ClassVar[bool] = False[source]

parse_file() → None[source]

Parse BWDF.lobster/BWDFCOHP.lobster file.

Returns:: None

process_data_into_bwdf_centers() → None[source]

Process data into bwdf and centers.

Returns:: None

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

class BWDFCOHP(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)[source]

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[source]

Get the default filename for the BWDFCOHP class.

Returns:: Default filename.
Return type:: str

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

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

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[source]

“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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

Parse bandOverlaps.lobster file for LOBSTER versions ≤3.2.

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

parse_file_v4_0() → None[source]

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>}[source]

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

Bases: LobsterFile

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

is_lcfo[source]

Whether the CHARGE file is from LCFO analysis.

Type:: bool

centers[source]

Atom labels with indices.

Type:: list[str]

mulliken[source]

Mulliken charges for each atom.

Type:: list[float]

loewdin[source]

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+)'[source]

classmethod get_default_filename() → str[source]

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[source]

parse_file() → None[source]

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>}[source]

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

Bases: CHARGE

Parser for CHARGE.LCFO.lobster files.

is_lcfo[source]

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+)'[source]

is_lcfo: ClassVar[bool] = True[source]

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

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

Bases: COXXCAR

Reader for COBICAR.lobster files.

coxxcar_type[source]

Type of COXXCAR file (“COBICAR”).

Type:: str

is_lcfo[source]

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'[source]

classmethod get_default_filename() → str[source]: Return the default filename for COBICAR.

is_lcfo: ClassVar[bool] = False[source]

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

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

Bases: COBICAR

Reader for COBICAR.LCFO.lobster files.

is_lcfo[source]

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[source]

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

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

Bases: COXXCAR

Reader for COHPCAR.lobster files.

coxxcar_type[source]

Type of COXXCAR file (“COHPCAR”).

Type:: str

is_lcfo[source]

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'[source]

classmethod get_default_filename() → str[source]: Return the default filename for COOPCAR.

is_lcfo: ClassVar[bool] = False[source]

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

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

Bases: COHPCAR

Reader for COHPCAR.LCFO.lobster files.

is_lcfo[source]

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[source]

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

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

Bases: COXXCAR

Reader for COOPCAR.lobster files.

coxxcar_type[source]

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'[source]

classmethod get_default_filename() → str[source]: Return the default filename for COOPCAR.

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

class COXXCAR(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)[source]

Bases: LobsterInteractionsHolder

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

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

filename[source]

Input file path.

Type:: PathLike

num_bonds[source]

Number of bond interactions reported.

Type:: int

num_data[source]

Number of energy/data points.

Type:: int

efermi[source]

Fermi energy from the file.

Type:: float

spins[source]

Present spin channels.

Type:: list[Spin]

interactions[source]

Parsed interaction metadata.

Type:: list[dict]

data[source]

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][source]

property energies: NDArray[np.floating][source]

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][source]

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

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][source]

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]*)\\])?(?:\\(([^)]*)\\))?'[source]

parse_bonds() → None[source]

Parse the bonds/interactions header block.

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

parse_data() → None[source]

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[source]: Parse the full COXXCAR file (header and data).

parse_header() → None[source]

Parse the file header and set metadata attributes.

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

process_data_into_interactions() → None[source]

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>}[source]

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

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[source]

Complete DOS data.

Type:: LobsterCompleteDos

pdos[source]

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

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

tdos[source]

Total density of states.

Type:: Dos

energies[source]

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

Type:: np.ndarray

tdensities[source]

Total density arrays for each spin channel.

Type:: dict[Spin, np.ndarray]

itdensities[source]

Integrated total density arrays for each spin channel.

Type:: dict[Spin, np.ndarray]

is_spin_polarized[source]

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[source]: Fermi energy in eV.

property energies: NDArray[floating][source]: Energies at which the DOS was calculated (in eV, relative to efermi).

classmethod get_default_filename() → str[source]

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[source]

is_lcfo: ClassVar[bool] = False[source]

property is_spin_polarized: bool[source]

Whether the system is spin polarized.

Returns:: True if the system is spin polarized, False otherwise.
Return type:: bool

process() → None[source]

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]][source]

total_dos: Dos[source]

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

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

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[source]

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[source]

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

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

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[source]: Convert lists in band_overlaps to numpy arrays.

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

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[source]

Get the default filename for the Fatband class.

Returns:: Default filename pattern.
Return type:: str

parse_file() → None[source]: Parse the FATBAND file and populate the fatband attribute.

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

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)[source]

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[source]

Fermi level read from vasprun.xml.

Type:: float

spins[source]

Spins present in the FATBAND files.

Type:: list[Spin]

kpoints[source]

Parsed KPOINTS used for the lobster FatBand calculations.

Type:: Kpoints

filenames[source]

Sorted list of matched filenames.

Type:: list[Path]

structure[source]

Structure object used for projections.

Type:: Structure

reciprocal_lattice[source]

Reciprocal lattice of the structure.

Type:: Lattice

lobster_version[source]

LOBSTER version string used for parsing.

Type:: str

fatbands[source]

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][source]

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][source]

property has_spin: bool[source]

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[source]

Indicates whether the file contains spin-polarized data.

Returns:: True if multiple spins are present, False otherwise.
Return type:: bool

process() → None[source]

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)[source]

Bases: LobsterFile

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

is_lcfo[source]

Whether the GROSSPOP file is from LCFO analysis.

Type:: bool

populations[source]

Population dictionaries for each atom.

Type:: LobsterPopulations

spins[source]

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[source]

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[source]

parse_file() → None[source]

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>}[source]

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

Bases: GROSSPOP

Parser for GROSSPOP.LCFO.lobster files.

is_lcfo[source]

Whether the GROSSPOP file is in LCFO format.

Type:: bool

populations[source]

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[source]

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

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

Bases: ICOXXLIST

Reader for ICOBILIST.lobster files.

icoxxlist_type[source]

Type of ICOXXLIST file (“COBI”).

Type:: str

is_lcfo[source]

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[source]: Return the default filename for ICOBILIST.

icoxxlist_type: ClassVar[str] = 'COBI'[source]

is_lcfo: ClassVar[bool] = False[source]

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

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

Bases: ICOBILIST

Reader for ICOBILIST.LCFO.lobster files.

is_lcfo[source]

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[source]

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

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

Bases: ICOXXLIST

Reader for ICOHPLIST.lobster files.

icoxxlist_type[source]

Type of ICOXXLIST file (“COHP”).

Type:: str

is_lcfo[source]

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[source]: Return the default filename for ICOHPLIST.

icoxxlist_type: ClassVar[str] = 'COHP'[source]

is_lcfo: ClassVar[bool] = False[source]

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

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

Bases: ICOHPLIST

Reader for ICOHPLIST.LCFO.lobster files.

is_lcfo[source]

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[source]

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

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

Bases: ICOXXLIST

Reader for ICOOPLIST.lobster files.

icoxxlist_type[source]

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[source]: Return the default filename for ICOOPLIST.

icoxxlist_type: ClassVar[str] = 'COOP'[source]

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

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

Bases: LobsterInteractionsHolder

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

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

interactions[source]

List of parsed interactions.

Type:: list[LobsterInteractionData]

spins[source]

List of spins present in the file.

Type:: list[Spin]

data[source]

Array of ICOXX values for each interaction and spin.

Type:: NDArray[np.floating]

icoxxlist_type[source]

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

Type:: str

is_lcfo[source]

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 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][source]

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+))?'[source]

parse_file() → None[source]

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[source]

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[source]

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>}[source]

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

Bases: LobsterFile

Parser for LOBSTER matrix files.

matrix_type[source]

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

Type:: str

centers[source]

Atom centers.

Type:: list[str]

orbitals[source]

Orbitals.

Type:: list[str]

matrices[source]

Matrix data for each k-point and spin.

Type:: LobsterMatrixData

efermi[source]

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][source]

Serialize object to a dictionary.

Returns:: Dictionary representation of the object.
Return type:: dict[str, Any]

centers: list[str][source]

classmethod from_dict(d: dict[str, Any]) → Self[source]: Deserialize from dictionary.

classmethod get_default_filename() → str[source]

Get the default filename for the LobsterMatrices class.

Returns:: Default filename.
Return type:: str

get_matrix_type() → str[source]

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[source]

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[source]

matrix_types: ClassVar[set[str]] = {'coefficient', 'hamilton', 'overlap', 'transfer'}[source]

orbitals: list[str][source]

parse_file() → None[source]

Parse matrix data and set instance attributes.

Returns:: None

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

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

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[source]

Basis functions used in the LOBSTER run.

Type:: list[str]

basis_type[source]

Basis types used in the LOBSTER run.

Type:: list[str]

charge_spilling[source]

Charge spilling for each spin channel.

Type:: list[float]

dft_program[source]

DFT program used for the calculation.

Type:: str

elements[source]

Elements present in the calculation.

Type:: list[str]

has_charge[source]

Whether CHARGE.lobster is present.

Type:: bool

has_cohpcar[source]

Whether COHPCAR.lobster and ICOHPLIST.lobster are present.

Type:: bool

has_madelung[source]

Whether SitePotentials.lobster and MadelungEnergies.lobster are present.

Type:: bool

has_coopcar[source]

Whether COOPCAR.lobster and ICOOPLIST.lobster are present.

Type:: bool

has_cobicar[source]

Whether COBICAR.lobster and ICOBILIST.lobster are present.

Type:: bool

has_doscar[source]

Whether DOSCAR.lobster is present.

Type:: bool

has_doscar_lso[source]

Whether DOSCAR.LSO.lobster is present.

Type:: bool

has_projection[source]

Whether projectionData.lobster is present.

Type:: bool

has_bandoverlaps[source]

Whether bandOverlaps.lobster is present.

Type:: bool

has_density_of_energies[source]

Whether DensityOfEnergy.lobster is present.

Type:: bool

has_fatbands[source]

Whether fatband calculation was performed.

Type:: bool

has_grosspopulation[source]

Whether GROSSPOP.lobster is present.

Type:: bool

has_polarization[source]

Whether POLARIZATION.lobster is present.

Type:: bool

info_lines[source]

Additional information on the run.

Type:: list[str]

info_orthonormalization[source]

Information on orthonormalization.

Type:: list[str]

is_restart_from_projection[source]

Whether calculation was restarted from a projection file.

Type:: bool

lobster_version[source]

The LOBSTER version.

Type:: str

number_of_spins[source]

Number of spins.

Type:: int

number_of_threads[source]

Number of threads used.

Type:: int

timing[source]

Timing information.

Type:: dict[str, float]

total_spilling[source]

Total spilling for each spin channel.

Type:: list[float]

warning_lines[source]

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[source]

Get the default filename for LobsterOut.

Returns:: The default filename.
Return type:: str

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

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[source]

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>}[source]

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

Bases: LobsterFile

Parser for MadelungEnergies.lobster files.

madelung_energies_mulliken[source]

Madelung energy (Mulliken).

Type:: float

madelung_energies_loewdin[source]

Madelung energy (Loewdin).

Type:: float

ewald_splitting[source]

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[source]

Get the default filename for MadelungEnergies.

Returns:: Default filename.
Return type:: str

parse_file() → None[source]

Parse MadelungEnergies.lobster file.

Extracts the Ewald splitting parameter and Madelung energies.

Returns:: None

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

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

Bases: LobsterInteractionsHolder

Reader for NcICOBILIST.lobster files.

Parses non-conventional ICOBI interaction data.

interactions[source]

List of parsed interactions.

Type:: list

spins[source]

List of spins present in the file.

Type:: list[Spin]

data[source]

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 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[source]: Return the default filename for NcICOBILIST.

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

parse_file() → None[source]

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[source]

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>}[source]

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

Bases: LobsterFile

Parser for POLARIZATION.lobster file.

rel_mulliken_pol_vector[source]

Relative Mulliken polarization vector.

Type:: dict[str, float]

rel_loewdin_pol_vector[source]

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[source]

Get the default filename for the Polarization class.

Returns:: Default filename.
Return type:: str

parse_file() → None[source]

Parse POLARIZATION.lobster file.

Returns:: None

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

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

Bases: LobsterFile

Parser for SitePotentials.lobster files.

centers[source]

Atom centers.

Type:: list[str]

site_potentials_mulliken[source]

Mulliken site potentials.

Type:: list[float]

site_potentials_loewdin[source]

Loewdin site potentials.

Type:: list[float]

madelung_energies_mulliken[source]

Madelung energy (Mulliken).

Type:: float

madelung_energies_loewdin[source]

Madelung energy (Loewdin).

Type:: float

ewald_splitting[source]

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[source]

Get the default filename for SitePotentials.

Returns:: Default filename.
Return type:: str

parse_file() → None[source]

Parse SitePotentials.lobster file.

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

Returns:: None

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

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

Bases: LobsterFile

Parser for wave function files from LOBSTER.

Reads wave function files and creates VolumetricData objects.

grid[source]

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

Type:: tuple[int, int, int]

points[source]

Points in real space.

Type:: list[tuple[float, float, float]]

reals[source]

Real parts of the wave function.

Type:: list[float]

imaginaries[source]

Imaginary parts of the wave function.

Type:: list[float]

distances[source]

Distances to the first point in the wave function file.

Type:: list[float]

structure[source]

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[source]

get_volumetricdata_density() → VolumetricData[source]

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

Returns:: Density volumetric data.
Return type:: VolumetricData

get_volumetricdata_imaginary() → VolumetricData[source]

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

Returns:: Imaginary part volumetric data.
Return type:: VolumetricData

get_volumetricdata_real() → VolumetricData[source]

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

Returns:: Real part volumetric data.
Return type:: VolumetricData

parse_file() → None[source]

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[source]

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>}[source]

write_file(filename: PathLike = 'WAVECAR.vasp', part: Literal['real', 'imaginary', 'density'] = 'real') → None[source]

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)[source]

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[source]

“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[source]

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[source]

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[source]

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[source]

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[source]

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[source]

Parse bandOverlaps.lobster file for LOBSTER versions ≤3.2.

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

parse_file_v4_0() → None[source]

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>}[source]

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

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[source]: Convert lists in band_overlaps to numpy arrays.

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

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[source]

Get the default filename for the Fatband class.

Returns:: Default filename pattern.
Return type:: str

parse_file() → None[source]: Parse the FATBAND file and populate the fatband attribute.

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

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)[source]

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[source]

Fermi level read from vasprun.xml.

Type:: float

spins[source]

Spins present in the FATBAND files.

Type:: list[Spin]

kpoints[source]

Parsed KPOINTS used for the lobster FatBand calculations.

Type:: Kpoints

filenames[source]

Sorted list of matched filenames.

Type:: list[Path]

structure[source]

Structure object used for projections.

Type:: Structure

reciprocal_lattice[source]

Reciprocal lattice of the structure.

Type:: Lattice

lobster_version[source]

LOBSTER version string used for parsing.

Type:: str

fatbands[source]

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][source]

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][source]

property has_spin: bool[source]

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[source]

Indicates whether the file contains spin-polarized data.

Returns:: True if multiple spins are present, False otherwise.
Return type:: bool

process() → None[source]

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)[source]

Bases: COXXCAR

Reader for COBICAR.lobster files.

coxxcar_type[source]

Type of COXXCAR file (“COBICAR”).

Type:: str

is_lcfo[source]

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'[source]

classmethod get_default_filename() → str[source]: Return the default filename for COBICAR.

is_lcfo: ClassVar[bool] = False[source]

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

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

Bases: COBICAR

Reader for COBICAR.LCFO.lobster files.

is_lcfo[source]

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[source]

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

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

Bases: COXXCAR

Reader for COHPCAR.lobster files.

coxxcar_type[source]

Type of COXXCAR file (“COHPCAR”).

Type:: str

is_lcfo[source]

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'[source]

classmethod get_default_filename() → str[source]: Return the default filename for COOPCAR.

is_lcfo: ClassVar[bool] = False[source]

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

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

Bases: COHPCAR

Reader for COHPCAR.LCFO.lobster files.

is_lcfo[source]

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[source]

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

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

Bases: COXXCAR

Reader for COOPCAR.lobster files.

coxxcar_type[source]

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'[source]

classmethod get_default_filename() → str[source]: Return the default filename for COOPCAR.

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

class COXXCAR(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)[source]

Bases: LobsterInteractionsHolder

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

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

filename[source]

Input file path.

Type:: PathLike

num_bonds[source]

Number of bond interactions reported.

Type:: int

num_data[source]

Number of energy/data points.

Type:: int

efermi[source]

Fermi energy from the file.

Type:: float

spins[source]

Present spin channels.

Type:: list[Spin]

interactions[source]

Parsed interaction metadata.

Type:: list[dict]

data[source]

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][source]

property energies: NDArray[np.floating][source]

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][source]

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

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][source]

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]*)\\])?(?:\\(([^)]*)\\))?'[source]

parse_bonds() → None[source]

Parse the bonds/interactions header block.

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

parse_data() → None[source]

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[source]: Parse the full COXXCAR file (header and data).

parse_header() → None[source]

Parse the file header and set metadata attributes.

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

process_data_into_interactions() → None[source]

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>}[source]

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

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

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[source]

Complete DOS data.

Type:: LobsterCompleteDos

pdos[source]

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

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

tdos[source]

Total density of states.

Type:: Dos

energies[source]

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

Type:: np.ndarray

tdensities[source]

Total density arrays for each spin channel.

Type:: dict[Spin, np.ndarray]

itdensities[source]

Integrated total density arrays for each spin channel.

Type:: dict[Spin, np.ndarray]

is_spin_polarized[source]

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[source]: Fermi energy in eV.

property energies: NDArray[floating][source]: Energies at which the DOS was calculated (in eV, relative to efermi).

classmethod get_default_filename() → str[source]

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[source]

is_lcfo: ClassVar[bool] = False[source]

property is_spin_polarized: bool[source]

Whether the system is spin polarized.

Returns:: True if the system is spin polarized, False otherwise.
Return type:: bool

process() → None[source]

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]][source]

total_dos: Dos[source]

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

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

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[source]

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[source]

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

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

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

Bases: ICOXXLIST

Reader for ICOBILIST.lobster files.

icoxxlist_type[source]

Type of ICOXXLIST file (“COBI”).

Type:: str

is_lcfo[source]

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[source]: Return the default filename for ICOBILIST.

icoxxlist_type: ClassVar[str] = 'COBI'[source]

is_lcfo: ClassVar[bool] = False[source]

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

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

Bases: ICOBILIST

Reader for ICOBILIST.LCFO.lobster files.

is_lcfo[source]

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[source]

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

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

Bases: ICOXXLIST

Reader for ICOHPLIST.lobster files.

icoxxlist_type[source]

Type of ICOXXLIST file (“COHP”).

Type:: str

is_lcfo[source]

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[source]: Return the default filename for ICOHPLIST.

icoxxlist_type: ClassVar[str] = 'COHP'[source]

is_lcfo: ClassVar[bool] = False[source]

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

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

Bases: ICOHPLIST

Reader for ICOHPLIST.LCFO.lobster files.

is_lcfo[source]

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[source]

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

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

Bases: ICOXXLIST

Reader for ICOOPLIST.lobster files.

icoxxlist_type[source]

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[source]: Return the default filename for ICOOPLIST.

icoxxlist_type: ClassVar[str] = 'COOP'[source]

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

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

Bases: LobsterInteractionsHolder

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

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

interactions[source]

List of parsed interactions.

Type:: list[LobsterInteractionData]

spins[source]

List of spins present in the file.

Type:: list[Spin]

data[source]

Array of ICOXX values for each interaction and spin.

Type:: NDArray[np.floating]

icoxxlist_type[source]

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

Type:: str

is_lcfo[source]

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 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][source]

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+))?'[source]

parse_file() → None[source]

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[source]

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[source]

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>}[source]

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

Bases: LobsterInteractionsHolder

Reader for NcICOBILIST.lobster files.

Parses non-conventional ICOBI interaction data.

interactions[source]

List of parsed interactions.

Type:: list

spins[source]

List of spins present in the file.

Type:: list[Spin]

data[source]

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 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[source]: Return the default filename for NcICOBILIST.

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

parse_file() → None[source]

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[source]

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>}[source]

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

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

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[source]

Basis functions used in the LOBSTER run.

Type:: list[str]

basis_type[source]

Basis types used in the LOBSTER run.

Type:: list[str]

charge_spilling[source]

Charge spilling for each spin channel.

Type:: list[float]

dft_program[source]

DFT program used for the calculation.

Type:: str

elements[source]

Elements present in the calculation.

Type:: list[str]

has_charge[source]

Whether CHARGE.lobster is present.

Type:: bool

has_cohpcar[source]

Whether COHPCAR.lobster and ICOHPLIST.lobster are present.

Type:: bool

has_madelung[source]

Whether SitePotentials.lobster and MadelungEnergies.lobster are present.

Type:: bool

has_coopcar[source]

Whether COOPCAR.lobster and ICOOPLIST.lobster are present.

Type:: bool

has_cobicar[source]

Whether COBICAR.lobster and ICOBILIST.lobster are present.

Type:: bool

has_doscar[source]

Whether DOSCAR.lobster is present.

Type:: bool

has_doscar_lso[source]

Whether DOSCAR.LSO.lobster is present.

Type:: bool

has_projection[source]

Whether projectionData.lobster is present.

Type:: bool

has_bandoverlaps[source]

Whether bandOverlaps.lobster is present.

Type:: bool

has_density_of_energies[source]

Whether DensityOfEnergy.lobster is present.

Type:: bool

has_fatbands[source]

Whether fatband calculation was performed.

Type:: bool

has_grosspopulation[source]

Whether GROSSPOP.lobster is present.

Type:: bool

has_polarization[source]

Whether POLARIZATION.lobster is present.

Type:: bool

info_lines[source]

Additional information on the run.

Type:: list[str]

info_orthonormalization[source]

Information on orthonormalization.

Type:: list[str]

is_restart_from_projection[source]

Whether calculation was restarted from a projection file.

Type:: bool

lobster_version[source]

The LOBSTER version.

Type:: str

number_of_spins[source]

Number of spins.

Type:: int

number_of_threads[source]

Number of threads used.

Type:: int

timing[source]

Timing information.

Type:: dict[str, float]

total_spilling[source]

Total spilling for each spin channel.

Type:: list[float]

warning_lines[source]

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[source]

Get the default filename for LobsterOut.

Returns:: The default filename.
Return type:: str

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

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[source]

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>}[source]

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

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

Bases: LobsterFile

Parser for BWDF.lobster/BWDFCOHP.lobster files.

centers[source]

Bond length centers for the distribution.

Type:: NDArray

bwdf[source]

Bond weighted distribution function.

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

bin_width[source]

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[source]

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[source]

Get the default filename for the BWDF class.

Returns:: Default filename.
Return type:: str

is_cohp: ClassVar[bool] = False[source]

parse_file() → None[source]

Parse BWDF.lobster/BWDFCOHP.lobster file.

Returns:: None

process_data_into_bwdf_centers() → None[source]

Process data into bwdf and centers.

Returns:: None

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

class BWDFCOHP(filename: PathLike | None = None, process_immediately: bool = True, lobster_version: str | None = None)[source]

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[source]

Get the default filename for the BWDFCOHP class.

Returns:: Default filename.
Return type:: str

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

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

Bases: LobsterFile

Parser for LOBSTER matrix files.

matrix_type[source]

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

Type:: str

centers[source]

Atom centers.

Type:: list[str]

orbitals[source]

Orbitals.

Type:: list[str]

matrices[source]

Matrix data for each k-point and spin.

Type:: LobsterMatrixData

efermi[source]

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][source]

Serialize object to a dictionary.

Returns:: Dictionary representation of the object.
Return type:: dict[str, Any]

centers: list[str][source]

classmethod from_dict(d: dict[str, Any]) → Self[source]: Deserialize from dictionary.

classmethod get_default_filename() → str[source]

Get the default filename for the LobsterMatrices class.

Returns:: Default filename.
Return type:: str

get_matrix_type() → str[source]

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[source]

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[source]

matrix_types: ClassVar[set[str]] = {'coefficient', 'hamilton', 'overlap', 'transfer'}[source]

orbitals: list[str][source]

parse_file() → None[source]

Parse matrix data and set instance attributes.

Returns:: None

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

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

Bases: LobsterFile

Parser for MadelungEnergies.lobster files.

madelung_energies_mulliken[source]

Madelung energy (Mulliken).

Type:: float

madelung_energies_loewdin[source]

Madelung energy (Loewdin).

Type:: float

ewald_splitting[source]

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[source]

Get the default filename for MadelungEnergies.

Returns:: Default filename.
Return type:: str

parse_file() → None[source]

Parse MadelungEnergies.lobster file.

Extracts the Ewald splitting parameter and Madelung energies.

Returns:: None

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

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

Bases: LobsterFile

Parser for POLARIZATION.lobster file.

rel_mulliken_pol_vector[source]

Relative Mulliken polarization vector.

Type:: dict[str, float]

rel_loewdin_pol_vector[source]

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[source]

Get the default filename for the Polarization class.

Returns:: Default filename.
Return type:: str

parse_file() → None[source]

Parse POLARIZATION.lobster file.

Returns:: None

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

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

Bases: LobsterFile

Parser for SitePotentials.lobster files.

centers[source]

Atom centers.

Type:: list[str]

site_potentials_mulliken[source]

Mulliken site potentials.

Type:: list[float]

site_potentials_loewdin[source]

Loewdin site potentials.

Type:: list[float]

madelung_energies_mulliken[source]

Madelung energy (Mulliken).

Type:: float

madelung_energies_loewdin[source]

Madelung energy (Loewdin).

Type:: float

ewald_splitting[source]

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[source]

Get the default filename for SitePotentials.

Returns:: Default filename.
Return type:: str

parse_file() → None[source]

Parse SitePotentials.lobster file.

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

Returns:: None

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

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

Bases: LobsterFile

Parser for wave function files from LOBSTER.

Reads wave function files and creates VolumetricData objects.

grid[source]

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

Type:: tuple[int, int, int]

points[source]

Points in real space.

Type:: list[tuple[float, float, float]]

reals[source]

Real parts of the wave function.

Type:: list[float]

imaginaries[source]

Imaginary parts of the wave function.

Type:: list[float]

distances[source]

Distances to the first point in the wave function file.

Type:: list[float]

structure[source]

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[source]

get_volumetricdata_density() → VolumetricData[source]

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

Returns:: Density volumetric data.
Return type:: VolumetricData

get_volumetricdata_imaginary() → VolumetricData[source]

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

Returns:: Imaginary part volumetric data.
Return type:: VolumetricData

get_volumetricdata_real() → VolumetricData[source]

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

Returns:: Real part volumetric data.
Return type:: VolumetricData

parse_file() → None[source]

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[source]

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>}[source]

write_file(filename: PathLike = 'WAVECAR.vasp', part: Literal['real', 'imaginary', 'density'] = 'real') → None[source]

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]]][source]

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)[source]

Bases: LobsterFile

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

is_lcfo[source]

Whether the CHARGE file is from LCFO analysis.

Type:: bool

centers[source]

Atom labels with indices.

Type:: list[str]

mulliken[source]

Mulliken charges for each atom.

Type:: list[float]

loewdin[source]

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+)'[source]

classmethod get_default_filename() → str[source]

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[source]

parse_file() → None[source]

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>}[source]

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

Bases: CHARGE

Parser for CHARGE.LCFO.lobster files.

is_lcfo[source]

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+)'[source]

is_lcfo: ClassVar[bool] = True[source]

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

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

Bases: LobsterFile

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

is_lcfo[source]

Whether the GROSSPOP file is from LCFO analysis.

Type:: bool

populations[source]

Population dictionaries for each atom.

Type:: LobsterPopulations

spins[source]

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[source]

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[source]

parse_file() → None[source]

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>}[source]

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

Bases: GROSSPOP

Parser for GROSSPOP.LCFO.lobster files.

is_lcfo[source]

Whether the GROSSPOP file is in LCFO format.

Type:: bool

populations[source]

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[source]

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