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, dynamic_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=None, 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=None, citations=True, dry_run=False, memory_override=False, gapw_molecular_limit=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, bipole_exact_zone_bohr=None, sr_image_precision=1e-06, sr_range_screening=False, 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=None, symmetry_reduce_k=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)

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. ROHF/GDF is available by explicit backend selection at Gamma and on a full Monkhorst-Pack mesh. 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.

Warning

kpoints=(N, N, N) builds the Gamma-centred mesh {0, 1/N, ..., (N-1)/N} per axis. ASE/GPAW read the same-looking argument as the classical shifted mesh, offset by half a step. The two agree exactly for odd N and are disjoint for even N (measured 2026-08-02: (3,3,3)/(5,5,5) share every point, (2,2,2)/(4,4,4)/(6,6,6) share none), so a cross-code comparison validated at an odd mesh can still be sampling a different Brillouin zone at an even one. The resolved convention and k-point count are printed in the .out; pass VIBEQC_OUTPUT_LEVEL=verbose for the full k-list.

Parameters:

• system (PeriodicSystem) – Periodic system + AO basis. For basis-free periodic semiempirical methods (dftb0, scc_dftb, gfn2_xtb, pm6, om1, om2, om3), pass basis=None; the runner dispatches before any Gaussian-basis setup.

• basis (Optional[BasisSet]) – Periodic system + AO basis. For basis-free periodic semiempirical methods (dftb0, scc_dftb, gfn2_xtb, pm6, om1, om2, om3), pass basis=None; the runner dispatches before any Gaussian-basis setup.

• method (str) – "RHF", "ROHF", "ROKS", "UHF", "RKS" or "UKS". Periodic ROHF/ROKS are maintained-preview 3D routes: ROHF runs on native GDF at Gamma or on full Monkhorst-Pack meshes (jk_method="gdf"), on Gamma-only GPW (jk_method="gpw"), or on the BIPOLE-route corrected-Ewald-exchange EWALD_3D engine (jk_method="bipole" – the AUTO default for ROHF – at Gamma and on full Monkhorst-Pack meshes), while pure-DFT ROKS is GPW-only (Gamma or true multi-k). Unsupported backends, hybrids on the multi-k ROKS route, smearing, gradients, and response properties fail closed. Closed-shell RHF / RKS default to the Gamma or multi-k GDF path depending on kpoints. With jk_method="bipole"`, the RHF/ROHF/RKS/UHF/UKS 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, compute COOP and COHP bonding analysis and embed dos.coop + dos.cohp sections in the QVF archive. Requires output_qvf=True: the archive is the analysis’s only sink, so coop_cohp=True with output_qvf=False raises ValueError before SCF rather than silently skipping the analysis. 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.

• gapw_molecular_limit (bool) – Declare that jk_method="gapw" is describing an isolated molecule or atom in a vacuum-padded single-Gamma cell. Required for RHF/UHF so the method-aware one-centre default can select the validated fit-free analytic augmentation without guessing from geometry. Compact crystals should use GDF or BIPOLE. Rejected for RKS/UKS, whose method-aware default remains the block DFT functional. High-level GAPW HF geometry/cell optimization and Hessians fail closed until derivatives of the same fit-free energy are implemented.

• 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. Corrected-gauge RHF/RKS/UHF/UKS runs measure Bloch-overlap fold drift before the first Fock build. Drift above 1e-2 is the established unreliable-support regime and raises before SCF; increase this cutoff until the reported drift is below 1e-4 for quantitative work. Intermediate drift retains a truncation note. These controls 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. Corrected-gauge RHF/RKS/UHF/UKS runs measure Bloch-overlap fold drift before the first Fock build. Drift above 1e-2 is the established unreliable-support regime and raises before SCF; increase this cutoff until the reported drift is below 1e-4 for quantitative work. Intermediate drift retains a truncation note. These controls 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])

• dynamic_damping (Optional[bool])

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

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

• 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_exact_zone_bohr (Optional[float])

• sr_image_precision (Optional[float])

• sr_range_screening (bool)

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

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

dynamic_damping is a χ-CCM-B-only override. None preserves that selector’s option default, while False disables adaptive damping updates. Supplying it explicitly with any other jk_method fails closed. It is separate from the generic convergence="auto" explicit-knob detection; χ-CCM-B campaign callers pin their generic convergence controls independently. 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), "mermin" (Mermin finite-temperature free-energy functional), "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. dynamic_damping is a χ-CCM-B-only override. None preserves that selector’s option default, while False disables adaptive damping updates. Supplying it explicitly with any other jk_method fails closed. It is separate from the generic convergence="auto" explicit-knob detection; χ-CCM-B campaign callers pin their generic convergence controls independently. 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), "mermin" (Mermin finite-temperature free-energy functional), "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. dynamic_damping is a χ-CCM-B-only override. None preserves that selector’s option default, while False disables adaptive damping updates. Supplying it explicitly with any other jk_method fails closed. It is separate from the generic convergence="auto" explicit-knob detection; χ-CCM-B campaign callers pin their generic convergence controls independently. 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), "mermin" (Mermin finite-temperature free-energy functional), "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 | None) – Emit {output}.molden of the Γ-point MOs (using the unit-cell molecule + basis as the molecular target). None (the default) enables it for exact single-Γ Gaussian-basis SCF routes and for Gamma-containing BIPOLE/GDF meshes whose result metadata locates that block. It is inapplicable for basis-free and shifted meshes. Explicit True on an inapplicable route fails before calculation.

• write_population_file (bool | None) – Emit the population-summary text/JSON pair. Exact single-Γ routes use the molecular analysis; multi-k BIPOLE uses its lattice-density population and χ-CCM uses its finite-torus population. None is capability-aware auto mode, True is a guaranteed request, and False disables the pair.

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

• dynamic_damping (Optional[bool])

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

• citations (bool)

• dry_run (bool)

• memory_override (bool)

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

• bipole_exact_zone_bohr (Optional[float])

• sr_image_precision (Optional[float])

• sr_range_screening (bool)

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

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