ddpc.io package¶

Subpackages¶

Submodules¶

ddpc.io.band module¶

Read band data from output files.

ddpc.io.band.read_band(p: str | Path, mode: int = 5, fmt: str = '8.3f') → tuple[DataFrame, float, bool][source]¶

Read and process electronic band structure data from HDF5 or JSON files.

This function provides a unified interface for reading band structure data from DFT calculations, supporting both total and projected band structures with automatic format detection and data formatting.

Parameters:¶

p : str or pathlib.Path¶

Path to the band structure data file. Supported formats are HDF5 (.h5) and JSON (.json) files from DFT calculations.

mode : int, default 5¶

Projection mode for projected band structure data. Only relevant when the file contains orbital-projected information. Different modes correspond to different orbital groupings (s, p, d, f, etc.).

Returns:¶

• DataFrame containing band structure data with k-points and energies

• Fermi energy in eV

• Boolean indicating whether the data contains orbital projections

Return type:¶

tuple of (polars.DataFrame, float, bool)

Raises:¶

TypeError – If the input file is neither HDF5 nor JSON format.

Notes

The function automatically detects file format based on extension and processes the data accordingly. For projected band structures, the mode parameter determines which orbital contributions are included in the output. The DataFrame includes k-point coordinates, distances, and band energies, with spin-polarized calculations having separate up/down columns.

ddpc.io.band.read_band_h5(absfile: str, mode: int) → tuple[DataFrame, float, bool][source]¶

Read band structure data from HDF5 file format.

This function processes HDF5 files containing electronic band structure data from DFT calculations, handling both total and projected band structures with proper metadata extraction.

Parameters:¶

absfile : str or pathlib.Path¶

Path to the HDF5 band structure file (typically with .h5 extension).

mode : int¶

Projection mode for orbital-projected band structure data. Mode 0 forces total band structure regardless of projection availability.

Returns:¶

• DataFrame containing processed band structure data

• Fermi energy in eV extracted from the file

• Boolean indicating presence of orbital projection data

Return type:¶

tuple of (polars.DataFrame, float, bool)

Raises:¶

• TypeError – If the HDF5 file doesn’t contain the required ‘BandInfo’ group.

• SystemExit – If critical metadata (Fermi energy or projection info) cannot be read.

Notes

The function expects HDF5 files with a specific structure containing:

• /BandInfo/EFermi: Fermi energy value

• /BandInfo/IsProject: Boolean indicating orbital projections

• Band energy datasets organized by spin channels

For projected data, the mode parameter determines which orbital contributions are included in the final DataFrame.

ddpc.io.band.read_band_json(absfile: str, mode: int) → tuple[DataFrame, float, bool][source]¶

Read band structure data from JSON file format.

This function processes JSON files containing electronic band structure data from DFT calculations, providing an alternative to HDF5 format with the same functionality for band structure analysis.

Parameters:¶

absfile : str or pathlib.Path¶

Path to the JSON band structure file (typically with .json extension).

mode : int¶

Projection mode for orbital-projected band structure data. Mode 0 forces total band structure regardless of projection availability.

Returns:¶

• DataFrame containing processed band structure data

• Fermi energy in eV extracted from the file

• Boolean indicating presence of orbital projection data

Return type:¶

tuple of (polars.DataFrame, float, bool)

Notes

The function expects JSON files with the same logical structure as HDF5 files but in JSON format. The data organization includes:

• BandInfo/EFermi: Fermi energy value

• BandInfo/IsProject: Boolean indicating orbital projections

• Band energy arrays organized by spin channels

JSON format may be preferred for smaller datasets or when HDF5 is not available, though it’s generally less efficient for large band structures.

ddpc.io.band.read_pband_h5(band: File, mode: int) → DataFrame[source]¶

Read orbital-projected band structure data from HDF5 file.

This function extracts and processes orbital-projected electronic band structure data, providing detailed information about atomic orbital contributions to each band at every k-point.

Parameters:¶

band : h5py.File¶

Opened HDF5 file object containing projected band structure data.

mode : int¶

Projection mode determining which orbital contributions to include. Different modes correspond to different orbital groupings and processing schemes for the projection data.

Returns:¶

DataFrame containing projected band structure with columns:

• label: High-symmetry k-point labels

• kx, ky, kz: k-point coordinates

• dist: Cumulative distance along k-path

• Orbital projection columns:

  • ”{atom_index}{orbital}-{spin}” for spin-polarized

  • ”{atom_index}{orbital}” for non-spin-polarized

Return type:¶

polars.DataFrame

Notes

The function processes orbital projection data organized by atom indices and orbital types (s, p, d, f, etc.). For spin-polarized calculations, separate up and down spin projections are included.

The projection data represents the weight of each atomic orbital in the electronic wavefunctions, useful for analyzing chemical bonding and orbital character of electronic states.

ddpc.io.band.read_pband_json(band: dict, mode: int) → DataFrame[source]¶

Read orbital-projected band structure data from JSON file.

This function extracts and processes orbital-projected electronic band structure data from JSON format files, providing the same functionality as the HDF5 reader but for JSON-based data storage.

Parameters:¶

band : dict¶

Dictionary containing projected band structure data loaded from JSON.

mode : int¶

Projection mode determining which orbital contributions to include and how they are processed and grouped in the output.

Returns:¶

DataFrame containing projected band structure with columns:

• label: High-symmetry k-point labels

• kx, ky, kz: k-point coordinates

• dist: Cumulative distance along k-path

• Processed orbital projections based on the specified mode

Return type:¶

polars.DataFrame

Notes

The function processes JSON-formatted orbital projection data with the same logical structure as HDF5 files. The mode parameter determines the level of detail and grouping for orbital contributions.

ddpc.io.band.read_tband(band: File | dict, h5: bool = True) → DataFrame[source]¶

Read total (non-projected) band structure data from file.

This function extracts and processes total electronic band structure data without orbital projections, handling both spin-polarized and non-spin- polarized calculations from HDF5 or JSON sources.

Parameters:¶

band : h5py.File or dict¶

Band structure data container, either an opened HDF5 file object or a dictionary loaded from JSON.

h5 : bool, default True¶

Flag indicating the data source format. True for HDF5, False for JSON.

Returns:¶

DataFrame containing band structure with columns:

• label: High-symmetry k-point labels

• kx, ky, kz: k-point coordinates

• dist: Cumulative distance along k-path

• band1, band2, …: Band energies (with -up/-down suffix for spin-polarized)

Return type:¶

polars.DataFrame

Notes

The function handles different data layouts between HDF5 and JSON formats, automatically detecting spin polarization and organizing band energies accordingly. For collinear spin calculations, separate up and down spin channels are included with appropriate column naming.

K-point distances are calculated as cumulative path lengths between consecutive k-points, useful for band structure plotting.

ddpc.io.dos module¶

Read data from output files.

ddpc.io.dos.read_dos(p: str | Path, mode: int = 5) → tuple[DataFrame, float, bool][source]¶

Read and process electronic density of states data from HDF5 or JSON files.

This function provides a unified interface for reading density of states (DOS) data from DFT calculations, supporting both total and projected DOS with automatic format detection and data formatting.

Parameters:¶

p : str or pathlib.Path¶

Path to the DOS data file. Supported formats are HDF5 (.h5) and JSON (.json) files from DFT calculations.

mode : int, default 5¶

Projection mode for projected density of states data. Only relevant when the file contains orbital-projected information. Different modes correspond to different orbital groupings: 1: s/p/d/f orbitals 2: detailed orbitals (px, py, pz, etc.) 3: by element 4: atom + s/p/d/f orbitals 5: atom + detailed orbitals 6: atom + t2g/eg orbitals 7: atom-projected (sum all orbitals per atom)

Returns:¶

• DataFrame containing DOS data with energy points and DOS values

• Fermi energy in eV

• Boolean indicating whether the data contains orbital projections

Return type:¶

tuple of (polars.DataFrame, float, bool)

Raises:¶

TypeError – If the input file is neither HDF5 nor JSON format.

Notes

The function automatically detects file format based on extension and processes the data accordingly. For projected DOS, the mode parameter determines which orbital contributions are included in the output. The DataFrame includes energy points and DOS values, with spin-polarized calculations having separate up/down columns.

ddpc.io.dos.read_dos_h5(absfile: str, mode: int) → tuple[DataFrame, float, bool][source]¶

Read density of states data from HDF5 file format.

Parameters:¶

absfile : str¶

Path to the HDF5 DOS file (typically with .h5 extension).

mode : int¶

Projection mode for orbital-projected DOS data. Mode 0 forces total DOS regardless of projection availability.

Returns:¶

• DataFrame containing processed DOS data

• Fermi energy in eV extracted from the file

• Boolean indicating presence of orbital projection data

Return type:¶

tuple of (polars.DataFrame, float, bool)

ddpc.io.dos.read_dos_json(absfile: str, mode: int) → tuple[DataFrame, float, bool][source]¶

Read density of states data from JSON file format.

Parameters:¶

absfile : str¶

Path to the JSON DOS file (typically with .json extension).

mode : int¶

Projection mode for orbital-projected DOS data. Mode 0 forces total DOS regardless of projection availability.

Returns:¶

• DataFrame containing processed DOS data

• Fermi energy in eV extracted from the file

• Boolean indicating presence of orbital projection data

Return type:¶

tuple of (polars.DataFrame, float, bool)

ddpc.io.dos.read_pdos_h5(dos: File, mode: int) → DataFrame[source]¶

Read orbital-projected density of states data from HDF5 file.

Parameters:¶

dos : h5py.File¶

Opened HDF5 file object containing projected DOS data.

mode : int¶

Projection mode determining which orbital contributions to include.

Returns:¶

DataFrame containing projected DOS with orbital contributions.

Return type:¶

polars.DataFrame

ddpc.io.dos.read_pdos_json(dos: dict, mode: int) → DataFrame[source]¶

Read orbital-projected density of states data from JSON file.

Parameters:¶

dos : dict¶

Dictionary containing projected DOS data loaded from JSON.

mode : int¶

Projection mode determining which orbital contributions to include.

Returns:¶

DataFrame containing projected DOS with orbital contributions.

Return type:¶

polars.DataFrame

ddpc.io.dos.read_tdos(dos: File | dict, h5: bool = True) → DataFrame[source]¶

Read total (non-projected) density of states data.

Parameters:¶

dos : h5py.File or dict¶

DOS data container, either an opened HDF5 file object or a dictionary loaded from JSON.

h5 : bool, default True¶

Flag indicating the data source format. True for HDF5, False for JSON.

Returns:¶

DataFrame containing total DOS with energy points and DOS values.

Return type:¶

polars.DataFrame

ddpc.io.structure module¶

Wrapper for structure data loading.

ddpc.io.structure.read_single_structure(p: str | Path)[source]¶

Read the first structure from a file containing one or more structures.

This function reads crystal structures from various file formats and ensures that only a single Atoms object is returned. If the file contains multiple structures (e.g., trajectory files), only the first one is returned.

Parameters:¶

p : str or pathlib.Path¶

Path to the structure file. Supported formats include:

• .as : DS-PAW atomic structure format

• .xyz : RESCU XYZ format

• Other formats supported by ASE (POSCAR, CIF, etc.)

Returns:¶

Single crystal structure as an ASE Atoms object. If the input file contains multiple structures, only the first one is returned.

Return type:¶

ase.atoms.Atoms

Notes

This function is particularly useful when working with trajectory files or formats that can contain multiple structures, but you only need the first structure for analysis.

ddpc.io.structure.read_structure(p: str | Path)[source]¶

Read crystal structure from various file formats.

This function provides a unified interface for reading crystal structures from different file formats. It automatically detects the format based on file extension and uses the appropriate reader.

Parameters:¶

p : str or pathlib.Path¶

Path to the structure file. Supported formats include:

• .as : DS-PAW atomic structure format

• .xyz : RESCU XYZ format

• Other formats supported by ASE (POSCAR, CIF, etc.)

Returns:¶

Crystal structure(s) as ASE Atoms object(s). Some formats may return multiple structures (e.g., trajectory files).

Return type:¶

ase.atoms.Atoms or list of ase.atoms.Atoms

Notes

The function uses format-specific readers for:

• DS-PAW .as files: Custom reader supporting lattice/atom constraints and magnetism

• RESCU .xyz files: Custom reader supporting magnetic moments and constraints

• Other formats: ASE’s built-in readers

ddpc.io.structure.write_structure(p: str | Path, atoms: Atoms | list[Atoms], file_format: str | None = None, **kwargs) → str[source]¶

Write crystal structure(s) to file in various formats.

This function provides a unified interface for writing crystal structures to different file formats. It automatically detects the format based on file extension or uses the explicitly specified format.

Parameters:¶

p : str or pathlib.Path¶

Path to the output file. The file extension determines the format if file_format is not specified.

atoms : ase.atoms.Atoms or list of ase.atoms.Atoms¶

Crystal structure(s) to write. Some formats support multiple structures.

file_format : str, optional¶

Explicit file format specification. If None, format is determined from file extension. Supported formats include:

• ’as’ : DS-PAW atomic structure format

• ’xyz’ : RESCU XYZ format

• Other formats supported by ASE (‘vasp’, ‘cif’, etc.)

**kwargs¶

Additional keyword arguments passed to the format-specific writer.

Returns:¶

String representation of the written structure file content.

Return type:¶

str

Raises:¶

ValueError – If trying to write multiple structures to a format that only supports single structures (.as or .xyz formats).

Notes

Format-specific behaviors:

• DS-PAW .as format: Only supports single Atoms objects, preserves constraints

• RESCU .xyz format: Only supports single Atoms objects, preserves magnetism

• Other formats: Use ASE’s built-in writers with full feature support

Examples

>>> content = write_structure("output.vasp", atoms, file_format="vasp")
>>> content = write_structure("structure.as", atoms)
>>> content = write_structure("trajectory.xyz", atoms_list)

ddpc.io.utils module¶

Utility functions for read/write data.

ddpc.io.utils.absf(p: str | Path) → Path[source]¶

Return absolute path of a file or directory.

This function converts a relative or absolute path to an absolute path by resolving all symbolic links and relative path components.

Parameters:¶

p : str or pathlib.Path¶

File or directory path to convert to absolute path.

Returns:¶

Absolute path object with all symbolic links resolved.

Return type:¶

pathlib.Path

ddpc.io.utils.get_h5_str(f: str | File, key: str) → list[source]¶

Read string data from HDF5 file and return as list of elements.

This function extracts string data from an HDF5 file at the specified key and returns it as a list of strings. It’s commonly used to read element information from DFT calculation output files.

Parameters:¶

f : str or h5py.File¶

HDF5 file path as string or already opened h5py.File object.

key : str¶

HDF5 dataset key/path to read from, e.g., “/AtomInfo/Elements”.

Returns:¶

List of string elements extracted from the HDF5 dataset.

Return type:¶

list of str

Raises:¶

TypeError – If the input file parameter is neither a string nor h5py.File object.

Notes

The function handles HDF5 string data that may be stored as bytes and automatically decodes it to strings. Multiple ion steps in MD simulations typically only save element information in the initial structure.

ddpc.io.utils.remove_comments(p: str | Path, comment: str = '#') → list[source]¶

Remove all comments from a text file and return non-empty lines.

This function reads a text file, removes all comments (lines starting with or containing the comment character), and returns a list of non-empty lines with leading/trailing whitespace stripped.

Parameters:¶

p : str or pathlib.Path¶

Path to the input text file to process.

comment : str, default "#"¶

Comment character or string. Everything from this character to the end of the line will be removed.

Returns:¶

List of non-empty lines with comments removed and whitespace stripped.

Return type:¶

list of str

Notes

The function processes files line by line and:

1. Removes everything from the comment character to the end of each line

2. Strips leading and trailing whitespace

3. Excludes empty lines from the result

4. Uses UTF-8 encoding for file reading

Module contents¶