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}\).
`get_supported_backends`	Tuple with backends supported by the core library for a given class.
`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}\).

classmethod get_supported_backends()¶

Tuple with backends supported by the core library for a given class. User can pass either one of these values as backend=... to run() method, or a custom object that has apply method (see documentation for run()):

‘serial’: no parallelization

‘multiprocessing’: parallelization using multiprocessing.Pool

‘dask’: parallelization using dask.delayed.compute(). Requires installation of mdanalysis[dask]

If you want to add your own backend to an existing class, pass a backends.BackendBase subclass (see its documentation to learn how to implement it properly), and specify unsupported_backend=True.

Returns:

tuple: names of built-in backends that can be used in run(backend=...)()

Added in version 2.8.0: ..

property parallelizable¶

Boolean mark showing that a given class can be parallelizable with split-apply-combine procedure. Namely, if we can safely distribute _single_frame() to multiple workers and then combine them with a proper _conclude() call. If set to False, no backends except for serial are supported.

Note

If you want to check parallelizability of the whole class, without explicitly creating an instance of the class, see _analysis_algorithm_is_parallelizable. Note that you setting it to other value will break things if the algorithm behind the analysis is not trivially parallelizable.

Returns:

bool: if a given AnalysisBase subclass instance is parallelizable with split-apply-combine, or not

Added in version 2.8.0: ..

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

Performs the calculation.