GridLens

GridLens is a local Python desktop application for running GridPACK contingency analysis through a prebuilt Docker container.

The intended deployment target is NVIDIA DGX Spark / DGX OS 7, which is Ubuntu 24.04 based on ARM64. For other architectures, the app detects the host architecture and passes the matching Docker platform flag.

This app is local-only by design. Pull the GridPACK Docker image before opening sensitive files in the app.

Quick Start For Development

cd /path/to/gridpack-workbench-dev
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev]"
gridlens

The full test suite expects the development dependencies, including PySide6:

python -m pytest

For a quick local environment smoke check:

python3 scripts/check_environment.py

Web API Mode

GridLens now also includes a backend API layer for a browser-based frontend. Install the web dependencies and run:

python -m pip install -e ".[dev,web]"
gridlens-api

The API defaults to http://0.0.0.0:8000 and stores uploaded web projects under ~/GridLensWebProjects. If GRIDLENS_AUTH_MODE=cognito, the API verifies Cognito bearer tokens and automatically scopes every user to a private per-user project root on disk.

• GET /health
• GET /api/auth
• GET /api/me
• GET /api/projects
• POST /api/projects
• GET /api/projects/{project_id}
• GET /api/projects/{project_id}/configuration
• POST /api/projects/{project_id}/configuration
• POST /api/projects/{project_id}/runs
• GET /api/projects/{project_id}/runs/{run_id}
• GET /api/projects/{project_id}/runs/{run_id}/log
• GET /api/projects/{project_id}/runs/{run_id}/outputs
• GET /api/projects/{project_id}/runs/{run_id}/outputs/download/{relative_path}
• GET /api/projects/{project_id}/runs/{run_id}/export
• POST /api/projects/{project_id}/runs/{run_id}/analysis/interactive

Set GRIDLENS_API_CORS_ORIGINS to allow a local frontend such as Vite or Next.js to call an API hosted on AWS. The browser client scaffold lives in webapp/README.md. Deployment guidance for a hosted web app lives in docs/web_deployment.md.

Browser Deployment Pattern

The recommended hosted architecture is:

• GitHub Pages for the static React frontend
• EC2 for the FastAPI backend, Docker, GridPACK execution, and user file storage
• Amazon Cognito for email-and-password authentication

In this setup, the frontend authenticates through Cognito and sends bearer tokens to the EC2 API. The API then limits each user to their own projects, runs, logs, ZIP exports, and output files.

Manual Docker Equivalent

The GUI builds a Docker command equivalent to:

docker run --rm \
  --pull=never \
  --network none \
  --platform linux/arm64 \
  -u "$(id -u):$(id -g)" \
  -e HOME=/tmp \
  -v /path/to/project/runs/YYYY-MM-DD_HH-MM-SS/work:/app/workspace \
  -w /app/workspace \
  pnnl/gridpack:latest \
  mpirun -n 4 ca.x input.xml

On x86_64 systems the platform is linux/amd64; on DGX Spark ARM64 it is typically linux/arm64.

Repository Layout

src/gridlens/
  gui/        PySide6 tabs and main window
  core/       settings, projects, validation, run manifests
  runner/     Docker probing, command construction, GridPACK execution
  analysis/   local output parsing, graph data, metrics, exports
  resources/  application icon

tests/        core unit tests
docs/         architecture, install, user, security, packaging notes
packaging/    PyInstaller and Debian package files
scripts/      local helper scripts
samples/      small parser sample files

Documentation

• Architecture
• Developer Guide
• DGX OS 7 Install Guide
• User Guide
• CEII Security Notes
• Packaging And Distribution
• Troubleshooting
• Contributing