ELECTRONS
References: Zhang2026
Settings for the electronic potentiostat driving a constant-potential / Ne-electrode MD run. [Edit on GitHub]
Keywords
Keyword descriptions
SECTION_PARAMETERS
Type: logical
Default: F
Lone keyword: T
Usage: &ELECTRONS T
Description: Controls the activation of the electronic potentiostat. There are three states, not two. Section ABSENT: nothing happens, no .cpcont file. Section present with T (or 1): full constant-potential dynamics – q is propagated by the potentiostat, requires ENSEMBLE NVT or LANGEVIN. Section present with 0 (or F): REPORT-ONLY – an ordinary MD run that additionally computes the Fermi level and work function every step and writes the .cpcont file, with q held at the system’s electron count and TARGET_WORKFUNCTION reported as 0. Report-only needs only POTENTIAL_AVERAGE_AXIS and POTENTIAL_AVERAGE_REGION, works under any ensemble, and requires a plain FORCE_EVAL (not METHOD MIXED). Use it to measure the work function of a fixed-charge system – for example to find the neutral work function before choosing TARGET_WORKFUNCTION and Q_INIT for a constant-potential run. [Edit on GitHub]
CHARGE_MIXING
Type: logical
Default: F
Lone keyword: T
Usage: CHARGE_MIXING T
Description: Use dual integer-endpoint charge mixing (CP2K METHOD MIXED LINEAR_COMBINATION over two integer-charge FORCE_EVAL sections) instead of the Ne-electrode core correction. Q_INIT is the initial mixing coordinate q. NEUTRAL_ELECTRONS is REQUIRED here, contrary to what an earlier version of this text said: it sets the CHARGE of every rebuilt endpoint via NINT(neutral_electrons) - N, and defines the reference point of the grand-canonical potential. [Edit on GitHub]
CHARGE_MIXING_INPLACE
Type: logical
Default: F
Lone keyword: T
Usage: CHARGE_MIXING_INPLACE T
Description: At a boundary crossing, mutate the stale endpoint’s electron count IN PLACE instead of tearing it down and re-running qs_init. Only the electron count of the existing endpoint is changed. The converged wavefunction, the dispersion neighbour lists, pw_env and the atomic distributions all survive, so a crossing no longer cold-starts an SCF. Strongly recommended; FALSE only to fall back to the original rebuild path for comparison. [Edit on GitHub]
CHARGE_MIXING_SPAN
Type: integer
Default: 1
Usage: CHARGE_MIXING_SPAN 1
Description: Integer span S between the two mixed FORCE_EVAL endpoints: N_lo=S*floor(q/S), N_hi=N_lo+S. Only used when CHARGE_MIXING is TRUE. S=2 keeps the endpoint parity fixed, which UKS with an explicit MULTIPLICITY requires. With CHARGE_MIXING_INPLACE, ADDED_MOS must cover every endpoint the run reaches (each crossing moves one by S). [Edit on GitHub]
CURRENT_FERMI_LEVEL
Type: real
Default: 0.00000000E+000
Usage: CURRENT_FERMI_LEVEL 0.0
Description: Last Fermi level in eV. Restart bookkeeping only: it is recomputed from the density at the first force evaluation, and exists so that the .cpcont column is meaningful on the restart step itself. [Edit on GitHub]
CURRENT_WORKFUNCTION
Type: real
Default: 0.00000000E+000
Usage: CURRENT_WORKFUNCTION 0.0
Description: Last work function in eV. Restart bookkeeping only, as for CURRENT_FERMI_LEVEL: md_run.F recomputes it at the initial force evaluation before the first electronic kick. [Edit on GitHub]
LAMBDA
Type: real
Default: 1.79769313E+308
Usage: LAMBDA 0.5
Description: Freeze the mixing weight at this value instead of deriving it from q. When given: q(t) is NOT propagated, the potentiostat is inactive, and the endpoints are never rebuilt – the run becomes ordinary MD on the fixed combination (1-LAMBDA)E(N_lo) + LAMBDAE(N_hi) of the two integer-charge FORCE_EVALs, with N_lo/N_hi exactly as the input CHARGE keywords built them. Intended as a control experiment: it separates the charge mixing from the constant-potential dynamics. A run with LAMBDA set contains no constant-potential physics at all. [Edit on GitHub]
MASS
Type: real
Default: 4.00000000E+002
Usage: MASS 400.0
Description: Fictitious mass of the electron-count degree of freedom, in atomic units. Plain number, not unit-converted. [Edit on GitHub]
NEUTRAL_ELECTRONS
Type: real
Default: 1.32900000E+003
Usage: NEUTRAL_ELECTRONS 1329.0
Description: Reference (neutral-system) total electron count. Must match the actual DFT electron count of the simulated system – there is no physically meaningful universal default. Plain number, not unit-converted. [Edit on GitHub]
POTENTIAL_AVERAGE_AXIS
Type: enum
Default: Z
Usage: POTENTIAL_AVERAGE_AXIS Z
Description: Lattice axis along which the planar Hartree-potential average is computed for the work-function readback. [Edit on GitHub]
Valid values:
Xaverage along the x axisYaverage along the y axisZaverage along the z axis
POTENTIAL_AVERAGE_REGION
Type: real[2]
Default: [angstrom]
Usage: POTENTIAL_AVERAGE_REGION 27.0 30.0
Description: Minimum and maximum coordinate, along POTENTIAL_AVERAGE_AXIS, of the vacuum region over which the Hartree potential is averaged to obtain the work function. [Edit on GitHub]
POTENTIOSTAT_ENERGY
Type: real
Default: 0.00000000E+000
Usage: POTENTIOSTAT_ENERGY 0.0
Description: Accumulated heat exchanged with the electronic potentiostat, in atomic units, for conserved-quantity bookkeeping across restarts. Written automatically into restart files. [Edit on GitHub]
P_INIT
Type: real
Default: 0.00000000E+000
Usage: P_INIT 0.0
Description: Initial (or restarted) momentum conjugate to the electronic coordinate q, in atomic units. Normally left at zero for a fresh run and written automatically into restart files. [Edit on GitHub]
Q_INIT
Type: real
Default: 1.32900000E+003
Usage: Q_INIT 1329.0
Description: Initial value of the potentiostat’s electron-count variable q. Normally equal to NEUTRAL_ELECTRONS for a neutral start. Plain number, not unit-converted. [Edit on GitHub]
TARGET_FERMI_LEVEL
Type: real
Default: 1.79769313E+308
Usage: TARGET_FERMI_LEVEL -0.5
Description: Target Fermi level in eV. Setting this switches the potentiostat from work-function control to FERMI-LEVEL control: the generalized force becomes (TARGET_FERMI_LEVEL - current Fermi level) instead of (current work function - TARGET_WORKFUNCTION), and the grand-canonical potential becomes E - e_F_target*(q - N_neutral). TAKES PRECEDENCE over TARGET_WORKFUNCTION when both are present, so a restart file written in work-function mode can be switched to Fermi control by adding this one keyword. The two modes are NOT interchangeable: they differ by the vacuum level, whose derivative with respect to q is not zero for a charged slab, so holding one constant does not hold the other constant. Unset by default (sentinel HUGE). REFERENCE: this is an ABSOLUTE Kohn-Sham eigenvalue on CP2K’s internal energy scale, NOT a shift relative to the neutral cell. In a periodic cell the G=0 Hartree term is set to zero, so that scale is referenced to the CELL-AVERAGE electrostatic potential: not to vacuum, and not to the Fermi level of the neutral system. To target a potential a known amount away from the neutral cell, first run the neutral cell once, read its Fermi level e_F(N0) from the output, and set TARGET_FERMI_LEVEL = e_F(N0) + your shift. [Edit on GitHub]
TARGET_WORKFUNCTION
Type: real
Default: 5.00000000E+000 [eV]
Usage: TARGET_WORKFUNCTION [eV] 4.81
Description: Target work function the potentiostat drives toward. Accepts CP2K’s usual [unit] qualifier, e.g. TARGET_WORKFUNCTION [eV] 4.81 or [hartree] 0.1768; a bare number is read as eV, so existing input decks are unaffected. The value is stored in atomic units and converted back to eV in md_run.F, because the potentiostat works in eV throughout. [Edit on GitHub]
TAU_POTENTIOSTAT
Type: real
Default: 2.00000000E+002
Usage: TAU_POTENTIOSTAT 200.0
Description: Langevin relaxation time of the electronic potentiostat, in femtoseconds. Plain number, not unit-converted. [Edit on GitHub]
TEMP_POTENTIOSTAT
Type: real
Default: 3.00000000E+002
Usage: TEMP_POTENTIOSTAT 300.0
Description: Target temperature of the electronic potentiostat Langevin thermostat, in kelvin. Plain number, not unit-converted. Set to 0.0 to disable stochastic noise (deterministic/damped dynamics only). [Edit on GitHub]