# Level 4 API¶

## Essentials¶

typedef struct ccv_nnc_dynamic_graph_s ccv_nnc_dynamic_graph_t

Opaque pointer to the dynamic graph structure.

typedef struct ccv_nnc_tensor_variable_s *ccv_nnc_tensor_variable_t

Masquerade this as if it is a on stack variable, there is a heap allocation but managed by the dynamic graph. The fact that ccv_nnc_tensor_variable_t is a pointer is an implementation detail. It should be treated as an opaque type throughout. We may later extends this to be some on-stack information or even just a uid.

ccv_nnc_dynamic_graph_new(void)

Create a dynamic graph.

Return
A newly created dynamic graph.

ccv_nnc_tensor_variable_alias_new(ccv_nnc_dynamic_graph_t *const graph, const ccv_nnc_tensor_variable_t tensor_variable, const int ofs[CCV_NNC_MAX_DIM_ALLOC], const int inc[CCV_NNC_MAX_DIM_ALLOC], const ccv_nnc_tensor_param_t info)

Create a new tensor variable that is an alias of a given tensor variable.

Return
New tensor variable that is an alias.
Parameters
• graph: The dynamic graph.
• tensor_variable: The tensor variable we are going to alias from.
• ofs: The offset on each of the dimension.
• inc: The line size of each dimension.
• info: The tensor parameters for the new alias.

ccv_nnc_tensor_from_variable(ccv_nnc_dynamic_graph_t *const graph, const ccv_nnc_tensor_variable_t tensor_variable)

Get the underlying tensor for the tensor variable. The tensor allocation may be performed when calling this method.

Return
The underlying tensor.
Parameters
• graph: The dynamic graph.
• tensor_variable: The tensor variable to get the underlying tensor.

void ccv_nnc_tensor_variable_set(ccv_nnc_dynamic_graph_t *const graph, const ccv_nnc_tensor_variable_t tensor_variable, ccv_nnc_tensor_t *const tensor)

Set a tensor on the tensor variable. Tensor variable doesn’t take over the life-cycle management of the tensor (in similar way as the tensor binds).

Parameters
• graph: The dynamic graph.
• tensor_variable: The tensor variable to set.
• tensor: The tensor that is going to be associated with the tensor variable.

int ccv_nnc_dynamic_graph_exec(ccv_nnc_dynamic_graph_t *const graph, const ccv_nnc_cmd_t cmd, const ccv_nnc_hint_t hint, const int flags, const ccv_nnc_tensor_variable_t *const inputs, const int input_size, ccv_nnc_tensor_variable_t *const outputs, const int output_size)

Execute a command with given tensor variables, the output is in the output tensor variables.

Parameters
• graph: The dynamic graph.
• cmd: The wrapped command.
• hint: The hint associated with the command.
• flags: A reserved field for flags.
• inputs: The input tensor variables array.
• input_size: The size of the input tensor variables array.
• outputs: The output tensor variables array.
• output_size: The size of the output tensor variables array.

void ccv_nnc_dynamic_graph_backward(ccv_nnc_dynamic_graph_t *const dynamic_graph, const ccv_nnc_tensor_variable_t f_variable, const ccv_nnc_tensor_variable_t df_optional, const ccv_nnc_tensor_variable_t *const inputs, const int input_size, ccv_nnc_tensor_variable_t *const outputs, const int output_size)

Compute the gradient of given tensor, with respect to the f. Thus, df / dt.

Parameters
• dynamic_graph: The dynamic graph.
• f_variable: The output losses.
• df_optional: The custom gradient for f. If not provided, will default to 1.
• inputs: The input variables.
• input_size: The size of the input variables array.
• outputs: The gradients with respect to the inputs.
• output_size: The size of the outputs array. Should be equal to the input_size.

void ccv_nnc_dynamic_graph_minimize(ccv_nnc_dynamic_graph_t *const dynamic_graph, const ccv_nnc_cmd_t minimizer, const ccv_nnc_tensor_variable_t *const losses, const int loss_size, const ccv_nnc_tensor_variable_t *const dlosses_optional, ccv_nnc_tensor_variable_t *const parameters, const int parameter_size, ccv_nnc_tensor_variable_t *const saved_aux)

Apply one step of minimization (most likely, a gradient descent) to the parameters with a given loss (or losses).

Parameters
• dynamic_graph: The dynamic graph.
• minimizer: The wrapped command that represents a particular optimization strategy.
• losses: The losses we are trying to minimize.
• loss_size: The size of the losses array.
• dlosses_optional: The custom gradient for losses. If not provided, will default to 1.
• parameters: The parameters to update.
• parameter_size: The size of parameters array.
• saved_aux: The aux variables to faciliate the minimizer. See ccv_nnc_minimizer_saved_aux_size.

void ccv_nnc_tensor_variable_free(ccv_nnc_dynamic_graph_t *const graph, const ccv_nnc_tensor_variable_t tensor_variable)

Dispose a tensor variable. You cannot do any computation against this tensor variable afterwards.

Parameters
• graph: The dynamic graph.
• tensor_variable: The tensor variable to be disposed.

void ccv_nnc_dynamic_graph_free(ccv_nnc_dynamic_graph_t *const graph)

Free the dynamic graph.

Parameters
• graph: The dynamic graph.

void ccv_nnc_dynamic_graph_dot(const ccv_nnc_dynamic_graph_t *const graph, const int flags, FILE *out)

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

Parameters
• graph: The dynamic graph.
• flags: Either CCV_NNC_SHORT_DOT_GRAPH or CCV_NNC_LONG_DOT_GRAPH
• out: The output file stream.

ccv_nnc_tensor_variable_new(ccv_nnc_dynamic_graph_t *const graph)

Create a new tensor variable without specified dimensions. Most likely this will be used as output, therefore, its shape can be derived.

Return
A newly created tensor variable reference.
Parameters
• graph: The dynamic graph.

ccv_nnc_tensor_variable_new(ccv_nnc_dynamic_graph_t *const graph, const ccv_nnc_tensor_param_t info)

Create a new tensor variable with tensor parameters.

Return
A newly created tensor variable reference.
Parameters
• graph: The dynamic graph.
• info: Tensor parameters.

ccv_nnc_tensor_constant_new(ccv_nnc_dynamic_graph_t *const graph)

Create a new tensor constant without specified dimensions. This may be used with ccv_nnc_tensor_variable_set. A constant cannot be an output with some inputs. It can be a output with no input (such as CCV_NNC_SET_FORWARD command). This is used so that we don’t need to keep memory of this constant because later we want to compute gradient of this constant. It is not legal to run ccv_nnc_dynamic_backward against a constant.

Return
A newly created tensor constant reference.
Parameters
• graph: The dynamic graph.

ccv_nnc_tensor_constant_new(ccv_nnc_dynamic_graph_t *const graph, const ccv_nnc_tensor_param_t info)

Create a new tensor constant with tensor parameters.

Return
A newly created tensor constant reference.
Parameters
• graph: The dynamic graph.
• info: Tensor parameters.