Skip to main content

Python tools to handle CP2K input files

Project description


Build Status codecov PyPI

Fully validating pure-python CP2K input file parsers including preprocessing capabilities

Available commands (also available through an API, see below):

  • cp2klint .. a CP2K input file linter
  • fromcp2k .. create a JSON or YAML configuration file from a CP2K input file (includes validation)
  • tocp2k .. convert a JSON or YAML configuration back to CP2K's input file format (includes validation)
  • cp2kgen .. generate new input files based on a given input file and expressions to change parameters programmatically
  • cp2kget .. get values from a CP2K input file (most likely a restart file) given a path of sections and attribute

For a description of the JSON/YAML formats used, see below.


For development:


  • have a pure-python CP2K input file linter with proper syntax error reporting (context, etc.)
  • a final & complete restart file parser
  • basis for an AiiDA CP2K project importer
  • testbed for alternative import formats (YAML, JSON) for CP2K
  • possible testbed for a re-implementation of the CP2K input parser itself


  • parser: improve error reporting with context
  • preprocessor: don't lose original context when interpolating variables
  • parser: parsing the XML is slow (easily 70% of the time), pickle or generate Python code directly instead and keep XML parsing as fallback
  • parser: maybe generate AST using an emitting (yield) parser for more flexibility, would allow for YAML generator preserving the comments


Command Line Interface

Generate JSON or YAML from a CP2K input file:

$ fromcp2k --help
usage: fromcp2k [-h] [-y] [-c] [-b BASE_DIR] [-t TRAFO] <file>

Convert CP2K input to JSON (default) or YAML

positional arguments:
  <file>                CP2K input file

optional arguments:
  -h, --help            show this help message and exit
  -y, --yaml            output yaml instead of json
  -c, --canonical       use the canonical output format
  -b BASE_DIR, --base-dir BASE_DIR
                        search path used for relative @include's
  -t TRAFO, --trafo TRAFO
                        transformation applied to key and section names (auto,
                        upper, lower)

Generate a CP2K input file from a JSON or YAML:

$ tocp2k --help
usage: tocp2k [-h] [-y] <file>

Convert JSON or YAML input to CP2K

positional arguments:
  <file>      JSON or YAML input file

optional arguments:
  -h, --help  show this help message and exit
  -y, --yaml

Lint a CP2K input file:

$ cp2klint tests/inputs/unterminated_var.inp
Syntax error: unterminated variable, in tests/inputs/unterminated_var.inp:
line   36: @IF ${HP

Generate input files for a CUTOFF convergence study (multiple expressions will be combined as a cartesian product):

$ cp2kgen tests/inputs/NaCl.inp "force_eval/dft/mgrid/cutoff=[800,900,1000]"
Writing 'NaCl-cutoff_800.inp'...
Writing 'NaCl-cutoff_900.inp'...
Writing 'NaCl-cutoff_1000.inp'...
$ diff -Naurb NaCl-cutoff_800.inp NaCl-cutoff_900.inp 
--- NaCl-cutoff_800.inp	2019-10-21 18:52:09.994323474 +0200
+++ NaCl-cutoff_900.inp	2019-10-21 18:52:10.680996641 +0200
@@ -69,7 +69,7 @@
          REL_CUTOFF 80.0
-         CUTOFF 800
+         CUTOFF 900
          NGRIDS 6
       &END MGRID

Get a value from a CP2K input file, for example a RESTART file generated in a cell optimization:

$ poetry run cp2kget tests/inputs/NaCl.inp "force_eval/subsys/cell/a/0"
force_eval/subsys/cell/a/0: 5.64123539364476


Convert a CP2K input file to a nested Python dictionary:

from cp2k_input_tools.parser import CP2KInputParser, CP2KInputParserSimplified

canonical = False

if canonical:
    parser = CP2KInputParser()
    parser = CP2KInputParserSimplified()

with open("project.inp") as fhandle:
    tree = parser.parse(fhandle)

Convert a nested Python dictionary back to a CP2K input file:

from cp2k_input_tools.generator import CP2KInputGenerator

generator = CP2KInputGenerator()

tree = {"global": {}}  # ... the input tree

with open("project.inp", "w") as fhandle:
    for line in generator.line_iter(tree):

The CP2K JSON and YAML formats

A reference to the CP2K input format can be found here:

Canonical format

For everything except the pre-processor capabilities (@IF/@ENDIF/$var/@SET) there is a canonical one-to-one mapping of the CP2K input format to either JSON or YAML:

  • repeatable sections are mapped to dictionaries
  • keywords or subsections are key/value entries in sections
  • all repeatable elements (sections and keywords) are mapped to lists of their respective mapped datatype
  • section parameters are mapped to a special key named _
  • default section keywords are mapped to a special key name *
  • sections in JSON or YAML must be prefixed to avoid double definition of a key in case of same name for a section and a keyword (like the POTENTIAL in KIND), to avoid quotation marks, instead of CP2K's & we are using the +
  • keyword values are mapped based on their datatypes: a list of values is always mapped to a list of their respective datatypes

The following example input:

   PROJECT test
   METHOD Quickstep
      &END XC
         A [angstrom] 4.07419 0.0 0.0
         B [angstrom] 2.037095 3.52835204 0.0
         C [angstrom] 2.037095 1.17611735 3.32656221
      &END CELL
      &KIND Ge
         ELEMENT Ge
         POTENTIAL ALL-q32
         BASIS_SET ORB pob-TZVP
      &END KIND
         COORD_FILE ./

would generate the (canonical) JSON:

  "+global": {
    "print_level": "medium",
    "project_name": "test",
    "run_type": "energy"
  "+force_eval": [
      "method": "quickstep",
      "+DFT": {
        "basis_set_file_name": [
        "potential_file_name": "./POTENTIALS"
      "+XC": {
        "+xc_functional": {
          "_": "PBE"
      "+subsys": {
        "cell": {
          "A": [ 4.07419, 0, 0 ],
          "B": [ 2.037095, 3.52835204, 0 ],
          "C": [ 2.037095, 1.17611735, 3.32656221 ],
          "periodic": "XYZ"
        "+kind": [
            "_": "Ge",
            "element": "Ge",
            "potential": "ALL-q32",
            "basis_set": [
              [ "ORB", "pob-TZVP" ]
        "+topology": {
          "coord_file_name": "./",
          "coord_file_format": "XYZ"


  • the full input format needs be known and is being loaded from a bundled cp2k_input.xml
  • the YAML/JSON is quiet verbose and one has to know exactly which keywords can be repeated

While there is no solution to remedy the first caveat, the second can be solved with the simplified output format

Simplified format

Still based on the canonical format the simplified format relaxes some of the rules

  1. a section must only be prefixed with a + if a keyword with the same name is present at the same time in the same section (since we can figure out whether the user wanted to specify the section or the keyword by inspecting the value for the key: dict for a section)
  2. if a repeated keyword or section contains only one entry, the list can be omitted (in case of ambiguity priority is given to multiple values per keyword rather than keyword repetition)
  3. sections with default parameters can be formulated as dictionaries, as long as the default parameter values are unique and do not match section keyword or subsection names

the example from before in the simplified format:

  "global": {
    "print_level": "medium",
    "project_name": "test",
    "run_type": "energy"
  "force_eval": {
    "method": "quickstep",
    "DFT": {
      "basis_set_file_name": "./BASIS_SETS",
      "potential_file_name": "./POTENTIALS"
    "xc": {
      "xc_functional": {
        "_": "PBE"
    "subsys": {
      "cell": {
        "A": [ 4.07419, 0, 0 ],
        "B": [ 2.037095, 3.52835204, 0 ],
        "C": [ 2.037095, 1.17611735, 3.32656221 ],
        "periodic": "XYZ"
      "kind": {
        "_": "Ge",
        "element": "Ge",
        "potential": "ALL-q32",
        "basis_set": [ "ORB", "pob-TZVP" ]
      "topology": {
        "coord_file_name": "./",
        "coord_file_format": "XYZ"

or in YAML (with simplification rule #3 applied):

  print_level: medium
  project_name: test
  run_type: energy
    basis_set_file_name: ./BASIS_SETS
    potential_file_name: ./POTENTIALS
      _: PBE  # this can NOT be simplified since PBE could also be a subsection of xc_functional
  method: quickstep
      A: [ 4.07419, 0.0, 0.0]
      B: [ 2.037095, 3.52835204, 0.0]
      C: [ 2.037095, 1.17611735, 3.32656221]
      periodic: XYZ
        basis_set: [ORB, pob-TZVP]
        element: Ge
        potential: ALL-q32
      coord_file_format: XYZ
      coord_file_name: ./

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for cp2k-input-tools, version 0.3.1
Filename, size File type Python version Upload date Hashes
Filename, size cp2k_input_tools-0.3.1-py3-none-any.whl (676.5 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size cp2k-input-tools-0.3.1.tar.gz (655.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page