Projects & Files

Qemica stores each project as a plain folder of human-readable files — project.json, .xyz/.mol structures, and cached result.json documents. This file-first design keeps your work portable and free of database lock-in; an SQLite index provides fast search but is fully disposable and rebuilt from the files whenever needed.

What a project is

A project is a named folder on disk containing every molecule, calculation configuration, and result for a study. Projects live in user://projects/ (or a custom directory). The files — not any database — are the source of truth.

  • Copy or share the folder and Qemica loads it unchanged on any machine — no lock-in to Godot, SQLite, or a proprietary format.
  • project.json carries project metadata (format_version, name, description, tags) and the molecule list — the single source of truth for structure.
  • <molecule_name>.xyz holds 3D atomic coordinates in standard XYZ format, one file per molecule.
  • result_<mol_id>.json caches calculation results (energies, orbitals, vibrations, excited states, NMR, MD), created only after a run.

How molecules and results are stored

  • Each molecule is stored twice: a summary in project.json (name, charge, multiplicity, molecular graph, canonical SMILES and InChIKey when RDKit is available, plus 2D sketch coordinates) and full coordinates in its .xyz file.
  • Result documents (schema_version 1) capture all Analyze data and reference companion .cube files for orbital and density isosurfaces.
  • Every result carries provenance — engine name/version, RNG seed for reproducible quantum runs, method/basis/functional, wall-clock time, and host.
  • Units are always tracked: an energy_unit field is present so tabs read units rather than assuming them.

Import, export, and deduplication

  • Import: .xyz, .mol, .sdf, .pdb (read with RDKit) and the Open Babel-exclusive .mol2, .cif, .cml; plus SMILES strings and PubChem queries (a compound name or CID fetches an .sdf online).
  • Export: .xyz geometry from the Modeler or Geometry tab, and CSV for reaction profiles, frequency tables, and excited-state data from the Analyze tabs.
  • Deduplication: a canonical InChIKey is computed on save (with RDKit); an identical structure updates in place rather than duplicating.
  • Search by canonical SMILES, molecular formula (e.g. C6H6), or contained elements.
The disposable SQLite index. Behind the scenes, an SQLite database indexes projects by formula, InChIKey, element, and name for fast search. It is never a system of record: it is created on first launch, safe to delete, and rebuilt from the canonical project files if it becomes corrupted or out of sync. Schema upgrades drop and rebuild the index rather than migrating it, so your data is never at risk.

Working across multiple projects

  • Create a project from the left panel's project picker → ＋ New project… (a name is all it takes).
  • Switch projects from the left panel; the Modeler and Analyzer immediately show that project's molecules.
  • Share or back up by copying the entire folder — no database export needed.
  • Move everything to a new computer with Settings → Paths → Device migration: export projects, results, and settings as a single zip and import it on the other machine (credentials never ride along; already-existing items are skipped).
  • Merge by copying molecule .xyz files and their project.json entries into another project folder.