Native Molecular Geometry Optimizer¶

vibe-qc ships a standalone molecular geometry optimizer that needs no ASE. It wraps analytic SCF nuclear gradients under scipy’s L-BFGS-B minimiser and is available both as a library function and through run_job.

Quick start¶

from vibeqc import Molecule, Atom
from vibeqc.molecular_optimize import optimize_molecule

mol = Molecule([
    Atom(8, [ 0.00,  0.00,  0.00]),
    Atom(1, [ 0.00,  1.43, -0.98]),
    Atom(1, [ 0.00, -1.43, -0.98]),
])

result = optimize_molecule(
    mol,
    basis_name="def2-svp",
    method="rks",
    functional="PBE",
)
print(result.system)           # optimised Molecule (bohr)
print(result.energy)           # final energy (Ha)
print(result.n_iter)           # number of BFGS steps
print(result.converged)        # True / False

Through `run_job`¶

Pass optimizer_backend="native" to bypass ASE:

from vibeqc import run_job

run_job(
    mol,
    basis="def2-svp",
    method="rks",
    functional="PBE",
    optimize=True,
    optimizer_backend="native",   # ← no ASE needed
    output="h2o_opt",
)

The default optimizer_backend="auto" prefers ASE when installed and falls back to the native path otherwise, so existing workflows are unchanged.

Supported methods¶

Method	Gradient	Notes
`rhf`, `uhf`	Analytic	All-electron, closed- and open-shell
`rks`, `uks`	Analytic	All DFT functionals with analytic gradients
`selected_ci`, `dmrg`, `v2rdm`, `transcorrelated_ci`	Central FD	2-point finite difference on energy (`fd_step_bohr=0.005`)

Dispersion corrections (D3-BJ) and implicit solvation (CPCM/COSMO) are folded into the energy and gradient automatically when passed.

Trajectory collection¶

Set record_trajectory=True (the default) to collect per-step geometries and energies:

result = optimize_molecule(mol, basis_name="sto-3g", method="rhf")
for i, (frame, e) in enumerate(
    zip(result.trajectory_frames, result.trajectory_energies)
):
    print(f"  step {i}: E = {e:.8f} Ha")

When used through run_job(optimize=True, output_qvf=True), the trajectory is embedded in the QVF archive for vibe-view’s animation player — identical behaviour to the ASE backend.

Convergence control¶

Parameter	Default	Meaning
`conv_tol_grad`	`4.5e-4`	Gradient norm convergence (Ha/bohr)
`conv_tol_energy`	`1e-6`	Energy change tolerance (Ha)
`max_iter`	`100`	Maximum L-BFGS-B steps

For DFT jobs where the SCF may struggle at intermediate geometries (common with PBE + minimal basis sets), pass the appropriate rks_options / uks_options with increased max_iter:

from vibeqc import RKSOptions

rks_opts = RKSOptions()
rks_opts.max_iter = 80
rks_opts.use_diis = True

result = optimize_molecule(
    mol, basis_name="sto-3g", method="rks", functional="PBE",
    rks_options=rks_opts,
)

API reference¶

class vibeqc.molecular_optimize.MolecularOptimizeResult(system, energy, gradient, n_iter, converged, trajectory_frames=None, trajectory_energies=None)[source]¶

Bases: object

Container for molecular geometry optimization results.

Parameters:

system (Molecule)
energy (float)
gradient (np.ndarray)
n_iter (int)
converged (bool)
trajectory_frames (Optional[list[Molecule]])
trajectory_energies (Optional[list[float]])

vibeqc.molecular_optimize.optimize_molecule(molecule, basis_name, *, method='rhf', functional=None, rhf_options=None, uhf_options=None, rks_options=None, uks_options=None, max_iter=100, conv_tol_grad=0.00045, conv_tol_energy=1e-06, gradient_options=None, grid_options=None, dispersion_params=None, solvent=None, record_trajectory=True, progress=False, fd_step_bohr=0.005)[source]¶

Relax molecular geometry using analytic gradients + L-BFGS-B.