potential

Potential functions.

jrystal.potential.effective(density_grid: Float[Array, 'x y z'], position: Float[Array, 'num_atom 3'], charge: Float[Array, 'num_atom'], g_vector_grid: Float[Array, 'x y z 3'], vol: Float, split: bool = False, xc: str = 'lda', kohn_sham: bool = False, spin_restricted: bool = True) → Tuple[Float[Array, 'x y z'], Float[Array, 'x y z'], Float[Array, 'x y z']] | Float[Array, 'x y z']

Calculate the effective potential for electronic structure calculations.

The effective potential is the sum of three contributions:

\[V_{\text{eff}}(\mathbf{r}) = V_H(\mathbf{r}) + V_{\text{ext}}(\mathbf{r}) + V_{xc}(\mathbf{r})\]

where:

• \(V_H(\mathbf{r})\) is the Hartree potential

• \(V_{\text{ext}}(\mathbf{r})\) is the external (nuclear) potential

• \(V_{xc}(\mathbf{r})\) is the exchange-correlation potential

Warning

Currently supports only LDA exchange-correlation functional.

Parameters:

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

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

• charge (Float[Array, "num_atom"]) – Nuclear charges.

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

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

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

• xc (str, optional) – Exchange-correlation functional type. Only “lda” is currently supported. Defaults to “lda”.

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

• spin_restricted (bool, optional) – If True, use spin-restricted calculation. Defaults to True.

Returns:

If split is True, returns (Hartree, external, exchange-correlation) potentials. Otherwise returns their sum as the total effective potential.

Return type:

Union[Tuple[Array, Array, Array], Array]

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

Calculate the external potential in real space.

Computes the external potential by applying inverse Fourier transform to the reciprocal space potential. The real-space external potential represents the Coulomb interaction between electrons and nuclei:

\[V_{\text{ext}}(\mathbf{r}) = \mathcal{F}^{-1}[\hat{V}_{\text{ext}}(\mathbf{G})]\]

where:

• \(V_{\text{ext}}(\mathbf{r})\) is the external potential in real space

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

• \(\mathcal{F}^{-1}\) denotes the inverse Fourier transform

Parameters:

• 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) – Volume of the unit cell.

Returns:

External potential in real space.

Return type:

Complex[Array, ‘x y z’]

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

Calculate the external potential in reciprocal space.

The external potential represents the Coulomb interaction between electrons and nuclei. In reciprocal space, it is computed as a sum over atomic contributions:

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

where:

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

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

• \(v(\mathbf{G}) = -4\pi/|\mathbf{G}|^2\) is the Coulomb potential in reciprocal space

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

Parameters:

• 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) – Volume of the unit cell.

Returns:

External potential in reciprocal space.

Return type:

Complex[Array, ‘x y z’]

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

Calculate the Hartree potential in real space.

Computes the Hartree potential by applying inverse Fourier transform to the reciprocal space potential. The real-space Hartree potential represents the classical electrostatic interaction between electrons:

\[V_H(\mathbf{r}) = \mathcal{F}^{-1}[\hat{V}_H(\mathbf{G})]\]

where:

• \(V_H(\mathbf{r})\) is the Hartree potential in real space

• \(\hat{V}_H(\mathbf{G})\) is the Hartree potential in reciprocal space

• \(\mathcal{F}^{-1}\) denotes the inverse Fourier transform

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.

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

Returns:

Hartree potential in real space. If density_grid_reciprocal has batch axes, they are preserved in the output.

Return type:

Complex[Array, ‘x y z’]

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

Calculate the Hartree potential in reciprocal space.

The Hartree potential represents the classical electrostatic interaction between electrons. In reciprocal space, it obeys the following equation:

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

where:

• \(\hat{V}_H(\mathbf{G})\) is the Hartree potential in reciprocal space

• \(\hat{n}(\mathbf{G})\) is the electron density in reciprocal space

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

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.

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

Returns:

Hartree potential in reciprocal space. If density_grid_reciprocal has batch axes, they are preserved in the output.

Return type:

Complex[Array, ‘x y z’]

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

Calculate the LDA exchange-correlation potential.

Implements the Local Density Approximation (LDA) for the exchange-correlation potential in the spin-unpolarized case. The potential is obtained as the functional derivative of the LDA energy:

\[v_{xc}^{\text{LDA}}(\mathbf{r}) = -\left(\frac{3\rho(\mathbf{r})}{\pi} \right)^{1/3}\]

where:

• \(\rho(\mathbf{r})\) is the electron density

• \(v_{xc}^{\text{LDA}}\) is the exchange-correlation potential

Parameters:

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

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

Returns:

LDA exchange-correlation potential.

Return type:

Float[Array, ‘x y z’]