DFT workflow metadata example
This completed example shows how a density functional theory workflow can be documented as a sequence of interconnected computational steps. It records the purpose of each step, its inputs and outputs, software, parameters, dependencies, execution status and quality-control results. The example applies selected elements of the Metadata profile for DFT datasets and extends them with workflow-step descriptions, input-output relationships and execution provenance.
Resource information
Resource type
Completed workflow metadata example
Intended users
Computational researchers, dataset authors, curators and workflow developers
Recommended use
Workflow documentation, provenance capture, FAIR packaging and training
Status
Illustrative domain-specific example of the Competence Center
Download the example workflow package
Download the complete example package or inspect the individual workflow, provenance and manifest files.
What does this example represent?
The example represents a computational workflow used to prepare and validate a DFT calculation for cubic silicon carbide. The workflow begins with an initial crystal structure, tests numerical parameters, optimises the structure, performs a final self-consistent calculation and packages the principal inputs, outputs and metadata.
Each workflow step is treated as a separate activity with defined inputs, outputs, software, parameters, dependencies and validation results.
Workflow metadata describe how results were produced
The DFT dataset metadata profile describes the published dataset as a whole. This workflow example records the sequence of operations that used and generated the files contained in that dataset.
Workflow overview
The example contains five connected computational and documentation steps.
1. Prepare structure
Select and document the initial 3C-SiC crystal structure.
2. Test convergence
Determine suitable energy cutoffs and k-point sampling.
3. Optimise geometry
Relax the atomic positions and unit-cell parameters.
4. Calculate results
Run the final self-consistent calculation using validated settings.
5. Package outputs
Extract principal results and prepare the FAIR data package.
Workflow step summary
Each step has a persistent internal identifier and explicit input-output relationships.
| Step | Purpose | Main inputs | Main outputs | Depends on |
|---|---|---|---|---|
structure_preparation |
Prepare and verify the initial 3C-SiC structure | Source structure and reference information | structures/initial_3c_sic.cif |
None |
convergence_testing |
Select the numerical settings used by later calculations | Initial structure, pseudopotentials and test inputs | Cutoff and k-point convergence tables | structure_preparation |
geometry_optimisation |
Optimise atomic positions and unit-cell parameters | Initial structure and selected numerical settings | Relaxed structure and optimisation log | convergence_testing |
final_scf |
Calculate the final electronic ground state | Relaxed structure and validated settings | SCF output, total energy, forces and stress | geometry_optimisation |
result_packaging |
Extract results and prepare the publication package | SCF outputs, structures and convergence evidence | Tables, metadata, README, manifest and provenance record | final_scf |
Metadata recorded for each workflow step
Workflow-level fields describe execution order, dependencies and the use and generation of digital objects.
| Field | Purpose | Example |
|---|---|---|
step_id |
Stable internal identifier of the workflow step | geometry_optimisation |
step_order |
Position of the step in the workflow | 3 |
step_type |
Category of computational or documentation activity | DFT geometry optimisation |
description |
Scientific purpose of the step | Optimise the 3C-SiC structure |
software |
Software and version used to execute the step | Quantum ESPRESSO 7.3 |
parameters |
Numerical and methodological settings specific to the step | PBE, 60 Ry, 8 × 8 × 8 k-point grid |
inputs |
Files or digital objects used by the step | structures/initial_3c_sic.cif |
outputs |
Files or digital objects generated by the step | structures/relaxed_3c_sic.cif |
depends_on |
Previous step that must be completed first | convergence_testing |
execution_status |
Operational status of the step | Completed |
validation |
Quality-control or convergence result | Force convergence criterion satisfied |
execution_record |
Log, job record or provenance entry associated with execution | provenance/step_03.json |
Completed workflow JSON example
The following shortened record illustrates the structure of the downloadable workflow metadata file.
{
"workflow": {
"workflow_id": "dft-3c-sic-example",
"title": "DFT workflow for cubic silicon carbide",
"workflow_type": "Density functional theory calculation",
"version": "1.0",
"description": "Illustrative workflow for preparing, validating and running a DFT calculation for 3C-SiC.",
"subject": {
"material_name": "Silicon carbide",
"chemical_formula": "SiC",
"phase_or_polymorph": "3C-SiC"
},
"software_environment": {
"primary_software": "Quantum ESPRESSO",
"software_version": "7.3",
"operating_environment": "Linux",
"execution_mode": "MPI"
},
"steps": [
{
"step_id": "structure_preparation",
"step_order": 1,
"step_type": "Structure preparation",
"description": "Prepare and verify the initial 3C-SiC crystal structure.",
"inputs": [
{
"path": "source/reference_structure.cif",
"role": "source structure"
}
],
"outputs": [
{
"path": "structures/initial_3c_sic.cif",
"role": "validated initial structure"
}
],
"depends_on": [],
"execution_status": "completed",
"validation": {
"status": "passed",
"checks": [
"chemical composition verified",
"periodicity verified"
]
}
},
{
"step_id": "convergence_testing",
"step_order": 2,
"step_type": "Numerical convergence testing",
"description": "Evaluate energy-cutoff and k-point convergence.",
"software": {
"name": "Quantum ESPRESSO",
"version": "7.3"
},
"inputs": [
{
"path": "structures/initial_3c_sic.cif",
"role": "atomic structure"
},
{
"path": "pseudopotentials/Si.upf",
"role": "silicon pseudopotential"
},
{
"path": "pseudopotentials/C.upf",
"role": "carbon pseudopotential"
}
],
"parameters_tested": {
"energy_cutoffs_Ry": [40, 50, 60, 70],
"k_point_grids": [
"4 x 4 x 4",
"6 x 6 x 6",
"8 x 8 x 8"
]
},
"selected_parameters": {
"energy_cutoff": {
"value": 60,
"unit": "Ry"
},
"k_point_grid": "8 x 8 x 8"
},
"outputs": [
{
"path": "convergence/cutoff_test.csv",
"role": "cutoff convergence results"
},
{
"path": "convergence/kpoint_test.csv",
"role": "k-point convergence results"
}
],
"depends_on": [
"structure_preparation"
],
"execution_status": "completed",
"validation": {
"status": "passed",
"criterion": "Total-energy variation below the selected threshold"
}
},
{
"step_id": "geometry_optimisation",
"step_order": 3,
"step_type": "DFT geometry optimisation",
"description": "Optimise atomic positions and unit-cell parameters.",
"software": {
"name": "Quantum ESPRESSO",
"version": "7.3"
},
"method": {
"exchange_correlation_functional": "PBE",
"basis_representation": "plane waves",
"energy_cutoff": {
"value": 60,
"unit": "Ry"
},
"k_point_grid": "8 x 8 x 8"
},
"inputs": [
{
"path": "structures/initial_3c_sic.cif",
"role": "initial structure"
},
{
"path": "input/relax.in",
"role": "calculation input"
}
],
"outputs": [
{
"path": "output/relax.out",
"role": "calculation log"
},
{
"path": "structures/relaxed_3c_sic.cif",
"role": "relaxed structure"
}
],
"depends_on": [
"convergence_testing"
],
"execution_status": "completed",
"validation": {
"status": "passed",
"convergence_status": "converged",
"force_threshold": {
"value": 0.0001,
"unit": "Ry/Bohr"
}
}
},
{
"step_id": "final_scf",
"step_order": 4,
"step_type": "Self-consistent DFT calculation",
"description": "Calculate the final electronic ground state.",
"inputs": [
{
"path": "structures/relaxed_3c_sic.cif",
"role": "relaxed structure"
},
{
"path": "input/scf.in",
"role": "SCF input"
}
],
"outputs": [
{
"path": "output/scf.out",
"role": "SCF output"
},
{
"path": "results/energies.csv",
"role": "extracted energy results"
},
{
"path": "results/forces.csv",
"role": "extracted atomic forces"
}
],
"depends_on": [
"geometry_optimisation"
],
"execution_status": "completed",
"validation": {
"status": "passed",
"electronic_convergence": "1e-8 Ry"
}
},
{
"step_id": "result_packaging",
"step_order": 5,
"step_type": "FAIR data packaging",
"description": "Prepare documentation, metadata, provenance and file inventory.",
"inputs": [
{
"path": "output/scf.out",
"role": "principal calculation output"
},
{
"path": "results/energies.csv",
"role": "derived result"
},
{
"path": "structures/relaxed_3c_sic.cif",
"role": "final structure"
}
],
"outputs": [
{
"path": "README.md",
"role": "package documentation"
},
{
"path": "manifest.csv",
"role": "file inventory"
},
{
"path": "metadata.json",
"role": "dataset metadata"
},
{
"path": "provenance/provenance.json",
"role": "workflow provenance"
}
],
"depends_on": [
"final_scf"
],
"execution_status": "completed",
"validation": {
"status": "passed",
"checks": [
"all manifest paths resolved",
"required metadata present",
"principal files checksummed"
]
}
}
]
}
}
Provenance relationships
Provenance records explain which activities used or generated each digital object and how later results were derived from earlier files.
Used
Identifies the files, structures or parameters used by a workflow step.
Generated
Identifies the files and results generated by a workflow step.
Was derived from
Connects a result or transformed file to its source digital object.
Depends on
Records the execution dependency between two workflow steps.
Example provenance record
This simplified representation connects workflow activities with the digital objects they use and generate.
{
"activities": [
{
"activity_id": "geometry_optimisation",
"used": [
"structures/initial_3c_sic.cif",
"input/relax.in"
],
"generated": [
"output/relax.out",
"structures/relaxed_3c_sic.cif"
]
},
{
"activity_id": "final_scf",
"used": [
"structures/relaxed_3c_sic.cif",
"input/scf.in"
],
"generated": [
"output/scf.out",
"results/energies.csv",
"results/forces.csv"
]
}
],
"derivations": [
{
"entity": "structures/relaxed_3c_sic.cif",
"was_derived_from": "structures/initial_3c_sic.cif"
},
{
"entity": "results/energies.csv",
"was_derived_from": "output/scf.out"
}
]
}
Recommended example package structure
dft-workflow-example/
│
├── README.md
├── manifest.csv
├── metadata.json
├── workflow.json
│
├── source/
│ └── reference_structure.cif
│
├── structures/
│ ├── initial_3c_sic.cif
│ └── relaxed_3c_sic.cif
│
├── pseudopotentials/
│ ├── Si.upf
│ └── C.upf
│
├── input/
│ ├── cutoff_test.in
│ ├── kpoint_test.in
│ ├── relax.in
│ └── scf.in
│
├── output/
│ ├── relax.out
│ └── scf.out
│
├── convergence/
│ ├── cutoff_test.csv
│ └── kpoint_test.csv
│
├── results/
│ ├── energies.csv
│ └── forces.csv
│
├── scripts/
│ └── extract_results.py
│
├── environment/
│ └── software_environment.yml
│
└── provenance/
└── provenance.json
How to use the example
1. Examine
Review how the example separates workflow steps, files and provenance relations.
2. Copy
Copy the workflow structure and remove example-specific values.
3. Adapt
Replace the example steps with the operations used in your own calculation.
4. Connect
Link each step to the actual input, output and provenance files.
5. Validate
Check execution order, file paths, dependencies and metadata consistency.
Important notes
- Treat this resource as an illustrative example rather than a mandatory universal workflow specification.
- Replace all example parameters, software versions and file paths with values from the actual calculation.
-
Give every workflow step a unique and stable
step_id. - Record the actual execution order separately from the conceptual order when the workflow contains iterations or parallel branches.
- Link every declared input and output to an existing file or digital object in the package.
- Distinguish a software input file from the scientific structure or dataset referenced by that file.
- Record failed, repeated or excluded calculations when they are relevant to interpreting the final result.
- Do not report a step as converged unless its documented criterion was satisfied.
- Keep workflow paths consistent with the manifest and package directory structure.
- Do not include passwords, access tokens, confidential cluster information or other security-sensitive values.