energy

Energy functions.

jrystal.energy.band_energy(coefficient: Complex[Array, 'spin kpt band x y z'], position: Float[Array, 'atom 3'], charge: Int[Array, 'atom'], g_vector_grid: Float[Array, 'x y z 3'], kpts: Float[Array, 'kpt 3'], vol: Float, occupation: Float[Array, 'spin kpt band'], kohn_sham: bool = False, xc: str = 'lda')

Calculate the energy eigenvalues for each electronic state.

Computes the energy eigenvalues by evaluating the expectation value of the single-particle Hamiltonian for each state:

\[\varepsilon_{n\mathbf{k}} = \langle \psi_{n\mathbf{k}} | \hat{T} + \hat{V}_{\text{eff}} | \psi_{n\mathbf{k}} \rangle\]

where \(\hat{T}\) is the kinetic energy operator and \(\hat{V}_{\text{eff}}\) is the effective potential operator.

Parameters:

• coefficient (Complex[Array, "spin kpt band x y z"]) – Plane wave coefficients.

• position (Float[Array, "atom 3"]) – Atomic positions in the unit cell.

• charge (Int[Array, "atom"]) – Nuclear charges.

• g_vector_grid (Float[Array, "x y z 3"]) – Grid of G-vectors in reciprocal space.

• kpts (Float[Array, "kpt 3"]) – k-points in reciprocal space.

• vol (Float) – Unit cell volume.

• occupation (Float[Array, "spin kpt band"]) – Occupation numbers.

• kohn_sham (bool, optional) – If True, use Kohn-Sham formalism. Defaults to False.

• xc (str, optional) – Exchange-correlation functional type. Defaults to ‘lda’.

Returns:

Energy eigenvalues for each electronic state.

Return type:

Float[Array, “spin kpt band”]

jrystal.energy.external(density_grid_reciprocal: Complex[Array, 'x y z'], position: Float[Array, 'atom 3'], charge: Float[Array, 'atom'], g_vector_grid: Float[Array, 'x y z 3'], vol: Float) → Float

Calculate the external potential energy.

The external potential energy is computed using Parseval’s identity, expressing the real-space integral as a sum over reciprocal lattice vectors:

\[E = \sum_{\mathbf{G}} \hat{\rho}(\mathbf{G})\hat{V}_{\text{ext}}(\mathbf{G}) = \sum_{\mathbf{G}} \hat{\rho}(\mathbf{G}) \sum_{\alpha} Z_{\alpha} \exp(-i\mathbf{G}\cdot\mathbf{R}_{\alpha}) v(\mathbf{G})\]

where:

• \(\hat{\rho}(\mathbf{G})\) is the Fourier transform of the electron density, i.e. the density in reciprocal space.

• \(\hat{V}_{\text{ext}}(\mathbf{G})\) is the external potential in reciprocal space

• \(Z_{\alpha}\) is the nuclear charge of atom \(\alpha\)

• \(\mathbf{R}_{\alpha}\) is the position of atom \(\alpha\)

• \(v(\mathbf{G})\) is the Fourier transform of the Coulomb potential

Parameters:

• density_grid_reciprocal (Complex[Array, 'x y z']) – Electron density in reciprocal space.

• position (Float[Array, 'atom 3']) – Atomic positions in the unit cell.

• charge (Float[Array, 'atom']) – Nuclear charges.

• g_vector_grid (Float[Array, 'x y z 3']) – Grid of G-vectors in reciprocal space.

• vol (Float) – Unit cell volume.

Returns:

External potential energy.

Return type:

Float

jrystal.energy.hartree(density_grid_reciprocal: Complex[Array, 'x y z'], g_vector_grid: Float[Array, 'x y z 3'], vol: Float, kohn_sham: bool = False) → Float

Calculate the Hartree energy.

The Hartree energy represents the classical electrostatic interaction between electrons. The calculation is performed in reciprocal space for efficiency. The Hartree potential in reciprocal space is given by:

\[\hat{V}_H(\mathbf{G}) = 4\pi \frac{\hat{\rho}(\mathbf{G})}{|\mathbf{G}|^2}, \quad \hat{V}_H(\mathbf{0}) = 0\]

The Hartree energy is computed as:

\[E_H = \frac{1}{2}\sum_{\mathbf{G}} \hat{\rho}(\mathbf{G})\hat{V}_{H}(\mathbf{G}) = 2\pi \sum_{\mathbf{G}} \frac{|\hat{\rho}(\mathbf{G})|^2}{|\mathbf{G}|^2}\]

Please also refer to the tutorial Total Energy Minimization for more details.

Parameters:

• density_grid_reciprocal (Complex[Array, 'x y z']) – Electron density in reciprocal space.

• g_vector_grid (Float[Array, 'x y z 3']) – Grid of G-vectors in reciprocal space.

• vol (Float) – Unit cell volume.

• kohn_sham (bool, optional) – If True, use Kohn-Sham formalism. Defaults to False.

Returns:

Hartree energy.

Return type:

Float

jrystal.energy.kinetic(g_vector_grid: Float[Array, 'x y z 3'], kpts: Float[Array, 'kpt 3'], coeff_grid: Complex[Array, 'spin kpt band x y z'], occupation: Float[Array, 'spin kpt band'] | None = None) → Float | Float[Array, 'spin kpt band']

Calculate the kinetic energy.

For plane wave basis, the kinetic energy operator is diagonal in reciprocal space. The kinetic energy is computed as:

\[E_{\text{kin}} = \frac{1}{2} \sum_{\mathbf{G}} |\mathbf{k} + \mathbf{G}|^2 |c_{n\mathbf{k}}(\mathbf{G})|^2\]

where:

• \(\mathbf{k}\) is the k-point vector

• \(\mathbf{G}\) is the reciprocal lattice vector

• \(c_{n\mathbf{k}}(\mathbf{G})\) are the plane wave coefficients

• \(n\) is the band index

Parameters:

• g_vector_grid (Float[Array, 'x y z 3']) – Grid of G-vectors in reciprocal space.

• kpts (Float[Array, 'kpt 3']) – k-points in reciprocal space.

• coeff_grid (Complex[Array, 'spin kpt band x y z']) – Plane wave coefficients.

• occupation (Float[Array, 'spin kpt band'], optional) – Occupation numbers. If provided, returns the total kinetic energy weighted by occupations.

Returns:

If occupation is provided, returns the total kinetic energy. Otherwise, returns the kinetic energy for each state.

Return type:

Union[Float, Float[Array, “spin kpt band”]]

jrystal.energy.nuclear_repulsion(position: Float[Array, 'atom 3'], charge: Float[Array, 'atom'], cell_vectors: Float[Array, '3 3'], g_vector_grid: Float[Array, 'x y z 3'], vol: Float, ewald_eta: float, ewald_cutoff: float) → Float

Compute the nuclear repulsion energy using Ewald summation.

This function calculates the nuclear-nuclear repulsion energy in periodic systems using the Ewald summation technique.

Parameters:

• position (Float[Array, 'atom 3']) – Coordinates of atoms in a unit cell.

• charge (Float[Array, 'atom']) – Nuclear charges of atoms.

• cell_vectors (Float[Array, '3 3']) – Unit cell vectors.

• g_vector_grid (Float[Array, 'x y z 3']) – Grid of G-vectors in reciprocal space.

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

• ewald_eta (float) – Ewald splitting parameter.

• ewald_cutoff (float) – Real-space cutoff for Ewald summation.

Returns:

Nuclear-nuclear repulsion energy.

Return type:

Float

jrystal.energy.total_energy(coefficient: Complex[Array, 'spin kpts band x y z'], position: Float[Array, 'atom 3'], charge: Int[Array, 'atom'], g_vector_grid: Float[Array, 'x y z 3'], kpts: Float[Array, 'kpt 3'], vol: Float, occupation: Float[Array, 'spin kpt band'] | None = None, kohn_sham: bool = False, xc: str = 'lda_x', spin_restricted: str = True, split: bool = False) → Float | Tuple[Float, Float, Float, Float]

Calculate the total electronic energy of the system.

Computes the total energy as the sum of kinetic, external potential, Hartree, and exchange-correlation terms:

\[E_{\text{tot}} = E_{\text{kin}} + E_{\text{ext}} + E_H + E_{xc}\]

Warning

This function does not include the nuclear-nuclear repulsion (Ewald) energy. For the complete total energy, the Ewald term must be added separately.

Parameters:

• coefficient (Complex[Array, "spin kpts band x y z"]) – Plane wave coefficients.

• position (Float[Array, "atom 3"]) – Atomic positions in the unit cell.

• charge (Int[Array, "atom"]) – Nuclear charges.

• g_vector_grid (Float[Array, "x y z 3"]) – Grid of G-vectors in reciprocal space.

• kpts (Float[Array, "kpt 3"]) – k-points in reciprocal space.

• vol (Float) – Unit cell volume.

• occupation (Float[Array, "spin kpt band"], optional) – Occupation numbers. If not provided, all states are considered fully occupied.

• kohn_sham (bool, optional) – If True, use Kohn-Sham formalism. Defaults to False.

• xc (str, optional) – Exchange-correlation functional type. Defaults to ‘lda’.

• split (bool, optional) – If True, return individual energy components. Defaults to False.

Returns:

If split is False, returns

the total electronic energy. If split is True, returns the individual components (kinetic, external, Hartree, exchange-correlation).

Return type:

Union[Float, Tuple[Float, Float, Float, Float]]

jrystal.energy.xc_lda(density_grid: Float[Array, 'x y z'], vol: Float, kohn_sham: bool = False) → Float

Calculate the LDA exchange-correlation energy.

Implements the Local Density Approximation (LDA) for the exchange-correlation energy in the spin-unpolarized case. The exchange energy in LDA is given by:

\[E_x^{\text{LDA}}[\rho] = -\frac{3}{4}\left(\frac{3}{\pi}\right)^{1/3} \int \rho(\mathbf{r})^{4/3} d\mathbf{r}\]

Note that this implementation includes both exchange and correlation terms, though only the exchange term is shown in the equation above.

Parameters:

• density_grid (Float[Array, 'x y z']) – Real-space electron density.

• vol (Float) – Unit cell volume.

• kohn_sham (bool, optional) – If True, use Kohn-Sham formalism. Defaults to False.

Returns:

LDA exchange-correlation energy.

Return type:

Float