vibe-qcDocumentation

Extended-system and nanoconfinement acceptance¶

Production use of periodic semiempirical methods and MACE requires more than small-molecule convergence. The target applications include large clusters, wires, surfaces, bulk solids, defect chemistry, adsorption, and molecules moving through or confined inside pores. This protocol defines that broader acceptance work. It does not reopen accepted paper-release checks or make the entire accuracy roadmap a prerequisite of an already frozen release.

Systems and reference hierarchy¶

Class	Small decisive case	Required comparison and remaining work
1D	Empty zigzag (10,0) and armchair (5,5) carbon nanotubes	Period, bond lengths, curvature energy relative to graphene, axial force/strain response; matched CRYSTAL DFT and external semiempirical calculations; converge axial sampling or supercell length
2D	Graphene and an ionic oxide surface	Energy/forces under in-plane wrapping; vacuum independence for true 2D routes; slab-thickness and lateral-size convergence
3D	Diamond plus an ionic solid	Equation of state, forces, all strain derivatives and state stability; retain the existing MgO and SECCM instability evidence
Surface adsorption	Clean surface, isolated molecule and combined system	Frozen interaction energy first; separately relaxed adsorption energy only after force convergence and consistent state/geometry accounting
Surface defect	The same surface with a specified vacancy or dopant, both empty and adsorbed	Defect reconstruction, charge/spin alternatives, defect formation convention and adsorption-energy difference; a pristine/defective pair alone is not a formation energy
Nanotube confinement	Water inside/outside a (10,0) tube; empty tube and isolated water	Exact reference geometries, interaction energies, radial/axial forces and matched fragment cells; extend to methane and another guest only after the first case is understood
Molecular passage/trapping	Fixed-host axial/radial profiles, then a relaxed path and finite channel with defined ends	Periodic image continuity, same-state force checks, entry/exit and escape barriers; trapping requires a characterized minimum and escape path
Other confinement	Water between two graphene sheets	Width-dependent binding and forces with both host surfaces present; expand to another pore chemistry after a matched reference is available

The independently generated starting sites are in 40_extended_systems.py. They cover 1D nanotubes, 2D graphene and slits, 3D diamond, single vacancies, and water/methane guests. They are not the optimized structures of the papers below. The existing 39_corundum_adsorption.py provides the bare/hydroxylated methanol and phenol cases. Oxide vacancy reconstruction and its spin/charge validation remain additional work.

# Prepare a 1D tube with a confined molecule, without running a calculation.
python examples/semiempirical/40_extended_systems.py \
  --system cnt --chirality 10 0 --guest water --output /path/to/cnt

# Evaluate an unreconstructed 2D vacancy with an adsorbate.
python examples/semiempirical/40_extended_systems.py \
  --system graphene --vacancy --guest water --evaluate --method mace \
  --output /path/to/vacancy-water

# Move only the guest by one tube cell; the defect and host stay fixed.
python examples/semiempirical/40_extended_systems.py \
  --system cnt --vacancy --guest water --phase 1 \
  --output /path/to/cnt-next-image

--repeat grows only periodic directions. The guest count and the number of vacancies stay fixed, so concentration changes with size. --component host and --component guest retain the combined geometry’s coordinates; the guest is isolated. A paper using periodic fragment energies must instead preserve its fragment cell and boundary prescription explicitly. --radial-offset sets the guest anchor’s displacement from the tube axis in Angstrom. No automatic optimization, SCF retry sweep or reference campaign is started. Evaluation uses the public molecular/periodic runners; seccm is the experimental MSINDO cyclic route. Method availability is not acceptance. Use --evaluate --forces to write an additional force summary in <component>-summary.json; the periodic GFN2 and DFTB0 analytic kernels reuse the converged result. SCC-DFTB forces require 6N displaced SCFs, so forces are explicitly requested rather than silently included in an energy timing. site.json records the generated geometry’s status. Prepared extended XYZ files and the job’s standard output/manifest/QVF files retain distinct names. For MACE, tilted wires and unwrapped trajectories also require the partial-PBC backend fix.

Literature and data¶

Use these primary sources and their supporting information. Archived calculation outputs can replace new reference calculations when their inputs, units, functional, numerical controls and identities are authenticated.

Demichelis et al., J. Phys. Chem. C 115, 8876 (2011), doi:10.1021/jp110704x, computational methods and nanotube structural/curvature results. CRYSTAL calculations cover armchair and zigzag families and explicitly address basis and Brillouin-zone convergence. The paper and SI are in the literature library.
Brandenburg et al., J. Chem. Phys. 151, 164702 (2019), WaC18, doi:10.1063/1.5121370, Sec. II, Eqs. (1)-(2), Tables I and III, and SI. It supplies frozen-geometry water interactions with graphene, carbon nanotubes and aromatic molecules, plus 2D/3D ice. Preserve its inside/outside geometries and reference uncertainties; do not compare a newly generated tube directly to its tabulated energies. The original geometry supplement is now available in the library, with unchanged geometry/reference members and bundled POTCAR data excluded. Its pbe.dat retains earlier CNT reference values (-80/-244 meV), whereas published Table I gives -85 +/-18 and -287 +/-16 meV. The supplied common unbound-water structure also differs internally from the internal-CNT water. Pin the target revision and explicitly construct frozen fragments under Eq. (1); retain the supplied unbound geometry as a separate control.
Abidin and Hamada, Phys. Rev. B 105, 075416 (2022), doi:10.1103/PhysRevB.105.075416, Sec. II and adsorption results. The CC BY 4.0 dataset contains Quantum ESPRESSO inputs/outputs for pristine and N-doped graphene, fragments, and a graphene subset of WaC18. Its 80/800 Ry cutoffs, 0.02 Ry Marzari-Vanderbilt smearing, effective-screening-medium boundary and spin-polarized doped cases must remain explicit. It is not the complete WaC18 nanotube/ice geometry archive. Its WaC18/vdW-DF2-B86R/0leg combined geometry duplicates 1leg, while water-0leg has different internal geometry. The corresponding inputs and executed outputs agree individually, but this triple is not a frozen-fragment comparison. Retain the archive unchanged and exclude that triple until its provenance is resolved; the 1leg and 2leg fragment geometries match.
Li et al., R. Soc. Open Sci. 6, 190727 (2019), doi:10.1098/rsos.190727, Sec. 2 and SI. It compares water, methane and ammonia on defective nanotubes using DFTB+ with Slater-Kirkwood dispersion, with PBE0-D3/6-31G(d,p) checks on capped structures. Our in-house DFTB parameters or D4 are different models, not an implementation-parity replacement. Recover the actual parameter set, cap/defect coordinates and charge/spin before adopting numerical targets. SI Tables S8-S24 contain 17 coordinate sets. Table S24 is labelled water but lists C260 O2 H; preserve and flag those element labels rather than silently replacing them. The other coordinates still need their method, units and fragment conventions authenticated before reference acceptance.
Hummer, Rasaiah and Noworyta, Nature 414, 188 (2001), doi:10.1038/35102535, and their accessible 2002 conference account. The latter describes a finite 144-carbon channel and a surrounding TIP3P water bath. This motivates transport observables; its classical force field is not a quantum energy reference. Reproducing a transport rate needs the bath, end treatment, thermostat, loading, observation time and statistics.

Keep acquired papers, source archives and operational calculations in the literature library or external evidence store. The product example constructs its own geometry and does not redistribute those archives.

Numerical and physical gates¶

Pin geometry/cell/PBC, method and parameter/checkpoint identity, charge/spin, electronic temperature, cutoffs, k sampling, tolerances, source and native runtime. Distinguish same-Hamiltonian implementation parity from agreement between different approximate methods. MACE provides no electronic state or spin-selection evidence.
Require a converged stationary result and an appropriate state audit. Retain alternative densities, occupations, residuals and stability flags. Use same-branch finite differences; do not smooth state switches or drop unstable points. Retain #184 conventions and all existing failing controls.
Check two-step nuclear derivatives, force balance, cell-image covariance and periodic endpoint continuity. Check strain/stress only where supported; an arbitrary vacuum volume does not define physical slab/wire stress.
Compare frozen interaction energies and structural/force observables on authenticated literature geometries. Agree accuracy bounds in advance and report signed errors, reference uncertainty and worst cases. A prospective 50 meV screen on archived graphene interaction energies is a first diagnostic, not a universal adsorption-accuracy requirement or a production certificate.
For paths, keep host atoms, atom order, defect position and electronic branch fixed unless relaxation is explicitly part of the protocol. For transport, add converged dynamics/free-energy sampling, timestep/energy-drift checks, independent trajectories and uncertainty estimates. A periodic five-point potential scan is neither observed molecular travel nor an escape rate.

Initial measured scope¶

The first execution packet covers ten MACE-MPA-0 sites: diamond, graphene, graphene with water, a graphene vacancy with/without water, a nanotube with/without water, a nanotube vacancy with/without water, and water in a graphene slit. These are 8-83 atom starting structures. Energies and forces are finite, one nanotube force component passes two-step differentiation, and translating its guest by one cell preserves the result. The five-point axial profile is a fixed-host potential probe, not a transport measurement.

The 83-atom nanotube/water Gamma GFN2 calculation converges in 21 iterations under explicit 0.001 Ha electronic temperature, 1e-8 charge tolerance, 0.05 charge mixing, a 200-iteration cap, no automatic stabilization, a 15-bohr electronic cutoff and coupled D4. Its oxygen axial force errors at 0.001/0.0005 bohr are 7.04e-8/1.73e-8 Ha/bohr. Charge, density and occupation changes remain small across those displacements. This supports a local numerical branch, not a global ground state or an accuracy claim. One energy and full analytic gradient took about 8.4 seconds and 392 MiB peak RSS on the measured two-thread CPU runtime; this is a measured small case, not a largest-system result. The same controls also converge at 163 and 323 atoms in 19 iterations each. Energy plus analytic forces take about 63 and 251 seconds, with peak RSS of 796 and 2020 MiB respectively. The 323-atom point is the largest completed execution probe in this two-thread ladder. The next doubling is projected to exceed the declared ten-minute/4-GiB budget and was not submitted. This projection is not a measured method ceiling; large-size finite differences, state stability and physical reference acceptance remain outstanding. Each repeat has one guest, so adsorption coverage changes with size and these timings do not establish convergence at fixed coverage.

On authenticated archived 1leg/2leg geometries, MACE-MPA-0 frozen water interaction energies are about -0.31549/-0.39369 eV, versus -0.10999/-0.11393 eV for the archived rev-vdW-DF2 calculations. Both exceed the prospective 50 meV screen. Matched-coordinate/unit evaluation with the upstream calculator reproduces the adapter values within 7e-14 eV. This is a difference between approximate models, not evidence for changing adapter units or fitting away the discrepancy. Exclude the inconsistent 0leg triple described above. DFT electronic smearing and boundary conventions remain part of the reference record.

The public 1D MACE route also exposes the upstream partial-PBC neighbour defect noted in the manual. A job-local diagnostic using upstream 726ecec6 restores the saved nanotube result, including an eleven-cell rigid translation, within 2.2e-14 Ha and 1.7e-14 Ha/bohr. The three wire rotation/translation regressions pass with that correction. This does not qualify an installed runtime that still has the old dependency, or validate all tilted slabs and dynamics. Preserve the failing unpatched case.

Largest practical size per method¶

Measure a size ladder only after the small numerical cases pass. Start with the same chemistry and increase periodic repeats, recording actual atoms, basis functions or graph size, force evaluations, cold/warm time, peak RSS, threads/device, convergence iterations and output size. Stop on a scientific failure or before the next measured cost exceeds the declared resource budget. Retain the largest completed size and the first limiting case, without calling an extrapolation a validated ceiling.

The practical size is method-, observable- and hardware-dependent. A single energy evaluation does not establish feasibility of forces, relaxation, a barrier or dynamics. In particular, a 6N finite-difference force path can dominate the cost even when its energy is fast. Current dense SCC/state solvers, periodic SCC-DFTB’s finite-difference gradient, experimental SECCM state stability and parameter accuracy remain explicit possible limits. No fixed speedup over DFT is assumed. Sparse/linear-scaling development, if needed, must preserve the same accuracy and state diagnostics.

Ready-for-production claims must name the supported dimensionality, chemistry, observables and measured scale. The complete application scope above remains open until those requirements have executed evidence.