From 7506d5571a97889bb116e7c37124e8f0dac07430 Mon Sep 17 00:00:00 2001
From: Joshua Bell <jsbell@chromium.org>
Date: Wed, 24 Jul 2024 10:43:08 -0700
Subject: [PATCH 1/8] Editorial: Clarify reduction with empty axes and scalar
 input

Improve the description of the reduction ops:

- Give in-line definition for L1/L2.
- Make "input values" slightly clearer.
- Explicitly note that if the input is a scalar, so is the output.
- State how the reduction function is applied for empty axes.
- Standardize on "reduction operation" not "reduce operation".

Fixes #740
---
 index.bs | 49 +++++++++++++++++++++++++------------------------
 1 file changed, 25 insertions(+), 24 deletions(-)

diff --git a/index.bs b/index.bs
index 7bb43dc8..10c6c1a1 100644
--- a/index.bs
+++ b/index.bs
@@ -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.
+
 <script type=idl>
 dictionary MLReduceOptions {
   sequence<[EnforceRange] unsigned long> axes;
@@ -4959,7 +4960,7 @@ 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. 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 reduction function is applied to each input value individually.
 
     : <dfn>keepDimensions</dfn>
     ::
@@ -4971,21 +4972,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.
 </div>
 
 <div class="note">
     **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.
+        - *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.
+        - *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>
@@ -5008,7 +5009,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:
   </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}}.
@@ -5033,70 +5034,70 @@ partial interface MLGraphBuilder {
   </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>

From 5a2df457c5c16fa195539567ddc281a467fee597 Mon Sep 17 00:00:00 2001
From: Joshua Bell <jsbell@chromium.org>
Date: Wed, 24 Jul 2024 11:41:16 -0700
Subject: [PATCH 2/8] Make "reduction types" list normative

The "reduction types" list was styled as a non-normative note. The
element-wise ops (add, equal, abs, etc.) don't do this. Be consistent
here.
---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 10c6c1a1..516998e9 100644
--- a/index.bs
+++ b/index.bs
@@ -4975,7 +4975,7 @@ partial interface MLGraphBuilder {
     **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.
 </div>
 
-<div class="note">
+<div>
     **Reduction types:**
         - *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.
         - *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.

From fc04fcf1c35c3e396c5d261bb22c637e81bb030a Mon Sep 17 00:00:00 2001
From: Joshua Bell <jsbell@chromium.org>
Date: Wed, 24 Jul 2024 16:19:57 -0700
Subject: [PATCH 3/8] One more wording tweak

---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 516998e9..f506ae51 100644
--- a/index.bs
+++ b/index.bs
@@ -5030,7 +5030,7 @@ 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:

From 7fbceaab077592e94addd423ad9066c7aaa025a0 Mon Sep 17 00:00:00 2001
From: Joshua Bell <jsbell@chromium.org>
Date: Thu, 25 Jul 2024 09:45:44 -0700
Subject: [PATCH 4/8] more explicit input values

---
 index.bs | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index f506ae51..5815f2a6 100644
--- a/index.bs
+++ b/index.bs
@@ -4960,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 reduction function is applied to each input value individually.
+        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.
+
+        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>
     ::

From 4af5b3c9c81ac939ba33fe5c80770f06c1b519f6 Mon Sep 17 00:00:00 2001
From: Dwayne Robinson <dwayner@microsoft.com>
Date: Mon, 29 Jul 2024 20:56:41 -0700
Subject: [PATCH 5/8] Extra space

---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 5815f2a6..86cdcf37 100644
--- a/index.bs
+++ b/index.bs
@@ -4934,7 +4934,7 @@ 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 input values across the reduced dimensions.
+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.
 
 <script type=idl>
 dictionary MLReduceOptions {

From c14dc6ab4975d683b91e1c986110e6874adf40b2 Mon Sep 17 00:00:00 2001
From: Joshua Bell <inexorabletash@gmail.com>
Date: Tue, 30 Jul 2024 10:19:45 -0700
Subject: [PATCH 6/8] don't repeat "input", "values"

Co-authored-by: Dwayne Robinson <dwayner@microsoft.com>
---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 86cdcf37..6635d3f9 100644
--- a/index.bs
+++ b/index.bs
@@ -4960,7 +4960,7 @@ partial interface MLGraphBuilder {
 <dl dfn-type=dict-member dfn-for=MLReduceOptions>
     : <dfn>axes</dfn>
     ::
-        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.
+        The dimensions to reduce, which also specifies which of the values in the input tensor are used with the reduction function. The axes 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. The input values for the reduction function are all of the values in the input tensor.
 

From d798044cf2dc3f59f4e5a9b5bdab3b4eb6090473 Mon Sep 17 00:00:00 2001
From: Joshua Bell <inexorabletash@gmail.com>
Date: Tue, 30 Jul 2024 10:20:14 -0700
Subject: [PATCH 7/8] more commas more better

Co-authored-by: Dwayne Robinson <dwayner@microsoft.com>
---
 index.bs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.bs b/index.bs
index 6635d3f9..0c66c8e9 100644
--- a/index.bs
+++ b/index.bs
@@ -4978,7 +4978,7 @@ 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. If the input operand is a scalar, the reduction function is applied to the scalar value and the output is also a scalar.
+    **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.
 </div>
 
 <div>

From f9824188789c2c0653764c1538a0db799978179c Mon Sep 17 00:00:00 2001
From: Joshua Bell <jsbell@chromium.org>
Date: Tue, 30 Jul 2024 10:22:27 -0700
Subject: [PATCH 8/8] remove 'all'

---
 index.bs | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/index.bs b/index.bs
index c008b5f4..2e102d21 100644
--- a/index.bs
+++ b/index.bs
@@ -5005,16 +5005,16 @@ partial interface MLGraphBuilder {
 
 <div>
     **Reduction types:**
-        - *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.
-        - *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.
-        - *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.
+        - *L1*: Compute the <a href="https://mathworld.wolfram.com/L1-Norm.html">L1 norm</a>, the sum of the absolute value of the input values.
+        - *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 the input values.
+        - *LogSum*: Compute the log value of the sum of the input values.
+        - *LogSumExp*: Compute the log value of the sum of the exponent of the input values.
+        - *Max*: Compute the maximum value of the input values.
+        - *Mean*: Compute the average value of the input values.
+        - *Min*: Compute the minimum value of the input values.
+        - *Product*: Compute the product of the input values.
+        - *Sum*: Compute the sum of the input values.
+        - *SumSquare*: Compute the sum of the square of the input values.
 </div>
 
 <details open algorithm>