turi::neural_net::model_spec Class Reference

#include <ml/neural_net/model_spec.hpp>

Public Types
enum	padding_type
enum	padding_policy
enum	pooling_type

Public Member Functions
	model_spec ()
	model_spec (const CoreML::Specification::NeuralNetwork &nn_model)
	model_spec (const std::string &mlmodel_path)
const CoreML::Specification::NeuralNetwork &	get_coreml_spec () const
std::unique_ptr< CoreML::Specification::NeuralNetwork >	move_coreml_spec () &&
float_array_map	export_params_view () const
void	update_params (const float_array_map &weights, bool use_quantization=false)
bool	has_layer_output (const std::string &layer_name) const
void	add_relu (const std::string &name, const std::string &input)
void	add_leakyrelu (const std::string &name, const std::string &input, float alpha)
void	add_sigmoid (const std::string &name, const std::string &input)
void	add_pooling (const std::string &name, const std::string &input, size_t kernel_height, size_t kernel_width, size_t stride_h, size_t stride_w, padding_type padding, bool use_poolexcludepadding=false, pooling_type pooling=pooling_type::MAX)
void	add_convolution (const std::string &name, const std::string &input, size_t num_output_channels, size_t num_kernel_channels, size_t kernel_height, size_t kernel_width, size_t stride_h, size_t stride_w, padding_type padding, weight_initializer weight_initializer_fn, weight_initializer bias_initializer_fn=nullptr)
void	add_padding (const std::string &name, const std::string &input, size_t padding_top, size_t padding_bottom, size_t padding_left, size_t padding_right, padding_policy policy=padding_policy::REFLECTIVE)
void	add_upsampling (const std::string &name, const std::string &input, size_t scaling_x, size_t scaling_y)
void	add_inner_product (const std::string &name, const std::string &input, size_t num_output_channels, size_t num_input_channels, weight_initializer weight_initializer_fn, weight_initializer bias_initializer_fn=nullptr)
void	add_batchnorm (const std::string &name, const std::string &input, size_t num_channels, float epsilon)
void	add_instancenorm (const std::string &name, const std::string &input, size_t num_channels, float epsilon)
void	add_channel_concat (const std::string &name, const std::vector< std::string > &inputs)
void	add_softmax (const std::string &name, const std::string &input)
void	add_flatten (const std::string &name, const std::string &input)
void	add_addition (const std::string &name, const std::vector< std::string > &inputs)
void	add_multiplication (const std::string &name, const std::vector< std::string > &inputs)
void	add_exp (const std::string &name, const std::string &input)
void	add_scale (const std::string &name, const std::string &input, const std::vector< size_t > &shape_c_h_w, weight_initializer scale_initializer_fn)
void	add_constant (const std::string &name, const std::array< size_t, 3 > &shape_c_h_w, weight_initializer weight_initializer_fn)
void	add_reshape (const std::string &name, const std::string &input, const std::array< size_t, 4 > &seq_c_h_w)
void	add_permute (const std::string &name, const std::string &input, const std::array< size_t, 4 > &axis_permutation)
void	add_channel_slice (const std::string &name, const std::string &input, int start_index, int end_index, size_t stride)
void	add_lstm (const std::string &name, const std::string &input, const std::string &hidden_input, const std::string &cell_input, const std::string &hidden_output, const std::string &cell_output, size_t input_vector_size, size_t output_vector_size, float cell_clip_threshold, const lstm_weight_initializers &initializers)
void	add_preprocessing (const std::string &feature_name, const float image_scale)
void	add_transpose (const std::string &name, const std::string &input, std::vector< size_t > axes)
void	add_split_nd (const std::string &name, const std::string &input, size_t axis, size_t num_splits, const std::vector< size_t > &split_sizes)
void	add_concat_nd (const std::string &name, const std::vector< std::string > &inputs, size_t axis)
void	add_reshape_static (const std::string &name, const std::string &input, const std::vector< size_t > &targetShape)
void	add_reshape_dynamic (const std::string &name, const std::vector< std::string > &inputs)
void	add_expand_dims (const std::string &name, const std::string &input, const std::vector< size_t > &axes, const std::vector< size_t > &inputVector, const std::vector< size_t > &outputVector)
void	add_squeeze (const std::string &name, const std::string &input, const std::vector< size_t > &axes, const std::vector< size_t > &inputVector, const std::vector< size_t > &outputVector)
void	add_add_broadcastable (const std::string &name, const std::vector< std::string > &inputs)
void	add_gather (const std::string &name, const std::vector< std::string > &inputs)
void	add_constant_nd (const std::string &name, const std::vector< size_t > &shape, const weight_initializer &data)
void	add_get_shape (const std::string &name, const std::string &input)
void	add_slice_dynamic (const std::string &name, const std::vector< std::string > &inputs)
void	add_nms_layer (const std::string &name, const std::vector< std::string > &inputs, const std::vector< std::string > &outputs, float iou_threshold, float confidence_threshold, size_t max_boxes, bool per_class_supression)

Detailed Description

Representation for a neural-network model (structure and parameters), optimized for convenient export to CoreML.

This class just wraps CoreML::Specification::NeuralNetwork, helping to insulate toolkits from protobuf code.

Definition at line 40 of file model_spec.hpp.

Member Enumeration Documentation

padding_policy

enum turi::neural_net::model_spec::padding_policy

strong

Parameter for the padding layer

Definition at line 50 of file model_spec.hpp.

padding_type

enum turi::neural_net::model_spec::padding_type

strong

Parameter for convolution and pooling layers.

Definition at line 44 of file model_spec.hpp.

pooling_type

enum turi::neural_net::model_spec::pooling_type

strong

Parameter for pooling types.

Definition at line 57 of file model_spec.hpp.

Constructor & Destructor Documentation

model_spec() [1/3]

turi::neural_net::model_spec::model_spec

(

)

Creates an empty model_spec (with no layers).

model_spec() [2/3]

turi::neural_net::model_spec::model_spec

(

const CoreML::Specification::NeuralNetwork &

nn_model

)

Initializes a model_spec from a NeuralNetwork proto.

model_spec() [3/3]

turi::neural_net::model_spec::model_spec

(

const std::string &

mlmodel_path

)

Initializes a model_spec from the top-level NeuralNetwork found inside a CoreML model specification on disk.

Parameters

mlmodel_path

Path to a CoreM::Specification::Model proto on disk.

Exceptions

If	the indicated path could not be read or parsed.

Member Function Documentation

add_add_broadcastable()

void turi::neural_net::model_spec::add_add_broadcastable	(	const std::string &	name,
		const std::vector< std::string > &	inputs
	)

Appends an Add Broadcastable layer.

Parameters

name	The name of the layer and its output
inputs	The vector of names of the layer's inputs

add_addition()

void turi::neural_net::model_spec::add_addition	(	const std::string &	name,
		const std::vector< std::string > &	inputs
	)

Appends a layer that performs elementwise addition.

Parameters

name	The name of the layer and its output
inputs	The names of the layer's inputs

add_batchnorm()

void turi::neural_net::model_spec::add_batchnorm	(	const std::string &	name,
		const std::string &	input,
		size_t	num_channels,
		float	epsilon
	)

Appends a batch norm layer.

The beta and mean parameters are initialized to 0.f; the gamma and variance parameters are initialized to 1.f

Parameters

name	The name of the layer and its output
input	The name of the layer's input
num_channels	The C dimension of the input and output
epsilon	Added to the variance for each input before normalizing

add_channel_concat()

void turi::neural_net::model_spec::add_channel_concat	(	const std::string &	name,
		const std::vector< std::string > &	inputs
	)

Appends a layer that concatenates its inputs along the channel axis.

Parameters

name	The name of the layer and its output
inputs	The names of the layer's inputs

add_channel_slice()

void turi::neural_net::model_spec::add_channel_slice	(	const std::string &	name,
		const std::string &	input,
		int	start_index,
		int	end_index,
		size_t	stride
	)

Appends a layer that slices the input along the channel axis.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
start_index	The first channel to include
end_index	The first channel to stop including. If negative, then the number of channels is added first (so -1 becomes n - 1).
stride	The interval between channels to include

add_concat_nd()

void turi::neural_net::model_spec::add_concat_nd	(	const std::string &	name,
		const std::vector< std::string > &	inputs,
		size_t	axis
	)

Appends an Concat layer.

Parameters

name	The name of the layer and its output
inputs	The vector of names of the layer's inputs
axis	The axis to concat the layer on

add_constant()

void turi::neural_net::model_spec::add_constant	(	const std::string &	name,
		const std::array< size_t, 3 > &	shape_c_h_w,
		weight_initializer	weight_initializer_fn
	)

Appends a layer with fixed values.

Parameters

name	The name of the layer and its output
shape_c_h_w	The shape of the output
weight_initializer_fn	Callback used to initialize the weights

add_constant_nd()

void turi::neural_net::model_spec::add_constant_nd	(	const std::string &	name,
		const std::vector< size_t > &	shape,
		const weight_initializer &	data
	)

Appends a Constant ND layer.

Parameters

name	The name of the layer and its output
shape	The shape of the constant layer
data	The data being loaded in the constant layer

add_convolution()

void turi::neural_net::model_spec::add_convolution	(	const std::string &	name,
		const std::string &	input,
		size_t	num_output_channels,
		size_t	num_kernel_channels,
		size_t	kernel_height,
		size_t	kernel_width,
		size_t	stride_h,
		size_t	stride_w,
		padding_type	padding,
		weight_initializer	weight_initializer_fn,
		weight_initializer	bias_initializer_fn = nullptr
	)

Appends a convolution layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
num_output_channels	The number of distinct filters in this layer
num_kernel_channels	The number of input features per "pixel"
kernel_size	The height and width of the kernel
weight_initializer_fn	Callback used to initialize the conv weights
bias_initializer_fn	Callback used to initialize the conv bias. If nullptr, then no bias vector is set.

add_exp()

void turi::neural_net::model_spec::add_exp	(	const std::string &	name,
		const std::string &	input
	)

Appends a layer that applies the unary function f(x) = e^x to its input.

Parameters

name	The name of the layer and its output
input	The name of the layer's input

add_expand_dims()

void turi::neural_net::model_spec::add_expand_dims	(	const std::string &	name,
		const std::string &	input,
		const std::vector< size_t > &	axes,
		const std::vector< size_t > &	inputVector,
		const std::vector< size_t > &	outputVector
	)

Appends an Expand Dims layer.

Parameters

name	The name of the layer and its output
input	The vector of names of the layer's input
axes	The axes to expand the layer on

add_flatten()

void turi::neural_net::model_spec::add_flatten	(	const std::string &	name,
		const std::string &	input
	)

Appends a layer that performs flatten normalization (along channel axis).

currently only supports channel first flattening, which means if the input order is [C, H, W], then output array will be [C * H * W, 1, 1], still C-major orderring. No underlying array storage will be changed.

Parameters

name	The name of the layer and its output
input	The name of the layer's input

add_gather()

void turi::neural_net::model_spec::add_gather	(	const std::string &	name,
		const std::vector< std::string > &	inputs
	)

Appends a Gather layer.

Parameters

name	The name of the layer and its output
inputs	The vector of names of the layer's inputs

add_get_shape()

void turi::neural_net::model_spec::add_get_shape	(	const std::string &	name,
		const std::string &	input
	)

Appends a Get Shape layer.

Parameters

name	The name of the layer and its output
input	The vector of names of the layer's input

add_inner_product()

void turi::neural_net::model_spec::add_inner_product	(	const std::string &	name,
		const std::string &	input,
		size_t	num_output_channels,
		size_t	num_input_channels,
		weight_initializer	weight_initializer_fn,
		weight_initializer	bias_initializer_fn = nullptr
	)

Appends an inner-product (dense, fully connected) layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
num_output_channels	Size of the output vector
num_input_channels	Size of the input vector
weight_initializer_fn	Callback used to initialize the weights
bias_initializer_fn	Callback used to initialize the bias. If nullptr, then no bias vector is set.

add_instancenorm()

void turi::neural_net::model_spec::add_instancenorm	(	const std::string &	name,
		const std::string &	input,
		size_t	num_channels,
		float	epsilon
	)

Appends an instance norm layer.

The beta is initialized to 0.f; the gamma is initialized to 1.f

Parameters

name	The name of the layer and its output
input	The name of the layer's input
num_channels	The C dimension of the input and output
epsilon	Added to the variance for each input before normalizing

add_leakyrelu()

void turi::neural_net::model_spec::add_leakyrelu	(	const std::string &	name,
		const std::string &	input,
		float	alpha
	)

Appends a leaky ReLU activation layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
alpha	Multiplied to negative inputs

add_lstm()

void turi::neural_net::model_spec::add_lstm	(	const std::string &	name,
		const std::string &	input,
		const std::string &	hidden_input,
		const std::string &	cell_input,
		const std::string &	hidden_output,
		const std::string &	cell_output,
		size_t	input_vector_size,
		size_t	output_vector_size,
		float	cell_clip_threshold,
		const lstm_weight_initializers &	initializers
	)

Appends an LSTM layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
hidden_input	The name of the initial hidden state
cell_input	The name of the initial cell state
hidden_output	The name of the resulting hidden state
cell_output	The name of the resulting cell state
input_vector_size	The size of the input vector
output_vector_size	The size of the output vector (hidden state and cell state)
cell_clip_threshold	Maximum magnitude of cell state values
initializers	LSTM weights

add_multiplication()

void turi::neural_net::model_spec::add_multiplication	(	const std::string &	name,
		const std::vector< std::string > &	inputs
	)

Appends a layer that performs elementwise multiplication.

Parameters

name	The name of the layer and its output
inputs	The names of the layer's inputs

add_nms_layer()

void turi::neural_net::model_spec::add_nms_layer	(	const std::string &	name,
		const std::vector< std::string > &	inputs,
		const std::vector< std::string > &	outputs,
		float	iou_threshold,
		float	confidence_threshold,
		size_t	max_boxes,
		bool	per_class_supression
	)

Appends a non maximum suppression layer.

Parameters

name	The name of the layer and its output
inputs	The name of the layer's inputs
outputs	The outputs of the layer
iou_thrsshold	The default value for the iou threshold
confidence_threshold	The default value for the confidence threshold
max_boxes	The maximum number of boxes you want NMS to run
per_class_suppression	When false, suppression happens for all classes.

add_padding()

void turi::neural_net::model_spec::add_padding	(	const std::string &	name,
		const std::string &	input,
		size_t	padding_top,
		size_t	padding_bottom,
		size_t	padding_left,
		size_t	padding_right,
		padding_policy	policy = padding_policy::REFLECTIVE
	)

Appends a padding layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
padding_top	The padding on the top
padding_bottom	The padding on the bottom
padding_left	The padding to the left
padding_right	The padding to the right
policy	The padding policy of zero, reflective, or replication

add_permute()

void turi::neural_net::model_spec::add_permute	(	const std::string &	name,
		const std::string &	input,
		const std::array< size_t, 4 > &	axis_permutation
	)

Appends a layer that transposes the dimensions of its input

Parameters

name	The name of the layer and its output
input	The name of the layer's input
axis_permutation	A permutation of [0, 1, 2, 3], describing how to rearrange the [Seq, C, H, W] input.

add_pooling()

void turi::neural_net::model_spec::add_pooling	(	const std::string &	name,
		const std::string &	input,
		size_t	kernel_height,
		size_t	kernel_width,
		size_t	stride_h,
		size_t	stride_w,
		padding_type	padding,
		bool	use_poolexcludepadding = false,
		pooling_type	pooling = pooling_type::MAX
	)

Appends a pooling layer. By default, it's a max pooling layer.

It can be of type:

• MAX
• AVERAGE
• L2

Parameters

pooling	this sets the type of pooling this layer performs.
use_poolexcludepadding	padded values are excluded from the count (denominator) when computing average pooling.

add_preprocessing()

void turi::neural_net::model_spec::add_preprocessing	(	const std::string &	feature_name,
		const float	image_scale
	)

Appends a preprocessing layer Now only support image scaling preprocessing though.

add_relu()

void turi::neural_net::model_spec::add_relu	(	const std::string &	name,
		const std::string &	input
	)

Appends a ReLU activation layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input

add_reshape()

void turi::neural_net::model_spec::add_reshape	(	const std::string &	name,
		const std::string &	input,
		const std::array< size_t, 4 > &	seq_c_h_w
	)

Appends a layer that reshapes its input.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
shape_c_h_w	The shape of the output

add_reshape_dynamic()

void turi::neural_net::model_spec::add_reshape_dynamic	(	const std::string &	name,
		const std::vector< std::string > &	inputs
	)

Appends a Reshape Dynamic layer.

Parameters

name	The name of the layer and its output
inputs	The vector of names of the layer's inputs

add_reshape_static()

void turi::neural_net::model_spec::add_reshape_static	(	const std::string &	name,
		const std::string &	input,
		const std::vector< size_t > &	targetShape
	)

Appends a Reshape Static layer.

Parameters

name	The name of the layer and its output
input	The vector of names of the layer's input
targetShape	The target shape

add_scale()

void turi::neural_net::model_spec::add_scale	(	const std::string &	name,
		const std::string &	input,
		const std::vector< size_t > &	shape_c_h_w,
		weight_initializer	scale_initializer_fn
	)

Appends a layer that performs elementwise multiplication between its input and some fixed weights.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
shape_c_h_w	The shape of the input and output
weight_initializer_fn	Callback used to initialize the weights

add_sigmoid()

void turi::neural_net::model_spec::add_sigmoid	(	const std::string &	name,
		const std::string &	input
	)

Appends a sigmoid activation layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input

add_slice_dynamic()

void turi::neural_net::model_spec::add_slice_dynamic	(	const std::string &	name,
		const std::vector< std::string > &	inputs
	)

Appends dynamic slicing.

Parameters

name	The name of the layer and its output
inputs	The name of the layer's inputs

add_softmax()

void turi::neural_net::model_spec::add_softmax	(	const std::string &	name,
		const std::string &	input
	)

Appends a layer that performs softmax normalization (along channel axis).

Parameters

name	The name of the layer and its output
input	The name of the layer's input

add_split_nd()

void turi::neural_net::model_spec::add_split_nd	(	const std::string &	name,
		const std::string &	input,
		size_t	axis,
		size_t	num_splits,
		const std::vector< size_t > &	split_sizes
	)

Appends an Split layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
axis	The axis to split the layer on
num_splits	The number of splits to perform
split_sizes	The size of each split

add_squeeze()

void turi::neural_net::model_spec::add_squeeze	(	const std::string &	name,
		const std::string &	input,
		const std::vector< size_t > &	axes,
		const std::vector< size_t > &	inputVector,
		const std::vector< size_t > &	outputVector
	)

Appends a Squeeze layer.

Parameters

name	The name of the layer and its output
input	The vector of names of the layer's input
axes	The axes to squeeze the layer on

add_transpose()

void turi::neural_net::model_spec::add_transpose	(	const std::string &	name,
		const std::string &	input,
		std::vector< size_t >	axes
	)

Appends an Transpose layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
axes	The ordering of the axes to transpose for instance {0, 2, 1, 3} would flip the channel and height axes

add_upsampling()

void turi::neural_net::model_spec::add_upsampling	(	const std::string &	name,
		const std::string &	input,
		size_t	scaling_x,
		size_t	scaling_y
	)

Appends an upsampling layer.

Parameters

name	The name of the layer and its output
input	The name of the layer's input
scaling_x	The upsample scale on the x axis
scaling_y	The upsample scale on the y axis

export_params_view()

float_array_map turi::neural_net::model_spec::export_params_view

(

)

const

Creates a shared_float_array view (weak reference) into the parameters of the model, indexed by layer name.

Returns

A dictionary whose keys are of the form "$layername_$paramname". The layer names are taken from the name field of each NeuralNetworkLayer containing a supported layer. The supported layers are ConvolutionLayerParams (with params "weight" (in NCHW order) and "bias") and BatchnormLayerParams (with params "gamma", "beta", "running_mean", and "running_var").

Exceptions

If	a NeuralNetworkLayer in the specification seems malformed (e.g. WeightParams with size inconsistent with declared layer shape).

To avoid copying data, the data backing the shared_float_array instances in the return value will only remain valid for the lifetime of this instance!

get_coreml_spec()

const CoreML::Specification::NeuralNetwork& turi::neural_net::model_spec::get_coreml_spec ( ) const

inline

Exposes the underlying CoreML proto.

Definition at line 88 of file model_spec.hpp.

has_layer_output()

bool turi::neural_net::model_spec::has_layer_output

(

const std::string &

layer_name

)

const

Determines whether the neural network contains a layer with the given output name.

In general, it is only safe to add a new layer that takes a named input if this method returns true for that name.

move_coreml_spec()

std::unique_ptr<CoreML::Specification::NeuralNetwork> turi::neural_net::model_spec::move_coreml_spec

(

)

&&

Transfer ownership of the underlying CoreML proto, invalidating the current instance (leaving it in a "moved-from" state).

(Note that this method may only be invoked from a model_spec&&)

update_params()

void turi::neural_net::model_spec::update_params	(	const float_array_map &	weights,
		bool	use_quantization = false
	)

Overwrites existing WeightParams values using the provided float_array values.

Parameters

weights	A dictionary whose keys follow the same naming scheme used by export_params_view.
use_quantization	If true, weights are stored in half precision.

Exceptions

If	a float_array's shape does not match the corresponding NeuralNetworkLayer.

---

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

• ml/neural_net/model_spec.hpp