AiiDA-WorkGraph
A powerful Python library for creating, managing, and executing scalable scientific workflows with automatic data provenance.
✨ Why AiiDA-WorkGraph?
AiiDA-WorkGraph empowers researchers and developers to build complex, reproducible workflows with ease.
- 🎨 Pythonic Workflow Design: Define workflows using familiar Python functions and decorators.
- 🖥️ Interactive GUI: Visualize, monitor, and debug your workflows in real-time with a user-friendly web interface.
- 🔗 Automatic Data Provenance: Guarantee scientific reproducibility with zero effort. The complete history of all data and calculations is automatically tracked.
- 🚀 Remote & Parallel Execution: Seamlessly offload tasks to remote supercomputers and run them concurrently.
- 🧠 Dynamic Control Flow: Build adaptive workflows that respond to data at runtime using standard Python
if/elsestatements and loops. - 🛡️ Checkpointing & Error Handling: Protect long-running workflows from interruptions and build resilient logic to recover from failures.
- ⚡ High-Throughput Computing: Built to scale, AiiDA-WorkGraph can efficiently manage thousands of concurrent workflows.
- 🧩 Reusable Components: Encapsulate common routines as sub-workflows and easily reuse them in larger, more complex pipelines.
🚀 Getting Started
1. Installation
pip install aiida-workgraph
First, ensure you have a working AiiDA environment.
verdi presto # Or 'verdi quicksetup' for a detailed setup
2. Quick Start Example
Let's create a simple workflow to calculate $(x + y) \times z$.
1️⃣ Define Tasks
Use the @task decorator to turn Python functions into workflow components.
from aiida_workgraph import task
@task
def add(x, y):
"""Adds two numbers."""
return x + y
@task
def multiply(x, y):
"""Multiplies two numbers."""
return x * y
2️⃣ Compose a Workflow
Use the @task.graph decorator to link tasks. Data flows naturally from one task's output to the next one's input.
@task.graph
def add_multiply(x, y, z):
"""A workflow to add two numbers and then multiply by a third."""
sum_result = add(x, y).result
product_result = multiply(x=sum_result, y=z).result
return product_result
3️⃣ Run the Workflow
Build the workflow with your inputs and run it.
from aiida import load_profile
# Load your AiiDA profile
load_profile()
# Build and run the workflow
results = add_multiply.run(x=2, y=3, z=4)
# Print the final result
print(f"✅ Result: {results}")
# Expected output: ✅ Result: 20
4️⃣ Automatic Provenance Tracking
AiiDA-WorkGraph automatically generates a detailed provenance graph, tracking the full history of data and calculations to ensure full traceability and reproducibility. Here is an example of the provenance graph generated for the above workflow:
🛠️ Flexible Workflow Construction
AiiDA-WorkGraph supports three complementary approaches to building workflows, letting you choose the best method for your needs.
-
🐍 Pythonic Workflows (Recommended): Use
@task.graphfor clean, readable, and powerful workflows, as shown in the Quick Start. -
👁️ Visual Graph with Explicit Logic: Use zones like
If,While, andMapto build a graph where the control flow is visually explicit. -
⚙️ Low-Level Node-Graph Programming: Programmatically define each task and link them manually for maximum control and dynamic graph generation.
🖥️ Interactive GUI
Visualize, monitor, and debug your workflows in real-time. To launch the GUI, first install the package and then run:
pip install aiida-gui-workgraph
aiida-gui start
Navigate to http://127.0.0.1:8000/workgraph in your web browser.
Note: The GUI is an experimental feature and is under active development.
🔗 Useful Links
- 📚 Full Documentation: Dive deep into all features and capabilities.
- 🧪 Demo & Examples Repository: See real-world examples with various computational codes.
- 🧑💻 Development & Contribution: Learn how to contribute to the project.
- 📄 License: AiiDA-WorkGraph is licensed under the MIT License.
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file aiida_workgraph-0.8.1.tar.gz.
File metadata
- Download URL: aiida_workgraph-0.8.1.tar.gz
- Upload date:
- Size: 62.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.9.25
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
e30a9da73ffdd6643eee6217ff3a7a0b48a88c9bde358ad2d2e06230d93ebbbf
|
|
| MD5 |
3f1d94f6ff672eb2a9654c55fc502033
|
|
| BLAKE2b-256 |
870a90eea7ffc10e748e8135efe108a435c9a7b70969b20a34fac42293f658f2
|
File details
Details for the file aiida_workgraph-0.8.1-py3-none-any.whl.
File metadata
- Download URL: aiida_workgraph-0.8.1-py3-none-any.whl
- Upload date:
- Size: 79.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
twine/6.2.0 CPython/3.9.25
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
75304b462a0bd5530f13c9df30c7f680654d5ada012f204d7c7d4589c01de6b7
|
|
| MD5 |
973669d71a45ff99c3fa59d367f003cc
|
|
| BLAKE2b-256 |
f153173691a9630b32099ef114a29c30df3285c3d0a2f2066304302ff3b428d3
|
