VS-ORCA (Virtual Studio for ORCA Chemistry)

A comprehensive Visual Studio Code extension that transforms VS Code into a unified development environment for ORCA computational chemistry calculations. Streamline your workflow with intelligent input editing, one-click execution, automated output parsing, and interactive results visualization.

🎯 Problem Solved

Computational chemists using ORCA face a fragmented workflow:

• Input Creation: Text files prone to syntax errors (keyword typos, wrong multiplicity)
• Execution: Constant context switching to terminal for manual command execution
• Analysis: Massive output files (10k+ lines) requiring manual grep/scrolling to find energies

VS-ORCA unifies this workflow by bringing intelligent editing, execution, and automated parsing into VS Code.

✨ Features

📝 Intelligent Input Editor

Example:

! B3LYP def2-TZVP Opt TightSCF    # Auto-highlighted
%pal nprocs 8 end                  # Block syntax
* xyz 0 1                          # Coordinates highlighted
  C  0.0  0.0  0.0
*

🚀 Execution Engine

Workflow:

1. Open any .inp file
2. Press F5 (or click the ▶️ icon in the editor toolbar)
3. Output streams live to the ORCA output panel
4. Status bar shows real-time progress

📊 Output File Management & Analysis

Other Capabilities:

• Automatic Output Persistence: All calculation output saved to .out files
• Syntax Highlighted Output: Open .out files with color-coded sections
• Interactive Dashboard: Visual results with tables, metrics, and diagnostics
• TOC Sidebar: Collapsible Table of Contents with one-click navigation to sections
• Quick Navigation: Use Outline view or Ctrl+Shift+O to jump to sections
• CodeLens Actions: Click "Open Dashboard" at the top of any .out file for instant access
• Smart Diagnostics: Warnings and errors collected with line numbers
• Scroll Preservation: Dashboard context maintained during TOC navigation

🛠️ Installation

Prerequisites

• Visual Studio Code 1.85.0 or higher
• ORCA (computational chemistry software)

Quick Start

1. Install the Extension (Recommended via VS Code Marketplace):

   • Install from VS-ORCA on the VS Code Marketplace
   • Or clone the repository from GitHub

2. Install ORCA:

   • Option 1: Use the built-in Installation Wizard

     • Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
     • Run: "ORCA: Setup ORCA Installation Wizard"
     • Follow guided steps

   • Option 2: Automatic Detection

     • Run: "ORCA: Detect ORCA Installations"
     • Select from detected installations

   • Option 3: Manual Configuration

     • Open Settings and set orca.binaryPath
     • Example: /opt/orca/orca (Linux/macOS) or C:\orca\orca.exe (Windows)

3. Verify Installation:

   • Run: "ORCA: Validate ORCA Installation"

📖 Detailed installation instructions: See INSTALLATION.md

Install from Source

1. Clone the repository:

   git clone https://github.com/ductrung-nguyen/Orca-vscode.git
   cd Orca-vscode
   

2. Install dependencies:

   npm install
   

3. Compile the extension:

   npm run compile
   

4. Open in VS Code and press F5 to launch the extension in a new window.

Install from VSIX (Coming Soon)

You can download the VSIX file from the Release page of this repository, then run the following command:

code --install-extension vs-orca-0.1.0.vsix

⚙️ Configuration

Open Settings (Ctrl/Cmd + ,) and search for "ORCA":

Example settings.json:

{
  "orca.binaryPath": "/usr/local/orca/orca",
  "orca.mpiProcs": 8
}

🚀 Usage

Basic Workflow

1. Create a new file with .inp extension (e.g., water.inp)

2. Type a snippet: opt + Tab to expand to optimization template

3. Edit your input:

   ! B3LYP def2-TZVP Opt TightSCF
   
   * xyz 0 1
     O  0.0  0.0  0.0
     H  0.0  0.0  1.0
     H  0.0  1.0  0.0
   *
   

4. Press F5 to run the calculation

5. View output in the ORCA panel (auto-opens)

6. Check status bar for final energy and convergence status

Available Snippets

Tip: Type the prefix and press Tab to expand.

🎨 Syntax Highlighting

The extension recognizes:

• Keywords (starting with !): B3LYP, def2-TZVP, Opt, etc.
• Blocks (starting with %): %pal, %scf, %geom, etc.
• Coordinates: Element symbols and numeric values
• Comments: Lines starting with #

Color Scheme Example:

• 🟢 Functionals: B3LYP, wB97X-D3
• 🔵 Basis sets: def2-TZVP, cc-pVTZ
• 🟡 Job types: Opt, Freq, OptTS
• 🟣 Blocks: %pal, %scf

📋 Commands

All commands are available via Command Palette (Ctrl/Cmd + Shift + P):

Execution Commands

Installation & Configuration Commands

Access via:

• Command Palette (Ctrl/Cmd + Shift + P) → "ORCA: ..."
• Open input file, and click "▶️ Run ORCA" at the top of the file
• Editor toolbar icon (▶️) for Run
• Status bar (click to detect installations)

🔍 Output Parsing

After job completion, VS-ORCA automatically extracts:

• ✅ Convergence status ("HURRAY" or "SCF NOT CONVERGED")
• 📊 Final energy (displayed in status bar)
• ✨ Geometry optimization convergence
• 🎵 Frequency calculation results
• ⚠️ Imaginary frequencies (for transition states)

Example Output:

═══════════════════════════════════════════════════════
✅ ORCA job completed successfully
🎉 Calculation converged successfully!
📊 Final Energy: -76.42371840 Hartree
✨ Geometry optimization converged!
🎵 Frequency calculation completed
═══════════════════════════════════════════════════════

🗺️ Roadmap

✅ Phase 1: MVP (v0.1.0)

• Syntax highlighting
• Code snippets
• Local execution
• Output streaming
• Basic parsing

✅ Phase 2: Installation Capability (v0.2.0)

• Interactive installation wizard
• Automatic ORCA detection
• Validation and health checks
• OS-specific installation strategies
• Multi-version support

✅ Phase 3: Output File Management (Current - v0.3.0)

• Automatic output file persistence
• Syntax highlighting for output files
• Structured navigation (Outline, Go to Symbol)
• Interactive results dashboard
• Enhanced parsing (SCF, geometry, frequencies)
• JSON export capability

🔄 Phase 4: Real-time Visualization (v0.4.0)

• Live streaming visualization during execution
• Energy vs. cycle plots
• Convergence graphs
• Molecular orbital viewer integration

🚀 Phase 5: Remote Execution (v0.5.0)

• SSH integration for cluster submission
• SLURM/PBS job management
• Queue monitoring
• Auto-download results

🐛 Known Issues

• Large output files (>50 MB) may slow down real-time streaming
• Windows paths with spaces require proper escaping in orca.binaryPath
• Syntax highlighting doesn't cover all obscure ORCA keywords (contributions welcome!)

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

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

🙏 Acknowledgments

• ORCA by Frank Neese and colleagues at the Max Planck Institute
• Inspired by the computational chemistry community's need for better tooling
• Built with TypeScript and the VS Code Extension API

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

💖 Support the Project

If you find this extension helpful, consider buying me a beer! Your support helps maintain and improve VS-ORCA.

Happy Computing! 🧪⚛️