Moving to the basis-set optimizer engine¶
vibe-qc has two basis-set optimizers. vibeqc.basis_optimization, with the
vibe-basis/ driver it delegates to, is frozen: it gets bug and licence fixes
only. vibeqc.basisopt is its clean replacement, designed in
the engine design. This page maps each part of
the frozen code to its replacement (#1059).
Timeline¶
Now: importing
vibeqc.basis_optimizationraises aDeprecationWarningthat names this page. New work usesvibeqc.basisopt.Through the 0.19 release line:
vibeqc.basis_optimizationstays importable as a deprecated alias.vibe-basis/retires once no running campaign imports it. Its distribution, lifecycle scripts, documentation and roadmap go in the same change.
What changes in practice¶
Evaluation is native. Every objective is computed by vibe-qc in the same process, or by a fleet job that runs vibe-qc. CRYSTAL and ORCA are validation references, never evaluators. A recipe that drove CRYSTAL has no counterpart.
No basis files during a run. A candidate basis is an in-memory model. Routes that only accept a name get a scoped registration.
Gradients come with the objective. RHF and UHF molecular terms use the analytic exponent gradient of
vibeqc.basis_derivatives. Other terms use finite differences, and the result says which was used.Failures are explicit. A rejected point carries its reasons. An optimizer never sees a silent stand-in value.
Mapping¶
Frozen |
Replacement |
|---|---|
|
|
|
|
|
|
Correlation and cohesive objectives in the recipes |
|
|
|
|
|
|
|
|
|
|
|
|
No counterpart; use |
|
Two |
|
|
CRYSTAL stage recipes ( |
No counterpart: native stages in |
Contraction by hand |
|
|
|
Recipe summaries |
|
|
|
|
|
Old results stay readable¶
A campaign directory of the frozen engine, or a bare energies.jsonl, loads
read-only:
from vibeqc.basisopt.run import read_frozen_campaign
old = read_frozen_campaign("path/to/campaign")
old.summary() # evaluations, failures by mode, engines, sessions
old.energy("c:0e01e730609dbe1e")
The reader never takes the lock or writes, so it is safe while a frozen driver still runs. From the shell, the same summary for either engine’s campaigns is:
vibe-qc-basisopt campaign path/to/campaign
vibe-qc-basisopt parse crystal OUT reads a CRYSTAL output with the frozen
reader’s rules. Exit code 0 means converged and finished. A convergence on a
cycle that left the density unchanged is reported as scf_stalled.
Parity¶
The new engine was checked against the frozen one on a molecular objective
that both compute natively. For H2 RHF with three free hydrogen s exponents,
both reach the same optimum to 1e-9 Ha in the energy and 1e-4 in the
exponents (tests/basisset_dev/test_basisopt_migration.py). The periodic and
atomic gates of #1059 compare final bases against CRYSTAL and ORCA through
vq. They are recorded on that issue with their runtime identities.