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 |
required | |
system
|
|
required | |
repeats
|
(3,) supercell repetitions |
required | |
symmetry
|
use a |
required | |
displacement
|
finite-difference step, Angstroms |
required |
Source code in chmpy/vib/force_constants.py
367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 | |
displacements()
(representative, direction, sign) for every displaced cell, in order
positions(representative, direction, sign)
(M, 3) supercell positions for one displacement
Source code in chmpy/vib/force_constants.py
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 |
required |
Source code in chmpy/vib/force_constants.py
systems()
Every displaced supercell, in the order solve expects their forces
Source code in chmpy/vib/force_constants.py
ForceConstants
dataclass
Harmonic force constants of a periodic structure.
Attributes:
| Name | Type | Description |
|---|---|---|
pairs |
ndarray
|
(P, 2) the atom indices |
shifts |
ndarray
|
(P, 3) integer lattice translation taking |
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
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 | |
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
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
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 |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
(3N, 3N) complex Hermitian matrix in eV/(Angstrom^2 amu) |
Source code in chmpy/vib/force_constants.py
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
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
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
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 |
required | |
calculator
|
a |
required | |
supercell
|
(3,) repetitions, or None to choose one from |
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 |
None
|
info
|
model inputs that are not geometry, carried on every |
None
|
|
progress
|
True to print a line per displacement, or a callable given
a |
None
|
|
symmetry
|
bool
|
use a |
True
|
batch
|
bool
|
evaluate every displaced cell in one |
False
|
Returns:
| Type | Description |
|---|---|
ForceConstants
|
ForceConstants |
Source code in chmpy/vib/force_constants.py
symmetrise(constants)
Impose permutation symmetry and the acoustic sum rule together.
- Permutation.
Phi_ab(i,j,S)andPhi_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) = 0for everyi.
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.