Design: strain derivative and stress on the cyclic cluster routes¶
Status (#1118, #1120): the contract below is implemented in full for
DFTB0-SECCM and SCC-DFTB-SECCM (analytic, one to three periodic dimensions,
every long-range closure, screened overlap and smearing), for the
Slater-Koster DFTB0/DFTB2/DFTB3-SECCM routes (same scope, with the
lattice-summed short-range closure and DFTB+ stress parity on diamond and
MgO; tests/test_seccm_sk_dftb_stress.py,
tests/test_sk_dftb_dftbplus_parity.py), for GFN2-SECCM, PM6-SECCM and
OM2/OM3-SECCM (sections below and the engines’ design notes) and for
MSINDO-SECCM (analytic, one to three periodic dimensions, every Madelung
kernel; section “MSINDO-SECCM”). The elastic-constant driver built on the
stress is described in “Elastic constants”. SECCM is experimental and so is
its stress.
The energy as a function of the cell¶
A cyclic cluster is a Born-von Karman supercell of N primitive cells with
the Wigner-Seitz weighting of
Bredow, Geudtner and Jug 2001
and Peintinger and Bredow 2014. Every
interaction of a central atom I with another atom J is evaluated at the
images of J that are closest to I, each with weight 1/n when n images
are equally close. The topology is this list of directed records
(I, J, label, w), where the integer label names the cyclic translation
T(label) = sum_i label_i T_i of the image. The geometry enters every
SECCM energy only through
the record displacements
d = R_J + T(label) - R_I, andthe cyclic translations
T_ithemselves, in the Ewald and Madelung lattice sums of the long-range closures.
Write the primitive lattice as the columns of h and the atoms in fractional
coordinates s, so R = h s and T_i = n_i h_i. At fixed topology (the
record list and its weights frozen) the energy per primitive cell E(h, s)
is a smooth function, and this is the function all derivatives here refer
to. The atomic gradients already use this convention
(SECCMTopology.rebuild_displacements).
When a strain keeps the topology¶
Record identity is the integer label, a statement in fractional space. A
homogeneous deformation x -> F x of atoms and lattice maps every record
displacement to F d and keeps the record list by construction. What a
finite deformation can change is the builder’s answer: which image is the
closest one. Three cases:
No ties. The closest image changes when a candidate crosses a Wigner-Seitz face. The builder records the margin of every candidate, the distance of its Wigner-Seitz score
max_v (v . d) / |v|^2from the face value 1/2 (vruns over the first-shell lattice vectors). A strainepschanges a score to first order by at most2 |eps| (|d|/|v| + 1/2), so the minimum margin bounds the admissible strain.SECCMTopology.switching_margin_excluding_tiesis that minimum and every stress result carries it. The exact test for a finite strain isrebuild_for_cell(..., check=True), which raisesSECCMTopologyChangedError, or a comparison of the fingerprint of a freshly built topology.Exact ties (shared images; generic for cubic, hexagonal and centred lattices and for even replica counts). A uniform scaling keeps every tie. Any other strain splits ties: the rebuilt topology keeps only the nearer images, the fixed topology keeps all of them with their frozen weights. The two energies agree at zero strain and the rebuilt one has a cusp there, with one-sided slopes
+-|f'(r)| |dr/d eps|for the split pair interactionf. The fixed-topology energy is the smooth continuation and its derivative is the mean of the one-sided slopes. Because a uniform scaling keeps the ties,trace(dE/d eps)is also the volume derivative of an energy-volume scan with rebuilt topology.A finite strain past the margin. The topology changes and the energy is only piecewise smooth. The cell optimiser therefore works at fixed topology inside a macro-iteration, rebuilds the topology between macro-iterations, records whether it changed and the energy step this caused, and judges convergence on a fresh topology only.
Definitions¶
Strain. A homogeneous strain moves every point as x -> (1 + eps) x
(Doll 2010, Eq. 1). Lattice
vectors are columns, so h -> (1 + eps) h, and the fractional coordinates
are fixed. This is the convention of vibeqc.bipole_stress, of MSINDO-CCM
(ccm_strain_derivative_analytic) and of MACE-CCM.
Strain derivative. Every engine returns
W_ab = dE_cell / d eps_ab (Hartree, derivative index first)
at fixed topology, unsymmetrized. For a rotationally invariant energy
W is symmetric; the antisymmetric part is kept as a diagnostic and must
vanish to rounding.
Stress (three dimensions): sigma = sym(W) / V in Hartree/bohr^3 with V
the primitive-cell volume. The sign is tensile positive: a compressed
crystal has negative diagonal stress and the pressure is
p = -trace(sigma) / 3 (Doll 2010, Eqs. 9-11; the periodic semiempirical
stress in semiempirical/gradient.cpp and MSINDO-CCM use the same sign).
One Hartree/bohr^3 is 29421.0157 GPa.
Lower dimensions: periodic_stress = P sym(W) P / m, with P the projector
onto the span of the periodic lattice vectors and m the length (1-D,
Hartree/bohr: the line tension times the axis dyad), the area (2-D,
Hartree/bohr^2: the in-plane stress) or the volume (3-D, equal to sigma).
These are the definitions and names of
ExperimentalMACECCMResult.periodic_stress. The full W is still returned
in every dimension: its components along non-periodic directions are the
ordinary virial of the atoms in those directions and are not a cell
deformation.
Voigt order (xx, yy, zz, yz, xz, xy) with engineering shear strains (Doll
2010, Eq. 3).
Cell gradient. With the periodic lattice vectors as the columns of A
(3 x dim), dA = eps A and dE = W : eps give
dE/dA = W A (A^T A)^-1 (Hartree/bohr, fixed fractional coordinates)
which is W h^-T in three dimensions. Atoms keep their fractional
coordinates along the periodic vectors and their Cartesian component
perpendicular to them; that component is orthogonal to A and drops out.
Normalisation. Energies, gradients and W are per primitive cell: cluster
totals divided by the group order N. The gradient of the energy per cell
with respect to a primitive site is the sum of the cluster gradient over the
N copies of the site.
The strain derivative term by term¶
Pair terms: the record virial¶
For an energy that is a sum over directed records of a function of the
record displacement, E = sum_rec e_rec(d), the chain rule with
d -> (1 + eps) d gives
dE/d eps_ab = sum_rec (d e_rec / d d_a) d_b .
The gradient is the other contraction of the same per-record derivative
f = d e_rec / dd: -f on the central atom and +f on the origin atom.
For a radial term e_rec = c u(|d|) this is the familiar
c u'(r) d_a d_b / r. The pair repulsion (c = w/2) and the
Wigner-Seitz-truncated SCC term (c = w q_I q_J / 2, u = gamma) are of
this form. Both mirror records of a pair are in the sum, so no factor is
lost or doubled.
One-electron terms and the generalized eigenproblem¶
The DFTB-family band energy depends on the geometry through the cyclic
overlap S = sum_rec w S(d) and H0 = kappa hbar S. With the density D
and the energy-weighted density W_e = C n eps C^T, stationarity of the
orbitals at fixed occupations gives
(Elstner et al. 1998, Eqs. 20-25)
dE = sum_rec w sum_{mu in I, nu in J} M_mu,nu dS_mu,nu(d),
M = -W_e + K + D (kappa hbar_IJ - (V_I + V_J)/2),
where V is the SCC (and Madelung) potential, absent for DFTB0, and K is
the response of the retained overlap subspace when the cyclic overlap is
screened (next paragraph). The overlap of two atom-centred functions with
space-fixed axes depends on the centre displacement only, so
dS/d eps_ab = (dS/dd)_a d_b and
dE/d eps_ab = sum_rec w sum_{mu nu} M_mu,nu (dS_mu,nu/dd)_a d_b .
The -W_e : dS part is the Pulay term of the generalized eigenproblem. The
matrix M and the record blocks -w M are built once; the gradient
(overlap_lattice_gradient_contribution) and the strain derivative
(overlap_record_strain_contribution) are its two contractions.
Screened overlap. When the cyclic overlap has eigenvalues at or below the
screening threshold (Peintinger and Bredow 2014, critical eigenvalues), the
variational space is the retained eigenspace and moves with the geometry.
Its projector response K (screened_overlap_projector_response) is a
matrix contracted with dS like the rest of M, so it enters the strain
derivative unchanged. As for the gradient, an eigenvalue at the threshold is
refused.
Smearing. At finite electronic temperature the objective is the Mermin free
energy A = E - T S
(Weinert and Davenport 1992).
A is stationary in the occupations, so the entropy term has no explicit
strain contribution: W_e and D are built with the fractional
occupations and nothing else changes. A fractional zero-temperature
ensemble is refused, like its gradient.
Self-consistency. The SCC energy is variational in the Mulliken charges
(the potential in M is the derivative of the full second-order term,
Madelung embedding included), so the charges are held fixed and no response
equation is needed.
Ewald and Madelung terms¶
Both long-range closures contain the Ewald-regularised lattice potential
Phi(v) of a unit point charge and its cyclic images:
Ewald-completed gamma:
E = 1/2 sum_IJ q_I q_J Phi(R_J - R_I) + 1/2 sum_rec w q_I q_J [gamma(r) - 1/r] + on-site. The remainder is a pair term. The Ewald part gives1/2 sum_IJ q_I q_J dPhi/d eps (R_J - R_I), same-site terms included.Madelung embedding:
E = 1/2 sum_I q_I sum_{rec in EWS(I)} w q_J [Phi(-d) - 1/|d|]over the Wigner-Seitz records plus each atom’s own image. The-1/|d|subtraction is a pair term; the rest is1/2 w q_I q_J dPhi/d eps (d).
The own-image (same-site) potential has no gradient but it does have a strain derivative, because the lattice self-potential depends on the cell.
The Ewald parameter. seccm_ewald_alpha chooses alpha from the cell
(sqrt(pi) / V^(1/3), 0.85 sqrt(pi/A), 4/L), so alpha changes under
strain. The converged sum does not depend on alpha, hence
dPhi/d eps = (partial Phi / partial eps) at fixed alpha. This is checked,
not assumed: the kernels are evaluated at two values of alpha and their
values and strain derivatives agree to 1e-13.
Three dimensions (Nielsen and Martin 1985):
Phi(v) = sum_{k != 0} c_k cos(k.v) + sum_L g(|v + L|) - pi/(V alpha^2) [- 2 alpha/sqrt(pi)],
c_k = 4 pi exp(-k^2/4 alpha^2) / (V k^2), g(r) = erfc(alpha r)/r .
Under strain the phase k.v is invariant, k -> (1 - eps) k and
V -> V (1 + tr eps), so
dPhi/d eps_ab = sum_k c_k cos(k.v) [2 k_a k_b (1/k^2 + 1/(4 alpha^2)) - delta_ab]
+ sum_L g'(r) r_a r_b / r + pi/(V alpha^2) delta_ab .
The first term holds the reciprocal-vector derivative and the volume
derivative of the prefactor, the last one the volume derivative of the
neutralising background. The self term in brackets is constant at fixed
alpha.
Two dimensions (the sum of Parry 1975
in the per-pair form of
de Leeuw and Perram 1979).
With n the plane normal, z = v.n, K the in-plane reciprocal vectors
and A the cell area,
Phi(v) = (pi/A) sum_K cos(K.v) F(K, z)/K - (2 pi/A) [z erf(alpha z) + exp(-alpha^2 z^2)/(alpha sqrt(pi))] + sum_L g(|v + L|),
F = exp(Kz) erfc(alpha z + K/2 alpha) + exp(-Kz) erfc(-alpha z + K/2 alpha).
A general symmetric strain tilts the plane with the lattice. To first order
dA = A (delta_ab - n_a n_b), dz = z n_a n_b,
d|K| = -K_a K_b / |K|, d(K.v) = z (K_a n_b + n_a K_b),
the last one because a point at height z moves in the plane by
2 z eps.n relative to the lattice. With dF/dz = K G,
G = exp(Kz) erfc(alpha z + K/2 alpha) - exp(-Kz) erfc(-alpha z + K/2 alpha),
and dF/dK = z G - 2 exp(-alpha^2 z^2 - K^2/4 alpha^2)/(alpha sqrt(pi))
the derivative follows by the chain rule. For the in-plane components this
is the area, reciprocal-vector and real-space derivative; the components
with n are the virial of the height coordinate.
One dimension. The background-corrected wire potential (seccm/ewald_1d.h)
is rotation invariant and homogeneous of degree -1 in (v, T). Writing
Phi = phi(z, rho, L) with t = T/L, z = v.t, rho = v - z t, the chain
rule and Euler’s theorem z phi_z + |rho| phi_rho + L phi_L = -phi give
dPhi/d eps_ab = -(Phi + g_perp.rho) t_a t_b + g_par (t_a rho_b + rho_a t_b) + g_perp,a rho_b,
with g = dPhi/dv split into its parts along and perpendicular to the
axis. No derivative with respect to the period is needed.
In every dimension Phi is homogeneous of degree -1, so
trace(dPhi/d eps) = -Phi; this identity is one of the tests.
What is implemented and how it was checked¶
Native (cpp/src/semiempirical/seccm/): seccm_strain.h,
seccm_overlap_strain.h, ewald_1d.h, dftb0.cpp, scc_dftb.cpp,
sk_dftb.cpp (the Slater-Koster block derivatives contracted record by
record, the same arithmetic as its gradient). Python:
vibeqc.semiempirical.seccm.cell (conversions, SECCMStress,
fixed-topology finite differences, the cell optimiser) and
seccm_strain_scan.
Checks, all on a triclinic cell with a polar two-species basis and none of them using a symmetry that could hide a term:
kernel level:
dPhi/d epsagainst central differences of the closed-form potential on a strained lattice in one, two and three dimensions, same-site and pair arguments, agreement to 6e-12;trace = -Phito 2e-13;Madelung strain derivative against central differences of the embedding energy at fixed (non-neutral) charges in one, two and three dimensions (8e-12), and against
indo::_madelung_virialin three (2e-16);total: analytic
Wagainst fourth-order central differences of the fixed-topology energy for DFTB0 and for SCC-DFTB with the Wigner-Seitz, Madelung and Ewald-gamma closures, Klopman-Ohno and Elstner kernels, with and without smearing, in one, two and three dimensions: all nine components within 2.2e-10 Hartree, antisymmetric part below 3e-16.screened overlap: a dense (2, 2, 2) cluster with one negative overlap mode, analytic against central differences within 4e-8 Hartree;
invariances:
W -> Q W Q^Tunder a rigid rotation, unchanged under a rigid translation and under naming an atom by another lattice copy; the Madelung and Ewald-gamma closures, one kernel in exact arithmetic, give the sameWto 1e-8;trace(W)against the derivative of a rebuilt-topology volume scan on a simple cubic cell with shares down to 1/8.
The regression tests are tests/test_seccm_stress.py,
tests/test_seccm_cell.py and tests/test_seccm_lattices.py.
PM6-SECCM (seccm/pm6.cpp, tests/test_pm6_seccm_stress.py) follows the
contract with the pair-term rule alone plus the Madelung helper. Each
directed record contributes f d^T with f the derivative of the record’s
NDDO pair energy with respect to its displacement, the same intermediate
the analytic gradient scatters to the two atoms; the core-core term enters
with half the record weight. The NDDO basis is orthonormal for every cell,
so the generalized-eigenproblem (Pulay) term of the DFTB family is absent,
and the embedding charges are diagonal populations, so the Madelung term is
seccm_madelung_strain_derivative at fixed charges with no overlap part.
Measured on the gradient test cells (LiH, HF and LiH with He chains, the
h-BN sheet, with and without embedding, one tilted chain and an
acknowledged truncated 3-D cell): all nine components within 8e-8 Hartree of
the fixed-topology central difference at h = 1e-4 (scaling as h^2),
antisymmetric part below 3e-13, rotation covariance to 1e-14.
The faded-pair 3-D model of PM6-SECCM
(its design note, section
“Derivatives of the faded-pair variant”) keeps this contract. Each faded
record and each Coulomb-only completion image deposits f d^T with the
fade derivative included exactly, and the Ewald sum of the net charges is
the 3-D case of seccm_madelung_strain_derivative. Its fixed topology
adds the completion image set (lattice labels inside the completion radius,
weights 1 - w_WS from the frozen WS weights) to the WS records. An image
crossing the completion radius moves the energy by less than 1e-10 of its
remainder, so the WS switching margins recorded by the topology builder
remain the bound on the admissible strain. The fade is continuously
differentiable but its second derivative jumps at the onset R0, which
matters for second derivatives only. The regression tests are in
tests/test_pm6_seccm_faded_pair.py.
Cell optimisation¶
optimize_seccm_cell uses the two derivatives together. Inside a
macro-iteration the variables are the atoms’ coordinates X in the frame of
the macro-iteration and the coefficients e_k of a symmetric strain
eps = sum_k e_k B_k, with h = F h0, R = F X and F = 1 + eps. The
gradient of the fixed-topology energy in these variables is exact:
dE/dX = F^T g (g: gradient of the primitive sites)
dE/de_k = W : (B_k F^-1) (W: strain derivative at the current cell)
because a change of e_k deforms the current configuration homogeneously
with velocity gradient B_k F^-1. At fixed volume F is rescaled within
the periodic subspace to unit determinant and the basis is traceless. The
strain basis B_k holds the constraints: all symmetric strains of the
periodic directions, projected on the invariants of the lattice point group
(spglib on the bare lattice; the Bravais lattice type is kept) or of the
crystal’s space group, without the uniform scaling at fixed volume, only
the uniform scaling at fixed shape, and without the strains that change a
fixed lattice parameter to first order (the parameters are restored exactly
after the macro-iteration). The minimiser is SciPy’s L-BFGS-B, as in
vibeqc.bipole_optimize.
Between macro-iterations the topology is rebuilt at the new cell. The result
lists for every rebuild whether the record set changed and the energy step
it caused, and convergence (forces and the stress residual in the allowed
strain space, both thresholds recorded) is judged on the fresh topology. On
the DFTB0 toy crystals of tests/test_seccm_cell.py (rocksalt, a hexagonal
hP2 cell, a triclinic cell with fixed angles, a wire and a sheet) the
optimiser reaches stress residuals below 1e-7 Hartree/bohr^3, reaches the
same cell from differently strained starts to 1e-4 relative, and records
topology changes with energy steps between 1e-4 and 1e-7 Hartree on the way.
Inner-loop economy. The L-BFGS-B run of a macro-iteration uses
gtol = ftol = 0 so that it never stops above the requested tolerances on
its own criteria. It therefore stops on three rules: forces and stresses at
half the tolerances; the strain at max_strain_per_macro_iteration with the
forces converged (the next macro-iteration continues on a fresh topology);
and the enthalpy unchanged to 1e-13 relative over two iterations. Without
the last two rules the line searches of a bound or converged macro step
spent their evaluations on gradient noise. Energy evaluations on the DFTB0
toy crystals, before and after (the same minima): rocksalt from a = 6.5
9 and 8, from a = 5.8 6 and 6, hP2 (two strains) 18 and 13, triclinic with
fixed angles 47 and 41, hP2 at fixed volume 6 and 6, the wire 46 and 13, the
sheet 34 and 10, and a free rocksalt cell with free atoms (12 variables)
204 and 36. A diagonal model-Hessian scaling (preconditioner="model":
model_bond_stiffness for atoms, an isotropic model_bulk_modulus for the
strains) gave 7, 7, 14, 36, 6, 15, 11 and 107 on the same cells: no net
gain, so it is opt-in. Scaling the first L-BFGS-B step to the model Newton
step was worse still (the triclinic cell did not converge in 21
macro-iterations) and was dropped. The toy crystals are saddles in their
internal coordinates, so the free-atom relaxations end in lower-symmetry
minima; the counts measure the inner loop, not the physics.
MSINDO-SECCM¶
Convention. ccm_strain_derivative_analytic (native indo:: ccm_strain_derivative_analytic, Python reference
_python_derivatives_on_topology) is dE/d eps_ab of the whole cyclic
cluster for x -> (1 + eps) x of atoms and cyclic translations together,
derivative index first (W += w/2 D d^T, D = dE/dd of the record), at
the frozen Wigner-Seitz weights: the contract’s sign and index order. The
front door divides it by the group order N; ccm_stress_analytic divides
it by the cyclic-cluster volume, N V, and so is the same stress (up to
the symmetrisation the contract applies). The gradient is divided by N in
the same way.
Topology. The MSINDO engine builds its Wigner-Seitz cells with the shared
builder (seccm.topology.build_seccm_topology, the native twin), so the
front door’s topology of the same cluster holds the same records, labels
and weights. An energy without derivatives and without a topology keeps the
native route (topology_fingerprint = "not-applicable"). A cluster that
carries a topology built from its own geometry also runs the native route;
a cluster re-evaluated on a deformed cell by deformed_cluster (its
reference coordinates differ from its current ones) runs
run_seccm(molecule, options, topology=...), which evaluates exactly those
records (indo::ccm_derivatives_on_topology through the binding
ccm_derivatives_on_records, Python reference otherwise). Derivatives
(compute_gradient, compute_stress) are always taken on the cluster’s
topology from one SCF at gradient_conv_tol, whose energy and net charges
must equal the reported ones; a request with derivatives therefore reports
the energy of the frozen route as well, on bit-identical inputs
(seccm_engine_inputs). The MSINDO energy reacts to roundoff-level changes
of the pair geometry: on LiH (3,3,3) the native record build and the
front-door records (identical labels, weights and displacements to 4e-15
bohr) give energies 1.6e-8 Hartree per cluster apart, more than the state
check admits at tight tolerances, and a rigid rotation of the same cluster
changes its energy by 1.5e-8 Hartree, while perturbations of 1e-15 bohr of
one representation move it by 1e-12 only. The source in the engine is not
isolated. Checked: at zero strain the frozen route
reproduces the native energy to 1e-9 Hartree; strains inside the switching
margin pass rebuild_for_cell(check=True); a frozen strain scan of LiH is
smooth to 1e-9 Hartree rms and its slope equals W : D.
Units. run_seccm hands the engine Angstrom converted with vibe-qc’s
constant, and the engine converts back with MSINDO’s, so the engine
evaluates the cluster uniformly scaled by
seccm_engine_length_scale() = 1 - 8.8e-8. Every frozen evaluation and
derivative applies the same factor. A uniform scaling commutes with
1 + eps, so W needs no correction and the gradient takes the factor
once; the legacy ccm_stress_analytic divides by the engine’s volume and
differs from the contract’s stress by s^3.
Madelung terms. The energy is 1/2 sum_I q_I sum_{rec in EWS(I)} w q_o h(d)
over the Ewald WS set (own image included) at fixed net charges (the SCF is
variational in the density):
1-D truncated (default):
h = sum_{s in +-T, +-2T} 1/|d + s|; every vector scales,dh/d eps = -sum x x^T / |x|^3.1-D wire Ewald (opt-in):
h = Phi(-d) - 1/|d|with the kernel of_madkonst_1d_wire, which is exactly homogeneous of degree -1 (its truncations scale withL:alpha = 4/L, fixed image and channel counts), so the Euler form of “One dimension” above applies withg = dPhi/dvfrom_wire_kernel_value_gradient(twin ofdetail::wire_kernel_gradient). Python only, as the energy.2-D Parry/Heyes:
h = Phi(-d) - 1/|d|with the element of_madkonst_2d(alpha = 0.85 sqrt(pi/A)held fixed); the first-order changes of “Two dimensions” above (indo::_parry_element_strain, Python_parry_element_strain).3-D Ewald: Nielsen and Martin, as above (
indo::_madelung_virial).
Checks: the kernel strain derivatives and the wire gradient against central
differences of the embedding energy at fixed non-neutral charges on a skewed
cell with out-of-plane offsets, 4e-12 to 1e-11 Hartree in every dimension
(native 2-D: 9e-12); the front-door W against seccm_strain_derivative_fd
(step 1e-4) for LiH (fcc, 2x2x2, H displaced), a LiF sheet (3x3) and a LiH
chain (5 cells), bare and embedded with every kernel: 6e-9 to 3e-8 Hartree,
the FD truncation; antisymmetric parts below 1e-12; native and Python
reference energy, gradient and W on one frozen topology to 1e-9; the
legacy whole-cluster call to 1e-9 after the conversion;
optimize_seccm_cell(constraint="isotropic") reaches the zero-pressure
scale of ccm_optimize_lattice_isotropic to 1e-5 relative. Tests:
tests/test_msindo_ccm_stress.py, tests/test_msindo_ccm.py.
Elastic constants¶
seccm.elastic.seccm_elastic_constants follows the stress-strain definition
of CRYSTAL’s ELASTCON (Perger, Criswell, Civalleri and Dovesi, Comput.
Phys. Commun. 180, 1753 (2009); the procedure of vibeqc.bipole_elastic)
on the energy per primitive cell. For each applied Voigt strain direction
D_u (engineering shear) the cells F = 1 +- h D_u are evaluated on the
reference topology, and B_vu = (sigma_v(+h) - sigma_v(-h)) / 2h with
sigma = sym(W)/V of the strained cell; C = B - Delta(sigma0) with the
pre-stress term of Erba et al. (J. Chem. Phys. 140, 124703 (2014)).
strains="symmetry" applies one strain per orbit of the crystal’s point
group and solves for B by least squares over the rotated images.
Clamped-ion cells keep the fractional coordinates; relaxed-ion cells are
relaxed at fixed cell and topology (L-BFGS-B, analytic gradient). The
reference is relaxed first, its internal-coordinate Hessian (central
differences of the gradient, translations projected out) must have no
negative eigenvalue, and the relaxations at +h and -h must mirror each
other; otherwise relaxed-ion constants are refused. Each strained geometry
is checked with rebuild_for_cell(check=True); when non-tied images switch,
the stress on a rebuilt topology is computed and a difference above
topology_stress_tolerance_gpa refuses the result. Moduli (Hill 1952) and
the Born verdict (Mouhat and Coudert 2014) come from vibeqc.bipole_elastic.
Checks (tests/test_seccm_elastic.py): a synthetic energy with known
clamped C0 and relaxed C0 - Lambda K^-1 Lambda^T tensors, reproduced to
2e-5 and 1e-4 of the largest constant at h = 0.004; DFTB0 rocksalt
(3x3x3) has the cubic pattern exactly from two strains, its
(C11 + 2 C12)/3 equals the EOS B0 (150.9 and 150.8 GPa), the energy
second differences agree with the stresses to 0.005 GPa, and its Born
verdict (unstable, C11 < C12) matches a frozen tetragonal energy scan,
d2E/dt2 / V = 2 (C11 - C12); the hP2 cell reproduces the hexagonal
pattern from three strains and from six, and C33, C44 match frozen
energy scans to 5e-4 relative. Both toys are saddles in their internal
coordinates (the internal Hessian has negative eigenvalues, the H-F
displacement energy curvature is negative), and the relaxed-ion constants
are refused there. On a real crystal at an internal minimum the relaxed-ion
path agrees with the harmonic internal-strain formula. GFN2-SECCM diamond
carbon (2x2x2, a = 3.51045 Å, zero pressure on this cluster) has a positive
internal Hessian, three equal optical eigenvalues of 1.2273 Ha/bohr². At
h = 2e-4 the clamped C44 is 1330.97 GPa. The relaxed C44 is 1186.34 GPa
from the driver and 1186.61 GPa from C44 - Lambda^T H^+ Lambda / V, with
Lambda = dg/de4 taken at the affine positions. The relaxed energy second
difference gives 1188.75 GPa. The Kleinman parameter is 0.4607 from the
driver’s relaxations and 0.4606 from -H^+ Lambda. The shear energy of
this model softens strongly at small strain: E/e4² falls 4 % between
|e4| = 1e-4 and 1e-3, on the 3x3x3 cluster too. At the default step of
0.005 the clamped C44 is therefore 730 GPa from the stress and 847 GPa from
the energies, so a constant must be quoted with its step. A triclinic cell whose images switch under shear gives a
stress step of 0.002 GPa, accepted at the default tolerance and refused
below it.
Contract for the other cyclic engines¶
An engine that offers a stress must:
return the strain derivative
W_ab = dE_cell/d eps_ab(Hartree, per primitive cell, derivative index first, unsymmetrized) at fixed topology on its result asstrain_derivative, computed when the adapter is called withcompute_stress=True, and nothing else: the stress, the periodic stress, the pressure, the cell gradient, the unit conversions and the switching margin are assembled from it byseccm_stress_from_strain_derivativeso that they are identical on every route;differentiate exactly the term set of its energy at fixed weights, with charges or density held at their converged values where the energy is variational in them, and
alphaheld fixed in Ewald sums;pass the fixed-topology finite-difference test (
seccm_strain_derivative_fdis the oracle and needs only the energy) and show a vanishing antisymmetric part.
Shared native helpers (namespace vibeqc::semiempirical::seccm::detail):
Helper |
Header |
Use |
|---|---|---|
|
|
deposit one record derivative |
|
|
the same for a radial pair term |
|
|
record blocks |
|
|
|
|
|
|
|
|
the 1-D Euler form for any degree -1 wire kernel |
|
|
Ewald-completed shell or atom gamma at fixed charges |
|
|
Madelung embedding with the own-image term, one to three dimensions |
Python side: vibeqc.semiempirical.seccm.cell works for any route through
the front door. optimize_seccm_cell and seccm_cell_derivatives use an
analytic strain derivative when the adapter accepts compute_stress and
fall back to fixed-topology central differences otherwise; they need the
adapter’s analytic gradient (compute_gradient).