braket

braket#

Integration operations for quantum mechanical calculations in real and reciprocal space.

This module provides functions for calculating inner products (brakets) and expectation values in both real and reciprocal space, which are fundamental operations in quantum mechanics and density functional theory (DFT) calculations.

jrystal._src.braket.expectation(bra: Complex[Array, 'spin kpt band x y z'] | Float[Array, 'spin kpt band x y z'], hamiltonian: Complex[Array, 'spin kpt band x y z'] | Float[Array, 'spin kpt band x y z'], vol: Float, ket: Complex[Array, 'spin kpt band x y z'] | Float[Array, 'spin kpt band x y z'] | None = None, diagonal: bool = False, mode: str = 'real') → Array[source]#

Calculate the expectation value of a Hamiltonian operator.

Computes matrix elements of the form:

\[E_{ij} = \langle \psi_i | \hat{H} | \psi_j \rangle \approx \sum_{\mathbf{q}} \psi_i^*(\mathbf{q}) \hat{H}(\mathbf{q}) \psi_j(\mathbf{q}) \frac{vol}{N^p}\]

where \(\psi_i\) and \(\psi_j\) are wavefunctions, \(\hat{H}\) is the Hamiltonian operator, \(\mathbf{q}\) represents either real (\(\mathbf{r}\)) or reciprocal (\(\mathbf{G}\)) space coordinates, and \(p\) depends on the mode:

  • For real space: \(p = 1\)

  • For reciprocal space: \(p = 2\) (includes Parseval factor)

  • For kinetic terms: \(p = 0\)

For more details on expectation values in quantum mechanics, see: https://en.wikipedia.org/wiki/Expectation_value_(quantum_mechanics)

Parameters:

  • bra (Complex[Array, 'spin kpt band x y z'] | Float[Array, 'spin kpt band x y z']) – Left wavefunction in the expectation value calculation. Must have shape (spin, kpt, band, x, y, z).

  • hamiltonian (Complex[Array, 'spin kpt band x y z'] | Float[Array, 'spin kpt band x y z']) – Hamiltonian operator matrix. Must have shape (spin, kpt, band, x, y, z).

  • vol (Float) – Volume of the unit cell.

  • ket (Complex[Array, 'spin kpt band x y z'] | Float[Array, 'spin kpt band x y z']) – Right wavefunction. If None, uses the bra wavefunction (for diagonal elements). Must have same shape as bra if provided.

  • diagonal (bool) – If True, only compute diagonal elements \(E_{ii}\). If False, compute full matrix \(E_{ij}\).

  • mode (str) – Integration mode determining the normalization factors: - ‘real’: Real space integration (\(vol/N\)) - ‘reciprocal’: Reciprocal space (includes \(1/N\) Parseval factor) - ‘kinetic’: Special case with unit factor

Returns:

Array of expectation values. Shape depends on diagonal parameter:

  • If diagonal=True: shape (spin, kpt, band)

  • If diagonal=False: shape (spin, kpt, band, band)

Return type:

Array

jrystal._src.braket.real_braket(bra: Complex[Array, '*n x y z'] | Float[Array, '*n x y z'], ket: Complex[Array, '*n x y z'] | Float[Array, '*n x y z'], vol: Float) → Float[source]#

Calculate the inner product of two functions in real space.

Computes the inner product between two wavefunctions in real space using:

\[\langle f|g \rangle \approx \sum_{\mathbf{r}} f^*(\mathbf{r})g(\mathbf{r}) \frac{vol}{N}\]

where \(f^*(\mathbf{r})\) is the complex conjugate of \(f(\mathbf{r})\), \(N\) is the number of grid points, and \(vol\) is the unit cell volume.

Note

This formulation is commonly used in planewave DFT for calculating exchange-correlation energy integrals, which are typically evaluated in real space for efficiency.

Parameters:

  • bra (Complex[Array, ‘*n x y z’] | Float[Array, ‘*n x y z’]) – Wavefunction in real space (left side of braket). Shape must match ket’s shape.

  • ket (Complex[Array, ‘*n x y z’] | Float[Array, ‘*n x y z’]) – Wavefunction in real space (right side of braket). Shape must match bra’s shape.

  • vol (Float) – Volume of the unit cell.

Returns:

The real-valued inner product result.

Return type:

Float

Raises:

ValueError – If bra and ket shapes do not match.

jrystal._src.braket.reciprocal_braket(bra: Complex[Array, '*n x y z'] | Float[Array, '*n x y z'], ket: Complex[Array, '*n x y z'] | Float[Array, '*n x y z'], vol: Float) → Float[source]#

Calculate the inner product of two functions in reciprocal space.

Computes the inner product between two wavefunctions in reciprocal space using:

\[\langle f|g \rangle \approx \sum_{\mathbf{G}} f^*(\mathbf{G})g(\mathbf{G}) \frac{vol}{N^2}\]

where \(f^*(\mathbf{G})\) is the complex conjugate of \(f(\mathbf{G})\), \(N\) is the number of grid points, and \(vol\) is the real-space unit cell volume.

Note

This formulation is particularly useful for calculating hartree and external energy integrals in reciprocal space, as they often have simpler forms than in real space.

Parameters:

  • bra (Complex[Array, ‘*n x y z’] | Float[Array, ‘*n x y z’]) – Wavefunction in reciprocal space (left side of braket). Shape must match ket’s shape.

  • ket (Complex[Array, ‘*n x y z’] | Float[Array, ‘*n x y z’]) – Wavefunction in reciprocal space (right side of braket). Shape must match bra’s shape.

  • vol (Float) – Volume of the real-space unit cell.

Returns:

The real-valued inner product result.

Return type:

Float

Raises:

ValueError – If bra and ket shapes do not match.

Contents