vibeqc.run_periodic_job

vibeqc.run_periodic_job(system, basis, *, integral_engine=None, coulomb=None, exchange=None, periodic_integrals=None, periodic_xc=None, periodic_fitting=None, method='RHF', functional=None, orbital_optimizer='native', variant=None, scf_reference=None, correlation=None, jk_method='auto', cutoff_ha=300.0, aux_basis=None, gdf_method=None, rsgdf_ke_cutoff=None, rsgdf_tail_ke_cutoff=None, mdf_ke_cutoff=40.0, aiccm_backend='four_center', fit_source='auto', dlpno_ccsd_options=None, dlpno_thresholds=None, frozen_core=None, chi_support_policy=None, chi_coulomb_controls=None, chi_hf_reference=None, chi_reference_from=None, chi_reference_checkpoint=None, chi_correlation_resume=None, chi_correlation_checkpoint=None, chi_checkpoint_interval=1, chi_frozen_core=None, chi_auxiliary_batch_size=None, chi_cc_options=None, chi_xc_controls=None, chi_grid_options=None, chi_ks_reference=None, aiccm_lattice_extension=None, aiccm_wigner_seitz_shells=None, aiccm_symmetry='off', aiccm_symmetry_require_full_group=False, aiccm_allow_vacuum_padding=False, aiccm_cderi_storage=None, 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, conv_tol_grad=None, initial_guess='AUTO', write_molden_file=None, trexio=False, trexio_backend='hdf5', 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, iao_analysis=False, citations=True, dry_run=False, memory_override=False, gapw_molecular_limit=False, record_hostname=True, structured_log=False, progress=None, verbose=None, dispersion=None, dispersion_backend='auto', dispersion_cutoff_bohr=50.0, bipole_historical_domain=False, 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, fragments=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.

Explicit integral_engine=IntegralEngineOptions(backend="manta") selects finite 3D RHF/UHF or pure/global/range-separated LDA/GGA RKS/UKS with separate coulomb and exchange options and required periodic_integrals=PeriodicIntegralOptions(...) cutoffs. Explicit BUPO HF instead uses CoulombBuildOptions(algorithm="bupo") and matched PeriodicBupoIntegralOptions(...) AO/Ewald cubes and accuracy targets. KS also requires periodic_xc=PeriodicXCOptions(...). J uses algorithm=”exact”; K uses “exact” for HF/hybrids and “none” for pure KS. Fitted RHF/UHF instead requires explicit algorithm=”ri” for both J and K, a resolved auxiliary BasisSet in coulomb and periodic_fitting=PeriodicFittingOptions(...). This route supports full regular meshes, HCORE/AUTO, and use_diis=False. It retains the evaluated density in standard output and QVF, and refuses unsupported requests before SCF. See the MANTA manual for the source, budget, convergence and output contracts. 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", "UKS", or "aiccm" (case-insensitive). method="aiccm" is the front door of the experimental AICCM family: variant names the formulation, the SCF reference is inferred (see variant and scf_reference below), and the formulation runs on its own J/K route, so jk_method stays "auto" (any other value must equal that route, else a ValueError names both). Every AICCM job stamps [run].method_status = "experimental" plus aiccm_variant / aiccm_selector (plus aiccm_correlation when one was requested) into the .system manifest and keeps its experimental warning. See docs/user_guide/aiccm.md. 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). ROKS runs through Gamma-only GPW for pure DFT, or through BIPOLE at Gamma and on full Monkhorst-Pack meshes for pure and global-hybrid functionals. Unsupported backends, multi-k GPW ROKS, range-separated ROKS, 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"; with method="aiccm" its presence selects a Kohn-Sham reference.

  • variant (Optional[str]) – Required with method="aiccm", rejected otherwise. One of "real-gamma" (neutral Γ-CCM, real-Γ supercell representation; the former jk_method="real-gamma"), "neutral-bloch" (the same neutral torus Hamiltonian in its Bloch representation through the periodic.ccm.ri producer, not plain unit-cell GDF), "four-center" (the union-and-weight 2014 lineage), or "chi" (χ-CCM; the former jk_method="aiccm2026dev-b", with the aiccm_* keywords as its options). "gamma" / "gamma-ccm" are not variants (ruling R1). Every variant reads aiccm_lattice_extension for the BvK torus; kpoints stays an accepted alias for the torus mesh, never both.

  • scf_reference (Optional[str]) – With method="aiccm" only. None (default) infers the reference: functional decides HF versus KS, and the system is open-shell when system.multiplicity != 1 or the electron count is odd (unrestricted), else restricted – the parity rule the CCM library’s run_ccm_scf applies. "rhf" / "uhf" select a Hartree-Fock reference explicitly on every variant and reject a functional; "uhf" is mainly useful on a closed-shell singlet, which inference would run as RHF, and "rhf" on an odd electron count is refused by the closed-shell check. "rohf" / "roks" select the restricted open-shell references explicitly ("rohf" rejects a functional; "roks" requires one); whether the variant runs them is decided by that variant’s own guard (none does today).

  • aiccm_allow_vacuum_padding (bool) – With method="aiccm" and variant="real-gamma" or "neutral-bloch" only. The neutral producers refuse a cell declared 3-D whose atom positions leave an empty slab above 25 bohr along a lattice direction (the measured-dimensionality guard, IID 291). True runs it anyway as a warned, recorded vacuum-parameter study (ruling R6, 2026-09-10): an AICCMVacuumPaddingWarning names the padded directions, the .out header prints allow_vacuum_padding = True, and the .system manifest records aiccm_allow_vacuum_padding and aiccm_vacuum_padded_axes (1-based lattice directions). Refused on four-center and chi, which carry no such guard, and with any other method. The positive-converged-energy refusal is not relaxed by it.

  • aiccm_cderi_storage (Optional[str]) – With method="aiccm" and variant="real-gamma" only (#519, RG-6). "dense" (what None runs) holds the supercell cderi, whose memory grows as the cube of the torus size; "block" holds one block per transfer of the block-circulant torus and "block-star" only the fits of the k-pair star plan. The three are one operator, so the energy and the neutral-source identity do not depend on the choice; the .system manifest records cderi_storage_executed. Not combinable with correlation=, whose treatments read the dense array.

  • correlation (Optional[str]) – With method="aiccm" only, and optional: None (default) is an SCF-only run. "mp2", "ccsd", "dlpno-mp2" and "dlpno-ccsd" add a post-HF treatment on top of the variant’s SCF. "mp2" and "ccsd" are wired on variant="four-center" and variant="real-gamma"; the two DLPNO treatments are "real-gamma" only, because DLPNO screens on a fitted reference and the bare four-centre operator has no RI decomposition. At their default zero truncations the DLPNO routes reproduce the canonical ones on the same reference to machine precision. "ccsd" and "dlpno-ccsd" are CCSD(T), and their citation keys record whether the triples actually ran. Open-shell clusters take the u siblings of every route automatically; the one refusal is "ccsd" on variant="four-center", whose only open-shell driver is neutral-only and so cannot build that arm’s reference. The driver is chosen to MATCH the construction the SCF ran, never to substitute another one, so each arm cites its own lineage: four-center takes the bare run_ccm_mp2 / run_ccm_ump2 (aiccm2026dev-a-mp2) and real-gamma the neutral-RI correlation (aiccm2026dev-a-ri-mp2). They never share a citation row – handing a union-and-weight SCF to a neutral-RI driver would return a different construction’s number (ruling R1). Both consume the SCF the front door already converged rather than building a second one. neutral-bloch refuses because its reference is the per-k Bloch representation while the drivers work in real-Gamma supercell space; the refusal names real-gamma as the exact substitute (same Hamiltonian, ruling R1). chi admits experimental same-source MP2 with explicit classic/sr, UMP2 and ROHF Knowles RMP2 with classic, and RHF CCSD(T) or UHF UCCSD(T) with classic. The UHF triples use the canonical spin-orbital definition documented in the chi manual; ROHF and SR CC remain unsupported. chi_cc_options selects CC controls and compute_triples=False there selects CCSD only. These source capabilities remain experimentally admitted and not numerically qualified. They require RI and physical Coulomb controls, conv_tol_energy <= 1e-11 and conv_tol_grad <= 1e-9. chi_frozen_core and chi_auxiliary_batch_size select the library’s per-character frozen counts and factor panels. A KS reference refuses because MP2 needs an HF one. The bare four-centre drivers form the dense n_ref_ao**4 AO tensor, so that arm is a small-cluster tool: no dimensionality guard, but size the torus deliberately. See docs/user_guide/aiccm.md.

  • chi_reference_from (str | os.PathLike | None) – Read a validated persistent classic chi RHF/UHF/ROHF reference or save the accepted reference to the exact supplied path (conventionally .vqr). Restoring verifies the retained source and stationary state; it never reruns SCF or refits factors. Numerical request controls must match. Mutually exclusive with legacy restart_from/read_from.

  • chi_reference_checkpoint (str | os.PathLike | None) – Read a validated persistent classic chi RHF/UHF/ROHF reference or save the accepted reference to the exact supplied path (conventionally .vqr). Restoring verifies the retained source and stationary state; it never reruns SCF or refits factors. Numerical request controls must match. Mutually exclusive with legacy restart_from/read_from.

  • chi_correlation_resume (str | os.PathLike | None) – Resume or publish canonical classic chi MP2/RMP2/CCSD(T) progress. Resume requires chi_reference_from or chi_hf_reference. Reference and correlation archives require distinct paths. Without a new output path, resume updates its input archive. The positive integer interval counts MP2 work units, CC iterations, or streamed triples work units; complete results are always published. These options require a single-point admitted HF calculation and preserve all source gates. See docs/chi_restart.md for identity and compatibility rules.

  • chi_correlation_checkpoint (str | os.PathLike | None) – Resume or publish canonical classic chi MP2/RMP2/CCSD(T) progress. Resume requires chi_reference_from or chi_hf_reference. Reference and correlation archives require distinct paths. Without a new output path, resume updates its input archive. The positive integer interval counts MP2 work units, CC iterations, or streamed triples work units; complete results are always published. These options require a single-point admitted HF calculation and preserve all source gates. See docs/chi_restart.md for identity and compatibility rules.

  • chi_checkpoint_interval (int) – Resume or publish canonical classic chi MP2/RMP2/CCSD(T) progress. Resume requires chi_reference_from or chi_hf_reference. Reference and correlation archives require distinct paths. Without a new output path, resume updates its input archive. The positive integer interval counts MP2 work units, CC iterations, or streamed triples work units; complete results are always published. These options require a single-point admitted HF calculation and preserve all source gates. See docs/chi_restart.md for identity and compatibility rules.

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

  • structured_log (Union[bool, str, os.PathLike, None]) – Optional NDJSON (one-JSON-record-per-line) log capturing every SCF transition – banner, job_start, memory_estimate, per-iter rows, scf_converged, properties, job_end. Off by default. Pass True to emit {output}.scf.jsonl, a path-like to write there explicitly, or set the VIBEQC_STRUCTURED_LOG=path env var (which wins when structured_log is left at False). When neither is given and $VQ_WORKDIR is set (a vq job), the log is auto-enabled at {output}.scf.jsonl. The format is stable: events are append-only, fields are never renamed or removed. See vibeqc.structured_log for the full event catalog. Resolved exactly as in vibeqc.run_job() (one shared resolver, #384). The basis-free periodic semiempirical routes write no structured log, so an explicit True or path is refused there before calculation.

  • 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_historical_domain (bool) – False (default) selects physical pair support for BIPOLE RHF/UHF/RKS/UKS. True reproduces historical index-ball support, which is not invariant under atom-image relabelling. Rejected when that BIPOLE route is inactive. Generic native lattice defaults and other methods are unchanged.

  • 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. A home-only short-range image list is valid for the 3D Ewald split: its reciprocal term still supplies periodic coupling. Converge both halves of the split; the number of short-range images alone does not determine whether the Hamiltonian is periodic. Other backends have route-specific image semantics. 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. A home-only short-range image list is valid for the 3D Ewald split: its reciprocal term still supplies periodic coupling. Converge both halves of the split; the number of short-range images alone does not determine whether the Hamiltonian is periodic. Other backends have route-specific image semantics. 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)

  • orbital_optimizer (str)

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

  • cutoff_ha (float)

  • gdf_method (Optional[str])

  • rsgdf_ke_cutoff (Optional[float])

  • rsgdf_tail_ke_cutoff (Optional[float])

  • mdf_ke_cutoff (float)

  • aiccm_backend (str)

  • fit_source (str)

  • dlpno_ccsd_options (Optional[object])

  • dlpno_thresholds (object)

  • frozen_core (object)

  • chi_support_policy (str | None)

  • chi_frozen_core (int | tuple[int, int] | None)

  • chi_auxiliary_batch_size (int | None)

  • chi_cc_options (object | None)

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

  • conv_tol_grad (float | None)

  • initial_guess (Union[str, InitialGuess])

  • write_molden_file (bool | None)

  • trexio (bool | str | os.PathLike)

  • trexio_backend (str)

  • write_density (bool | None)

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

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

  • fragments (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 (Union[str, InitialGuess]) – Initial-guess selector. "AUTO" is the default; "SAD", "HCORE", "SAP", "PATOM", "HUECKEL", "MINAO", and "READ" are available where supported by the selected method and periodic Coulomb route. Unsupported combinations fail before SCF instead of silently changing the guess. AUTO resolution is variant-aware: method="aiccm" with variant="real-gamma" additionally accepts READ from an in-memory target-supercell density/reference through read_from (no file or geometry projection). Both "real-gamma" and "four-center" resolve AUTO to "HCORE", their default density construction. Passing initial_guess="SAD" to those two variants explicitly still fails before SCF – the default moves, a request never does (#692).

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

  • trexio (bool | str | os.PathLike) – Write the periodic Gaussian SCF wavefunction, including all k-point and spin blocks, lattice and applied scalar ECP parameters. True selects {output}.trexio.h5 (HDF5) or {output}.trexio (text); a path selects an explicit target. Requires the optional trexio extra. See TREXIO wavefunction files.

  • trexio_backend (str) – Write the periodic Gaussian SCF wavefunction, including all k-point and spin blocks, lattice and applied scalar ECP parameters. True selects {output}.trexio.h5 (HDF5) or {output}.trexio (text); a path selects an explicit target. Requires the optional trexio extra. See TREXIO wavefunction files.

  • iao_analysis (bool) – Reserved for periodic IAO populations. True explicitly raises before calculation until k-point and lattice bond conventions are implemented.

  • 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 | None) – Emit {output}.xsf with the SCF density on a primitive-cell grid (XSF works for any lattice; cube is orthorhombic-only). The artefact evaluates a real-space lattice density, or the exact Gamma block of a Gamma-only mesh. On a true multi-k mesh the plain Gaussian routes (gdf, rijcosx, gpw) return per-k Bloch blocks only, and a lattice density is not reconstructed from them: an explicit True there is refused before the SCF rather than after it (#679). bipole and every method="aiccm" variant carry a lattice density at any mesh. None is capability-aware auto mode, True is a guaranteed request, and False (the default) disables it.

  • density_spacing_bohr (float) – Grid spacing for the XSF density and the QVF density volume. Default 0.2 bohr. The QVF volume is written only if its grid sum over the primitive cell matches the cell’s electron count within 0.005 electrons. All-electron cores of second-row and heavier atoms are too compact for a 0.2-bohr grid to integrate: Ne/STO-3G in a 7-bohr cube gives 11.98 instead of 10 electrons at 0.2 bohr and 10.00002 at 0.05 bohr. The volume is then omitted and the error is recorded under volume.density; refine the spacing to get it.

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

  • orbital_optimizer (str)

  • variant (Optional[str])

  • scf_reference (Optional[str])

  • correlation (Optional[str])

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

  • cutoff_ha (float)

  • aux_basis (Optional[str])

  • gdf_method (Optional[str])

  • rsgdf_ke_cutoff (Optional[float])

  • rsgdf_tail_ke_cutoff (Optional[float])

  • mdf_ke_cutoff (float)

  • aiccm_backend (str)

  • fit_source (str)

  • dlpno_ccsd_options (Optional[object])

  • dlpno_thresholds (object)

  • frozen_core (object)

  • chi_support_policy (str | None)

  • chi_reference_from (str | os.PathLike | None)

  • chi_reference_checkpoint (str | os.PathLike | None)

  • chi_correlation_resume (str | os.PathLike | None)

  • chi_correlation_checkpoint (str | os.PathLike | None)

  • chi_checkpoint_interval (int)

  • chi_frozen_core (int | tuple[int, int] | None)

  • chi_auxiliary_batch_size (int | None)

  • chi_cc_options (object | None)

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

  • aiccm_allow_vacuum_padding (bool)

  • aiccm_cderi_storage (Optional[str])

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

  • conv_tol_grad (float | None)

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

  • structured_log (Union[bool, str, os.PathLike, None])

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

  • verbose (Optional[int])

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

  • dispersion_backend (str)

  • dispersion_cutoff_bohr (float)

  • bipole_historical_domain (bool)

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

  • fragments (Optional[object])

  • spinlock (Optional[str])

  • spinlock_value (int)

  • spinlock_iterations (int)

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