.. index:: pair: page; Convolution Primitive Example .. _doxid-convolution_example_cpp: Convolution Primitive Example ============================= This C++ API example demonstrates how to create and execute a :ref:`Convolution ` primitive in forward propagation mode in two configurations - with and without groups. Key optimizations included in this example: * Creation of optimized memory format from the primitive descriptor; * Primitive attributes with fused post-ops. .. ref-code-block:: cpp /******************************************************************************* * Copyright 2020-2022 Intel Corporation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. *******************************************************************************/ #include #include #include #include #include #include "example_utils.hpp" #include "oneapi/dnnl/dnnl.hpp" using namespace :ref:`dnnl `; using :ref:`tag ` = :ref:`memory::format_tag `; using :ref:`dt ` = :ref:`memory::data_type `; void convolution_example(:ref:`dnnl::engine::kind ` engine_kind) { // Create execution dnnl::engine. :ref:`dnnl::engine ` :ref:`engine `(engine_kind, 0); // Create dnnl::stream. :ref:`dnnl::stream ` engine_stream(:ref:`engine `); // Tensor dimensions. const :ref:`memory::dim ` N = 3, // batch size IC = 32, // input channels IH = 13, // input height IW = 13, // input width OC = 64, // output channels KH = 3, // weights height KW = 3, // weights width PH_L = 1, // height padding: left PH_R = 1, // height padding: right PW_L = 1, // width padding: left PW_R = 1, // width padding: right SH = 4, // height-wise stride SW = 4, // width-wise stride OH = (IH - KH + PH_L + PH_R) / SH + 1, // output height OW = (IW - KW + PW_L + PW_R) / SW + 1; // output width // Source (src), weights, bias, and destination (dst) tensors // dimensions. :ref:`memory::dims ` src_dims = {N, IC, IH, IW}; :ref:`memory::dims ` weights_dims = {OC, IC, KH, KW}; :ref:`memory::dims ` bias_dims = {OC}; :ref:`memory::dims ` dst_dims = {N, OC, OH, OW}; // Strides, padding dimensions. :ref:`memory::dims ` strides_dims = {SH, SW}; :ref:`memory::dims ` padding_dims_l = {PH_L, PW_L}; :ref:`memory::dims ` padding_dims_r = {PH_R, PW_R}; // Allocate buffers. std::vector src_data(product(src_dims)); std::vector weights_data(product(weights_dims)); std::vector bias_data(OC); std::vector dst_data(product(dst_dims)); // Initialize src, weights, and dst tensors. std::generate(src_data.begin(), src_data.end(), []() { static int i = 0; return std::cos(i++ / 10.f); }); std::generate(weights_data.begin(), weights_data.end(), []() { static int i = 0; return std::sin(i++ * 2.f); }); std::generate(bias_data.begin(), bias_data.end(), []() { static int i = 0; return std::tanh(float(i++)); }); // Create memory objects for tensor data (src, weights, dst). In this // example, NCHW layout is assumed for src and dst, and OIHW for weights. auto user_src_mem = :ref:`memory `({src_dims, :ref:`dt::f32 `, tag::nchw}, :ref:`engine `); auto user_weights_mem = :ref:`memory `({weights_dims, :ref:`dt::f32 `, tag::oihw}, :ref:`engine `); auto user_dst_mem = :ref:`memory `({dst_dims, :ref:`dt::f32 `, tag::nchw}, :ref:`engine `); // Create memory descriptors with format_tag::any for the primitive. This // enables the convolution primitive to choose memory layouts for an // optimized primitive implementation, and these layouts may differ from the // ones provided by the user. auto conv_src_md = :ref:`memory::desc `(src_dims, :ref:`dt::f32 `, :ref:`tag::any `); auto conv_weights_md = :ref:`memory::desc `(weights_dims, :ref:`dt::f32 `, :ref:`tag::any `); auto conv_dst_md = :ref:`memory::desc `(dst_dims, :ref:`dt::f32 `, :ref:`tag::any `); // Create memory descriptor and memory object for input bias. auto user_bias_md = :ref:`memory::desc `(bias_dims, :ref:`dt::f32 `, tag::a); auto user_bias_mem = :ref:`memory `(user_bias_md, :ref:`engine `); // Write data to memory object's handle. write_to_dnnl_memory(src_data.data(), user_src_mem); write_to_dnnl_memory(weights_data.data(), user_weights_mem); write_to_dnnl_memory(bias_data.data(), user_bias_mem); // Create primitive post-ops (ReLU). const float alpha = 0.f; const float beta = 0.f; :ref:`post_ops ` conv_ops; conv_ops.:ref:`append_eltwise `(:ref:`algorithm::eltwise_relu `, alpha, beta); :ref:`primitive_attr ` conv_attr; conv_attr.:ref:`set_post_ops `(conv_ops); // Create primitive descriptor. auto conv_pd = :ref:`convolution_forward::primitive_desc `(:ref:`engine `, :ref:`prop_kind::forward_training `, :ref:`algorithm::convolution_direct `, conv_src_md, conv_weights_md, user_bias_md, conv_dst_md, strides_dims, padding_dims_l, padding_dims_r, conv_attr); // For now, assume that the src, weights, and dst memory layouts generated // by the primitive and the ones provided by the user are identical. auto conv_src_mem = user_src_mem; auto conv_weights_mem = user_weights_mem; auto conv_dst_mem = user_dst_mem; // Reorder the data in case the src and weights memory layouts generated by // the primitive and the ones provided by the user are different. In this // case, we create additional memory objects with internal buffers that will // contain the reordered data. The data in dst will be reordered after the // convolution computation has finalized. if (conv_pd.src_desc() != user_src_mem.get_desc()) { conv_src_mem = :ref:`memory `(conv_pd.src_desc(), :ref:`engine `); :ref:`reorder `(user_src_mem, conv_src_mem) .:ref:`execute `(engine_stream, user_src_mem, conv_src_mem); } if (conv_pd.weights_desc() != user_weights_mem.:ref:`get_desc `()) { conv_weights_mem = :ref:`memory `(conv_pd.weights_desc(), :ref:`engine `); :ref:`reorder `(user_weights_mem, conv_weights_mem) .:ref:`execute `(engine_stream, user_weights_mem, conv_weights_mem); } if (conv_pd.dst_desc() != user_dst_mem.:ref:`get_desc `()) { conv_dst_mem = :ref:`memory `(conv_pd.dst_desc(), :ref:`engine `); } // Create the primitive. auto conv_prim = :ref:`convolution_forward `(conv_pd); // Primitive arguments. std::unordered_map conv_args; conv_args.insert({:ref:`DNNL_ARG_SRC `, conv_src_mem}); conv_args.insert({:ref:`DNNL_ARG_WEIGHTS `, conv_weights_mem}); conv_args.insert({:ref:`DNNL_ARG_BIAS `, user_bias_mem}); conv_args.insert({:ref:`DNNL_ARG_DST `, conv_dst_mem}); // Primitive execution: convolution with ReLU. conv_prim.execute(engine_stream, conv_args); // Reorder the data in case the dst memory descriptor generated by the // primitive and the one provided by the user are different. if (conv_pd.dst_desc() != user_dst_mem.:ref:`get_desc `()) { :ref:`reorder `(conv_dst_mem, user_dst_mem) .:ref:`execute `(engine_stream, conv_dst_mem, user_dst_mem); } else user_dst_mem = conv_dst_mem; // Wait for the computation to finalize. engine_stream.wait(); // Read data from memory object's handle. read_from_dnnl_memory(dst_data.data(), user_dst_mem); } void depthwise_convolution_example(:ref:`dnnl::engine::kind ` engine_kind) { // Create execution dnnl::engine. :ref:`dnnl::engine ` :ref:`engine `(engine_kind, 0); // Create dnnl::stream. :ref:`dnnl::stream ` engine_stream(:ref:`engine `); // Tensor dimensions. const :ref:`memory::dim ` N = 3, // batch size G = 32, // channel groups IC = 32, // input channels IH = 13, // input height IW = 13, // input width OC = 32, // output channels KH = 3, // weights height KW = 3, // weights width PH_L = 1, // height padding: left PH_R = 1, // height padding: right PW_L = 1, // width padding: left PW_R = 1, // width padding: right SH = 4, // height-wise stride SW = 4, // width-wise stride OH = (IH - KH + PH_L + PH_R) / SH + 1, // output height OW = (IW - KW + PW_L + PW_R) / SW + 1; // output width // Source (src), weights, bias, and destination (dst) tensors dimensions. :ref:`memory::dims ` src_dims = {N, IC, IH, IW}; :ref:`memory::dims ` weights_dims = {G, OC / G, IC / G, KH, KW}; :ref:`memory::dims ` bias_dims = {OC}; :ref:`memory::dims ` dst_dims = {N, OC, OH, OW}; // Strides, padding dimensions. :ref:`memory::dims ` strides_dims = {SH, SW}; :ref:`memory::dims ` padding_dims_l = {PH_L, PW_L}; :ref:`memory::dims ` padding_dims_r = {PH_R, PW_R}; // Allocate buffers. std::vector src_data(product(src_dims)); std::vector weights_data(product(weights_dims)); std::vector bias_data(OC); std::vector dst_data(product(dst_dims)); // Initialize src, weights, and dst tensors. std::generate(src_data.begin(), src_data.end(), []() { static int i = 0; return std::cos(i++ / 10.f); }); std::generate(weights_data.begin(), weights_data.end(), []() { static int i = 0; return std::sin(i++ * 2.f); }); std::generate(bias_data.begin(), bias_data.end(), []() { static int i = 0; return std::tanh(float(i++)); }); // Create memory objects for tensor data (src, weights, dst). In this // example, NCHW layout is assumed for src and dst, and OIHW for weights. auto user_src_mem = :ref:`memory `({src_dims, :ref:`dt::f32 `, tag::nchw}, :ref:`engine `); auto user_weights_mem = :ref:`memory `({weights_dims, :ref:`dt::f32 `, tag::goihw}, :ref:`engine `); auto user_dst_mem = :ref:`memory `({dst_dims, :ref:`dt::f32 `, tag::nchw}, :ref:`engine `); // Create memory descriptors with format_tag::any for the primitive. This // enables the convolution primitive to choose memory layouts for an // optimized primitive implementation, and these layouts may differ from the // ones provided by the user. auto conv_src_md = :ref:`memory::desc `(src_dims, :ref:`dt::f32 `, :ref:`tag::any `); auto conv_weights_md = :ref:`memory::desc `(weights_dims, :ref:`dt::f32 `, :ref:`tag::any `); auto conv_dst_md = :ref:`memory::desc `(dst_dims, :ref:`dt::f32 `, :ref:`tag::any `); // Create memory descriptor and memory object for input bias. auto user_bias_md = :ref:`memory::desc `(bias_dims, :ref:`dt::f32 `, tag::a); auto user_bias_mem = :ref:`memory `(user_bias_md, :ref:`engine `); // Write data to memory object's handle. write_to_dnnl_memory(src_data.data(), user_src_mem); write_to_dnnl_memory(weights_data.data(), user_weights_mem); write_to_dnnl_memory(bias_data.data(), user_bias_mem); // Create primitive post-ops (ReLU). const float alpha = 0.f; const float beta = 0.f; :ref:`post_ops ` conv_ops; conv_ops.:ref:`append_eltwise `(:ref:`algorithm::eltwise_relu `, alpha, beta); :ref:`primitive_attr ` conv_attr; conv_attr.:ref:`set_post_ops `(conv_ops); // Create primitive descriptor. auto conv_pd = :ref:`convolution_forward::primitive_desc `(:ref:`engine `, :ref:`prop_kind::forward_training `, :ref:`algorithm::convolution_direct `, conv_src_md, conv_weights_md, user_bias_md, conv_dst_md, strides_dims, padding_dims_l, padding_dims_r, conv_attr); // For now, assume that the src, weights, and dst memory layouts generated // by the primitive and the ones provided by the user are identical. auto conv_src_mem = user_src_mem; auto conv_weights_mem = user_weights_mem; auto conv_dst_mem = user_dst_mem; // Reorder the data in case the src and weights memory layouts generated by // the primitive and the ones provided by the user are different. In this // case, we create additional memory objects with internal buffers that will // contain the reordered data. The data in dst will be reordered after the // convolution computation has finalized. if (conv_pd.src_desc() != user_src_mem.get_desc()) { conv_src_mem = :ref:`memory `(conv_pd.src_desc(), :ref:`engine `); :ref:`reorder `(user_src_mem, conv_src_mem) .:ref:`execute `(engine_stream, user_src_mem, conv_src_mem); } if (conv_pd.weights_desc() != user_weights_mem.:ref:`get_desc `()) { conv_weights_mem = :ref:`memory `(conv_pd.weights_desc(), :ref:`engine `); :ref:`reorder `(user_weights_mem, conv_weights_mem) .:ref:`execute `(engine_stream, user_weights_mem, conv_weights_mem); } if (conv_pd.dst_desc() != user_dst_mem.:ref:`get_desc `()) { conv_dst_mem = :ref:`memory `(conv_pd.dst_desc(), :ref:`engine `); } // Create the primitive. auto conv_prim = :ref:`convolution_forward `(conv_pd); // Primitive arguments. std::unordered_map conv_args; conv_args.insert({:ref:`DNNL_ARG_SRC `, conv_src_mem}); conv_args.insert({:ref:`DNNL_ARG_WEIGHTS `, conv_weights_mem}); conv_args.insert({:ref:`DNNL_ARG_BIAS `, user_bias_mem}); conv_args.insert({:ref:`DNNL_ARG_DST `, conv_dst_mem}); // Primitive execution: convolution with ReLU. conv_prim.execute(engine_stream, conv_args); // Reorder the data in case the dst memory descriptor generated by the // primitive and the one provided by the user are different. if (conv_pd.dst_desc() != user_dst_mem.:ref:`get_desc `()) { :ref:`reorder `(conv_dst_mem, user_dst_mem) .:ref:`execute `(engine_stream, conv_dst_mem, user_dst_mem); } else user_dst_mem = conv_dst_mem; // Wait for the computation to finalize. engine_stream.wait(); // Read data from memory object's handle. read_from_dnnl_memory(dst_data.data(), user_dst_mem); } int main(int argc, char **argv) { auto exit_code = handle_example_errors( convolution_example, parse_engine_kind(argc, argv)); if (exit_code != 0) return exit_code; return handle_example_errors( depthwise_convolution_example, parse_engine_kind(argc, argv)); }