English · 한국어

ORCA_auto is a queue-based runner for ORCA on Linux/WSL. It provides background execution, queue scheduling, and structured result tracking for ORCA calculations and downstream tools.

Key Features

• Background execution. Submissions are committed to disk and run under systemd workers independently of the submitting terminal session.
• Structured status & inspection. Query job progress and system status via orca_auto queue list --json and orca_auto service status --json. Terminal machine.json records provide structured outcomes and artifact receipts for downstream tools and scripts.
• Explicit recovery. Worker or host interruptions follow explicit, verified recovery paths without automatic retries of failed chemistry runs.

Getting started

Python 3.11+, Linux/WSL2, and a separately installed ORCA engine are required. Workers are managed with systemd.

python -m pip install orca_auto==10.2.1

• Installation details — install the standalone ORCA package.
• Quickstart guide — configure settings, start background services, and submit your first calculation.

Existing 10.1.x installations follow the 10.2 upgrade notes: expanded queue Detail labels and rejection of incomplete final coordinates. Existing 10.0.x installations upgrade with the 10.1 upgrade notes: the last frequency section now decides frequency evidence. Existing 9.0.x installations first follow the 10.0 upgrade guide: 10.0 changes what a completed run means. For upgrades from 8.x or earlier, see the 9.0 upgrade guide first, then the 10.0 upgrade guide. For 6.x or earlier, complete the 7.0 migration first, then follow the 9.0 upgrade guide.

Chemistry ecosystem

• Chemvas for drawing chemical structures,
• ORCA_auto for calculation execution and queue management, and
• Chemleaf for drafting research documents.

These are independent, local-first companion tools that connect through standard formats (machine.json, results bundles, and input files). How the tools connect →

Documentation

Command reference · Public contracts · Architecture · systemd services · Discord notifications · Slack notifications (new in 10.0.0; 9.0.x does not support Slack)

Development guide · Validation · Roadmap · Changelog

Citation · Contributing · Support · Security · Code of Conduct

How this was built

I'm a chemist, not a programmer. AI coding agents write the code in this repository. I decide what ORCA_auto should do, keep its public behavior written down in the public contracts, and set the checks a change must pass before it merges.

I don't review the code line by line, so a change is accepted on evidence, not on an agent's report that it works:

• make check runs lint, formatting, type checks, import-boundary checks, a bilingual documentation check and the full test suite with coverage. CI runs the same gate and validates emitted machine.json files with the bundled validator, a pinned copy of the shared machine-contracts v1 contract.
• A change to public behavior updates the contract document in the same change.
• A change to how ORCA_auto runs the engine also needs a bounded run with the real ORCA engine, judged by the calculation's own evidence such as termination, geometry convergence or frequencies (validation).
• High-impact changes, such as recovery, queue state and result correctness, get an independent adversarial review from a separate agent.