| Name | aiida-workgraph JSON |
| Version |
0.7.0
JSON |
| download |
| home_page | None |
| Summary | Design flexible node-based workflow for AiiDA calculation. |
| upload_time | 2025-09-14 20:33:28 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
aiida
workflows
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# AiiDA-WorkGraph
[](https://badge.fury.io/py/aiida-workgraph)
[](https://github.com/aiidateam/aiida-workgraph/actions/workflows/ci.yaml)
[](https://codecov.io/gh/aiidateam/aiida-workgraph)
[](http://aiida-workgraph.readthedocs.io/)
**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/else` statements 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
```console
pip install aiida-workgraph
```
First, ensure you have a working AiiDA environment.
```console
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.
```python
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.
```python
@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.
```python
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:
</div>
<p align="center">
<img src="docs/source/_static/images/add_multiply.png" height="600" alt="Provenance Graph Example"/>
</p>
-----
## 🛠️ 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.graph` for clean, readable, and powerful workflows, as shown in the Quick Start.
- **👁️ Visual Graph with Explicit Logic**: Use zones like `If`, `While`, and `Map` to 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:
```console
pip install aiida-gui-workgraph
aiida-gui start
```
Navigate to `http://127.0.0.1:8000/workgraph` in your web browser.
</div>
<p align="center">
<img src="docs/source/_static/images/web-detail.png" width="90%" alt="AiiDA-WorkGraph Web UI"/>
</p>
> **Note:** The GUI is an experimental feature and is under active development.
-----
## 🔗 Useful Links
- **📚 [Full Documentation](https://aiida-workgraph.readthedocs.io/en/latest/)**: Dive deep into all features and capabilities.
- **🧪 [Demo & Examples Repository](https://github.com/superstar54/workgraph-collections)**: See real-world examples with various computational codes.
- **🧑💻 [Development & Contribution](https://aiida-workgraph.readthedocs.io/en/latest/development/index.html)**: Learn how to contribute to the project.
- **📄 [License](http://opensource.org/licenses/MIT)**: AiiDA-WorkGraph is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": null,
"name": "aiida-workgraph",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "aiida, workflows",
"author": null,
"author_email": "Xing Wang <xingwang1991@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/4a/03/299847f01997f38c6aa8641bfc2044f43f107d98f60cd3d6f577e0262187/aiida_workgraph-0.7.0.tar.gz",
"platform": null,
"description": "# AiiDA-WorkGraph\n[](https://badge.fury.io/py/aiida-workgraph)\n[](https://github.com/aiidateam/aiida-workgraph/actions/workflows/ci.yaml)\n[](https://codecov.io/gh/aiidateam/aiida-workgraph)\n[](http://aiida-workgraph.readthedocs.io/)\n\n**A powerful Python library for creating, managing, and executing scalable scientific workflows with automatic data provenance.**\n\n\n-----\n\n## \u2728 Why AiiDA-WorkGraph?\n\nAiiDA-WorkGraph empowers researchers and developers to build complex, reproducible workflows with ease.\n\n - **\ud83c\udfa8 Pythonic Workflow Design**: Define workflows using familiar Python functions and decorators.\n - **\ud83d\udda5\ufe0f Interactive GUI**: Visualize, monitor, and debug your workflows in real-time with a user-friendly web interface.\n - **\ud83d\udd17 Automatic Data Provenance**: Guarantee scientific reproducibility with zero effort. The complete history of all data and calculations is automatically tracked.\n - **\ud83d\ude80 Remote & Parallel Execution**: Seamlessly offload tasks to remote supercomputers and run them concurrently.\n - **\ud83e\udde0 Dynamic Control Flow**: Build adaptive workflows that respond to data at runtime using standard Python `if/else` statements and loops.\n - **\ud83d\udee1\ufe0f Checkpointing & Error Handling**: Protect long-running workflows from interruptions and build resilient logic to recover from failures.\n - **\u26a1 High-Throughput Computing**: Built to scale, AiiDA-WorkGraph can efficiently manage thousands of concurrent workflows.\n - **\ud83e\udde9 Reusable Components**: Encapsulate common routines as sub-workflows and easily reuse them in larger, more complex pipelines.\n\n-----\n\n## \ud83d\ude80 Getting Started\n\n### 1\\. Installation\n\n```console\npip install aiida-workgraph\n```\n\nFirst, ensure you have a working AiiDA environment.\n\n```console\nverdi presto # Or 'verdi quicksetup' for a detailed setup\n```\n\n### 2\\. Quick Start Example\n\nLet's create a simple workflow to calculate $(x + y) \\times z$.\n\n**1\ufe0f\u20e3 Define Tasks**\n\nUse the `@task` decorator to turn Python functions into workflow components.\n\n```python\nfrom aiida_workgraph import task\n\n@task\ndef add(x, y):\n \"\"\"Adds two numbers.\"\"\"\n return x + y\n\n@task\ndef multiply(x, y):\n \"\"\"Multiplies two numbers.\"\"\"\n return x * y\n```\n\n**2\ufe0f\u20e3 Compose a Workflow**\n\nUse the `@task.graph` decorator to link tasks. Data flows naturally from one task's output to the next one's input.\n\n```python\n@task.graph\ndef add_multiply(x, y, z):\n \"\"\"A workflow to add two numbers and then multiply by a third.\"\"\"\n sum_result = add(x, y).result\n product_result = multiply(x=sum_result, y=z).result\n return product_result\n```\n\n**3\ufe0f\u20e3 Run the Workflow**\n\nBuild the workflow with your inputs and run it.\n\n```python\nfrom aiida import load_profile\n\n# Load your AiiDA profile\nload_profile()\n\n# Build and run the workflow\nresults = add_multiply.run(x=2, y=3, z=4)\n\n# Print the final result\nprint(f\"\u2705 Result: {results}\")\n# Expected output: \u2705 Result: 20\n```\n\n**4\ufe0f\u20e3 Automatic Provenance Tracking**\n\nAiiDA-WorkGraph automatically generates a detailed provenance graph, tracking the full history of data and calculations to ensure full traceability and reproducibility.\nHere is an example of the provenance graph generated for the above workflow:\n\n</div>\n\n<p align=\"center\">\n<img src=\"docs/source/_static/images/add_multiply.png\" height=\"600\" alt=\"Provenance Graph Example\"/>\n</p>\n\n\n-----\n\n## \ud83d\udee0\ufe0f Flexible Workflow Construction\n\nAiiDA-WorkGraph supports three complementary approaches to building workflows, letting you choose the best method for your needs.\n\n - **\ud83d\udc0d Pythonic Workflows (Recommended)**: Use `@task.graph` for clean, readable, and powerful workflows, as shown in the Quick Start.\n\n - **\ud83d\udc41\ufe0f Visual Graph with Explicit Logic**: Use zones like `If`, `While`, and `Map` to build a graph where the control flow is visually explicit.\n\n - **\u2699\ufe0f Low-Level Node-Graph Programming**: Programmatically define each task and link them manually for maximum control and dynamic graph generation.\n\n-----\n\n\n## \ud83d\udda5\ufe0f Interactive GUI\n\nVisualize, monitor, and debug your workflows in real-time. To launch the GUI, first install the package and then run:\n\n\n```console\npip install aiida-gui-workgraph\naiida-gui start\n```\n\nNavigate to `http://127.0.0.1:8000/workgraph` in your web browser.\n\n</div>\n\n<p align=\"center\">\n<img src=\"docs/source/_static/images/web-detail.png\" width=\"90%\" alt=\"AiiDA-WorkGraph Web UI\"/>\n</p>\n\n> **Note:** The GUI is an experimental feature and is under active development.\n\n-----\n\n## \ud83d\udd17 Useful Links\n\n - **\ud83d\udcda [Full Documentation](https://aiida-workgraph.readthedocs.io/en/latest/)**: Dive deep into all features and capabilities.\n - **\ud83e\uddea [Demo & Examples Repository](https://github.com/superstar54/workgraph-collections)**: See real-world examples with various computational codes.\n - **\ud83e\uddd1\u200d\ud83d\udcbb [Development & Contribution](https://aiida-workgraph.readthedocs.io/en/latest/development/index.html)**: Learn how to contribute to the project.\n - **\ud83d\udcc4 [License](http://opensource.org/licenses/MIT)**: AiiDA-WorkGraph is licensed under the MIT License.\n\n",
"bugtrack_url": null,
"license": null,
"summary": "Design flexible node-based workflow for AiiDA calculation.",
"version": "0.7.0",
"project_urls": {
"Documentation": "https://aiida-workgraph.readthedocs.io",
"Source": "https://github.com/aiidateam/aiida-workgraph"
},
"split_keywords": [
"aiida",
" workflows"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d4d5023918dd0c69d2d7112b791fc86fb944f0f77d893ff8c5f170fdf6b5767e",
"md5": "9f2a15dad3e2d6ea62f6045b59329923",
"sha256": "d9ec93459429b234f9e369b1c3f9e38d833b3d7ff35d4d461cce4d54b9373e35"
},
"downloads": -1,
"filename": "aiida_workgraph-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f2a15dad3e2d6ea62f6045b59329923",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 89588,
"upload_time": "2025-09-14T20:33:27",
"upload_time_iso_8601": "2025-09-14T20:33:27.109860Z",
"url": "https://files.pythonhosted.org/packages/d4/d5/023918dd0c69d2d7112b791fc86fb944f0f77d893ff8c5f170fdf6b5767e/aiida_workgraph-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4a03299847f01997f38c6aa8641bfc2044f43f107d98f60cd3d6f577e0262187",
"md5": "91582adc989e367bdbd89b8cd41accf8",
"sha256": "ba8a7b62e5d5faff4e5c302beb470f128d3378f4d96047e32100692882769e5e"
},
"downloads": -1,
"filename": "aiida_workgraph-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "91582adc989e367bdbd89b8cd41accf8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 70234,
"upload_time": "2025-09-14T20:33:28",
"upload_time_iso_8601": "2025-09-14T20:33:28.595441Z",
"url": "https://files.pythonhosted.org/packages/4a/03/299847f01997f38c6aa8641bfc2044f43f107d98f60cd3d6f577e0262187/aiida_workgraph-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-14 20:33:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aiidateam",
"github_project": "aiida-workgraph",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aiida-workgraph"
}
