Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify reduction with empty axes and scalar input #741

Merged
merged 12 commits into from
Jul 30, 2024
Merged

Clarify reduction with empty axes and scalar input #741

Changes from 4 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
7506d55
Editorial: Clarify reduction with empty axes and scalar input
inexorabletash Jul 24, 2024
5a2df45
Make "reduction types" list normative
inexorabletash Jul 24, 2024
fc04fcf
One more wording tweak
inexorabletash Jul 24, 2024
7fbceaa
more explicit input values
inexorabletash Jul 25, 2024
e0bda19
Merge branch 'refs/heads/review' into reduction-reword
inexorabletash Jul 25, 2024
15349c9
Merge branch 'refs/heads/review' into reduction-reword
inexorabletash Jul 28, 2024
4af5b3c
Extra space
fdwr Jul 30, 2024
cb6e70d
Merge branch 'refs/heads/review' into reduction-reword
inexorabletash Jul 30, 2024
c14dc6a
don't repeat "input", "values"
inexorabletash Jul 30, 2024
d798044
more commas more better
inexorabletash Jul 30, 2024
f7eb68e
Merge remote-tracking branch 'mine/reduction-reword' into reduction-r…
inexorabletash Jul 30, 2024
f982418
remove 'all'
inexorabletash Jul 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 33 additions & 26 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4934,7 +4934,8 @@ partial interface MLGraphBuilder {
</div>

### Reduction operations ### {#api-mlgraphbuilder-reduce}
Reduce the input tensor along all dimensions, or along the axes specified in the {{MLReduceOptions/axes}} array parameter. For each specified axis, the dimension with that index is reduced, i.e. the resulting tensor will not contain it, unless the {{MLReduceOptions/keepDimensions}} option is specified. The values of the resulting tensor are calculated using the specified reduction function that takes as parameters all the values across the reduced dimension.
Reduce the input tensor along all dimensions, or along the axes specified in the {{MLReduceOptions/axes}} array parameter. For each specified axis, the dimension with that index is reduced, i.e. the resulting tensor will not contain it, unless the {{MLReduceOptions/keepDimensions}} option is specified. The values of the resulting tensor are calculated using the specified reduction function that takes as parameters all the input values across the reduced dimensions.
fdwr marked this conversation as resolved.
Show resolved Hide resolved

<script type=idl>
dictionary MLReduceOptions {
sequence<[EnforceRange] unsigned long> axes;
Expand All @@ -4959,7 +4960,13 @@ partial interface MLGraphBuilder {
<dl dfn-type=dict-member dfn-for=MLReduceOptions>
: <dfn>axes</dfn>
::
The dimensions to reduce. The values in the list must be in the range [0, N-1] where N is the [=MLOperand/rank=] of the input tensor. If not present, all dimensions are reduced. If empty, no dimensions are reduced, and the shape of the output tensor is the same as the shape of the input tensor.
The dimensions to reduce, which also specifies which of the values in the input tensor are used as input values to the reduction function. The values in the list must be in the range [0, N-1] where N is the [=MLOperand/rank=] of the input tensor.
inexorabletash marked this conversation as resolved.
Show resolved Hide resolved

If not present, all dimensions are reduced. The input values for the reduction function are all of the values in the input tensor.

If present and not empty, the input values for the reduction function are all the values for the specified dimensions of the input tensor.

If present and empty, no dimensions are reduced, and the shape of the output tensor is the same as the shape of the input tensor; the reduction function is applied to each value in the tensor individually.

: <dfn>keepDimensions</dfn>
::
Expand All @@ -4971,21 +4978,21 @@ partial interface MLGraphBuilder {
- <dfn>input</dfn>: an {{MLOperand}}. The input tensor.
- <dfn>options</dfn>: an optional {{MLReduceOptions}}. The optional parameters of the operation.

**Returns:** an {{MLOperand}}. The reduced output tensor.
**Returns:** an {{MLOperand}}. The reduced output tensor. If the input operand is a scalar, the reduction function is applied to the scalar value and the output is also a scalar.
inexorabletash marked this conversation as resolved.
Show resolved Hide resolved
</div>

<div class="note">
<div>
**Reduction types:**
- *L1*: Compute the <a href="https://mathworld.wolfram.com/L1-Norm.html">L1 norm</a> of all the input values along the axes.
- *L2*: Compute the <a href="https://mathworld.wolfram.com/L2-Norm.html">L2 norm</a> of all the input values along the axes.
- *LogSum*: Compute the log value of the sum of all the input values along the axes.
- *LogSumExp*: Compute the log value of the sum of the exponent of all the input values along the axes.
- *Max*: Compute the maximum value of all the input values along the axes.
- *Mean*: Compute the average value of all the input values along the axes.
- *Min*: Compute the minimum value of all the input values along the axes.
- *Product*: Compute the product of all the input values along the axes.
- *Sum*: Compute the sum of all the input values along the axes.
- *SumSquare*: Compute the sum of the square of all the input values along the axes.
- *L1*: Compute the <a href="https://mathworld.wolfram.com/L1-Norm.html">L1 norm</a>, the sum of the absolute value of all the input values.
huningxin marked this conversation as resolved.
Show resolved Hide resolved
inexorabletash marked this conversation as resolved.
Show resolved Hide resolved
- *L2*: Compute the <a href="https://mathworld.wolfram.com/L2-Norm.html">L2 norm</a>, the square root of the sum of the square of all the input values.
- *LogSum*: Compute the log value of the sum of all the input values.
- *LogSumExp*: Compute the log value of the sum of the exponent of all the input values.
- *Max*: Compute the maximum value of all the input values.
- *Mean*: Compute the average value of all the input values.
fdwr marked this conversation as resolved.
Show resolved Hide resolved
- *Min*: Compute the minimum value of all the input values.
- *Product*: Compute the product of all the input values.
- *Sum*: Compute the sum of all the input values.
- *SumSquare*: Compute the sum of the square of all the input values.
</div>

<details open algorithm>
Expand All @@ -5008,7 +5015,7 @@ partial interface MLGraphBuilder {

<details open algorithm>
<summary>
To <dfn for="MLGraphBuilder" data-lt="reduce-op">create reduce operation</dfn> given [=string=] |op|, {{MLOperand}} |input|, {{MLReduceOptions}} |options|, and optional [=/list=] |allowedDataTypes|, run the following steps:
To <dfn for="MLGraphBuilder">create reduction operation</dfn> given [=string=] |op|, {{MLOperand}} |input|, {{MLReduceOptions}} |options|, and optional [=/list=] |allowedDataTypes|, run the following steps:
inexorabletash marked this conversation as resolved.
Show resolved Hide resolved
</summary>
1. [=Assert=]: |op| is one of "reduceL1", "reduceL2", "reduceLogSum", "reduceLogSumExp", "reduceMax", "reduceMean", "reduceMin", "reduceProduct", "reduceSum", "reduceSumSquare".
1. If [=this=].{{MLGraphBuilder/[[hasBuilt]]}} is true, then [=exception/throw=] an "{{InvalidStateError}}" {{DOMException}}.
Expand All @@ -5029,74 +5036,74 @@ partial interface MLGraphBuilder {

<details open>
<summary>
The following reduce algorithms are supported.
The following reduction algorithms are supported.
</summary>
<div algorithm>
The <dfn method for=MLGraphBuilder>reduceL1(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceL1", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}}, {{MLOperandDataType/"int32"}}, {{MLOperandDataType/"uint32"}} ».
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceL1", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}}, {{MLOperandDataType/"int32"}}, {{MLOperandDataType/"uint32"}} ».
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>

<div algorithm>
The <dfn method for=MLGraphBuilder>reduceL2(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceL2", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} ».
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceL2", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} ».
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>

<div algorithm>
The <dfn method for=MLGraphBuilder>reduceLogSum(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceLogSum", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} ».
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceLogSum", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} ».
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>

<div algorithm>
The <dfn method for=MLGraphBuilder>reduceLogSumExp(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceLogSumExp", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} ».
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceLogSumExp", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} ».
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>

<div algorithm>
The <dfn method for=MLGraphBuilder>reduceMax(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceMax", |input| and |options|.
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceMax", |input| and |options|.
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>

<div algorithm>
The <dfn method for=MLGraphBuilder>reduceMean(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceMean", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} ».
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceMean", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}} ».
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>

<div algorithm>
The <dfn method for=MLGraphBuilder>reduceMin(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceMin", |input| and |options|.
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceMin", |input| and |options|.
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>

<div algorithm>
The <dfn method for=MLGraphBuilder>reduceProduct(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceProduct", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}}, {{MLOperandDataType/"int32"}}, {{MLOperandDataType/"uint32"}} ».
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceProduct", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}}, {{MLOperandDataType/"int32"}}, {{MLOperandDataType/"uint32"}} ».
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>

<div algorithm>
The <dfn method for=MLGraphBuilder>reduceSum(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceSum", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}}, {{MLOperandDataType/"int32"}}, {{MLOperandDataType/"uint32"}} ».
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceSum", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}}, {{MLOperandDataType/"int32"}}, {{MLOperandDataType/"uint32"}} ».
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>

<div algorithm>
The <dfn method for=MLGraphBuilder>reduceSumSquare(|input|, |options|)</dfn> method steps are:
1. Let |output| be the result of running the [=MLGraphBuilder/reduce-op | create reduce operation=] given "reduceSumSquare", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}}, {{MLOperandDataType/"int32"}}, {{MLOperandDataType/"uint32"}} ».
1. Let |output| be the result of [=MLGraphBuilder/creating reduction operation=] given "reduceSumSquare", |input|, |options|, and « {{MLOperandDataType/"float32"}}, {{MLOperandDataType/"float16"}}, {{MLOperandDataType/"int32"}}, {{MLOperandDataType/"uint32"}} ».
1. If that [=exception/throws=] an error, then re-[=exception/throw=] the error.
1. Return |output|.
</div>
Expand Down