Troubleshooting & FAQ

Common issues and how to resolve them: locating the Python sidecar, dispersion failures on Python 3.14, understanding greyed-out features and Overview warnings, the Hartree-versus-kcal/mol unit convention, convergence tuning, importing external output, and recovering from hangs or crashes.

Sidecar not found and degraded capabilities

  • If you see 'sidecar failed' or 'python3: command not found', open Config → Engines · Environment and enter an absolute path to a Python interpreter or to a virtual-environment root (the app finds bin/python or Scripts\python.exe inside), then press Enter to probe.
  • By default the app auto-detects the per-user engine environment created during setup (see Getting Started); manual entry is only needed for a custom environment location such as conda.
  • Greyed-out options or '(feature unavailable)' tabs mean a package is missing: RDKit (2D sketch/embed/SMILES), cclib (external-output parsing), geomeTRIC (optimization/TS/IRC/scans), qiskit (quantum export), or torch + mace-torch (the MACE ML backend).
  • Check the capability pills under Config → Engines (installed / missing per package), install any missing capability with a click there, then restart so the app re-probes.

Dispersion correction fails on Python 3.14

  • On Apple Silicon, Python 3.14 gets an x86_64-only pyscf-dispersion wheel that cannot load, so D3/D3(BJ) may fail.
  • Qemica automatically falls back to the standalone arm64-native dftd3 and dftd4 libraries — transparent once the dispersion capability is installed (Config → Engines quick-install, or pip install '.[dispersion]').
  • If dispersion still fails on a Python 3.14 environment, uncheck dispersion and run plain DFT — or point Config → Engines at an environment where a dispersion backend is available.
  • On Linux, Windows, and Intel macOS the pyscf-dispersion wheels work normally and the shim is a no-op.

Reading Overview warnings

  • Amber warning rows below the Converged pill mean the job succeeded with degraded features or a fallback — the calculation is still valid and analysable, with no hidden data loss.
  • Examples: 'Hessian not computed; frequency analysis skipped', 'imported from external output file: gaussian.log', and atom-count mismatches.
  • To clear, re-run with corrected settings or accept the fallback if acceptable.
Units: Hartree vs kcal/mol.
  • Quantum calculations (HF/DFT/post-HF/VQE/QPE) report energy in Hartree (1 Ha = 627.509 kcal/mol = 27.2114 eV); orbital energies appear in eV.
  • Force-field and classical-MD energies (MMFF/UFF) are in kcal/mol; forces from quantum methods are in Hartree/Bohr.
  • Golden rule: the app encodes the unit in every result — read it from the result rather than assuming Hartree or kcal/mol.

Convergence, imports, and crashes

  • Poor SCF convergence: the Configure script preview is genuine and editable — set mf.max_cycle, tighten mf.conv_tol (e.g. 1e-10 for single points), or change the initial guess right in the preview and submit; check the Run live log for PySCF messages.
  • Import external output: the left panel's Import button loads result files from other quantum-chemistry packages via cclib as a new molecule — requires cclib, inherits its parser coverage, and is tagged 'imported from [filename]'.
  • If a job shows 'Running' indefinitely, check the live log, click Stop, and export a diagnostics bundle from Config → About → Export diagnostics.
  • If the sidecar crashes (job suddenly 'Failed'), read the job's log in the detail panel (Export log saves it), check the capability pills under Config → Engines for anything missing, verify disk space, and export diagnostics from Config → About.