1Reduction {#dev_guide_reduction}
2============================
3>
4> [API Reference](@ref dnnl_api_reduction)
5>
6
7## General
8
9The reduction primitive performs reduction operation on arbitrary data. Each
10element in the destination is the result of reduction operation with specified
11algorithm along one or multiple source tensor dimensions:
12
13\f[
14    \dst(f) = \mathop{reduce\_op}\limits_{r}\src(r),
15\f]
16
17where \f$reduce\_op\f$ can be max, min, sum, mul, mean, Lp-norm and
18Lp-norm-power-p, \f$f\f$ is an index in an idle dimension and \f$r\f$ is an
19index in a reduction dimension.
20
21Mean:
22
23\f[
24    \dst(f) = \frac{\sum\limits_{r}\src(r)} {R},
25\f]
26
27where \f$R\f$ is the size of a reduction dimension.
28
29Lp-norm:
30
31\f[
32    \dst(f) = \root p \of {\mathop{eps\_op}(\sum\limits_{r}|src(r)|^p, eps)},
33\f]
34
35where \f$eps\_op\f$ can be max and sum.
36
37Lp-norm-power-p:
38
39\f[
40    \dst(f) = \mathop{eps\_op}(\sum\limits_{r}|src(r)|^p, eps),
41\f]
42
43where \f$eps\_op\f$ can be max and sum.
44
45### Notes
46
47 * The reduction primitive requires the source and destination tensors to have
48   the same number of dimensions.
49 * Reduction dimensions are of size 1 in a destination tensor.
50 * The reduction primitive does not have a notion of forward or backward
51   propagations.
52
53## Execution Arguments
54
55When executed, the inputs and outputs should be mapped to an execution
56argument index as specified by the following table.
57
58| Primitive input/output      | Execution argument index |
59| ---                         | ---                      |
60| \src                        | DNNL_ARG_SRC             |
61| \dst                        | DNNL_ARG_DST             |
62| \f$\text{binary post-op}\f$ | DNNL_ARG_ATTR_MULTIPLE_POST_OP(binary_post_op_position) \| DNNL_ARG_SRC_1 |
63
64## Implementation Details
65
66### General Notes
67 * The \dst memory format can be either specified explicitly or by
68   #dnnl::memory::format_tag::any (recommended), in which case the primitive
69   will derive the most appropriate memory format based on the format of the
70   source tensor.
71
72### Post-Ops and Attributes
73
74The following attributes are supported:
75
76| Type    | Operation                                      | Description                                                                    | Restrictions                        |
77| :--     | :--                                            | :--                                                                            | :--                                 |
78| Post-op | [Sum](@ref dnnl::post_ops::append_sum)         | Adds the operation result to the destination tensor instead of overwriting it. |                                     |
79| Post-op | [Eltwise](@ref dnnl::post_ops::append_eltwise) | Applies an @ref dnnl_api_eltwise operation to the result.                      |                                     |
80| Post-op | [Binary](@ref dnnl::post_ops::append_binary)   | Applies a @ref dnnl_api_binary operation to the result                         | General binary post-op restrictions |
81
82### Data Types Support
83
84The source and destination tensors may have `f32`, `bf16`, or `int8` data types.
85See @ref dev_guide_data_types page for more details.
86
87### Data Representation
88
89#### Sources, Destination
90
91The reduction primitive works with arbitrary data tensors. There is no special
92meaning associated with any of the dimensions of a tensor.
93
94## Implementation Limitations
95
961. Refer to @ref dev_guide_data_types for limitations related to data types
97   support.
98
99## Performance Tips
100
1011. Whenever possible, avoid specifying different memory formats for source
102   and destination tensors.
103
104## Example
105
106[Reduction Primitive Example](@ref reduction_example_cpp)
107
108@copydetails reduction_example_cpp_short
109