001/*
002 * Copyright (c) 2021, Oracle and/or its affiliates. All rights reserved.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package org.tribuo.util.onnx;
018
019import ai.onnx.proto.OnnxMl;
020
021import java.util.Arrays;
022import java.util.Collections;
023import java.util.HashMap;
024import java.util.HashSet;
025import java.util.List;
026import java.util.Map;
027import java.util.Set;
028
029import static org.tribuo.util.onnx.ONNXAttribute.VARIADIC_INPUT;
030
031/**
032 * ONNX Opset 13, and ONNX-ML version 1.
033 * <p>
034 * In a future version of Tribuo this class will be split into two enums, one for ONNX opset 13 and one for ONNX-ML v1.
035 */
036public enum ONNXOperators implements ONNXOperator {
037    /**
038     * Identity.
039     */
040    IDENTITY("Identity",1,1),
041    /**
042     * Concatenates tensors.
043     */
044    CONCAT("Concat",VARIADIC_INPUT,1, Collections.singletonList(
045            new ONNXAttribute("axis", OnnxMl.AttributeProto.AttributeType.INT, true)
046    )),
047    /**
048     * Makes a constant of the size of the supplied shape containing the {@code value}.
049     */
050    CONSTANT_OF_SHAPE("ConstantOfShape",1,1, Collections.singletonList(
051            new ONNXAttribute("value", OnnxMl.AttributeProto.AttributeType.TENSOR, false)
052    )),
053    /**
054     * Sigmoid element-wise.
055     */
056    SIGMOID("Sigmoid",1,1),
057    /**
058     * Softmax.
059     * <ul>
060     *     <li>{@code axis} defaults to -1.</li>
061     * </ul>
062     */
063    SOFTMAX("Softmax",1,1, Collections.singletonList(
064            new ONNXAttribute("axis", OnnxMl.AttributeProto.AttributeType.INT, false)
065    )),
066    /**
067     * Cast input to specified type.
068     * <ul>
069     *     <li>{@code to} must be a data type int from {@link OnnxMl.TensorProto.DataType}</li>
070     * </ul>
071     */
072    CAST("Cast",1,1, Collections.singletonList(
073            new ONNXAttribute("to", OnnxMl.AttributeProto.AttributeType.INT, true)
074    )),
075    /**
076     * Element-wise negation.
077     */
078    NEG("Neg",1,1),
079    /**
080     * Element-wise addition with broadcasting.
081     */
082    ADD("Add",2,1),
083    /**
084     * Element-wise subtraction with broadcasting.
085     */
086    SUB("Sub",2,1),
087    /**
088     * Element-wise multiplication with broadcasting.
089     */
090    MUL("Mul",2,1),
091    /**
092     * Element-wise division with broadcasting.
093     */
094    DIV("Div",2,1),
095    /**
096     * Element-wise exponentiation with broadcasting.
097     */
098    POW("Pow",2,1),
099    /**
100     * Element-wise summation across the supplied inputs with broadcasting.
101     */
102    SUM("Sum",VARIADIC_INPUT,1),
103    /**
104     * Gathers elements from the first argument (of rank r) indexed by the second argument (of rank q) producing
105     * a tensor of rank {@code q + r - 1}.
106     * <ul>
107     *     <li>{@code axis} the axis of the first argument to gather from.</li>
108     * </ul>
109     */
110    GATHER("Gather",2,1,Collections.singletonList(
111            new ONNXAttribute("axis", OnnxMl.AttributeProto.AttributeType.INT, true)
112    )),
113    /**
114     * Hardmax(element in input, axis) = 1 if the element is the first maximum value along the specified axis, 0 otherwise.
115     * <ul>
116     *     <li>{@code axis} default is -1, i.e., take the hardmax over the last dimension.</li>
117     * </ul>
118     */
119    HARDMAX("Hardmax",1,1, Collections.singletonList(
120            new ONNXAttribute("axis", OnnxMl.AttributeProto.AttributeType.INT,false)
121    )),
122    /**
123     * Computes the mean of the input tensor's element along the provided axes.
124     * <ul>
125     *     <li>{@code axes} default is to reduce over all dimensions.</li>
126     *     <li>{@code keepdims} defaults to 1 which means keep.</li>
127     * </ul>
128     */
129    REDUCE_MEAN("ReduceMean",1,1,Arrays.asList(
130            new ONNXAttribute("axes", OnnxMl.AttributeProto.AttributeType.INTS,false),
131            new ONNXAttribute("keepdims", OnnxMl.AttributeProto.AttributeType.INT,false)
132    )),
133    /**
134     * Compute the minimum along the specified axes of the tensor.
135     * <ul>
136     *     <li>{@code axes} defaults to all dimensions.</li>
137     *     <li>{@code keepdims} defaults to 1 which means keep.</li>
138     * </ul>
139     */
140    REDUCE_MIN("ReduceMin",1,1,Arrays.asList(
141            new ONNXAttribute("axes", OnnxMl.AttributeProto.AttributeType.INTS,false),
142            new ONNXAttribute("keepdims", OnnxMl.AttributeProto.AttributeType.INT,false)
143    )),
144    /**
145     * Compute the sum along the specified axes of the tensor, the axes are the second input.
146     * <ul>
147     *     <li>{@code keepdims} defaults to 1 which means keep.</li>
148     *     <li>{@code noop_with_empty_axes} defaults to 0 which means empty axes reduces the tensor to a scalar.</li>
149     * </ul>
150     */
151    REDUCE_SUM("ReduceSum",1,1,1,Arrays.asList(
152            // Opset 11 version: new ONNXAttribute("axes", OnnxMl.AttributeProto.AttributeType.INTS, false),
153            new ONNXAttribute("keepdims", OnnxMl.AttributeProto.AttributeType.INT, false),
154            new ONNXAttribute("noop_with_empty_axes", OnnxMl.AttributeProto.AttributeType.INT, false) // Opset 13
155    )),
156    /**
157     * Adds extra dimensions to a tensor in the specified places, the axes are the second input.
158     */
159    UNSQUEEZE("Unsqueeze",2,1),
160    // Unsqueeze Opset 11: Collections.singletonList(new ONNXAttribute("axes", OnnxMl.AttributeProto.AttributeType.INTS, true))
161    /**
162     * General Matrix Multiply: {@code alpha*AB + beta*C}.
163     * <p>
164     * The {@code C} input is optional, and if not supplied is treated as zero.
165     * <ul>
166     *     <li>{@code alpha} defaults to 1.0</li>
167     *     <li>{@code beta} defaults to 1.0</li>
168     *     <li>{@code transA} defaults to 0 (i.e., not transposed)</li>
169     *     <li>{@code transB} defaults to 0 (i.e., not transposed)</li>
170     * </ul>
171     */
172    GEMM("Gemm",2,1, 1, Arrays.asList(
173            new ONNXAttribute("alpha", OnnxMl.AttributeProto.AttributeType.FLOAT,false),
174            new ONNXAttribute("beta", OnnxMl.AttributeProto.AttributeType.FLOAT,false),
175            new ONNXAttribute("transA", OnnxMl.AttributeProto.AttributeType.INT,false),
176            new ONNXAttribute("transB", OnnxMl.AttributeProto.AttributeType.INT,false)
177    )),
178    /**
179     * Greater than, returns the element-wise greater than operation on the two tensors.
180     * <p>
181     * Tensors must be broadcastable to the same shape.
182     */
183    GREATER("Greater",2,1),
184    /**
185     * Greater than or equal to, returns the element-wise greater than or equal to operation on the two tensors.
186     * <p>
187     * Tensors must be broadcastable to the same shape.
188     */
189    GREATER_OR_EQUAL("GreaterOrEqual",2,1),
190    /**
191     * Less than, returns the element-wise less than operation on the two tensors.
192     * <p>
193     * Tensors must be broadcastable to the same shape.
194     */
195    LESS("Less",2,1),
196    /**
197     * Less than or equal to, returns the element-wise less than or equal to operation on the two tensors.
198     * <p>
199     * Tensors must be broadcastable to the same shape.
200     */
201    LESS_OR_EQUAL("LessOrEqual",2,1),
202    /**
203     * Choice operator, based on the true value of the condition input, returns the element at that index from either
204     * the second or third input. When the test is true, return the second input, otherwise return the third input.
205     */
206    WHERE("Where",3,1),
207    /**
208     * Array feature extractor, selects the indices specified by the second tensor from the last dimension of the first tensor.
209     */
210    ARRAY_FEATURE_EXTRACTOR("ArrayFeatureExtractor",2,1,"ai.onnx.ml"),
211    /**
212     * SVM Classifier.
213     * <ul>
214     *     <li>{@code classlabels_ints} - Class labels if using integer labels. One and only one of the 'classlabels_*' attributes must be defined.</li>
215     *     <li>{@code classlabels_strings} - Class labels if using string labels. One and only one of the 'classlabels_*' attributes must be defined.</li>
216     *     <li>{@code coefficients} - SVM coefficients</li>
217     *     <li>{@code kernel_params} - Tuple of gamma, coef0 and degree. Set to zero if unused by the kernel.</li>
218     *     <li>{@code kernel_type} - One of 'LINEAR,' 'POLY,' 'RBF,' 'SIGMOID'.</li>
219     *     <li>{@code post_transforms} - Transform to apply to the score (usually unused by SVMs), one of 'NONE,' 'SOFTMAX,' 'LOGISTIC,' 'SOFTMAX_ZERO,' or 'PROBIT'.</li>
220     *     <li>{@code prob_a} - Probability coefficients, if set must be the same size as prob_b.</li>
221     *     <li>{@code prob_b} - Probability coefficients, if set must be the same size as prob_a.</li>
222     *     <li>{@code rho} - Rho vector.</li>
223     *     <li>{@code support_vectors} - linearised support vectors.</li>
224     *     <li>{@code vectors_per_class} - the number of support vectors in each class.</li>
225     * </ul>
226     */
227    SVM_CLASSIFIER("SVMClassifier",1,2, "ai.onnx.ml", Arrays.asList(
228            new ONNXAttribute("classlabels_ints",OnnxMl.AttributeProto.AttributeType.INTS,false),
229            new ONNXAttribute("classlabels_strings",OnnxMl.AttributeProto.AttributeType.STRINGS,false),
230            new ONNXAttribute("coefficients",OnnxMl.AttributeProto.AttributeType.FLOATS,true),
231            new ONNXAttribute("kernel_params",OnnxMl.AttributeProto.AttributeType.FLOATS,true),
232            new ONNXAttribute("kernel_type",OnnxMl.AttributeProto.AttributeType.STRING,false),
233            new ONNXAttribute("post_transform",OnnxMl.AttributeProto.AttributeType.STRING,false),
234            new ONNXAttribute("prob_a",OnnxMl.AttributeProto.AttributeType.FLOATS,false),
235            new ONNXAttribute("prob_b",OnnxMl.AttributeProto.AttributeType.FLOATS,false),
236            new ONNXAttribute("rho",OnnxMl.AttributeProto.AttributeType.FLOATS,true),
237            new ONNXAttribute("support_vectors",OnnxMl.AttributeProto.AttributeType.FLOATS,true),
238            new ONNXAttribute("vectors_per_class",OnnxMl.AttributeProto.AttributeType.INTS,true)
239    )),
240    /**
241     * SVM Regressor.
242     * <ul>
243     *     <li>{@code coefficients} - SVM coefficients</li>
244     *     <li>{@code kernel_params} - Tuple of gamma, coef0 and degree. Set to zero if unused by the kernel.</li>
245     *     <li>{@code kernel_type} - One of 'LINEAR,' 'POLY,' 'RBF,' 'SIGMOID'.</li>
246     *     <li>{@code n_supports} - The number of support vectors.</li>
247     *     <li>{@code one_class} - Flag noting if this regression is a one-class SVM for anomaly detection or not.</li>
248     *     <li>{@code post_transforms} - Transform to apply to the score (usually unused by SVMs), one of 'NONE,' 'SOFTMAX,' 'LOGISTIC,' 'SOFTMAX_ZERO,' or 'PROBIT'.</li>
249     *     <li>{@code rho} - Rho vector.</li>
250     *     <li>{@code support_vectors} - linearised support vectors.</li>
251     * </ul>
252     */
253    SVM_REGRESSOR("SVMRegressor",1,1, "ai.onnx.ml", Arrays.asList(
254            new ONNXAttribute("coefficients",OnnxMl.AttributeProto.AttributeType.FLOATS,true),
255            new ONNXAttribute("kernel_params",OnnxMl.AttributeProto.AttributeType.FLOATS,true),
256            new ONNXAttribute("kernel_type",OnnxMl.AttributeProto.AttributeType.STRING,false),
257            new ONNXAttribute("n_supports",OnnxMl.AttributeProto.AttributeType.INT,true),
258            new ONNXAttribute("one_class",OnnxMl.AttributeProto.AttributeType.INT,false),
259            new ONNXAttribute("post_transform",OnnxMl.AttributeProto.AttributeType.STRING,false),
260            new ONNXAttribute("rho",OnnxMl.AttributeProto.AttributeType.FLOATS,true),
261            new ONNXAttribute("support_vectors",OnnxMl.AttributeProto.AttributeType.FLOATS,true)
262    ))
263    ;
264
265    /**
266     * The operator name.
267     */
268    public final String opName;
269    /**
270     * The number of inputs.
271     */
272    public final int numInputs;
273    /**
274     * The number of optional inputs.
275     */
276    public final int numOptionalInputs;
277    /**
278     * The number of outputs.
279     */
280    public final int numOutputs;
281    /**
282     * The operator attributes.
283     */
284    public final Map<String,ONNXAttribute> attributes;
285    /**
286     * The mandatory attribute names.
287     */
288    public final Set<String> mandatoryAttributeNames;
289    /**
290     * The operator domain (used for the ML operators).
291     * <p>
292     * Null if the domain is the default one.
293     */
294    public final String domain;
295
296    /**
297     * Opset supported by these definitions.
298     */
299    private static final int OPSET_VERSION = 13;
300
301    /**
302     * Builds an operator without attributes.
303     * @param value The operator name.
304     * @param numInputs The number of inputs.
305     * @param numOutputs The number of outputs.
306     */
307    private ONNXOperators(String value, int numInputs, int numOutputs) {
308        this(value,numInputs,0,numOutputs);
309    }
310
311    /**
312     * Builds an operator without attributes and with optional inputs.
313     * @param value The operator name.
314     * @param numInputs The number of inputs.
315     * @param numOptionalInputs The number of optional inputs.
316     * @param numOutputs The number of outputs.
317     */
318    private ONNXOperators(String value, int numInputs, int numOptionalInputs, int numOutputs) {
319        this(value, numInputs, numOptionalInputs, numOutputs, (String) null);
320    }
321
322    /**
323     * Builds an operator without attributes and with optional inputs.
324     * @param value The operator name.
325     * @param numInputs The number of inputs.
326     * @param numOutputs The number of outputs.
327     * @param domain The domain.
328     */
329    private ONNXOperators(String value, int numInputs, int numOutputs, String domain) {
330        this(value, numInputs, 0, numOutputs, domain);
331    }
332
333    /**
334     * Builds an operator without attributes and with optional inputs.
335     * @param value The operator name.
336     * @param numInputs The number of inputs.
337     * @param numOptionalInputs The number of optional inputs.
338     * @param numOutputs The number of outputs.
339     * @param domain The domain.
340     */
341    private ONNXOperators(String value, int numInputs, int numOptionalInputs, int numOutputs, String domain) {
342        this.opName = value;
343        this.numInputs = numInputs;
344        this.numOptionalInputs = numOptionalInputs;
345        this.numOutputs = numOutputs;
346        this.attributes = Collections.emptyMap();
347        this.mandatoryAttributeNames = Collections.emptySet();
348        this.domain = domain;
349    }
350
351    /**
352     * Builds an operator with attributes.
353     * @param value The operator name.
354     * @param numInputs The number of inputs.
355     * @param numOutputs The number of outputs.
356     * @param attributes The attributes.
357     */
358    private ONNXOperators(String value, int numInputs, int numOutputs, List<ONNXAttribute> attributes) {
359        this(value,numInputs,0,numOutputs,attributes);
360    }
361
362    /**
363     * Builds an operator with attributes.
364     * @param value The operator name.
365     * @param numInputs The number of inputs.
366     * @param numOutputs The number of outputs.
367     * @param domain The domain.
368     * @param attributes The attributes.
369     */
370    private ONNXOperators(String value, int numInputs, int numOutputs, String domain, List<ONNXAttribute> attributes) {
371        this(value,numInputs,0,numOutputs, domain, attributes);
372    }
373
374    /**
375     * Builds an operator with attributes and optional inputs.
376     * @param value The operator name.
377     * @param numInputs The number of inputs.
378     * @param numOptionalInputs The number of optional inputs.
379     * @param numOutputs The number of outputs.
380     * @param attributes The attributes.
381     */
382    private ONNXOperators(String value, int numInputs, int numOptionalInputs, int numOutputs, List<ONNXAttribute> attributes) {
383        this(value,numInputs,numOptionalInputs,numOutputs, null, attributes);
384    }
385
386    /**
387     * Builds an operator with attributes and optional inputs.
388     * @param value The operator name.
389     * @param numInputs The number of inputs.
390     * @param numOptionalInputs The number of optional inputs.
391     * @param numOutputs The number of outputs.
392     * @param domain The operator domain.
393     * @param attributes The attributes.
394     */
395    private ONNXOperators(String value, int numInputs, int numOptionalInputs, int numOutputs, String domain, List<ONNXAttribute> attributes) {
396        this.opName = value;
397        this.numInputs = numInputs;
398        this.numOptionalInputs = numOptionalInputs;
399        this.numOutputs = numOutputs;
400        Map<String,ONNXAttribute> attributeMap = new HashMap<>();
401        Set<String> attributeSet = new HashSet<>();
402        for (ONNXAttribute a : attributes) {
403            attributeMap.put(a.getName(),a);
404            if (a.isMandatory()) {
405                attributeSet.add(a.getName());
406            }
407        }
408        if (attributes.size() != attributeMap.size()) {
409            throw new IllegalArgumentException("Duplicate attribute in enum declaration - " + attributes);
410        }
411        this.attributes = Collections.unmodifiableMap(attributeMap);
412        this.mandatoryAttributeNames = attributeSet.isEmpty() ? Collections.emptySet() : Collections.unmodifiableSet(attributeSet);
413        this.domain = domain;
414    }
415
416    @Override
417    public String getOpName() {
418        return opName;
419    }
420
421    @Override
422    public int getNumInputs() {
423        return numInputs;
424    }
425
426    @Override
427    public int getNumOptionalInputs() {
428        return numOptionalInputs;
429    }
430
431    @Override
432    public int getNumOutputs() {
433        return numOutputs;
434    }
435
436    @Override
437    public Map<String,ONNXAttribute> getAttributes() {
438        return attributes;
439    }
440
441    @Override
442    public Set<String> getMandatoryAttributeNames() {
443        return mandatoryAttributeNames;
444    }
445
446    @Override
447    public int getOpVersion() {
448        return getOpsetVersion();
449    }
450
451    @Override
452    public String getOpDomain() {
453        return domain;
454    }
455
456    /**
457     * Returns the opset version supported by these operators.
458     * @return The opset version.
459     */
460    public static int getOpsetVersion() {
461        return OPSET_VERSION;
462    }
463
464    /**
465     * Returns the opset proto for these operators.
466     * @return The opset proto.
467     */
468    public static OnnxMl.OperatorSetIdProto getOpsetProto() {
469        return OnnxMl.OperatorSetIdProto.newBuilder().setVersion(ONNXOperators.getOpsetVersion()).build();
470    }
471}