aaronmarkham commented on a change in pull request #12340: Add a tutorial for control flow operators. URL: https://github.com/apache/incubator-mxnet/pull/12340#discussion_r212778449
########## File path: docs/tutorials/control_flow/ControlFlowTutorial.md ########## @@ -0,0 +1,386 @@ + +MXNet currently provides three control flow operators: `cond`, `foreach` and `while_loop`. Like other MXNet operators, they all have a version for NDArray and a version for Symbol. These two versions have exactly the same semantics. We can take advantage of this and use them in Gluon to hybridize models. + +In this tutorial, we use a few examples to demonstrate the use of control flow operators in Gluon and show how a model that requires control flow is hybridized. + +# Prepare running the code + + +```python +import mxnet as mx +from mxnet.gluon import HybridBlock +``` + +# foreach +`foreach` is defined with the following signature: + +```python +foreach(body, data, init_states, name) => (outputs, states) +``` + +It iterates over the first dimension of the input data (it can be an array or a list of arrays) and run the Python function defined in `body` for every slice from the input arrays. The signature of the `body` function is defined as follows: + +```python +body(data, states) => (outputs, states) +``` + +The inputs of the `body` function have two parts: `data` is a slice of an array (if there is only one input array in `foreach`) or a list of slices (if there are a list of input arrays); `states` are the arrays from the previous iteration. The outputs of the `body` function also have two parts: `outputs` is an array or a list of arrays; `states` is the computation states of the current iteration. `outputs` from all iterations are concatenated as the outputs of `foreach`. + +The pseudocode below illustrates the execution of `foreach`. + +```python +def foreach(body, data, init_states): + states = init_states + outs = [] + + for i in range(data.shape[0]): + s = data[i] + out, states = body(s, states) + outs.append(out) + outs = mx.nd.stack(*outs) + return outs, states +``` + +### Example 1: foreach works like map +`foreach` can work like a map function of a functional language. In this case, the states of foreach can be an empty list, which means the computation doesn't carry computation states across iterations. + +In this example, we use `foreach` to add each element in an array by one. Review comment: use foreach with an array to increase each element's value by one ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
