From 5973cd9fcb2b69d593aec6a09650a3ea02aa8a59 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Wed, 15 Feb 2023 21:04:24 +0200 Subject: [PATCH 1/3] Add the clamp() algorithm Squashed from the following commits: Replace MLOperand.[[descriptor]] with type and dimensions Clarify the algorithm for only setting up the op Improve the clamp() algorithm, use the prose assuming the create steps for MLOperand and MLActivation Rework clamp with polymorphic behavior. Update for changes in MLOperand. Rework clamp() like constant(), polymorphic forms in separate sections, argument and return descriptions as notes. Fix platform related steps and reference to internal slots Address review, remove note Remove back quotes from title Signed-off-by: Zoltan Kis --- index.bs | 63 ++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 50 insertions(+), 13 deletions(-) diff --git a/index.bs b/index.bs index 14778685..63084178 100644 --- a/index.bs +++ b/index.bs @@ -1371,22 +1371,12 @@ dictionary MLClampOptions { }; partial interface MLGraphBuilder { - MLOperand clamp(MLOperand x, optional MLClampOptions options = {}); + MLOperand clamp(MLOperand operand, optional MLClampOptions options = {}); MLActivation clamp(optional MLClampOptions options = {}); }; -
- **Arguments:** - - *x*: an {{MLOperand}}. The input tensor. - - *options*: an optional {{MLClampOptions}}. The optional parameters of the operation. - - *minValue*: a {{float}} scalar. Specifies the minimum value of the range. When it is not specified, the clamping is not performed on the lower limit of the range. - - *maxValue*: a {{float}} scalar. Specifies the maximum value of the range. When it is not specified, the clamping is not performed on the upper limit of the range. - - **Returns:** - - an {{MLOperand}}. The output tensor of the same shape as *x*. - - an {{MLActivation}}. The activation function representing the clamp operation. -
+
The behavior of this operation can be generically emulated from the usage of other operations as follow. However, user agents typically have a more efficient implementation for it, therefore its usage is encouraged from the @@ -1408,7 +1398,54 @@ partial interface MLGraphBuilder { } } -
+
+ +To check clamp options given |options|, run the following steps: + 1. If |options| is not an object that [=implements=] {{MLClampOptions}}, then return `false`. + 1. If |options|.{{MLClampOptions/minValue}} and |options|.{{MLClampOptions/maxValue}} are not a [=numeric type=], then then return `false`. + 1. If |options|.{{MLClampOptions/minValue}} is greater than |options|.{{MLClampOptions/maxValue}}, then return `false`. + 1. Return `true`. + +#### The {{MLGraphBuilder/clamp(operand, options)}} method #### {#api-mlgraphbuilder-clamp-operand-options} +
+ **Arguments:** + - *operand*: an {{MLOperand}}. The input tensor. + - *options*: an optional {{MLClampOptions}}. The optional parameters of the operation. + - *minValue*: a {{float}} scalar. Specifies the minimum value of the range. When it is not specified, the clamping is not performed on the lower limit of the range. + - *maxValue*: a {{float}} scalar. Specifies the maximum value of the range. When it is not specified, the clamping is not performed on the upper limit of the range. + **Returns:** + - an {{MLOperand}}. The output tensor of the same shape as *operand*. +
+
+ The {{MLGraphBuilder/clamp(operand, options)}} method steps are: + 1. Let |operand| be the first argument. + 1. Let |options| be the second argument. + 1. If running the check clamp options steps with |options| returns `false`, then throw a "{{TypeError}}" {{DOMException}} and abort these steps. + 1. Let |result| be the result of invoking the copy MLOperand steps given |operand|. + 1. If that throws an error, re-throw the error and abort these steps. + 1. Make a request to the underlying platform to connect |result| with the [=implementation-defined=] platform operator for clamp, and store a reference to the resulting [=implementation-defined=] platform operand object in |result|.{{MLOperand/[[operand]]}}. + 1. If that fails, throw an "{{OperationError}}" {{DOMException}} and stop. + 1. Return |result|. +
+ +#### The {{MLGraphBuilder/clamp(options)}} method #### {#api-mlgraphbuilder-clamp-options} +
+ **Arguments:** + - *options*: an optional {{MLClampOptions}}. The optional parameters of the operation. + - *minValue*: a {{float}} scalar. Specifies the minimum value of the range. When it is not specified, the clamping is not performed on the lower limit of the range. + - *maxValue*: a {{float}} scalar. Specifies the maximum value of the range. When it is not specified, the clamping is not performed on the upper limit of the range. + **Returns:** + - an {{MLActivation}}. The operator representing the clamp operation. +
+
+ The {{MLGraphBuilder/clamp(options)}} method steps are: + 1. Let |options| be the first argument. + 1. If running the check clamp options steps with |options| returns `false`, then throw a "{{TypeError}}" {{DOMException}} and abort these steps. + 1. Let |op| be the result of invoking the create MLActivation steps with `"clamp"` and |options|. + 1. If that throws an error, re-throw the error and abort these steps. + 1. Make a request to the underlying platform to connect |op| with the [=implementation-defined=] platform operator for clamp, and store a reference to the resulting [=implementation-defined=] platform operator object in |op|.{{MLActivation/[[operator]]}}. + 1. If that fails, throw an "{{OperationError}}" {{DOMException}} and stop. + 1. Return |op|.
### The concat() method ### {#api-mlgraphbuilder-concat} From d68bd87cf2ceaf7cfb23a121b61d1f7fe2824cba Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Thu, 25 May 2023 19:10:35 +0300 Subject: [PATCH 2/3] Add the 'copy MLOperand' and 'create MLActivation' steps Signed-off-by: Zoltan Kis --- index.bs | 53 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 50 insertions(+), 3 deletions(-) diff --git a/index.bs b/index.bs index 63084178..666979e1 100644 --- a/index.bs +++ b/index.bs @@ -754,6 +754,16 @@ To create MLOperand given |builder| and |desc|, run the following ste 1. Return |operand|.
+To copy MLOperand given |operand|, run the following steps: +
+ 1. If |operand| is not an instance of {{MLOperand}}, then throw a "{{TypeError}}" and stop. + 1. Let |result| be a new [=object=]. + 1. Set |result|.{{MLOperand/[[builder]]}} to |operand|.{{MLOperand/[[builder]]}}. + 1. Set |result|.{{MLOperand/[[descriptor]]}} to |operand|.{{MLOperand/[[descriptor]]}}. + 1. Set |result|.{{MLOperand/[[name]]}} to |operand|.{{MLOperand/[[name]]}}. + 1. Return |result|. +
+ To check dimensions given |dimensions| and |type|, run the following steps:
1. If |dimensions| is not an array of positive numbers, return `false`; @@ -769,16 +779,53 @@ Objects implementing the {{MLActivation}} interface represent activation functio +
+{{MLActivation}} has the following internal slots: +
+ : \[[name]] of type [=string=] + :: + The {{MLActivation}}'s name. + : \[[builder]] of type {{MLGraphBuilder}} + :: + The graph builder object this {{MLActivation}} belongs to. + : \[[options]] of type [=object=] + :: + A dictionary containing {{MLActivation}} options. + : \[[operator]] of type [=object=] + :: + Reference to {{MLActivation}}'s corresponding [=implementation-defined=] platform operator object. +
+
+
These activations function types are used to create other operations. One such use of this interface is for when an activation function is fused into another operation such as [[#api-mlgraphbuilder-conv2d]] or [[#api-mlgraphbuilder-batchnorm]] during a graph construction session. Such fused activation functions can provide a significant performance improvement when supported natively by the underlying implementation. This is intended as an optimization opportunity for implementers.
+#### Creating {{MLActivation}} #### {#api-mlactivation-create}
-The implementation of the {{MLActivation}} interface can simply be a struct that holds a string type of the activation function along with other properties needed. The actual creation of the activation function e.g. a [[#api-mlgraphbuilder-sigmoid]] or [[#api-mlgraphbuilder-relu]] can then be deferred until when the rest of the graph is ready to connect with it such as during the construction of [[#api-mlgraphbuilder-conv2d]] for example. -
+The {{MLActivation}} objects (including the ones passed as input to methods) are created by the methods of {{MLGraphBuilder}} and are identified by their name. The |options| dictionary is defined by those methods. The actual creation of the activation function e.g. a [[#api-mlgraphbuilder-sigmoid]] or [[#api-mlgraphbuilder-relu]] can then be deferred until when the rest of the graph is ready to connect with it such as during the construction of [[#api-mlgraphbuilder-conv2d]] for example. +
+ +
+ + To create MLActivation given |builder|, |name| and |options|, run the following steps: + +
+ 1. If |builder| is not an instance of {{MLGraphBuilder}}, throw a "{{TypeError}}" and abort these steps. + 1. If |name| is `undefined` or `null`, throw a "{{TypeError}}" and abort these steps. + 1. Let |activation| be a new [=object=]. + 1. Set |activation|.{{MLActivation/[[builder]]}} to |builder|. + 1. Set |activation|.{{MLActivation/[[name]]}} to |name|. + 1. If |options| is an [=object=], set |activation|.{{MLActivation/[[options]]}} to |options|. + 1. Make a request to the underlying platform to bind the [=implementation-defined=] platform operator for |name| to |activation|.{{MLActivation/[[operator]]}}. + 1. If that fails, throw a "{{TypeError}}" and abort these steps. + 1. Return |activation|. +
+
## The MLContext interface ## {#api-mlcontext} The {{MLContext}} interface represents a global state of neural network compute workload and execution processes. Each {{MLContext}} object has associated [=context type=], [=device type=] and [=power preference=]. From dc4d3d63d2cddb3b48ef02ac1dcb785c2910cc22 Mon Sep 17 00:00:00 2001 From: Zoltan Kis Date: Fri, 2 Jun 2023 17:26:56 +0300 Subject: [PATCH 3/3] clamp(): improve platform related steps Signed-off-by: Zoltan Kis --- index.bs | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/index.bs b/index.bs index 666979e1..850564bd 100644 --- a/index.bs +++ b/index.bs @@ -760,7 +760,7 @@ To copy MLOperand given |operand|, run the following steps: 1. Let |result| be a new [=object=]. 1. Set |result|.{{MLOperand/[[builder]]}} to |operand|.{{MLOperand/[[builder]]}}. 1. Set |result|.{{MLOperand/[[descriptor]]}} to |operand|.{{MLOperand/[[descriptor]]}}. - 1. Set |result|.{{MLOperand/[[name]]}} to |operand|.{{MLOperand/[[name]]}}. + 1. If |operand|.{{MLOperand/[[name]]}} [=map/exists=], then set |result|.{{MLOperand/[[name]]}} to |operand|.{{MLOperand/[[name]]}}. 1. Return |result|. @@ -1470,8 +1470,13 @@ To check clamp options given |options|, run the following steps: 1. If running the check clamp options steps with |options| returns `false`, then throw a "{{TypeError}}" {{DOMException}} and abort these steps. 1. Let |result| be the result of invoking the copy MLOperand steps given |operand|. 1. If that throws an error, re-throw the error and abort these steps. - 1. Make a request to the underlying platform to connect |result| with the [=implementation-defined=] platform operator for clamp, and store a reference to the resulting [=implementation-defined=] platform operand object in |result|.{{MLOperand/[[operand]]}}. - 1. If that fails, throw an "{{OperationError}}" {{DOMException}} and stop. + 1. If any of the following sub-steps fail, throw an "{{OperationError}}" {{DOMException}} and stop. + 1. Make a request to the underlying platform to create an [=implementation-defined=] platform operand |operandImpl| given |result|.{{MLOperand/[[descriptor]]}}. + 1. Store a reference to |operandImpl| in |result|.{{MLOperand/[[operand]]}}. + 1. Make a request to the underlying platform to create an [=implementation-defined=] platform operator |operatorImpl| for clamp with |options|.{{MLClampOptions/minValue}} and |options|.{{MLClampOptions/minValue}}. + 1. Register the |operand|.{{MLOperand/[[operand]]}} as an input to |operatorImpl|. + 1. Register the |result|.{{MLOperand/[[operand]]}} as output to |operatorImpl|. + 1. Store a reference to |operatorImpl| in |result|.{{MLOperand/[[operator]]}}. 1. Return |result|. @@ -1490,8 +1495,9 @@ To check clamp options given |options|, run the following steps: 1. If running the check clamp options steps with |options| returns `false`, then throw a "{{TypeError}}" {{DOMException}} and abort these steps. 1. Let |op| be the result of invoking the create MLActivation steps with `"clamp"` and |options|. 1. If that throws an error, re-throw the error and abort these steps. - 1. Make a request to the underlying platform to connect |op| with the [=implementation-defined=] platform operator for clamp, and store a reference to the resulting [=implementation-defined=] platform operator object in |op|.{{MLActivation/[[operator]]}}. - 1. If that fails, throw an "{{OperationError}}" {{DOMException}} and stop. + 1. If any of the following sub-steps fail, throw an "{{OperationError}}" {{DOMException}} and stop. + 1. Make a request to the underlying platform to connect |op| with the [=implementation-defined=] platform operator for clamp |operatorImpl|. + 1. Store a reference to |operatorImpl| in |op|.{{MLActivation/[[operator]]}}. 1. Return |op|.