Class SameDiff

    • Field Detail

      • math

        public final SDMath math
        Op creator object for math operations
      • random

        public final SDRandom random
        Op creator object for random number generation operations
      • nn

        public final SDNN nn
        Op creator object for general neural network operations
      • cnn

        public final SDCNN cnn
        Op creator object for convolutional neural network operations
      • rnn

        public final SDRNN rnn
        Op creator object for recurrent neural network operations
      • loss

        public final SDLoss loss
        Op creator object for loss function operations
      • image

        public final SDImage image
        Op creator object for image operations
      • bitwise

        public final SDBitwise bitwise
        Op creator object for bitwise operations
      • linalg

        public final SDLinalg linalg
        Op creator object for linalg operations
    • Method Detail

      • math

        public SDMath math()
        Op creator object for math operations
      • random

        public SDRandom random()
        Op creator object for random number generation operations
      • nn

        public SDNN nn()
        Op creator object for general neural network operations
      • cnn

        public SDCNN cnn()
        Op creator object for convolutional neural network operations
      • rnn

        public SDRNN rnn()
        Op creator object for recurrent neural network operations
      • loss

        public SDLoss loss()
        Op creator object for loss function operations
      • image

        public SDImage image()
        Op creator object for image operations
      • bitwise

        public SDBitwise bitwise()
        Op creator object for bitwise operations
      • linalg

        public SDLinalg linalg()
        Op creator object for linalg operations
      • getInferenceFactory

        public static InferenceFactory getInferenceFactory()
        Get the inference factory
        Returns:
        the inference Factory
      • bindInferenceFactory

        public static boolean bindInferenceFactory​(InferenceFactory inferenceFactory)
        Bind the inferenceFactory.
        Parameters:
        inferenceFactory -
        Returns:
        true if the provided inferenceFactory is bound successfully
      • enableEagerMode

        public SameDiff enableEagerMode()
        Enables eager mode. Eager mode means variables will be computed as soon as they are created and stored in eagerArrays Note this is experimental and mainly meant for internal use at the moment. Eager mode is mainly useful in the context of model import for dynamically obtaining shapes and other information for use in a model import context.
        Returns:
      • disableEagerMode

        public SameDiff disableEagerMode()
        Disables eager mode. Eager mode means variables will be computed as soon as they are created and stored in eagerArrays Note this is experimental and mainly meant for internal use at the moment. Eager mode is mainly useful in the context of model import for dynamically obtaining shapes and other information for use in a model import context.
        Returns:
      • disableDebugging

        public SameDiff disableDebugging()
        Clears debugging state and disables debug mode.
      • enableDebugMode

        public SameDiff enableDebugMode()
        Enables tracing of graphs automatically.
      • setListeners

        public void setListeners​(Listener... listeners)
        Set the current SameDiff-wide Listener instances. Note that this will overwrite the current listener list. If you want to use additional listeners for a single operation, use the listener arguments in those methods (e.g. fit() and FitConfig.listeners(Listener...)).
        Parameters:
        listeners - Listeners
      • addListeners

        public void addListeners​(Listener... listeners)
        Add SameDiff-wide Listener instances. If you want to use additional listeners for a single operation, use the listener arguments in those methods (e.g. fit() and FitConfig.listeners(Listener...)).
        Parameters:
        listeners - Listeners
      • getListeners

        public List<Listener> getListeners()
        Gets the current SameDiff-wide listeners.
      • setArrayHolders

        public void setArrayHolders​(@NonNull
                                    @NonNull ArrayHolder variableArrayHolder,
                                    @NonNull
                                    @NonNull ArrayHolder constantArrayHolder,
                                    boolean initialize)
        Set the array holders for variable and constant arrays
        NOTE: this is usually reserved for developers and internal use, and should not be needed by almost all users
        See ArrayHolder for more details
        Parameters:
        variableArrayHolder - Array holder for variable arrays
        constantArrayHolder - Array holder for constant arrays
        initialize - If true: transfer any arrays from the current array holders to the new/specified ones
      • currentNameScope

        public String currentNameScope()
        Returns:
        The current name scope, if any (null otherwise). See withNameScope(String) for more details.
      • withNameScope

        public NameScope withNameScope​(String nameScope)
        Create a name scope. Name scopes append a prefix to the names of any variables and ops created while they are open.
          
          SameDiff sd = SameDiff.create();
          SDVariable x = sd.var("x", DataType.FLOAT, 5);
          SDVariable y;
          try(NameScope ns = sd.withNameScope("myScope"){
              y = sd.var("y", DataType.FLOAT, 5);
          }
          SDVariable z = sd.var("z", DataType.FLOAT, 5);
        
          String xName = x.name();      //RESULT: "x"
          String yName = y.name();      //RESULT: "myScope/y"
          String zName = z.name();      //RESULT: "z"
          
         

        Note that name scopes can also be nested:

          
          SameDiff sd = SameDiff.create();
          SDVariable x;
          try(NameScope ns = sd.withNameScope("first"){
              try(NameScope ns2 = sd.withNameScope("second"){
                  x = sd.var("x", DataType.FLOAT, 5);
              }
          }
          String xName = x.name();      //RESULT: "first/second/x"
          
         
        Parameters:
        nameScope - Name of the name scope to open/create
        Returns:
        The NameScope object
      • getOpsInScope

        public List<SameDiffOp> getOpsInScope​(NameScope scope)
        Gets all operations in a given name scope.
      • getVariablesInScope

        public List<SDVariable> getVariablesInScope​(NameScope scope)
        Gets all variables in a given name scope.
      • invokeGraphOn

        public SDVariable invokeGraphOn​(SameDiff sameDiff)
        Parameters:
        sameDiff -
        Returns:
      • opExists

        public boolean opExists​(String id)
        Returns true if the given function id exists
        Parameters:
        id - the function id to test for
        Returns:
        true if the function id exists, false otherwise
      • getVariableOutputOp

        public DifferentialFunction getVariableOutputOp​(String variableName)
        Get the differential function (if any) that this variable is the output for
        Parameters:
        variableName - Name of the variable
        Returns:
        The differential function that this variable is an output of, or null if it is not the output of a function
      • getOpById

        public DifferentialFunction getOpById​(@NonNull
                                              @NonNull String id)
        Get the function by the DifferentialFunction#getOwnName()
        Parameters:
        id - the id of the function
        Returns:
        the function for the given id if it exists
      • putOpForId

        public void putOpForId​(String id,
                               DifferentialFunction function)
        Put the function for the given id
        Parameters:
        id - the id of the function
        function - the function
      • getInputsForOp

        public String[] getInputsForOp​(@NonNull
                                       @NonNull DifferentialFunction function)
        Returns the name(s) of the inputs for the given function
        Parameters:
        function - the function to get the inputs for
        Returns:
        the input ids for a given function
      • getOutputsForOp

        public String[] getOutputsForOp​(DifferentialFunction function)
        Returns the name(s) of the outputs for the given function
        Parameters:
        function - the function to get the outputs for
        Returns:
        the outputs ids for a given function
      • getOutputVariablesForOp

        public SDVariable[] getOutputVariablesForOp​(DifferentialFunction function)
        Get the output variable(s) for the specified differential function
        Parameters:
        function - the function reference to get the output variable(s) for
        Returns:
        the output variables for the given function
      • getInputVariablesForOp

        public SDVariable[] getInputVariablesForOp​(DifferentialFunction function)
        Get the input variable(s) for the specified differential function
        Parameters:
        function - the function reference to get the input variable(s) for
        Returns:
        the input variables for the given function
      • arrayAlreadyExistsForVarName

        public boolean arrayAlreadyExistsForVarName​(String varName)
        Returns true if the given vertex id and INDArray already exist.
        Parameters:
        varName - the vertex id
        Returns:
        true if a vertex with the given INDArray exists, and it has an INDArray associated with it
      • setEagerArrForVarName

        public void setEagerArrForVarName​(@NonNull
                                          @NonNull String varName,
                                          INDArray arr)
        Sets an array for the given variable name in the eager session.
        Parameters:
        varName - the variable name to set for
      • getEagerArrForVarName

        public INDArray getEagerArrForVarName​(@NonNull
                                              @NonNull String varName)
        Note this is a special getter for the eager holder. Eager mode is meant to mainly be used in only very special cases right now. Normal array retrieval should be done by getArrForVarName(java.lang.String)
        Parameters:
        varName -
        Returns:
      • getArrForVarName

        public INDArray getArrForVarName​(@NonNull
                                         @NonNull String varName)
        Get an INDArray for a given vertex id, or null if none exists
        Parameters:
        varName - Variable name to get the array for
        Returns:
        Array, or null if none exists
      • associateArrayWithVariable

        public void associateArrayWithVariable​(INDArray arr,
                                               @NonNull
                                               @NonNull String variable)
        Associate the array with the given variable.
        Parameters:
        arr - the array to get the variable for
        variable - the name of the variable to associate the array with
      • associateArrayWithVariable

        public void associateArrayWithVariable​(INDArray arr,
                                               SDVariable variable)
        Associate the array with the given variable.
        Parameters:
        arr - the array to get the variable for
        variable - the variable to associate the array with
      • assignArray

        public void assignArray​(@NonNull
                                @NonNull INDArray arr,
                                @NonNull
                                @NonNull SDVariable variable)
        Update the constant or variable type SDVariable with the values from the specified array. Note that unlike associateArrayWithVariable(INDArray, String) this method will take the values from the argument array and assign it to the current array. The actual array (INDArray object) will not be stored or otherwise used within the SameDiff instance.
        Parameters:
        arr - Array values to set
        variable - Variable to update the array of. Must be CONSTANT or VARIBLE type SDVariable
      • putSubFunction

        public void putSubFunction​(String name,
                                   SameDiff nameSpace)
        Associate a SameDiff namespace as a sub function.
        Parameters:
        name - the opName of the function
        nameSpace - the namespace
      • variableMap

        public Map<String,​SDVariable> variableMap()
        Return a copy of the internal variable map
        Returns:
        Map of variables by name
      • definedFunctionNames

        public Collection<String> definedFunctionNames()
        The set of defined SameDiff function names. SameDiff function instances should not be confused with DifferentialFunction ops; an example of a SameDiff function instance is the gradient "grad" function
        Returns:
        Set of defined SameDiff function instance names
      • setupFunction

        public <X extends SDVariable> X setupFunction​(X function)
        Attempts to insert the DifferentialFunction reference in to this SameDiff instance. If the given array field with the given index already exists, it will do a reference check to ensure that the 2 array fields are the same. If not, an exception is thrown.
        If the instances are the same (by semantics, not reference) then it will just return the original instance. This is to ensure that instances that are created are unique and reference checked.
        Parameters:
        function - the array field to attempt to create
        Returns:
        Original instance
      • addOutgoingFor

        public void addOutgoingFor​(SDVariable[] variables,
                                   DifferentialFunction function)
        Adds outgoing arguments to the graph for the specified DifferentialFunction Also checks for input arguments and updates the graph adding an appropriate edge when the full graph is declared.
        Parameters:
        variables - Variables - arguments for the specified differential function
        function - Differential function
      • addOutgoingFor

        public void addOutgoingFor​(String[] varNames,
                                   DifferentialFunction function)
        Adds outgoing arguments to the graph for the specified DifferentialFunction Also checks for input arguments and updates the graph adding an appropriate edge when the full graph is declared.
        Parameters:
        varNames - Name of the variables that are outputs of the specified differential function
        function - Differential function
      • addArgumentInterceptor

        public void addArgumentInterceptor​(@NonNull
                                           @NonNull ArgumentInterceptor interceptor)
        Add a new argument interceptor to the interceptor stack

        For internal use only.

        When a op is added with arguments, most recent argument interceptor is called on it. If ops are added in that interceptor, the next most recent will be called on their args, and so on.

        Parameters:
        interceptor - the argument interceptor to add
      • removeArgumentInterceptor

        public void removeArgumentInterceptor()
        Remote the top (most recently added) argument interceptor

        For internal use only.

      • pauseArgumentInterceptor

        public void pauseArgumentInterceptor()
        Pause the top (most recently added) argument interceptor

        For internal use only.

      • pauseArgumentInterceptor

        public void pauseArgumentInterceptor​(@NonNull
                                             @NonNull ArgumentInterceptor interceptor)
        Pause the given argument interceptor

        For internal use only.

        Parameters:
        interceptor - the argument interceptor to pause
      • unpauseArgumentInterceptor

        public void unpauseArgumentInterceptor()
        Unpause the top (most recently added) argument interceptor

        For internal use only.

      • unpauseArgumentInterceptor

        public void unpauseArgumentInterceptor​(@NonNull
                                               @NonNull ArgumentInterceptor interceptor)
        Unpause the top given argument interceptor

        For internal use only.

        Parameters:
        interceptor - the argument interceptor to unpause
      • addArgsFor

        public void addArgsFor​(String[] variables,
                               DifferentialFunction function)
        Adds incoming arguments for the specified differential function to the graph
        Parameters:
        variables - Name of the variables that are arguments (inputs) to the specified function
        function - Function
      • addArgsFor

        public void addArgsFor​(SDVariable[] variables,
                               DifferentialFunction function)
        Adds incoming arguments for the specified differential function to the graph
        Parameters:
        variables - variables that are arguments (inputs) to the specified function
        function - Function
      • replaceArgFor

        public void replaceArgFor​(int i,
                                  @NonNull
                                  @NonNull SDVariable newArg,
                                  @NonNull
                                  @NonNull DifferentialFunction function)
        Replaces the argument at i with newArg for function Does not use (or remove) ArgumentInterceptor stuff
      • hasArgs

        public boolean hasArgs​(DifferentialFunction function)
        Returns true if this function already has defined arguments
        Parameters:
        function - the function to check
        Returns:
        true if the function has args, false otherwise
      • clearPlaceholders

        public void clearPlaceholders​(boolean allThreads)
        Clear the placeholder arrays from the SameDiff instance
        Parameters:
        allThreads - If true: clear the placeholders for all threads. False: clear only for current thread
      • clearOpInputs

        public void clearOpInputs()
        Clear the input arrays to each op. This is usually not required, under normal SameDiff use
      • ops

        public DifferentialFunction[] ops()
        Get an array of differential functions that have been defined for this SameDiff instance
        Returns:
        Array of differential functions
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • create

        public static SameDiff create()
        Create a new (empty) SameDiff instance without any functions or variables
        Returns:
        New SameDiff instance
      • dup

        public SameDiff dup()
        Clone/duplicate the SameDiff instance, including arrays etc. The returned SameDiff instance should have no shared state with the original instance
        Returns:
        The cloned SameDiff instance
      • numElements

        public long numElements()
        Count the number of elements in all arrays, according to SDVariable.getShape()
        Returns:
        Number of array elements for all variables
      • inputs

        public List<String> inputs()
        Returns the inputs (placeholders) for the SameDiff graph
        Returns:
        the inputs for this graph
      • outputs

        public List<String> outputs()
        Outputs are the names of the predictions of the network. Note that the outputs must be set using setOutputs(List) first
        Returns:
        The outputs of the SameDiff instance, or null if no outputs have been set
      • setOutputs

        public void setOutputs​(List<String> outputs)
        Set the outputs of the SameDiff instance. Outputs are the names of the variables that are the predictions of the neural network. Note that this is merely a convenience, and does not impact execution at all. Outputs can be retrieved (after setting here) using outputs()
        Parameters:
        outputs - Outputs to set. Must be valid variable names in this SameDiff instance
      • variables

        public List<SDVariable> variables()
        The list of all variables in the graph
        Returns:
        All variables in the graph
      • getLossVariables

        public List<String> getLossVariables()
        Get the names of variables (if any) that have been marked as loss variables to be minimized.
        Variables can be marked as loss variables in a few different ways:
        (a) Losses are automatically added when creating loss functions via SDBaseOps.sd
        (b) Via setLossVariables(String...), @link #addLossVariable(String)} or SDVariable.markAsLoss()
        (c) Via TrainingConfig#setLossVariables(List)
      • setLossVariables

        public void setLossVariables​(@NonNull
                                     @NonNull String... lossVariableNames)
        Clear/remove any existing loss variables, and set the loss variables to the specified variable names.
        See addLossVariable(String) for more details
        Parameters:
        lossVariableNames - Names of variables to be loss function variables
      • addLossVariable

        public void addLossVariable​(@NonNull
                                    @NonNull String variableName)
        Mark the specified variable as a loss function variable. This means that this variable will be minimized via backprop during training.
        This will add the variable as a loss to any others - i.e., if multiple variables are marked as losses, their values will be summed to give the total network loss.
        Note that only floating point (Float16/32/64) variables may be marked as a loss.
        Note also that only ARRAY type SDVariables can be marked as losses to be minimized. That is, we cannot mark the value of a constant, variable or placeholder to be minimized as doing so would not make sense.
      • setTrainingConfig

        public void setTrainingConfig​(TrainingConfig trainingConfig)
        Set the training configuration (TrainingConfig) for the SameDiff instance. A TrainingConfig must be set before the SameDiff instance can be trained via the fit methods
        Parameters:
        trainingConfig - Training configuration
      • fit

        public History fit​(@NonNull
                           @NonNull DataSet dataSet,
                           @NonNull
                           @NonNull Listener... listeners)
        Fit the SameDiff instance based on a single DataSet (i.e., a single minibatch for one iteration).
        This method can only be used for singe input, single output SameDiff instances as DataSet only supports a single input and a single output.
        Note that a TrainingConfig must be set via setTrainingConfig(TrainingConfig) before training can be performed.
        Parameters:
        dataSet - The DataSet (single minibatch) to peform training on
        listeners - Additional listeners to use during this operation
        Returns:
        a History object containing the history information for this training operation (evaluations specified in the TrainingConfig, loss values, and timing information).
      • fit

        public History fit​(@NonNull
                           @NonNull MultiDataSet dataSet,
                           @NonNull
                           @NonNull Listener... listeners)
        Fit the SameDiff instance based on a single MultiDataSet (i.e., a single minibatch for one iteration).
        Note that a TrainingConfig must be set via setTrainingConfig(TrainingConfig) before training can be performed.
        Parameters:
        dataSet - The MultiDataSet (single minibatch) to peform training on
        listeners - Additional listeners to use during this operation
        Returns:
        a History object containing the history information for this training operation (evaluations specified in the TrainingConfig, loss values, and timing information).
      • fit

        public History fit​(@NonNull
                           @NonNull DataSetIterator iter,
                           int numEpochs,
                           DataSetIterator validationIter,
                           int validationFrequency,
                           @NonNull
                           @NonNull Listener... listeners)
        Fit the SameDiff instance based on DataSetIterator for the specified number of epochs.
        This method can only be used for singe input, single output SameDiff instances as DataSet only supports a single input and a single output.
        Note that a TrainingConfig must be set via setTrainingConfig(TrainingConfig) before training can be performed.

        A special case of fit().

        Parameters:
        iter - The iterator to train the SameDiff instance with
        numEpochs - The number of epochs for training. Must be > 0
        validationIter - The DataSetIterator to use for validation (null to skip validation)
        validationFrequency - The frequency with which to run validation. 1 is every epoch, 2 is every other, etc.
        listeners - Additional listeners to use during this operation
        Returns:
        a History object containing the history information for this training operation (evaluations specified in the TrainingConfig, loss values, and timing information).
      • fit

        public History fit​(@NonNull
                           @NonNull DataSetIterator iter,
                           int numEpochs,
                           @NonNull
                           @NonNull Listener... listeners)
        See fit(DataSetIterator, int, DataSetIterator, int, Listener...), does not preform validation.

        A special case of fit().

        Parameters:
        iter - The iterator to train the SameDiff instance with
        numEpochs - The number of epochs for training. Must be > 0
        listeners - Additional listeners to use during this operation
        Returns:
        a History object containing the history information for this training operation (evaluations specified in the TrainingConfig, loss values, and timing information).
      • fit

        public History fit​(@NonNull
                           @NonNull MultiDataSetIterator iter,
                           int numEpochs,
                           MultiDataSetIterator validationIter,
                           int validationFrequency,
                           @NonNull
                           @NonNull Listener... listeners)
        Fit the SameDiff instance based on MultiDataSetIterator for the specified number of epochs.
        This method can both singe input, single output and multi-input, multi-output SameDiff instances
        Note that a TrainingConfig must be set via setTrainingConfig(TrainingConfig) before training can be performed.

        A special case of fit().

        Parameters:
        iter - The iterator to train the SameDiff instance with
        numEpochs - The number of epochs for training. Must be > 0
        validationIter - The MultiDataSetIterator to use for validation (null to skip validation)
        validationFrequency - The frequency with which to run validation. 1 is every epoch, 2 is every other, etc.
        listeners - Additional listeners to use during this operation
        Returns:
        a History object containing the history information for this training operation (evaluations specified in the TrainingConfig, loss values, and timing information).
      • fit

        public FitConfig fit()
        Set up for a fit operation using FitConfig.

        Supports the setting of training data (MultiDataSetIterator or DataSetIterator), number of epochs, validation data (MultiDataSetIterator or DataSetIterator), validation frequency, and additional listeners.

        Example: train on data for 5 epochs, validating on valData every 2nd epoch

             
             SameDiff sd = ...;
             MultiDataSet data = ...;
             MultiDataSet valData = ...;
        
             History hist = sd.fit()
                 .train(data, 5)
                 .validate(valData, 2)
                 .exec();
             
         
      • calcRegularizationScore

        public double calcRegularizationScore()
        Calculate the regularization (L1, L2 and/or WeightDecay) component of the loss function for the current parameters.. Note that the training configuration must be set (via setTrainingConfig(TrainingConfig)) before this method can be called
        Returns:
        The regularization component of the score/loss function
      • initializeTraining

        protected void initializeTraining()
        Perform setup for training. Does the following: 1. Infer the set of trainable parameters - unless specified manually by the user 2. Set up the updaters
      • evaluate

        public void evaluate​(@NonNull
                             @NonNull DataSetIterator iterator,
                             @NonNull
                             @NonNull String outputVariable,
                             @NonNull
                             @NonNull List<Listener> listeners,
                             @NonNull
                             @NonNull IEvaluation... evaluations)
        Evaluate the performance of a single variable's prediction.
        For example, if the variable to evaluatate was called "softmax" you would use:
         Evaluation e = new Evaluation();
         sameDiff.evaluate(iterator, "softmax", e);
         

        A special case of evaluate().

        Parameters:
        iterator - Iterator as source of data to evaluate
        outputVariable - The variable to evaluate
        listeners - Additional listeners to use during this operation.
        evaluations - The evaluations to perform
      • evaluate

        public void evaluate​(@NonNull
                             @NonNull MultiDataSetIterator iterator,
                             @NonNull
                             @NonNull String outputVariable,
                             int labelIndex,
                             @NonNull
                             @NonNull List<Listener> listeners,
                             @NonNull
                             @NonNull IEvaluation... evaluations)
        Evaluate the performance of a single variable's prediction.
        For example, if the variable to evaluatate was called "softmax" you would use:
         Evaluation e = new Evaluation();
         sameDiff.evaluate(iterator, "softmax", e);
         

        A special case of evaluate().

        Parameters:
        iterator - Iterator as source of data to evaluate
        outputVariable - The variable to evaluate
        labelIndex - The index of the target variable's labels in the iterator
        listeners - Additional listeners to use during this operation.
        evaluations - The evaluations to perform
      • evaluate

        public void evaluate​(MultiDataSetIterator iterator,
                             Map<String,​List<IEvaluation>> variableEvals,
                             Map<String,​Integer> predictionLabelMapping,
                             Listener... listeners)
        Perform evaluation using classes such as Evaluation for classifier outputs and RegressionEvaluation for regression outputs.

        Example: classifier evaluation
        Predictions variable name: "softmaxOutput"
        Evaluations to perform: Evaluation
        Data: single input, single output MultiDataSets
        Code:
         
         MultiDataSetIterator data = ...
         Map<String,List<IEvaluation>> evals = Collections.singletonMap("softmaxOutput",Collections.singletonList(new Evaluation()));
         Map<String,Integer> labelMapping = Collections.singletonMap("softmaxOutput",0);  //Compare: "softmaxOutput" vs. MultiDataSet.getLabels(0)
         
         

        A special case of evaluate().

        Parameters:
        iterator - The iterator - the source of the data for evaluation
        variableEvals - The evaluations to perform. Key: the name of the variable. Value: the evaluations to perform
        predictionLabelMapping - The output/label mapping. Key: the name of the variable.
        listeners - Additional listeners to use during this operation.
      • evaluate

        public EvaluationConfig evaluate()
        Set up for a evaluation operation using EvaluationConfig.

        Supports the setting of the data (MultiDataSetIterator or DataSetIterator), adding evaluations for variables (with optional label index setting), setting label indices, and setting additional listeners. Does not require setting label indices when using a DataSetIterator.

        Also supports using SDVariable instances instead of variable names.

        Example: evaluate "pred" with Evaluation and ROC, using label 0.

              
             SameDiff sd = ...;
             MultiDataSetIterator data = ...;
        
             EvaluationRecord results = sd.evaluate()
                 .data(data)
                 .evaluate("pred", 0, new Evaluation(), new ROC()),
                 .exec();
              
          
        Example: evaluate "pred" with Evaluation, using the only label from a DataSetIterator.
              
             SameDiff sd = ...;
             DataSetIterator singleData = ...;
        
             EvaluationRecord results = sd.evaluate()
                 .data(singleData)
                 .evaluate("pred", new Evaluation()),
                 .exec();
              
          
      • output

        public Map<String,​INDArray> output​(@NonNull
                                                 @NonNull DataSet dataSet,
                                                 @NonNull
                                                 @NonNull String... outputs)
        Do a single batch inference on a network with a single input.
        For example, if the variable to infer was called "softmax" you would use:
         
         sameDiff.output(iterator, "softmax");
         
        Parameters:
        dataSet - The data to evaluate
        outputs - The variables to evaluate
      • output

        public Map<String,​INDArray> output​(@NonNull
                                                 @NonNull MultiDataSet dataSet,
                                                 @NonNull
                                                 @NonNull String... outputs)
        Do a single batch inference on a network.
        For example, if the variable to infer was called "softmax" you would use:
         
         sameDiff.output(iterator, "softmax");
         
        Parameters:
        dataSet - The data to evaluate
        outputs - The variables to evaluate
      • output

        public Map<String,​INDArray> output​(@NonNull
                                                 @NonNull DataSetIterator iterator,
                                                 @NonNull
                                                 @NonNull List<Listener> listeners,
                                                 @NonNull
                                                 @NonNull String... outputs)
        Do inference on a network with a single input.
        For example, if the variable to infer was called "softmax" you would use:
         
         sameDiff.output(iterator, "softmax");
         

        Uses concatenation on the outputs of outputBatches(DataSetIterator, String...) which may cause issues with some inputs. RNNs with variable time series length and CNNs with variable image sizes will most likely have issues.

        Special case of output().

        Parameters:
        iterator - Iterator as source of data to evaluate
        listeners - Additional listeners to use during this operation.
        outputs - The variables to evaluate
      • output

        public Map<String,​INDArray> output​(@NonNull
                                                 @NonNull MultiDataSetIterator iterator,
                                                 @NonNull
                                                 @NonNull List<Listener> listeners,
                                                 @NonNull
                                                 @NonNull String... outputs)
        Perform inference.

        Example: classifier inference
        Predictions variable name: "softmaxOutput"
        Evaluations to perform: Evaluation
        Data: single output MultiDataSets
        Code:
         
         MultiDataSetIterator data = ...
         sameDiff.output(iterator, "softmaxOutput);
         
         

        Special case of output().

        Parameters:
        iterator - The iterator - the source of the data for inference
        listeners - Additional listeners to use during this operation.
        outputs - The set of outputs to report. If null, defaults to all outputs of this SameDiff.
      • outputBatches

        public List<Map<String,​INDArray>> outputBatches​(MultiDataSetIterator iterator,
                                                              List<Listener> listeners,
                                                              String... outputs)
        Perform inference.

        Example: classifier inference
        Predictions variable name: "softmaxOutput"
        Evaluations to perform: Evaluation
        Data: single output MultiDataSets
        Code:
         
         MultiDataSetIterator data = ...
         sameDiff.output(iterator, "softmaxOutput);
         
         

        Uses concatenation on the outputs of outputBatches(MultiDataSetIterator, List, String...) which may cause issues with some inputs. RNNs with variable time series length and CNNs with variable image sizes will most likely have issues.

        Special case of output().

        Parameters:
        iterator - The iterator - the source of the data for inference
        listeners - Additional listeners to use during this operation.
        outputs - The set of outputs to report. If null, defaults to all outputs of this SameDiff.
      • output

        public OutputConfig output()
        Set up for an inference operation using OutputConfig. Supports the setting of variables to output, the input data (MultiDataSetIterator or DataSetIterator), and additional listeners. Has exec methods to get results in batches or concatenated, or to get results when there is only a single output (again in batches or concatenated).

        Also supports using SDVariable instances instead of variable names.

        Example: get the output of pred, with batches concatenated together

             
             SameDiff sd = ...;
             MultiDataSet data = ...;
        
             INDArray out = sd.output()
                 .data(data)
                 .output("pred")
                 .outputSingle();
             
         
      • batchOutput

        public BatchOutputConfig batchOutput()
        Set up for a single batch inference operation using OutputConfig. Supports the setting of placeholder inputs, outputs, and additional listeners. Has exec methods to get the single output if only one is requested, or all requested outputs.

        Also supports using SDVariable instances instead of variable names.

        Example: get the value of "out" with placeholders x and y

             
             SameDiff sd = ...;
             INDArray xValue = ...;
             INDArray yValue = ...;
             SDVariable y = ...;
        
             INDArray outValue = sd.batchOutput()
                 .output("out")
                 .input("x", xValue)
                 .input(y, yValue)
                 .outputSingle();
             
         
      • output

        public Map<String,​INDArray> output​(Map<String,​INDArray> placeholders,
                                                 List<Listener> listeners,
                                                 String... outputs)
        Do inference for the given variables for a single batch.

        Special case of batchOutput().

        Parameters:
        placeholders - The values to use for placeholders.
        listeners - Additional listeners to use during this operation.
        outputs - The variables to output and return.
      • output

        public ExecutionResult output​(Map<String,​INDArray> placeholders,
                                      Map<String,​SDValue> sequencePlaceHolders,
                                      List<Listener> listeners,
                                      String... outputs)
        Do inference for the given variables for a single batch.

        Special case of batchOutput().

        Parameters:
        placeholders - The values to use for placeholders.
        sequencePlaceHolders - the placeholders involving an array of arrays
        listeners - Additional listeners to use during this operation.
        outputs - The variables to output and return.
      • one

        public SDVariable one​(String name,
                              DataType dataType,
                              int... shape)
        Create a new variable with the specified shape, with all values initialized to 1.0. Creates a constant - i.e., CONSTANT type SDVariable.
        Parameters:
        name - the name of the variable to create
        shape - the shape of the array to be created
        Returns:
        the created variable
      • one

        public SDVariable one​(String name,
                              DataType dataType,
                              long... shape)
        Create a new variable with the specified shape, with all values initialized to 1.0. Creates a constant - i.e., CONSTANT type SDVariable.
        Parameters:
        name - the name of the variable to create
        shape - the shape of the array to be created
        Returns:
        the created variable
      • zero

        public SDVariable zero​(String name,
                               DataType dataType,
                               long... shape)
        Create a new variable with the specified shape, with all values initialized to 0. Creates a constant - i.e., CONSTANT type SDVariable.
        Parameters:
        name - the name of the variable to create
        shape - the shape of the array to be created
        Returns:
        the created variable
      • zero

        public SDVariable zero​(String name,
                               DataType dataType,
                               int... shape)
        Create a new variable with the specified shape, with all values initialized to 0. Creates a constant - i.e., CONSTANT type SDVariable.
        Parameters:
        name - the name of the variable to create
        shape - the shape of the array to be created
        Returns:
        the created variable
      • constant

        public SDVariable constant​(@NonNull
                                   @NonNull INDArray constant)
        Create an SDVariable with a fixed/constant value, with a generated name
        Constants are not modified by training/backprop. See VariableType for more details.
        Parameters:
        constant - Value for the constant SDVariable
        Returns:
        The created variable
      • constant

        public SDVariable constant​(String name,
                                   @NonNull
                                   @NonNull INDArray constant)
        Create an SDVariable with a fixed/constant value
        Constants are not modified by training/backprop. See VariableType for more details.
        Parameters:
        name - Name of the constant SDVariable
        constant - Value for the constant SDVariable
        Returns:
        The created variable
      • placeHolder

        public SDVariable placeHolder​(@NonNull
                                      @NonNull String name,
                                      DataType dataType,
                                      long... shape)
        Create a a placeholder variable. Placeholders are variables that expect an array to be provided during training and inference.
        For example, the SDVariables for your input/features and labels should be placeholders.
        See also: VariableType
        Parameters:
        name - the name of the variable
        dataType - Data type of the new placeholder
        shape - the shape of the variable if any
        Returns:
        SDVariable placeholder
      • var

        public SDVariable var​(@NonNull
                              @NonNull String name,
                              @NonNull
                              @NonNull WeightInitScheme weightInitScheme,
                              @NonNull
                              @NonNull DataType dataType,
                              @NonNull
                              @lombok.NonNull long... shape)
        Variable initialization with a specified WeightInitScheme This method creates VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        name - the name of the variable
        shape - the shape of the array to be created
        weightInitScheme - the weight initialization scheme
        Returns:
        the created variable
      • var

        public SDVariable var​(@NonNull
                              @NonNull String name,
                              @NonNull
                              @NonNull VariableType variableType,
                              WeightInitScheme weightInitScheme,
                              DataType dataType,
                              long... shape)
        Variable initialization with a specified WeightInitScheme This method creates VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        name - the name of the variable
        variableType - the SameDiff variable type of the variable (e.g. CONSTANT, PLACEHOLDER, etc.)
        weightInitScheme - the weight initialization scheme
        dataType - the data type of the variable (float, int, etc)
        shape - the shape of the array to be created
        Returns:
        the created variable
      • var

        public SDVariable var​(@NonNull
                              @NonNull String name,
                              @NonNull
                              @NonNull LongShapeDescriptor shape,
                              WeightInitScheme weightInitScheme)
        Creates a SDVariable with the given shape and name
        The underlying array will be initialized using the specified weight initilization scheme
        This is a VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        name - the name of the variable
        shape - the shape of the variable
        weightInitScheme - Weight initialization scheme to use to initialize the underlying array
        Returns:
        the created variable
      • var

        public SDVariable var​(String name,
                              DataType dataType,
                              long... shape)
        Creates a SDVariable with the given shape and name
        Any array will be generated with all zeros for the values
        This is a VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        name - the name of the variable
        shape - the shape of the variable
        Returns:
        the created variable
      • var

        public SDVariable var​(String name,
                              LongShapeDescriptor shapeDesc)
        Creates a SDVariable with the given shape and name
        Any array will be generated with all zeros for the values
        This is a VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        name - the name of the variable
        shapeDesc - the shape of the variable
        Returns:
        the created variable
      • var

        public SDVariable var​(String name,
                              int... shape)
        Creates a SDVariable with the given shape and name
        Any array will be generated with all zeros for the values. Data type will be given by Nd4j.defaultFloatingPointType()
        This is a VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        name - the name of the variable
        shape - the shape of the variable
        Returns:
        the created variable
      • var

        public SDVariable var​(String name,
                              long... shape)
        Creates a SDVariable with the given shape and name
        Any array will be generated with all zeros for the values. Data type will be given by Nd4j.defaultFloatingPointType()
        This is a VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        name - the name of the variable
        shape - the shape of the variable
        Returns:
        the created variable
      • var

        public SDVariable var​(@NonNull
                              @NonNull String name,
                              @NonNull
                              @NonNull WeightInitScheme weightInitScheme,
                              @NonNull
                              @lombok.NonNull long... shape)
        Variable initialization with a specified WeightInitScheme. Data type will be given by Nd4j.defaultFloatingPointType()
        This method creates VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        name - the name of the variable
        shape - the shape of the array to be created
        weightInitScheme - the weight initialization scheme
        Returns:
        the created variable
      • var

        public SDVariable var​(String name,
                              DataType dataType,
                              int... shape)
        Creates a SDVariable with the given shape and name
        Any array will be generated with all zeros for the values
        Parameters:
        name - the name of the variable
        shape - the shape of the variable
        Returns:
        the created variable
      • var

        public SDVariable var​(@NonNull
                              @NonNull SDVariable v)
        Initialize a SDVariable reference tying this variable to this samediff instance.

        NDArraySupplierInitScheme is used to ensure that if the array is allocated anywhere and SameDiff instance to exist as a copy of the variable.

        Parameters:
        v - Variable
        Returns:
      • createSequence

        public SDVariable createSequence​(String name,
                                         INDArray[] arrays)
        Creates a sequence variable based on the input arrays. Note that all input arrays must be the same data type.
        Parameters:
        name - the name of the variable
        arrays - the arrays
        Returns:
        the new sequence variable
      • removeItemFromSequence

        public void removeItemFromSequence​(String varName,
                                           int indexOfItem)
        Removes the item from the sequence for name at the specified index.
        Parameters:
        varName - the variable name of the sequence
        indexOfItem - the index to insert the item at. Index should be -n to n- 1 where is the length of the sequence atIndex is < 0, the index will be treated as counting backwards from the end.
      • addItemToSequence

        public void addItemToSequence​(String varName,
                                      INDArray item,
                                      int atIndex)
        Add an item to the sequence
        Parameters:
        varName - the variable name to
        item - the item to add
        atIndex - the index to insert the item at. Index should be -n to n- 1 where is the length of the sequence atIndex is < 0, the index will be treated as counting backwards from the end.
      • sequenceLength

        public long sequenceLength​(String varName)
        Returns the length of the sequence for the given variable name
        Parameters:
        varName - the name of the sequence to get the length
        Returns:
        the length of the sequence for the given variable name
      • setItemForSequenceAtIndex

        public void setItemForSequenceAtIndex​(String varName,
                                              INDArray item,
                                              int index)
        Sets the item at the particular index in the sequence to the passed in item.
        Parameters:
        varName - the name of the sequence
        item - the item to set
        index - the index to insert the item at. Index should be -n to n- 1 where is the length of the sequence index is < 0, the index will be treated as counting backwards from the end.
      • itemForSequence

        public INDArray itemForSequence​(String varName,
                                        int atIndex)
        Get the INDArray at a particular sequence.
        Parameters:
        varName - the name of the variable to get the sequence for
        atIndex - the index to get the item for
        Returns:
        the array at the sequence
      • var

        public SDVariable var​(DataType dataType,
                              int... shape)
        Creates a SDVariable with the specified shape and a generated name
        Any array will be generated with all zeros for the values
        This method creates a VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        shape - the shape of the variable
        Returns:
        the created variable
      • var

        public SDVariable var​(DataType dataType,
                              long... shape)
        Creates a SDVariable with the specified shape and a generated name
        Any array will be generated with all zeros for the values
        This method creates a VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        shape - the shape of the variable
        Returns:
        the created variable
      • var

        public SDVariable var​(WeightInitScheme weightInitScheme,
                              DataType dataType,
                              long... shape)
        Creates a SDVariable with the specified shape and a generated name. The associated array will then be generated using the specified weight initialization scheme
        Parameters:
        weightInitScheme - The weight initialization scheme to use when generating an INDArray
        shape - the shape of the variable
        Returns:
        the created variable
      • var

        public SDVariable var​(INDArray arr)
        Create an SDVariable with a generated name, and assocate the specified array with it.
        This is a VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        arr - Array to associate with the new variable
        Returns:
        New SDVariable
        See Also:
        var(String, INDArray)
      • var

        public SDVariable var​(String name,
                              @NonNull
                              @NonNull INDArray arr)
        Create an SDVariable with the specified name, and associate the specified array with it
        This is a VARIABLE type SDVariable - i.e., must be floating point, and is a trainable parameter. See VariableType for more details.
        Parameters:
        arr - Array to associate with the new variable
        Returns:
        New SDVariable with the specified name and array
      • convertToConstant

        public SDVariable convertToConstant​(@NonNull
                                            @NonNull SDVariable variable)
        Convert the specified variable to a constant. This is equivalent to "freezing" a variable so that it's value won't be changed by further training.
        This can only be done for variables and placeholders, not ARRAY type variables (which are usually network activations). As a constant, this variable will no longer be modified by any subsequent training.
        See also: VariableType
        Parameters:
        variable - Variable to convert to a constant
        Returns:
        The (now constant) SDVariable
      • convertToConstants

        public void convertToConstants​(List<SDVariable> variables)
        Convert all of the specified variables to constants. This is equivalent to "freezing" the variables so that their values won't be changed by further training.
        This can only be done for variables and placeholders, not ARRAY type variables (which are usually network activations). As constants, these variables will no longer be modified by any subsequent training.
        See also: VariableType
        Parameters:
        variables - Variables to convert to constants
      • convertToVariable

        public SDVariable convertToVariable​(@NonNull
                                            @NonNull SDVariable constant)
        Convert the specified variable to a VARIABLE type SDVariable.
        This can only be done for constants and placeholders, not ARRAY type variables (which are usually network activations). As a variable, this variable will modified during any subsequent training.
        See also: VariableType
        Returns:
        This variable (now a variable type SDVariable)
      • convertToVariables

        public void convertToVariables​(@NonNull
                                       @NonNull List<SDVariable> constants)
        Convert the specified variables to VARIABLE type SDVariables.
        This can only be done for constants and placeholders, not ARRAY type variables (which are usually network activations). As variables, this variable will modified during any subsequent training.
        See also: VariableType
      • convertDataTypes

        public void convertDataTypes​(@NonNull
                                     @NonNull Map<String,​DataType> dataTypeMap)
        Convert the datatypes of the specified constants, placeholders and variables.
        After conversion, the downstream datatypes are changed. For example, z(float) = x(float)+y(float), changing both x and y to double results in z(double) = x(double)+y(double) without doing anything to change z's datatype directly (z datatype is inferred from x + y + add op).
        ARRAY type SDVariables cannot be converted directly, as their datatypes are determined by the function + input datatypes. Note that this method should be used with caution: incorrect datatype modifications may leave your network in an incorrect state. For example, op(x(float),y(float)) -> op(x(double),y(float)) may not be supported by all ops.
        Parameters:
        dataTypeMap - Map of SDVariables to change the datatype for. Key = SDVariable name, Value = new datatype
      • renameVariable

        public void renameVariable​(SameDiffOp opToReName,
                                   String from,
                                   String to)
        Rename the specified variable to the new name. Note here we also specify the op. Sometimes, ops have multiple outputs and after the first rename of the variable we lose the reference to the correct op to modify.
        Parameters:
        opToReName - the op to rename
        from - The variable to rename - this variable must exist
        to - The new name for the variable - no variable with this name must already exist
      • renameVariable

        public void renameVariable​(String from,
                                   String to)
        Rename the specified variable to the new name.
        Parameters:
        from - The variable to rename - this variable must exist
        to - The new name for the variable - no variable with this name must already exist
      • removeArgFromOp

        public void removeArgFromOp​(String varName,
                                    DifferentialFunction function)
        Remove an argument for a function. Note that if this function does not contain the argument, it will just be a no op.
        Parameters:
        varName - the variable name to remove
        function - the function to remove the argument from
      • getVariable

        public SDVariable getVariable​(String name)
        Get the variable based on the opName
        Parameters:
        name - the opName of the variable
        Returns:
        the variable instance if there is one
      • hasVariable

        public boolean hasVariable​(String name)
      • getGradForVariable

        public SDVariable getGradForVariable​(String varName)
        Get the gradient for the variable with the specified name.
        The gradient variable is the variable that represents the derivative of the loss function with respect to the output of this variable. I.e., if this variable is X and loss function is L, then gradient() returns the variable representing dL/dX
        Note that only floating point variables can have gradients.
        Note also that a gradient may not yet be defined, and/or if no loss function variables have been set.
        You can set the loss function variables using setLossVariables(String...) and then create the gradient functions using createGradFunction(). Alternatively, the gradient function will be created automatically when training is performed.
        Parameters:
        varName - the vertex id
        Returns:
        the gradient for this variable or null
      • variableHasGradient

        public boolean variableHasGradient​(String varName)
        Determine if the specified variable has a gradient with respect to the current loss. Note that: (a) Non-floating-point variables (integer, string, etc) will never have gradients
        (b) This method will return false if no gradient function has been created yet. See createGradFunction() and setLossVariables(String...)
        (c) Floating point variables may not have any gradient if the specified loss variables does not depend on the specified variable at all. In this case, "no gradient" for floating point is equivalent to "always 0"
        Parameters:
        varName - Name of the variable to check the existence of a gradient variable for
        Returns:
        True if a gradient variable exists for the specified variable, for the current loss
      • setGradientForVariableName

        public void setGradientForVariableName​(String variableName,
                                               SDVariable variable)
        Assign a SDVariable to represent the gradient of the SDVariable with the specified name
        Parameters:
        variableName - the variable name to assign the gradient variable for
        variable - the gradient variable
      • grad

        public SDVariable grad​(String varName)
        Get the gradient for the variable with the specified variable name. All gradient functions are obtained from the results of the execBackwards call.
        Parameters:
        varName - the variable name to get the gradient variable for.
        Returns:
        The gradient variable for the specified variable
      • scalar

        public SDVariable scalar​(String name,
                                 double value)
        Create a new double scalar (rank 0) SDVariable with the specified value
        Parameters:
        name - Name of the SDVariable
        value - Value to initialize the variable with
        Returns:
        SDVariable
      • scalar

        public SDVariable scalar​(String name,
                                 float value)
        Create a new float scalar (rank 0) SDVariable with the specified value
        Parameters:
        name - Name of the SDVariable
        value - Value to initialize the variable with
        Returns:
        SDVariable
      • scalar

        public SDVariable scalar​(String name,
                                 int value)
        Create a new integer scalar (rank 0) SDVariable with the specified value
        Parameters:
        name - Name of the SDVariable
        value - Value to initialize the variable with
        Returns:
        SDVariable
      • scalar

        public SDVariable scalar​(String name,
                                 long value)
        Create a new long scalar (rank 0) SDVariable with the specified value
        Parameters:
        name - Name of the SDVariable
        value - Value to initialize the variable with
        Returns:
        SDVariable
      • scalar

        public SDVariable scalar​(String name,
                                 DataType dataType,
                                 Number value)
        Create a new scalar (rank 0) SDVariable with the specified value and datatype
        Parameters:
        name - Name of the SDVariable
        dataType - Data type of the scalar
        value - Value to initialize the variable with
        Returns:
        SDVariable
      • constant

        public SDVariable constant​(double value)
        Create a new double scalar constant (rank 0) with the specified value.
        Constants are not modified by training/backprop. See VariableType for more details.
        Parameters:
        value - Value to initialize the constant with
        Returns:
        SDVariable
      • constant

        public SDVariable constant​(String name,
                                   double value)
        Create a new double scalar constant (rank 0) with the specified value
        Parameters:
        name - Name of the SDVariable
        value - Value to initialize the constant with
        Returns:
        SDVariable
      • constant

        public SDVariable constant​(float value)
        Create a new float scalar constant (rank 0) with the specified value
        Constants are not modified by training/backprop. See VariableType for more details.
        Parameters:
        value - Value to initialize the constant with
        Returns:
        SDVariable
      • constant

        public SDVariable constant​(String name,
                                   float value)
        Create a new float scalar constant (rank 0) with the specified value
        Parameters:
        name - Name of the SDVariable
        value - Value to initialize the constant with
        Returns:
        SDVariable
      • constant

        public SDVariable constant​(int value)
        Create a new integer scalar constant (rank 0) with the specified value
        Parameters:
        value - Value to initialize the constant with
      • constant

        public SDVariable constant​(String name,
                                   int value)
        Create a new integer scalar constant (rank 0) with the specified value
        Parameters:
        name - Name of the SDVariable
        value - Value to initialize the constant with
        Returns:
        SDVariable
      • constant

        public SDVariable constant​(boolean value)
        Create a new long scalar constant (rank 0) with the specified value
        Parameters:
        value - Value to initialize the constant with
      • constant

        public SDVariable constant​(String name,
                                   boolean value)
        Create a new long scalar constant (rank 0) with the specified value
        Parameters:
        name - Name of the SDVariable
        value - Value to initialize the constant with
      • constant

        public SDVariable constant​(long value)
        Create a new long scalar constant (rank 0) with the specified value
        Parameters:
        value - Value to initialize the constant with
      • constant

        public SDVariable constant​(String name,
                                   long value)
        Create a new long scalar constant (rank 0) with the specified value
        Parameters:
        name - Name of the SDVariable
        value - Value to initialize the constant with
      • constant

        public SDVariable constant​(String name,
                                   DataType dataType,
                                   Number value)
        Create a new scalar constant (rank 0) with the specified value and datatype
        Parameters:
        name - Name of the SDVariable
        dataType - Data type of the scalar constant
        value - Value to initialize the constant with
      • addVariable

        public SDVariable addVariable​(SDVariable variable)
        Add the specified variable to this SameDiff instance
        Parameters:
        variable - Variable to add
      • generateOutputVariableForOp

        public SDVariable[] generateOutputVariableForOp​(DifferentialFunction function,
                                                        String baseName,
                                                        boolean isImport)
        Generate the variables based on the given input op and return the output variable names.
        Parameters:
        function - the function to generate the output variable names for
        Returns:
        the set of names generated for each output of the function.
      • generateOutputVariableForOp

        public SDVariable[] generateOutputVariableForOp​(DifferentialFunction function)
        Generate the variables based on the given input op and return the output variable names.
        Parameters:
        function - the function to generate the output variable names for
        Returns:
        the set of names generated for each output of the function.
      • getFunction

        public SameDiff getFunction​(String functionName)
        Get a SameDiff function instance given the name of the function
        Parameters:
        functionName - the name of the function
        Returns:
        the same diff function instance defined for the given name
      • tensorArray

        public TensorArray tensorArray​(SDVariable tensorArrayToAccess)
        Create a new TensorArray.
      • tensorArray

        public TensorArray tensorArray​(DataType dataType)
        Create a new TensorArray.
      • invokeFunctionOn

        public SDVariable invokeFunctionOn​(String functionName,
                                           SameDiff with)
        Parameters:
        functionName -
        with -
      • calculateGradients

        public Map<String,​INDArray> calculateGradients​(Map<String,​INDArray> placeholderVals,
                                                             @NonNull
                                                             @NonNull Collection<String> variables)
        Calculate and return the gradients for the specified variables
        Parameters:
        placeholderVals - Placeholders. May be null
        variables - Names of the variables that you want the gradient arrays for
        Returns:
        Gradients as a map, keyed by the variable name
      • calculateGradientsAndOutputs

        public OutAndGrad calculateGradientsAndOutputs​(Map<String,​INDArray> placeholderVals,
                                                       Collection<String> outputVars,
                                                       Collection<String> gradientVars)
        Calculate the activations and the gradients for the specified variables, in one execution call. This is equivalent to calling output(Map, List) and calculateGradients(Map, Collection), but is more efficient than calling both separately.
        Parameters:
        placeholderVals - Placeholders. May be null
        outputVars - Names of the variables that you want the activations/outputs for. May be null
        gradientVars - Names of the variables that you want the gradient arrays for. May be null
        Returns:
        Activations and gradients, keyed by variable name
      • hasGradientFunction

        public boolean hasGradientFunction()
        Returns true if the gradient function has been created - i.e., createGradFunction() or createGradFunction(String...) has been called at all
        Returns:
        True if gradient (backprop) function exists
      • createGradFunction

        public void createGradFunction()
        Create the gradient function (for calculating gradients via calculateGradients(Map, Collection)) if it is not already defined. Users do not usually need to call this function manually, as it is called as required in the aforementioned method.

        If the gradient function already exists, this method is a no-op.
        After this method returns, the SameDiff function instance for the gradient can be accessed using getFunction(String) with name "grad" as the argument.
        Note that the gradient array (after execBackwards has been called) can be accessed via SDVariable.gradient().getArr()
      • createGradFunction

        public void createGradFunction​(String... variablesRequiringGradients)
        As per createGradFunction(), but this method allows a set of variables requiring gradients to be specified. By default, only parameter gradients will be calculated; placeholder gradients may not be defined (unless they happen to be calculated in the same op as calculating a parameter gradient. This method allows you to override this behaviour by passing the name of the placeholder you want the gradients for. The specified gradient variables still need to be floating point variables.
        Parameters:
        variablesRequiringGradients - May be null. If non-null: the gradients for the variables with these names will be calculated and available after backprop has been done
      • bestGuessLossVariables

        protected List<String> bestGuessLossVariables()
        Try to infer the loss variable/s (usually loss variables). Note that this is not reliable in general.
      • isPlaceHolder

        public boolean isPlaceHolder​(String varName)
        Returns true if this vertex id is a placeholder variable or not
        A place holder variable is one where the array shape(s) are currently known and can't yet be calculated
        Parameters:
        varName - the vertex id to test
        Returns:
        True if the variable is a placeholder, false otherwise
      • isConstant

        public boolean isConstant​(String varName)
        Returns true if this vertex id is a constant variable or not
        A constant variable is one where the array's variable is predefined and can not be changed.
        Parameters:
        varName - the vertex id to test
        Returns:
        True if the variable is a placeholder, false otherwise
      • updateVariableNameAndReference

        public SDVariable updateVariableNameAndReference​(SDVariable varToUpdate,
                                                         String newVarName,
                                                         boolean exactName)
        Updates the variable name property on the passed in variable, the reference in samediff, and returns the variable.

        Note that if null for the new variable is passed in, it will just return the original input variable.

        Parameters:
        varToUpdate - the variable to update
        newVarName - the new variable name
        exactName - whether the variable name should be modified or remain exact. If the variable already exists and exact is required, an IllegalArgumentException will be thrown.
        Returns:
        the passed in variable
      • updateVariableNameAndReference

        public SDVariable updateVariableNameAndReference​(SameDiffOp opToRename,
                                                         SDVariable varToUpdate,
                                                         String newVarName,
                                                         boolean exactName)
        Updates the variable name property on the passed in variable, the reference in samediff, and returns the variable.

        Note that if null for the new variable is passed in, it will just return the original input variable.

        Parameters:
        opToRename - note we pass in the op here for times when an op may have multiple outputs when this is the case, we need to pass in the op to rename otherwise context gets lost and subsequent rename attempts will not operate on the op.
        varToUpdate - the variable to update
        newVarName - the new variable name
        exactName - whether the variable name should be modified or remain exact. If the variable already exists and exact is required, an IllegalArgumentException will be thrown.
        Returns:
        the passed in variable
      • updateVariableNameAndReference

        public SDVariable updateVariableNameAndReference​(SameDiffOp opToRename,
                                                         SDVariable varToUpdate,
                                                         String newVarName)
        Updates the variable name property on the passed in variable, the reference in samediff, and returns the variable.

        Note that if null for the new variable is passed in, it will just return the original input variable.

        Parameters:
        opToRename - note we pass in the op here for times when an op may have multiple outputs when this is the case, we need to pass in the op to rename otherwise context gets lost and subsequent rename attempts will not operate on the op.
        varToUpdate - the variable to update
        newVarName - the new variable name
        Returns:
        the passed in variable
      • updateVariableNameAndReference

        public SDVariable updateVariableNameAndReference​(SDVariable varToUpdate,
                                                         String newVarName)
        Updates the variable name property on the passed in variable, the reference in samediff, and returns the variable.

        Note that if null for the new variable is passed in, it will just return the original input variable.

        Parameters:
        varToUpdate - the variable to update
        newVarName - the new variable name
        Returns:
        the passed in variable
      • updateVariableNamesAndReferences

        public SDVariable[] updateVariableNamesAndReferences​(SDVariable[] variablesToUpdate,
                                                             String[] newVariableNames)
        Updates the variable name property on the passed in variables, its reference in samediff, and returns the variable.
        Parameters:
        variablesToUpdate - the variable to update
        newVariableNames - the new variable name
        Returns:
        the updated, passed in variables
      • associateSameDiffWithOpsAndVariables

        protected void associateSameDiffWithOpsAndVariables()
        Associate the current SameDiff instance with all ops and variables. This is necessary to ensure that when dealing with shared state (usually with a SameDiff function such as "grad" - the backward function) we have the correct SameDiff instance set for all ops/SDVariables.
        If this is not done, arrays and shapes could be fetched from the incorrect SameDiff instance for some methods
      • asFlatNode

        protected int asFlatNode​(String name,
                                 @NonNull
                                 @NonNull SameDiff scope,
                                 @NonNull
                                 @NonNull com.google.flatbuffers.FlatBufferBuilder bufferBuilder)
      • parseVariable

        public static Pair<String,​Integer> parseVariable​(@NonNull
                                                               @NonNull String varName)
        Note: INTENDED FOR DEVELOPER USE
        This method extract base variable name and output index (if exists) from raw variable name. I.e: - if variable name is "Unstack_2", result will be Pair("Unstack_2", 0) - if variable name is "Unstack_2:12", result will be Pair("Unstack_2", 12)
        Parameters:
        varName -
        Returns:
      • asFlatBuffers

        public ByteBuffer asFlatBuffers​(@NonNull
                                        @NonNull ExecutorConfiguration configuration,
                                        boolean includeUpdaterState)
        This method exports the current SameDiff instance into FlatBuffers format, returning the array ops and all arrays as a ByteBuffer containing the FlatBuffers format data
        Parameters:
        configuration - - ExecutorConfiguration to be embedded into serialized graph
        includeUpdaterState - If true: include the updater state (state for updaters such as Adam, Nesterov, AdaGrad etc)
        Returns:
        a ByteBuffer holding the exported FlatBuffers representation of the graph
      • asFlatBuffers

        public ByteBuffer asFlatBuffers​(long graphId,
                                        @NonNull
                                        @NonNull ExecutorConfiguration configuration,
                                        boolean includeUpdaterState)
        This method exports the current SameDiff instance into FlatBuffers format, returning the array ops and all arrays as a ByteBuffer containing the FlatBuffers format data
        Parameters:
        configuration - - ExecutorConfiguration to be embedded into serialized graph
        includeUpdaterState - If true: include the updater state (state for updaters such as Adam, Nesterov, AdaGrad etc)
        Returns:
        a ByteBuffer holding the exported FlatBuffers representation of the graph
      • asFlatGraph

        public FlatGraph asFlatGraph​(long graphId,
                                     ExecutorConfiguration configuration,
                                     boolean includeUpdaterState)
        This method returns FlatGraph structure
        Parameters:
        configuration -
        includeUpdaterState - If true: include the updater state (state for updaters such as Adam, Nesterov, AdaGrad etc)
        Returns:
      • asFlatBuffers

        public ByteBuffer asFlatBuffers​(boolean includeUpdaterState)
        This method exports the current SameDiff instance into FlatBuffers format, returning the array ops and all arrays as a ByteBuffer containing the FlatBuffers format data Uses the default ExecutorConfiguration with output mode as OutputMode.VARIABLE_SPACE, execution mode as ExecutionMode.SEQUENTIAL, with profiling disabled and gather timings enabled.
        Parameters:
        includeUpdaterState - If true: include the updater state (state for updaters such as Adam, Nesterov, AdaGrad etc)
        Returns:
        a ByteBuffer holding the exported FlatBuffers representation of the graph
      • save

        public void save​(@NonNull
                         @NonNull File file,
                         boolean saveUpdaterState)
        Save the SameDiff instance to a file. Files can be loaded using load(File, boolean)
        Parameters:
        file - File to save to
        saveUpdaterState - If true: save the updater state (arrays etc for Adam, Nesterov, RmsProp etc). If false: don't save the updater state. If you want to continue training after loading your model, this should be true, however may increase the file size significantly. If the network is to be used for inference only, set this to false to save space
      • save

        public void save​(@NonNull
                         @NonNull OutputStream outputStream,
                         boolean saveUpdater)
        As per save(File, boolean) but the serialized SameDiff instance is written to the output stream instead. Note that this temporarily saves to disk (using ND4JFileUtils.createTempFile(String, String) then copies all file bytes to the stream
        Parameters:
        outputStream - Stream to write the serialized SameDiff instance to
        saveUpdater - If true: save the updater state (arrays etc for Adam, Nesterov, RmsProp etc). If false: don't save the updater state. If you want to continue training after loading your model, this should be true, however may increase the file size significantly. If the network is to be used for inference only, set this to false to save space.
      • load

        public static SameDiff load​(@NonNull
                                    @NonNull File file,
                                    boolean loadUpdaterState)
        Load the SameDiff instance previously saved with save(File, boolean)
        Parameters:
        file - The file to load the network from
        loadUpdaterState - If true - load the updater state (history etc for updaters such as Adam, Nesterov momentum, RMSProp etc). For inference only, this should be false, as the updater state will take more memory, but is not required for training. If the network is to be trained further, this should be true. The updater state can only be loaded if it was saved with the network.
        Returns:
        The loaded SameDiff network
      • load

        public static SameDiff load​(@NonNull
                                    @NonNull InputStream is,
                                    boolean loadUpdaterState)
        As per load(File, boolean) but the SameDiff instance
        Parameters:
        is - Input stream to load the saved network from
        loadUpdaterState - If true - load the updater state (history etc for updaters such as Adam, Nesterov momentum, RMSProp etc). For inference only, this should be false, as the updater state will take more memory, but is not required for training. If the network is to be trained further, this should be true. The updater state can only be loaded if it was saved with the network.
        Returns:
        The loaded SameDiff network
      • asFlatFile

        public void asFlatFile​(@NonNull
                               @NonNull File file)
                        throws IOException
        This method converts SameDiff instance to FlatBuffers and saves it to file which can be restored later
        This includes the updater state, if applicable. Uses the default ExecutorConfiguration with output mode as OutputMode.VARIABLE_SPACE, execution mode as ExecutionMode.SEQUENTIAL, with profiling disabled and gather timings enabled.
        Parameters:
        file - File to save the FlatBuffers serialized graph (including arrays) to
        Throws:
        IOException
      • asFlatFile

        public void asFlatFile​(@NonNull
                               @NonNull File file,
                               @NonNull
                               @NonNull ExecutorConfiguration configuration,
                               boolean includeUpdaterState)
                        throws IOException
        This method converts SameDiff instance to FlatBuffers and saves it to file which can be restored later
        Parameters:
        file - File to save the FlatBuffers serialized graph (including arrays) to
        includeUpdaterState - If true: include the updater state (state for updaters such as Adam, Nesterov, AdaGrad etc)
        Throws:
        IOException
      • fromFlatFile

        public static SameDiff fromFlatFile​(@NonNull
                                            @NonNull File file)
                                     throws IOException
        Create a SameDiff instance from a file, including the updater state The method to save the file is save(File, boolean)
        Parameters:
        file - the file to load from
        Returns:
        the loaded same diff instance
        Throws:
        IOException
      • fromFlatFile

        public static SameDiff fromFlatFile​(@NonNull
                                            @NonNull File file,
                                            boolean loadUpdaterState)
                                     throws IOException
        Create a SameDiff instance from a file, optionally also loading the updater state The method to save the file is save(File, boolean)
        Parameters:
        file - the file to load from
        loadUpdaterState - If true, load the updater state (Adam etc state). For training, use true. For inference, use false
        Returns:
        the loaded same diff instance
        Throws:
        IOException
      • fromFlatBuffers

        public static SameDiff fromFlatBuffers​(ByteBuffer bbIn,
                                               boolean loadUpdaterState)
                                        throws IOException
        Create a SameDiff instance from a byte buffers instance.
        Parameters:
        bbIn - the input byte buffer
        loadUpdaterState - If true, load the updater state (Adam etc state). For training, use true. For inference, use false
        Returns:
        the created samediff instance
        Throws:
        IOException
      • asFlatPrint

        public String asFlatPrint()
        This method returns a text representation of the "flattened" graph.
        Returns:
        String representation of the graph
        See Also:
        summary()
      • freeze

        public SameDiff freeze​(boolean inPlace)
        Freezes the model. Optionally, can be done in place. Returns either a copy or this instance of the model with frozen variables. A frozen model is not trainable with variables converted to constants.
        Returns:
      • convertConstantsToVariables

        public void convertConstantsToVariables()
        All constants are converted to variables, also called unfreezing a graph. Frozen graphs are graphs where all differentiable variables are converted to constants. This is used when unfreezing a graph for training. A graph is usually frozen when importing a model.
      • constants

        public Set<SDVariable> constants()
        Returns the constants in this graph
        Returns:
        a set of constants in this graph
      • placeHolders

        public Set<SDVariable> placeHolders()
        Returns the placeholders in this graph
        Returns:
        the set of placeholders in this graph
      • summary

        public String summary()
        Generate and return a String representation of the current SameDiff instance
        Reports variables, ops, SameDiff function instances, and (where possible) array shapes.
        For ops, the input and output variables are reported.
        For variables, the ops that they are inputs to - or outputs of - are also reported
        Returns:
        A String representation of the SameDiff instance
      • invoke

        public SDVariable[] invoke​(Invoke.InvokeParams invokeParams)
        Invoke a sub graph and return the outputs aliased as outputs specified in the parent graph. Since no outputs are specified, this will just use the outputs generated by the normal generateNewVarName(String, int) Inputs will be derived from the inputs arguments of the parent assuming to be the same names.
        Returns:
        the outputs fo the op
      • invoke

        public SDVariable[] invoke​(String[] desiredOutputNames,
                                   Invoke.InvokeParams invokeParams)
        Invoke a sub graph and return the outputs aliased as outputs specified in the parent graph. Since no outputs are specified, this will just use the outputs generated by the normal generateNewVarName(String, int) Inputs will be derived from the inputs arguments of the parent assuming to be the same names.
        Parameters:
        desiredOutputNames - the desired output names of the variables
        Returns:
        the outputs fo the op
      • newBlockName

        public String newBlockName​(String baseName)
        For internal use only. Creates a new distinct block name from baseName. Block names are used by If and While
      • importFrozenTF

        public static SameDiff importFrozenTF​(File graphFile)
        Import a frozen Tensorflow graph to a new SameDiff graph.
        Parameters:
        graphFile - The text or binary file containing the graph
        Returns:
        The imported graph
      • getOpName

        public String getOpName​(String base,
                                boolean force)
        Generate a new, distinct op name of the form <base>_#.

        Applies name scope if active.

        Parameters:
        base - The base name to use
        force - Whether to force the result name to be the same as base.
      • generateNewVarName

        public String generateNewVarName​(String base,
                                         int argIndex,
                                         boolean existingOp)
        Generate a new, distinct variable name of the form <base>_#[:#].

        Applies name scopes if active.

        Parameters:
        base - The base of the name.
        argIndex - The argument index, used in the ":#". A value of 0 (or negative) does not include the ":#" part.
        existingOp - Whether to generate an distinct operation name from base (if false), or just use base (if true).
      • generateDistinctCustomVariableName

        public String generateDistinctCustomVariableName​(String base)
        Returns an unused variable name of the format <base>_#. Intended to be used for custom variables (like weights), arguments and op outputs should use generateNewVarName(String, int).
      • ifCond

        public SDVariable ifCond​(String outputName,
                                 String ifName,
                                 @NonNull
                                 @NonNull SameDiffNoArgSingleLambda cond,
                                 @NonNull
                                 @NonNull SameDiffNoArgSingleLambda trueBody,
                                 @NonNull
                                 @NonNull SameDiffNoArgSingleLambda falseBody)
        Constructs a If statement using the tensorflow style control flow operations (Switch and Merge) If the result of cond is true, returns the result of trueBody, otherwise returns the result of falseBody Note that cond and body lambdas are only called once to construct the graph. The constructed graph is used to evaluate. See Tensorflow Control Flow Implementation
        Parameters:
        outputName - Name to give the output variable. If null, doesn't rename
        ifName - The name of the if block. If null, uses "if"
        cond - A lambda evaluating to the if condition
        trueBody - A lambda to be executed if cond is true (the if block)
        falseBody - A lambda to be executed if cond is false (the else block)
        Returns:
        The value of trueBody if cond is true, or falseBody if it isn't
      • whileLoop

        public SDVariable[] whileLoop​(String[] outputNames,
                                      String loopName,
                                      @NonNull
                                      @NonNull SDVariable[] loopVars,
                                      @NonNull
                                      @NonNull SameDiffSingleLambda cond,
                                      @NonNull
                                      @NonNull SameDiffLambda body)
        Constructs a While loop using the tensorflow style control flow operations (Switch, Merge, Enter, Exit, and NextIteration) Repeatedly executes body on the loop variables and updates them with the results, until cond evaluates to false Note that cond and body lambdas are only called once to construct the graph. The constructed graph is used for further iterations. See Tensorflow Control Flow Implementation
        Parameters:
        outputNames - Names to give the output variables. If null, doesn't rename
        loopName - The name of the loop block and frame (must be unique). If null, uses "if"
        loopVars - Loop variables' inputs
        cond - A lambda evaluating to the loop condition
        body - A lambda doing the loop operation and returning the new loop variable values
        Returns:
        The values of the loop variables once condition is false