---
# System prepended metadata

title: Discussion on the name and syntax of WorkGraph (previous WorkTree)

---

# Discussion on the name and syntax of WorkGraph (previous WorkTree)

Before we make an official release, we need to think about and fix the names and syntax of the variables and API. 

## WorkGraph
Previous `WorkTree` is pronounced similarly to `WorkChain`, which is not good. So we changed it to `WorkGraph`, indicating that it creates a graph for the workflow.

Is `WorkGraph` good enough? How about `AnyFlow` or `AnyGraph`: indicates that it's very powerful, by combing nodes to construct any workflow.

## node
`node` is the decorator that creates the Node class.
```python
@node()
def add(x, y):
  return x+y

@node.calcfunction()
def multiply(x, y):
  return x*y

@node.group(outputs=[["add1.result", "sum"],
                     ["multiply.result", "product"]])
def add_multiply(x, y, z):
  wt = WorkTree()
  wt.nodes.new(add, name="add1")
  wt.nodes.new(multiply, name="multiply1")
  return wt
```
`node` is also confusing with AiiDA nodes. Any comment on the name?

> [Mbx] Would it be possible to just use an `aiida.engine.calcfunction` instead when adding a node to the worktree? If I would have to convert my previously created `calcfunction`s to use them in the `WorkTree`, it would seriously inhibit me using it.


## Validatoin of inputs/outputs sockets
One can also define the inputs/outputs sockets explicitly.


```python
@node.calcfunction(outputs=[["General", "sum"],
                            ["General", "difference"]])
def add_minus(x, y):
  return {"sum": x+y, "difference": x-y}
```
The first value `General` indicates the data type. We use `General` for any data type. Since the order of the socket is important, so we can not use a dictionary for this.

> [MBx]  So this is adding validation to the output types? Why not just use the class then? I don't understand the "socket" concept, how is it different from a "port"?
> More generally, I think it's important that we try and reuse the concepts already in AiiDA as much as possible, and that the concepts are the same. Adding a lot of new ones to the long list we already have will be problematic.

Please continue this discusssion in this [issue](https://github.com/superstar54/aiida-workgraph/issues/51)


## Add node and link
Worktree has `nodes` and `links` attributes, one can add new node and link by:
```python
add1 = wt.nodes.new(add, name="add1", x=2, y=3)
multiply1= wt.nodes.new(multiply, name="multiply1", y=2)
wt.links.new(add1.outputs[0], multiply1.inputs["x"])
```
One can make an alias in case adding many nodes:
```
new = wt.nodes.new
new(add, name="add1")
new(multiply, name="multiply1")
```

Instead of add link explicitly, one can also pass the output socket as input when creating node:
```python
multiply1= wt.nodes.new(multiply, name="multiply1", x=add1.outputs[0], y=2)
```
in case of nested input name:
```python
scf_node= wt.nodes.new(PwBaseNode, name="scf")
multiply1.set({"pw.structure": relax_node.outputs["output_structure"]})
```

Any comment on the name?


## while group
One can run a WorkTree repeatedly until the conditions are fulfilled. To do this, only need to set the `worktree_type` as `WHILE`, and add `conditions`.
```python
wt = WorkTree("while_worktree")
wt.worktree_type = "WHILE"
wt.max_iteration = 5
# use both the output of compare1 and variable form context as conditions
wt.conditions = ["compare1.result", "ctx.is_converged"]
```
Names to be discussed:
- is `worktree_type` good? or simpily change it to `type`? or use `is_while_worktree`?
- `max_iteration` is the maximum number of execution times for this while work tree.
- is `wt.conditions = ["compare1.result", "ctx.is_converged"]` good?


## to_ctx
Save the result of a node to the context.
```python
# expose add1.sum to ctx.n
add1.to_ctx = [["sum", "n"]]
```
What about other names for `to_ctx`? e.g. `to_context`, `to_golbal`.

Since the order of `sum` and `n` is not important, we may also change it to
```python!

add1.to_ctx = {"sum": "n"}
# or
add1.to_ctx = {"n": "sum"}
```
which one do you prefer?


## from ctx
If a node read data from context as input value, `{{name}}` is used.


```python!
# use `current_structure` from ctx
seekpath_node = tree.nodes.new(
        SeekpathNode,
        structure='{{current_structure}}',
    )
```

## Build node from others
One can build a node from an already existing AiiDA component: `calcfunction`,  `workfunction`, `calcjob`, `Workchain` with the `build_node` function.
```python!
from aiida_worktree import build_node
AddNode = build_node({"path": "aiida.calculations.arithmetic.add.ArithmeticAddCalculation"})
```

One can also build a node from a WorkTree
```python!
wt1 = WorkTree()
wt1.nodes.new(add, name="add")
wt1.nodes.new(multiply, name="multiply", x=wt1.nodes["add"].outputs[0])
# create a node using the WorkTree
AddMultiplyNode = build_node(wt1)
```

is `build_node` a good name?


> [MBx] I think the syntax of `build_node` is rather cumbersome. Why can't I just import the `PwCalculation` and then do add it with `wt1.nodes.new`? It should be able to figure out the path and build the node on the fly, no?

Please continue the discussion on this [issue](https://github.com/superstar54/aiida-workgraph/issues/48)

## Method namespacing

[Edan] Why not just `.add_node` instead `.nodes.new`?

-> `add_node` makes more sense. `.nodes` already serves as a collection.



## Group

- dynamic_group
- group_builder
- group_generator