Quick Start

Introduction

This quick-start tutorial is intended to demonstrate the very basics of WorkGraph. We do so through a simple arithmetic workflow. At the end of the tutorial, we will suggest some next steps to help you apply WorkGraph principles to your real-world workflows.

Setup

Let’s first install aiida-workgraph (this will also install aiida-core automatically):

$ pip install aiida-workgraph

To interact with the AiiDA database, we need to load an AiiDA profile. If you haven’t configured one yet, you can do so by running the following command:

$ verdi presto

Note

The rest of the quick start tutorial is best followed using a Jupyter notebook.

To load your profile, run the following code:

from aiida import load_profile

load_profile()

Profile<uuid='2c6af82ef2b241408a4c27c7c32d5490' name='presto'>

Tip

Some features of WorkGraph are best demonstrated interactively. We recommend using the AiiDA GUI for this. You can learn how to run and use the GUI in the WorkGraph web UI section.

Simple workflow

Suppose you want to compute (x + y) * z as a workflow of two distinct tasks: (i) addition, and (ii) multiplication. Let’s see how we can do this using WorkGraph:

First, let’s define our tasks using the @task decorator:

from aiida_workgraph import task


@task
def add(x, y):
    return x + y


@task
def multiply(x, y):
    return x * y

Note

To learn more about the @task decorator, visit the Task concept section.

Next, we use our tasks to define a workflow using the @task.graph decorator:

@task.graph
def AddMultiply(x, y, z):
    the_sum = add(x=x, y=y).result
    return multiply(x=the_sum, y=z).result

Note

To learn more about the @task.graph decorator, visit the Graph Task concept section.

The workflow accepts three input parameters, x, y, and z. It passes x and y to the add task, which computes their sum. The sum is then passed to the multiply task along with z. The result of the multiplication task is returned as the output of the workflow.

Note

Calling a @task-decorated Python function returns a socket namespace - a collection of output sockets. We do this to allow tasks to have multiple outputs. We access a given socket with .<socket_name>. In the absence of explicit definition of output sockets, the default socket is named result.

You can learn more about these features in the Sockets concept section.

Let’s build the workflow with some input and visualize it:

wg = AddMultiply.build(x=2, y=3, z=4)
wg

We can see our two tasks, the assignment of the sum to the multiplication task, and the subsequent assignment of the product to the workflow (graph) result.

Let’s run the workflow and inspect the result:

wg.run()

print('Result:', wg.outputs.result.value)

Result: uuid: 9338ac58-83a6-4785-897b-384bef70d66f (pk: 9) value: 20

We can also access the results of the individual tasks:

print('Result of addition:', wg.tasks.add.outputs.result.value)
print('Result of multiplication:', wg.tasks.multiply.outputs.result.value)

Result of addition: uuid: 21289053-d3dc-4ae2-bead-1ae4e06b7d07 (pk: 7) value: 5
Result of multiplication: uuid: 9338ac58-83a6-4785-897b-384bef70d66f (pk: 9) value: 20

Note

Functional tasks (i.e., Python functions decorated with @task) are automatically named by their function name. If you call the same task multiple times, subsequent calls will be suffixed with a number, e.g., add1, add2, etc.

Tip

If you’re running the AiiDA GUI, you can visualize the executed workflow interactively. Click on the PK field of the submitted workflow (look for WorkGraph<AddMultiply>) to view its details.

Data provenance

Maintaining a consistent data provenance is crucial for reproducibility and understanding a workflow’s behavior. Much like AiiDA’s core components, WorkGraph ensures full data provenance, tracking inputs, processes, and outputs.

Let’s have a look at the full data provenance of our executed workflow:

wg.generate_provenance_graph()

Summary

This wraps up our quick start tutorial. You have learned how to:

• Define tasks using the @task decorator

• Define a workflow using the @task.graph decorator

• Visualize the workflow (tasks and their connections)

• Build and run a workflow with input parameters

• Inspect results and data provenance

What’s Next

Concepts	Learn the core concepts behind AiiDA-WorkGraph.
Tutorials	Discover real-world examples in computational materials science and other domains.
How-To Guides	Master advanced topics like control flow with if, for, while, and context.
GUI	Use the web UI to explore WorkGraphs.