httk.io.vasp.wavecar

Neutral, numpy-backed VASP WAVECAR binary I/O.

The wavecar value returned by read_wavecar() is a WavecarSource: an object exposing nspins, nkpts, nbands, encut, cell, kpoints, eigenvalues, occupations, nplanewaves, double_precision, and coefficients(spin, kpt, band). WavecarFile also exposes its record_length. The gamma-half orientation is not stored in a WAVECAR; gamma_half is a pass-through hint because the consumer’s default ("x") cannot be inferred from the data. The atomistic phase may provide the same contract for in-memory data without depending on this module’s concrete class.

Classes

WavecarFile

Open a VASP WAVECAR and eagerly read its small metadata headers.

Functions

read_wavecar(source, *[, double_precision, gamma_half])	Read a WAVECAR path into a neutral vasp-wavecar payload.
write_wavecar(destination, payload)	Write a neutral vasp-wavecar payload to a binary path.

Module Contents

class httk.io.vasp.wavecar.WavecarFile(filename, *, double_precision=None)

Open a VASP WAVECAR and eagerly read its small metadata headers.

Public indices are all zero-based. The small metadata headers and band summaries are read eagerly, while each coefficient vector is loaded lazily from its band record. Compressed paths are refused because random access cannot stream decompression. cell has shape (3, 3), kpoints has shape (nkpts, 3), the eigenvalue and occupation arrays have shape (nspins, nkpts, nbands), and nplanewaves has shape (nkpts,).

Parameters:

• filename (str | os.PathLike[str]) – Filesystem path to an uncompressed WAVECAR.

• double_precision (bool | None) – Override the precision indicated by the WAVECAR header.

nspins: int

nkpts: int

nbands: int

encut: float

cell: Any

kpoints: Any

eigenvalues: Any

occupations: Any

nplanewaves: Any

double_precision: bool

record_length: int

property closed: bool

Whether the underlying WAVECAR file is closed.

close()

Close the WAVECAR file.

coefficients(spin, kpt, band)

Read one zero-based spin/k-point/band coefficient vector.

Parameters:

• spin (int) – Zero-based spin-channel index.

• kpt (int) – Zero-based k-point index.

• band (int) – Zero-based band index.

Returns:

The coefficient vector for the selected band record.

Raises:

ValueError – If the file is closed, an index is invalid, or the record is truncated.

Return type:

Any

httk.io.vasp.wavecar.read_wavecar(source, *, double_precision=None, gamma_half=None)

Read a WAVECAR path into a neutral vasp-wavecar payload.

Parameters:

• source (str | os.PathLike[str]) – Filesystem path to an uncompressed WAVECAR.

• double_precision (bool | None) – Override the precision indicated by the WAVECAR header.

• gamma_half (str | None) – Consumer hint for the gamma-half orientation, or None when unspecified.

Returns:

A payload containing the lazy WAVECAR source and the gamma-half hint.

Raises:

ValueError – If an option is invalid, compression is present, or the file is malformed.

Return type:

dict[str, Any]

httk.io.vasp.wavecar.write_wavecar(destination, payload)

Write a neutral vasp-wavecar payload to a binary path.

Parameters:

• destination (str | os.PathLike[str]) – Filesystem path for the uncompressed binary output.

• payload (collections.abc.Mapping[str, Any]) – Neutral payload containing a WAVECAR source.

Raises:

• ValueError – If the destination or payload cannot represent a WAVECAR.

• TypeError – If the payload is not a mapping.

• KeyError – If the payload mapping does not contain "wavecar".