From 9e77e5d390d75429d43c5b482249935e90ef8f4e Mon Sep 17 00:00:00 2001 From: superstar54 Date: Thu, 19 Jun 2025 22:56:44 +0200 Subject: [PATCH 1/3] AEP 010: A dedicated Graphical User Interface for AiiDA --- 010_aiida_gui/readme.md | 186 ++++++++++++++++++++++++++++++++++++++++ README.md | 1 + 2 files changed, 187 insertions(+) create mode 100644 010_aiida_gui/readme.md diff --git a/010_aiida_gui/readme.md b/010_aiida_gui/readme.md new file mode 100644 index 0000000..1a55b9e --- /dev/null +++ b/010_aiida_gui/readme.md @@ -0,0 +1,186 @@ +# AEP 010: A dedicated Graphical User Interface for AiiDA + +| AEP number | 010 | +|------------|--------------------------------------------------------------| +| Title | A dedicated Graphical User Interface for AiiDA | +| Authors | [Xing Wang](mailto:xingwang1991@gmail.com) (superstar54) | +| Champions | [Xing Wang](mailto:xingwang1991@gmail.com) (superstar54) | +| Type | S - Standard Track AEP | +| Created | 18-June-2025 | +| Status | Draft + +--- + +## Table of Contents + +1. [Background](#background) +2. [Proposed Enhancement](#proposed-enhancement) + + * [Key Features](#key-features) +3. [Implementation Details](#implementation-details) + + * [Backend: FastAPI & aiida-restapi](#backend-fastapi--aiida-restapi) + * [Frontend: React & Component Library](#frontend-react--component-library) + * [Plugin Architecture](#plugin-architecture) + * [Apps Integration](#apps-integration) + * [CLI & Deployment](#cli--deployment) + * [Security & Authentication](#security--authentication) +4. [Usage Examples](#usage-examples) +5. [Design Considerations](#design-considerations) + + * [Integration with AiiDA Core](#integration-with-aiida-core) + * [Performance and Scalability](#performance-and-scalability) + * [Extensibility and Maintainability](#extensibility-and-maintainability) +6. [Conclusion](#conclusion) + +--- + +## Background + +AiiDA’s command-line interface (CLI) is powerful and scriptable, yet many users, especially newcomers, find the text-based tools steep to learn and lacking in interactivity. Modern computational science benefits greatly from visual summaries of running processes, interactive data viewers (for crystal structures, band structures, arrays…), and plugin-driven dashboards that can be composed on the fly. While tools like AiiDAlab and Materials Cloud offer some GUI functionality, they either run within Jupyter notebooks or impose heavy deployment overhead. A dedicated, self-hosted AiiDA GUI would lower the barrier to entry, speed up common tasks, and provide a solid foundation for community-built extensions. + + +--- + +## Proposed Enhancement + +Provide a standalone web-based graphical interface for AiiDA, **AiiDA GUI**, that allows users to inspect and control processes, explore data nodes in rich viewers, and extend its functionality through plugins and “apps.” + + +### Key Features + +* **Core Views** + + * **Process Table:** live view of running and completed processes, with filters, search, and status badges, and control buttons (pause, resume, kill, delete). + * **Data nodes Table:** browse Data nodes with faceted filters and custom projections. + * **Node Group Table:** create, edit, and query Groups of nodes or processes. + * **Daemon Control:** start/stop/restart the AiiDA daemon and monitor logs in real time. + * **Computer & code:** Configure and manage computers and codes. + +* **Rich Data Viewers** + + * Raw JSON inspector for any node + * Specialized renderers: crystal structure (using weas), band structure plots, array and dict, and more. + +* **Rich Process Viewers** + + * Interactive WorkChain and workflow graphs (e.g., inspired by `WorkGraph`), as well as process report, summary etc. + * `CalcJob` viewers similar to Materials Cloud. + * Provenance graph visualization or table: inputs, outputs, and dependencies. + +* **Plugin & App Ecosystem** + + * Load frontend dynamically into sidebar, new pages or data viewers. + * Shared React component library (`aiida-react-components-base`) published to npm + +* **Apps Page** + + * Discover and launch self-contained “apps” (standalone frontends) + +* **CLI Integration** + + * `pip install aiida-gui` (or `verdi gui install`) + * Commands: `aiida-gui start|stop|restart|status` + * Mount the React frontend into FastAPI so only a single process is needed + +* **Security & Multi-User Support** + + * Token-based access (`?token=…`) akin to Jupyter notebooks + * Optional integration with JupyterHub deployment for centralized authentication + +--- + +## Implementation Details + +### Backend: FastAPI & aiida-restapi + +* **Leverage** the existing [aiida-restapi](https://github.com/aiidateam/aiida-restapi) endpoints wherever possible. +* **Refactor** aiida-restapi to allow query-time projections and filters (e.g. selecting only certain columns). +* **Expose** new routes for plugin registration, and app discovery. +* **Mount** plugin routers automatically by scanning entry points under `aiida_gui.plugins` and `aiida_gui.apps`. + +### Frontend: React & Component Library + +* **Framework:** React (latest stable), built with Vite or Next.js in ESM mode. +* **Component Package:** `aiida-react-components-base` on npm, containing: + + * Data viewers, e.g., StructureViewer, BandsPlot, TableGrid. + * Common UI elements, e.g., Code selection, process tree. +* **Build & Mount:** + + * Build output is a static bundle served by FastAPI at `/static/`. + * FastAPI serves `index.html` at `/`, embedding the React app. + +### Plugin Architecture + +* **Backend:** Plugins declare entry points under `aiida_gui.plugins` which provide a FastAPI Router. On startup, the core app includes these routers under `/plugins/{name}`. +* **Frontend:** Plugins publish an ESM bundle, with its entry describing routes and components to mount in the sidebar or as standalone pages. The core React app loads and mounts these dynamically. + +### Apps Integration + +* **Self-contained apps** are packaged as static HTML/JS/CSS under `/apps/{app_name}/`. +* The core GUI provides a directory listing with icons and metadata for each registered app. +* Apps can still call core REST endpoints (with CORS enabled internally) and reuse shared components via the npm package. + +### CLI & Deployment + +* **Entry Point:** `aiida-gui` console script +* **Commands:** + + * `aiida-gui start [--host HOST] [--port PORT] [--token TOKEN]` + * `aiida-gui stop` + * `aiida-gui restart` + * `aiida-gui status` +* **Configuration:** `~/.config/aiida/gui-config.json` holds defaults for host/port, token, plugin enable/disable. + +### Security & Deployment + +* **Token Auth:** generate a random token at first run; all GUI requests must include `?token=` or `Authorization: Bearer`. +* **JupyterHub Integration:** provide optional flags to respect JupyterHub’s proxy authentication and mount under user’s namespace, e.g., under `/user/{name}/aiida-gui/`. + + +--- + +## Usage Examples + +```bash +pip install aiida-gui +aiida-gui start --port 8080 +``` + +* Open `http://localhost:8080?token=3f8d2a…` in your browser. +* Browse running processes, inspect nodes, and control the daemon. + +To install a community plugin: + +```bash +pip install aiida-gui-myplugin +aiida-gui restart +``` + +The plugin’s sidebar entry appears; clicking it loads its custom page and data viewers. + +--- + +## Design Considerations + +### Integration with AiiDA Core + +* **Non-intrusive:** No changes to `aiida-core` are required beyond optional dependency mount the cli command to `verdi`. + +### Performance and Scalability + +* **Backend:** FastAPI + Uvicorn supports async concurrency; use caching where appropriate for heavy queries. +* **Frontend:** Code-splitting ensures only needed plugins are loaded. + +### Extensibility and Maintainability + +* **Plugin-First:** Every new feature should live as a plugin until it proves broadly useful for the core. +* **Shared Components:** Encourage reuse via the `aiida-react-components-base` package. +* **Documentation & Testing:** Provide cookie-cutter plugin template, and CI pipelines for core and plugins. + +--- + +## Conclusion + +The proposed AiiDA GUI brings a modern, user-friendly interface to AiiDA, reducing the learning curve and enabling rich, interactive exploration of workflows and data. By building on FastAPI and React, and embracing a plugin-and-apps ecosystem, the GUI will be flexible, performant, and easily extensible by the community. This enhancement promises to accelerate AiiDA adoption and catalyze the development of domain-specific extensions and apps. diff --git a/README.md b/README.md index f46bf70..26ad8a5 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,7 @@ Accepted AEPs can be easily browsed and read on the [online documentation](https | 007 | implemented | [Abstract and improve the file repository](007_improved_file_repository/readme.md) | | 008 | implemented | [Allow `CalcJob`s to be actively monitored and interrupted](008_calcjob_monitors/readme.md) | | 009 | implemented | [Improved Docker images](009_improved_docker_images/readme.md) | +| 010 | draft | [AiiDA GUI](010_aiida_gui/readme.md) | ## Submitting an AEP From 1470339808caea64524d2495af92ef923c0926df Mon Sep 17 00:00:00 2001 From: superstar54 Date: Tue, 24 Jun 2025 11:25:40 +0200 Subject: [PATCH 2/3] Add team members to Champions --- 010_aiida_gui/readme.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/010_aiida_gui/readme.md b/010_aiida_gui/readme.md index 1a55b9e..8ca40d1 100644 --- a/010_aiida_gui/readme.md +++ b/010_aiida_gui/readme.md @@ -4,7 +4,7 @@ |------------|--------------------------------------------------------------| | Title | A dedicated Graphical User Interface for AiiDA | | Authors | [Xing Wang](mailto:xingwang1991@gmail.com) (superstar54) | -| Champions | [Xing Wang](mailto:xingwang1991@gmail.com) (superstar54) | +| Champions | [Xing Wang](mailto:xingwang1991@gmail.com) (superstar54), [Edan Bainglass](mailto:edan.bainglass@psi.ch) (edan-bainglass) [Kristjan Eimre](mailto:kristjaneimre@gmail.com) ( eimrek), [Bud Macaulay](mailto:bud.macaulay@psi.ch) (bud-macaulay)| | Type | S - Standard Track AEP | | Created | 18-June-2025 | | Status | Draft From 46ccd07d4a02d30aa2b93d41e80200a3f68cc05a Mon Sep 17 00:00:00 2001 From: superstar54 Date: Tue, 24 Jun 2025 21:55:06 +0200 Subject: [PATCH 3/3] Mark apps integration as Optional, refactor the text based on review. --- 010_aiida_gui/readme.md | 35 ++++++++++++++++++----------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/010_aiida_gui/readme.md b/010_aiida_gui/readme.md index 8ca40d1..35a6d82 100644 --- a/010_aiida_gui/readme.md +++ b/010_aiida_gui/readme.md @@ -31,7 +31,8 @@ * [Integration with AiiDA Core](#integration-with-aiida-core) * [Performance and Scalability](#performance-and-scalability) * [Extensibility and Maintainability](#extensibility-and-maintainability) -6. [Conclusion](#conclusion) +6. [Optional apps integration](#optional-apps-integration) +7. [Conclusion](#conclusion) --- @@ -44,7 +45,7 @@ AiiDA’s command-line interface (CLI) is powerful and scriptable, yet many user ## Proposed Enhancement -Provide a standalone web-based graphical interface for AiiDA, **AiiDA GUI**, that allows users to inspect and control processes, explore data nodes in rich viewers, and extend its functionality through plugins and “apps.” +Provide a standalone web-based graphical interface for AiiDA, **AiiDA GUI**, that allows users to inspect and control processes, explore data nodes in rich viewers, and extend its functionality through plugins. ### Key Features @@ -68,15 +69,11 @@ Provide a standalone web-based graphical interface for AiiDA, **AiiDA GUI**, tha * `CalcJob` viewers similar to Materials Cloud. * Provenance graph visualization or table: inputs, outputs, and dependencies. -* **Plugin & App Ecosystem** +* **Plugin Ecosystem** * Load frontend dynamically into sidebar, new pages or data viewers. * Shared React component library (`aiida-react-components-base`) published to npm -* **Apps Page** - - * Discover and launch self-contained “apps” (standalone frontends) - * **CLI Integration** * `pip install aiida-gui` (or `verdi gui install`) @@ -94,10 +91,10 @@ Provide a standalone web-based graphical interface for AiiDA, **AiiDA GUI**, tha ### Backend: FastAPI & aiida-restapi -* **Leverage** the existing [aiida-restapi](https://github.com/aiidateam/aiida-restapi) endpoints wherever possible. +* **Leverage** the existing [aiida-restapi](https://github.com/aiidateam/aiida-restapi) endpoints, adding new ones as needed. * **Refactor** aiida-restapi to allow query-time projections and filters (e.g. selecting only certain columns). -* **Expose** new routes for plugin registration, and app discovery. -* **Mount** plugin routers automatically by scanning entry points under `aiida_gui.plugins` and `aiida_gui.apps`. +* **Expose** new routes for plugin registration and discovery. +* **Mount** plugin routers automatically by scanning entry points under `aiida_gui.plugins`. ### Frontend: React & Component Library @@ -116,12 +113,6 @@ Provide a standalone web-based graphical interface for AiiDA, **AiiDA GUI**, tha * **Backend:** Plugins declare entry points under `aiida_gui.plugins` which provide a FastAPI Router. On startup, the core app includes these routers under `/plugins/{name}`. * **Frontend:** Plugins publish an ESM bundle, with its entry describing routes and components to mount in the sidebar or as standalone pages. The core React app loads and mounts these dynamically. -### Apps Integration - -* **Self-contained apps** are packaged as static HTML/JS/CSS under `/apps/{app_name}/`. -* The core GUI provides a directory listing with icons and metadata for each registered app. -* Apps can still call core REST endpoints (with CORS enabled internally) and reuse shared components via the npm package. - ### CLI & Deployment * **Entry Point:** `aiida-gui` console script @@ -181,6 +172,16 @@ The plugin’s sidebar entry appears; clicking it loads its custom page and data --- +## Optional apps integration + +Apps differ from standard plugins, which are JavaScript modules dynamically loaded into the core GUI. Instead, apps are collections of AiiDA GUI applications delivered as fully self-contained static bundles (HTML, JS, and CSS) that run independently of the main React router. They provide complete, task-specific frontends with their own UI and workflow logic, while still interacting with AiiDA via its REST API, e.g., a DFT app that submits Quantum Espresso calculations, streams job status, and visualizes results. + +* **Packaging:** apps are static HTML/JS/CSS bundles under `/apps/{app_name}/` deployed alongside the core GUI. +* **Discovery and launch:** the GUI’s "Apps" page lists installed apps with names, icons, and metadata; users can launch them directly in a new tab or window. +* **Reuse:** apps may import shared components from `aiida-react-components-base` to maintain a consistent UX. + +--- + ## Conclusion -The proposed AiiDA GUI brings a modern, user-friendly interface to AiiDA, reducing the learning curve and enabling rich, interactive exploration of workflows and data. By building on FastAPI and React, and embracing a plugin-and-apps ecosystem, the GUI will be flexible, performant, and easily extensible by the community. This enhancement promises to accelerate AiiDA adoption and catalyze the development of domain-specific extensions and apps. +The proposed AiiDA GUI brings a modern, user-friendly interface to AiiDA, reducing the learning curve and enabling rich, interactive exploration of workflows and data. By building on FastAPI and React, and embracing a plugin ecosystem, the GUI will be flexible, performant, and easily extensible by the community. This enhancement promises to accelerate AiiDA adoption and catalyze the development of domain-specific extensions.