vibe-qcDocumentation

MACE-CCM theoretical framework

MACE-CCM is the learned-potential member of the CCM family. The common object is a finite translation group with physical atom identities and virtual images. The energy law distinguishes SECCM, Gamma/chi AICCM and MACE-CCM. Sharing that geometry does not identify their Hamiltonians, boundary weights or accuracy. This framework extends the implemented definition and the development programme, under #732 and #733. All routes remain experimental. This follow-up does not change the SECCM paper or its 0.18.x submission scope.

1. State space and image algebra

Use row vectors. Let A be a nonsingular input lattice, x_i the Cartesian positions, and z_i the species, i=1,…,m. For positive integers n_a define D=diag(n_1,n_2,n_3), H=DA, G=Z^3/(Z^3 D), and N=|G|. Choose representatives r_g in Z^3 with r_g mod n=g. A node is (i,g), with parent i, species z_i, and position X_ig=x_i+r_g A. The present API restricts the state to these repeated copies; it does not allow independent replica displacements. A decorated cyclic cluster could instead have independent X_ig and species, but would be a different input contract.

Each directed image edge has a source, a target and an integer shift s. For a primitive-cell neighbor (i,j,s), set

h = (g+s) mod n
q = (r_g+s-r_h) D^-1             (an integer row vector)
d_ig,jh,q = X_jh-X_ig+qH = x_j-x_i+sA.

Keep the entire image multiset within the network cutoff, including distinct shifts with the same endpoint indices and nonzero-shift self images. Exclude only i=j,s=0. Thus N=1 is a periodic cell with winding edges. An isolated molecule has PBC disabled and only zero-shift edges; it is a different limit. The finite labels cannot replace the winding integers, which record geometry lost when taking the quotient. This is a graph covering construction, not a nearest-image approximation.

A representative change r_g -> r_g+k_g D gives q -> q+k_g-k_h, so every d is unchanged. Rewrapping x_i -> x_i+t_i A requires s -> s+t_i-t_j. These are changes of coordinates, not new physical states. For a unimodular basis change A’=UA, image labels transform as s’=s U^-1. Comparing the same superlattice also requires transforming its integer generators; reusing the same diagonal D after a basis change need not describe the same sublattice. On the repeated-state subspace, the equivalence below makes per-cell energy independent of that choice anyway.

2. Many-body energy and equivalence theorem

Write the local MACE operations schematically as

h_v^0 = embedding(z_v)
a_v^t = sum_(e outgoing from v) Phi_t(d_e,h_target(e)^t,z_v,z_target(e))
b_v^(t,nu) = C_(t,nu) [a_v^t tensor ... tensor a_v^t]
h_v^(t+1) = U_t(h_v^t,{b_v^(t,nu)})
E_G = sum_v e_theta(v);             E_cell = E_G/N.

Here Phi includes radial functions, spherical harmonics, feature mixing and the checkpoint’s normalization; C denotes equivariant contractions. This is notation for the published MACE operations, not a replacement network. Every atomic offset, scale, shift and layer readout belongs in e_theta. Dividing only the interaction energy, or dividing a second time by m, gives the wrong energy.

Construction A theorem. Suppose the graph contains all upstream periodic image edges, with unit weights and identical displacements; species and initial features are repeated; the network has shared local parameters and additive site readout. Then E_G=N E_periodic for any finite layer count.

Proof: h_ig^0=h_i^0. If equality holds at layer t, the incoming message multiset at (i,g) equals that at i, including multiplicities and vectors. Pooling, contractions, residuals and updates give h_ig^(t+1)=h_i^(t+1). Induction gives identical site energies, and summing over G gives the result. Floating-point reduction order can introduce numerical differences. Global attention, graph normalization, charge equilibration or nonlocal additions require a new proof; the theorem does not authorize arbitrary MACE-family checkpoints.

No lower bound on N is needed for A: winding paths retain all periodic images. With L layers of cutoff R, a site’s receptive radius is bounded by LR. An open halo oracle must preserve all paths to that depth. Repeated-cell replication is an algebraic check, not a finite-size convergence study. For a localized perturbation, a shortest supercell translation greater than 2LR is a sufficient local-network condition to separate perturbation influence regions, provided the compared environments otherwise match. It does not establish convergence of electrostatics, elastic relaxation or the electronic reference energy.

A reproduces the same pretrained periodic model and its limitations. Its CCM contribution is the finite-group representation and derivative/output contract; it is not a new physical approximation or an isolated-defect model.

3. Ownership and a genuinely modified construction B

Wigner-Seitz ownership in a finite CCM Hamiltonian partitions interactions of physical sites among images. In A, different physical image neighbors each contribute with weight one, including face, edge and vertex ties. Equal distance is not evidence that two edges are duplicate neighbors.

To define B, specify a joint ownership tensor for every correlation order:

b_v^(t,nu) = sum_(e1,...,enu) W_v^(nu)(e1,...,enu)
            C_(t,nu)[Phi_t(e1) tensor ... tensor Phi_t(enu)].

This is an explicit family of modified message constructions. W must respect permutation, Euclidean covariance, image relabelling and physical-site counting. Its derivation must refer to a named target energy. MACE includes repeated neighbor indices in these products; forbidding them changes the architecture.

Weighting the pooled density by w_e implies the specific factorization W^(nu)(e1,…,enu)=product_k w_ek. That is a modelling assumption, not a general CCM ownership identity. For example, if two images a,b are alternative complete environments with equal probability, the quadratic density average is (a tensor a+b tensor b)/2. Squaring the average density instead gives (a tensor a+a tensor b+b tensor a+b tensor b)/4. Mixed tuples appear and the repeated-image terms change weight. A pairwise rule therefore cannot be silently transplanted from MSINDO, DFTB or MM-CCM into MACE tensor products.

An alternative precisely defined family averages complete scalar energies: E_B(X,H)=sum_alpha p_alpha(X,H) E_theta(Graph_alpha(X,H)), where the nonnegative p_alpha sum to one. Each alpha specifies a complete consistent image assignment through all layers. Its joint moments need not factorize. Averaging independent layer messages does not implement this energy ensemble. This is a candidate family, not a selected or implemented physical model. Selecting it would still require a Hamiltonian-based reason for the assignments and probabilities.

Hard nearest-image selection can switch directional many-body features at a boundary even when competing distances agree. Averaging only exactly at the tie does not prove continuity of either one-sided limit or derivatives. Geometry-dependent weights must be differentiated: the ensemble force contains both -sum p_alpha grad(E_alpha) and -sum E_alpha grad(p_alpha). A smooth, invariant partition may define conservative forces, but changes the model and must satisfy extensivity and boundary limits before training. Smoothness cannot be inferred from symmetry alone. No weighted B dispatch is authorized by A’s validation. Pretrained weights have no established applicability to B; plan training against that exact topology and target unless independent evidence establishes a narrower transfer domain.

3a. Construction B as the Wigner-Seitz cyclic cluster: decision

The CCM transcription of a finite-range message-passing potential is the minimum-image rule of SECCM. Let T be the periodic part of the cluster superlattice (the rows of DA along the periodic directions) and L_min the length of its shortest nonzero vector. For two lifted nodes u=(i,g) and v=(j,h) the candidate displacements are d_uv(t)=X_v-X_u+t, t in T.

Definition B. Keep, for every ordered pair u != v, only the nearest image t* minimizing |d_uv(t)|, with Wigner-Seitz weight 1/m when m images tie, and make it an edge iff |d_uv(t*)| < r_cut. A node has no image of itself (t*=0 gives d=0). Message passing then runs unchanged on this graph.

Construction A keeps, for the same pair, every t in T with |d_uv(t)| < r_cut (these are the lifted copies of all primitive shifts s with h=(g+s) mod n), and self-image edges (u=v, t != 0) within the cutoff. So A_uv contains B_uv.

Proposition. If L_min >= 2 r_cut, then for every pair at most one image lies inside the cutoff, no node has a self image inside it, and no inside edge is a tie: A and B are the same graph with unit weights, so E_B = E_A = N E_per exactly, for any number of layers.

Proof: two distinct images t1 != t2 both inside the cutoff would give |t1-t2| = |d_uv(t1)-d_uv(t2)| < 2 r_cut <= L_min, but t1-t2 is a nonzero vector of T. A self image needs |t| < r_cut < L_min. A tie between two images at distance r needs 2r >= |t1-t2| >= L_min, so r >= r_cut and neither is an edge. Equivalently, the cutoff sphere fits inside the Wigner-Seitz cell of T, whose inradius is L_min/2. Identical graphs give identical messages at every layer (Section 2), so the receptive radius L r_cut plays no role: information that travels around the torus does so in the crystal too.

Otherwise some pair has two images inside the cutoff, or an atom sees itself. B then drops edges the periodic graph contains: an atom’s pooled features lose physical neighbours. The result is the energy of a different, truncated graph that is not the environment of any crystal at that geometry. A 1/m tie weight does not repair it (the weighted-pooling counterexample of Section 3). The B error is not a monotone finite-size error either. Measured on the registered MPA-0 checkpoint, energy per atom of B minus periodic MACE, with ties resolved by keeping one image (scratch experiment evaluating the nearest-image subgraph through the same network; A itself agrees with periodic MACE to 2e-14 eV/atom in every row):

structure

replicas

L_min/(2 r_cut)

edges A

edges B

E_B-E_per (eV/atom)

max force error (eV/angstrom)

carbon chain, 2.6 angstrom

(1,1,1)

0.217

16

2

2.9016

0.736

(2,1,1)

0.433

32

12

0.1112

1.510

(3,1,1)

0.650

48

30

-0.0044

0.805

(4,1,1)

0.867

64

56

-0.0064

0.271

(5,1,1)

1.083

80

80

0

0

diamond, a=3.567 angstrom, primitive

(2,2,2)

0.420

2528

240

0.0029

0.060

(3,3,3)

0.631

8532

2862

0.0580

0.050

(4,4,4)

0.841

20224

15360

-0.0016

0.009

MgO, a=4.21 angstrom, primitive

(2,2,2)

0.496

1472

240

-0.1239

0.632

(3,3,3)

0.744

4968

2808

-0.0116

0.008

(4,4,4)

0.992

11776

11008

below 5e-5

below 5e-4

The diamond rows are not monotone ((3,3,3) is worse than (2,2,2)); MgO at 0.992 already agrees because the edges still missing lie at the very end of the cutoff, where the radial envelope vanishes.

Conclusion. For a strictly local network, B adds nothing but an error for small clusters and is identical to A for large ones. The physics a CCM captures for an electronic Hamiltonian (long-range electrostatics, orbital delocalization across the boundary) has no counterpart in a cutoff network, whose periodic energy already is the model’s infinite-crystal energy. B is therefore not implemented. Instead every MACE-CCM run records, under nearest_image_regime: the shortest cluster translation L_min, the ratio L_min/(2 r_cut) (at least 1 is the geometric sufficient condition), the measured number of lifted node pairs with more than one edge, the excess edges and the self-image edges (all zero means B would be the same graph as A for this geometry), and the receptive-field ratio L r_cut/L_min. The last number matters only for a perturbation confined to one replica (a defect in an independently displaced replica, which the current API does not support): below 1/2 such a perturbation cannot reach its own images.

3b. One and two periodic dimensions

For a wire or slab the translation group has dimensionality d=1 or 2: replicas (n,1,1) or (n1,n2,1), and no image shift along a non-periodic axis. The proof of Section 2 holds verbatim, since it never uses d. The adapter evaluates the structure in the canonical frame of the ordinary route (periodic vectors on the leading Cartesian axes, vacuum coordinates non-negative), so both supported mace-torch releases build the correct neighbour list, and rotates the results back: F = F’ R and dE/d epsilon = R^T (dE/d epsilon’) R for backend coordinates x’ = R x.

Only strains inside the periodic span deform the cell. With P the projector onto the span of the periodic lattice vectors and m the input-cell length (d=1) or area (d=2), the reported periodic stress is P sym(D) P / m, D the strain derivative of Section 4: the line tension times the axis dyad (Hartree/bohr) for a wire and the in-plane stress (Hartree/bohr^2, force per length; a surface stress follows only after subtracting the strained bulk contribution) for a slab. For d=3 it is the stress itself. Tensile is positive throughout. A slab in a 3-D box whose vacuum exceeds r_cut is the same graph, so the in-plane block of its 3-D stress times the box volume equals the d=2 periodic stress times the area; the tests use this identity.

4. Conservative coordinate and cell response

On the repeated-state subspace, differentiating the normalized scalar gives

F_i = -(1/N) sum_g partial E_G / partial X_ig.

For an independent decorated cluster, physical forces would instead be -partial E_G/partial X_ig. Differentiating a per-cell energy with respect to independent atoms and forgetting N would reduce those forces incorrectly. This distinction prevents reusing the current tied-coordinate API for defects on independent replicas without a new energy/derivative contract.

For A define g=dE_cell/dx and C=dE_cell/dA at fixed Cartesian x. Both replica positions r_g A and periodic shifts qDA remain in the differentiation graph. Under affine strain x’=x(I+epsilon).T and A’=A(I+epsilon).T,

D_epsilon = g.T x + C.T A
f = x A^-1
C_fractional = C + f.T g
D_epsilon = C_fractional.T A
sigma = sym(D_epsilon)/abs(det(A)).

The stress is tensile positive; pressure is -tr(sigma)/3. For symmetric shear with epsilon_xy=epsilon_yx=t, dE/dt=2 V sigma_xy. Engineering shear gamma=2t instead gives dE/dgamma=V sigma_xy. The code exposes column-lattice gradients, so its cell-gradient arrays are the transposes of the C matrices above. Translation invariance implies sum_i F_i=0. Joint atom/cell rotation implies symmetry of D_epsilon; atom torque alone need not vanish in a periodic cell.

These identities also hold for B only when all geometric weights are included in the scalar’s derivative. Discrete neighbor lists are held fixed for local finite differences. Boundary crossings require separate continuity checks; cutoff smoothness is inherited from the chosen network, not proved by CCM. Higher derivatives and dynamics require their own qualification.

5. A dedicated CCM surrogate and the production decision

A dedicated model needs a target scalar E_ref(X,H; eta), where eta fixes the reference method, basis/ECP, finite group, electrostatics, dispersion, charge, spin and normalization. Gamma-CCM, chi-CCM and SECCM are different possible label sources, not interchangeable labels. A finite-CCM surrogate may use the same A graph but different trained parameters; it need not introduce arbitrary ownership weights to belong to the CCM family. Conversely, changing graph weights alone does not make a network reproduce any CCM electronic Hamiltonian.

Before training, test identifiability: if two admitted reference states have the same multiset of rooted L-layer environments but different E_ref beyond an atomic offset, an additive local network cannot reproduce both. More data cannot fix this missing information. Restrict the target domain or derive explicit size/topology or long-range inputs, with a new derivative and extensivity contract. A size label alone is not a long-range physical model. Do not add Coulomb or dispersion energy to pretrained predictions without establishing how their fitted contributions are removed or refitted. The opt-in D3(BJ) add-on of the user guide satisfies this for models whose training energies contain no dispersion (MACE-MP-0, MACE-MPA-0: PBE/PBE+U): nothing fitted is removed, and the term is the published PBE-D3(BJ) recipe.

Production qualification must keep three errors separate: graph/derivative implementation error, learned-potential error against a specified reference, and reference/finite-CCM approximation error against the physical target. Equality to upstream MACE constrains only the first. The existing qualification report and independent reference assessment remain applicable; this theory document upgrades neither scientific acceptance nor the supported runtime domain.

The next bounded decisions are: retain A as the periodic-equivalent route; resolve reference derivative consistency before accepting full-vector accuracy; freeze the dedicated CCM target and identifiability experiment in #739; derive and validate any selected B ownership in #733 before implementing it; and use #740/#741 for separately authorized training and model qualification. No training or release campaign is begun by this framework. A production claim requires passing evidence for the exact advertised domain and model, not only a completed derivation.

Sources and implementation correspondence

The graph-cover proof, ownership counterexample and state-space distinctions above are deductions in this framework. They are not claims of a new published MACE architecture. The primary sources were read from the scientific library:

  • Batatia et al., MACE (2022), Sections 2 and 4, Eqs. (2)-(4), (7)-(13): message pooling, repeated indices, tensor products and site readouts. Paper.

  • Samaniego-Rojas et al., A molecular mechanics implementation of the cyclic cluster model (2024), Sections 2.2-2.3, Eqs. (5)-(8): geometric interaction regions and image averaging in its specified MM energy. DOI.

  • The definition note records the geometric cell derivative source and the earlier CCM/HF comparison. Their electronic terms are not imported into the learned energy.

The implementation maps image algebra to lift_periodic_graph, scalar energy and tied derivatives to ExperimentalMACECCMEvaluator.run, both in python/vibeqc/mlip/mace_ccm.py. Upstream MACE 0.3.16 blocks and models provide the network; no replacement contractions are introduced here.