QUARKS - QUAntum woRKflow Suite

A comprehensive computational chemistry pipeline for automated high-throughput ligand screening, from molecular design to data extraction.

Overview

QUARKS is a modular pipeline that integrates multiple computational chemistry tools into a seamless workflow:

1. Ligand Functionalization: Design and generate molecular variants
2. Conformer Search: XTB/CREST-based conformational sampling
3. Input Generation: Automated ORCA input file creation
4. Job Management: Resource-aware ORCA calculation execution
5. Data Extraction: Energy and molecular descriptor analysis

Features

• 🧪 Complete Pipeline: From base ligand to analyzed data
• ⚡ High-Throughput: Batch processing with parallel execution
• 🎯 Resource-Aware: Intelligent CPU and memory management
• 🖥️ Dual Interface: Both GUI and CLI for all tools
• 📊 Data Extraction: Energies, %Vbur, σ-donation, and more
• 🔧 Modular: Use individual components or the full pipeline

📚 Documentation for Beginners

New to QUARKS? Start here:

1. INSTALLATION_GUIDE.md - Complete step-by-step installation (no experience required!)
2. USER_MANUAL.md - How to use all 5 programs with examples
3. START_HERE.md - Quick 30-second launch guide

Already installed? Just run:

./launch.sh

---

🚀 Quick Start

The easiest way to launch QUARKS programs:

cd /Users/thomasquaid/Projects/QUARKS
./launch.sh

This opens an interactive menu to launch any QUARKS program.

Or launch programs directly:

./launch_conformer.sh        # Conformer Search GUI
./launch_orca_manager.sh     # ORCA Job Manager GUI
./launch_input_generator.sh  # Input File Generator
./launch_screening_tool.sh   # Ligand Screening Tool GUI
./launch_extractor.sh        # Data Extractor CLI

---

Installation

Prerequisites

External Tools:

• ORCA 6.0+ (DFT calculations)
• XTB 6.6+ (semi-empirical optimization)
• CREST (conformer search)

Python Environment Setup

# Create conda environment with required chemistry package
conda create -n quarks-env python=3.11
conda activate quarks-env
conda install -c conda-forge scine-molassembler

# Install QUARKS package
cd /Users/thomasquaid/Projects/QUARKS
pip install -e .

# Install additional dependencies
pip install numpy scipy pandas matplotlib PySide6 psutil pyyaml cclib pillow rdkit py3Dmol

Quick Start

Complete Pipeline Workflow

# 1. Functionalize a base ligand (GUI)
python -m quarks.conformer.gui

# 2. Run conformer search
quarks conformer --input functionalized/ --output conformers/ --charge 1 --uhf 0

# 3. Generate ORCA inputs
quarks input-gen --input conformers/ --output orca_inputs/ --functional PBE0 --basis def2-TZVP

# 4. Run ORCA calculations (GUI with queue management)
quarks-orca

# 5. Extract results
quarks extract energy --input orca_outputs/
quarks extract descriptors --input orca_outputs/

Individual Tool Usage

Conformer Search:

quarks conformer --input molecules/ --output refined/ --charge 1 --frozen-atoms 25

Input Generation:

quarks input-gen -i structures/ -o inputs/ -f B3LYP -b def2-TZVP --freq --cpcm water

Data Extraction:

quarks extract energy --input calculations/
quarks extract descriptors --input calculations/

Project Structure

quarks/
├── core/              # Shared molecular manipulation and chemistry utilities
├── gui/               # Shared PySide6 GUI components
├── conformer/         # XTB/CREST conformer search workflows
├── orca_manager/      # ORCA job queue and resource management
├── input_generator/   # ORCA input file generation
├── extractor/         # Energy and descriptor extraction
└── pipeline/          # Full workflow orchestration

Documentation

• Installation Guide
• User Guide
  • Conformer Search
  • ORCA Manager
  • Input Generator
  • Data Extractor
• API Reference
• Examples

Example Workflow: Zinc-Cyclen Screening

from quarks.core import load_molecule_from_file, MoleculeFunctionalizer
from quarks.conformer import StructureRefinement
from quarks.input_generator import OrcaInputGenerator
from quarks.extractor import energy_extractor

# 1. Load base ligand
base_ligand = load_molecule_from_file("cyclen.xyz")

# 2. Functionalize (manual GUI step or programmatic)
# ... generates functionalized_ligands/

# 3. Conformer search
refiner = StructureRefinement(
    base_dir="conformers/",
    charge=1,
    uhf=0,
    frozen_atoms=[25]  # Zn atom
)
refiner.process_molecule("functionalized_ligands/cyclen_CH3.xyz")

# 4. Generate ORCA inputs
generator = OrcaInputGenerator()
generator.generate_input_files(
    xyz_folder="conformers/compiled_conformers/",
    output_folder="orca_inputs/",
    functional="PBE0",
    basis_set="def2-TZVP",
    charge=1,
    multiplicity=1
)

# 5. Run calculations (via GUI or cluster submission)
# ...

# 6. Extract data
energy_extractor.extract_energies_cli("orca_outputs/", "energies.csv")

Citation

If you use QUARKS in your research, please cite:

@software{quarks2025,
  title = {QUARKS: QUantum chemistry Automated Research Kits},
  author = {QUARKS Development Team},
  year = {2025},
  url = {https://github.com/quaidtUC/quarks}
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

QUARKS integrates and builds upon several excellent computational chemistry tools:

• ORCA - DFT calculations
• XTB - Semi-empirical methods
• CREST - Conformer search
• SCINE Molassembler - Molecular assembly
• RDKit - Cheminformatics
• cclib - Parsing computational chemistry outputs

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---

QUARKS - Accelerating computational chemistry research through automation.