1/*******************************************************************************
2* Copyright 2020-2022 Intel Corporation
3*
4* Licensed under the Apache License, Version 2.0 (the "License");
5* you may not use this file except in compliance with the License.
6* You may obtain a copy of the License at
7*
8* http://www.apache.org/licenses/LICENSE-2.0
9*
10* Unless required by applicable law or agreed to in writing, software
11* distributed under the License is distributed on an "AS IS" BASIS,
12* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13* See the License for the specific language governing permissions and
14* limitations under the License.
15*******************************************************************************/
16
17/// @example lstm.cpp
18/// > Annotated version: @ref lstm_example_cpp
19///
20/// @page lstm_example_cpp_short
21///
22/// This C++ API example demonstrates how to create and execute an
23/// [LSTM RNN](@ref dev_guide_rnn) primitive in forward training propagation
24/// mode.
25///
26/// Key optimizations included in this example:
27/// - Creation of optimized memory format from the primitive descriptor.
28///
29/// @page lstm_example_cpp LSTM RNN Primitive Example
30/// @copydetails lstm_example_cpp_short
31///
32/// @include lstm.cpp
33
34#include <algorithm>
35#include <cmath>
36#include <iostream>
37#include <string>
38#include <vector>
39
40#include "example_utils.hpp"
41#include "oneapi/dnnl/dnnl.hpp"
42
43using namespace dnnl;
44
45using tag = memory::format_tag;
46using dt = memory::data_type;
47
48void lstm_example(dnnl::engine::kind engine_kind) {
49
50 // Create execution dnnl::engine.
51 dnnl::engine engine(engine_kind, 0);
52
53 // Create dnnl::stream.
54 dnnl::stream engine_stream(engine);
55
56 // Tensor dimensions.
57 const memory::dim N = 26, // batch size
58 T = 6, // time steps
59 C = 12, // channels
60 G = 4, // gates
61 L = 4, // layers
62 D = 1; // directions
63
64 // Source (src), weights, bias, and destination (dst) tensors
65 // dimensions.
66 memory::dims src_dims = {T, N, C};
67 memory::dims weights_dims = {L, D, C, G, C};
68 memory::dims bias_dims = {L, D, G, C};
69 memory::dims dst_dims = {T, N, C};
70
71 // Allocate buffers.
72 std::vector<float> src_layer_data(product(src_dims));
73 std::vector<float> weights_layer_data(product(weights_dims));
74 std::vector<float> weights_iter_data(product(weights_dims));
75 std::vector<float> dst_layer_data(product(dst_dims));
76 std::vector<float> bias_data(product(bias_dims));
77
78 // Initialize src, weights, and bias tensors.
79 std::generate(src_layer_data.begin(), src_layer_data.end(), []() {
80 static int i = 0;
81 return std::cos(i++ / 10.f);
82 });
83 std::generate(weights_layer_data.begin(), weights_layer_data.end(), []() {
84 static int i = 0;
85 return std::sin(i++ * 2.f);
86 });
87 std::generate(bias_data.begin(), bias_data.end(), []() {
88 static int i = 0;
89 return std::tanh(float(i++));
90 });
91
92 // Create memory descriptors and memory objects for src, bias, and dst.
93 auto src_layer_md = memory::desc(src_dims, dt::f32, tag::tnc);
94 auto bias_md = memory::desc(bias_dims, dt::f32, tag::ldgo);
95 auto dst_layer_md = memory::desc(dst_dims, dt::f32, tag::tnc);
96
97 auto src_layer_mem = memory(src_layer_md, engine);
98 auto bias_mem = memory(bias_md, engine);
99 auto dst_layer_mem = memory(dst_layer_md, engine);
100
101 // Create memory objects for weights using user's memory layout. In this
102 // example, LDIGO is assumed.
103 auto user_weights_layer_mem
104 = memory({weights_dims, dt::f32, tag::ldigo}, engine);
105 auto user_weights_iter_mem
106 = memory({weights_dims, dt::f32, tag::ldigo}, engine);
107
108 // Write data to memory object's handle.
109 write_to_dnnl_memory(src_layer_data.data(), src_layer_mem);
110 write_to_dnnl_memory(bias_data.data(), bias_mem);
111 write_to_dnnl_memory(weights_layer_data.data(), user_weights_layer_mem);
112 write_to_dnnl_memory(weights_iter_data.data(), user_weights_iter_mem);
113
114 // Create memory descriptors for weights with format_tag::any. This enables
115 // the LSTM primitive to choose the optimized memory layout.
116 auto lstm_weights_layer_md = memory::desc(weights_dims, dt::f32, tag::any);
117 auto lstm_weights_iter_md = memory::desc(weights_dims, dt::f32, tag::any);
118
119 // Optional memory descriptors for recurrent data.
120 auto src_iter_md = memory::desc();
121 auto src_iter_c_md = memory::desc();
122 auto dst_iter_md = memory::desc();
123 auto dst_iter_c_md = memory::desc();
124
125 // Create primitive descriptor.
126 auto lstm_pd = lstm_forward::primitive_desc(engine,
127 prop_kind::forward_training,
128 rnn_direction::unidirectional_left2right, src_layer_md, src_iter_md,
129 src_iter_c_md, lstm_weights_layer_md, lstm_weights_iter_md, bias_md,
130 dst_layer_md, dst_iter_md, dst_iter_c_md);
131
132 // For now, assume that the weights memory layout generated by the primitive
133 // and the ones provided by the user are identical.
134 auto lstm_weights_layer_mem = user_weights_layer_mem;
135 auto lstm_weights_iter_mem = user_weights_iter_mem;
136
137 // Reorder the data in case the weights memory layout generated by the
138 // primitive and the one provided by the user are different. In this case,
139 // we create additional memory objects with internal buffers that will
140 // contain the reordered data.
141 if (lstm_pd.weights_desc() != user_weights_layer_mem.get_desc()) {
142 lstm_weights_layer_mem = memory(lstm_pd.weights_desc(), engine);
143 reorder(user_weights_layer_mem, lstm_weights_layer_mem)
144 .execute(engine_stream, user_weights_layer_mem,
145 lstm_weights_layer_mem);
146 }
147
148 if (lstm_pd.weights_iter_desc() != user_weights_iter_mem.get_desc()) {
149 lstm_weights_iter_mem = memory(lstm_pd.weights_iter_desc(), engine);
150 reorder(user_weights_iter_mem, lstm_weights_iter_mem)
151 .execute(engine_stream, user_weights_iter_mem,
152 lstm_weights_iter_mem);
153 }
154
155 // Create the memory objects from the primitive descriptor. A workspace is
156 // also required for LSTM.
157 // NOTE: Here, the workspace is required for later usage in backward
158 // propagation mode.
159 auto src_iter_mem = memory(lstm_pd.src_iter_desc(), engine);
160 auto src_iter_c_mem = memory(lstm_pd.src_iter_c_desc(), engine);
161 auto weights_iter_mem = memory(lstm_pd.weights_iter_desc(), engine);
162 auto dst_iter_mem = memory(lstm_pd.dst_iter_desc(), engine);
163 auto dst_iter_c_mem = memory(lstm_pd.dst_iter_c_desc(), engine);
164 auto workspace_mem = memory(lstm_pd.workspace_desc(), engine);
165
166 // Create the primitive.
167 auto lstm_prim = lstm_forward(lstm_pd);
168
169 // Primitive arguments
170 std::unordered_map<int, memory> lstm_args;
171 lstm_args.insert({DNNL_ARG_SRC_LAYER, src_layer_mem});
172 lstm_args.insert({DNNL_ARG_WEIGHTS_LAYER, lstm_weights_layer_mem});
173 lstm_args.insert({DNNL_ARG_WEIGHTS_ITER, lstm_weights_iter_mem});
174 lstm_args.insert({DNNL_ARG_BIAS, bias_mem});
175 lstm_args.insert({DNNL_ARG_DST_LAYER, dst_layer_mem});
176 lstm_args.insert({DNNL_ARG_SRC_ITER, src_iter_mem});
177 lstm_args.insert({DNNL_ARG_SRC_ITER_C, src_iter_c_mem});
178 lstm_args.insert({DNNL_ARG_DST_ITER, dst_iter_mem});
179 lstm_args.insert({DNNL_ARG_DST_ITER_C, dst_iter_c_mem});
180 lstm_args.insert({DNNL_ARG_WORKSPACE, workspace_mem});
181
182 // Primitive execution: LSTM.
183 lstm_prim.execute(engine_stream, lstm_args);
184
185 // Wait for the computation to finalize.
186 engine_stream.wait();
187
188 // Read data from memory object's handle.
189 read_from_dnnl_memory(dst_layer_data.data(), dst_layer_mem);
190}
191
192int main(int argc, char **argv) {
193 return handle_example_errors(lstm_example, parse_engine_kind(argc, argv));
194}
195