neureka.backend.api

Interface Operation

All Known Implementing Classes:

Absolute, AbstractOperation, Addition, AssignLeft, Cat, Cbrt, Convolution, Cosinus, DimFit, DimTrim, Division, DotProduct, Exp, GaSU, GaTU, Gaussian, GaussianFast, GeLU, Identity, Log10, Logarithm, MatMul, Max, Min, Modulo, Multiplication, Permute, Power, Product, Quadratic, Randomization, ReLayout, ReLU, Reshape, SeLU, Sigmoid, SiLU, Sinus, Slice, Softplus, Softsign, Sqrt, Subtraction, Sum, Summation, Tanh, TanhFast, XConvLeft, XConvRight

public interface Operation

This interface is part of the backend API, and it embodies the top layer of the 3 tier backend architecture. It represents broad and high level types of algorithms which might be executed differently depending on the provided ExecutionCall arguments. An Operation implementation ought to consist of a component system containing multiple Algorithm instances, which themselves ought to contain device specific implementations capable of processing ExecutionCall instances, or rather their state.

Other than the component system, there is also the definition for how It's supposed to integrate into the neureka.math package in order to serve as part of an Function AST. This means that the operation should have a function name and optionally also an operator in the form of String instances. Alongside there must be an implementation of the stringify(String[]) method, which ought to generate a String view as part of a Function-AST.

Method Summary

Modifier and Type	Method and Description
java.lang.String	asDerivative(Function[] children, int derivationIndex) Operation implementations and Function implementations are in a tight relationship where the Function describes an abstract syntax tree based on the syntactic information provided by the Operation (through methods like getOperator() or getIdentifier()).
static OperationBuilder	builder()
double	calculate(double[] inputs, int j, int d, Function[] src) This method mainly ought to serve as a reference- and fallback- implementation for tensor backends and also as the backend for handling the calculation of scalar inputs passed to a given abstract syntax tree of Function instances...
default Result	execute(Function caller, ExecutionCall<?> call)
<T extends Algorithm> T	getAlgorithm(java.lang.Class<T> type) Operation implementations embody a component system hosting unique Algorithm instances.
Algorithm	getAlgorithmFor(ExecutionCall<?> call) Alongside a component system made up of Algorithm instances, implementations of this interface also ought to express a routing mechanism which finds the best Algorithm for a given ExecutionCall instance.
Algorithm[]	getAllAlgorithms()
int	getArity() Arity is the number of arguments or operands that this function or operation takes.
java.lang.String	getIdentifier() Concrete Operation types ought to be representable by a function name.
java.lang.String	getOperator()
boolean	isDifferentiable() Deprecated.
boolean	isIndexer() This boolean property tell the Function implementations that this Operation ought to be viewed as something to be indexed.
boolean	isInline() This flag indicates that the implementation of this Operation performs an operation which modifies the inputs to that operation.
boolean	isOperator() An operator is an alternative to a function like "sum()" or "prod()".
<T extends Algorithm> Operation	setAlgorithm(java.lang.Class<T> type, T instance) Operation implementations embody a component system hosting unique Algorithm instances.
default <T extends Algorithm> Operation	setAlgorithm(T instance)
java.lang.String	stringify(java.lang.String[] children)
<T extends Algorithm> boolean	supports(java.lang.Class<T> implementation)
<T extends Algorithm> boolean	supportsAlgorithm(java.lang.Class<T> type) This method checks if this Operation contains an instance of the Algorithm implementation specified via its type class.

Method Detail

builder

static OperationBuilder builder()

getAllAlgorithms

Algorithm[] getAllAlgorithms()

getAlgorithmFor

Algorithm getAlgorithmFor(ExecutionCall<?> call)

Alongside a component system made up of Algorithm instances, implementations of this interface also ought to express a routing mechanism which finds the best Algorithm for a given ExecutionCall instance. This method signature describes this requirement.

Parameters:

call - The ExecutionCall instance which needs the best Algorithm for execution.

Returns:

The chosen Algorithm which ought to be fir for execution the provided call.

setAlgorithm

<T extends Algorithm> Operation setAlgorithm(java.lang.Class<T> type,
                                             T instance)

Operation implementations embody a component system hosting unique Algorithm instances. For a given class implementing the Algorithm class, there can only be a single instance of it referenced (aka supported) by a given Operation instance. This method enables the registration of Algorithm types in the component system of this Operation.

Type Parameters:

T - The type parameter of the Algorithm type class.

Parameters:

type - The class of the type which implements Algorithm as key for the provided instance.

instance - The instance of the provided type class which ought to be referenced (supported) by this Operation.

Returns:

This very Operation instance to enable method chaining on it.

setAlgorithm

default <T extends Algorithm> Operation setAlgorithm(T instance)

getAlgorithm

<T extends Algorithm> T getAlgorithm(java.lang.Class<T> type)

Operation implementations embody a component system hosting unique Algorithm instances. For a given class implementing the Algorithm class, there can only be a single instance of it referenced (aka supported) by a given Operation instance. This method ensures this in terms of read access by returning only a single instance or null based on the provided class instance whose type extends the Algorithm interface.

Type Parameters:

T - The type parameter of the Algorithm type class.

Parameters:

type - The class of the type which implements Algorithm as a key to get an existing instance.

Returns:

The instance of the specified type if any exists within this Operation.

supportsAlgorithm

<T extends Algorithm> boolean supportsAlgorithm(java.lang.Class<T> type)

This method checks if this Operation contains an instance of the Algorithm implementation specified via its type class.

Type Parameters:

T - The type parameter of the Algorithm type class.

Parameters:

type - The class of the type which implements Algorithm.

Returns:

The truth value determining if this Operation contains an instance of the specified Algorithm type.

getIdentifier

java.lang.String getIdentifier()

Concrete Operation types ought to be representable by a function name. The following ensures that this contract is met when overriding the method.

Returns:

the function name which serves as identifier when parsing Function instances.

stringify

java.lang.String stringify(java.lang.String[] children)

asDerivative

java.lang.String asDerivative(Function[] children,
                              int derivationIndex)

Operation implementations and Function implementations are in a tight relationship where the Function describes an abstract syntax tree based on the syntactic information provided by the Operation (through methods like getOperator() or getIdentifier()). One important feature of the Function is the ability to create derivatives by calling the Function.getDerivative(int) method. Implementations of this Function method ought to call the method defined below in order to form the derivation based on the child nodes of the abstract syntax tree of the given Function node.

Parameters:

children - The child nodes of a AST node referencing this operation.

derivationIndex - The index of the input node which ought to be derived.

Returns:

The derivative as a String which should be parsable into yet another AST.

getOperator

java.lang.String getOperator()

getArity

int getArity()

Arity is the number of arguments or operands that this function or operation takes.

Returns:

The number of arguments expected by this operation, or -1 if an arbitrary number is accepted.

isOperator

boolean isOperator()

An operator is an alternative to a function like "sum()" or "prod()".
Examples would be "+, -, * ..."!

Returns:

If this operation can be represented as operator like "+, -, * ..."!

isIndexer

boolean isIndexer()

This boolean property tell the Function implementations that this Operation ought to be viewed as something to be indexed. The Function will use this information to iterate over all the provided inputs and then execute the function wile also passing the index to the function AST. The resulting array will then be available to this Operation as argument list. This feature works alongside the Function implementation found in FunctionVariable, which represents an input indexed by the identifier 'j'!

Returns:

If this operation is an indexer.

isDifferentiable

@Deprecated
boolean isDifferentiable()

Deprecated.

isInline

boolean isInline()

This flag indicates that the implementation of this Operation performs an operation which modifies the inputs to that operation. An example of this would be an assignment operation which copies the contents of one nd-array / tensor into another tensor. This second tensor will then have changed its state. This can be dangerous when auto-differentiation is involved.

Returns:

The truth value determining if this Operation changes the contents of inputs.

supports

<T extends Algorithm> boolean supports(java.lang.Class<T> implementation)

execute

default Result execute(Function caller,
                       ExecutionCall<?> call)

calculate

double calculate(double[] inputs,
                 int j,
                 int d,
                 Function[] src)

This method mainly ought to serve as a reference- and fallback- implementation for tensor backends and also as the backend for handling the calculation of scalar inputs passed to a given abstract syntax tree of Function instances...
( (almost) every Function instance contains an OperationType reference to which it passes scalar executions... )

This is also the reason why the last parameter of this method is a list of Function objects : The list stores the child nodes of the Function node that is currently being processed. Therefore, when implementing this method one should first call the child nodes in order to get the "real inputs" of this current node.

One might ask : Why does that not happen automatically? The answer is to that question lies in the other parameters of this method. Specifically the parameter "d" ! This argument determines if the derivative ought to be calculated and also which value is being targeted within the input array. Depending on this variable and also the nature of the operation, the execution calls to the child nodes of this node change considerably!

Parameters:

inputs - An array of scalar input variables.

j - The index variable for indexed execution on the input array. (-1 if no indexing should occur)

d - The index of the variable of which a derivative ought to be calculated.

src - The child nodes of the Function node to which this very OperationType belongs.

Returns:

The result of the calculation.