MACE-CCM development plan

Status: planned, experimental research. Tracker: #732. Capability milestone: QC CCM production scaling and embedding (2.x track). No release date is assigned.

Scope and scientific contract

Implement MACE on a cyclic-cluster topology first, then consider QM/MACE embedding. Ordinary periodic MACE already exists in vibeqc.mlip.mace; its periodic neighbor graph is a control, not evidence of a new CCM construction. This route produces a learned potential energy, forces and eventually strain derivatives. It produces no wavefunction or electronic charge/spin solution. It is distinct from Gamma-CCM, chi-CCM and SECCM and remains experimental. Reuse the MACE interface, optional dependencies, checkpoint registry, license gates and output infrastructure.

The candidate energy is a sum of physical-site readouts on a precisely defined cyclic graph, E_C = sum_i epsilon_i(G_C; theta). This is a design starting point, not a proof that pretrained weights remain valid on modified graphs. M0 must define G_C, boundary multiplicities, readout normalization, and the chain rule from image coordinates to real atoms and cell strain. Multiplying pair edges by CCM weights, averaging messages and averaging full environment energies generally differ because the network is nonlinear. No choice is accepted without a derivation and small-graph controls.

The receptive field depends on the actual checkpoint cutoff and message-passing layers, not the cutoff alone. Paths can wind around a cyclic graph and couple defects indirectly even when direct self-image edges are absent. Establish the minimum admissible cluster and the regime of agreement with ordinary periodic MACE. Outside that regime, derive and validate a distinct construction or refuse it. If the research supports only periodic equivalence, document that limited outcome rather than claiming an isolated-defect method.

The first implementation targets neutral, fixed-cell 3D systems in a registered model’s domain. Skew cells and 1D/2D support require explicit graph and derivative qualification. Charged defects, explicit spin-state selection, long-range charge response, Hessians, NPT dynamics and QM embedding are not initial deliverables. Do not add point-charge Ewald or dispersion terms to pretrained energies without a new energy model and a double-counting analysis.

Work packages and dependencies

Stage

Issue

Depends on

Deliverable

M0

#733

none

Derive the cyclic MACE energy and boundary contract

M1

#734

M0

Implement image-resolved cyclic graph and energy evaluation

M2

#735

M1

Derive and verify conservative forces and cell derivatives

M3

#736

M1, M2

Expose experimental MACE-CCM through vq and recorded output

M4

#737

M3

Qualify cyclic MACE on bulk, defects and finite-size controls

M5

#738

M2, M3, M4

Integrate relaxation and scope later dynamics and QM embedding

M0: Derive the cyclic MACE energy and boundary contract

Define a separate experimental MACE-CCM construction, distinct from ordinary periodic MACE, Gamma-CCM, chi-CCM and SECCM. Derive a scalar energy and its graph semantics before implementing inference. Specify real atom identities, image shifts, Wigner-Seitz boundary ties, site-energy counting and normalization, and force accumulation from all virtual-image uses.

Explicitly compare averaging edge features, averaging messages and averaging complete environments/energies: nonlinear MACE updates and tensor products make these inequivalent. Derive the chosen many-body rule, including face/edge/vertex ties, or reject unsupported cells. Do not transplant pair-potential weights into a pretrained network without proof and numerical controls. Determine the checkpoint’s actual layer count and cutoff, propagation radius and paths which wrap around the torus. Removing direct self-image edges does not eliminate indirect defect-image coupling.

Acceptance: a derivation with equations, paper sections, departures and an executable small-graph oracle; invariance and energy extensivity arguments; a documented regime in which ordinary periodic MACE is an exact control; a justified minimum-size/receptive-field refusal. A finding that only the periodic-equivalent regime is justified is an acceptable research result and must narrow the feature rather than claim a novel CCM method. Freeze numeric tolerances and pilot systems before qualification.

Paper keys: MACE, ACE, CCM, HF, MM, LR.

M1: Implement image-resolved cyclic graph and energy evaluation

Reuse the existing optional MACE model registry and geometry infrastructure. Build an image-resolved graph with parent atom IDs, integer shifts, dimension mask, boundary multiplicity and the M0 weighting rule. Count each physical site energy once, including model atomic reference terms. Preserve distinct images where required; exclude or retain self images only according to the derivation, not a generic neighbor-list deduplication.

Start with neutral, fixed-cell 3D systems in the proven domain. Add skew cells and 1D/2D only with explicit graph tests; refuse unsupported geometry. Compare to a separately constructed expanded/halo graph reference and the upstream MACE calculator in the proven common regime, with identical checkpoint, dtype and device. Test permutation, translation, rotation, lattice rewrapping, exact boundary ties and just-off-boundary displacements, and several cluster sizes. Acceptance: energy agreement at a proposed float64 target of 1e-8 eV/atom (M0 must confirm), no silent graph fallback, and no new hard dependency.

Paper keys: MACE, ACE, CCM, MM.

M2: Derive and verify conservative forces and cell derivatives

Differentiate the same scalar energy as M1 through every image occurrence and the cell-dependent displacement vectors. Fold image forces to real atoms by the chain rule. State fixed-fractional versus fixed-Cartesian cell derivatives, stress sign, volume normalization and shear convention. Analyze Wigner-Seitz switching and tie continuity: a piecewise or discontinuous energy cannot silently claim smooth forces. Refuse derivative routes outside the proven smooth domain.

Acceptance: central finite differences at multiple steps with a convergence window, all Cartesian force components and all nine cell perturbations; net force/torque and strain symmetry checks; skew-cell and boundary-crossing adversarial cases. Proposed float64 tolerances: 1e-5 eV/angstrom force and 1e-4 eV for derivatives with respect to dimensionless strain, confirmed in M0. Compare same-model upstream derivatives only in the established equivalence regime. No low-dimensional volume-normalized stress until its normalization is explicitly defined.

Paper keys: MACE, MM, CELL.

M3: Expose experimental MACE-CCM through vq and recorded output

Add an explicit experimental route through vq, schema, dispatch and output without changing ordinary method=”mace” behavior or inventing an AICCM construction identity. Proposed naming/API must be settled in M0. Reuse lazy optional imports, checkpoint license gates and cache behavior. Reject charge/spin state claims, electronic properties, unsupported models and missing derivative capabilities rather than silently ignoring requests.

Record construction revision, topology/cell/dimension, graph convention and size restrictions, cutoff/layers, energy normalization and units, checkpoint hash, backend version/device/dtype, source/native identity and model domain. Route files and literature citations through vibeqc.output. Document supported energy/force/cell operations in the MACE manual, add a user-visible changelog fragment and classify any new tests using the suite-manifest generator. Acceptance: a complete vq job and output round-trip, tested refusals and unchanged ordinary MACE dispatch. No runtime implementation is claimed by the planning issue.

Paper keys: MACE, MP, OFF.

M4: Qualify cyclic MACE on bulk, defects and finite-size controls

Run complete calculations through vq on a small registered-checkpoint domain: a neutral covalent bulk crystal, a neutral vacancy with a size series, and a skew strained cell. Add a molecular crystal and 1D/2D systems only when model licensing/domain and route support allow. Include pristine/defect matched cells and independent graph controls. Separate implementation parity, cyclic finite-size error and model error; do not use an absolute MACE energy minus an ab-initio total as an accuracy metric.

Compare identical-checkpoint upstream MACE energies/forces/stress in the common regime; use explicit expanded-graph controls elsewhere. For scientific accuracy compare relative energies, relaxation observables and forces to vibe-qc plus CRYSTAL (bulk) or ORCA (appropriate molecular controls), with matched geometry, reference method, basis/ECP, charge/spin, approximations, units and convergence. Where pretrained training theory cannot be matched exactly, label the comparison a model-domain benchmark, not numerical equivalence. If an external reference is unavailable, record justified literature/numerical evidence and remaining uncertainty.

Acceptance: measured tables with source/native/checkpoint identity, frozen tolerances, graph and cluster-size convergence, wall-time and peak-memory scaling. Record indirect defect-image coupling; never claim isolated defects just because direct self images were removed. Model-accuracy thresholds are system-specific and frozen in M0. Failed cases remain experimental/refused. Reuse valid results; no extra source-review or release gate.

Paper keys: MACE, CCM, HF, MM, LR, EVAL, MP, OFF.

M5: Integrate relaxation and scope later dynamics and QM embedding

Use qualified forces for fixed-cell relaxation, then qualified strain derivatives for joint atom/cell relaxation with separate coordinate scaling/trust radii. Reuse #713 and #578 for shared optimizer/stress work rather than duplicating their ownership. Acceptance for relaxation: final independent energy/force/stress check and explicit unconverged status; preserve the #476 fail-closed behavior.

Later milestones only: NVE energy-drift tests with timestep refinement, then NVT/NPT through the shared NHC/MTK work in #713. Before QM/MACE embedding, derive the partition and boundary/capping treatment, subtractive energy and double-counting cancellation, conservative cross-boundary forces, and any electrostatic/polarization model. A short-range MACE model supplies neither charges nor a long-range Ewald Hamiltonian. The 2024 MM-CCM Ewald correction cannot simply be added to trained MACE energies. Record these as future research exits, not prerequisites for the initial fixed-cell route. Dedicated MIT MACE-CCM weights are a required program deliverable through W0-W2 below, reusing #712 infrastructure. They do not block initial M0-M4 runtime/control work.

Paper keys: MM, CELL, NHC, MTK, ONIOM, LR.

Dedicated open-weight MACE-CCM model

A dedicated model with MIT weights is a required deliverable of this program. It has its own cyclic reference target, dataset and checkpoint identity, with training and data infrastructure reused from #712’s planned separate training repository. Initial M0-M4 runtime/control work can proceed without waiting for these weights; completing that work alone does not complete the model track. No weights have been trained or released by this planning change.

All training labels are computed by vibe-qc through vq; ORCA/CRYSTAL provide independent validation only. The initial model trains from scratch. Release reproducible training recipes, split manifests, model cards and redistributable data with the weights. The dataset license is fixed separately in W0 after checking seed-structure rights. Keep training artifacts outside the product checkout, and fetch immutable weights through the existing runtime registry.

Stage

Issue

Depends on

Deliverable

W0

#739

#733

Specify the dedicated open-weight target and generate cyclic training data

W1

#740

W0, #734, #735

Train and refine a topology-consistent MACE-CCM model

W2

#741

W1, #736, #737

Qualify, publish and register MIT MACE-CCM weights

W0: Specify the dedicated open-weight target and generate cyclic training data

Develop a dedicated MACE-CCM model with MIT weights, reusing the data/provenance infrastructure planned in #712. This is a required deliverable of #732, not just optional reuse of a general periodic checkpoint. M0 (#733) must first define the cyclic graph and energy convention. Freeze initial elements, neutral 3D domain, cluster sizes, reference theory, compute budget and numerical acceptance targets before the label campaign.

Choose explicitly whether the model fits a named finite-CCM reference Hamiltonian or approximates a specified converged bulk surface on cyclic graphs. For the dedicated finite-CCM model, use one qualified vibe-qc CCM construction with a fixed method/basis/ECP, electrostatic convention, dispersion treatment and normalization. Never pool Gamma-CCM, chi-CCM, neutral fitted controls and ordinary periodic labels as interchangeable targets. Bulk labels may serve as separately tagged convergence controls; any multi-target training needs explicit conditioning and separate qualification. #712’s molecular r2SCAN-D4 decision does not establish a qualified periodic CCM reference.

Test identifiability: can two cluster/reference states have the same model input but different energies or forces because of long-range physics? If so, limit the target/domain or derive explicit size/topology or physical long-range features. More training data alone cannot repair missing information. Keep charge/spin and electrostatic extensions outside the pilot unless a suitable Hamiltonian and architecture are derived.

Generate every training label in vibe-qc through vq. Require converged energies and forces; add strain labels only from a qualified route (#578/#637 where applicable). Use finite differences of the same scalar energy when analytic derivatives are unavailable, and budget their cost. ORCA/CRYSTAL are independent validation sources only, never training labels. Reject unconverged or derivative-inconsistent frames. Record source/native identity, complete reference settings, topology/size, geometry, atomic reference energies, units and hashes per frame.

Cover pristine/strained/rattled cells, neutral defects, cluster-size series, boundary/tie perturbations and supported chemistry. Seed structures must be redistributable. Group related geometries, symmetry copies, parent crystals, trajectories and defect/size families before splitting; freeze independent chemistry/size holdouts to prevent leakage. Reuse #712 tooling and its separate training repository, with a distinct CCM dataset namespace.

Acceptance: a versioned target/model card and dataset schema, frozen error thresholds and dataset splits, a budgeted pilot manifest with measured label quality and sampled reference/FD checks. No arbitrary frame count substitutes for domain coverage. Freeze a compatible dataset redistribution license separately from the MIT weight license.

Paper keys: MACE, CCM, HF, MM, LR.

W1: Train and refine a topology-consistent MACE-CCM model

Train a dedicated MACE-CCM checkpoint against W0 labels using exactly the M0/M1 cyclic graph, boundary weighting, physical-site counting and energy convention used at inference. Reuse #712’s planned training repository and infrastructure outside python/vibeqc/ and cpp/. Start from random initialization with own-data-only labels so upstream weight/data restrictions do not enter the initial release; do not fine-tune academic-only weights into a purported MIT model.

Train energy and force losses from one scalar energy; enable strain/stress loss only for qualified labels with the recorded derivative convention. Freeze loss normalization/units, atomic energy offsets, architecture/cutoff/layer count, optimizer, seeds, data hashes and code versions. Encode the graph/target revision in checkpoint metadata and reject incompatible runtime topology. Audit whether weights learned for one cluster size transfer to the admitted size range; do not promise general isolated-defect behavior from small-cell fitting.

Compare matched-budget ordinary-periodic and cyclic-graph models, scratch training and any later independently licensed initialization, and cluster-size/cutoff/layer ablations. Use committee disagreement and coverage diagnostics for candidate selection, then run new vq labels; disagreement is not a calibrated error bound. Never select on the frozen final test set. Recheck boundary continuity and conservative forces after training.

Acceptance: reproducible pilot training from a frozen manifest, independent seeds and learning curves, held-out errors by chemistry/defect/size/boundary stratum, a recorded stopping rule and cost, and checkpoint/graph compatibility tests. Publish only domain-supported claims. A model that misses W0’s preregistered accuracy/coverage targets stays experimental; success is not guaranteed by using MACE.

Paper keys: MACE, ACE, EVAL, MP, OFF.

W2: Qualify, publish and register MIT MACE-CCM weights

Qualify the dedicated checkpoint through the MACE-CCM vq route, separately from existing-checkpoint graph controls in M4. Evaluate frozen holdouts by chemistry, defect type and unseen cluster size, relative and defect-formation energies with consistent chemical potentials, force errors, relaxation outcomes and qualified strain derivatives. Include boundary-crossing cases, finite-size trends and out-of-domain refusals. Compare against W0’s exact reference convention; use ORCA/CRYSTAL controls where scientifically matched, recording any unavailable reference and remaining uncertainty.

Require W0’s frozen error/coverage criteria, the M1/M2 implementation and FD tolerances, and complete provenance. NVE drift/timestep checks follow when dynamics is exposed; NPT and QM embedding remain later capabilities. Report learning error, reference error and CCM finite-size effects separately. Benchmark the dedicated model against registered upstream models and an ordinary-periodic training baseline within their domains, without mixing absolute reference scales.

Release weights under MIT at an immutable versioned public location with a SHA-256, architecture and graph/target schema, supported elements/topologies/cluster-size range, training-data and source hashes, recipe/configs/seeds, model card, known limitations and validation report. Release the redistributable dataset and split manifests under the license fixed in W0; verify rights to both structures and any initialization. Training and data artifacts stay outside the product checkout; the runtime fetches weights on demand.

Register a distinct model key and explicit MACE-CCM compatibility metadata. Add checkpoint/hash and topology-mismatch refusals, loader/serialization parity tests, lazy dependency behavior, model citations via vibeqc.output, the affected user manual, docs/license.md and a changelog fragment. Do not silently replace the ordinary MACE default. A future paper describes the cyclic construction, dataset, model and limitations; its publication is not a separate source-landing gate.

Acceptance: reproducible vq benchmark evidence, open downloadable MIT checkpoint and reproducibility assets, verified hash and loader parity, documented model domain, and an explicitly experimental registry entry. Model publication follows existing maintainer release authorization; this issue authorizes planning, not a release today.

Paper keys: MACE, EVAL, MP, OFF, HF, MM, LR.

Validation and delivery rules

M0 freezes benchmark systems, model/domain choices, tolerances, cost budget and supported topology before qualification. The numeric targets in M1/M2 are proposed implementation tolerances, not measured results or model-accuracy claims. Use deterministic float64 controls first, then quantify device/dtype differences. Keep energy normalization, atomic reference offsets and composition explicit. Use same-composition relative energies, or a consistently specified chemical potential reference for defect formation energies.

Dev owns focused checks and source landing. Validator runs the complete vq calculations, records the actual source/native/model identities and reference settings, and reports numerical acceptance. This planning change needs only text/link checks. No chemistry calculation, runtime feature or scientific PASS is claimed here. Full CI remains a release-candidate responsibility.

Related issues retain their scope and owners: #712 supplies shared owned-MLIP training infrastructure; W0-W2 define the dedicated CCM model campaign. #713 covers shared MM-CCM optimization and dynamics; #578 covers periodic stress; #476 supplies the existing unconverged-relaxation behavior. General-model training and the first MACE-CCM runtime controls need not wait for each other.

Literature and reading map

The local literature library contains the papers below. Initial planning read MACE Sections 2/4 and the receptive-field discussion, the 2001 CCM boundary construction, the 2014 HF-CCM Theory section, and the 2024 MM-CCM Sections 2.2/2.3 and Ewald scope; #713 provides the existing optimization/dynamics assessment. The remaining entries are task-specific required reading, including available supporting information, rather than a claim of completed review. M0 records the selected equations and material departures. M4 reads the model benchmark SI before adopting structures or reference values. Missing papers/SI must be requested through the library’s documented intake.

The 2024 MM-CCM formulas concern classical bonded/pair and point-charge terms; the cell derivation there assumes orthorhombic cells. They do not establish many-body neural-message weighting, general-cell MACE derivatives, or the absence of long-range defect-image interactions. HF multi-center integral weights likewise motivate the derivation but cannot be copied into learned features without analysis. ONIOM, NHC and MTK are extension references only.