vibe-qcDocumentation

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, and

  • the cyclic translations T_i themselves, 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:

  1. 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|^2 from the face value 1/2 (v runs over the first-shell lattice vectors). A strain eps changes a score to first order by at most 2 |eps| (|d|/|v| + 1/2), so the minimum margin bounds the admissible strain. SECCMTopology.switching_margin_excluding_ties is that minimum and every stress result carries it. The exact test for a finite strain is rebuild_for_cell(..., check=True), which raises SECCMTopologyChangedError, or a comparison of the fingerprint of a freshly built topology.

  2. 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 interaction f. 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.

  3. 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 gives 1/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 is 1/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 eps against 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 = -Phi to 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_virial in three (2e-16);

  • total: analytic W against 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^T under 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 same W to 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 with L: alpha = 4/L, fixed image and channel counts), so the Euler form of “One dimension” above applies with g = dPhi/dv from _wire_kernel_value_gradient (twin of detail::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:

  1. 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 as strain_derivative, computed when the adapter is called with compute_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 by seccm_stress_from_strain_derivative so that they are identical on every route;

  2. 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 alpha held fixed in Ewald sums;

  3. pass the fixed-topology finite-difference test (seccm_strain_derivative_fd is the oracle and needs only the energy) and show a vanishing antisymmetric part.

Shared native helpers (namespace vibeqc::semiempirical::seccm::detail):

Helper

Header

Use

RecordDerivativeAccumulator{gradient, strain}.add(central, origin, d, f)

seccm_strain.h

deposit one record derivative f = dE/dd into the gradient and the strain derivative

deposit_radial_record(acc, central, origin, d, c u'(r))

seccm_strain.h

the same for a radial pair term

weighted_record_matrix_set(topology, ao_atom, M)

seccm_strain.h

record blocks -w M for the overlap contractions

overlap_record_strain_contribution(basis, W_set)

seccm_overlap_strain.h

-sum W(g) : (dS/dd)_a d_b, the strain twin of overlap_lattice_gradient_contribution

EwaldStrainKernel(translations, alpha).strain(v, exclude_self)

seccm_strain.h

dPhi/d eps in one, two and three dimensions

wire_potential_strain(Phi, dPhi/dv, v, T)

seccm_strain.h

the 1-D Euler form for any degree -1 wire kernel

ewald_gamma_strain_derivative(sites, positions, spec, kernel, records, dq)

seccm_strain.h

Ewald-completed shell or atom gamma at fixed charges

seccm_madelung_strain_derivative(topology, charges)

ewald_1d.h

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).