DipoleMoment¶

class mdhelper.analysis.electrostatics.DipoleMoment(groups: AtomGroup | tuple[AtomGroup], charges: ndarray[float] | Quantity | Quantity = None, dimensions: ndarray[float] | Quantity | Quantity = None, scales: float | tuple[float] = 1, average: bool = False, reduced: bool = False, neutralize: bool = False, unwrap: bool = False, parallel: bool = False, verbose: bool = True, **kwargs)[source]¶

Bases: DynamicAnalysisBase

Serial and parallel implementations to calculate the instantaneous dipole moment vectors \(\mathbf{M}(t)\).

For a system with \(N\) atoms or molecules, the dipole moment is given by

\[\mathbf{M}=\sum_i^{N}q_i\mathbf{z}_i\]

where \(q_i\) and \(\mathbf{z}_i\) are the charge and position of entity \(i\).

The dipole moment can be used to estimate the relative permittivity (or static dielectric constant) via the dipole moment fluctuation formula [1]:

\[\varepsilon_\mathrm{r}=1+\frac{\overline{\langle\mathbf{M}^2\rangle -\langle\mathbf{M}\rangle^2}}{3\varepsilon_0 Vk_\mathrm{B}T}\]

where the angular brackets \(\langle\,\cdot\,\rangle\) denote the ensemble average, the overline signifies the spatial average, \(\varepsilon_0\) is the vacuum permittivity, \(k_\mathrm{B}\) is the Boltzmann constant, and \(T\) is the system temperature.

Parameters:

groupsMDAnalysis.AtomGroup or array-like

Group(s) of atoms for which the dipole moments are calculated.

chargesarray-like, keyword-only, optional

Charge information for the atoms in the \(N_\mathrm{g}\) groups in groups. If not provided, it should be available in and will be retrieved from the main MDAnalysis.core.universe.Universe object.

Shape: \((N_\mathrm{g},)\) array of real numbers or \((N_i,)\) arrays, where \(N_i\) is the number of atoms in group \(i\).

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

dimensionsarray-like, keyword-only, optional

System dimensions. If the MDAnalysis.core.universe.Universe object that the groups in groups belong to does not contain dimensionality information, provide it here. Affected by scales.

Shape: \((3,)\).

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

scalesarray-like, keyword-only, optional

Scaling factors for each system dimension. If an int is provided, the same value is used for all axes.

Shape: \((3,)\).

averagebool, keyword-only, default: False

Determines whether the dipole moment vectors and volumes are time-averaged.

reducedbool, keyword-only, default: False

Specifies whether the data is in reduced units. Only affects calculate_relative_permittivity() calls.

neutralizebool, keyword-only, default: False

Specifies whether the net charge is subtracted at the center of mass for molecules with net charges. Must be enabled if your system contains molecules with net charges and you want to calculate the relative permittivity, but should be disabled if you are only interested in the instantaneous dipole moment.

unwrapbool, keyword-only, default: False

Determines whether atom positions are unwrapped.

parallelbool, keyword-only, default: False

Determines whether the analysis is performed in parallel.

verbosebool, keyword-only, default: True

Determines whether progress is printed to the console.

**kwargs

Additional keyword arguments to pass to MDAnalysis.analysis.base.AnalysisBase.

References

[1]

Neumann, M. Dipole Moment Fluctuation Formulas in Computer Simulations of Polar Systems. Molecular Physics 1983, 50 (4), 841–858. https://doi.org/10.1080/00268978300102721.

Attributes:

universeMDAnalysis.Universe

MDAnalysis.core.universe.Universe object containing all information describing the system.

results.unitsdict

Reference units for the results. For example, to get the reference units for results.times, call results.units["results.times"].

results.timesnumpy.ndarray

Changes in time \(t-t_0\).

Shape: \((N_t,)\).

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

results.dipolesnumpy.ndarray

Instantaneous dipole moment vectors \(\mathbf{M}\).

Shape: \((N_t,\,N_\mathrm{g},\,3)\).

Reference unit: \(\mathrm{e\cdotÅ}\).

results.volumesnumpy.ndarray

System volumes \(V\).

Shape: \((N_t,)\).

Reference unit: \(\mathrm{Å^3}\).

results.dielectricnumpy.ndarray

Relative permittivity (or static dielectric constant) \(\varepsilon_\mathrm{r}\) in each dimension.

Shape: \((3,)\).

Methods

`calculate_relative_permittivity`	Calculates the relative permittivity (or static dielectric constant) \(\varepsilon_\mathrm{r}\) of a medium using the instantaneous dipole moments \(\mathbf{M}(t)\).
`run`	Performs the calculation.
`save`	Saves results to a binary or archive file in NumPy format.

calculate_relative_permittivity(temperature: float | Quantity | Quantity) → None[source]¶

Calculates the relative permittivity (or static dielectric constant) \(\varepsilon_\mathrm{r}\) of a medium using the instantaneous dipole moments \(\mathbf{M}(t)\).

Parameters:

temperaturefloat, openmm.unit.Quantity, or pint.Quantity

System temperature \(T\).

Note

If reduced=True was set in the DipoleMoment constructor, temperature should be equal to the energy scale. When the Lennard-Jones potential is used, it generally means that \(T^* = 1\), or temperature=1.

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

run(start: int = None, stop: int = None, step: int = None, frames: slice | ndarray[int] = None, verbose: bool = None, **kwargs) → SerialAnalysisBase | ParallelAnalysisBase¶

Performs the calculation.