DipoleMoment¶

class mdcraft.analysis.electrostatics.DipoleMoment(groups: AtomGroup | tuple[AtomGroup], charges: ndarray[float] | Quantity | Quantity = None, dim_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 dipole moment \(\mathbf{M}\).

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 time average, \(\varepsilon_0\) is the vacuum permittivity, \(k_\mathrm{B}\) is the Boltzmann constant, and \(T\) is the temperature.

Parameters:

groupsMDAnalysis.AtomGroup or array-like

Groups of atoms for which the dipole moments are calculated.

Note

If neutralize=True or unwrap=True, all atoms of any particular molecule must belong to the same atom group.

chargesarray-like, openmm.unit.Quantity, or pint.Quantity, keyword-only,optional

Charges \(q_i\) for the atoms in the \(N_\mathrm{groups}\) 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{groups},)\) array of real numbers or \((N_i,)\) arrays, where \(N_i\) is the number of atoms in group \(i\).

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

dim_scalesfloat or array-like, keyword-only, optional

Scale factors for the system dimensions. 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 averaged over the \(N_\mathrm{frames}\) analysis frames.

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 net charges of molecules are subtracted at the center of mass. 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 dipole moment.

Note

The topology must contain residue (molecule) information.

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 detailed progress is shown.

**kwargs

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

Attributes:

universeMDAnalysis.Universe

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

results.unitsdict

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

results.timesnumpy.ndarray

Times \(t\). Only available if average=False.

Shape: \((N_\mathrm{frames},)\).

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

results.dipolesnumpy.ndarray

Dipole moment vectors \(\mathbf{M}\).

Shape: \((N_\mathrm{groups},\,3)\) or \((N_\mathrm{frames},\,N_\mathrm{groups},\,3)\).

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

results.volumesnumpy.ndarray

System volumes \(V\).

Shape: \((N_\mathrm{frames},)\).

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

results.dielectricsnumpy.ndarray

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

Shape: \((3,)\).

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.

Methods

`calculate_relative_permittivity`	Calculates the relative permittivity (or static dielectric constant) \(\varepsilon_\mathrm{r}\) of a medium using dipole moments \(\mathbf{M}\).
`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 dipole moments \(\mathbf{M}\).

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.