Naming: Consider renaming `WorkGraph.nodes`

[sphuber]

The WorkGraph.nodes property returns a collection of "nodes" of the workgraph. These nodes are not the same as nodes in AiiDA's provenance graph and this is bound to cause confusion. Nodes in the workgraph context are really the subprocesses or steps of the workgraph. In the provenance graph, nodes can also refer to the inputs and outputs of the processes.

The suggestion is therefore to find another name for the nodes property of WorkGraph. Since conceptually they refer to the steps of the workgraph (or workflow) it might make sense to use a word in that direction:

• WorkGraph.processes
• WorkGraph.steps
• WorkGraph.operations

[superstar54]

Thanks @sphuber for the suggestion.

Possible Choices

• processes: This can be confusing due to its overlap with the AiiDA process (e.g., verdi process list/kill), where a process only exists when the job is running.
• steps: it is used within WorkChain to refer to sequential execution, thus not suitable for WorkGraph, which is not sequential execution.
• operation: Implies a standalone operation and does not suggest connectivity or interaction with others.
• task, job: Commonly used in other frameworks, which I prefer to avoid.
• junction, knot, vertex, unit, block, cell, action: These are considered, but are not fully capture the intended functionality.
• work: I prefer this, but it is not commonly used in this context in English.
• workunit, worknode: I am leaning towards using worknode, to imply the connectivity or interaction with others.

WorkNode

WorkNode is the foundational building block of the WorkGraph. A WorkNode has inputs, outputs, and an executor. Below is how users can define and utilize a WorkNode:

from aiida_workgraph import worknode, WorkGraph

# Define a standard worknode
@worknode()
def add(x, y):
    return x + y

# Define a calcfunction worknode
@worknode.calcfunction()
def multiply(x, y):
    return x * y

# Visualize the worknode in Jupyter Notebook
add.worknode()

# Create a WorkGraph to link the nodes.
wg = WorkGraph("test_add_multiply")
wg.nodes.new(add, name="add1")
wg.nodes.new(multiply, name="multiply1")
wg.links.new(wg.nodes["add1"].outputs["result"], wg.nodes["multiply1"].inputs["x"])

Comparison with Other AiiDA Nodes

• WorkNode is a node in the WorkGraph.
• An AiiDA node refers to a node in the database. Although the Node concept in AiiDA is complex (e.g., Data Node, ProcessNode, WorkChainNode), and there are distinctions between a Process and its Node.

To distinguish from AiiDA Node, we consistently use Work and Node together (WorkNode) to indicate it is a node in the WorkGraph.

@sphuber, @mbercx, @giovannipizzi, if you are not against this, I will proceed with it.

[khsrali]

It could be GraphNode?

[sphuber]

The worknode option does limit potential confusion with AiiDA terms somewhat but can still be confused with WorkflowNode etc. But admittedly, the other options I suggested also suffer from this.

When it comes to intuitiveness, I don't think worknode is that great. I still think that it would be better to have a term that indicates what it does rather than what it is in the implementation. The node concept really focuses on the fact that it is just a node in the graph, but when you look at it from the UI perspective, the user wants to communicate an action. So I think a term that directly conveys this action would be best. This is why I suggested words like process, step, operation.

You say that you actively avoided task because it is used in other frameworks. Why is that a bad thing? I think this could fit well perhaps.

[superstar54]

The worknode option does limit potential confusion with AiiDA terms somewhat but can still be confused with WorkflowNode etc.

From the user's point of view, they rarely encounter the WorkflowNode etc.

The node concept really focuses on the fact that it is just a node in the graph, but when you look at it from the UI perspective, the user wants to communicate an action.

This is true for the DataNode, but not for the ProcessNode. Instead, one can load the ProcessNode and show it's input and output ports.

node = load_node(pk)
node.inputs
node.ouputs

Similar logic for the WorkNode, it's a node in the WorkGraph, and has its own input and output ports, as seen in the UI.

You say that you actively avoided task because it is used in other frameworks. Why is that a bad thing? I think this could fit well perhaps.

I think choosing a distinct name makes it easier for developers to understand the unique features of our API instead of mixing it with another framework, thus avoiding misinterpretations of our API.

[giovannipizzi]

I still think that Task could be an interesting option. Or WorkTask if we really want to make it distinct?