API

Pure-Python implementation

pymbd.atomic_polarizabilities(coords, species, volumes, beta, lattice=None, kind='TS')[source]

Calculate static atomic polarizabilities.

Parameters:

  • coords (array-like) – (a.u.) atom coordinates in rows

  • species (array-like) – atom types (elements)

  • volumes (array-like) – ratios of Hirshfeld volumes in molecule and vacuum

  • beta (float) – MBD damping parameter \(\beta\) (see J. Chem. Phys. 140, 18A508 (2014))

  • lattice (array-like) – (a.u.) lattice vectors in rows

  • kind (str) – one of ‘TS’, ‘BG’ or ‘TSsurf’

Returns the isotropic per-atom screened static polarizabilities of shape (N,) (a.u.).

pymbd.from_volumes(species, volumes, kind='TS')[source]

Scale free-atom vdW parameters by Hirshfeld volume ratios.

Parameters:

  • species (array-like) – atom types (elements)

  • volumes (array-like) – ratios of Hirshfeld volumes in molecule and vacuum

  • kind (str) – one of ‘TS’, ‘BG’ or ‘TSsurf’

Returns partitioned atomic polarizabilities, \(C_6\) coefficients, and \(R_\mathrm{vdw}\) coefficients (a.u.).

pymbd.mbd_energy(coords, alpha_0, C6, R_vdw, beta, lattice=None, k_grid=None, nfreq=15)[source]

Calculate an MBD energy.

Use with Hirshfeld-partitioned atomic polarizabilities, C6 coefficients and van der Waal radii. Otherwise use mbd_energy_species().

Parameters:

  • coords (array-like) – (a.u.) atomic coordinates in rows

  • alpha_0 (array-like) – (a.u.) atomic polarizabilities

  • C6 (array-like) – (a.u.) atomic \(C_6\) coefficients

  • R_vdw (array-like) – (a.u.) atomic vdW radii

  • beta (float) – MBD damping parameter \(\beta\)

  • lattice (array-like) – (a.u.) lattice vectors in rows

  • k_grid (array-like) – number of \(k\)-points along reciprocal axes

  • nfreq (int) – number of grid points for frequency quadrature

pymbd.mbd_energy_species(coords, species, volume_ratios, beta, **kwargs)[source]

Calculate an MBD energy from atom types and Hirshfeld-volume ratios.

Parameters:

  • coords (array-like) – (a.u.) atom coordinates in rows

  • species (array-like) – atom types (elements)

  • volume_ratios (array-like) – ratios of Hirshfeld volumes in molecule and vacuum

  • beta (float) – MBD damping parameter \(\beta\) (use :math:’beta = 0.83’ for PBE xc-functional)

  • kwargs – see mbd_energy()

pymbd.molecular_polarizability(coords, species, volumes, beta, lattice=None, kind='TS')[source]

Calculate the static molecular polarizability tensor.

Parameters:

  • coords (array-like) – (a.u.) atom coordinates in rows

  • species (array-like) – atom types (elements)

  • volumes (array-like) – ratios of Hirshfeld volumes in molecule and vacuum

  • beta (float) – MBD damping parameter \(\beta\) (see J. Chem. Phys. 140, 18A508 (2014))

  • lattice (array-like) – (a.u.) lattice vectors in rows

  • kind (str) – one of ‘TS’, ‘BG’ or ‘TSsurf’

Returns the \(3\times3\) static polarizability tensor (a.u.).

pymbd.screening(coords, alpha_0, C6, R_vdw, beta, lattice=None, nfreq=15)[source]

Screen atomic polarizabilities.

Parameters:

  • coords (array-like) – (a.u.) atom coordinates in rows

  • alpha_0 (array-like) – (a.u.) atomic polarizabilities

  • C6 (array-like) – (a.u.) atomic \(C_6\) coefficients

  • R_vdw (array-like) – (a.u.) atomic vdW radii

  • beta (float) – MBD damping parameter \(\beta\)

  • lattice (array-like) – (a.u.) lattice vectors in rows

  • nfreq (int) – number of grid points for frequency quadrature

Returns static polarizabilities, \(C_6\) coefficients, and \(R_\mathrm{vdw}\) coefficients (a.u.).

pymbd.screening_matrix(coords, alpha_0, R_vdw, beta, lattice=None)[source]

Build the screened non-local polarizability matrix.

Returns the \((3N, 3N)\) matrix \(\bar{\boldsymbol\alpha}=(\boldsymbol\alpha_0^{-1}+\mathbf T_\mathrm{GG})^{-1}\), whose \(3\times3\) blocks \(\bar{\boldsymbol\alpha}_{ij}\) are the dipole-screened polarizabilities coupling atoms \(i\) and \(j\). This is the shared core of screening(), atomic_polarizabilities(), and molecular_polarizability().

Parameters:

  • coords (array-like) – (a.u.) atom coordinates in rows

  • alpha_0 (array-like) – (a.u.) atomic polarizabilities

  • R_vdw (array-like) – (a.u.) atomic vdW radii

  • beta (float) – MBD damping parameter \(\beta\)

  • lattice (array-like) – (a.u.) lattice vectors in rows

pymbd.pymbd.ang = 1.8897259885789233

(a.u.) angstrom

Can be imported directly as pymbd.ang.

Fortran bindings

class pymbd.fortran.MBDGeom(coords, lattice=None, k_grid=None, custom_k_pts=None, n_freq=None, do_rpa=False, get_spectrum=False, get_rpa_orders=False, rpa_rescale_eigs=False, max_atoms_per_block=None, ewald_cutoff_scaling=(1.0, 1.0))[source]

Represents an initialized libMBD geom_t object.

Parameters:

  • coords (array-like) – (a.u.) atomic coordinates as rows

  • lattice (array-like) – (a.u.) lattice vectors as rows

  • k_grid (array-like) – number of \(k\)-points per reciprocal lattice vector

  • custom_k_pts (array-like) – (a.u.) custom \(k\)-points as rows

  • n_freq (int) – number of quadrature points for frequency integration

  • do_rpa (bool) – whether to calculate MBD energy via frequency integration

  • get_spectrum (bool) – whether to return eigenvalues and eigenvectors

  • get_rpa_orders (bool) – whether to return RPA order decomposition

  • rpa_rescale_eigs (bool) – whether to rescale RPA eigenvalues

property coords

(a.u.) Atom coordinates in rows.

has_lattice()[source]

Whether structure is a crystal.

int_density(pts, q, m, w_t, modes)[source]

Evaluate the density of the interacting QDOs.

Returns the charge density of the quantum Drude oscillators (QDOs) with the dipole coupling switched on. Unlike nonint_density(), each per-atom contribution is a general (anisotropic) Gaussian obtained by integrating out the remaining oscillators from the coupled ground-state wavefunction (see QDO charge densities for the derivation and a plotting example). Like the non-interacting density, it integrates to \(\sum_A q_A\).

The coupled frequencies w_t and eigenmodes modes are the MBD normal modes, obtained from mbd_energy() with a geometry constructed with get_spectrum=True (w_t are the square roots of the returned eigenvalues).

Parameters:

  • pts (array-like) – (a.u.) points at which to evaluate the density, shape (n_pts, 3)

  • q (array-like) – (a.u.) oscillator charges

  • m (array-like) – (a.u.) oscillator masses

  • w_t (array-like) – (a.u.) coupled MBD frequencies \(\tilde\omega\), shape (3 n_atoms,)

  • modes (array-like) – MBD eigenmodes, shape (3 n_atoms, 3 n_atoms)

Returns:

(a.u.) density evaluated at pts, shape (n_pts,)

property lattice

(a.u.) Lattice vectors in rows.

mbd_energy(alpha_0, C6, R_vdw=None, beta=0.0, a=6.0, sigma=None, damping='fermi,dip', variant='rsscs', force=False, intermediates=False)[source]

Calculate an MBD energy.

Parameters:

  • alpha_0 (array-like) – (a.u.) atomic polarizabilities

  • C6 (array-like) – (a.u.) atomic \(C_6\) coefficients

  • R_vdw (array-like) – (a.u.) atomic vdW radii

  • sigma (array-like) – (a.u.) oscillator widths

  • beta (float) – MBD damping parameter \(\beta\)

  • a (float) – MBD damping parameter \(a\)

  • str (variant) – type of damping

  • str – one of ‘plain’, ‘scs’, ‘rsscs’

  • bool (force) – if True, calculate energy gradients

mbd_energy_species(species, volume_ratios, beta, **kwargs)[source]

Calculate an MBD energy from atom types and Hirshfed-volume ratios.

Parameters:

  • species (array-like) – atom types (elements)

  • volume_ratios (array-like) – ratios of Hirshfeld volumes in molecule and vacuum

  • beta (float) – MBD damping parameter \(\beta\)

  • kwargs – see mbd_energy()

nonint_density(pts, q, m, w)[source]

Evaluate the density of the non-interacting QDOs.

Returns the charge density of the quantum Drude oscillators (QDOs) in the absence of the dipole coupling, that is a sum of independent spherical Gaussians, one per atom,

\[n(\mathbf r)=\sum_A q_A\left(\frac{m_A\omega_A}\pi\right)^\frac32 \exp\big(-m_A\omega_A|\mathbf r-\mathbf R_A|^2\big)\]

which integrates to \(\sum_A q_A\). The oscillator parameters are related to the vdW parameters by \(\omega_A=\tfrac43 C_{6,A}/\alpha_{0,A}^2\) and \(\alpha_{0,A}=q_A^2/(m_A\omega_A^2)\). The MBD convention is \(m_A=1\), which gives \(q_A=\omega_A\sqrt{\alpha_{0,A}}\). See QDO charge densities for a plotting example.

Parameters:

  • pts (array-like) – (a.u.) points at which to evaluate the density, shape (n_pts, 3)

  • q (array-like) – (a.u.) oscillator charges

  • m (array-like) – (a.u.) oscillator masses

  • w (array-like) – (a.u.) oscillator frequencies \(\omega\)

Returns:

(a.u.) density evaluated at pts, shape (n_pts,)

print_timing()[source]

Print timing from libMBD.

ts_energy(alpha_0, C6, R_vdw, sR, d=20.0, damping='fermi', force=False)[source]

Calculate a TS energy.

Parameters:

  • alpha_0 (array-like) – (a.u.) atomic polarizabilities

  • C6 (array-like) – (a.u.) atomic \(C_6\) coefficients

  • R_vdw (array-like) – (a.u.) atomic vdW radii

  • sR (float) – TS damping parameter \(s_R\)

  • d (float) – TS damping parameter \(d\)

  • str (damping) – type of damping

  • bool (force) – if True, calculate energy gradients

ts_energy_species(species, volume_ratios, beta, **kwargs)[source]

Calculate a TS energy from atom types and Hirshfed-volume ratios.

Parameters:

  • species (array-like) – atom types (elements)

  • volume_ratios (array-like) – ratios of Hirshfeld volumes in molecule and vacuum

  • sR (float) – TS damping parameter \(s_R\)

  • kwargs – see ts_energy()

pymbd.fortran.with_mpi

Whether libMBD was compiled with MPI

pymbd.fortran.with_scalapack

Whether libMBD was compiled with Scalapack