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, rsgdf_ke_cutoff=200.0, rsgdf_tail_ke_cutoff=None, mdf_ke_cutoff=40.0, aiccm_backend='four_center', aiccm_lattice_extension=None, aiccm_wigner_seitz_shells=None, aiccm_symmetry='off', aiccm_symmetry_require_full_group=False, output='output', use_diis=True, solver='dense', convergence=None, damping=None, fmixing_percent=None, fock_mixing=None, density_mixer=None, density_mixer_depth=8, density_mixer_beta=0.5, density_mixer_kerker=False, kerker_k0=1.5, kerker_strength=1.0, kerker_cutoff_ha=120.0, smearing=None, smearing_temperature=<object object>, smearing_unit='hartree', smearing_method='fermi-dirac', smearing_metallic=None, smearing_band_gap_hartree=None, bz_integration=<object object>, 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=False, write_xsf_structure_file=True, write_cif_file=True, write_population_file=True, citations=True, dry_run=False, memory_override=False, record_hostname=True, progress=None, verbose=None, dispersion=None, dispersion_backend='auto', dispersion_cutoff_bohr=50.0, bipole_cutoff_bohr=None, bipole_nuclear_cutoff_bohr=None, 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=True, qvf_wannier_centers=False, checkpoint_qvf=None, checkpoint_every=0, hessian=False, hessian_frozen_indices=None, band_structure=None, coop_cohp=False, tddft=False, tddft_n_states=5, dos_kmesh=None, dft_plus_u=None, atomic_spins=None, read_from=None, spinlock=None, spinlock_value=0, spinlock_iterations=0, restart_from=None)[source]

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

Mirrors vibeqc.run_job() but for periodic systems. Gamma RHF/RKS GDF is the default when no k-mesh is specified. Multi-k RHF/RKS GDF, multi-k RHF/RKS/UHF/UKS RIJCOSX, and all four BIPOLE methods are available via kpoints. These routes accept 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 Gamma or multi-k GDF path depending on kpoints. With jk_method="bipole", all four methods dispatch through the BIPOLE Gamma or multi-k route. With jk_method="rijcosx", Gamma RHF uses the dedicated RIJCOSX driver and true multi-k meshes use the GDF/COSX backend for RHF/RKS/UHF/UKS.

  • 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().

  • coop_cohp (bool) – When True together with output_qvf=True, compute COOP and COHP bonding analysis and embed dos.coop + dos.cohp sections in the QVF archive. Uses the same DOS k-mesh as the total/projected DOS ([8,8,8]). The Hcore matrix (T + V) needed for COHP is computed independently within the DOS/COHP k-mesh block; no additional user input is required.

  • tddft (bool) – When True, compute TD-DFT vertical excitation energies via the Tamm-Dancoff approximation (TDA) at the Gamma point. Writes excitation energies, oscillator strengths, and dominant transitions to the .out file. Requires _has_valid_mo_coeffs(result) (true for Γ-only and multi-k results). Not embedded in QVF yet.

  • tddft_n_states (int) – Number of excited states to compute when tddft=True. Default 5.

  • dos_kmesh (Optional[Sequence[int]]) – Override the DOS/PDOS/COOP k-mesh dimensions. Default [8, 8, 8]. For 1D systems use e.g. [32, 1, 1]; for 2D use [12, 12, 1]. Only used when output_qvf=True.

  • qvf_wannier_centers (bool) – When True for jk_method="aiccm2026dev-b", localize the occupied finite-torus space with the B-owned Wannier gauge and embed an x_ccm.wannier_centers vendor section in the QVF archive for vibe-view’s centre overlay. Requires output_qvf=True.

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

  • bipole_cutoff_bohr (Optional[float]) – Direct-lattice cutoff radii in bohr for jk_method="bipole". bipole_cutoff_bohr controls the electronic BIPOLE Fock sums; when bipole_nuclear_cutoff_bohr is omitted, the BIPOLE route keeps the nuclear/Ewald real-space cutoff no longer than the electronic J/K cutoff so neutral-cell cancellation stays in the corrected Ewald gauge. These are separate from cutoff_ha, which is a GPW/GAPW plane-wave grid cutoff.

  • bipole_nuclear_cutoff_bohr (Optional[float]) – Direct-lattice cutoff radii in bohr for jk_method="bipole". bipole_cutoff_bohr controls the electronic BIPOLE Fock sums; when bipole_nuclear_cutoff_bohr is omitted, the BIPOLE route keeps the nuclear/Ewald real-space cutoff no longer than the electronic J/K cutoff so neutral-cell cancellation stays in the corrected Ewald gauge. These are separate from cutoff_ha, which is a GPW/GAPW plane-wave grid cutoff.

  • 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. MgO-class ionic cells get FMIXING 30 % with integer occupations; smearing is never selected automatically for an insulating profile because it can converge a wrong-energy metallic basin. "off"/"none" keeps the plain defaults. Omitted (None): auto applies only when no explicit convergence knob is given – any explicit damping= / fmixing_percent= / fock_mixing= / 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])

  • fock_mixing (Optional[float])

  • diis_start_iter (int)

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

  • cutoff_ha (float)

  • gdf_method (Optional[str])

  • rsgdf_ke_cutoff (float)

  • rsgdf_tail_ke_cutoff (Optional[float])

  • mdf_ke_cutoff (float)

  • aiccm_backend (str)

  • aiccm_lattice_extension (Optional[Union[int, Sequence[int]]])

  • aiccm_wigner_seitz_shells (Optional[Union[int, Sequence[int]]])

  • aiccm_symmetry (str)

  • aiccm_symmetry_require_full_group (bool)

  • solver (str)

  • density_mixer (Optional[str])

  • density_mixer_depth (int)

  • density_mixer_beta (float)

  • density_mixer_kerker (bool)

  • kerker_k0 (float)

  • kerker_strength (float)

  • kerker_cutoff_ha (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])

  • bz_integration (Optional[str])

  • 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)

  • memory_override (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)

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

  • checkpoint_every (int)

  • hessian (bool)

  • hessian_frozen_indices (Optional[List[int]])

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

  • atomic_spins (Optional[List[int]])

  • read_from (Optional[object])

  • spinlock (Optional[str])

  • spinlock_value (int)

  • spinlock_iterations (int)

  • 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. fock_mixing is the same knob on the fractional 0.0-1.0 scale; pass only one spelling. density_mixer / density_mixer_kerker expose the periodic Anderson/Broyden/Kerker API surface on the closed-shell multi-k GDF and RIJCOSX routes. The lower-level Ewald RKS drivers also support these mixers directly. Other routes fail closed on active requests instead of silently ignoring them or changing electrostatic gauge. Compact 3D closed-shell RKS/GDF SCAN/r2SCAN-family jobs with an explicit kpoints= mesh select Anderson density mixing by default unless density_mixer= or convergence="off" is set. 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. smearing_method selects "fermi-dirac" (default), "methfessel-paxton" or "marzari-vanderbilt" (all implemented). 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. fock_mixing is the same knob on the fractional 0.0-1.0 scale; pass only one spelling. density_mixer / density_mixer_kerker expose the periodic Anderson/Broyden/Kerker API surface on the closed-shell multi-k GDF and RIJCOSX routes. The lower-level Ewald RKS drivers also support these mixers directly. Other routes fail closed on active requests instead of silently ignoring them or changing electrostatic gauge. Compact 3D closed-shell RKS/GDF SCAN/r2SCAN-family jobs with an explicit kpoints= mesh select Anderson density mixing by default unless density_mixer= or convergence="off" is set. 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. smearing_method selects "fermi-dirac" (default), "methfessel-paxton" or "marzari-vanderbilt" (all implemented). 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. fock_mixing is the same knob on the fractional 0.0-1.0 scale; pass only one spelling. density_mixer / density_mixer_kerker expose the periodic Anderson/Broyden/Kerker API surface on the closed-shell multi-k GDF and RIJCOSX routes. The lower-level Ewald RKS drivers also support these mixers directly. Other routes fail closed on active requests instead of silently ignoring them or changing electrostatic gauge. Compact 3D closed-shell RKS/GDF SCAN/r2SCAN-family jobs with an explicit kpoints= mesh select Anderson density mixing by default unless density_mixer= or convergence="off" is set. 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. smearing_method selects "fermi-dirac" (default), "methfessel-paxton" or "marzari-vanderbilt" (all implemented). 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.

  • solver (str) – Diagonalisation solver. "dense" (default) uses NumPy/ScaLAPACK dense eigh. "davidson" uses the block-Davidson iterative solver (opts.use_davidson = True). "lobpcg" also sets use_davidson = True; the Python SCF loop then detects the LOBPCG preference and dispatches through the Python solver stack instead of dense or Davidson diagonalisation.

  • 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])

  • rsgdf_ke_cutoff (float)

  • rsgdf_tail_ke_cutoff (Optional[float])

  • mdf_ke_cutoff (float)

  • aiccm_backend (str)

  • aiccm_lattice_extension (Optional[Union[int, Sequence[int]]])

  • aiccm_wigner_seitz_shells (Optional[Union[int, Sequence[int]]])

  • aiccm_symmetry (str)

  • aiccm_symmetry_require_full_group (bool)

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

  • use_diis (bool)

  • convergence (Optional[str])

  • damping (Optional[float])

  • fmixing_percent (Optional[float])

  • fock_mixing (Optional[float])

  • density_mixer (Optional[str])

  • density_mixer_depth (int)

  • density_mixer_beta (float)

  • density_mixer_kerker (bool)

  • kerker_k0 (float)

  • kerker_strength (float)

  • kerker_cutoff_ha (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])

  • bz_integration (Optional[str])

  • 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)

  • memory_override (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)

  • bipole_cutoff_bohr (Optional[float])

  • bipole_nuclear_cutoff_bohr (Optional[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)

  • qvf_wannier_centers (bool)

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

  • checkpoint_every (int)

  • hessian_frozen_indices (Optional[List[int]])

  • band_structure (Optional['BandStructure'])

  • coop_cohp (bool)

  • tddft (bool)

  • tddft_n_states (int)

  • dos_kmesh (Optional[Sequence[int]])

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

  • atomic_spins (Optional[List[int]])

  • read_from (Optional[object])

  • spinlock (Optional[str])

  • spinlock_value (int)

  • spinlock_iterations (int)

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