VirtualLab-CC

VirtualLab_CC

An LLM-Augmented Virtual Laboratory for Automated Computational Chemistry Research

Archived software (release v1.1.0): DOI 10.5281/zenodo.21396720

VirtualLab_CC is an AI-driven framework that pairs large language models (Claude, Anthropic) with quantum chemistry software (Gaussian 16, ORCA, MRCC, OpenMolcas, CREST) to run the full computational chemistry research workflow — from literature review, through calculation execution on HPC clusters, to result analysis and manuscript preparation. A human principal investigator (PI) supervises the pipeline and approves every decision at defined checkpoints.

This repository accompanies the paper:

Kieninger, M.; Segovia, M.; Vega-Teijido, M.; Katz, A.; Martinez, A.; Vuan, E.; Irving, K.; Ventura, O. N. "VirtualLab_CC: An LLM-Augmented Virtual Laboratory for Automated Computational Chemistry Research." Artificial Intelligence in Chemistry (2026). DOI: 10.0000/PLACEHOLDER-DOI (to be updated on acceptance).

Overview

VirtualLab_CC organizes computational chemistry research around three ideas:

1. A three-layer architecture that separates research data, orchestration, and a personal knowledge base.
2. A gated project lifecycle (G0–G5) with mandatory human approval at the points where resources or scientific claims are committed.
3. A library of composable skills that the language model invokes to perform concrete tasks — literature search, cluster synchronization, result extraction, peer review, citation checking, and more.

Three-Layer Architecture

┌───────────────────────────────────────────────┐
│  PI (human oversight, approves every gate)     │
├───────────────────────────────────────────────┤
│  Orchestrator (ccbg-orchestrator)              │
│    ├── Project lifecycle gates (G0–G5)         │
│    ├── Calculation stages (S0–S5)              │
│    └── Agent roster (CC_R01–CC_R10)            │
├───────────────────────────────────────────────┤
│  Skill layer (25 specialized skills)           │
│    ├── Lab operations                          │
│    ├── Quality & review                        │
│    ├── Research tools                           │
│    ├── Manuscript & reporting                   │
│    └── Meta / system                            │
├───────────────────────────────────────────────┤
│  HPC cluster                                    │
│    SLURM + Gaussian 16 / ORCA / MRCC /          │
│    OpenMolcas / CREST                           │
└───────────────────────────────────────────────┘

Gated Lifecycle (G0–G5)

Every project advances through six gates. The orchestrator never crosses a gate on its own; the PI reviews and approves each transition.

Gates (G0–G5, project lifecycle) are orthogonal to calculation stages (S0–S5, the state of an individual calculation). A project at G3 may still have calculations at several different stages.

Agent Roster (CC_R01–CC_R10)

Work is distributed across ten role-specialized agent profiles. The PI sits above the roster and approves all actions.

The roster matches Table 2 of the accompanying paper. The PI (CC_R10) holds final authority and approves every gate transition. See framework/agent_roster.md for the full definitions.

How Skills Plug In

Each skill is a self-contained module with a SKILL.md specification (name, description, trigger phrases, instructions) plus any supporting scripts. The language model selects a skill when a request matches its description, then follows the steps inside. Skills are the unit of capability: adding a behaviour means adding a skill folder, not modifying the core.

This release ships 25 skills, listed below. This list is generated from the skills/ directory of this release and matches Table 3 of the accompanying paper exactly.

Lab operations

Quality & review

Research tools

Manuscript & reporting

Knowledge vault & schemas

Skills provided by an external plugin. The runtime additionally loads general-purpose skills that are not part of this repository and are therefore not counted above: render-molecule, source-validator, decision-journal, and skill-creator. They are supplied by an installed skills plugin, not by VirtualLab_CC, and are listed separately in the paper for the same reason.

HPC Integration

VirtualLab_CC drives calculations on a SLURM-managed cluster over SSH. The framework supports:

• Engines: Gaussian 16, ORCA, MRCC, OpenMolcas, and CREST conformer sampling.
• Job management: SLURM script generation with consistent job-name prefixes, per-project submission caps, and a job queue that drains automatically.
• Scratch hygiene: every job stages temporary files into node-local scratch; a guard script aborts the run if scratch is missing or unwritable, preventing silent home-directory overflow.
• Synchronization: cluster-sync pulls recently modified outputs after every submission round, excluding large binary artifacts (*.chk, *.gbw, *.wfn, scratch temporaries).
• Result parsing: result-extractor converts engine output into standardized energies, geometries, frequencies, T1 diagnostics, and convergence flags.

The cluster connection is configured by copying the template at skills/cluster-sync/references/references/cluster_config_template.env and filling in host, user, and remote-base details. SSH keys are never stored in the repository.

Repository Structure

VirtualLab_CC/
├── skills/                    # 25 specialized skills (each with SKILL.md)
│   ├── ccbg-orchestrator/     # Central workflow orchestrator
│   ├── cluster-sync/          # HPC cluster synchronization
│   ├── novelty-check/         # Prior-art search at G0→G1
│   ├── manuscript-reviewer/   # Automated peer review at G4
│   ├── citation-validator/    # DOI verification for references
│   ├── result-extractor/      # Gaussian/ORCA → structured data
│   ├── arxiv-search/          # ArXiv literature search
│   ├── pubmed-search/         # PubMed literature search
│   ├── pubchem-search/        # PubChem compound lookup
│   ├── rdkit-tools/           # RDKit molecular operations
│   └── ...                    # See skills/ for the full set
├── framework/
│   ├── lifecycle/             # Gate and stage definitions
│   ├── methods/               # Method protocol library (METH_001–007)
│   ├── scripts/               # Cluster management scripts
│   ├── agent_roster.md        # Agent role definitions (CC_R01–CC_R10)
│   └── lab_charter.md         # Lab operating principles
├── docs/                      # Additional documentation
├── examples/                  # Example configurations
├── CITATION.cff               # Citation metadata
├── LICENSE                    # MIT License
└── README.md

Method Protocols

The framework/methods/ directory contains standardized computational protocols (METH_001–METH_019 in the live laboratory; the subset relevant to the published case study is shipped here):

• METH_001 — General DFT optimization for organic molecules
• METH_002 — Criegee–terpene PES mapping (the case study in the paper)
• METH_003 — PFAS electrode degradation
• METH_004 — Cyanobacterial VOC OH-oxidation
• METH_005 — Selenenic acid thermochemistry
• METH_006 — Chalcogen triad spectrokinetics
• METH_007 — 2-Haloethanol IR and kinetics

Requirements

• LLM backend: Claude (Anthropic) via Claude Code or Cowork
• Quantum chemistry: Gaussian 16 and/or ORCA; optional MRCC, OpenMolcas, CREST
• HPC access: SLURM-managed cluster with SSH access
• Python: 3.10+ with RDKit, NumPy, cclib
• Optional: PyMOL (molecular visualization), Obsidian (knowledge vault)

Getting Started

1. Clone this repository.
2. Copy skills/cluster-sync/references/references/cluster_config_template.env to your working directory as cluster_config.env and fill in your cluster details.
3. Configure your Claude Code or Cowork environment to load skills from the skills/ directory.
4. Set up SSH key-based authentication to your HPC cluster.
5. Create your first project with the add-new-project skill.

Release and reproducibility

The skill registry above, the gate names (G0–G5), and the agent roster (CC_R01–CC_R10) are identical to Table 3, Section 2.3, and Table 2 of the accompanying paper respectively. All three are pinned to release v1.1.0 of this repository; cite that release (or its Zenodo DOI) when referring to a specific version of the system.

Citation

If you use VirtualLab_CC in your research, please cite the paper above and the software via the metadata in CITATION.cff. GitHub and Zenodo both read this file, so the "Cite this repository" button will produce a correctly formatted reference.

License

MIT — see LICENSE.

Acknowledgments

Developed at the Computational Chemistry and Biology Group (CCBG), DETEMA, Facultad de Química, Universidad de la República, Montevideo, Uruguay. HPC resources provided by the CCBG beorn cluster. Financial support: PEDECIBA, CSIC (Universidad de la República) and ANII.