add_slab_correction

mdhelper.openmm.system.add_slab_correction(system: System, topology: Topology, nbforce: NonbondedForce | CustomNonbondedForce, temp: float | Quantity, fric: float | Quantity, dt: float | Quantity, axis: int = 2, *, charge_index: int = 0, z_scale: float = 3, method: str = 'force') → Integrator

Implements a slab correction so that efficient three-dimensional Ewald methods can continue to be used to evaluate the electrostatics for systems that are periodic in the \(x\)- and \(y\)-directions but not the \(z\)-direction. Effectively, the system is treated as if it were periodic in the \(z\)-direction, but with empty volume added between the slabs and the slab–slab interactions removed.

For electroneutral systems, the Yeh–Berkowitz correction [1] is applied:

\[\begin{split}\begin{gather*} U^\mathrm{corr}=\frac{N_A}{2\varepsilon_0V}M_z^2\\ u_i^\mathrm{corr}=\frac{N_A}{2\varepsilon_0V}q_i\left(z_iM_z -\frac{\sum_i q_iz_i^2}{2}\right)\\ f_{i,z}^\mathrm{corr}=-\frac{N_A}{\varepsilon_0V}q_iM_z \end{gather*}\end{split}\]

For systems with a net electric charge, the Ballenegger–Arnold–Cerdà correction [2] is applied instead:

\[\begin{split}\begin{gather*} U^\mathrm{corr}=\frac{N_A}{2\varepsilon_0V} \left(M_z^2-q_\mathrm{tot}\sum_i q_iz_i^2 -\frac{q_\mathrm{tot}^2L_z^2}{12}\right)\\ u_i^\mathrm{corr}=\frac{N_A}{2\varepsilon_0V}q_i \left(z_iM_z-\frac{\sum_i q_iz_i^2+q_\mathrm{tot}z_i^2}{2} -\frac{q_\mathrm{tot}L_z^2}{12}\right)\\ f_{i,z}^\mathrm{corr}=-\frac{N_A}{\varepsilon_0V}q_i \left(M_z-q_\mathrm{tot}z_i\right) \end{gather*}\end{split}\]

Note that the the relative permittivity \(\varepsilon_\mathrm{r}\) does not appear in the equations above because it is accounted for by scaling the particle charges in the Coulomb potential.

Parameters:

systemopenmm.System

OpenMM molecular system.

topologyopenmm.app.Topology

Topological information about an OpenMM system.

nbforceopenmm.NonbondedForce or openmm.CustomNonbondedForce

Pair potential object containing particle charge information.

Note

It is assumed that the charge \(q\) information is the first per-particle parameter stored in nbforce. If not, the index can be specified in charge_index.

tempfloat or openmm.unit.Quantity

System temperature \(T\).

Reference unit: \(\mathrm{K}\).

fricfloat or openmm.unit.Quantity

Friction coefficient \(\gamma\) that couples the system to the heat bath.

Reference unit: \(\mathrm{ps}^{-1}\).

dtfloat or openmm.unit.Quantity

Integration step size \(\Delta t\).

Reference unit: \(\mathrm{ps}\).

axisint, default: 2

Axis along which to apply the slab correction, with \(x\) being 0, \(y\) being 1, and \(z\) being 2. The source code and outputs, if any, will refer to this dimension as z regardless of this value.

charge_indexint, keyword-only, default: 0

Index of charge \(q\) information in the per-particle parameters stored in nbforce.

z_scalefloat, keyword-only, default: 3

Scaling factor for the dimension specified in axis.

methodstr, keyword-only, default: "force"

Slab correction methodology.

Valid values:

• "force": Collective implementation via openmm.CustomExternalForce and openmm.CustomCVForce [3]. This is generally the most efficient.

• "integrator": Per-particle implementation via an openmm.CustomIntegrator.

Returns:

integratoropenmm.Integrator or openmm.CustomIntegrator

Integrator that simulates a system using Langevin dynamics, with the LFMiddle discretization.

References

[1]

Yeh, I.-C.; Berkowitz, M. L. Ewald Summation for Systems with Slab Geometry. J. Chem. Phys. 1999, 111 (7), 3155–3162. https://doi.org/10.1063/1.479595.

[2]

Ballenegger, V.; Arnold, A.; Cerdà, J. J. Simulations of Non-Neutral Slab Systems with Long-Range Electrostatic Interactions in Two-Dimensional Periodic Boundary Conditions. J. Chem. Phys. 2009, 131 (9), 094107. https://doi.org/10.1063/1.3216473.

[3]

Son, C. Y.; Wang, Z.-G. Image-Charge Effects on Ion Adsorption near Aqueous Interfaces. Proc. Natl. Acad. Sci. U.S.A. 2021, 118 (19), e2020615118. https://doi.org/10.1073/pnas.2020615118.