Skip to content

force_constants

Harmonic force constants, and the dynamical matrix they give.

The second derivative of the energy with respect to atomic displacements, Phi_ab(i, j, S) = -dF_jb / du_ia, where j sits in the cell displaced by the integer lattice vector S from i's. Those triples are indexed the same way a neighbour list is, which is the point: the dynamical matrix is then a phase sum over exactly the pairs that exist,

D_ab(q) = sum_(i,j,S) w(i,j,S) Phi_ab(i,j,S) exp(2 pi i q.S) / sqrt(m_i m_j)

and no supercell index ever appears in it. A supercell is used to measure Phi -- far enough that a displaced atom does not feel its own image -- and then discarded.

w is the multiplicity weight. A pair (i, j) may be reachable through several lattice translations that are equally short, and each of those images is physically present in the infinite crystal while the finite supercell measured their sum once. The weight shares it back out. The degeneracy is exact -- it comes from lattice symmetry, not from floating point -- so the ties can be found by comparing squared distances against the minimum with a tolerance far below any real spacing.

Three symmetries constrain Phi, and they do not commute, so the order is fixed and documented in symmetrise:

  • permutation, Phi_ab(i,j,S) = Phi_ba(j,i,-S);
  • the acoustic sum rule, sum_(j,S) Phi_ab(i,j,S) = 0, which is the statement that translating the whole crystal costs nothing;
  • the space group, which reduces what is measured in the first place; see force_constants.

DisplacementPlan

The displaced supercells force constants are measured from, and the solve that turns their forces into force constants.

With symmetry, one atom per orbit is displaced, along only as many directions as its site symmetry needs to span all three; every displacement is made in both directions, + then -. Separating the plan from the evaluation lets the displaced cells be computed one at a time or all in one batch.

Parameters:

Name Type Description Default
structure

a Crystal or a periodic System

required
system

structure as a System

required
repeats

(3,) supercell repetitions

required
symmetry

use a Crystal's space group

required
displacement

finite-difference step, Angstroms

required
Source code in chmpy/vib/force_constants.py
class DisplacementPlan:
    """The displaced supercells force constants are measured from, and the
    solve that turns their forces into force constants.

    With symmetry, one atom per orbit is displaced, along only as many
    directions as its site symmetry needs to span all three; every
    displacement is made in both directions, `+` then `-`. Separating the plan
    from the evaluation lets the displaced cells be computed one at a time or
    all in one batch.

    Args:
        structure: a `Crystal` or a periodic `System`
        system: `structure` as a `System`
        repeats: (3,) supercell repetitions
        symmetry: use a `Crystal`'s space group
        displacement: finite-difference step, Angstroms
    """

    def __init__(self, structure, system, repeats, symmetry, displacement):
        repeats = np.asarray(repeats, dtype=int)
        if np.any(repeats < 1):
            raise ValueError(f"supercell repetitions must be positive, got {repeats}")
        self.system, self.repeats, self.displacement = system, repeats, displacement
        self.atom_map = _symmetry_for(structure, system, repeats, symmetry)
        self.supercell, self.origin, _ = _build_supercell(system, repeats)
        self.cartesian = self.atom_map.cartesian(system.cell)

        n = len(system)
        self.plan, measured = [], np.zeros(n, dtype=bool)
        for representative in range(n):
            if measured[representative]:
                continue
            images = self.atom_map.permutation[:, representative]
            stabiliser = np.flatnonzero(images == representative)
            directions = _directions_to_displace(self.cartesian[stabiliser])
            self.plan.append((representative, stabiliser, directions))
            measured[images] = True
        #: displacement directions, each made with both signs
        self.total = sum(len(directions) for _, _, directions in self.plan)

    def displacements(self):
        "(representative, direction, sign) for every displaced cell, in order"
        for representative, _, directions in self.plan:
            for direction in directions:
                for sign in (1, -1):
                    yield representative, direction, sign

    def positions(self, representative, direction, sign) -> np.ndarray:
        "(M, 3) supercell positions for one displacement"
        positions = np.array(self.supercell.positions)
        positions[self.origin[representative]] += (
            sign * self.displacement * np.asarray(direction)
        )
        return positions

    def systems(self) -> list:
        "Every displaced supercell, in the order `solve` expects their forces"
        big = self.supercell
        return [
            System(big.numbers, self.positions(*key), big.cell, True, dict(big.info))
            for key in self.displacements()
        ]

    def solve(self, forces) -> ForceConstants:
        """Force constants from the forces on each displaced cell.

        Args:
            forces: (M, 3) forces for each cell, in the order of `displacements`
        """
        n = len(self.system)
        n_cells = int(np.prod(self.repeats))
        atom_map, cartesian, repeats = self.atom_map, self.cartesian, self.repeats
        blocks = np.zeros((n, n, n_cells, 3, 3))
        forces = iter(forces)
        for representative, stabiliser, directions in self.plan:
            rows, responses = [], []
            for direction in directions:
                plus, minus = np.asarray(next(forces)), np.asarray(next(forces))
                # d . Phi(r, k) = -dF_k / du along d, for every supercell atom k
                response = -(plus - minus) / (2 * self.displacement)
                # each site-symmetry operation s gives another equation:
                # (R^T d) . Phi(r, k) = (d . Phi(r, s(k))) R
                for operation in stabiliser:
                    rotation = cartesian[operation]
                    target = _supercell_image(
                        atom_map, operation, representative, repeats
                    )
                    rows.append(rotation.T @ direction)
                    responses.append(response[target] @ rotation)

            # least squares for every supercell atom at once
            solved = np.einsum(
                "am,mkb->kab", np.linalg.pinv(np.array(rows)), np.array(responses)
            )
            _fill_orbit(blocks, solved, atom_map, cartesian, representative, repeats)

        return symmetrise(_assemble(self.system, repeats, blocks))

displacements()

(representative, direction, sign) for every displaced cell, in order

Source code in chmpy/vib/force_constants.py
def displacements(self):
    "(representative, direction, sign) for every displaced cell, in order"
    for representative, _, directions in self.plan:
        for direction in directions:
            for sign in (1, -1):
                yield representative, direction, sign

positions(representative, direction, sign)

(M, 3) supercell positions for one displacement

Source code in chmpy/vib/force_constants.py
def positions(self, representative, direction, sign) -> np.ndarray:
    "(M, 3) supercell positions for one displacement"
    positions = np.array(self.supercell.positions)
    positions[self.origin[representative]] += (
        sign * self.displacement * np.asarray(direction)
    )
    return positions

solve(forces)

Force constants from the forces on each displaced cell.

Parameters:

Name Type Description Default
forces

(M, 3) forces for each cell, in the order of displacements

required
Source code in chmpy/vib/force_constants.py
def solve(self, forces) -> ForceConstants:
    """Force constants from the forces on each displaced cell.

    Args:
        forces: (M, 3) forces for each cell, in the order of `displacements`
    """
    n = len(self.system)
    n_cells = int(np.prod(self.repeats))
    atom_map, cartesian, repeats = self.atom_map, self.cartesian, self.repeats
    blocks = np.zeros((n, n, n_cells, 3, 3))
    forces = iter(forces)
    for representative, stabiliser, directions in self.plan:
        rows, responses = [], []
        for direction in directions:
            plus, minus = np.asarray(next(forces)), np.asarray(next(forces))
            # d . Phi(r, k) = -dF_k / du along d, for every supercell atom k
            response = -(plus - minus) / (2 * self.displacement)
            # each site-symmetry operation s gives another equation:
            # (R^T d) . Phi(r, k) = (d . Phi(r, s(k))) R
            for operation in stabiliser:
                rotation = cartesian[operation]
                target = _supercell_image(
                    atom_map, operation, representative, repeats
                )
                rows.append(rotation.T @ direction)
                responses.append(response[target] @ rotation)

        # least squares for every supercell atom at once
        solved = np.einsum(
            "am,mkb->kab", np.linalg.pinv(np.array(rows)), np.array(responses)
        )
        _fill_orbit(blocks, solved, atom_map, cartesian, representative, repeats)

    return symmetrise(_assemble(self.system, repeats, blocks))

systems()

Every displaced supercell, in the order solve expects their forces

Source code in chmpy/vib/force_constants.py
def systems(self) -> list:
    "Every displaced supercell, in the order `solve` expects their forces"
    big = self.supercell
    return [
        System(big.numbers, self.positions(*key), big.cell, True, dict(big.info))
        for key in self.displacements()
    ]

ForceConstants dataclass

Harmonic force constants of a periodic structure.

Attributes:

Name Type Description
pairs ndarray

(P, 2) the atom indices i, j of each block, within the cell

shifts ndarray

(P, 3) integer lattice translation taking j's cell from i's

blocks ndarray

(P, 3, 3) the force-constant matrices, eV/Angstrom^2

weights ndarray

(P,) multiplicity weights for the phase sum

masses ndarray

(N,) atomic masses in amu

cell ndarray

(3, 3) lattice vectors as rows, Angstroms

positions ndarray

(N, 3) Cartesian positions the constants were measured at

Source code in chmpy/vib/force_constants.py
@dataclass
class ForceConstants:
    """Harmonic force constants of a periodic structure.

    Attributes:
        pairs: (P, 2) the atom indices `i`, `j` of each block, within the cell
        shifts: (P, 3) integer lattice translation taking `j`'s cell from `i`'s
        blocks: (P, 3, 3) the force-constant matrices, eV/Angstrom^2
        weights: (P,) multiplicity weights for the phase sum
        masses: (N,) atomic masses in amu
        cell: (3, 3) lattice vectors as rows, Angstroms
        positions: (N, 3) Cartesian positions the constants were measured at
    """

    pairs: np.ndarray
    shifts: np.ndarray
    blocks: np.ndarray
    weights: np.ndarray
    masses: np.ndarray
    cell: np.ndarray
    positions: np.ndarray
    _cache: dict = field(default_factory=dict, init=False, repr=False, compare=False)

    @property
    def n_atoms(self) -> int:
        return len(self.masses)

    def __repr__(self) -> str:
        return (
            f"<ForceConstants {self.n_atoms} atoms, {len(self.blocks)} blocks, "
            f"shifts to {int(np.abs(self.shifts).max())}>"
        )

    # -- the dynamical matrix ------------------------------------------------

    def dynamical_matrix(self, q) -> np.ndarray:
        """The (3N, 3N) dynamical matrix at a fractional wavevector.

        Args:
            q: (3,) wavevector in fractional reciprocal coordinates, so that
                the phase is `exp(2 pi i q.S)` with `S` the integer shift

        Returns:
            (3N, 3N) complex Hermitian matrix in eV/(Angstrom^2 amu)
        """
        return self.dynamical_matrices(np.reshape(q, (1, 3)))[0]

    def dynamical_matrices(self, qs) -> np.ndarray:
        """Dynamical matrices at several fractional wavevectors at once.

        The blocks are first summed into one mass-weighted real matrix per
        distinct shift `S`, which needs doing once, and then each `D(q)` is a
        phase-weighted sum of those -- one matrix product for every q at once,
        instead of a scatter over every block for each. Where the per-shift
        matrices would be too large to hold, each q is scattered instead.

        Args:
            qs: (M, 3) fractional wavevectors

        Returns:
            (M, 3N, 3N) complex Hermitian matrices in eV/(Angstrom^2 amu)
        """
        qs = np.asarray(qs, dtype=float).reshape(-1, 3)
        n3 = 3 * self.n_atoms
        by_shift = self._by_shift()
        if by_shift is not None:
            shifts, matrices = by_shift
            phases = np.exp(2j * np.pi * (qs @ shifts.T))
            result = (phases @ matrices.reshape(len(shifts), -1)).reshape(-1, n3, n3)
        else:
            result = np.stack([self._scatter(q) for q in qs])
        # the sum is Hermitian in exact arithmetic; make it so in practice
        return 0.5 * (result + result.conj().transpose(0, 2, 1))

    def _mass_weighted(self) -> np.ndarray:
        "(P, 3, 3) blocks times their weights over sqrt(m_i m_j)"
        root_mass = np.sqrt(self.masses)
        i, j = self.pairs[:, 0], self.pairs[:, 1]
        scale = self.weights / (root_mass[i] * root_mass[j])
        return scale[:, None, None] * self.blocks

    def _flat_index(self) -> np.ndarray:
        "(P, 3, 3) index of each block element in a flattened (3N, 3N) matrix"
        n3 = 3 * self.n_atoms
        rows = 3 * self.pairs[:, 0, None] + np.arange(3)
        cols = 3 * self.pairs[:, 1, None] + np.arange(3)
        return rows[:, :, None] * n3 + cols[:, None, :]

    def _by_shift(self):
        """(shifts, (S, 3N, 3N) real matrices), or None if too large to keep."""
        if self._cache.get("by_shift", False) is not False:
            return self._cache["by_shift"]
        n3 = 3 * self.n_atoms
        shifts, which = np.unique(
            np.rint(self.shifts).astype(np.int64), axis=0, return_inverse=True
        )
        which = which.ravel()
        if len(shifts) * n3 * n3 * 8 > BY_SHIFT_BYTES:
            self._cache["by_shift"] = None
            return None
        index = which[:, None, None] * (n3 * n3) + self._flat_index()
        matrices = np.bincount(
            index.ravel(),
            weights=self._mass_weighted().ravel(),
            minlength=len(shifts) * n3 * n3,
        ).reshape(len(shifts), n3, n3)
        self._cache["by_shift"] = (shifts.astype(float), matrices)
        return self._cache["by_shift"]

    def _scatter(self, q) -> np.ndarray:
        "One dynamical matrix, summed straight from the blocks"
        n3 = 3 * self.n_atoms
        phases = np.exp(2j * np.pi * (self.shifts @ q))
        values = phases[:, None, None] * self._mass_weighted()
        index = self._flat_index().ravel()
        real = np.bincount(index, weights=values.real.ravel(), minlength=n3 * n3)
        imag = np.bincount(index, weights=values.imag.ravel(), minlength=n3 * n3)
        return (real + 1j * imag).reshape(n3, n3)

    def frequencies(self, q, units: str = "thz") -> np.ndarray:
        """Phonon frequencies at one or more wavevectors, ordered low to high.

        A negative frequency is reported for an imaginary mode, which is the
        usual convention and keeps the array real.

        Args:
            q: (3,) fractional wavevector, or (M, 3) for several
            units: "thz", "cm-1", or "rad/s"

        Returns:
            (3N,) frequencies, or (M, 3N) for several wavevectors
        """
        factor = _unit_factor(units)
        q = np.asarray(q, dtype=float)
        eigenvalues = np.linalg.eigvalsh(self.dynamical_matrices(q.reshape(-1, 3)))
        omega = _omega(eigenvalues) * factor
        return omega[0] if q.ndim == 1 else omega

    def optical_frequencies(self, units: str = "thz") -> np.ndarray:
        """The 3N - 3 optical frequencies at Gamma, ordered low to high.

        The three uniform translations are projected out of the dynamical
        matrix before it is diagonalised, rather than dropped as the three
        lowest frequencies or those under a threshold. That way a soft optical
        mode is never mistaken for an acoustic one, and an imaginary optical
        mode is still reported as one.
        """
        factor = _unit_factor(units)
        complement = self._translation_complement()
        matrix = self.dynamical_matrix(np.zeros(3)).real
        projected = complement.T @ matrix @ complement
        eigenvalues = np.linalg.eigvalsh(0.5 * (projected + projected.T))
        return _omega(eigenvalues) * factor

    def _translation_basis(self) -> np.ndarray:
        """(3N, 3N) orthonormal basis whose first three columns are the uniform
        translations.

        A translation by `t` displaces every atom by `t`; in mass-weighted
        coordinates that is `sqrt(m_i) t`, which is what the dynamical matrix
        acts on.
        """
        root_mass = np.sqrt(self.masses)
        translations = np.kron(root_mass[:, None], np.eye(3))
        return np.linalg.qr(translations, mode="complete")[0]

    def _translation_complement(self) -> np.ndarray:
        "(3N, 3N - 3) orthonormal basis orthogonal to uniform translations"
        return self._translation_basis()[:, 3:]

    def gamma_hessian(self) -> np.ndarray:
        """(3N, 3N) d2E/du du for displacements repeated in every cell, eV/A^2.

        The q = 0 sum of each block over its images, without the mass
        weighting of the dynamical matrix: the Hessian of the unit cell with
        periodic boundary conditions, which is what relaxing the atoms of a
        strained cell responds to.
        """
        n = self.n_atoms
        hessian = np.zeros((n, n, 3, 3))
        np.add.at(
            hessian,
            (self.pairs[:, 0], self.pairs[:, 1]),
            self.weights[:, None, None] * self.blocks,
        )
        return hessian.transpose(0, 2, 1, 3).reshape(3 * n, 3 * n)

    def acoustic_error(self, units: str = "cm-1") -> float:
        """How far the three acoustic modes at Gamma are from zero.

        The cleanest single check on a set of force constants: translating the
        crystal costs no energy, so the dynamical matrix must send the uniform
        translations to zero. The largest amount it moves one by, as a
        frequency, is the residue of the acoustic sum rule. It is measured on
        the translations themselves rather than as the lowest frequencies, which
        would report an imaginary optical mode instead.
        """
        translations = self._translation_basis()[:, :3]
        moved = self.dynamical_matrix(np.zeros(3)).real @ translations
        return float(_omega(np.linalg.norm(moved, 2)) * _unit_factor(units))

acoustic_error(units='cm-1')

How far the three acoustic modes at Gamma are from zero.

The cleanest single check on a set of force constants: translating the crystal costs no energy, so the dynamical matrix must send the uniform translations to zero. The largest amount it moves one by, as a frequency, is the residue of the acoustic sum rule. It is measured on the translations themselves rather than as the lowest frequencies, which would report an imaginary optical mode instead.

Source code in chmpy/vib/force_constants.py
def acoustic_error(self, units: str = "cm-1") -> float:
    """How far the three acoustic modes at Gamma are from zero.

    The cleanest single check on a set of force constants: translating the
    crystal costs no energy, so the dynamical matrix must send the uniform
    translations to zero. The largest amount it moves one by, as a
    frequency, is the residue of the acoustic sum rule. It is measured on
    the translations themselves rather than as the lowest frequencies, which
    would report an imaginary optical mode instead.
    """
    translations = self._translation_basis()[:, :3]
    moved = self.dynamical_matrix(np.zeros(3)).real @ translations
    return float(_omega(np.linalg.norm(moved, 2)) * _unit_factor(units))

dynamical_matrices(qs)

Dynamical matrices at several fractional wavevectors at once.

The blocks are first summed into one mass-weighted real matrix per distinct shift S, which needs doing once, and then each D(q) is a phase-weighted sum of those -- one matrix product for every q at once, instead of a scatter over every block for each. Where the per-shift matrices would be too large to hold, each q is scattered instead.

Parameters:

Name Type Description Default
qs

(M, 3) fractional wavevectors

required

Returns:

Type Description
ndarray

(M, 3N, 3N) complex Hermitian matrices in eV/(Angstrom^2 amu)

Source code in chmpy/vib/force_constants.py
def dynamical_matrices(self, qs) -> np.ndarray:
    """Dynamical matrices at several fractional wavevectors at once.

    The blocks are first summed into one mass-weighted real matrix per
    distinct shift `S`, which needs doing once, and then each `D(q)` is a
    phase-weighted sum of those -- one matrix product for every q at once,
    instead of a scatter over every block for each. Where the per-shift
    matrices would be too large to hold, each q is scattered instead.

    Args:
        qs: (M, 3) fractional wavevectors

    Returns:
        (M, 3N, 3N) complex Hermitian matrices in eV/(Angstrom^2 amu)
    """
    qs = np.asarray(qs, dtype=float).reshape(-1, 3)
    n3 = 3 * self.n_atoms
    by_shift = self._by_shift()
    if by_shift is not None:
        shifts, matrices = by_shift
        phases = np.exp(2j * np.pi * (qs @ shifts.T))
        result = (phases @ matrices.reshape(len(shifts), -1)).reshape(-1, n3, n3)
    else:
        result = np.stack([self._scatter(q) for q in qs])
    # the sum is Hermitian in exact arithmetic; make it so in practice
    return 0.5 * (result + result.conj().transpose(0, 2, 1))

dynamical_matrix(q)

The (3N, 3N) dynamical matrix at a fractional wavevector.

Parameters:

Name Type Description Default
q

(3,) wavevector in fractional reciprocal coordinates, so that the phase is exp(2 pi i q.S) with S the integer shift

required

Returns:

Type Description
ndarray

(3N, 3N) complex Hermitian matrix in eV/(Angstrom^2 amu)

Source code in chmpy/vib/force_constants.py
def dynamical_matrix(self, q) -> np.ndarray:
    """The (3N, 3N) dynamical matrix at a fractional wavevector.

    Args:
        q: (3,) wavevector in fractional reciprocal coordinates, so that
            the phase is `exp(2 pi i q.S)` with `S` the integer shift

    Returns:
        (3N, 3N) complex Hermitian matrix in eV/(Angstrom^2 amu)
    """
    return self.dynamical_matrices(np.reshape(q, (1, 3)))[0]

frequencies(q, units='thz')

Phonon frequencies at one or more wavevectors, ordered low to high.

A negative frequency is reported for an imaginary mode, which is the usual convention and keeps the array real.

Parameters:

Name Type Description Default
q

(3,) fractional wavevector, or (M, 3) for several

required
units str

"thz", "cm-1", or "rad/s"

'thz'

Returns:

Type Description
ndarray

(3N,) frequencies, or (M, 3N) for several wavevectors

Source code in chmpy/vib/force_constants.py
def frequencies(self, q, units: str = "thz") -> np.ndarray:
    """Phonon frequencies at one or more wavevectors, ordered low to high.

    A negative frequency is reported for an imaginary mode, which is the
    usual convention and keeps the array real.

    Args:
        q: (3,) fractional wavevector, or (M, 3) for several
        units: "thz", "cm-1", or "rad/s"

    Returns:
        (3N,) frequencies, or (M, 3N) for several wavevectors
    """
    factor = _unit_factor(units)
    q = np.asarray(q, dtype=float)
    eigenvalues = np.linalg.eigvalsh(self.dynamical_matrices(q.reshape(-1, 3)))
    omega = _omega(eigenvalues) * factor
    return omega[0] if q.ndim == 1 else omega

gamma_hessian()

(3N, 3N) d2E/du du for displacements repeated in every cell, eV/A^2.

The q = 0 sum of each block over its images, without the mass weighting of the dynamical matrix: the Hessian of the unit cell with periodic boundary conditions, which is what relaxing the atoms of a strained cell responds to.

Source code in chmpy/vib/force_constants.py
def gamma_hessian(self) -> np.ndarray:
    """(3N, 3N) d2E/du du for displacements repeated in every cell, eV/A^2.

    The q = 0 sum of each block over its images, without the mass
    weighting of the dynamical matrix: the Hessian of the unit cell with
    periodic boundary conditions, which is what relaxing the atoms of a
    strained cell responds to.
    """
    n = self.n_atoms
    hessian = np.zeros((n, n, 3, 3))
    np.add.at(
        hessian,
        (self.pairs[:, 0], self.pairs[:, 1]),
        self.weights[:, None, None] * self.blocks,
    )
    return hessian.transpose(0, 2, 1, 3).reshape(3 * n, 3 * n)

optical_frequencies(units='thz')

The 3N - 3 optical frequencies at Gamma, ordered low to high.

The three uniform translations are projected out of the dynamical matrix before it is diagonalised, rather than dropped as the three lowest frequencies or those under a threshold. That way a soft optical mode is never mistaken for an acoustic one, and an imaginary optical mode is still reported as one.

Source code in chmpy/vib/force_constants.py
def optical_frequencies(self, units: str = "thz") -> np.ndarray:
    """The 3N - 3 optical frequencies at Gamma, ordered low to high.

    The three uniform translations are projected out of the dynamical
    matrix before it is diagonalised, rather than dropped as the three
    lowest frequencies or those under a threshold. That way a soft optical
    mode is never mistaken for an acoustic one, and an imaginary optical
    mode is still reported as one.
    """
    factor = _unit_factor(units)
    complement = self._translation_complement()
    matrix = self.dynamical_matrix(np.zeros(3)).real
    projected = complement.T @ matrix @ complement
    eigenvalues = np.linalg.eigvalsh(0.5 * (projected + projected.T))
    return _omega(eigenvalues) * factor

force_constants(structure, calculator, supercell=None, displacement=DEFAULT_DISPLACEMENT, cutoff=None, info=None, progress=None, symmetry=True, batch=False)

Measure force constants by displacing atoms in a supercell.

With symmetry, one atom per orbit is displaced, along only as many directions as its site symmetry needs to span all three (one on a cubic site, three on a general position). The other blocks follow from Phi(g(r), g(k)) = R_g Phi(r, k) R_g^T.

Parameters:

Name Type Description Default
structure

a Crystal or a periodic System, already relaxed

required
calculator

a chmpy.calc.Calculator

required
supercell

(3,) repetitions, or None to choose one from cutoff

None
displacement float

finite-difference step in Angstroms

DEFAULT_DISPLACEMENT
cutoff float | None

interaction range in Angstroms used to size the supercell when one is not given; defaults to a third of the smallest supercell width that supercell provides

None
info

model inputs that are not geometry, carried on every System

None
progress

True to print a line per displacement, or a callable given a chmpy.opt.progress.Progress for each

None
symmetry bool

use a Crystal's space group to reduce the displacements. A System carries no symmetry and every atom is displaced.

True
batch bool

evaluate every displaced cell in one calculator.batch call rather than one at a time. Worth it for small cells on a model with a native batch path; for large supercells it can be slower.

False

Returns:

Type Description
ForceConstants

ForceConstants

Source code in chmpy/vib/force_constants.py
def force_constants(
    structure,
    calculator,
    supercell=None,
    displacement: float = DEFAULT_DISPLACEMENT,
    cutoff: float | None = None,
    info=None,
    progress=None,
    symmetry: bool = True,
    batch: bool = False,
) -> ForceConstants:
    """Measure force constants by displacing atoms in a supercell.

    With symmetry, one atom per orbit is displaced, along only as many
    directions as its site symmetry needs to span all three (one on a cubic
    site, three on a general position). The other blocks follow from
    `Phi(g(r), g(k)) = R_g Phi(r, k) R_g^T`.

    Args:
        structure: a `Crystal` or a periodic `System`, already relaxed
        calculator: a `chmpy.calc.Calculator`
        supercell: (3,) repetitions, or None to choose one from `cutoff`
        displacement: finite-difference step in Angstroms
        cutoff: interaction range in Angstroms used to size the supercell when
            one is not given; defaults to a third of the smallest supercell
            width that `supercell` provides
        info: model inputs that are not geometry, carried on every `System`
        progress: True to print a line per displacement, or a callable given
            a `chmpy.opt.progress.Progress` for each
        symmetry: use a `Crystal`'s space group to reduce the displacements.
            A `System` carries no symmetry and every atom is displaced.
        batch: evaluate every displaced cell in one `calculator.batch` call
            rather than one at a time. Worth it for small cells on a model
            with a native batch path; for large supercells it can be slower.

    Returns:
        ForceConstants
    """
    system = _as_system(structure, info)
    if not system.periodic:
        raise ValueError("force constants need a periodic structure")

    repeats = (
        np.array(supercell, dtype=int)
        if supercell is not None
        else _supercell_for(system, cutoff or 8.0)
    )
    plan = DisplacementPlan(structure, system, repeats, symmetry, displacement)

    report = reporter(progress)
    report(
        "force constants",
        "setup",
        f"force constants: {plan.total} displacements of {len(plan.plan)} of "
        f"{len(system)} atoms, {len(plan.atom_map)} operations, supercell "
        f"{repeats.tolist()} ({len(plan.supercell)} atoms)",
    )

    if batch:
        results = calculator.batch(plan.systems(), (FORCES,))
        return plan.solve([result.forces for result in results])

    forces = []
    scratch = plan.supercell.copy()
    for done, (representative, direction, sign) in enumerate(plan.displacements()):
        if sign > 0:
            stage = f"atom {representative} along {np.round(direction, 4).tolist()}"
            report("force constants", stage, stage, index=done // 2, total=plan.total)
        scratch.set_positions(plan.positions(representative, direction, sign))
        forces.append(calculator.forces(scratch))
    return plan.solve(forces)

symmetrise(constants)

Impose permutation symmetry and the acoustic sum rule together.

  • Permutation. Phi_ab(i,j,S) and Phi_ba(j,i,-S) are the same second derivative measured from opposite ends. Finite differences give them slightly differently, and their average is the better estimate -- the same free error signal the elastic tensor gets from its asymmetry.
  • Acoustic sum rule. Translating the whole crystal costs nothing, so sum_(j,S) w Phi(i,j,S) = 0 for every i.

Each is a linear constraint, and the answer wanted is the closest set of constants satisfying both. Imposing them once each in turn does not get there: a residual that is not symmetric cannot be removed by changing only the symmetric self block, and the part left over reappears as a sum-rule error in the dynamical matrix, which is Hermitian, of a size that shows up as acoustic modes at Gamma that are not quite zero. Alternating the two projections does converge, but can take hundreds of sweeps.

So the projection onto both is solved for directly. After permutation symmetry, the closest constants obeying the sum rule are Phi - P(w Lambda_i), with P the permutation average and one 3x3 multiplier Lambda_i per atom chosen so that every row sums to zero. That condition is a symmetric positive semi-definite linear system in the multipliers, solved by conjugate gradients to round-off.

Source code in chmpy/vib/force_constants.py
def symmetrise(constants: ForceConstants) -> ForceConstants:
    """Impose permutation symmetry and the acoustic sum rule together.

    * **Permutation.** `Phi_ab(i,j,S)` and `Phi_ba(j,i,-S)` are the same
      second derivative measured from opposite ends. Finite differences give
      them slightly differently, and their average is the better estimate --
      the same free error signal the elastic tensor gets from its asymmetry.
    * **Acoustic sum rule.** Translating the whole crystal costs nothing, so
      `sum_(j,S) w Phi(i,j,S) = 0` for every `i`.

    Each is a linear constraint, and the answer wanted is the closest set of
    constants satisfying both. Imposing them once each in turn does not get
    there: a residual that is not symmetric cannot be removed by changing only
    the symmetric self block, and the part left over reappears as a
    sum-rule error in the dynamical matrix, which is Hermitian, of a size
    that shows up as acoustic modes at Gamma that are not quite zero.
    Alternating the two projections does converge, but can take hundreds of
    sweeps.

    So the projection onto both is solved for directly. After permutation
    symmetry, the closest constants obeying the sum rule are
    `Phi - P(w Lambda_i)`, with `P` the permutation average and one 3x3
    multiplier `Lambda_i` per atom chosen so that every row sums to zero.
    That condition is a symmetric positive semi-definite linear system in the
    multipliers, solved by conjugate gradients to round-off.
    """
    blocks = np.array(constants.blocks)
    pairs, shifts, weights = constants.pairs, constants.shifts, constants.weights
    n = constants.n_atoms
    partner = _permutation_partners(pairs, shifts)
    has_partner = partner >= 0
    row = pairs[:, 0]
    index = (9 * row[:, None] + np.arange(9)).ravel()

    def permute(values):
        result = np.array(values)
        mirrored = values[partner[has_partner]].transpose(0, 2, 1)
        result[has_partner] = 0.5 * (values[has_partner] + mirrored)
        return result

    def row_sums(values):
        weighted = (weights[:, None, None] * values).ravel()
        return np.bincount(index, weights=weighted, minlength=9 * n).reshape(n, 3, 3)

    def correction(multipliers):
        return permute(weights[:, None, None] * multipliers[row])

    blocks = permute(blocks)
    residual = row_sums(blocks)
    tolerance = SUM_RULE_TOLERANCE * max(float(np.abs(blocks).max(initial=0.0)), 1e-300)
    multipliers, left = _conjugate_gradient(
        lambda x: row_sums(correction(x)), residual, tolerance, SUM_RULE_ITERATIONS
    )
    blocks -= correction(multipliers)
    if left > tolerance:
        LOG.warning(
            "the acoustic sum rule converged only to %.1e eV/A^2 per atom", left
        )

    return ForceConstants(
        pairs=pairs,
        shifts=shifts,
        blocks=blocks,
        weights=constants.weights,
        masses=constants.masses,
        cell=constants.cell,
        positions=constants.positions,
    )