vibe-qcDocumentation

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_optimization raises a DeprecationWarning that names this page. New work uses vibeqc.basisopt.

  • Through the 0.19 release line: vibeqc.basis_optimization stays 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

{symbol: CrystalAtomBasis} dicts

basisopt.model.BasisModel (from_library, from_toolkit, native)

parametrise.BasisParametrisation, FreeSpec

basisopt.params: FreeExponents, EvenTempered, WellTempered, SharedExponents, Coefficients, Composite

objective.SinglePointEnergy, PeriodicSinglePointEnergy

basisopt.objectives.Objective with energy_term, routes molecular, bipole, gdf, aiccm:<variant>

Correlation and cohesive objectives in the recipes

correlation_term, cohesive_term

ld_penalty, condition_number_penalty

ConditioningGuard (reject or penalty), SpacingGuard

drivers.optimize_scipy (L-BFGS-B)

basisopt.optimize.minimize(method="quasi-newton")

bdiis.optimize_bdiis

minimize(method="bdiis")

drivers.optimize_bobyqa (COBYQA)

minimize(method="cobyqa")

drivers.optimize_cmaes

minimize(method="cmaes")

drivers.optimize_minuit, drivers.optimize_dfols

No counterpart; use quasi-newton or cobyqa

recipes.global_then_polish

Two workflows.Stages in run_pipeline: cmaes, then bdiis

recipes.topology_scan

workflows.topology_search

CRYSTAL stage recipes (crystal_stage1 to 3, production)

No counterpart: native stages in run_pipeline

Contraction by hand

workflows.natural_orbitals, workflows.contract

export.save_optimised_basis, write_optimised_basis

basisopt.report.export_basis, load_exported

Recipe summaries

basisopt.report.build_report, write_report

vibe_basis campaigns (campaign.json, energies.jsonl)

basisopt.run.Campaign (journal.jsonl)

vb parse crystal OUT

vibe-qc-basisopt parse crystal OUT

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.