XML-based network builder. More...

#include <XmlNetworkBuilder.h>

Public Types
using	LayerScopeCallbackFunc = std::function< void(const char *pLayerName)>
	Function type for setScopeCallbackFunc. More...

Public Member Functions
NeuralResult	addFusingRule (const char *pFusingRule)
	Adds a fusing rule to network construction. More...

NeuralResult	buildNetworkFromFile (INetwork pNetwork, const char pFilename) const
	Builds a network from a file on disk. More...

NeuralResult	buildNetworkFromXmlLiteral (INetwork pNetwork, const char pXmlLiteral) const
	Builds a network from a provided XML literal. More...

NeuralResult	clearLayerOverrides ()
	Removes all layer overrides.

bool	loadDefaultFusingRules () const
	Returns true if ClassRegistry-based fusing rules are enabled. More...

NeuralResult	setFallbackLayerType (const char *pObjectClass)
	Set an emergency fallback object class when no candidates match the layer type. More...

NeuralResult	setInliningEnabled (bool enableInlining)
	Enable or disable network inlining during preprocessing. More...

NeuralResult	setLayerOverride (const char pLayerName, const char pObjectClass)
	Overrides construction of a layer. More...

NeuralResult	setLoadDefaultFusingRules (bool enableDefaultFusing)
	Turns ClassRegistry-based fusing rules on or off. More...

NeuralResult	setRuntimeOptionsHost (IRuntimeOptionsHost *pRuntimeOptionsHost)
	Set the runtime options host pointer to pass to layers during building.

NeuralResult	setScopeCallbackFunc (LayerScopeCallbackFunc scopeCallback)
	Sets a function that will be called around layer-specific operations during buildNetwork calls. More...

	XmlNetworkBuilder (const IClassRegistry *pRegistry)
	Create an XmlNetworkBuilder. More...

Protected Member Functions
virtual RefPtr< ILayer >	createLayerObject (const std::string &name, const std::string &layerType, const std::string &objectClass) const
	Creates a layer object for a given object class. More...

virtual RefPtr< IParameterNode >	createParameterNode (ILayer *pLayer, pugi::xml_node node) const
	Creates an appropriate parameter node for a given <Parameters> block. More...

virtual NeuralResult	setLayerActivation (ILayer *pLayer, ActivationFunctionId activationId, const std::string &activationName) const
	Sets an activation function on the indicated layer. More...

virtual NeuralResult	setLayerAlpha (ILayer *pLayer, size_t alphaIndex, float alphaValue) const
	Sets an activation coefficient on the indicated layer. More...

virtual NeuralResult	setLayerInput (ILayer pLayer, size_t inputIndex, ILayer pInput) const
	Sets an input on the indicated layer. More...

Detailed Description

XML-based network builder.

This class populates an INetwork-based network from a description stored in the original Neural XML model file format. LayerDesc structures exported to a ClassRegistry are used to decide which object class best represents each layer.

Under normal circumstances this class will abandon network creation if a layer type or activation function is missing, or if parameters stored in the model file are not valid for a created layer.

Warning: This class does not declare a stable ABI; do not pass it between modules.

Member Typedef Documentation

◆ LayerScopeCallbackFunc

using nvneural::XmlNetworkBuilder::LayerScopeCallbackFunc = std::function<void(const char* pLayerName)>

Function type for setScopeCallbackFunc.

Parameters

pLayerName Name of the layer entering scope, or nullptr when the operation is complete.

Warning: This method is not ABI-stable and should be used only as part of setScopeCallbackFunc, and only then from inside the module that created the XmlNetworkBuilder object.

Constructor & Destructor Documentation

◆ XmlNetworkBuilder()

XmlNetworkBuilder::XmlNetworkBuilder ( const IClassRegistry * pRegistry )

explicit

Create an XmlNetworkBuilder.

Parameters

pRegistry ClassRegistry object to use for object creation and layer lookup

Member Function Documentation

◆ addFusingRule()

NeuralResult XmlNetworkBuilder::addFusingRule ( const char * pFusingRule )

Adds a fusing rule to network construction.

Manually specified fusing rules take precedence over default fusing rules.

Parameters

pFusingRule Fusing rule to add

◆ buildNetworkFromFile()

NeuralResult XmlNetworkBuilder::buildNetworkFromFile	(	INetwork *	pNetwork,
		const char *	pFilename
	)		const

Builds a network from a file on disk.

Parameters

pNetwork	Network to populate
pFilename	UTF-8 path to an XML file on disk describing the network

◆ buildNetworkFromXmlLiteral()

NeuralResult XmlNetworkBuilder::buildNetworkFromXmlLiteral	(	INetwork *	pNetwork,
		const char *	pXmlLiteral
	)		const

Builds a network from a provided XML literal.

Parameters

pNetwork	Network to populate
pXmlLiteral	UTF-8 XML literal describing the network

◆ createLayerObject()

RefPtr< ILayer > XmlNetworkBuilder::createLayerObject	(	const std::string &	name,
		const std::string &	layerType,
		const std::string &	objectClass
	)		const

protectedvirtual

Creates a layer object for a given object class.

Derived classes may override to store data or change object types. Calling the version of createLayerObject in this class is not required.

Parameters

name	Name of the layer (advisory only–setName is not required)
layerType	Type name of the layer (see ILayer::serializedType), as originally defined in the model
objectClass	Object class to instantiate

◆ createParameterNode()

RefPtr< IParameterNode > XmlNetworkBuilder::createParameterNode	(	ILayer *	pLayer,
		pugi::xml_node	node
	)		const

protectedvirtual

Creates an appropriate parameter node for a given <Parameters> block.

Derived classes may override to store data or change object types. Calling the version of createParameterNode in this class is not required.

Parameters

pLayer	Layer being initialized
node	XML node containing <Parameters> entries

Returns: IParameterNode suitable for ILayer::loadFromParameters

◆ loadDefaultFusingRules()

bool XmlNetworkBuilder::loadDefaultFusingRules ( ) const

Returns true if ClassRegistry-based fusing rules are enabled.

See setLoadDefaultFusingRules for how to change this setting.

◆ setFallbackLayerType()

NeuralResult XmlNetworkBuilder::setFallbackLayerType ( const char * pObjectClass )

Set an emergency fallback object class when no candidates match the layer type.

If no fallback is provided, network creation will fail when encountering unknown layers. When a fallback is present, it will be tried after all other candidates. Failure to create this object class will still cause network creation to fail.

When an emergency object is provided, the original layer type name will be passed as an extra layer parameter named "__originaltype".

Parameters

pObjectClass Object class to use for fallback layers, or nullptr to disable the feature

◆ setInliningEnabled()

NeuralResult XmlNetworkBuilder::setInliningEnabled ( bool enableInlining )

Enable or disable network inlining during preprocessing.

When inlining is enabled, external network references are flattened into the main network being built rather than creating subnetworks.

By default, inlining is disabled.

◆ setLayerActivation()

NeuralResult XmlNetworkBuilder::setLayerActivation	(	ILayer *	pLayer,
		ActivationFunctionId	activationId,
		const std::string &	activationName
	)		const

protectedvirtual

Sets an activation function on the indicated layer.

Derived classes may override to capture this information. Calling the version of setLayerActivation in this class is not required.

Parameters

pLayer	Layer being altered
activationId	Activation function ID being assigned
activationName	Serialized name of the activation function being assigned

Note: The string in activationName matches ActivationDesc::pSerializedName, not the qualified C++ enum type in ActivationFunctionId.

Returns: Result of ILayer::setActivationFunction

◆ setLayerAlpha()

NeuralResult XmlNetworkBuilder::setLayerAlpha	(	ILayer *	pLayer,
		size_t	alphaIndex,
		float	alphaValue
	)		const

protectedvirtual

Sets an activation coefficient on the indicated layer.

Derived classes may override to capture this information. Calling the version of setLayerAlpha in this class is not requireed.

Parameters

pLayer	Layer being altered
alphaIndex	Coefficient index
alphaValue	Coefficient value

Returns: Result of ILayer::setActivationCoefficient

◆ setLayerInput()

NeuralResult XmlNetworkBuilder::setLayerInput	(	ILayer *	pLayer,
		size_t	inputIndex,
		ILayer *	pInput
	)		const

protectedvirtual

Sets an input on the indicated layer.

Derived classes may override to capture this information. Calling the version of setLayerInput in this class is not required.

Parameters

pLayer	Layer being altered
inputIndex	Index of the input layer inside pLayer
pInput	Input to attach to pLayer

Returns: Result of ILayer::setLayerInput

◆ setLayerOverride()

NeuralResult XmlNetworkBuilder::setLayerOverride	(	const char *	pLayerName,
		const char *	pObjectClass
	)

Overrides construction of a layer.

Rather than using the normal candidate scoring procedure for picking a layer type from the ClassRegistry's available layer descriptors, the network building process will simply instantiate the provided object type using ClassRegistry::createObject. If the object is unable to be instantiated, or does not implement required interfaces such as ILayer, network construction will fail rather than fall back to candidate scoring.

Overriding a layer name that is not constructed by the network (whether because fusing rules removed it, because the layer name is misspelled, or for any other reason) is not an error; host applications that wish to warn upon a failed override should check the resulting list of layers in the network against the list of intended overrides, then complain to the user if the network list is not a superset of the override lists.

Parameters

pLayerName	Name of the layer to override
pObjectClass	Object class to use for this layer, or nullptr to remove the override

◆ setLoadDefaultFusingRules()

NeuralResult XmlNetworkBuilder::setLoadDefaultFusingRules ( bool enableDefaultFusing )

Turns ClassRegistry-based fusing rules on or off.

Unless changed, default fusing rules will be ON.

Parameters

enableDefaultFusing Load fusing rules from ClassRegistry

◆ setScopeCallbackFunc()

NeuralResult XmlNetworkBuilder::setScopeCallbackFunc ( LayerScopeCallbackFunc scopeCallback )

Sets a function that will be called around layer-specific operations during buildNetwork calls.

If this function object is non-null, it will be called under the following circumstances:

Before creating a new layer object. Param is the name of the layer.
After a layer object has been created, or after all candidates have been exhausted including the (if present) fallback layer type. Param is nullptr.
Before configuring a created layer object (e.g., ILayer::setInputLayer and ILayer::loadFromParameters being some of the operations performed during "configuration"). Param is the name of the layer.
After layer configuration is complete. Param is nullptr.

Parameters

scopeCallback Function to call around layer operations

Warning: This method is not ABI-stable and should be called only by the module that created the XmlNetworkBuilder object.

The documentation for this class was generated from the following files:

Host/Inc/XmlNetworkBuilder.h
Host/Src/XmlNetworkBuilder.cpp

Public Types

Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ LayerScopeCallbackFunc

Constructor & Destructor Documentation

◆ XmlNetworkBuilder()

Member Function Documentation

◆ addFusingRule()

◆ buildNetworkFromFile()

◆ buildNetworkFromXmlLiteral()

◆ createLayerObject()

◆ createParameterNode()

◆ loadDefaultFusingRules()

◆ setFallbackLayerType()

◆ setInliningEnabled()

◆ setLayerActivation()

◆ setLayerAlpha()

◆ setLayerInput()

◆ setLayerOverride()

◆ setLoadDefaultFusingRules()

◆ setScopeCallbackFunc()