Ion Utility Functions#
Utility Functions for Reading .recpot Files#
- ion_utils.get_ion_charge(path)#
Reads recpot file to extract ion charge.
- Parameters:
path (string) – Path to recpot file from current directory
- Returns:
Ion charge
- Return type:
int
- ion_utils.interpolate_recpot(path, ks_interp)#
Reads recpot file to get interpolated ion potential.
- Parameters:
path (string) – Path to recpot file from current directory
ks_interp (torch.Tensor) – Reciprocal space grid for which the ionic potential is interpolated over.
- Returns:
Reciprocal space ionic potential
- Return type:
torch.Tensor
Utility Functions for Lattice Convolutions#
Lattice Sum#
- ion_utils.lattice_sum(box_vecs, shape, cart_ion_coords, f_tilde, order=None)#
Performs convolution of lattice with function \(f\) using FFTs and the convolution theorem. Effectively, \(F(\mathbf{r})\) is computed by taking the inverse FFT of
\[\tilde{F}(\mathbf{q}) = \frac{1}{\Omega} S(\mathbf{q}) \tilde{f}(\mathbf{q}),\]where \(\tilde{f}\) is the Fourier transform of \(f\) and \(S(\mathbf{q})\) is the structure factor given by
\[S(\mathbf{q}) = \sum_{i=1}^N e^{-i\mathbf{q}\cdot\mathbf{r}}.\]- Parameters:
box_vecs (torch.Tensor) – Lattice vectors
shape (torch.Size or iterable) – Real-space grid shape
cart_ion_coords (Torch.tensor) – Cartesian ionic coordinates
f_tilde (torch.Tensor) – Fourier transform of function to be convolved
order (None or int) – Order of approximation for structure factor via the Particle-Mesh Ewald scheme, which must be an even integer more than or equal to 2.
Noneindicates that the exact quadratic scaling method is used.
- Returns:
Convolution of the lattice with function \(f\)
- Return type:
torch.Tensor
Exact Structure Factor#
- ion_utils.structure_factor(box_vecs, shape, cart_ion_coords)#
Computes, using the direct \(\mathcal{O}(N^2)\) method, the structure factor given by
\[S(\mathbf{q}) = \sum_{i=1}^N e^{-i\mathbf{q}\cdot\mathbf{r}}.\]- Parameters:
box_vecs (torch.Tensor) – Lattice vectors
shape (torch.Size or iterable) – Real-space grid shape
cart_ion_coords (torch.Tensor) – Cartesian ionic coordinates
- Returns:
Exact structure factor
- Return type:
torch.Tensor
Particle-Mesh Ewald Structure Factor#
- ion_utils.structure_factor_spline(box_vecs, shape, cart_ion_coords, order)#
Computes an approximate structure factor using the Particle-Mesh Ewald scheme based on cardinal B-splines, which is an \(\mathcal{O}(N\log N)\) scaling method. For comprehensive details, see the following references.
- Parameters:
box_vecs (torch.Tensor) – Lattice vectors
shape (torch.Size or iterable) – Real-space grid shape
cart_ion_coords (torch.Tensor) – Cartesian ionic coordinates
order (int) – Order of approximation for structure factor
- Returns:
Approximate structure factor
- Return type:
torch.Tensor
Ion-ion Interaction Energy#
- ion_utils.ion_interaction_sum(box_vecs, coords, charges, Rc, Rd)#
Computes the ion-ion interaction energy using a real-space pairwise electrostatic summation in a uniform neutralizing background. Key parameters are \(R_c\), the cut-off radius, and \(R_d\), a damping parameter. It was recommended that \(R_d = 2 h_\text{max}\) and \(R_c = 3 R_d^2 / h_\text{max}\), where \(h_\text{max}\) is the maximum interplanar distance.
More details can be found in Phys. Rev. Materials 2, 013806.
- Parameters:
box_vecs (torch.Tensor) – Lattice vectors
coords (torch.Tensor) – Cartesian ionic coordinates
charges (torch.Tensor) – Charges of all ions in the simulation cell
Rc (float) – Parameters for the electrtrostatic sum (see paper)
Rd (float) – Parameters for the electrtrostatic sum (see paper)
- Returns:
Ion-ion interaction energy
- Return type:
torch.Tensor