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, cisd_options=None, selected_ci_options=None, dmrg_options=None, v2rdm_options=None, transcorrelated_options=None, casci_options=None, caspt2_options=None, casscf_options=None, active_space=None, cas_reference=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", "casci", "casscf"). 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.

  • / (transcorrelated_options / casci_options / caspt2_options)

  • /

  • casscf_options (Any) – Wavefunction-solver options, forwarded to every per-step energy evaluation (the FD path) exactly as the final single point receives them — an SA-CASSCF optimization (casscf_options=CASSCFOptions(nroots=2)) walks the state-averaged surface it reports.

  • active_space (tuple[int, int] | None) – (n_active_orbitals, n_active_electrons) truncation for the wavefunction methods, applied at every per-step evaluation. Without it a selected_ci step would run full-space CI.

  • cas_reference (str | None) – Reference-orbital choice for the determinant solvers ("rhf" / "uhf" / "uno").

  • 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

  • cisd_options (Any)

  • selected_ci_options (Any)

  • dmrg_options (Any)

  • v2rdm_options (Any)

  • transcorrelated_options (Any)

  • casci_options (Any)

  • caspt2_options (Any)

Return type:

MolecularOptimizeResult