aiida-explorer

AiiDA provenance explorer

A React component to explore AiiDA provenance built on top of the AiiDA REST API.

The tool allows you to explore the graph of nodes, view detailed metadata, and track node visits with interactive breadcrumbs.

This repository contains

• the AiidaExplorer component (library), which is also published to npm; and
• a demo page illustrating the usage, which is deployed to github pages (https://aiidateam.github.io/aiida-explorer/). This also allows to directly explore your local AiiDA database (using verdi restapi), but might depend on the browser security settings (confirmed working with Firefox).

Main features include:

• Interactive graph view of nodes and their relationships.
• Single click selects a node to show details in a sidebar.
• Double click refocuses the graph on a node, fetching additional metadata (attributes, comments, extras).
• Breadcrumb trail tracks visited nodes, clickable for quick navigation.
• Nodes styled by type (process, data, etc.) with clear selection highlighting.

Explore your own AiiDA database

The demo page can be used to explore your own AiiDA database. To do this, start the REST API locally:

verdi -p <profile-name> restapi

and explore it at https://aiidateam.github.io/aiida-explorer/?api_url=http://127.0.0.1:5000/api/v4.

(Note that some browser extensions might block access to localhost, and should be disabled for this to work).

Alternatively a cli tool is avaible that allows provides a interface to select the profile to explore.

npx aiida-explorer # requires node https://nodejs.org/en/download

Installation and usage

Install via

npm install aiida-explorer

And use with the following:

import { AiidaExplorer } from "aiida-explorer";

...
<AiidaExplorer restApiUrl={AIIDA_REST_URL} />
...

where restApiUrl is the base url of the AiiDA REST API, e.g. http://localhost:5000/api/v4 if started locally via verdi restapi. For more details see the source code of the demo page.

One can also manage the rootNode state outside the component (e.g. to sync with URL parameters), then one should use

<AiidaExplorer
  restApiUrl={AIIDA_REST_URL}
  rootNode={rootNode}
  onRootNodeChange={onRootNodeChange}
/>

Development

We use the prefix ae to isolate tailwind classes (ae:bg-slate-50).

Using the demo page

For development, start the demo page by

npm install
npm run dev

Building the library and testing locally

To build the component library and test locally in an external application (e.g. before publishing to npm), use

npm run build:lib
npm pack

which will create a .tgz file that can then be installed by the external application via

npm install /path/to/aiida-explorer-x.y.z.tgz

Publishing a new version of the library on npm

To make a new version and publish to npm via GitHub Actions:

npm version [major|minor|patch]
git push --follow-tags

(Note: no need to write the version number manually!)

Deploying the demo page to github-pages

The demo page is deployed to Github pages automatically from the main branch.

Additionally, any pull request gets deployed in it's own subpath as well.

Manual deployment to Github pages should not be done, as that might break any PR previews.

Notes

• An initial prototype of this tool was created by Sharan Poojari during Google Summer of Code 2024 (see the final report).