httk.atomistic.wavefunction

Provide NumPy-native plane-wave wavefunctions and VASP WAVECAR adapters.

Attributes

RYTOEV
AUTOA
PI

Classes

PlaneWaveFunctions

Provide a zero-based, NumPy-native collection of plane-wave coefficients.

Functions

wavefunction_overlap(phi1, phi2)	Return the complex overlap of two wavefunctions.
save_vesta(basename, structure, wave, *[, cols])	Save real and imaginary wave components as VASP volumetric files.

Module Contents

httk.atomistic.wavefunction.RYTOEV = 13.605826

httk.atomistic.wavefunction.AUTOA = 0.529177249

httk.atomistic.wavefunction.PI = 3.141592653589793

class httk.atomistic.wavefunction.PlaneWaveFunctions(source=None, *, cell=None, encut=None, kpoints=None, eigenvalues=None, occupations=None, coefficients=None, nplanewaves=None, double_precision=None, gamma_half=None)

Provide a zero-based, NumPy-native collection of plane-wave coefficients.

This is an eager NumPy representation, not a backend or view family. NumPy is required at construction time; install the httk-atomistic[numpy] extra when it is absent.

A WAVECAR does not store whether gamma compression used the x or z half-space. The default interpretation is x; pass gamma_half="z" to load() when loading a z-half gamma WAVECAR. Gamma compression is detected from the k-point and plane-wave count during construction.

Parameters:

• source (Any) – A WAVECAR source or neutral WAVECAR payload, or None for in-memory data.

• cell (Any) – The real-space cell used by the in-memory coefficients.

• encut (Any) – The plane-wave energy cutoff used to generate reciprocal vectors.

• kpoints (Any) – The k-points used by the in-memory coefficients.

• eigenvalues (Any) – The band eigenvalues.

• occupations (Any) – The band occupations.

• coefficients (Any) – The coefficient vectors keyed by zero-based spin, k-point, and band.

• nplanewaves (Any) – The number of plane waves for each k-point, or None to infer it.

• double_precision (Any) – Whether to retain double-precision complex coefficients.

• gamma_half (Any) – The gamma-compression half-space, "x" or "z", if applicable.

Raises:

ImportError – If NumPy is unavailable.

property nspins: int

Return the number of spin channels.

property nkpts: int

Return the number of k-points.

property nbands: int

Return the number of bands.

property encut: float

Return the plane-wave energy cutoff.

property cell: httk.atomistic.models.cell.cell.Cell

Return the real-space cell.

property kpoints: Any

Return the k-point coordinates.

property eigenvalues: Any

Return the band eigenvalues.

property occupations: Any

Return the band occupations.

property nplanewaves: Any

Return the plane-wave count for each k-point.

property double_precision: bool

Return whether coefficients use double precision.

property is_gamma: bool

Return whether the coefficients use gamma compression.

property gamma_half: str | None

Return the detected gamma-compression half-space, if applicable.

property kgrid_size: Any

Return the reciprocal-grid dimensions used for transforms.

close()

Close a file-backed source while retaining cached coefficients and metadata.

property closed: bool

Report whether the file-backed source is closed.

coefficients(spin, kpt, band, *, cache=True)

Return one coefficient vector, using an existing cache even when cache=False.

An uncached source read occurs once and is not stored; cached coefficients remain available after a file-backed source is closed.

Parameters:

• spin (int) – The zero-based spin index.

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

• band (int) – The zero-based band index.

• cache (bool) – Whether to cache a coefficient vector read from the source.

Returns:

The selected coefficient vector.

Raises:

ValueError – If an index is out of range or source coefficients have the wrong length.

Return type:

Any

gvectors(kpt=0, *, gamma=None, gamma_half=None)

Return the reciprocal grid vectors for a k-point.

Parameters:

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

• gamma (bool | None) – Whether to use gamma compression, or the construction default when None.

• gamma_half (str | None) – The gamma-compression half-space, if gamma compression is requested.

Returns:

The reciprocal grid vectors selected by the cutoff.

Raises:

ValueError – If the k-point, gamma flag, or half-space is invalid.

Return type:

Any

realspace_wave(spin, kpt, band, *, norm=True)

Transform coefficients to a real-space wave using NumPy FFTs.

The transform uses numpy.fft with norm="ortho". Gamma-compressed coefficients are expanded according to the detected half-space before the transform.

Parameters:

• spin (int) – The zero-based spin index.

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

• band (int) – The zero-based band index.

• norm (bool) – Whether to normalize the resulting wave to unit norm.

Returns:

The real-space wave on the reciprocal grid.

Raises:

ValueError – If an index is out of range or the stored gamma metadata is invalid.

Return type:

Any

select(spins=None, kpts=None, bands=None, *, format=None, gamma_half='x')

Select spins, k-points, and bands, optionally converting coefficient format.

Indices are zero-based and must be unique. Converting standard coefficients to gamma format derives a signed real wave from the standard complex wave and therefore destroys phase information; converting gamma coefficients to standard format expands the stored half-space. A gamma selection must contain exactly one gamma-point k-point.

Parameters:

• spins (collections.abc.Sequence[int] | None) – The zero-based spin indices to retain, or all spins when None.

• kpts (collections.abc.Sequence[int] | None) – The zero-based k-point indices to retain, or all k-points when None.

• bands (collections.abc.Sequence[int] | None) – The zero-based band indices to retain, or all bands when None.

• format (str | None) – The requested coefficient format, "std", "gamma", or None.

• gamma_half (str) – The target gamma-compression half-space.

Returns:

A new in-memory collection containing the selected data.

Raises:

ValueError – If indices, format, gamma selection, or half-space conversion is invalid.

Return type:

PlaneWaveFunctions

httk.atomistic.wavefunction.wavefunction_overlap(phi1, phi2)

Return the complex overlap of two wavefunctions.

Parameters:

• phi1 (Any) – The first wavefunction.

• phi2 (Any) – The second wavefunction.

Returns:

The conjugate-inner-product overlap.

Raises:

ValueError – If the wavefunctions do not have matching shapes.

Return type:

complex

httk.atomistic.wavefunction.save_vesta(basename, structure, wave, *, cols=10)

Save real and imaginary wave components as VASP volumetric files.

The files are written as <basename>_r.vasp and <basename>_i.vasp.

Parameters:

• basename (str) – The output filename prefix.

• structure (Any) – The structure supplying the volumetric-file cell and species metadata.

• wave (Any) – The three-dimensional complex wave to write.

• cols (int) – The number of values written per output line.

Raises:

• ImportError – If NumPy is not installed.

• ValueError – If wave is not a three-dimensional complex array.