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.nio.FloatBuffer;
022import java.util.Collections;
023import java.util.HashMap;
024import java.util.List;
025import java.util.Map;
026import java.util.function.Consumer;
027import java.util.stream.Collectors;
028import java.util.stream.IntStream;
029
030/**
031 * Context object used to scope and manage the creation of ONNX {@link ai.onnx.proto.OnnxMl.GraphProto} and {@link ai.onnx.proto.OnnxMl.ModelProto}
032 * instances. A single instance of ONNXContext should be used to create an ONNX graph/model, and mixing instances of
033 * ONNXContext or of {@link ONNXRef}s produced by multiple ONNXContexts is not supported.
034 * <p>
035 * The ONNXContext has all of the logic needed to produce ONNX graphs, but is typically used explicitly to produce leaf
036 * nodes of graphs (inputs, outputs, and weight matrices) that have more fluent interfaces to {@link ONNXContext#operation(ONNXOperator, List, List, Map)}.
037 * Produced ONNX protobuf objects are encapsulated by instances of {@link ONNXRef} and its subclasses.
038 */
039public final class ONNXContext {
040
041    private final Map<String, Long> nameMap;
042
043    private final OnnxMl.GraphProto.Builder protoBuilder;
044
045    /**
046     * Creates an empty ONNX context.
047     */
048    public ONNXContext() {
049        this.nameMap = new HashMap<>();
050        this.protoBuilder = OnnxMl.GraphProto.newBuilder();
051    }
052
053    /**
054     * Base method for creating {@link ONNXNode}s from {@link ONNXOperator} and inputs. Returns an instance of ONNXNode
055     * for each output of the ONNXOperator. The graph elements created by the operation are added to the calling
056     * ONNXContext instance. All inputs must belong to the calling instance of ONNXContext. This is the root method for
057     * constructing ONNXNodes which all other methods on ONNXContext and {@code ONNXRef} call.
058     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
059     * @param inputs A list of {@link ONNXRef}s created by this instance of ONNXContext.
060     * @param outputs A list of names that the output nodes of {@code op} should take.
061     * @param attributes A map of attributes of the operation, passed to {@link ONNXOperator#build(ONNXContext, String, String, Map)}.
062     * @param <T> The ONNXRef type of inputs
063     * @return a list of {@link ONNXNode}s that are the output nodes of {@code op}.
064     */
065    public <T extends ONNXRef<?>> List<ONNXNode> operation(ONNXOperator op,
066                                                    List<T> inputs,
067                                                    List<String> outputs,
068                                                    Map<String, Object> attributes) {
069        if(!inputs.stream().allMatch(n -> n.context == this)) {
070            throw new IllegalArgumentException("All input nodes must belong to this ONNXContext");
071        }
072        OnnxMl.NodeProto opProto = op.build(this,
073                inputs.stream().map(ONNXRef::getReference).toArray(String[]::new),
074                outputs.stream().map(this::generateUniqueName).toArray(String[]::new),
075                attributes);
076        protoBuilder.addNode(opProto);
077        return IntStream.range(0, outputs.size()).mapToObj(i-> new ONNXNode(this, opProto, outputs.get(i), i)).collect(Collectors.toList());
078    }
079
080    /**
081     * Method for creating {@link ONNXNode}s from {@link ONNXOperator} and inputs. Returns a single ONNXNode and throws
082     * IllegalStateException if the operator has multiple outputs. The graph elements created by the operation are added
083     * to the calling ONNXContext instance. All inputs must belong to the calling instance of ONNXContext.
084     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
085     * @param inputs A list of {@link ONNXRef}s created by this instance of ONNXContext.
086     * @param outputName Name that the output node of {@code op} should take.
087     * @param attributes A map of attributes of the operation, passed to {@link ONNXOperator#build(ONNXContext, String, String, Map)}.
088     * @param <T> The ONNXRef type of inputs
089     * @return An {@link ONNXNode} that is the output nodes of {@code op}.
090     */
091    public <T extends ONNXRef<?>> ONNXNode operation(ONNXOperator op, List<T> inputs, String outputName, Map<String, Object> attributes) {
092        List<ONNXNode> opOutputs = operation(op, inputs, Collections.singletonList(outputName), attributes);
093        if(opOutputs.get(0).backRef.getOutputList().size() > 1) {
094            throw new IllegalStateException("Requested a single output from operation " + op.getOpName() + " which produced " + opOutputs.get(0).backRef.getOutputList().size() + " outputs");
095        } else {
096            return opOutputs.get(0);
097        }
098    }
099
100    /**
101     * Method for creating {@link ONNXNode}s from {@link ONNXOperator} instances and inputs. Returns a single ONNXNode
102     * and throws IllegalStateException if the operator has multiple outputs. The graph elements created by the
103     * operation are added to the calling ONNXContext instance. All inputs must belong to the calling instance of
104     * ONNXContext.
105     * @param op An ONNXOperator to add to the graph, taking {@code inputs} as input.
106     * @param inputs A list of {@link ONNXRef}s created by this instance of ONNXContext.
107     * @param outputName Name that the output node of {@code op} should take.
108     * @param <T> The ONNXRef type of inputs
109     * @return An {@link ONNXNode} that is the output nodes of {@code op}.
110     */
111    public <T extends ONNXRef<?>> ONNXNode operation(ONNXOperator op, List<T> inputs, String outputName) {
112        return operation(op, inputs, outputName, Collections.emptyMap());
113    }
114
115    /**
116     * Creates an {@link ONNXOperators#IDENTITY} node connecting {@code input} to {@code output}, effectively permitting
117     * assignment of values.
118     * @param input The input node / right-hand side of the assignment.
119     * @param output The output node / left-hand side of the assignment.
120     * @param <LHS> the {@link ONNXRef} type of the output.
121     * @param <RHS> the {@link ONNXRef} type of the input.
122     * @return the output node that was assigned to.
123     */
124    public <LHS extends ONNXRef<?>, RHS extends ONNXRef<?>> LHS assignTo(RHS input, LHS output) {
125        if(!(input.context == output.context && input.context == this)) {
126            throw new IllegalArgumentException("both input and output must both belong to this ONNXContext");
127        }
128        OnnxMl.NodeProto idNode = ONNXOperators.IDENTITY.build(this, input.getReference(), output.getReference());
129        protoBuilder.addNode(idNode);
130        return output;
131    }
132
133    /**
134     * Creates an input node for this ONNXContext, with the given name, of dimension
135     * [batch_size, {@code featureDimension}], and of type float32.
136     * @param name The name for this input node.
137     * @param featureDimension the second dimension of this input node.
138     * @return An {@link ONNXPlaceholder} instance representing this input node.
139     */
140    public ONNXPlaceholder floatInput(String name, int featureDimension) {
141        OnnxMl.TypeProto inputType = ONNXUtils.buildTensorTypeNode(new ONNXShape(new long[]{-1, featureDimension}, new String[]{"batch", null}), OnnxMl.TensorProto.DataType.FLOAT);
142        OnnxMl.ValueInfoProto inputValue = OnnxMl.ValueInfoProto.newBuilder()
143                .setType(inputType)
144                .setName(name).build();
145        protoBuilder.addInput(inputValue);
146        return new ONNXPlaceholder(this, inputValue, name);
147    }
148
149    /**
150     * Creates an input node for this ONNXContext, with the name "input", of dimension
151     * [batch_size, {@code featureDimension}], and of type float32.
152     * @param featureDimension the second dimension of this input node.
153     * @return An {@link ONNXPlaceholder} instance representing this input node.
154     */
155    public ONNXPlaceholder floatInput(int featureDimension) {
156        return floatInput("input", featureDimension);
157    }
158
159    /**
160     * Creates an output node for this ONNXContext, with the given name, of dimension
161     * [batch_size, {@code outputDimension}], and of type float32.
162     * @param name the name for this output node.
163     * @param outputDimension The second dimension of this output node.
164     * @return An {@link ONNXPlaceholder} instance representing this output node.
165     */
166    public ONNXPlaceholder floatOutput(String name, int outputDimension) {
167        OnnxMl.TypeProto outputType = ONNXUtils.buildTensorTypeNode(new ONNXShape(new long[]{-1,outputDimension}, new String[]{"batch",null}), OnnxMl.TensorProto.DataType.FLOAT);
168        OnnxMl.ValueInfoProto outputValueProto = OnnxMl.ValueInfoProto.newBuilder()
169                .setType(outputType)
170                .setName(name).build();
171        protoBuilder.addOutput(outputValueProto);
172        return new ONNXPlaceholder(this, outputValueProto, name);
173    }
174
175    /**
176     * Creates an output node for this ONNXContext, with the name "output", of dimension
177     * [batch_size, {@code outputDimension}], and of type float32.
178     * @param outputDimension The second dimension of this output node.
179     * @return An {@link ONNXPlaceholder} instance representing this output node.
180     */
181    public ONNXPlaceholder floatOutput(int outputDimension) {
182        return floatOutput("output", outputDimension);
183    }
184
185    /**
186     * Creates a tensor for this ONNXContext, populated as {@link ONNXUtils#floatTensorBuilder(ONNXContext, String, List, Consumer)}.
187     * @param baseName The name for this tensor in the ONNX graph.
188     * @param dims The dimensions of this tensor.
189     * @param populate A function populating the {@link FloatBuffer} that backs this tensor.
190     * @return An {@link ONNXInitializer} instance representing this tensor.
191     */
192    public ONNXInitializer floatTensor(String baseName, List<Integer> dims, Consumer<FloatBuffer> populate) {
193        OnnxMl.TensorProto tens = ONNXUtils.floatTensorBuilder(this, baseName, dims, populate);
194        protoBuilder.addInitializer(tens);
195        return new ONNXInitializer(this, tens, baseName);
196    }
197
198    /**
199     * Creates a long tensor for this ONNXContext, populated according to parameters.
200     * @param baseName The name for this tensor in the ONNX graph.
201     * @param parameters The long[] to populate the tensor.
202     * @return An {@link ONNXInitializer} instance representing this tensor.
203     */
204    public ONNXInitializer array(String baseName, long[] parameters) {
205        OnnxMl.TensorProto tens = ONNXUtils.arrayBuilder(this, baseName, parameters);
206        protoBuilder.addInitializer(tens);
207        return new ONNXInitializer(this, tens, baseName);
208    }
209
210    /**
211     * Creates an int tensor for this ONNXContext, populated according to parameters.
212     * @param baseName The name for this tensor in the ONNX graph.
213     * @param parameters The int[] to populate the tensor.
214     * @return An {@link ONNXInitializer} instance representing this tensor.
215     */
216    public ONNXInitializer array(String baseName, int[] parameters) {
217        OnnxMl.TensorProto tens = ONNXUtils.arrayBuilder(this, baseName, parameters);
218        protoBuilder.addInitializer(tens);
219        return new ONNXInitializer(this, tens, baseName);
220    }
221
222    /**
223     * Creates a float tensor for this ONNXContext, populated according to parameters.
224     * @param baseName The name for this tensor in the ONNX graph.
225     * @param parameters The float[] to populate the tensor.
226     * @return An {@link ONNXInitializer} instance representing this tensor.
227     */
228    public ONNXInitializer array(String baseName, float[] parameters) {
229        OnnxMl.TensorProto tens = ONNXUtils.arrayBuilder(this, baseName, parameters);
230        protoBuilder.addInitializer(tens);
231        return new ONNXInitializer(this, tens, baseName);
232    }
233
234    /**
235     * Creates a tensor for this ONNXContext, populated according to parameters.
236     * @param baseName The name for this tensor in the ONNX graph.
237     * @param parameters The double[] to populate the tensor.
238     * @param downcast Whether to downcast {@code parameters} to float32 in the ONNX graph.
239     * @return An {@link ONNXInitializer} instance representing this tensor.
240     */
241    public ONNXInitializer array(String baseName, double[] parameters, boolean downcast) {
242        OnnxMl.TensorProto tens = ONNXUtils.arrayBuilder(this, baseName, parameters, downcast);
243        protoBuilder.addInitializer(tens);
244        return new ONNXInitializer(this, tens, baseName);
245    }
246
247    /**
248     * Creates a float tensor for this ONNXContext, populated according to parameters.
249     * <p>
250     * As with {@link ONNXUtils#arrayBuilder(ONNXContext, String, double[], boolean)} the doubles will be downcast to
251     * float32.
252     * @param baseName The name for this tensor in the ONNX graph.
253     * @param parameters The double[] to populate the tensor.
254     * @return An {@link ONNXInitializer} instance representing this tensor.
255     */
256    public ONNXInitializer array(String baseName, double[] parameters) {
257        return array(baseName, parameters, true);
258    }
259
260    /**
261     * Creates a float scalar constant for this ONNXContext.
262     * @param baseName The name for this constant in the ONNX graph.
263     * @param value The float to populate the constant.
264     * @return An {@link ONNXInitializer} instance representing this tensor.
265     */
266    public ONNXInitializer constant(String baseName, float value) {
267        OnnxMl.TensorProto constant = OnnxMl.TensorProto.newBuilder()
268                .setName(generateUniqueName(baseName))
269                .setDataType(OnnxMl.TensorProto.DataType.FLOAT.getNumber())
270                .addFloatData(value)
271                .build();
272        protoBuilder.addInitializer(constant);
273        return new ONNXInitializer(this, constant, baseName);
274    }
275
276    /**
277     * Creates a long scalar constant for this ONNXContext.
278     * @param baseName The name for this constant in the ONNX graph.
279     * @param value The long to populate the constant.
280     * @return An {@link ONNXInitializer} instance representing this tensor.
281     */
282    public ONNXInitializer constant(String baseName, long value) {
283        OnnxMl.TensorProto constant = OnnxMl.TensorProto.newBuilder()
284                .setName(generateUniqueName(baseName))
285                .setDataType(OnnxMl.TensorProto.DataType.INT64.getNumber())
286                .addInt64Data(value)
287                .build();
288        protoBuilder.addInitializer(constant);
289        return new ONNXInitializer(this, constant, baseName);
290    }
291
292    /**
293     * Generates a unique name by appending the counter for that name.
294     * @param name The name.
295     * @return A unique version of that name.
296     */
297    String generateUniqueName(String name) {
298        long counter = nameMap.computeIfAbsent(name,k -> 0L);
299        String newName = name + "_" + counter;
300        nameMap.put(name,counter + 1);
301        return newName;
302    }
303
304    /**
305     * Sets the graph name.
306     * @param name The graph name.
307     */
308    public void setName(String name) {
309        protoBuilder.setName(name);
310    }
311
312    /**
313     * Builds the ONNX graph represented by this context.
314     * @return The ONNX graph proto.
315     */
316    public OnnxMl.GraphProto buildGraph() {
317        return protoBuilder.build();
318    }
319}