001/*
002 * Copyright (c) 2022, 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.Collections;
022import java.util.Map;
023import java.util.Set;
024import java.util.logging.Logger;
025
026import static org.tribuo.util.onnx.ONNXAttribute.VARIADIC_INPUT;
027
028/**
029 * An interface for ONNX operators. Usually implemented by an enum representing the opset.
030 */
031public interface ONNXOperator {
032
033    /**
034     * The operator name.
035     * @return The name.
036     */
037    public String getOpName();
038
039    /**
040     * The number of inputs.
041     * @return The number of inputs.
042     */
043    public int getNumInputs();
044
045    /**
046     * The number of optional inputs.
047     * @return The number of optional inputs.
048     */
049    public int getNumOptionalInputs();
050
051    /**
052     * The number of outputs.
053     * @return The number of outputs.
054     */
055    public int getNumOutputs();
056
057    /**
058     * The operator attributes.
059     * @return The operator attribute map.
060     */
061    public Map<String,ONNXAttribute> getAttributes();
062    
063    /**
064     * The mandatory attribute names.
065     * @return The required attribute names.
066     */
067    public Set<String> getMandatoryAttributeNames();
068
069    /**
070     * Returns the opset version.
071     * @return The opset version.
072     */
073    public int getOpVersion();
074
075    /**
076     * Returns the opset domain.
077     * <p>
078     * May be {@code null} if it is the default ONNX domain;
079     * @return The opset domain.
080     */
081    public String getOpDomain();
082
083    /**
084     * Returns the opset proto for these operators.
085     * @return The opset proto.
086     */
087    default public OnnxMl.OperatorSetIdProto opsetProto() {
088        return OnnxMl.OperatorSetIdProto.newBuilder().setDomain(getOpDomain()).setVersion(getOpVersion()).build();
089    }
090
091    /**
092     * Builds this node based on the supplied inputs and output.
093     * Throws {@link IllegalArgumentException} if this operator takes more than a single input or output.
094     * @param context The onnx context used to ensure this node has a unique name.
095     * @param input The name of the input.
096     * @param output The name of the output.
097     * @return The NodeProto.
098     */
099    default public OnnxMl.NodeProto build(ONNXContext context, String input, String output) {
100        return build(context,new String[]{input},new String[]{output}, Collections.emptyMap());
101    }
102
103    /**
104     * Builds this node based on the supplied inputs and output.
105     * Throws {@link IllegalArgumentException} if this operator takes more than a single input or output.
106     * May throw {@link UnsupportedOperationException} if the attribute type is not supported.
107     * @param context The onnx context used to ensure this node has a unique name.
108     * @param input The names of the input.
109     * @param output The name of the output.
110     * @param attributeValues The attribute names and values.
111     * @return The NodeProto.
112     */
113    default public OnnxMl.NodeProto build(ONNXContext context, String input, String output, Map<String,Object> attributeValues) {
114        return build(context,new String[]{input},new String[]{output},attributeValues);
115    }
116
117    /**
118     * Builds this node based on the supplied inputs and output.
119     * Throws {@link IllegalArgumentException} if the number of inputs or outputs is wrong.
120     * @param context The onnx context used to ensure this node has a unique name.
121     * @param inputs The names of the inputs.
122     * @param output The name of the output.
123     * @return The NodeProto.
124     */
125    default public OnnxMl.NodeProto build(ONNXContext context, String[] inputs, String output) {
126        return build(context,inputs,new String[]{output},Collections.emptyMap());
127    }
128
129    /**
130     * Builds this node based on the supplied inputs and output.
131     * Throws {@link IllegalArgumentException} if the number of inputs, outputs or attributes is wrong.
132     * May throw {@link UnsupportedOperationException} if the attribute type is not supported.
133     * @param context The onnx context used to ensure this node has a unique name.
134     * @param inputs The names of the inputs.
135     * @param output The name of the output.
136     * @param attributeValues The attribute names and values.
137     * @return The NodeProto.
138     */
139    default public OnnxMl.NodeProto build(ONNXContext context, String[] inputs, String output, Map<String,Object> attributeValues) {
140        return build(context,inputs,new String[]{output},attributeValues);
141    }
142
143    /**
144     * Builds this node based on the supplied input and outputs.
145     * Throws {@link IllegalArgumentException} if the number of inputs or outputs is wrong.
146     * @param context The onnx context used to ensure this node has a unique name.
147     * @param input The name of the input.
148     * @param outputs The names of the outputs.
149     * @return The NodeProto.
150     */
151    default public OnnxMl.NodeProto build(ONNXContext context, String input, String[] outputs) {
152        return build(context,new String[]{input},outputs,Collections.emptyMap());
153    }
154
155    /**
156     * Builds this node based on the supplied input and outputs.
157     * Throws {@link IllegalArgumentException} if the number of inputs, outputs or attributes is wrong.
158     * May throw {@link UnsupportedOperationException} if the attribute type is not supported.
159     * @param context The onnx context used to ensure this node has a unique name.
160     * @param input The name of the input.
161     * @param outputs The names of the outputs.
162     * @param attributeValues The attribute names and values.
163     * @return The NodeProto.
164     */
165    default public OnnxMl.NodeProto build(ONNXContext context, String input, String[] outputs, Map<String,Object> attributeValues) {
166        return build(context,new String[]{input},outputs,attributeValues);
167    }
168
169    /**
170     * Builds this node based on the supplied inputs and outputs.
171     * Throws {@link IllegalArgumentException} if the number of inputs or outputs is wrong.
172     * @param context The onnx context used to ensure this node has a unique name.
173     * @param inputs The names of the inputs.
174     * @param outputs The names of the outputs.
175     * @return The NodeProto.
176     */
177    default public OnnxMl.NodeProto build(ONNXContext context, String[] inputs, String[] outputs) {
178        return build(context,inputs,outputs,Collections.emptyMap());
179    }
180
181    /**
182     * Builds this node based on the supplied inputs and outputs.
183     * Throws {@link IllegalArgumentException} if the number of inputs, outputs or attributes is wrong.
184     * May throw {@link UnsupportedOperationException} if the attribute type is not supported.
185     * @param context The onnx context used to ensure this node has a unique name.
186     * @param inputs The names of the inputs.
187     * @param outputs The names of the outputs.
188     * @param attributeValues The attribute names and values.
189     * @return The NodeProto.
190     */
191    default public OnnxMl.NodeProto build(ONNXContext context, String[] inputs, String[] outputs, Map<String,Object> attributeValues) {
192        int numInputs = getNumInputs();
193        int numOptionalInputs = getNumOptionalInputs();
194        int numOutputs = getNumOutputs();
195        String opName = getOpName();
196        String domain = getOpDomain();
197        Map<String, ONNXAttribute> attributes = getAttributes();
198        Set<String> mandatoryAttributeNames = getMandatoryAttributeNames();
199
200        String opStatus = String.format("Building op %s:%s(%d(+%d)) -> %d", domain, opName, numInputs, numOptionalInputs, numOutputs);
201
202        if ((numInputs != VARIADIC_INPUT) && ((inputs.length < numInputs) || (inputs.length > numInputs + numOptionalInputs))) {
203            throw new IllegalArgumentException(opStatus + ". Expected " + numInputs + " inputs, with " + numOptionalInputs + " optional inputs, but received " + inputs.length);
204        } else if ((numInputs == VARIADIC_INPUT) && (inputs.length == 0)) {
205            throw new IllegalArgumentException(opStatus + ". Expected at least one input for variadic input, received zero");
206        }
207        if (outputs.length != numOutputs) {
208            throw new IllegalArgumentException(opStatus + ". Expected " + numOutputs + " outputs, but received " + outputs.length);
209        }
210        if (!attributes.keySet().containsAll(attributeValues.keySet())) {
211            throw new IllegalArgumentException(opStatus + ". Unexpected attribute found, received " + attributeValues.keySet() + ", expected values from " + attributes.keySet());
212        }
213        if (!attributeValues.keySet().containsAll(mandatoryAttributeNames)) {
214            throw new IllegalArgumentException(opStatus + ". Expected to find all mandatory attributes, received " + attributeValues.keySet() + ", expected " + mandatoryAttributeNames);
215        }
216
217        Logger.getLogger("org.tribuo.util.onnx.ONNXOperator").fine(opStatus);
218        OnnxMl.NodeProto.Builder nodeBuilder = OnnxMl.NodeProto.newBuilder();
219        for (String i : inputs) {
220            nodeBuilder.addInput(i);
221        }
222        for (String o : outputs) {
223            nodeBuilder.addOutput(o);
224        }
225        nodeBuilder.setName(context.generateUniqueName(opName));
226        nodeBuilder.setOpType(opName);
227        if (domain != null) {
228            nodeBuilder.setDomain(domain);
229        }
230        for (Map.Entry<String,Object> e : attributeValues.entrySet()) {
231            ONNXAttribute attr = attributes.get(e.getKey());
232            nodeBuilder.addAttribute(attr.build(e.getValue()));
233        }
234        return nodeBuilder.build();
235    }
236}