Metadata-Version: 2.4
Name: aiida-workgraph
Version: 1.0.0b2
Summary: Design flexible node-based workflow for AiiDA calculation.
Keywords: aiida,workflows
Author-email: Xing Wang <xingwang1991@gmail.com>
Requires-Python: >=3.9,<3.14
Description-Content-Type: text/markdown
Classifier: Development Status :: 1 - Planning
Classifier: Framework :: AiiDA
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: node-graph==0.3.12
Requires-Dist: node-graph-widget>=0.0.5
Requires-Dist: aiida-core~=2.7.1
Requires-Dist: cloudpickle
Requires-Dist: aiida-shell~=0.8
Requires-Dist: aiida-pythonjob==0.4.4
Requires-Dist: jsonschema
Requires-Dist: sphinx_rtd_theme>=3.0 ; extra == "docs"
Requires-Dist: sphinx~=7.2 ; extra == "docs"
Requires-Dist: sphinx-copybutton~=0.5.0 ; extra == "docs"
Requires-Dist: sphinx-design~=0.5.0 ; extra == "docs"
Requires-Dist: sphinx-notfound-page~=1.0 ; extra == "docs"
Requires-Dist: sphinxext-rediraffe~=0.2.4 ; extra == "docs"
Requires-Dist: sphinx-intl~=2.1.0 ; extra == "docs"
Requires-Dist: sphinx-gallery ; extra == "docs"
Requires-Dist: myst-nb~=1.0.0 ; extra == "docs"
Requires-Dist: nbsphinx ; extra == "docs"
Requires-Dist: furo ; extra == "docs"
Requires-Dist: aiida-core~=2.7.1 ; extra == "docs"
Requires-Dist: aiida-quantumespresso ; extra == "docs"
Requires-Dist: aiida-pseudo ; extra == "docs"
Requires-Dist: anywidget ; extra == "docs"
Requires-Dist: sphinx-autobuild ; extra == "docs"
Requires-Dist: click~=8.1.0 ; extra == "docs"
Requires-Dist: pre-commit~=4.3 ; extra == "pre-commit"
Requires-Dist: pgtest~=1.3 ; extra == "tests"
Requires-Dist: pytest~=7.0 ; extra == "tests"
Requires-Dist: pytest-cov~=2.7,<2.11 ; extra == "tests"
Requires-Dist: pytest-xdist~=3.8 ; extra == "tests"
Requires-Dist: playwright ; extra == "tests"
Requires-Dist: httpx ; extra == "tests"
Project-URL: Documentation, https://aiida-workgraph.readthedocs.io
Project-URL: Source, https://github.com/aiidateam/aiida-workgraph
Provides-Extra: docs
Provides-Extra: pre-commit
Provides-Extra: tests

# AiiDA-WorkGraph
[![PyPI version](https://badge.fury.io/py/aiida-workgraph.svg)](https://badge.fury.io/py/aiida-workgraph)
[![Unit test](https://github.com/aiidateam/aiida-workgraph/actions/workflows/ci.yaml/badge.svg)](https://github.com/aiidateam/aiida-workgraph/actions/workflows/ci.yaml)
[![codecov](https://codecov.io/gh/aiidateam/aiida-workgraph/branch/main/graph/badge.svg)](https://codecov.io/gh/aiidateam/aiida-workgraph)
[![Docs status](https://readthedocs.org/projects/aiida-workgraph/badge)](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.

