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;
020import com.google.protobuf.GeneratedMessageV3;
021
022import java.util.ArrayList;
023import java.util.Arrays;
024import java.util.Collections;
025import java.util.List;
026import java.util.Map;
027import java.util.stream.Collectors;
028
029/**
030 * An abstract reference that represents both a node in an ONNX computation graph and a container for a specific ONNX
031 * proto object that denotes that node. In its role as the former it provides a fluent interface for applying
032 * {@link ONNXOperator}s to {@link ONNXRef} instances. ONNXRef instances are ultimately created by an {@link ONNXContext}
033 * instance, and ONNXRefs created by different instances of ONNXContext are incompatible. All ONNX proto objects
034 * produced by calling {@code apply} methods on ONNXRefs are added to a {@link ai.onnx.proto.OnnxMl.GraphProto} field
035 * in their governing ONNXContext. Instances of ONNXRef have a backreference to the ONNXContext that created them and
036 * can thus be passed around without needing to pass their governing context as well.
037 * <p>
038 * N.B. This class will be sealed once the library is updated past Java 8. Users should not subclass this class.
039 * @param <T> The protobuf type this reference generates.
040 */
041public abstract class ONNXRef<T extends GeneratedMessageV3> {
042    // Unfortunately there is no other shared supertype for OnnxML protobufs
043    /**
044     * Protobuf reference.
045     */
046    protected final T backRef;
047    private final String baseName;
048    /**
049     * The ONNX context.
050     */
051    protected final ONNXContext context;
052
053    /**
054     * Creates an ONNXRef for the specified context, protobuf and name.
055     * @param context The ONNXContext we're operating in.
056     * @param backRef The protobuf reference.
057     * @param baseName The name of this reference.
058     */
059    ONNXRef(ONNXContext context, T backRef, String baseName) {
060        this.context = context;
061        this.backRef = backRef;
062        this.baseName = baseName;
063    }
064
065    /**
066     * Gets the output name of this object.
067     * @return The output name.
068     */
069    public abstract String getReference();
070
071    /**
072     * The name of this object.
073     * @return The name.
074     */
075    public String getBaseName() {
076        return baseName;
077    }
078
079    /**
080     * The context this reference operates in.
081     * @return The context.
082     */
083    public ONNXContext onnxContext() {
084        return context;
085    }
086
087    /**
088     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, List, Map)}, using this ONNXRef
089     * as the first argument to {@code inputs}, with {@code otherInputs} append as subsequent arguments. The other
090     * arguments behave as in the analogous method on ONNXContext.
091     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
092     * @param otherInputs A list of {@link ONNXRef}s created by this instance of ONNXContext.
093     * @param outputs A list of names that the output nodes of {@code op} should take.
094     * @param attributes A map of attributes of the operation, passed to {@link ONNXOperator#build(ONNXContext, String, String, Map)}.
095     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
096     */
097    public List<ONNXNode> apply(ONNXOperator op, List<ONNXRef<?>> otherInputs, List<String> outputs, Map<String, Object> attributes) {
098        List<ONNXRef<?>> allInputs = new ArrayList<>();
099        allInputs.add(this);
100        allInputs.addAll(otherInputs);
101        return context.operation(op, allInputs, outputs, attributes);
102    }
103
104    /**
105     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, List, Map)}, using this ONNXRef
106     * as the argument to {@code inputs}. The other arguments behave as in the analogous method on ONNXContext.
107     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
108     * @param outputs A list of names that the output nodes of {@code op} should take.
109     * @param attributes A map of attributes of the operation, passed to {@link ONNXOperator#build(ONNXContext, String, String, Map)}.
110     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
111     */
112    public List<ONNXNode> apply(ONNXOperator op, List<String> outputs, Map<String, Object> attributes) {
113        return context.operation(op, Collections.singletonList(this), outputs, attributes);
114    }
115
116    /**
117     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, String)}, using this ONNXRef
118     * as the argument to {@code inputs}. Output names are generated based on the {@link ONNXOperator#getOpName} and the
119     * name of the input nodes.
120     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
121     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
122     */
123    public ONNXNode apply(ONNXOperator op) {
124        return context.operation(op, Collections.singletonList(this), getBaseName() + "_" + op.getOpName(), Collections.emptyMap());
125    }
126
127    /**
128     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, String)}, using this ONNXRef
129     * as the argument to {@code inputs}.
130     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
131     * @param outputName A name that the output node of {@code op} will take.
132     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
133     */
134    public ONNXNode apply(ONNXOperator op, String outputName) {
135        return context.operation(op, Collections.singletonList(this), outputName, Collections.emptyMap());
136    }
137
138    /**
139     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, String, Map)}, using this ONNXRef
140     * as the argument to {@code inputs}. Output names are generated based on the {@link ONNXOperator#getOpName} and the
141     * name of the input nodes.
142     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
143     * @param attributes A map of attributes of the operation, passed to {@link ONNXOperator#build(ONNXContext, String, String, Map)}.
144     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
145     */
146    public ONNXNode apply(ONNXOperator op, Map<String, Object> attributes) {
147        return context.operation(op, Collections.singletonList(this), getBaseName() + "_" + op.getOpName(), attributes);
148    }
149
150    /**
151     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, String, Map)}, passing this ONNXRef
152     * and {@code other} as a length 2 list to {@code inputs}. The other arguments behave as in the analogous method on
153     * ONNXContext. Output names are generated based on the {@link ONNXOperator#getOpName} and the name of the input nodes.
154     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
155     * @param other A second input argument to {@code op}
156     * @param attributes A map of attributes of the operation, passed to {@link ONNXOperator#build(ONNXContext, String, String, Map)}.
157     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
158     */
159    public ONNXNode apply(ONNXOperator op, ONNXRef<?> other, Map<String, Object> attributes) {
160        return context.operation(op, Arrays.asList(this, other), getBaseName() + "_" + op.getOpName() + "_" + other.getBaseName(), attributes);
161    }
162
163    /**
164     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, String)}, passing this ONNXRef
165     * and {@code other} as a length 2 list to {@code inputs}.
166     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
167     * @param other A second input argument to {@code op}
168     * @param outputName A name that the output node of {@code op} will take.
169     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
170     */
171    public ONNXNode apply(ONNXOperator op, ONNXRef<?> other, String outputName) {
172        return context.operation(op, Arrays.asList(this, other), outputName, Collections.emptyMap());
173    }
174
175    /**
176     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, String, Map)}, passing this ONNXRef
177     * and {@code other} as a length 2 list to {@code inputs}. Output names are generated based on the
178     * {@link ONNXOperator#getOpName} and the name of the input nodes.
179     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
180     * @param other A second input argument to {@code op}
181     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
182     */
183    public ONNXNode apply(ONNXOperator op, ONNXRef<?> other) {
184        return context.operation(op, Arrays.asList(this, other), getBaseName() + "_" + op.getOpName() + "_" + other.getBaseName(), Collections.emptyMap());
185    }
186
187    /**
188     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, String, Map)}, using this ONNXRef
189     * as the first argument to {@code inputs}, with {@code otherInputs} append as subsequent arguments. Output names
190     * are generated based on the {@link ONNXOperator#getOpName} and the name of the input nodes.
191     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
192     * @param others List of ONNXRefs supplied as inputs to {@code op} after this ONNXRef.
193     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
194     */
195    public ONNXNode apply(ONNXOperator op, List<ONNXRef<?>> others) {
196        return apply(op, others, Collections.singletonList(getBaseName() + "_" + others.stream().map(ONNXRef::getBaseName).collect(Collectors.joining("_"))), Collections.emptyMap()).get(0);
197    }
198
199    /**
200     * Convenience method that calls {@link ONNXContext#operation(ONNXOperator, List, String, Map)}, using this ONNXRef
201     * as the argument to {@code inputs}, with {@code otherInputs} append as subsequent arguments.
202     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
203     * @param others List of ONNXRefs supplied as inputs to {@code op} after this ONNXRef.
204     * @param outputName The name for the constructed node.
205     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
206     */
207    public ONNXNode apply(ONNXOperator op, List<ONNXRef<?>> others, String outputName) {
208        return apply(op, others, Collections.singletonList(outputName), Collections.emptyMap()).get(0);
209    }
210
211    /**
212     * Convenience method that calls {@link ONNXContext#assignTo(ONNXRef, ONNXRef)}, using this ONNXRef as the argument
213     * to {@code input}.
214     * @param output The output node / left-hand side of the assignment
215     * @param <Ret> the {@link ONNXRef} type of the output.
216     * @return the output node that was assigned to.
217     */
218    public <Ret extends ONNXRef<?>> Ret assignTo(Ret output) {
219        return context.assignTo(this, output);
220    }
221
222    /**
223     * Casts this ONNXRef to a different type using the {@link ONNXOperators#CAST} operation, and returning the output
224     * node of that op. Currently supports only float, double, int, and long, which are specified by their respective
225     * {@link Class} objects (e.g., {@code float.class}). Throws {@link IllegalArgumentException} when an unsupported cast
226     * is requested.
227     * @param clazz The class object specifying the type to cast to.
228     * @return An ONNXRef representing this object cast into the requested type.
229     */
230    public ONNXNode cast(Class<?> clazz) {
231        if (clazz.equals(float.class)) {
232            return apply(ONNXOperators.CAST, Collections.singletonMap("to", OnnxMl.TensorProto.DataType.FLOAT.getNumber()));
233        } else if(clazz.equals(double.class)) {
234            return apply(ONNXOperators.CAST, Collections.singletonMap("to", OnnxMl.TensorProto.DataType.DOUBLE.getNumber()));
235        } else if(clazz.equals(int.class)) {
236            return apply(ONNXOperators.CAST, Collections.singletonMap("to", OnnxMl.TensorProto.DataType.INT32.getNumber()));
237        } else if(clazz.equals(long.class)) {
238            return apply(ONNXOperators.CAST, Collections.singletonMap("to", OnnxMl.TensorProto.DataType.INT64.getNumber()));
239        } else {
240            throw new IllegalArgumentException("unsupported class for casting: " + clazz.getName());
241        }
242    }
243}