Skip to content

Commit 57f09df

Browse files
authored
[docs] clarify ordering of nonlinear tape (#2401)
1 parent c320ca7 commit 57f09df

File tree

1 file changed

+12
-3
lines changed

1 file changed

+12
-3
lines changed

docs/src/submodules/Nonlinear/overview.md

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -487,12 +487,14 @@ julia> struct Expression
487487
```
488488

489489
For each node `node` in the `.nodes` field, if `node.type` is:
490+
490491
* `NODE_CALL_MULTIVARIATE`, we look up
491492
`MULTIVARIATE_OPERATORS[node.index]` to retrieve the operator
492493
* `NODE_CALL_UNIVARIATE`, we look up
493494
`UNIVARIATE_OPERATORS[node.index]` to retrieve the operator
494495
* `NODE_VARIABLE`, we create `MOI.VariableIndex(node.index)`
495496
* `NODE_VALUE`, we look up `values[node.index]`
497+
496498
The `.parent` field of each node is the integer index of the parent node in
497499
`.nodes`. For the first node, the parent is `-1` by convention.
498500

@@ -511,6 +513,16 @@ julia> expr = Expression(
511513
);
512514
```
513515

516+
The ordering of the nodes in the tape must satisfy two rules:
517+
518+
* The children of a node must appear after the parent. This means that the tape
519+
is ordered topologically, so that a reverse pass of the nodes evaluates all
520+
children nodes before their parent
521+
* The arguments for a `CALL` node are ordered in the tape based on the order in
522+
which they appear in the function call.
523+
524+
#### Design goals
525+
514526
This is less readable than the other options, but does this data structure meet
515527
our design goals?
516528

@@ -524,9 +536,6 @@ easy to identify the _parent_ of any node. Therefore, we can use
524536
[`Nonlinear.adjacency_matrix`](@ref) to compute a sparse matrix that maps
525537
parents to their children.
526538

527-
The tape is also ordered topologically, so that a reverse pass of the nodes
528-
evaluates all children nodes before their parent.
529-
530539
### The design in practice
531540

532541
In practice, `Node` and `Expression` are exactly [`Nonlinear.Node`](@ref)

0 commit comments

Comments
 (0)