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 | |
43 | using namespace dnnl; |
44 | |
45 | using tag = memory::format_tag; |
46 | using dt = memory::data_type; |
47 | |
48 | void 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 | |
192 | int main(int argc, char **argv) { |
193 | return handle_example_errors(lstm_example, parse_engine_kind(argc, argv)); |
194 | } |
195 | |