QCortado User guide

Static guide for the main QCortado application

Run Quantum ESPRESSO workflows from CIF import to post-processing.

QCortado is a desktop interface for building, running, saving, and revisiting Quantum ESPRESSO calculations. This guide covers local setup, project management, every calculation wizard, HPC execution, storage, recovery, and result viewers.

Start with setup See workflow map
QCortado workflow
Project
CIF
SCF
Post-process
View
Archive

Quickstart

1

Install Quantum ESPRESSO and make sure the selected bin directory contains at least pw.x.

2

Download pseudopotentials for every element you plan to study. SSSP-compatible UPF files are the default path QCortado tries to make easy.

3

Open QCortado, set the QE bin directory, choose local or HPC execution, and set optional MPI defaults.

4

Create a project, import a CIF, run a converged SCF or relax calculation, then launch downstream wizards from the project dashboard.

Rule of thumb: downstream calculations should start from the saved SCF or optimized structure that best matches the physics you want. For phonons, use a tight, phonon-ready SCF from a relaxed geometry. For Wannier and transport, use a scalar SCF that the Wannier wizard marks as compatible.

First-time setup

QCortado stores global settings in the app data directory and applies them to new wizard runs. The settings panel controls local QE paths, MPI defaults, save-size policy, FermiSurfer, Wannier90, and HPC profiles.

Install or build QCortado

Packaged app

Use a released QCortado desktop build when available. The app is a Tauri desktop application, so it runs as a local GUI and launches QE executables from paths you configure.

Developer build

npm install
npm run tauri dev

Building from source also requires Rust and the Tauri prerequisites for your OS.

Configure local executables

SettingWhat QCortado expectsUsed by
QE bin directory A directory containing pw.x. QCortado also checks for bands.x, dos.x, projwfc.x, ph.x, q2r.x, matdyn.x, hp.x, and epw.x as needed. All QE workflows
Pseudopotential directory A folder of UPF files. QCortado reads filenames and metadata, offers SSSP/PAW/USPP/NCPP selection helpers, and can infer missing cutoff ratios cautiously. SCF, NSCF, bands, DOS, Fermi surface
Execution prefix An optional command prefix, for example mpirun or srun, prepended to local QE launches. Local advanced execution
MPI defaults Enable MPI and choose a default process count. Wizards can override the process count per run. Local runs
FermiSurfer path An executable path used to open saved Fermi-surface files externally. Fermi-surface viewer integration
Wannier90 path A wannier90.x executable. QCortado derives the sibling postw90.x path unless an older saved config supplies it directly. Wannier and BoltzWann transport
Non-SCF save size Large keeps full restart files for non-SCF calculations. Small compacts non-SCF saves where supported. Project storage
Do not mix pseudopotential families casually. Cutoffs, SOC support, semicore treatment, and exchange-correlation assumptions come from the pseudopotential. QCortado can help select files, but convergence tests remain the user's responsibility.

Projects, calculations, and storage

QCortado centers work around projects. A project contains one or more CIF variants, and each CIF variant contains saved calculations. The project dashboard is the launch point for all downstream workflows once an SCF or related prerequisite exists.

Project browser
Folders Project cards Archive import/export Band multiview
Project dashboard
CIF variants SCF and relax Post-processing Saved viewers

Project browser

  • Create, open, delete, import, and export projects.
  • Create folders, rename folders, delete folders, and move projects between root and folders.
  • Filter projects by saved calculation type: SCF, bands, DOS, Wannier, transport, phonon, EPW, and related entries.
  • Open the band multiview to compare saved band calculations across projects.

Project dashboard

  • Import CIFs and keep variants under the same project.
  • Run SCF, relaxation, SOC, phonon-ready SCF, and downstream calculations from saved source runs.
  • Open saved viewers for bands, DOS, Wannier, transport, phonons, EPW, magnetism, and Hubbard occupations.
  • Rename saved calculations, add/remove tags, download remote artifacts, inspect logs/inputs, and delete calculations.

Task queue and activity

Local background tasks appear in the task queue with live output, progress, cancel, and dismiss controls. HPC runs are submitted directly from the wizard and surface remote job metadata, Slurm state, remote work directories, and generated Slurm scripts in the activity views.

Storage manager

The storage manager scans local or HPC storage and groups data into projects, calculations, temp files, remote orphans, and other paths. It can delete selected entries or lighten supported saved calculations. Lightening removes heavy QE wavefunction/restart artifacts while preserving saved results for supported non-SCF types such as optimization, bands, DOS, and Fermi surface.

Workflow map

Import CIFParse cell, atoms, symmetry, citations
SCF or relaxSelect cell, pseudopotentials, cutoffs, k mesh, magnetism, Hubbard, vdW, SOC
Choose sourceDownstream wizards reuse saved density, structure, Fermi level, metadata, and artifacts
Post-processBands, DOS, Fermi surface, phonons, Hubbard U, Wannier, transport, EPW
View and saveInteractive plots, logs, input files, artifact manifests, project archive

Calculation wizards

Each wizard follows the same basic pattern: choose a source, configure parameters, run locally or submit to HPC, inspect live output, then save or open an interactive viewer. Many wizard settings are remembered per project in browser local storage.

SCF, relaxation, and SOC wizard

Purpose

Builds a pw.x input from a CIF-derived or optimized structure and runs SCF-like workflows. Presets include standard SCF, phonon-ready SCF, relaxation, and SOC.

Prerequisites

QE pw.x, pseudopotentials for each element, and a valid CIF. SOC requires fully relativistic pseudopotentials.

Steps

  1. Import a CIF or start from a project CIF variant.
  2. Choose conventional or primitive cell when available and inspect the 3D unit cell.
  3. Select pseudopotentials manually or with SSSP/PAW/USPP/NCPP helpers.
  4. Review wavefunction and charge-density cutoffs. If QCortado infers a cutoff from companion metadata, treat it as a starting point for convergence testing.
  5. Set k-point grid and offsets. Metals usually need smearing and denser sampling than insulators.
  6. Configure advanced options: occupations, smearing, total charge, magnetism, noncollinear angles, SOC, DFT+U, exchange-correlation override, convergence thresholds, mixing, diagonalization, and optional relaxation thresholds.
  7. Run locally, queue locally, or submit directly to HPC.

Outputs

Saved SCF/optimization calculations include QE input, output, parsed convergence, Fermi energy when present, optimized structure for relax runs, magnetism viewer data when available, and source metadata for downstream calculations.

Common problems

  • No pseudopotential found: confirm the selected local or remote pseudo directory and filename conventions.
  • SOC filter empties the list: use fully relativistic pseudopotentials.
  • SCF does not converge: adjust mixing, smearing, k mesh, cutoffs, occupations, and starting magnetization.
  • Relaxed structure looks wrong: inspect the structure viewer before using it downstream.

Band structure wizard

Purpose

Runs a band-path NSCF calculation with pw.x, then bands.x, and optionally projwfc.x for fat-band projections.

Prerequisites

A saved converged SCF calculation with enough local or remote restart data for the chosen execution mode.

Steps

  1. Select the source SCF. QCortado shows tags such as HPC and downloaded state.
  2. Choose or edit a high-symmetry k path in the Brillouin-zone viewer.
  3. Set NSCF controls: number of bands, convergence threshold, electron max steps, occupations, smearing, diagonalization, starting potential/wavefunction, and verbosity.
  4. Set bands.x options such as filband, symmetry labels, and overlap-based ordering.
  5. Enable orbital projections when projwfc.x is available and fat-band analysis is needed.

Outputs

The bands viewer plots energy versus k distance, supports Fermi or VBM zeroing, band gap overlays, comparison overlays, high-symmetry labels, projection coloring, and saved viewer metadata.

Common problems

  • Missing bands.dat.gnu: bands.x failed or wrote a different filename.
  • Bad band ordering: compare symmetry and overlap settings; complex crossings may need manual interpretation.
  • Local run blocked by HPC source: download the full source bundle or switch to HPC mode.

Electronic DOS wizard

Purpose

Runs a uniform-grid NSCF calculation with pw.x, then calculates the electronic density of states with dos.x.

Prerequisites

A saved SCF source and pseudopotentials available in the active local or remote environment.

Key controls

  • DOS k mesh, typically denser than the SCF mesh.
  • Energy step DeltaE, Gaussian broadening/degauss, and optional energy window.
  • Local MPI or HPC Slurm resources.

Outputs

The DOS viewer plots total DOS against energy and can reference the saved SCF Fermi energy.

Common problems

  • Noisy DOS: increase k mesh density or adjust broadening.
  • Wrong Fermi alignment: confirm the source SCF is the intended reference.

Fermi surface wizard

Purpose

Runs an NSCF calculation on a uniform Fermi grid with pw.x and saves Fermi-surface artifacts for QCortado and optional FermiSurfer viewing.

Prerequisites

A metallic or near-metallic source SCF, selected pseudopotentials, and optional FermiSurfer executable path.

Key controls

  • Fermi k grid and Monkhorst-Pack offsets.
  • Optional number of bands, NSCF convergence threshold, mixing beta, occupations, smearing, degauss, and verbosity.

Outputs

Saved Fermi-surface calculations preserve parsed Fermi energy context and generated artifacts. The project dashboard can launch external FermiSurfer when configured.

Common problems

  • Surface missing or sparse: increase k mesh and ensure enough bands cross the Fermi level.
  • External viewer does not open: verify the configured FermiSurfer path.

Hubbard LRT wizard

Purpose

Runs QE hp.x to calculate Hubbard parameters by linear response from a saved SCF source.

Prerequisites

A saved SCF calculation with Hubbard-compatible metadata and QE hp.x available locally or remotely.

Key controls

  • q mesh nq1 nq2 nq3, perturbation selection, conv_thr_chi, max iterations, verbosity, and response thresholds.
  • Advanced controls include no_metq0, equivalent-q skipping, docc_thr, ethr_nscf, thresh_init, alpha_mix, nmix, and max seconds.

Outputs

QCortado saves parsed Hubbard U data, raw output, input files, and an occupations viewer when the run exposes occupation data.

Common problems

  • No U values parsed: inspect hp.x output and confirm the perturbations completed.
  • HPC rank behavior surprises: QCortado adds conservative defaults for hp.x where needed, including diagonalization and pencil-decomposition handling.

Phonon wizard

Purpose

Runs a phonon pipeline: ph.x on a q grid, q2r.x for force constants, and optional matdyn.x calculations for phonon DOS and dispersion.

Prerequisites

A phonon-ready SCF source, usually from a relaxed structure with tight convergence. EPW-ready phonons require extra saved artifacts.

Steps

  1. Select a source SCF. Prefer the wizard's phonon-ready SCF preset for new work.
  2. Set the q grid and solver controls: tr2_ph, recover, trans, epsil, fpol, Raman, verbosity, mixing, q/irreducible ranges, and electron-phonon mode.
  3. Choose save policy. Plot-only saves are compact; EPW-ready saves retain required perturbation artifacts.
  4. Optionally calculate phonon DOS and dispersion with matdyn.x, choosing ASR and q path controls.

Outputs

The phonon viewer can show dispersion or DOS, switch frequency units between cm-1 and THz, and focus on full, acoustic, or optical modes.

Recovery

QCortado can repair saved phonon metadata from retained work directories and can recover remote phonon runs when the active HPC profile can still see the remote workspace or project archive path.

Common problems

  • Imaginary modes: inspect structural stability, q-grid convergence, ASR choice, and relaxation quality.
  • EPW prerequisites missing: re-run phonons with EPW-ready artifact retention and required fildvscf behavior.

Wannier90 wizard

Purpose

Prepares a Wannier workflow: wannier90.x -pp, pw.x NSCF on a full mesh, pw2wannier90.x, and final wannier90.x.

Prerequisites

A saved scalar SCF. The v1 workflow rejects sources with SOC, noncollinearity, DFT+U, or unsupported vdW flags. Wannier90 and pw2wannier90.x must be available.

Steps

  1. Select a Wannier-ready SCF source.
  2. Set the zero-shift Monkhorst-Pack NSCF mesh, interpolation path, total interpolation points target, seed name, and optional number of bands.
  3. Add element-targeted or site-targeted orbital projections. QCortado expands projections into the implied number of Wannier functions.
  4. Use a saved band calculation overlay to tune num_wann, num_bands, exclude_bands, and disentanglement/frozen windows.
  5. Run locally or on HPC and inspect convergence, spreads, centers, quality warnings, and artifacts.

Outputs

Saved Wannier results include interpolated bands, spreads, centers, convergence data, Fermi alignment, quality issues, and artifact manifests such as .win, .wout, _band.dat, and Hamiltonian files when available.

Common problems

  • Missing source Fermi level: re-run or repair the source SCF before transport-quality Wannierization.
  • Wannier manifold misses E_F: choose projections near the Fermi level, increase num_bands, and tune windows against a saved band plot.
  • Disentanglement fails: widen the outer window, check excluded bands, and verify the projection set spans the target bands.

BoltzWann transport wizard

Purpose

Copies saved Wannier artifacts, writes a transport-specific Wannier input, and runs postw90.x with BoltzWann transport enabled.

Prerequisites

A saved, transport-quality Wannier calculation with a source Fermi energy and artifact bundle.

Key controls

  • Source Wannier selection, sortable by recency or quality signals.
  • BoltzWann k mesh and optional 2D transport direction.
  • Local or HPC run resources. Remote postw90.x is derived from the configured remote Wannier90 path unless specified by the cluster environment.

Outputs

The transport viewer plots conductivity, Seebeck, electronic thermal conductivity, transport distribution function, tensor components, chemical-potential slices, and temperature slices parsed from upstream tables.

Common problems

  • Nearly zero transport: the selected Wannier bands likely do not span the Fermi level.
  • postw90.x not found: configure the Wannier90 executable path so QCortado can derive the sibling postw90.x.
  • EPW transport confusion: this wizard is BoltzWann-based. EPW transport is configured in the EPW wizard.

EPW wizard

Purpose

Builds and runs epw.x workflows for electron-phonon coupling, phonon linewidths/alpha2F, electron self-energy, EPW transport, and superconductivity outputs.

Prerequisites

A saved phonon calculation with q-grid metadata and EPW-ready artifacts. A saved Wannier source is optional for some EPW workflows but important for Wannier-derived interpolation context.

Steps

  1. Select the phonon source and optional Wannier source.
  2. Choose goals: coupling, phonon linewidths/alpha2F, electron self-energy, transport mobility, or superconductivity.
  3. Set prefix, outdir, dvscf_dir, Wannier directory, fine k/q meshes, fsthick, degaussw, nbndsub, mode, runtime pools, and max seconds.
  4. Set EPW reuse flags such as epbwrite, epbread, epwwrite, and epwread.
  5. Choose HPC artifact sync mode: minimal, EPW-ready, or full.
  6. Add expert keyword overrides only when you understand the upstream EPW input variable.

Outputs

The EPW viewer includes summary metrics, transport tables, superconductivity/Eliashberg summaries, spectral and self-energy tables, parsed numeric artifacts, warnings, files, and raw log inspection.

Common problems

  • epw.x missing: QCortado checks the QE bin directory and EPW/bin fallback layouts; many QE builds require EPW to be compiled separately.
  • No structured results parsed: inspect Files + Log. EPW may have completed without emitting a supported table family for the selected goals.
  • Transport tables absent: confirm scattering/transport EPW flags and carrier/scissor details in advanced overrides.

Viewers and result interpretation

Bands viewer

Plots electronic or phonon bands, high-symmetry markers, zero-reference modes, band-gap overlays, comparisons, and fat-band projections.

DOS viewer

Plots electronic DOS against energy with Fermi reference context.

Wannier viewer

Compares interpolated Wannier bands with source context and displays spread/convergence details.

Transport viewer

Switches metrics, components, temperature/chemical-potential slices, heatmaps, and transport distribution diagnostics.

Phonon viewer

Shows dispersion and DOS with frequency unit switching and mode focus.

EPW viewer

Groups EPW summary, transport, superconductivity, spectral data, chartable artifacts, warnings, files, and logs.

A separate QCortado Viewer build can sync read-only project snapshots from an HPC-hosted viewer library. The main app can publish that library automatically after project mutations when an active HPC profile is configured.

HPC configuration and remote execution

HPC mode submits self-contained calculation bundles to a remote Slurm cluster over SSH. QCortado uploads inputs and scripts to a remote workspace, submits with sbatch, polls scheduler state, streams useful status lines, and syncs artifacts back to the project record.

Profile fields

FieldMeaning
Name, cluster, host, port, usernameConnection identity shown in settings and used for SSH/SCP.
Auth methodSSH key or password. Password/secret persistence uses macOS Keychain where supported; otherwise secrets are session-only.
Remote QE bin directoriesDefault, CPU-specific, and GPU-specific directories. QCortado chooses by resource type.
Remote pseudo directoriesDefault, CPU-specific, and GPU-specific pseudopotential directories.
Remote EPW pathOptional explicit epw.x. If omitted, QCortado checks QE bin and EPW/bin fallbacks.
Remote Wannier90 pathPath or command for wannier90.x. Remote postw90.x is derived as a sibling when needed.
Workspace rootScratch area for active remote job bundles.
Project rootRemote archive area for persistent calculation artifacts and viewer-library snapshots.
Resource modeCPU-only, GPU-only, or both. Wizards constrain run settings to what the profile supports.
Launchersrun or mpirun. Optional resource-specific extra args are appended.

Run settings

Each HPC-capable wizard shows resource settings before submission. CPU and GPU templates can set partition, walltime, nodes, tasks, CPUs per task, memory, GPU count, QOS, account, constraint, module/setup preamble, and extra SBATCH lines. QCortado previews the generated Slurm script read-only before submission.

Typical generated shape

#SBATCH --job-name=qcortado-...
#SBATCH --output=slurm.out
#SBATCH --error=slurm.err
#SBATCH --partition=short
#SBATCH --time=02:00:00
#SBATCH --nodes=1
#SBATCH --ntasks=1

# User module/setup preamble
module load quantum-espresso

srun "$QE_BIN/pw.x" -in pw.in > pw.out 2>&1

Activity, recovery, and cleanup

  • HPC activity: shows active remote tasks, scheduler state, remote job IDs, remote nodes, generated Slurm scripts, and stage output.
  • Node activity: queries Slurm node and queue snapshots for the active profile and supports filters for node type, partition, state, resources, and queue scope.
  • Artifact download: saved HPC calculations can download task or calculation artifacts later if remote paths are still reachable.
  • Headless attach: QCortado can list and attach compatible remote jobs when it can find expected QCortado metadata.
  • Remote phonon recovery: scans workspace/project archive paths for recoverable phonon runs.
  • Orphan cleanup: removes remote QCortado directories not linked to saved calculations. Use this only after confirming they are not active jobs.
  • Viewer library: publishes read-only project snapshots under a remote _qcortado_viewer_library directory and syncs them into the Viewer app.
Security note: HPC credentials are powerful. Prefer SSH keys with passphrases, avoid storing shared account passwords, and review generated Slurm scripts before submitting jobs that load modules or run custom preambles.

QE tool matrix

QCortado workflowExecutablesMain saved resultUpstream reference
SCF, relax, SOC pw.x Convergence, energy, Fermi level, optimized structure, magnetism, source metadata INPUT_PW
Band structure pw.x, bands.x, optional projwfc.x Band energies, high-symmetry markers, projection groups INPUT_BANDS, INPUT_PROJWFC
Electronic DOS pw.x, dos.x DOS table and Fermi reference INPUT_DOS
Fermi surface pw.x, optional FermiSurfer Fermi-grid NSCF artifacts INPUT_PW
Hubbard LRT hp.x Linear-response Hubbard parameters INPUT_HP
Phonons ph.x, q2r.x, optional matdyn.x Dynamical matrices, force constants, phonon DOS, dispersion INPUT_PH, INPUT_Q2R, INPUT_MATDYN
Wannier90 wannier90.x, pw.x, pw2wannier90.x Interpolated bands, spreads, centers, Hamiltonian artifacts, quality issues INPUT_pw2wannier90, Wannier90 PWscf interface
BoltzWann transport postw90.x Conductivity, Seebeck, thermal conductivity, TDF tables Wannier90 docs
EPW epw.x, sometimes pw.x for coarse NSCF rebuild Electron-phonon coupling, linewidths, self-energy, transport, superconductivity, parsed artifacts EPW documentation

Troubleshooting

QCortado says an executable is missing.

Confirm the configured QE bin directory contains the executable needed by the wizard. EPW may live in EPW/bin depending on your build; QCortado checks common fallbacks but cannot compile EPW for you.

Pseudopotential metadata is incomplete.

Some UPF files do not embed recommended cutoffs or orbital metadata. QCortado can infer conservative ratios from companion values for some pseudo types, but you should run convergence tests and prefer curated libraries when possible.

PSLibrary files trigger projection or atomic-orbital errors.

QCortado includes local and remote repair helpers for a known malformed tenth atomic wavefunction tag pattern in PSLibrary-style UPF files. Use the repair action from settings when the error hint appears.

A dependent local workflow cannot use an HPC source.

Downstream local workflows need the full source bundle locally. Use the offered download action or switch execution mode to HPC and run the dependent calculation remotely.

HPC submission fails before Slurm starts.

Run profile connection and environment validation. Check SSH credentials, remote workspace write access, remote QE/pseudo paths, and whether sbatch and squeue are available in the remote shell.

HPC job runs but results do not sync.

Inspect the activity panel, remote workdir, and artifact sync warnings. For large EPW or phonon runs, use EPW-ready or full sync if minimal artifacts are insufficient.

Phonon run completed but viewer data is missing.

Use saved phonon recovery. QCortado can reconstruct metadata and plot files from retained work directories when q2r.x and matdyn.x outputs are still available.

Storage cleanup might delete too much.

Read each selected entry before deleting. Remote calculations can have linked HPC artifacts; deleting them removes the local saved record and the linked remote files QCortado can identify.

External references

Use these upstream references when checking the scientific meaning of QCortado controls.