How to create the input file with the GUI tool

This is the follow-up to the previous post:

How to download and install the QELK SUITE Package 

 

Once QELK is built and qelk is on your PATH, the next thing you need is a .qelk input file -- the plain-text format that describes the cell, the atoms, the species and the calculation steps for both Elk and QE. You can always write one by hand, or copy and edit one of the 28 bundled examples, but the suite also ships a small graphical builder, qelkinput_creator_gui.py, that walks you through all of it tab by tab and writes the file for you.

 

This post shows the whole tool, tab by tab, with a screenshot of each.

 

Launching the tool:

From inside the QELK tree:

 

abibitio@linux-ml0a:~/abinitio/QELK> python3 tools/qelkinput_creator_gui.py

This needs Tk (python3 -m tkinter should pop up a tiny test window -- if it errors, install python3-tk first).

 

abibitio@linux-ml0a:~> sudo apt install python3-tk

It opens an 880x640 window titled "QELK input creator" with six numbered tabs across the top. You work through them left to right -- 1 through 6.

 

1. Structures:

The fastest way to get a working file is to click one of the seven ready-made buttons -- each fills in the material name, lattice choice, lattice constant(s) and atom basis for you: Si(Diamond), Ni(fcc), Cr(bcc), NiS(NiAs), NaCl(Rocksalt), and three generic placeholders A(Ortho), A(Tetra), A(Rhombo) for orthorhombic/tetragonal/rhombohedral systems that aren't a specific real material.

 

Clicking a button pops a "Template loaded" dialog confirming what got filled in:

 

 

Click OK, then jump straight to tab 6 if the template is exactly what you want, or go to tab 2 to tweak the atoms/lattice constant first. If you'd rather build a structure from scratch, just skip this tab and go straight to tab 2 -- it works standalone.

 

2. Material, Lattice && Atoms:

This is where you build a structure by hand, or fine-tune what a template loaded. Left side: material name (with an "Apply known defaults" button for elements the tool recognises, e.g. Si, GaAs, Ni, W, Cu), the lattice choice (SC/BCC/FCC/DIAMOND/HEX/TET/ORTHO/RHOMBO), units, the lattice constant(s), the Primitive/Conventional cell choice, and an "Auto-fill atom(s)" button. Right side: the Atoms table (fractional coordinates only), with Add/Remove buttons and quick-fill presets.

 

 

3. Species:

One box per unique atom label used in tab 2's Atoms table -- switch to this tab (or click "Refresh from atoms") any time you add a new label. Each box has elk_file, qe_pseudo (with a Paste button and a Download... button that fetches a pseudopotential straight from a URL with wget), qe_mass, and an optional symbol override.

 

 

For elements the suite ships a matched, verified pseudopotential for, a grey note under the fields calls out anything worth knowing -- here it warns that xctype 2 (LDA) is the one that matches the bundled Si.pz-vbc.UPF, and pairing it with xctype 20 (GGA) was a real mismatch bug caught in this suite.

 

4. Steps && calculation type:

First choose the calculation type: single (one code runs every step), combined (a pipeline/handoff between codes, e.g. relax with Elk then SCF+band with QE), or comparison (the same calculation run independently by both codes, e.g. an elk_vs_qe file). For a single Elk run you then choose what goes in its task list -- SCF only, relax positions, relax positions+cell, or band structure and/or DOS (the note explains why relaxation can't be combined with band/DOS in one Elk run). The screenshot below has Band structure and/or DOS selected, which reveals the band-path box (prefilled with the lattice's standard high-symmetry path) and the DOS choice.

 

 

For combined or comparison, use the "Number of stages" spinner and "Configure stages" button instead -- this builds one labelled "Stage N" frame per stage, each with its own code choice and a function dropdown (scf/relax/vcrelax/band/dos/pdos).

 

5. Calculation settings:

Settings shared by every step: the k-point mesh, a Metal checkbox (which unlocks Spin-polarized / magnetic), then two side-by-side boxes for xctype/rgkmax/bfieldc on the Elk side and ecutwfc/ecutrho/conv_thr/degauss/smearing/forc_conv_thr on the QE side -- only the box(es) for the code(s) actually used on tab 4 are shown.

 

 

A DOS/PDOS step overrides this k-mesh automatically with a denser one -- no need for a separate dense-mesh entry for those steps.

 

6. Preview && save:

Click Generate to render the .qelk text from everything on tabs 1-5. If something required is still missing, it stops with a "Can't generate yet" dialog naming exactly which tab/field to fix. The Output filename is auto-suggested following the same <Material>_<types>_<code>.qelk convention every bundled example uses.

 

 

Click "Save As..." and pick a location -- it creates a new folder named after the filename's stem and writes the .qelk file into it, the same one-folder-per-example layout used under examples/:

 

 

Then "Create how-to-run file" writes a HOW_TO_RUN.md right next to the saved file, walking through what each generated step does and how to run and plot it:

 

 

Finally, "Validate (qelk --dry-run)" is enabled once qelk is on PATH and the file has been saved -- it runs the same --dry-run check from the install post against the saved file and reports success or the exact error in a dialog, so you catch a mistake before it's saved as a habit.

 

The installation is ok

 

Tips:

* A template on tab 1 is just a starting point, not a lock-in -- you can still edit the lattice, constant or atoms on tab 2 afterward.

 

* Going back to an earlier tab and changing something after you've already clicked Generate does NOT update the preview by itself -- click Generate again before saving.

 

* Everything the GUI writes is exactly the plain .qelk format -- nothing GUI-specific in the output, so a file built here is just as portable, diffable and hand-editable afterward as one built by hand or copied from examples/.

 

No display, or working over SSH? There's a terminal wizard that does the same job one prompt at a time -- python3 tools/qelkinput_creator.py -- covered in a later post.