vibeqc.optimize_molecule

vibeqc.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, freeze_indices=None)[source]

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

Parameters:

  • molecule (vibeqc._vibeqc_core.Molecule) – Starting geometry (Cartesian coordinates in bohr).

  • basis_name (str) – Basis-set name (rebuilt at each geometry step).

  • method (str) – "rhf", "uhf", "rks", "uks", or a wavefunction method ("selected_ci", "dmrg", "v2rdm", "transcorrelated_ci"). Wavefunction methods fall back to central finite differences on the energy.

  • functional (str | None) – XC functional string for "rks" / "uks" (e.g. "PBE").

  • uks_options (vibeqc._vibeqc_core.UKSOptions | None) – Per-method SCF options. If None, defaults are used.

  • max_iter (int) – Maximum L-BFGS-B iterations.

  • conv_tol_grad (float) – Gradient convergence tolerance (Ha/bohr). Default 4.5e-4 corresponds to ~0.01 eV/Å — tight enough for routine use.

  • conv_tol_energy (float) – Energy convergence tolerance (Ha). Controls the scipy ftol parameter.

  • gradient_options (vibeqc._vibeqc_core.GradientOptions | None) – Options for the analytic gradient kernels (density fitting, COSX, etc.).

  • grid_options (vibeqc._vibeqc_core.GridOptions | None) – DFT integration grid options (RKS / UKS only).

  • dispersion_params (Any) – A D3BJParams instance — if provided, the D3-BJ energy and gradient are folded into the objective.

  • solvent (Any) – A SolventModel or preset string / dict for CPCM implicit solvation (v0.9.0).

  • record_trajectory (bool) – If True (default), collect per-step geometries and energies for downstream visualisation (QVF animation player).

  • progress (bool) – If True, print per-step energy and gradient norms to stdout.

  • fd_step_bohr (float) – Finite-difference step size for wavefunction-method gradients (bohr). Default 0.005 (≈ 0.0026 Å).

  • freeze_indices (Sequence[int] | None) – Atom indices to hold fixed during the relaxation. Implemented via per-coordinate L-BFGS-B (fixed, fixed) bounds, mirroring vibeqc.bipole_optimize.relax_atoms(). The SCF + gradient still see every atom; the optimizer simply cannot move the frozen ones, and the reported |grad| excludes them so the convergence metric reflects only the free degrees of freedom.

  • rhf_options (vibeqc._vibeqc_core.RHFOptions | None)

  • uhf_options (vibeqc._vibeqc_core.UHFOptions | None)

  • rks_options (vibeqc._vibeqc_core.RKSOptions | None)

  • uks_options

Return type:

MolecularOptimizeResult