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}