Skip to content

Commit a551765

Browse files
superstar54superstar54
committed
AEP 011: A dedicated Graphical User Interface for AiiDA
1 parent c10ecd7 commit a551765

File tree

2 files changed

+187
-0
lines changed

2 files changed

+187
-0
lines changed

‎010_aiida_gui/readme.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# AEP 011: A dedicated Graphical User Interface for AiiDA
2+
3+
| AEP number | 010 |
4+
|------------|--------------------------------------------------------------|
5+
| Title | A dedicated Graphical User Interface for AiiDA |
6+
| Authors | [Xing Wang](mailto:xingwang1991@gmail.com) (superstar54) |
7+
| Champions | [Xing Wang](mailto:xingwang1991@gmail.com) (superstar54) |
8+
| Type | S - Standard Track AEP |
9+
| Created | 18-June-2025 |
10+
| Status | Draft
11+
12+
---
13+
14+
## Table of Contents
15+
16+
1. [Background](#background)
17+
2. [Proposed Enhancement](#proposed-enhancement)
18+
19+
* [Key Features](#key-features)
20+
3. [Implementation Details](#implementation-details)
21+
22+
* [Backend: FastAPI & aiida-restapi](#backend-fastapi--aiida-restapi)
23+
* [Frontend: React & Component Library](#frontend-react--component-library)
24+
* [Plugin Architecture](#plugin-architecture)
25+
* [Apps Integration](#apps-integration)
26+
* [CLI & Deployment](#cli--deployment)
27+
* [Security & Authentication](#security--authentication)
28+
4. [Usage Examples](#usage-examples)
29+
5. [Design Considerations](#design-considerations)
30+
31+
* [Integration with AiiDA Core](#integration-with-aiida-core)
32+
* [Performance and Scalability](#performance-and-scalability)
33+
* [Extensibility and Maintainability](#extensibility-and-maintainability)
34+
6. [Conclusion](#conclusion)
35+
36+
---
37+
38+
## Background
39+
40+
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.
41+
42+
43+
---
44+
45+
## Proposed Enhancement
46+
47+
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.”
48+
49+
50+
### Key Features
51+
52+
* **Core Views**
53+
54+
* **Process Table:** live view of running and completed processes, with filters, search, and status badges, and control buttons (pause, resume, kill, delete).
55+
* **Data nodes Table:** browse Data nodes with faceted filters and custom projections.
56+
* **Node Group Table:** create, edit, and query Groups of nodes or processes.
57+
* **Daemon Control:** start/stop/restart the AiiDA daemon and monitor logs in real time.
58+
* **Computer & code:** Configure and manage computers and codes.
59+
60+
* **Rich Data Viewers**
61+
62+
* Raw JSON inspector for any node
63+
* Specialized renderers: crystal structure (using weas), band structure plots, array and dict, and more.
64+
65+
* **Rich Process Viewers**
66+
67+
* Interactive WorkChain and workflow graphs (e.g., inspired by `WorkGraph`), as well as process report, summary etc.
68+
* `CalcJob` viewers similar to Materials Cloud.
69+
* Provenance graph visualization or table: inputs, outputs, and dependencies.
70+
71+
* **Plugin & App Ecosystem**
72+
73+
* Load frontend dynamically into sidebar, new pages or data viewers.
74+
* Shared React component library (`aiida-react-components-base`) published to npm
75+
76+
* **Apps Page**
77+
78+
* Discover and launch self-contained “apps” (standalone frontends)
79+
80+
* **CLI Integration**
81+
82+
* `pip install aiida-gui` (or `verdi gui install`)
83+
* Commands: `aiida-gui start|stop|restart|status`
84+
* Mount the React frontend into FastAPI so only a single process is needed
85+
86+
* **Security & Multi-User Support**
87+
88+
* Token-based access (`?token=…`) akin to Jupyter notebooks
89+
* Optional integration with JupyterHub deployment for centralized authentication
90+
91+
---
92+
93+
## Implementation Details
94+
95+
### Backend: FastAPI & aiida-restapi
96+
97+
* **Leverage** the existing [aiida-restapi](https://github.com/aiidateam/aiida-restapi) endpoints wherever possible.
98+
* **Refactor** aiida-restapi to allow query-time projections and filters (e.g. selecting only certain columns).
99+
* **Expose** new routes for plugin registration, and app discovery.
100+
* **Mount** plugin routers automatically by scanning entry points under `aiida_gui.plugins` and `aiida_gui.apps`.
101+
102+
### Frontend: React & Component Library
103+
104+
* **Framework:** React (latest stable), built with Vite or Next.js in ESM mode.
105+
* **Component Package:** `aiida-react-components-base` on npm, containing:
106+
107+
* Data viewers, e.g., StructureViewer, BandsPlot, TableGrid.
108+
* Common UI elements, e.g., Code selection, process tree.
109+
* **Build & Mount:**
110+
111+
* Build output is a static bundle served by FastAPI at `/static/`.
112+
* FastAPI serves `index.html` at `/`, embedding the React app.
113+
114+
### Plugin Architecture
115+
116+
* **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}`.
117+
* **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.
118+
119+
### Apps Integration
120+
121+
* **Self-contained apps** are packaged as static HTML/JS/CSS under `/apps/{app_name}/`.
122+
* The core GUI provides a directory listing with icons and metadata for each registered app.
123+
* Apps can still call core REST endpoints (with CORS enabled internally) and reuse shared components via the npm package.
124+
125+
### CLI & Deployment
126+
127+
* **Entry Point:** `aiida-gui` console script
128+
* **Commands:**
129+
130+
* `aiida-gui start [--host HOST] [--port PORT] [--token TOKEN]`
131+
* `aiida-gui stop`
132+
* `aiida-gui restart`
133+
* `aiida-gui status`
134+
* **Configuration:** `~/.config/aiida/gui-config.json` holds defaults for host/port, token, plugin enable/disable.
135+
136+
### Security & Deployment
137+
138+
* **Token Auth:** generate a random token at first run; all GUI requests must include `?token=` or `Authorization: Bearer`.
139+
* **JupyterHub Integration:** provide optional flags to respect JupyterHub’s proxy authentication and mount under user’s namespace, e.g., under `/user/{name}/aiida-gui/`.
140+
141+
142+
---
143+
144+
## Usage Examples
145+
146+
```bash
147+
pip install aiida-gui
148+
aiida-gui start --port 8080
149+
```
150+
151+
* Open `http://localhost:8080?token=3f8d2a…` in your browser.
152+
* Browse running processes, inspect nodes, and control the daemon.
153+
154+
To install a community plugin:
155+
156+
```bash
157+
pip install aiida-gui-myplugin
158+
aiida-gui restart
159+
```
160+
161+
The plugin’s sidebar entry appears; clicking it loads its custom page and data viewers.
162+
163+
---
164+
165+
## Design Considerations
166+
167+
### Integration with AiiDA Core
168+
169+
* **Non-intrusive:** No changes to `aiida-core` are required beyond optional dependency mount the cli command to `verdi`.
170+
171+
### Performance and Scalability
172+
173+
* **Backend:** FastAPI + Uvicorn supports async concurrency; use caching where appropriate for heavy queries.
174+
* **Frontend:** Code-splitting ensures only needed plugins are loaded.
175+
176+
### Extensibility and Maintainability
177+
178+
* **Plugin-First:** Every new feature should live as a plugin until it proves broadly useful for the core.
179+
* **Shared Components:** Encourage reuse via the `aiida-react-components-base` package.
180+
* **Documentation & Testing:** Provide cookie-cutter plugin template, and CI pipelines for core and plugins.
181+
182+
---
183+
184+
## Conclusion
185+
186+
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.

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Accepted AEPs can be easily browsed and read on the [online documentation](https
2121
| 007 | implemented | [Abstract and improve the file repository](007_improved_file_repository/readme.md) |
2222
| 008 | implemented | [Allow `CalcJob`s to be actively monitored and interrupted](008_calcjob_monitors/readme.md) |
2323
| 009 | implemented | [Improved Docker images](009_improved_docker_images/readme.md) |
24+
| 010 | draft | [AiiDA GUI](010_aiida_gui/readme.md) |
2425

2526
## Submitting an AEP
2627

0 commit comments

Comments
 (0)