The Python Sidecar — Qemica's Engine Environment

Every chemistry calculation runs in a dedicated Python environment — the sidecar — that you create once during installation (see Getting Started). After that one-time setup you never interact with it directly; it loads automatically when you run a job. Your chemistry computations run entirely on your machine; the sidecar only reaches the network for explicit actions you trigger — fetching a structure from PubChem, installing an optional capability, or running on IBM Quantum hardware.

What it includes

  • The uv-created environment at ~/Library/Application Support/Qemica/engine/.venv (macOS; equivalent per-user paths elsewhere), running chemistry computations in the background via the installed quchemy package.
  • PySCF for classical electronic structure, OpenFermion for the quantum methods, and geomeTRIC for geometry optimization, transition states, IRC, and relaxed scans.
  • RDKit (molecular structure and SMILES), cclib (parsing external calculation outputs), and — as optional installs — Open Babel (extra file formats), Qiskit (circuit export and IBM hardware), qiskit-addon-sqd + ffsim (SQD), dftd3/dftd4 (dispersion), and torch + mace-torch (the MACE ML potential).

How it is used

  • When you click Submit/Run, Qemica invokes the sidecar to execute your calculation.
  • It processes your geometry, basis set, and method choices and returns structured results — energies in Hartree, forces in Hartree/Bohr.
  • If a capability is unavailable (for example 3D embedding without RDKit), the sidecar reports what is installed and Qemica disables those controls with a tooltip explaining what is missing.

How Qemica finds it

  • Auto-detect: on startup Qemica probes the per-user engine environment (Application Support/Qemica/engine/.venv on macOS and the equivalent data directory elsewhere) and falls back to python3 on your PATH if none is present.
  • If no engine is found, a setup dialog appears with an Install automatically button (macOS and Linux) that performs the whole setup for you, plus the exact commands for your OS with a Copy button and a Re-check button that probes again after a manual install.
  • Override: Config → Engines · Environment accepts an absolute path to a Python interpreter or to a virtual-environment root; press Enter to re-probe.
  • Windows runs the engine through WSL2 by default — the interpreter setting then refers to the Linux-side Python inside WSL.
  • Version match: each Qemica release expects a matching quchemy engine version; if yours differs, a notice points you at the update — re-run the uv pip install line from Getting Started with the new wheel URL the app shows.

Installing optional capabilities

  • Config → Engines shows the Python sidecar capabilities as clickable status pills (installed / missing per package) with one-click install for anything missing — Open Babel formats, D3/D4 dispersion, Qiskit, the IBM Quantum runtime, SQD, and the MACE ML potential.
  • Installs go into your engine venv (architecture-aware, e.g. arm64-native dispersion libraries on Apple Silicon); restart the app afterwards so it re-probes.
  • The same extras are available from the command line against your engine environment — quchemy is not on PyPI, so use the direct-URL form: uv pip install --python <engine python> 'quchemy[qiskit] @ <the wheel URL shown in the app>' (likewise [ibmq], [sqd], [formats], [dispersion]).

References

  1. PySCFSun et al., J. Chem. Phys. 153, 024109 (2020); Sun et al., WIREs Comput. Mol. Sci. 8, e1340 (2018)
  2. MACEBatatia, Kovács, Simm, Ortner & Csányi, NeurIPS 35 (2022), arXiv:2206.07697
  3. cclibO'Boyle, Tenderholt & Langner, J. Comput. Chem. 29, 839 (2008)
  4. RDKitLandrum et al., RDKit: Open-source cheminformatics
  5. geomeTRICWang & Song, J. Chem. Phys. 144, 214108 (2016)
  6. Open BabelO'Boyle et al., J. Cheminform. 3, 33 (2011)
  7. OpenFermionMcClean et al., Quantum Sci. Technol. 5, 034014 (2020)
  8. QiskitJavadi-Abhari et al., arXiv:2405.08810 (2024)