REFERENCE_CLI

Run the native tblite command line interface as a reference for CP2K/tblite energies, nuclear gradients, and optionally virials. The section is a lone section: if it is present, the reference check is enabled. By default the native CLI calculation inherits the CP2K/tblite method, PARAM file, ACCURACY, charge, spin state, spin-polarized Hamiltonian setting, electronic temperature, TBLITE_MIXER/ITERATIONS, and TBLITE_MIXER/SOLVER from the surrounding input. CP2K forwards DFT/UKS, including its LSD and SPIN_POLARIZED aliases, as native tblite –spin-polarized; DFT/MULTIPLICITY is forwarded separately as –spin. REFERENCE_CLI/EFIELD can add a homogeneous electric field to the external native tblite command only. REFERENCE_CLI/IMPLICIT_SOLVATION can add native tblite implicit-solvent settings to the external reference command only. Native tblite run does not expose independent options for mixer MEMORY, DAMPING, OMEGA0, MIN_WEIGHT, MAX_WEIGHT, or WEIGHT_FACTOR; CP2K warns if these inherited production settings cannot be reproduced and aborts when STOP_ON_ERROR is enabled. Native CLI verbosity follows GLOBAL/PRINT_LEVEL: SILENT is forwarded as –silent, and HIGH or DEBUG are forwarded as –verbose. It remains a diagnostic one-shot calculation from temporary input files and is independent of CP2K’s SCF history, diagonalization, and k-point machinery. If RESTART is set, the named native tblite restart file is passed to the external command. Non-Fermi CP2K smearing methods cannot be represented by native tblite and are replaced by a Fermi-Dirac electronic temperature in the reference command with an explicit warning. [Edit on GitHub]

Subsections

• FIT_CLI
• GUESS_CLI
• IMPLICIT_SOLVATION
• PARAM_CLI
• TAGDIFF_CLI

Keywords

• SECTION_PARAMETERS

• CHECK_ENERGY

• CHECK_FORCES

• CHECK_VIRIAL

• EFIELD

• ELECTRONIC_TEMPERATURE_GUESS

• ERROR_LIMIT

• GRAD

• GUESS

• INPUT_FORMAT

• JSON

• KEEP_FILES

• POST_PROCESSING

• POST_PROCESSING_OUTPUT

• PREFIX

• PROGRAM_NAME

• RESTART

• STOP_ON_ERROR

• WORK_DIRECTORY

Keyword descriptions

SECTION_PARAMETERS: logical = F

Lone keyword: T

Activates the native tblite CLI reference check when the section is present. The check compares CP2K/tblite against a freshly executed external tblite calculation. [Edit on GitHub]

CHECK_ENERGY: logical = T

Lone keyword: T

Usage: CHECK_ENERGY T

Compare the CP2K/tblite total xTB energy with the energy obtained from the native tblite reference run. This checks the Hamiltonian setup, SCC solution, static repulsion/dispersion terms, charge and spin state, electronic temperature, and optional PARAM file consistency for the one-shot reference geometry. [Edit on GitHub]

CHECK_FORCES: logical = T

Lone keyword: T

Usage: CHECK_FORCES T

Compare CP2K/tblite nuclear gradients with the gradients written by the native tblite reference run. This is a sensitive check of derivative terms, including repulsion, dispersion, electrostatic response, and coordination-number response. The comparison uses the same geometry and model setup as the energy reference. [Edit on GitHub]

CHECK_VIRIAL: logical = F

Lone keyword: T

Usage: CHECK_VIRIAL T

Compare CP2K/tblite virial with the virial written by the native tblite reference run. This is a diagnostic for cell derivatives and stress-related terms. It is disabled by default because virial conventions, finite periodicity, and the absence of native CLI k-point sampling make this comparison more restrictive than the energy and force checks. [Edit on GitHub]

EFIELD: real[3] = 0.00000000E+000 0.00000000E+000 0.00000000E+000

Usage: EFIELD 0.0 0.0 0.0

Homogeneous electric field passed only to the native tblite reference command as tblite run –efield. The three components are given in V/Angstrom, matching the native tblite CLI convention. This keyword does not affect the production CP2K/tblite calculation because that path currently does not construct tblite’s external electric field container. If enabled together with energy, force, or virial checks, the comparison therefore intentionally diagnoses the native field response rather than matching a CP2K production field calculation. [Edit on GitHub]

ELECTRONIC_TEMPERATURE_GUESS: real = 0.00000000E+000 [K]

Usage: ELECTRONIC_TEMPERATURE_GUESS [K] 4000

Electronic temperature used only for the native tblite reference command’s initial CEH population guess. CP2K forwards positive values as tblite run –etemp-guess. The value does not affect CP2K/tblite production calculations and is independent of DFT/SCF/SMEAR/ELECTRONIC_TEMPERATURE, which controls the final electronic occupation temperature passed as –etemp. A value of zero leaves the native tblite default for the guess temperature untouched. Positive values are valid only together with GUESS CEH; CP2K aborts for SAD or EEQ because native tblite uses this option for the CEH guess. [Edit on GitHub]

ERROR_LIMIT: real = 1.00000000E-008

Usage: ERROR_LIMIT 1.0E-8

Tolerance for reporting reference CLI deviations. The value is applied to the absolute CP2K-minus-native differences printed by the enabled energy, force, and virial checks. Exceeding this limit produces a diagnostic warning, or an abort when STOP_ON_ERROR is enabled. [Edit on GitHub]

GRAD: string

Lone keyword: tblite.txt

Usage: GRAD tblite.txt

Filename passed to native tblite as –grad for the tagged ASCII gradient output. The native file contains the total energy, energy contributions, analytical molecular gradient, and virial. CP2K reads this file for the REFERENCE_CLI energy, force, and virial checks. If the keyword is omitted, CP2K writes a temporary PREFIX.grad file in WORK_DIRECTORY. If the keyword is present without a filename, CP2K uses tblite’s CLI default name tblite.txt. Unless KEEP_FILES is enabled, CP2K removes the selected file after the reference check. [Edit on GitHub]

GUESS: enum = SAD

Usage: GUESS (SAD|EEQ|CEH)

Valid values:

• SAD Use the superposition of atomic densities guess.

• EEQ Use the electronegativity equilibration guess.

• CEH Use the charge-equilibration Hamiltonian guess.

Initial population guess used only for the native tblite reference command. SAD uses the superposition of atomic densities, matching the default of tblite run. EEQ uses electronegativity equilibration charges, while CEH uses the charge-equilibration Hamiltonian guess. This keyword does not affect the production CP2K/tblite calculation; there, initial densities and restarts remain controlled by CP2K’s SCF machinery. [Edit on GitHub]

INPUT_FORMAT: string = gen

Usage: INPUT_FORMAT gen

Input format hint passed to native tblite run as –input. The default is GEN, matching the temporary DFTB+ GEN geometry written by CP2K for the reference calculation. Only change this together with a compatible externally inspected or modified input file workflow; the normal CP2K-generated reference geometry is GEN. [Edit on GitHub]

JSON: string

Lone keyword: tblite.json

Usage: JSON tblite.json

Filename passed to native tblite as –json for JSON result output. Without –grad the native JSON usually contains the energy and energy contributions; because CP2K’s REFERENCE_CLI path also requests –grad, native tblite can additionally include derivative data such as gradient and virial when supported by the CLI version. CP2K currently reads the tagged GRAD file for comparisons and keeps the JSON file as an inspectable native artifact. If the keyword is omitted, CP2K writes a temporary PREFIX.json file in WORK_DIRECTORY. If the keyword is present without a filename, CP2K uses tblite’s CLI default name tblite.json. Unless KEEP_FILES is enabled, CP2K removes the selected file after the reference check. [Edit on GitHub]

KEEP_FILES: logical = F

Lone keyword: T

Usage: KEEP_FILES T

Keep the temporary native tblite CLI input and output files after the comparison. This is mainly a debugging aid for inspecting the generated GEN geometry, the native tblite gradient/virial file, the JSON output, and the CLI log. [Edit on GitHub]

POST_PROCESSING: string

Usage: POST_PROCESSING molmom

Additional native tblite post-SCF analysis passed as tblite run –post-processing. The value can be a built-in post-processing module name or a TOML file. Native tblite already enables Mayer-Wiberg bond-order analysis internally by default. The additional built-in module names currently exposed by tblite include molmom for molecular moments and xtbml for xTB-ML descriptors. If the value names a TOML file, tblite reads its [post-processing] configuration and can select the post-processing modules more finely. This keyword affects only the external REFERENCE_CLI diagnostic run; CP2K does not parse the generated post-processing data for the energy/force/virial comparison. [Edit on GitHub]

POST_PROCESSING_OUTPUT: string

Lone keyword: tblite-data.npz

Usage: POST_PROCESSING_OUTPUT tblite-data.npz

Filename passed to native tblite as –post-processing-output. Native tblite documents this as the NPZ output file for post-processing data, with tblite-data.npz as its CLI default. In the locally checked tblite 0.5.0 source this option appears in the help text but is not wired in the command-line parser, so CP2K emits it only when explicitly requested and prints a warning before running the reference command. Use this keyword only with tblite CLI builds that actually accept the option. Unless KEEP_FILES is enabled, CP2K removes this explicit output file after the reference check. [Edit on GitHub]

PREFIX: string = tblite-reference

Usage: PREFIX tblite-reference

Prefix for the temporary native tblite CLI input and output files. Changing the prefix is useful when several reference checks are run in the same directory or when KEEP_FILES is used to inspect the generated geometry, gradient, JSON, or log files. [Edit on GitHub]

PROGRAM_NAME: string = tblite

Usage: PROGRAM_NAME tblite

Executable name or path for the native tblite command line program used for the reference calculation. This allows testing the CP2K/tblite implementation against a specific tblite build without changing the CP2K executable. [Edit on GitHub]

RESTART: string

Usage: RESTART filename

Native tblite restart file passed to the external reference command. When this keyword is absent, CP2K passes –no-restart so each diagnostic reference is a clean one-shot run from the generated geometry and selected CLI options. When a filename is given, CP2K passes –restart with that file. This affects only the external native tblite run; it does not read or write CP2K wavefunction or density restart data and is therefore independent of DFT/SCF/SCF_GUESS RESTART. [Edit on GitHub]

STOP_ON_ERROR: logical = F

Lone keyword: T

Usage: STOP_ON_ERROR T

Abort the CP2K run if any enabled reference CLI comparison exceeds ERROR_LIMIT. When disabled, CP2K prints the deviation but continues, which is useful for exploratory diagnostics and regression-test probes. [Edit on GitHub]

WORK_DIRECTORY: string = .

Usage: WORK_DIRECTORY .

Directory used for the temporary native tblite CLI input and output files. The CP2K/tblite result is not taken from this directory; the files are only used to run and inspect the independent reference calculation. [Edit on GitHub]