T6 — Higher-fidelity calculation with DFTB+#

Goal: put the optional calculate stage into a funnel, run DFTB+ on screened structures through your own AiiDA, and see the results folded into the final records.

Prerequisites: this is the most demanding tutorial on the site.

  • A completed screening run (T1), so you have RELAXED materials to calculate.

  • Your own AiiDA installation, working: aiida-core and the aiida-mydftbp plugin importable by the stage’s interpreter, a configured profile, a running daemon, and a DFTB+ code set up (verdi code list).

  • Slater–Koster parameter files for your elements, readable where DFTB+ runs.

Time: 30 minutes if AiiDA is already working; considerably longer if not.

About the output on this page

The doctor output here is real, captured against a local AiiDA profile. The end-to-end calculation results come from the recorded acceptance run on our own hardware (profile Macremote, DFTB+ on a lab machine), because a live DFTB+ cluster cannot be reproduced while writing the page. Substitute your own profile, code label and paths.

What this stage is, and is not#

calculate is optional. A funnel without it is complete and valid, and everything you have done so far is unaffected by adding it.

MatMelt does not implement DFTB+, and it does not ship or manage AiiDA. Your AiiDA installation owns the calculation: the plugin’s mydftbp.single WorkChain does the work, including its own self-healing retries. MatMelt is the launcher and the extractor around it — it prepares the inputs, submits the WorkChain, records its identity, waits, and turns the outcome into the same kind of stage verdict every other stage produces.

1. Configure the stage#

The scaffolded config ships this block commented out, between screen and extract. Uncomment it and fill in the two required options:

stages:
  calculate:
    backend: laptop
    options:
      python: python3
      profile: AiiDApro
      code_label: installed-code@localhost
      skf_prefix: /opt/skf/

code_label is the code as AiiDA knows it — exactly what verdi code list shows. skf_prefix is the absolute directory where DFTB+ will look for .skf files, on the machine where DFTB+ runs. profile is optional; omit it to use your default profile.

Note that backend: laptop is not a mistake. The stage runs wherever your AiiDA client runs, which is usually your own machine; AiiDA then dispatches the calculation to whatever computer the code is configured on.

2. Let doctor check it#

$ matmelt doctor

Two different checks now appear. The first is the usual import probe, which knows that the import name and the install name differ:

│ calculate │ aiida         │ python3     │ local │ ok      │ aiida importable │
│ calculate │ aiida_mydftbp │ python3     │ local │ MISSING │ ModuleNotFoundE… │
│           │               │             │       │         │ 'aiida_mydftbp'  │
└───────────┴───────────────┴─────────────┴───────┴─────────┴──────────────────┘
To fix the missing requirements, run:
  python3 -m pip install aiida-mydftbp

The second is a configuration check that no import probe could make — it loads your profile and looks up your code:

Calculate AiiDA: ok -- AiiDA profile 'AiiDApro' loads; code
'installed-code@localhost' found

and when the label is wrong, which is the most common setup mistake:

Calculate AiiDA: PROBLEM -- AiiDA not ready:
aiida.common.exceptions.NotExistent: no Code found with LABEL<dftbplus@cluster>:
No result was found

Fix both before running. doctor exits 1 while either is unresolved.

3. Push screened materials through it#

Materials that are already SCREENED do not need the earlier stages re-run:

$ matmelt run --only calculate

For each material the stage prepares DFTB+ inputs from the relaxed structure — a .gen geometry and a dftb_in.hsd with your skf_prefix, a k-mesh, and a maximum angular momentum chosen per element — then submits one mydftbp.single WorkChain and waits for it to reach a terminal state.

The submission is recorded before any waiting happens. The WorkChain’s pk and uuid are written to calc_submission.json the moment it is submitted, so if the run is interrupted the next run re-attaches to the same WorkChain instead of starting a second one. In the acceptance run this was tested the blunt way: the CLI and its runner were killed mid-poll, the WorkChain carried on running on the AiiDA daemon, and the rerun picked it up by uuid and drained it to completion — one WorkChain in the database, zero resubmissions.

4. Slater–Koster files#

DFTB+ needs parameter files for every element pair. MatMelt makes sure the node exists rather than letting a run stall waiting for one:

  • If a FolderData with the expected label is already in your database, it is reused — never duplicated.

  • If not, and you set skf_local_path to a directory of .skf files, one is created from it, labelled and stored.

  • If neither, the stage fails loudly and immediately, naming both the label it looked for and the option that would fix it.

That last case is deliberate. A missing parameter set used to be the kind of problem that surfaces as a job that simply never finishes; here it is an actionable error before anything is submitted.

5. Reading the result#

Each material gets a calc_result.json holding the outcome, the final energy, and the full history of the WorkChain’s healing attempts — every parameter change the plugin made while getting the calculation to converge, which is information the underlying tooling records but rarely surfaces.

Absolute Slater–Koster paths are stripped from that document before it is written. A results file is something you share; it should not carry the directory layout of the machine that produced it.

Verdicts follow the same doctrine as every other stage. A converged calculation advances the material. A WorkChain that ends in one of the plugin’s known scientific failure modes is a terminal verdict — recorded once, not retried. Anything else (an infrastructure failure, an unrecognised exit status) is a fault that spends retry budget.

From the acceptance run: WorkChain pk 13524 converged at −90.31 eV, the Slater–Koster FolderData was created once (pk 13517) and reused on the second run, and no .skf path appeared anywhere in the resulting document.

6. Fold it into the records#

extract picks up calc_result.json automatically when it exists:

$ matmelt run --only extract

The record then carries the calculation verbatim under attributes._mcli.calculate — pk, convergence, energy and the healing history — beside the screening block that was already there. A funnel without calculate produces byte-identical records apart from the absence of that key, so adding the stage does not change the shape of everything else.

7. Export the DFTB+ geometry#

The structure DFTB+ relaxed is not the same as the one MACE relaxed. To export it as CIF:

$ matmelt cif --out-dir dftb-structures

It writes to <work_dir>/cifs if you omit --out-dir, and --materials / --materials-file narrow it to chosen ids.

cif serves materials whose calculation converged. Where the geometry was cached into calc_result.json it is read straight from disk; otherwise the command fetches it from AiiDA — and when everything is cached it starts no AiiDA process at all.

What you learned#

  • calculate is optional and additive: funnels without it are unaffected, and records gain exactly one key when it runs.

  • Your AiiDA owns the calculation; MatMelt launches, waits, and extracts.

  • doctor checks both the imports and the AiiDA configuration — profile and code — before a run starts.

  • The WorkChain identity is recorded before polling, so an interrupted run re-attaches instead of resubmitting.

  • Missing Slater–Koster parameters fail loudly and actionably, never silently.

  • Results carry the full healing history and never leak Slater–Koster paths.

From here: Add the DFTB+ calculate stage is the same setup as a short recipe, and Look at a structure exports the DFTB+ relaxed geometries this stage produces.