7.2.1.4.3. ipodcoupling

Computes an electronic coupling between two, real, neighbor-list segments via POD2 (Projection Operator Diabatization), on a single, real, converged ground-state DFT calculation of the H-saturated supermolecule assembled from them – mirrors IQM’s own overall workflow (mapping, saturation-eligibility, H-saturation, relaxation, DFT), then hands off to PODCoupling for the actual coupling itself, instead of IQM’s own dftcoupling/bsecoupling. See podcoupling.xml’s own help text for the underlying POD2 method itself. The following table contains the defaults input options for the calculator, The default OPTIONAL means this option is switched off, if no input is given. REQUIRED arguments have to be specified, otherwise an error is thrown.

Property Name	Default Value	Description	Valid Input
job_file	ipodcoupling.jobs	name of jobfile to which jobs are written
map_file	votca_map.xml	xml file with segment definition
tasks	input,dft,parse,podcoupling	tasks to perform during calculation	[input dft parse podcoupling]
dftpackage.name	xtp	Name of the DFT package	xtp orca
dftpackage.charge	0	Molecular charge	int
dftpackage.spin	1	Molecular multiplicity	int+
dftpackage.basisset	def2-tzvp	Basis set for MOs
dftpackage.auxbasisset	OPTIONAL	Auxiliary basis set for RI
dftpackage.externalfield	OPTIONAL	Field given in x y z components
dftpackage.executable	OPTIONAL	Path to executable for dftpackage
dftpackage.ecp	OPTIONAL	Effective Core Potentials for DFT Calculations
dftpackage.optimize	false	Perform a molecular geometry optimization	bool
dftpackage.functional	XC_HYB_GGA_XC_PBEH	Exchange correlation functional used. You can also specify an exchange and a correlation functional
dftpackage.scratch	/tmp/qmpackage	path to the scratch folder
dftpackage.polarization	false	Calculate polarisation	bool
dftpackage.dipole_spacing	0.1	Spacing for splitting multipoles into charges	float+
dftpackage.temporary_file	temp	Filename for temporary files without extension
dftpackage.convergence_tightness	tight	How accurate the dft self-consistency has to be	low normal tight verytight
dftpackage.cleanup		files to remove after the calculation. Specify the fileextensions
dftpackage.initial_guess	atom	Method to use to make initial guess, independent(electrons) or atom(densities) or previous calculation keyword orbfile or dimer_guess (combine two monomer .orb files of independently arbitrary charge/spin – see dimer_guess_orbA/orbB below)	independent atom orbfile huckel huckel_dft dimer_guess
dftpackage.dimer_guess_orbA		Path to monomer A’s own, already-converged .orb file – only read when initial_guess=dimer_guess. Monomer A’s atoms must be an exact internal-geometry match (bond lengths/angles, NOT absolute position – translation/rotation between the standalone monomer and its placement in the dimer is expected and fine) for the first N_A atoms of this calculation’s own molecule.
dftpackage.dimer_guess_orbB		Same as dimer_guess_orbA, for monomer B – expected to match this calculation’s own remaining atoms (after monomer A’s own N_A atoms).
dftpackage.orca		orca specific keywords can be added here, where the xml tag corresponds to the option and the value to the option’s value
dftpackage.xtpdft.dft_in_dft.activeatoms		Indices of atoms in active region
dftpackage.xtpdft.dft_in_dft.threshold	0.4	Mulliken population above which orbital is considered in the active region
dftpackage.xtpdft.dft_in_dft.levelshift	10000.0	Levelshift energy for the projection operator
dftpackage.xtpdft.dft_in_dft.truncate_basis	false	Truncate the basis-set to active atoms only	bool
dftpackage.xtpdft.dft_in_dft.truncation_threshold	1e-4	Threshold to convert an inactive atom to a border atom	float+
dftpackage.xtpdft.screening_eps	1e-9	screening eps	float+
dftpackage.xtpdft.fock_matrix_reset	5	how often the fock matrix is reset	int+
dftpackage.xtpdft.integration_grid	medium	vxc grid quality	xcoarse coarse medium fine xfine
dftpackage.xtpdft.force_uks_path	false	forcing UKS path	bool
dftpackage.xtpdft.compute_forces	false	Compute analytic ground-state DFT nuclear forces (RI, and hybrid-exchange for UKS) and store them in the orb (HDF5) file. Adds real cost to every converged SCF, so this is opt-in.	bool
dftpackage.xtpdft.cdft.enabled	false	Enable a CDFT charge constraint on this calculation	bool
dftpackage.xtpdft.cdft.indices		Indices of atoms in the constrained fragment (0-based), using the same range syntax already used for diabatization.xml’s own fragment indices, e.g. ‘1 3 13:17’
dftpackage.xtpdft.cdft.charge	0.0	Target charge on the fragment, RELATIVE to its neutral reference state (the sum of the fragment atoms’ own nuclear charges) – e.g. +1.0 means one electron REMOVED from the fragment (a cation), -1.0 means one electron ADDED (an anion). Converted internally to an absolute target electron count once, at setup time.	float
dftpackage.xtpdft.cdft.initial_lambda	0.0	Initial guess for the Lagrange multiplier lambda, used as the center of the outer loop’s own bisection bracket	float
dftpackage.xtpdft.cdft.population_tolerance	1e-4	Outer-loop convergence criterion: the CDFT calculation is considered converged once the achieved fragment population is within this many electrons of the target	float+
dftpackage.xtpdft.cdft.max_iterations	50	Maximum number of outer (Lagrange-multiplier, bisection) iterations – each one is a full, warm-started inner SCF	int+
dftpackage.xtpdft.cdft.guess_strategy	warmstart	How each outer bisection trial’s own inner SCF is started, after the very first trial. ‘warmstart’ (default) reuses the immediately PRECEDING trial’s own converged MOs (initial_guess is forced to ‘orbfile’ internally) for every subsequent trial – usually helps, since consecutive lambda values are often close. ‘fresh’ instead re-uses the calculation’s own original, top-level initial_guess setting for every trial, never warm-starting from a previous lambda’s own MOs at all – worth trying if warm-starting itself seems to be part of a convergence difficulty (e.g. if consecutive lambda trials correspond to substantially different electronic structures, a previous trial’s own converged density could be a worse starting point than a fresh guess, not a better one).	warmstart fresh
dftpackage.xtpdft.convergence.energy	1E-7	DeltaE at which calculation is converged	float+
dftpackage.xtpdft.convergence.method	DIIS	Main method to use for convergence accelertation	DIIS mixing
dftpackage.xtpdft.convergence.DIIS_start	0.002	DIIS error at which DIIS takes over	float+
dftpackage.xtpdft.convergence.ADIIS_start	0.8	DIIS error at which ADIIS takes over	float+
dftpackage.xtpdft.convergence.DIIS_length	20	old hamiltonians to keep in history	int+
dftpackage.xtpdft.convergence.DIIS_maxout	false	if true remove the maximum element in the history if DIIS_length is exceeded.Otherwise, the oldest element is removed.	bool
dftpackage.xtpdft.convergence.levelshift	0.0	levelshift to apply to hamiltonian	float+
dftpackage.xtpdft.convergence.levelshift_end	0.2	DIIS error at levelshifting is disabled	float+
dftpackage.xtpdft.convergence.max_iterations	100	max iterations to use	int+
dftpackage.xtpdft.convergence.error	1e-7	convergence error	float+
dftpackage.xtpdft.convergence.mixing	0.7	mixing parameter for linear mixing of density matrices	float+
dftpackage.xtpdft.convergence.mixing_end	0.8	DIIS error below which mixing is disabled – independent of ADIIS_start (see ORCA’s own DampErr, kept independent of DIISStart for the same reason: difficult systems benefit from keeping mixing active well past the point where ADIIS/DIIS themselves start being tried, not exactly until that same point). Defaults to match ADIIS_start’s own default (0.8) for backward compatibility – existing configurations see identical behavior unless this is set explicitly.	float+
dftpackage.xtpdft.convergence.mixing_max	0.98	Ceiling mixing can adaptively ramp up toward as the SCF struggles (see consecutive ADIIS failures), rather than staying fixed at the base mixing value for an entire run. Matches ORCA’s own DampMax (default 0.98, confirmed directly from a real ORCA log’s own resolved SCF settings) – ORCA ramps its own damping factor from a base (DampFac, 0.7 by default) up to this ceiling only when actually needed, rather than paying the cost of heavy damping throughout.	float+
dftpackage.xtpdft.convergence.davidson_max_iter	50	Maximum iterations for the Davidson eigensolver used by the direct-minimization (augmented-Hessian) fallback, engaged when ADIIS/DIIS themselves are struggling. A genuinely difficult system (e.g. a strong constraint spanning a large fragment) can leave this solver still short of its own convergence tolerance at the default – confirmed directly, from a real run, that the previous, hardcoded 50 was not always enough. Not CDFT-specific: this fallback can also engage for an ordinary, non-CDFT UKS calculation.	int+
store_dft	false	If true, writes the converged orb file (the full, H-saturated supermolecule) to disk after the DFT step	bool
include_linkers	false	If true, looks for real, actual linker segments genuinely, covalently connecting the two, real, neighbor-list segments (via Topology::FindLinkingSegments, real bond connectivity only – no segment-type whitelist at all, unlike IQM’s own linker_names), PBC-correctly positions them, and includes them in the supermolecule – their own atoms belong to NEITHER fragment_A_atoms nor fragment_B_atoms in the resulting PODCoupling calculation. Default off, matching IQM’s own default-off linker behavior.	bool
podcoupling.levA	1	Number of orbitals to cover for fragment A, counting outward from its own HOMO/LUMO boundary, covering BOTH occupied (hole-transport) and virtual (electron-transport) orbitals together in one calculation – same convention as DFTcoupling’s own levA/podcoupling.xml’s own levA exactly. 1 covers just {HOMO, LUMO}; 2 covers {HOMO-1, HOMO, LUMO, LUMO+1}; etc.	int+
podcoupling.levB	1	Same as levA, for fragment B	int+

Note

An xml file containing the defaults for the ipodcoupling calculator can be created via -p ipodcoupling -o FILENAME command line options `