---
description: Add the optional calculate stage — DFTB+ run through your own AiiDA installation — between screening and extraction.
---

# 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.

:::{admonition} About the output on this page
:class: note

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:

```yaml
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

```console
$ 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:

```text
│ 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:

```text
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:

```text
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:

```console
$ 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:

```console
$ 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:

```console
$ 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: {doc}`../how-to/configure-calculate` is the same setup as a short
recipe, and {doc}`../how-to/view-a-structure` exports the DFTB+ relaxed
geometries this stage produces.
