vibeqc.run_periodic_job

vibeqc.run_periodic_job(system, basis, *, method='RHF', functional=None, jk_method='auto', cutoff_ha=300.0, aux_basis=None, gdf_method=None, mdf_ke_cutoff=40.0, output='output', use_diis=True, convergence=None, damping=None, fmixing_percent=None, smearing=None, smearing_temperature=<object object>, smearing_unit='hartree', smearing_method='fermi-dirac', smearing_metallic=None, smearing_band_gap_hartree=None, diis_start_iter=2, diis_subspace_size=8, max_iter=80, conv_tol_energy=1e-07, initial_guess='SAD', write_molden_file=True, write_density=False, density_spacing_bohr=0.2, write_xyz_file=True, write_poscar_file=True, write_xsf_structure_file=True, write_cif_file=True, write_population_file=True, citations=True, dry_run=False, record_hostname=True, progress=None, verbose=None, dispersion=None, dispersion_backend='auto', dispersion_cutoff_bohr=50.0, ewald_omega=None, ewald_precision=1e-08, use_oda=False, oda_trust_lambda_max=1.0, use_mom=False, level_shift=None, kpoints=None, reduce_to_primitive=False, symmetry_precision=0.0001, symmetry=False, symmetry_stabilize=False, symmetry_reduce_fock=False, use_multipole_far_field=False, multipole_l_max=2, use_exchange_ewald_split=None, exchange_exxdiv='ewald', optimize=False, optimize_max_iter=30, optimize_conv_tol_grad=0.0001, optimize_cell=False, output_qvf=False, hessian=False, hessian_frozen_indices=None, band_structure=None, dft_plus_u=None, atomic_spins=None, read_from=None, restart_from=None)[source]

Run a periodic SCF job and write the standard output files.

Mirrors vibeqc.run_job() but for periodic systems. Γ-only RHF/RKS GDF is the default when no k-mesh is specified. Multi-k RHF/RKS GDF and all four BIPOLE methods are available via kpoints. The BIPOLE route accepts a mesh tuple/list, a scalar mesh size, KPoints, or a native BlochKMesh.

Parameters:

  • system (PeriodicSystem) – Periodic system + AO basis.

  • basis (BasisSet) – Periodic system + AO basis.

  • method (str) – "RHF", "UHF", "RKS" or "UKS". Closed-shell RHF / RKS default to the Γ-only or multi-k GDF path depending on kpoints. With jk_method="bipole", all four methods dispatch through the BIPOLE Γ or multi-k route.

  • functional (Optional[str]) – XC functional for method="RKS" or method="UKS".

  • output (Union[str, os.PathLike]) – Path stem; produces {output}.out, {output}.system, {output}.molden, {output}.xsf (when write_density).

  • band_structure (Optional['BandStructure']) – Optional BandStructure pre-computed by vibeqc.band_structure() (or _hcore). When given together with output_qvf=True, the band structure is embedded in the QVF archive so vibe-view can render an interactive Plotly band-structure plot. Compute it before calling this function — the same workflow used for matplotlib plotting with vibeqc.plot.band_structure_figure().

  • aux_basis (Optional[str]) – Optional auxiliary basis for jk_method="gdf". If omitted, vibe-qc chooses the current native-GDF default for basis.name.

  • convergence (Optional[str]) – Convergence-strategy selector. "auto" classifies the system from cheap pre-SCF signals (composition electronegativity spread, cell volume, vacuum axes, electron parity) into a profile — ionic-insulator, covalent-insulator, metallic-candidate or molecular-limit — and fills every convergence knob the user did not set (Fermi-Dirac smearing, FMIXING, level shift, damping) with profile defaults grounded in measured behaviour (e.g. MgO-class ionic cells get FMIXING 30 % + T = 0.01 Ha and converge in ~20 iterations). "off"/"none" keeps the plain defaults. Omitted (None): auto applies only when no explicit convergence knob is given — any explicit damping= / fmixing_percent= / level_shift= / smearing input switches to fully-manual mode and nothing is auto-filled. Either way the .out file carries a “Convergence strategy” block stating the mode (AUTO default / AUTO requested / manual / off), the per-knob values with their provenance, and the classification reasons. Explicit knobs are never overridden. Scope: applied on jk_method="bipole" and "gdf"; other routes run with plain defaults and label the block accordingly.

  • use_diis (bool)

  • damping (Optional[float])

  • fmixing_percent (Optional[float])

  • diis_start_iter (int)

  • jk_method (Union[str, 'PeriodicJKMethod'])

  • cutoff_ha (float)

  • gdf_method (Optional[str])

  • mdf_ke_cutoff (float)

  • smearing (Optional[SmearingOptions])

  • smearing_temperature (Union[float, str, None])

  • smearing_unit (str)

  • smearing_method (str)

  • smearing_metallic (Optional[bool])

  • smearing_band_gap_hartree (Optional[float])

  • diis_subspace_size (int)

  • max_iter (int)

  • conv_tol_energy (float)

  • initial_guess (str)

  • write_molden_file (bool)

  • write_density (bool)

  • density_spacing_bohr (float)

  • write_xyz_file (bool)

  • write_poscar_file (bool)

  • write_xsf_structure_file (bool)

  • write_cif_file (bool)

  • write_population_file (bool)

  • citations (bool)

  • dry_run (bool)

  • record_hostname (bool)

  • progress (Union[bool, ProgressLogger, None])

  • verbose (Optional[int])

  • dispersion (Optional[Union[str, bool, 'D3BJParams']])

  • dispersion_backend (str)

  • dispersion_cutoff_bohr (float)

  • ewald_omega (Optional[float])

  • ewald_precision (float)

  • use_oda (bool)

  • oda_trust_lambda_max (float)

  • use_mom (bool)

  • level_shift (Optional[float])

  • kpoints (Optional[Union[Tuple[int, int, int], List[int], int, 'KPoints', 'BlochKMesh']])

  • reduce_to_primitive (bool)

  • symmetry_precision (float)

  • symmetry (Union[bool, str])

  • symmetry_stabilize (bool)

  • symmetry_reduce_fock (bool)

  • use_multipole_far_field (bool)

  • multipole_l_max (int)

  • use_exchange_ewald_split (Optional[bool])

  • exchange_exxdiv (str)

  • optimize (bool)

  • optimize_max_iter (int)

  • optimize_conv_tol_grad (float)

  • optimize_cell (bool)

  • output_qvf (bool)

  • hessian (bool)

  • hessian_frozen_indices (Optional[List[int]])

  • dft_plus_u (Optional[List['HubbardSite']])

  • atomic_spins (Optional[List[int]])

  • read_from (Optional[object])

  • restart_from (Optional[Union[str, os.PathLike]])

:param : :param diis_subspace_size: SCF controls forwarded to the periodic driver.

fmixing_percent mirrors CRYSTAL’s FMIXING keyword: the percentage of the previous Fock/KS matrix mixed into the matrix diagonalised on the next cycle. It is separate from density damping. smearing accepts the new vibeqc.SmearingOptions surface. The legacy smearing_temperature may be a numeric electronic k_B T (interpreted via smearing_unit), "auto", "metal", "small-gap", "debug", "none" / "off", or None. Only smearing_method="fermi-dirac" is implemented today. smearing_metallic and smearing_band_gap_hartree guide the conservative "auto" guess.

Parameters:

  • max_iter (int) – SCF controls forwarded to the periodic driver. fmixing_percent mirrors CRYSTAL’s FMIXING keyword: the percentage of the previous Fock/KS matrix mixed into the matrix diagonalised on the next cycle. It is separate from density damping. smearing accepts the new vibeqc.SmearingOptions surface. The legacy smearing_temperature may be a numeric electronic k_B T (interpreted via smearing_unit), "auto", "metal", "small-gap", "debug", "none" / "off", or None. Only smearing_method="fermi-dirac" is implemented today. smearing_metallic and smearing_band_gap_hartree guide the conservative "auto" guess.

  • conv_tol_energy (float) – SCF controls forwarded to the periodic driver. fmixing_percent mirrors CRYSTAL’s FMIXING keyword: the percentage of the previous Fock/KS matrix mixed into the matrix diagonalised on the next cycle. It is separate from density damping. smearing accepts the new vibeqc.SmearingOptions surface. The legacy smearing_temperature may be a numeric electronic k_B T (interpreted via smearing_unit), "auto", "metal", "small-gap", "debug", "none" / "off", or None. Only smearing_method="fermi-dirac" is implemented today. smearing_metallic and smearing_band_gap_hartree guide the conservative "auto" guess.

  • initial_guess (str) – "SAD" (default) or "HCORE".

  • write_molden_file (bool) – Emit {output}.molden of the Γ-point MOs (using the unit-cell molecule + basis as the molecular target).

  • write_density (bool) – Emit {output}.xsf with the SCF density on a primitive-cell grid (XSF works for any lattice; cube is orthorhombic-only).

  • density_spacing_bohr (float) – Grid spacing for the XSF density. Default 0.2 bohr.

  • hessian (bool) – When True, compute harmonic vibrational frequencies for the unit-cell molecule via finite-difference Hessian. Frequencies and IR intensities printed to .out and embedded in QVF for vibe-view. Default False. Cost: ~6N SCF evaluations for the unit cell.

  • system (PeriodicSystem)

  • basis (BasisSet)

  • method (str)

  • functional (Optional[str])

  • jk_method (Union[str, 'PeriodicJKMethod'])

  • cutoff_ha (float)

  • aux_basis (Optional[str])

  • gdf_method (Optional[str])

  • mdf_ke_cutoff (float)

  • output (Union[str, os.PathLike])

  • use_diis (bool)

  • convergence (Optional[str])

  • damping (Optional[float])

  • fmixing_percent (Optional[float])

  • smearing (Optional[SmearingOptions])

  • smearing_temperature (Union[float, str, None])

  • smearing_unit (str)

  • smearing_method (str)

  • smearing_metallic (Optional[bool])

  • smearing_band_gap_hartree (Optional[float])

  • diis_start_iter (int)

  • diis_subspace_size (int)

  • write_xyz_file (bool)

  • write_poscar_file (bool)

  • write_xsf_structure_file (bool)

  • write_cif_file (bool)

  • write_population_file (bool)

  • citations (bool)

  • dry_run (bool)

  • record_hostname (bool)

  • progress (Union[bool, ProgressLogger, None])

  • verbose (Optional[int])

  • dispersion (Optional[Union[str, bool, 'D3BJParams']])

  • dispersion_backend (str)

  • dispersion_cutoff_bohr (float)

  • ewald_omega (Optional[float])

  • ewald_precision (float)

  • use_oda (bool)

  • oda_trust_lambda_max (float)

  • use_mom (bool)

  • level_shift (Optional[float])

  • kpoints (Optional[Union[Tuple[int, int, int], List[int], int, 'KPoints', 'BlochKMesh']])

  • reduce_to_primitive (bool)

  • symmetry_precision (float)

  • symmetry (Union[bool, str])

  • symmetry_stabilize (bool)

  • symmetry_reduce_fock (bool)

  • use_multipole_far_field (bool)

  • multipole_l_max (int)

  • use_exchange_ewald_split (Optional[bool])

  • exchange_exxdiv (str)

  • optimize (bool)

  • optimize_max_iter (int)

  • optimize_conv_tol_grad (float)

  • optimize_cell (bool)

  • output_qvf (bool)

  • hessian_frozen_indices (Optional[List[int]])

  • band_structure (Optional['BandStructure'])

  • dft_plus_u (Optional[List['HubbardSite']])

  • atomic_spins (Optional[List[int]])

  • read_from (Optional[object])

  • restart_from (Optional[Union[str, os.PathLike]])