1# Recurrent Neural Network Driver
2
3## Usage
4``` sh
5    ./benchdnn --rnn [benchdnn-knobs] [rnn-knobs] [rnn-desc] ...
6```
7
8where *rnn-knobs* are:
9
10 - `--prop={FWD_I [default], FWD_D, BWD_DW}` -- dnnl_prop_kind_t.
11            Refer to [direction](knobs_dir.md) for details.
12 - `--cfg={f32 [default], ...}` -- refer to ``Configurations`` below.
13 - `--alg={VANILLA_RNN [default], VANILLA_LSTM, VANILLA_GRU, LBR_GRU}`
14            -- RNN algorithm.
15 - `--direction={left2right [default], right2left, concat, sum}` -- TBA.
16 - `--activation={RELU [default], LOGISTIC, TANH}` -- TBA.
17 - `--scaling="scale_str"` -- RNN scaling policy, default `""` (no scaling).
18 - `--scaling-proj="scale_str"` -- RNN scaling policy for the
19            projection weights, default `""` (no scaling).
20            Refer to [attributes](knobs_attr.md) for details.
21 - `--skip-nonlinear={true, false [default]}` -- specify if transcendental
22            activations will be treated as linear. This allows to test longer
23            chains avoiding errors coming from non-linear activation functions.
24            Especially relevant for int8 computations. For LSTM and GRU flows
25            changes internal implementation since there is no external control
26            over pre-defined activations in a cell.
27 - `--trivial-strides={true, false [default]}` -- specify if input tensors
28            should have trivial strides or not. Each tensor stride is the
29            product of previous dimensions.
30 - `--with-peephole={true, false [default]}` -- LSTM extension. Specify if LSTM
31            with peephole should be run.
32 - `--with-projection={true, false [default]}` -- LSTM extension. Specify if LSTM
33            with projection should be run.
34 - `--l=INT` -- override `l` (number of layers) value specified in the problem
35            descriptor. When `INT` is set to `0` (the default), use `l` value
36            specified in the problem descriptor.
37 - `--t=INT` -- override `t` (number of timestamps) value specified in the
38            problem descriptor. When `INT` is set to `0` (the default), use `t`
39            value specified in the problem descriptor.
40 - `--mb=INT` -- override `mb` (minibatch) value specified in the problem
41            descriptor. When `INT` is set to `0` (the default), use `mb` value
42            specified in the problem descriptor.
43
44and *rnn-desc* is a problem descriptor. The canonical form is:
45```
46 lXtXmbX_sicX_slcX_dhcX_dicX_nS
47```
48Here `X` is an integer number and `S` is a string literal without spaces (`n`
49stands for name). The special symbol `_` is ignored, so it may be used as a
50delimiter for better readability.
51
52Description of RNN descriptor symbols:
53 - `l` is the number of layers. The default value is `1`.
54 - `t` is the number of timestamps (or the sequence length). The default value
55   is `1`.
56 - `mb` is the minibatch. The default value is `2`.
57 - `sic` is the feature size of `src_iter`. No default value.
58 - `slc` is the feature size of `src_layer`. The default value is `sic`.
59 - `dhc` is the hidden feature size. The default value is `sic`.
60 - `dic` is the feature size of `dst_iter`. The default value is `dhc`. For GRU
61   it must be equal to `dhc`.
62
63
64## Precision Configurations
65
66The `--cfg` option specifies the [data types](knobs_dt.md) to be used for a
67problem. It also defines the data filling strategy. It is implicit for the
68integer type saturation. This option also defines the threshold for computation
69errors.
70
71The table below shows supported name configurations for this driver:
72
73| states | input | dst_iter  | dst_last_layer | cfg         | notes
74|:---    |:---   |:---       |:---            |:---         |:---
75| f32    | f32   | f32       | f32            | f32         | TBA
76| u8     | u8    | u8        | u8             | u8u8u8u8    | TBA
77| u8     | u8    | u8        | f32            | u8u8u8f32   | TBA
78| f32    | u8    | f32       | u8             | f32u8f32u8  | TBA
79| f32    | u8    | f32       | f32            | f32u8f32f32 | TBA
80| f16    | f16   | f16       | f16            | f16         | Only for GPU
81
82
83## Essence of Testing
84TBA.
85
86
87## Examples. TBA.
88
89Run the set of rnn training from an input file with the default settings:
90``` sh
91    ./benchdnn --rnn --batch=inputs/rnn/shapes_training
92```
93
94More examples with different driver options can be found at inputs/rnn/test_***.
95Examples with different problem descriptors can be found at
96inputs/rnn/shapes_***. More examples with different benchdnn common options can
97be found at driver_conv.md.
98