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: Verify Python Version

IQC Dashboard requires Python 3.9 or higher. Check your Python version:

python --version
# or
python3 --version

If you need to install or upgrade Python, visit python.org.

Step 2: Set Up a Virtual Environment (Recommended)

⚠️ Important: Always use a virtual environment to isolate dependencies and avoid conflicts with system packages.

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

Verify your virtual environment is activated:

• Your terminal prompt should show the environment name (e.g., (iqc-dashboard-env))
• Running which python (Linux/macOS) or where python (Windows) should point to the virtual environment's Python

Step 3: Ensure pip is Available and Up-to-Date

If your virtual environment doesn't have pip installed, bootstrap it:

python -m ensurepip --upgrade

Then upgrade pip to the latest version:

python -m pip install --upgrade pip

Note: Using python -m pip instead of just pip ensures you're using the pip from your virtual environment.

Step 4: Install IQC Dashboard

Option A: Install from PyPI (recommended for most users)

python -m pip install iqc-dashboard

Option B: Install from source (for development or latest features)

git clone https://github.com/Autonomous-Scientific-Agents/IQC_Dashboard.git
cd IQC_Dashboard
python -m pip install -e .

Option C: Using uv (fastest installation)

# From PyPI
uv pip install iqc-dashboard

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

Troubleshooting installation issues:

• If you get permission errors, make sure your virtual environment is activated
• If pip command is not found, use python -m pip instead
• If editable install fails, ensure setuptools is installed: python -m pip install setuptools wheel

Step 5: Verify Installation

Verify the installation was successful:

iqc-dashboard --help
# or
python -m iqc_dashboard.cli --help

Step 6: Run the Dashboard

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

Option 1: Using the command-line entry point (recommended)

iqc-dashboard

Option 2: Using Streamlit directly

streamlit run streamlit_app.py

Option 3: Running from the package

python -m streamlit run streamlit_app.py

Note: If you installed from source, you can run streamlit run streamlit_app.py from the repository directory, or use the iqc-dashboard command from anywhere 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

1. Clone the repository:

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

2. Create and activate a virtual environment:

Using venv:

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

Using uv:

uv venv
source .venv/bin/activate  # On macOS/Linux
# or
.venv\Scripts\activate  # On Windows

3. Ensure pip is up-to-date:

python -m pip install --upgrade pip

4. Install in development mode with dev dependencies:

python -m pip install -e ".[dev]"

Or with uv:

uv pip install -e ".[dev]"

Note: The [dev] extra includes development tools like pytest, black, ruff, and mypy.

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).