Level 5 API

Design Comments

Essentials

enum [anonymous]::__anonymous86

Values:

CCV_CNNP_ACTIVATION_NONE
CCV_CNNP_ACTIVATION_RELU
CCV_CNNP_ACTIVATION_SOFTMAX
enum [anonymous]::__anonymous87

Values:

CCV_CNNP_NO_NORM
CCV_CNNP_BATCH_NORM
typedef struct ccv_cnnp_dataframe_s ccv_cnnp_dataframe_t
typedef struct ccv_cnnp_model_s ccv_cnnp_model_t

model type is an abstract type, you won’t interact with a naked model ever.

typedef struct ccv_cnnp_model_io_s *ccv_cnnp_model_io_t

With this type, now in NNC, we have 4 types that represents a “tensor”: ccv_nnc_tensor_t / ccv_nnc_tensor_view_t / ccv_nnc_tensor_multiview_t: a concrete tensor with memory allocated. ccv_nnc_tensor_symbol_t: a symbol representation of a tensor, with its data layout, device affinity, and type specified. ccv_nnc_tensor_variable_t: in dynamic graph, this represents a concrete tensor with memory allocated, but also associated with a recorded execution. ccv_cnnp_model_io_t: this is the most flexible one. No data layout, device affinity or type specified, the format has to be c / h / w, no batch size needed. This is a handle used by model API to associates model inputs / outputs.

ccv_cnnp_dataframe_new(void)
void ccv_cnnp_dataframe_free(ccv_cnnp_dataframe_t *const dataframe)
ccv_cnnp_input(void)

Create a naked input.

Return
A ccv_cnnp_model_io_t represents an input.

ccv_cnnp_model_apply(ccv_cnnp_model_t *const model, const ccv_cnnp_model_io_t *const inputs, const int input_size)

This method mimics Keras callable for model (thus, override __call__ method in Python class).

Return
A ccv_cnnp_model_io_t that represents the output of the given model.
Parameters
  • model: A model that we can apply a set of inputs to get one output.
  • inputs: The set of inputs.
  • input_size: The size of inputs array.

ccv_cnnp_model_new(const ccv_cnnp_model_io_t *const inputs, const int input_size, const ccv_cnnp_model_io_t *const outputs, const int output_size)

This method name is deceiving. It return a composed model, not a naked model. This composed model takes set of inputs, and run through various other models to arrive at the set of outputs.

Return
A composed model that takes inputs, and generate the outputs.
Parameters
  • inputs: The set of inputs.
  • input_size: The size of inputs array.
  • outputs: The set of outputs.
  • output_size: The size of outputs array.

ccv_cnnp_sequential_new(ccv_cnnp_model_t *const *const models, const int model_size)

This method returns a sequential model, which composed from a sequence of models.

Return
A composed model that applies these models one by one in sequence.
Parameters
  • models: The list of models, that takes one input, and emit one output, feeding into the subsequent one.
  • model_size: The size of the list.

void ccv_cnnp_model_compile(ccv_cnnp_model_t *const model, const ccv_nnc_tensor_param_t *const inputs, const int input_size, const ccv_nnc_cmd_t minimizer, const ccv_nnc_cmd_t loss)

Prepare the model to be trained, the input specifies the batch size etc. Input size technically is not needed, here is a safety check.

Parameters
  • model: The model to be compiled.
  • inputs: The tensor parameters for the model’s inputs, that can be used to derive all tensor shapes.
  • input_size: The size of the inputs array.
  • minimizer: The wrapped command that represents a particular optimization strategy.
  • loss: The wrapped command that computes the loss function.

void ccv_cnnp_model_dot(const ccv_cnnp_model_t *const model, const int flags, FILE *out)

Generate output that can be parsed by GraphViz (DOT language).

Parameters
  • model: The composed model.
  • flags: Either CCV_NNC_SHORT_DOT_GRAPH or CCV_NNC_LONG_DOT_GRAPH
  • out: The output file stream.

void ccv_cnnp_model_fit(ccv_cnnp_model_t *const model, ccv_nnc_tensor_t *const *const inputs, const int input_size, ccv_nnc_tensor_t *const *const fits, const int fit_size, ccv_nnc_tensor_t *const *const outputs, const int output_size, ccv_nnc_stream_context_t *const stream_context)

Fit a model to a given input / output.

Parameters
  • model: The composed model.
  • inputs: The input tensors.
  • input_size: The size of the input tensors array.
  • fits: The target tensors.
  • fit_size: The size of the target tensors array.
  • outputs: The actual outputs from the model.
  • output_size: The size of the outputs array.
  • stream_context: The stream where the fit can be executed upon.

void ccv_cnnp_model_evaluate(ccv_cnnp_model_t *const model, ccv_nnc_tensor_t *const *const inputs, const int input_size, ccv_nnc_tensor_t *const *const outputs, const int output_size, ccv_nnc_stream_context_t *const stream_context)

Evaluate model with output.

Parameters
  • model: The composed model.
  • inputs: The input tensors.
  • input_size: The size of the input tensors array.
  • outputs: The actual outputs from the model.
  • output_size: The size of the outputs array.
  • stream_context: The stream where the fit can be executed upon.

void ccv_cnnp_model_set_minimizer(ccv_cnnp_model_t *const model, const ccv_nnc_cmd_t minimizer)

Set a new minimizer for the model. This is useful when you need to update learn rate for stochastic gradient descent for example. This method can be called any time during the training process (after compilation).

Parameters
  • model: The composed model.
  • minimizer: The wrapped command that represents a new optimization strategy.

void ccv_cnnp_model_free(ccv_cnnp_model_t *const model)

Free a given model.

Parameters
  • model: The composed model.

ccv_cnnp_add(void)

Add multiple input tensors together.

Return
A model that can be applied with multiple inputs, and generate output that is a sum of the inputs.

ccv_cnnp_concat(void)

Concatenate input tensors together.

Return
A model that can be applied with multiple inputs, and generate output that is a concatenation of the inputs.

ccv_cnnp_identity(const ccv_cnnp_param_t params)

An identity layer that takes input and do nothing pass it as the output. Realistically, we use this because we want to apply some normalization / activation function on top of the input.

Return
A model that takes input and pass it as output.
Parameters
  • params: Parameters (such as hint and activation or norm).

ccv_cnnp_convolution(const int groups, const int filters, const int kdim[CCV_NNC_MAX_DIM_ALLOC], const ccv_cnnp_param_t params)

A convolution model.

Return
A convolution model.
Parameters
  • groups: The number of kernel groups in the model.
  • filters: The total number of filters in the model (filters = groups * per group filters).
  • kdim: The dimensions of the kernel.
  • params: Other parameters (such as hint and activation or norm).

ccv_cnnp_dense(const int count, const ccv_cnnp_param_t params)

A dense layer model.

Return
A dense layer model.
Parameters
  • count: The output dimension.
  • params: Other parameters (such as hint and activation or norm).

ccv_cnnp_max_pool(const int kdim[CCV_NNC_MAX_DIM_ALLOC], const ccv_cnnp_param_t params)

A max pool model.

Return
A max pool model.
Parameters
  • kdim: The pooling window dimension.
  • params: Other parameters (such as hint and activation or norm).

ccv_cnnp_average_pool(const int kdim[CCV_NNC_MAX_DIM_ALLOC], const ccv_cnnp_param_t params)

An average pool model.

Return
An average pool model.
Parameters
  • kdim: The pooling window dimension.
  • params: Other parameters (such as hint and activation or norm).

ccv_cnnp_reshape(const int dim[CCV_NNC_MAX_DIM_ALLOC])

Reshape an input into a different dimension.

Return
A reshape layer model.
Parameters
  • dim: The new dimension for the input.

ccv_cnnp_flatten(void)

Flatten an input tensor into a one dimensional array.

Return
A flatten layer model.

struct ccv_cnnp_param_t

Public Members

int no_bias

No bias term.

int norm

The normalizations can be applied after activation such as CCV_CNNP_BATCH_NORM.

int activation

The activations can be applied for the output, such as CCV_CNNP_ACTIVATION_RELU or CCV_CNNP_ACTIVATION_SOFTMAX.

ccv_nnc_hint_t hint

The hint for a particular operation