IQC Dashboard

🌐 Live Dashboard: https://iqc-dashboard.streamlit.app/

A high-performance, open-source computational chemistry dashboard built with Streamlit. The IQC Dashboard provides fast, interactive visualization and analysis of large datasets produced by IQC (Interactive Quantum Chemistry). It includes 3D molecular viewers, rich analytics, and efficient querying of large Parquet datasets using DuckDB.

---

Overview

The IQC Dashboard is purpose-built for exploring results from the IQC framework, which supports quantum chemistry workflows such as:

• Single-point energy calculations
• Geometry optimizations
• Vibrational frequency analysis
• Thermochemistry calculations

This dashboard makes IQC outputs easy to browse, filter, visualize, and inspect—whether you're validating high-throughput calculations or exploring results molecule-by-molecule.

---

Features

🔗 IQC-Native Integration

• Works directly with Parquet datasets generated by IQC
• Recognizes and visualizes all major IQC task types (single, opt, vib, thermo)

⚡ Efficient Data Processing

• Powered by DuckDB for ultra-fast SQL queries on Parquet files
• No need to load entire datasets into memory, even for multi-gigabyte files

🧬 Interactive 3D Molecular Visualization

• View initial vs optimized structures side-by-side
• Built with stmol and py3Dmol

📊 Rich Analytics

Plotly-based interactive charts, including:

• Initial vs optimized energy comparisons
• Optimization time distributions
• Convergence analysis
• Vibrational frequency spectra

🎛️ Advanced Filtering

Filter datasets by:

• Calculator
• Task type
• Chemical formula
• Convergence status
• Number of atoms

🔍 Single Molecule Inspector

Deep dive into one molecule at a time with:

• Structure overlays
• Energy breakdown
• Vibrational and thermochemical properties

---

Quick Start

Installation

Step 1: Set Up a Virtual Environment (Recommended)

It's recommended to use a virtual environment to isolate dependencies. Choose one of the following methods:

Option A: Using venv (built into Python 3.9+)

python -m venv iqc-dashboard-env
source iqc-dashboard-env/bin/activate  # On macOS/Linux
# or
iqc-dashboard-env\Scripts\activate  # On Windows

Option B: Using conda (recommended for scientific computing)

conda create -n iqc-dashboard-env python=3.9
conda activate iqc-dashboard-env

Option C: Using uv (fastest)

uv venv iqc-dashboard-env
source iqc-dashboard-env/bin/activate  # On macOS/Linux
# or
iqc-dashboard-env\Scripts\activate  # On Windows

Step 2: Install IQC Dashboard

Once your virtual environment is activated, install the dashboard:

Using pip:

pip install iqc-dashboard

Using uv (recommended for faster installation):

uv pip install iqc-dashboard

From source:

git clone https://github.com/Autonomous-Scientific-Agents/IQC_Dashboard.git
cd IQC_Dashboard
pip install -e .
# or with uv:
uv pip install -e .

Step 3: Run the Dashboard

After installation, simply run:

streamlit run streamlit_app.py

Or if you installed the package, you can use:

iqc-dashboard

Note: If you installed from source, make sure you're in the repository directory when running streamlit run streamlit_app.py, or use the iqc-dashboard command after installation.

---

Usage

Running the Dashboard

After installation, you can run the dashboard in several ways:

Option 1: Using Streamlit directly

streamlit run streamlit_app.py

Option 2: Using the Python module

python -m streamlit run streamlit_app.py

Option 3: Using the command-line entry point (after installation)

iqc-dashboard

Option 4: Running from the package directly

streamlit run -m iqc_dashboard.app

Expected Data Schema

The dashboard expects Parquet files generated by IQC with the following columns (at minimum):

• unique_name: Unique identifier for each molecule
• initial_xyz: Initial structure in XYZ format
• opt_xyz: Optimized structure in XYZ format
• opt_energy_eV: Optimized energy in eV
• initial_energy_eV: Initial energy in eV
• formula: Chemical formula
• opt_converged: Boolean indicating convergence
• calculator: Calculator name (e.g., from ASE)
• task: Task type (single, opt, vib, thermo)
• number_of_atoms: Number of atoms
• vibrational_frequencies_cm^-1: List of vibrational frequencies (from vib calculations)
• G_eV, H_eV, S_eV/K: Thermochemical properties (from thermo calculations)

See the full schema in the application documentation. The schema matches the output format from IQC calculations.

---

Deployment on Streamlit Cloud

Prerequisites

1. A GitHub account
2. A Streamlit Cloud account (free at streamlit.io/cloud)
3. Your repository pushed to GitHub

Deployment Steps

1. Push your code to GitHub (if not already done):

   git add .
   git commit -m "Prepare for Streamlit Cloud deployment"
   git push origin main

2. Connect to Streamlit Cloud:

   • Go to share.streamlit.io
   • Sign in with your GitHub account
   • Click "New app"

3. Configure your app:

   • Repository: Select Autonomous-Scientific-Agents/IQC_Dashboard
   • Branch: main
   • Main file path: streamlit_app.py (or iqc_dashboard/app.py if preferred)
   • Python version: 3.9 or higher (Streamlit Cloud supports 3.9-3.12)

4. Advanced Settings (optional):

   • Streamlit Cloud will automatically detect and use pyproject.toml for dependencies
   • Alternatively, you can specify requirements.txt in the advanced settings
   • No secrets or environment variables are required for basic functionality
   • The app uses streamlit_app.py as the entry point (which imports from the package)

5. Deploy:

   • Click "Deploy!"
   • Streamlit Cloud will build and deploy your app
   • The first deployment may take a few minutes

Streamlit Cloud Configuration

The repository includes a .streamlit/config.toml file with recommended settings. Streamlit Cloud will use these automatically.

Troubleshooting Streamlit Cloud Deployment

If you encounter issues:

1. Dependency conflicts: Ensure all dependencies in pyproject.toml are compatible
2. Import errors: Check that all required packages are listed in dependencies
3. Memory issues: The app uses DuckDB to handle large files efficiently, but very large datasets may require optimization
4. 3D visualization not working: Ensure stmol and py3Dmol are properly installed (they should be automatically installed from dependencies)

Environment Variables

No environment variables are required for basic operation. If you need to configure additional settings, you can add them in Streamlit Cloud's "Advanced settings" section.

---

Development

Setting up a development environment

git clone https://github.com/Autonomous-Scientific-Agents/IQC_Dashboard.git
cd IQC_Dashboard

# Create and activate virtual environment (choose one method)
python -m venv venv
source venv/bin/activate  # On macOS/Linux
# or
venv\Scripts\activate  # On Windows

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Or with uv:

git clone https://github.com/Autonomous-Scientific-Agents/IQC_Dashboard.git
cd IQC_Dashboard
uv venv
source .venv/bin/activate  # On macOS/Linux
uv pip install -e ".[dev]"

Running tests

Run all tests:

pytest

Run tests with coverage:

pytest --cov=iqc_dashboard --cov-report=html

Run specific test file:

pytest tests/test_data_manager.py

Run tests in verbose mode:

pytest -v

Code formatting

black iqc_dashboard/
ruff check iqc_dashboard/

---

Project Structure

iqc_dashboard/
├── iqc_dashboard/
│   ├── __init__.py
│   ├── app.py          # Main Streamlit application
│   └── cli.py          # Command-line interface
├── tests/               # Unit tests
│   ├── __init__.py
│   ├── conftest.py     # Pytest fixtures
│   ├── test_data_manager.py
│   ├── test_render_molecule.py
│   └── test_cli.py
├── .github/
│   └── workflows/
│       └── ci.yml      # GitHub Actions CI workflow
├── .streamlit/
│   └── config.toml     # Streamlit configuration
├── pyproject.toml      # Package configuration (PEP 621)
├── pytest.ini         # Pytest configuration
├── requirements.txt    # Legacy requirements (for compatibility)
└── README.md          # This file

---

Dependencies

• streamlit: Web framework
• duckdb: Fast analytical database for Parquet files
• pandas: Data manipulation
• pyarrow: Parquet file support
• stmol: Streamlit wrapper for 3D molecular visualization
• py3Dmol: 3D molecular visualization library
• plotly: Interactive plotting
• numpy: Numerical computing

---

License

MIT License

---

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

Support

For issues, questions, or contributions, please open an issue on GitHub.

---

Related Projects

• IQC (Interactive Quantum Chemistry): The computational chemistry framework that generates the data visualized by this dashboard

---

Acknowledgments

Built with:

• Streamlit
• DuckDB
• stmol
• py3Dmol
• Plotly

Designed to visualize output from IQC (Interactive Quantum Chemistry).