Experimental features¶

vibe-qc ships a handful of features behind an experimental gate. They are reachable, you can turn one on and get a result, but they are not yet production-certified: a feature may be incomplete, may change or break between releases without the usual deprecation cycle, or is known to be inaccurate in some regime. Each one emits an ExperimentalWarning (or a feature-specific subclass) every time you use it, so an experimental result never slips into a script unnoticed.

This page is the catalog. Anything not listed here, and not flagged experimental on its own page, is production-grade.

What “experimental” means here¶

There are two reasons a feature carries the gate, and the difference matters for whether you can trust its numbers:

Production-quality in its supported regime, warned because the broader feature is still being built. GPW and GAPW are the examples: the shipped paths reproduce their references, but the surrounding capability (the all-electron augmentation default, open-shell multi-k, and so on) is incomplete, so the whole route warns. Safe to use within the documented regime.
Not yet accurate enough for published numbers. The native D4 backend, GFN2-xTB, OM1, and the BIPOLE multipole far-field are in this group: they run, but a known defect or a missing term makes them development and qualitative only. The “Quantitative” column below flags these.

Roadmap features are different: those raise NotImplementedError and are not reachable at all (see the roadmap). Experimental features are reachable; they just warn.

Catalog¶

Feature	Area	Opt in	Status and key caveat	Quantitative
GPW (Gaussian plane waves)	periodic	`run_periodic_job(jk_method="gpw")`	Gamma-only RHF/RKS/UHF/UKS and multi-k pure-DFT RKS ship; emits `GAPWExperimentalWarning`	Yes, in the supported regime
GAPW (all-electron augmentation)	periodic	`run_periodic_job(jk_method="gapw")`	not yet the AUTO default; single atoms match the all-electron reference, molecules over-bind (overlapping augmentation spheres); meta-GGA and open-shell GAPW raise	Partial
BIPOLE multipole far-field J	periodic	`run_periodic_job(jk_method="bipole", use_multipole_far_field=True)`	off by default; roughly 78 percent error on compact molecules (no near-field / far-field split); rejected under the corrected Ewald gauge	No
BIPOLE multi-k KS analytic gradient	periodic	`run_periodic_job(jk_method="bipole", optimize=True)` on a KS functional	maintained preview; the corrected gauge is finite-difference-validated, broader KS certification is pending. The default forces are the exact finite-difference path	Partial
MPI GPW grid overlay	periodic	`GpwJBuilder(mpi_aware=True)` (not via `run_periodic_job`)	distributed-memory Hartree-J; the multi-rank build was fixed after v0.12 and is pending validation on a real multi-rank run	No
Surface embedding (Green’s function)	periodic	the embedded-surface calculator, see surface embedding	emits an experimental warning; the 3D Gaussian foundation is validated, thick-slab GDF parity is pending, so absolute energies and densities are qualitative	No
AICCM2026DEV-A	periodic	`vibeqc.periodic.ccm`, `method="aiccm2026dev-a"`	symmetric weighted-integral development line with HF, KS, MP2, and CCSD(T); see its separate page	Partial
AICCM2026DEV-B	periodic	`run_periodic_job(jk_method="aiccm2026dev-b")`; restricted/unrestricted B APIs	independent finite-torus RHF/RKS/UHF/UKS in 1D/2D/3D plus restricted and unrestricted real-torus correlation in 3D; the real-space lattice extension is primary and the character net is derived; occupied localization and space-group diagnostics are B-only; symmetry integral reduction, minimum-image local screens, and production reduced-scaling CC remain open; see its separate page	Partial
GFN2-xTB	semiempirical	`run_job(method="gfn2_xtb")`	not quantitative; external parity and the periodic terms are production gates, and the native D4 dispersion over-binds (defective dataset)	No
OM1	semiempirical	`run_job(method="om1")`	the analytic core-valence ECP is not implemented, so bonds to heavy atoms come out roughly 0.3 angstrom short; OM2 / OM3 / PM6 are complete and do not warn	No
D4 dispersion, native backend	dispersion	`compute_d4(..., backend="native")`	the bundled reference dataset is defective (C6 coefficients 4 to 32 times too large), so it over-binds. The default `backend="dftd4"` (optional package) is bit-exact and production	No

The periodic GPW/GAPW family is documented in full in GPW and GAPW and the GAPW design note. The native-D4-backend status, the BIPOLE gradient preview, and the GFN2-xTB / OM1 limits are in troubleshooting; the semiempirical models also have a user-guide page.

The B-stream research interfaces have separate pages for occupied localization, PAO/PNO local correlation, and space-group diagnostics.

Keeping competing versions on purpose¶

Some experimental features exist in more than one version on purpose, because the right approach is itself an open research question and we want to measure which one wins before committing to it. These are not duplicates to be merged away; all are maintained until the comparison is settled.

The active example is the ab-initio CCM (AICCM). Three constructions are kept visible while two development streams remain independent:

method="union12" (default), the historical product weight from Peintinger and Bredow 2014 (eq. 18). Validated in 1-D, but it breaks the 8-fold permutational symmetry of the electron-repulsion integrals in two and three dimensions.
method="aiccm2026dev-a", the A stream’s explicitly symmetrized WSSC-weighted-integral construction inside vibeqc.periodic.ccm.
jk_method="aiccm2026dev-b", the independent B stream’s finite-group character representation in vibeqc.periodic_aiccm2026dev_b. It periodizes one Hamiltonian first and uses Wigner–Seitz ties only to choose equivalent representatives; it does not import the A-stream core.

Agreement in selected 1D tests is not assumed to extend to non-Bravais or higher-dimensional boundaries. The A and B streams are developed independently on purpose: if they converge to the same answer under a matched Coulomb gauge, that is evidence for the common limit; if they diverge, the tensor symmetries and scalar energy derivatives decide which construction is admissible. The duplication is the experiment, not an oversight.

The fleet comparison uses one shared geometry registry but separate executable drivers. See the AICCM2026DEV-B fleet inputs for the complete RHF/RKS backend matrix and the 3D post-HF inputs.

Internal and research-only paths (not for users)¶

A few experimental code paths are research scaffolding rather than user-facing features. They have no run_job / run_periodic_job entry, or are superseded, so they live in the roadmap rather than here: the GAPW orbital-transformation (OT) direct-minimisation solver, the landed-but-unwired Anderson density mixer, the BIPOLE legacy-gauge diagonal-Z gradient preview, and omega-B97M(2) (the functional exists in libxc but has no user alias yet).

Silencing an experimental warning¶

The warnings exist so an experimental path never runs unnoticed. Once you have read the caveat and accept it, silence it the standard Python way by filtering on the feature’s warning class (for example GAPWExperimentalWarning, importable from the module that raises it):

import warnings
warnings.filterwarnings("ignore", category=GAPWExperimentalWarning)

Some constructors also take a warn=False argument, for example GFN2Model(mol, warn=False).

Adding to this page¶

This is the designated home for experimental-feature status. When you ship a feature behind an ExperimentalWarning (or a subclass), add a row to the catalog with its opt-in and its one key caveat, and link to its detailed page. A feature that warns at runtime but is invisible here is exactly the gap this page exists to close.