ai.djl.nn

Class AbstractBlock

java.lang.Object

ai.djl.nn.AbstractBlock

All Implemented Interfaces:

Block

Direct Known Subclasses:

BatchNorm, ConstantEmbedding, Convolution, Decoder, Dropout, Embedding, Encoder, EncoderDecoder, LambdaBlock, Linear, ParallelBlock, Prelu, RecurrentBlock, ScaledDotProductAttentionBlock, SequentialBlock, TrainableTextEmbedding

public abstract class AbstractBlock
extends java.lang.Object
implements Block

AbstractBlock is an abstract implementation of Block.

It is recommended that all Block classes that have children extend the AbstractBlock.

To create your own blocks, you need to do the following:

• Define a version for serializing parameter and metadata and pass it to the parent constructor
• Use addParameter(Parameter, Shape) or addParameter(Parameter, Function) to add parameters to your block in the constructor if necessary.
• Use addChildBlock(String, Block) to add child blocks if necessary.
• Override Block.getOutputShapes(NDManager, Shape[]) to determine the shape of your custom block's output based on the input it will receive.
• Override initializeChildBlocks(NDManager, DataType, Shape...) if you added child blocks to initialize them based on the input shape your block will receive. You can skip this if your block does not contain child blocks
• Override Block.forward(ParameterStore, NDList, boolean, PairList) to implement the computation of your block
• IFF you need to save data apart from the parameter values of your block, you need to override saveMetadata(DataOutputStream) and loadMetadata(byte, DataInputStream). If you do not need to save or load any state other than parameters in your block, you can skip this.

If you use addParameter(Parameter) to add parameters, you have to take care of parameter initialization yourself. In this case, you need to override getParameterShape(String, Shape[]) to determine the shape of your parameters. If you use the other variants of addParameter this is done for you.

Field Summary

Fields

Modifier and Type	Field and Description
protected BlockList	children All direct children of this Block.
protected java.util.List<java.lang.String>	inputNames List of names for the input, defaults to ["data"] unless manually changed.
protected Shape[]	inputShapes The shape of the input for this block, set by the initialization process.
protected java.util.LinkedHashMap<java.lang.String,Parameter>	parameters All direct parameters of this Block.
protected java.util.LinkedHashMap<java.lang.String,java.util.function.Function<Shape[],Shape>>	parameterShapeCallbacks Callbacks to determine the shape of a parameter.
protected byte	version The model version of this block, used for checking if parameters are still valid during parameter loading.

Constructor Summary

Constructors

Constructor and Description
AbstractBlock(byte version) Builds an empty block with the given version for parameter serialization.

Method Summary

Modifier and Type	Method and Description
protected <B extends Block> B	addChildBlock(java.lang.String name, B block) Use this to add a child block to this block.
protected <P extends Parameter> P	addParameter(P parameter) Adds a parameter to this block.
protected <P extends Parameter> P	addParameter(P parameter, java.util.function.Function<Shape[],Shape> shapeCallback) Adds a parameter to this block.
protected <P extends Parameter> P	addParameter(P parameter, Shape shape) Adds a parameter to this block.
protected void	beforeInitialize(Shape[] inputShapes) Performs any action necessary before initialization.
void	cast(DataType dataType) Guaranteed to throw an exception.
void	clear() Closes all the parameters of the block.
ai.djl.util.PairList<java.lang.String,Shape>	describeInput() Returns a PairList of input names, and shapes.
BlockList	getChildren() Returns a list of all the children of the block.
ParameterList	getDirectParameters() Returns a list of all the direct parameters of the block.
ParameterList	getParameters() Returns a list of all the parameters of the block, including the parameters of its children fetched recursively.
Shape	getParameterShape(java.lang.String name, Shape[] inputShapes) Returns the shape of the specified direct parameter of this block given the shapes of the input to the block.
Shape[]	initialize(NDManager manager, DataType dataType, Shape... inputShapes) Initializes the parameters of the block.
protected void	initializeChildBlocks(NDManager manager, DataType dataType, Shape... inputShapes) Initializes the Child blocks of this block.
boolean	isInitialized() Returns a boolean whether the block is initialized.
protected void	loadMetadata(byte loadVersion, java.io.DataInputStream is) Overwrite this to load additional metadata with the parameter values.
void	loadParameters(NDManager manager, java.io.DataInputStream is) Loads the parameters from the given input stream.
protected void	readInputShapes(java.io.DataInputStream is)
protected void	saveInputShapes(java.io.DataOutputStream os)
protected void	saveMetadata(java.io.DataOutputStream os) Override this method to save additional data apart from parameter values.
void	saveParameters(java.io.DataOutputStream os) Writes the parameters of the block to the given outputStream.
void	setInitializer(Initializer initializer) Sets an Initializer to the block.
void	setInitializer(Initializer initializer, java.lang.String paramName) Sets an Initializer to the specified direct parameter of the block, overriding the initializer of the parameter, if already set.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ai.djl.nn.Block

forward, forward, forward, getOutputShapes, validateLayout

Field Detail

inputShapes

protected Shape[] inputShapes

The shape of the input for this block, set by the initialization process.

inputNames

protected java.util.List<java.lang.String> inputNames

List of names for the input, defaults to ["data"] unless manually changed.

version

protected byte version

The model version of this block, used for checking if parameters are still valid during parameter loading.

children

protected BlockList children

All direct children of this Block. Keys are names of the blocks.

Use the addChildBlock(String, Block) method to add children. All children in this map are automagically loaded / saved.

parameters

protected java.util.LinkedHashMap<java.lang.String,Parameter> parameters

All direct parameters of this Block. Keys are name of the parameters.

Use the addParameter(Parameter) method to add children. All parameters in this map are automatically loaded / saved.

parameterShapeCallbacks

protected java.util.LinkedHashMap<java.lang.String,java.util.function.Function<Shape[],Shape>> parameterShapeCallbacks

Callbacks to determine the shape of a parameter. Values may be null in which case extending classes need to override Block.getParameterShape(String, Shape[]) and implement parameter shape resolution manually.

Constructor Detail

AbstractBlock

public AbstractBlock(byte version)

Builds an empty block with the given version for parameter serialization.

Parameters:

version - the version to use for parameter serialization.

Method Detail

addChildBlock

protected final <B extends Block> B addChildBlock(java.lang.String name,
                                                  B block)

Use this to add a child block to this block.

Type Parameters:

B - The type of block

Parameters:

name - Name of the block, must be unique or otherwise existing children with this name are removed, must not be null.

block - The block, must not be null.

Returns:

the block given as a parameter - that way the block can be created and reassigned to a member variable more easily.

addParameter

protected final <P extends Parameter> P addParameter(P parameter)

Adds a parameter to this block. If parameters are added with this method, subclasses need to override Block.getParameterShape(String, Shape[]) and return the shapes of parameters themselves.

Type Parameters:

P - the specific parameter subclass

Parameters:

parameter - the parameter to add, not null

Returns:

the parameter passed as arguments to make it easier to create and assign paramters in one line

addParameter

protected final <P extends Parameter> P addParameter(P parameter,
                                                     Shape shape)

Adds a parameter to this block. If parameters are added with this method, intialization of the parameter works out of the box

Type Parameters:

P - the specific parameter subclass

Parameters:

parameter - the parameter to add, not null

shape - the shape of the parameter

Returns:

the parameter passed as arguments to make it easier to create and assign paramters in one line

addParameter

protected final <P extends Parameter> P addParameter(P parameter,
                                                     java.util.function.Function<Shape[],Shape> shapeCallback)

Adds a parameter to this block. If parameters are added with this method, intialization of the parameter works out of the box

Type Parameters:

P - the specific parameter subclass

Parameters:

parameter - the parameter to add, not null

shapeCallback - the method to call once the input shape of this block is known to determine the shape of the given parameter

Returns:

the parameter passed as arguments to make it easier to create and assign parameters in one line

getParameterShape

public Shape getParameterShape(java.lang.String name,
                               Shape[] inputShapes)

Returns the shape of the specified direct parameter of this block given the shapes of the input to the block.

Specified by:

getParameterShape in interface Block

Parameters:

name - the name of the parameter

inputShapes - the shapes of the input to the block

Returns:

the shape of the parameter specified

getChildren

public BlockList getChildren()

Returns a list of all the children of the block.

Specified by:

getChildren in interface Block

Returns:

the list of child blocks

describeInput

public ai.djl.util.PairList<java.lang.String,Shape> describeInput()

Returns a PairList of input names, and shapes.

Specified by:

describeInput in interface Block

Returns:

the PairList of input names, and shapes

setInitializer

public void setInitializer(Initializer initializer)

Sets an Initializer to the block.

Specified by:

setInitializer in interface Block

Parameters:

initializer - the initializer to set

setInitializer

public void setInitializer(Initializer initializer,
                           java.lang.String paramName)

Sets an Initializer to the specified direct parameter of the block, overriding the initializer of the parameter, if already set.

Specified by:

setInitializer in interface Block

Parameters:

initializer - the initializer to be set

paramName - the name of the parameter

initialize

public Shape[] initialize(NDManager manager,
                          DataType dataType,
                          Shape... inputShapes)

Initializes the parameters of the block. This method must be called before calling `forward`.

Specified by:

initialize in interface Block

Parameters:

manager - the NDManager to initialize the parameters

dataType - the datatype of the parameters

inputShapes - the shapes of the inputs to the block

Returns:

the shapes of the outputs of the block

initializeChildBlocks

protected void initializeChildBlocks(NDManager manager,
                                     DataType dataType,
                                     Shape... inputShapes)

Initializes the Child blocks of this block. You need to override this method if your subclass has child blocks. Used to determine the correct input shapes for child blocks based on the requested input shape for this block.

Parameters:

manager - the manager to use for initialization

dataType - the requested data type

inputShapes - the expected input shapes for this block

getParameters

public ParameterList getParameters()

Returns a list of all the parameters of the block, including the parameters of its children fetched recursively.

Specified by:

getParameters in interface Block

Returns:

the list of all parameters of the block

getDirectParameters

public ParameterList getDirectParameters()

Returns a list of all the direct parameters of the block.

Specified by:

getDirectParameters in interface Block

Returns:

the list of Parameter

beforeInitialize

protected void beforeInitialize(Shape[] inputShapes)

Performs any action necessary before initialization.

Parameters:

inputShapes - the expected shapes of the input

isInitialized

public boolean isInitialized()

Returns a boolean whether the block is initialized.

Specified by:

isInitialized in interface Block

Returns:

whether the block is initialized

clear

public void clear()

Closes all the parameters of the block. All the updates made during training will be lost.

Specified by:

clear in interface Block

cast

public void cast(DataType dataType)

Guaranteed to throw an exception. Not yet implemented

Specified by:

cast in interface Block

Parameters:

dataType - the data type to cast to

saveParameters

public void saveParameters(java.io.DataOutputStream os)
                    throws java.io.IOException

Writes the parameters of the block to the given outputStream.

Specified by:

saveParameters in interface Block

Parameters:

os - the outputstream to save the parameters to

Throws:

java.io.IOException - if an I/O error occurs

loadParameters

public void loadParameters(NDManager manager,
                           java.io.DataInputStream is)
                    throws java.io.IOException,
                           MalformedModelException

Loads the parameters from the given input stream.

Specified by:

loadParameters in interface Block

Parameters:

manager - an NDManager to create the parameter arrays

is - the inputstream that stream the parameter values

Throws:

java.io.IOException - if an I/O error occurs

MalformedModelException - if the model file is corrupted or unsupported

saveMetadata

protected void saveMetadata(java.io.DataOutputStream os)
                     throws java.io.IOException

Override this method to save additional data apart from parameter values.

This default implementation saves the currently set input shapes.

Parameters:

os - the non-null output stream the parameter values and metadata are written to

Throws:

java.io.IOException - saving failed

loadMetadata

protected void loadMetadata(byte loadVersion,
                            java.io.DataInputStream is)
                     throws java.io.IOException,
                            MalformedModelException

Overwrite this to load additional metadata with the parameter values.

If you overwrite saveMetadata(DataOutputStream) or need to provide backward compatibility to older binary formats, you prabably need to overwrite this. This default implementation checks if the version number fits, if not it throws an MalformedModelException. After that it restores the input shapes.

Parameters:

loadVersion - the version used for loading this metadata.

is - the input stream we are loading from

Throws:

java.io.IOException - loading failed

MalformedModelException - data can be loaded but has wrong format

saveInputShapes

protected void saveInputShapes(java.io.DataOutputStream os)
                        throws java.io.IOException

Throws:

java.io.IOException

readInputShapes

protected void readInputShapes(java.io.DataInputStream is)
                        throws java.io.IOException

Throws:

java.io.IOException

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object