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}