AI-MXNetCAPI
view release on metacpan or search on metacpan
typedef MXExecutor *ExecutorHandle;
/*! \brief handle a dataiter creator */
typedef MXDataIterCreator *DataIterCreator;
/*! \brief handle to a DataIterator */
typedef MXDataIter *DataIterHandle;
/*! \brief handle to KVStore */
typedef MXKVStore *KVStoreHandle;
/*! \brief handle to RecordIO */
typedef MXRecordIO *RecordIOHandle;
/*! \brief handle to MXRtc*/
typedef MXRtc *RtcHandle;
/*! \brief handle to cached operator */
typedef MXCachedOp *CachedOpHandle;
typedef void (*ExecutorMonitorCallback)(const char*,
NDArrayHandle,
void *);
struct NativeOpInfo {
void (*forward)(int, float**, int*, unsigned**, int*, void*);
void (*backward)(int, float**, int*, unsigned**, int*, void*);
void (*infer_shape)(int, int*, unsigned**, void*);
void (*list_outputs)(char***, void*);
void (*list_arguments)(char***, void*);
// all functions also pass a payload void* pointer
void* p_forward;
void* p_backward;
void* p_infer_shape;
void* p_list_outputs;
void* p_list_arguments;
};
struct NDArrayOpInfo {
bool (*forward)(int, void**, int*, void*);
bool (*backward)(int, void**, int*, void*);
bool (*infer_shape)(int, int*, unsigned**, void*);
bool (*list_outputs)(char***, void*);
bool (*list_arguments)(char***, void*);
bool (*declare_backward_dependency)(const int*, const int*, const int*,
int*, int**, void*);
// all functions also pass a payload void* pointer
void* p_forward;
void* p_backward;
void* p_infer_shape;
void* p_list_outputs;
void* p_list_arguments;
void* p_declare_backward_dependency;
};
/*!
* \brief return str message of the last error
* all function in this file will return 0 when success
* and -1 when an error occured,
* MXGetLastError can be called to retrieve the error
*
* this function is threadsafe and can be called by different thread
* \return error info
*/
const char *MXGetLastError();
//-------------------------------------
// Part 0: Global State setups
//-------------------------------------
/*!
* \brief Seed the global random number generators in mxnet.
* \param seed the random number seed.
* \return 0 when success, -1 when failure happens.
*/
int MXRandomSeed(int seed);
/*!
* \brief Notify the engine about a shutdown,
* This can help engine to print less messages into display.
*
* User do not have to call this function.
* \return 0 when success, -1 when failure happens.
*/
int MXNotifyShutdown();
/*!
* \brief Set up configuration of profiler
* \param mode indicate the working mode of profiler,
* record anly symbolic operator when mode == 0,
* record all operator when mode == 1
* \param filename where to save trace file
* \return 0 when success, -1 when failure happens.
*/
int MXSetProfilerConfig(int mode, const char* filename);
/*!
* \brief Set up state of profiler
* \param state indicate the working state of profiler,
* profiler not running when state == 0,
* profiler running when state == 1
* \return 0 when success, -1 when failure happens.
*/
int MXSetProfilerState(int state);
/*! \brief Save profile and stop profiler */
int MXDumpProfile();
/*! \brief Set the number of OMP threads to use */
int MXSetNumOMPThreads(int thread_num);
//-------------------------------------
// Part 1: NDArray creation and deletion
//-------------------------------------
/*!
* \brief create a NDArray handle that is not initialized
* can be used to pass in as mutate variables
* to hold the result of NDArray
* \param out the returning handle
* \return 0 when success, -1 when failure happens
*/
int MXNDArrayCreateNone(NDArrayHandle *out);
/*!
* \brief create a NDArray with specified shape
* \param shape the pointer to the shape
* \param ndim the dimension of the shape
* \param dev_type device type, specify device we want to take
* \param dev_id the device id of the specific device
* \param delay_alloc whether to delay allocation until
* the ndarray is first mutated
* \param out the returning handle
* \return 0 when success, -1 when failure happens
* \param ndim number of dimensions of new shape
* \param dims new shape
* \param out the NDArrayHandle of reshaped NDArray
* \return 0 when success, -1 when failure happens
*/
int MXNDArrayReshape(NDArrayHandle handle,
int ndim,
int *in,
NDArrayHandle *out);
/*!
* \brief get the shape of the array
* \param handle the handle to the ndarray
* \param out_dim the output dimension
* \param out_pdata pointer holder to get data pointer of the shape
* \return 0 when success, -1 when failure happens
*/
int MXNDArrayGetShape(NDArrayHandle handle,
mx_uint *out_dim,
const mx_uint **out_pdata);
/*!
* \brief get the content of the data in NDArray
* \param handle the handle to the ndarray
* \param out_pdata pointer holder to get pointer of data
* \return 0 when success, -1 when failure happens
*/
int MXNDArrayGetData(NDArrayHandle handle,
void **out_pdata);
/*!
* \brief get the type of the data in NDArray
* \param handle the handle to the ndarray
* \param out_dtype pointer holder to get type of data
* \return 0 when success, -1 when failure happens
*/
int MXNDArrayGetDType(NDArrayHandle handle,
int *out);
/*!
* \brief get the context of the NDArray
* \param handle the handle to the ndarray
* \param out_dev_type the output device type
* \param out_dev_id the output device id
* \return 0 when success, -1 when failure happens
*/
int MXNDArrayGetContext(NDArrayHandle handle,
int *out,
int *out);
/*!
* \brief return gradient buffer attached to this NDArray
* \param handle NDArray handle
* \return 0 when success, -1 when failure happens
*/
int MXNDArrayGetGrad(NDArrayHandle handle, NDArrayHandle *out);
/*!
* \brief detach and ndarray from computation graph by clearing entry_
* \param handle NDArray handle
* \return 0 when success, -1 when failure happens
*/
int MXNDArrayDetach(NDArrayHandle handle, NDArrayHandle *out);
/*!
* \brief set the flag for gradient array state.
* \param handle NDArray handle
* \param state the new state.
* \return 0 when success, -1 when failure happens
*/
int MXNDArraySetGradState(NDArrayHandle handle, int state);
/*!
* \brief set the flag for gradient array state.
* \param handle NDArray handle
* \param state the new state.
* \return 0 when success, -1 when failure happens
*/
int MXNDArrayGetGradState(NDArrayHandle handle, int *out);
//--------------------------------
// Part 2: functions on NDArray
//--------------------------------
/*!
* \brief list all the available functions handles
* most user can use it to list all the needed functions
* \param out_size the size of returned array
* \param out_array the output function array
* \return 0 when success, -1 when failure happens
*/
int MXListFunctions(mx_uint *out_size,
FunctionHandle **out_array);
/*!
* \brief get the function handle by name
* \param name the name of the function
* \param out the corresponding function handle
* \return 0 when success, -1 when failure happens
*/
int MXGetFunction(const char *name,
FunctionHandle *out);
/*!
* \brief Get the information of the function handle.
* \param fun The function handle.
* \param name The returned name of the function.
* \param description The returned description of the function.
* \param num_args Number of arguments.
* \param arg_names Name of the arguments.
* \param arg_type_infos Type information about the arguments.
* \param arg_descriptions Description information about the arguments.
* \param return_type Return type of the function.
* \return 0 when success, -1 when failure happens
*/
int MXFuncGetInfo(FunctionHandle fun,
const char **name,
const char **description,
mx_uint *num_args,
const char ***arg_names,
const char ***arg_type_infos,
const char ***arg_descriptions
);
/*!
* \brief get the argument requirements of the function
* \param fun input function handle
* \param num_use_vars how many NDArrays to be passed in as used_vars
* \param num_scalars scalar variable is needed
* \param num_mutate_vars how many NDArrays to be passed in as mutate_vars
* \param type_mask the type mask of this function
* \return 0 when success, -1 when failure happens
* \sa MXFuncInvoke
*/
int MXFuncDescribe(FunctionHandle fun,
mx_uint *out,
mx_uint *out,
mx_uint *out,
int *out);
/*!
* \brief invoke a function, the array size of passed in arguments
* must match the values in the
* \param fun the function
* \param use_vars the normal arguments passed to function
* \param scalar_args the scalar qarguments
* \param mutate_vars the mutate arguments
* \return 0 when success, -1 when failure happens
* \sa MXFuncDescribeArgs
*/
int MXFuncInvoke(FunctionHandle fun,
NDArrayHandle *in,
mx_float *in,
NDArrayHandle *in);
/*!
* \brief invoke a function, the array size of passed in arguments
* must match the values in the
* \param fun the function
* \param use_vars the normal arguments passed to function
* \param scalar_args the scalar qarguments
* \param mutate_vars the mutate arguments
* \param num_params number of keyword parameters
* \param param_keys keys for keyword parameters
* \param param_vals values for keyword parameters
* \return 0 when success, -1 when failure happens
* \sa MXFuncDescribeArgs
*/
int MXFuncInvokeEx(FunctionHandle fun,
NDArrayHandle *in,
mx_float *in,
NDArrayHandle *in,
int num_params,
char **keys,
char **vals);
/*!
* \brief invoke a nnvm op and imperative function
* \param creator the op
* \param num_inputs number of input NDArrays
* \param inputs input NDArrays
* \param num_outputs number of output NDArrays
* \param outputs output NDArrays
* \param num_params number of keyword parameters
* \param param_keys keys for keyword parameters
* \param param_vals values for keyword parameters
* \return 0 when success, -1 when failure happens
*/
int MXImperativeInvoke(AtomicSymbolCreator in,
int num_inputs,
NDArrayHandle *in,
int *out_size,
NDArrayHandle **out_array,
int num_params,
const char **keys,
const char **vals);
/*!
* \brief set whether to record operator for autograd
* \param is_train 1 when training, 0 when testing
* \param prev returns the previous status before this set.
* \return 0 when success, -1 when failure happens
*/
int MXAutogradSetIsTraining(int is_training, int* out);
/*!
* \brief mark NDArrays as variables to compute gradient for autograd
* \param num_var number of variable NDArrays
* \param var_handles variable NDArrays
* \return 0 when success, -1 when failure happens
*/
int MXAutogradMarkVariables(mx_uint num_var,
NDArrayHandle *in,
mx_uint *in,
NDArrayHandle *in);
/*!
* \brief compute the gradient of outputs w.r.t variables
* \param num_output number of output NDArray
* \param output_handles output NDArrays
* \return 0 when success, -1 when failure happens
*/
int MXAutogradComputeGradient(mx_uint num_output,
NDArrayHandle* in);
/*!
* \brief compute the gradient of outputs w.r.t variabels
* \param num_output number of output NDArray
* \param output_handles output NDArrays
* \param ograd_handles head gradient for NDArrays
* \param retain_graph whether to keep the graph after backward
* \return 0 when success, -1 when failure happens
*/
int MXAutogradBackward(mx_uint num_output,
NDArrayHandle* in,
NDArrayHandle* in,
int retain_graph);
/*!
* \brief create cached operator
*/
int MXCreateCachedOp(SymbolHandle handle,
CachedOpHandle *out);
/*!
* \brief free cached operator
*/
int MXFreeCachedOp(CachedOpHandle handle);
/*!
* \brief invoke cached operator
*/
int MXInvokeCachedOp(CachedOpHandle handle,
int num_inputs,
NDArrayHandle *in,
int *out_size,
NDArrayHandle **out_array);
//--------------------------------------------
// Part 3: symbolic configuration generation
//--------------------------------------------
/*!
* \brief list all the available operator names, include entries.
* \param out_size the size of returned array
* \param out_array the output operator name array.
* \return 0 when success, -1 when failure happens
*/
* \brief Save a symbol into a json file.
* \param symbol the input symbol.
* \param fname the file name.
* \return 0 when success, -1 when failure happens
*/
int MXSymbolSaveToFile(SymbolHandle symbol, const char *fname);
/*!
* \brief Save a symbol into a json string
* \param symbol the input symbol.
* \param out_json output json string.
* \return 0 when success, -1 when failure happens
*/
int MXSymbolSaveToJSON(SymbolHandle symbol, const char **out);
/*!
* \brief Free the symbol handle.
* \param symbol the symbol
* \return 0 when success, -1 when failure happens
*/
int MXSymbolFree(SymbolHandle symbol);
/*!
* \brief Copy the symbol to another handle
* \param symbol the source symbol
* \param out used to hold the result of copy
* \return 0 when success, -1 when failure happens
*/
int MXSymbolCopy(SymbolHandle symbol, SymbolHandle *out);
/*!
* \brief Print the content of symbol, used for debug.
* \param symbol the symbol
* \param out_str pointer to hold the output string of the printing.
* \return 0 when success, -1 when failure happens
*/
int MXSymbolPrint(SymbolHandle symbol, const char **out);
/*!
* \brief Get string name from symbol
* \param symbol the source symbol
* \param out The result name.
* \param success Whether the result is contained in out.
* \return 0 when success, -1 when failure happens
*/
int MXSymbolGetName(SymbolHandle symbol,
const char** out,
int *out);
/*!
* \brief Get string attribute from symbol
* \param symbol the source symbol
* \param key The key of the symbol.
* \param out The result attribute, can be NULL if the attribute do not exist.
* \param success Whether the result is contained in out.
* \return 0 when success, -1 when failure happens
*/
int MXSymbolGetAttr(SymbolHandle symbol,
const char* key,
const char** out,
int *out);
/*!
* \brief Set string attribute from symbol.
* NOTE: Setting attribute to a symbol can affect the semantics(mutable/immutable) of symbolic graph.
*
* Safe recommendaton: use immutable graph
* - Only allow set attributes during creation of new symbol as optional parameter
*
* Mutable graph (be careful about the semantics):
* - Allow set attr at any point.
* - Mutating an attribute of some common node of two graphs can cause confusion from user.
*
* \param symbol the source symbol
* \param key The key of the symbol.
* \param value The value to be saved.
* \return 0 when success, -1 when failure happens
*/
int MXSymbolSetAttr(SymbolHandle symbol,
const char* in,
const char* in);
/*!
* \brief Get all attributes from symbol, including all descendents.
* \param symbol the source symbol
* \param out_size The number of output attributes
* \param out 2*out_size strings representing key value pairs.
* \return 0 when success, -1 when failure happens
*/
int MXSymbolListAttr(SymbolHandle symbol,
mx_uint *out_size,
const char*** out_array2);
/*!
* \brief Get all attributes from symbol, excluding descendents.
* \param symbol the source symbol
* \param out_size The number of output attributes
* \param out 2*out_size strings representing key value pairs.
* \return 0 when success, -1 when failure happens
*/
int MXSymbolListAttrShallow(SymbolHandle symbol,
mx_uint *out_size,
const char*** out_array2);
/*!
* \brief List arguments in the symbol.
* \param symbol the symbol
* \param out_size output size
* \param out_str_array pointer to hold the output string array
* \return 0 when success, -1 when failure happens
*/
int MXSymbolListArguments(SymbolHandle symbol,
mx_uint *out_size,
const char ***out_array);
/*!
* \brief List returns in the symbol.
* \param symbol the symbol
* \param out_size output size
* \param out_str_array pointer to hold the output string array
* \return 0 when success, -1 when failure happens
*/
int MXSymbolListOutputs(SymbolHandle symbol,
mx_uint *out_size,
const char ***out_array);
/*!
* \brief Get a symbol that contains all the internals.
* \param symbol The symbol
* \param out The output symbol whose outputs are all the internals.
* \return 0 when success, -1 when failure happens
*/
int MXSymbolGetInternals(SymbolHandle symbol,
SymbolHandle *out);
/*!
* \brief Get a symbol that contains only direct children.
* \param aux_states auxiliary states array
* \param shared_exec input executor handle for memory sharing
* \param out output executor handle
* \return 0 when success, -1 when failure happens
*/
int MXExecutorBindEX(SymbolHandle symbol_handle,
int dev_type,
int dev_id,
mx_uint num_map_keys,
const char** in,
const int* in,
const int* in,
mx_uint len,
NDArrayHandle *in,
NDArrayHandle *in,
mx_uint *in,
mx_uint aux_states_len,
NDArrayHandle *in,
ExecutorHandle shared_exec,
ExecutorHandle *out);
int MXExecutorSimpleBind(SymbolHandle symbol_handle,
int dev_type,
int dev_id,
const mx_uint num_g2c_keys,
const char** in, // g2c_keys,
const int* in, // g2c_dev_types,
const int* in, // g2c_dev_ids,
const mx_uint provided_grad_req_list_len,
const char** in, // provided_grad_req_names,
const char** in, // provided_grad_req_types,
const mx_uint num_provided_arg_shapes,
const char** in, // provided_arg_shape_names,
const mx_uint* in, // provided_arg_shape_data,
const mx_uint* in, // provided_arg_shape_idx,
const mx_uint num_provided_arg_dtypes,
const char** in, // provided_arg_dtype_names,
const int* in, // provided_arg_dtypes,
const mx_uint num_shared_arg_names,
const char** in, // shared_arg_name_list,
//------------
int* shared_buffer_len,
const char** shared_buffer_name_list,
NDArrayHandle* shared_buffer_handle_list,
const char*** updated_shared_buffer_name_list,
NDArrayHandle** updated_shared_buffer_handle_list,
//------------------
mx_uint* num_in_args,
NDArrayHandle** in_args,
NDArrayHandle** arg_grads,
//-----------------
mx_uint* num_aux_states,
NDArrayHandle** aux_states,
//----------
ExecutorHandle shared_exec_handle,
ExecutorHandle* out
);
/*!
* \brief set a call back to notify the completion of operation
*/
int MXExecutorSetMonitorCallback(ExecutorHandle handle,
ExecutorMonitorCallback callback,
void* callback_handle);
//--------------------------------------------
// Part 5: IO Interface
//--------------------------------------------
/*!
* \brief List all the available iterator entries
* \param out_size the size of returned iterators
* \param out_array the output iteratos entries
* \return 0 when success, -1 when failure happens
*/
int MXListDataIters(mx_uint *out_size,
DataIterCreator **out_array);
/*!
* \brief Init an iterator, init with parameters
* the array size of passed in arguments
* \param handle of the iterator creator
* \param num_param number of parameter
* \param keys parameter keys
* \param vals parameter values
* \param out resulting iterator
* \return 0 when success, -1 when failure happens
*/
int MXDataIterCreateIter(DataIterCreator handle,
mx_uint num_param,
const char **keys,
const char **vals,
DataIterHandle *out);
/*!
* \brief Get the detailed information about data iterator.
* \param creator the DataIterCreator.
* \param name The returned name of the creator.
* \param description The returned description of the symbol.
* \param num_args Number of arguments.
* \param arg_names Name of the arguments.
* \param arg_type_infos Type informations about the arguments.
* \param arg_descriptions Description information about the arguments.
* \return 0 when success, -1 when failure happens
*/
int MXDataIterGetIterInfo(DataIterCreator creator,
const char **name,
const char **description,
mx_uint *num_args,
const char ***arg_names,
const char ***arg_type_infos,
const char ***arg_descriptions);
/*!
* \brief Free the handle to the IO module
* \param handle the handle pointer to the data iterator
* \return 0 when success, -1 when failure happens
*/
int MXDataIterFree(DataIterHandle handle);
/*!
* \brief Move iterator to next position
* \param handle the handle to iterator
* \param out return value of next
* \return 0 when success, -1 when failure happens
*/
int MXDataIterNext(DataIterHandle handle,
int *out);
/*!
* \brief Call iterator.Reset
* \param handle the handle to iterator
* \return 0 when success, -1 when failure happens
*/
int MXDataIterBeforeFirst(DataIterHandle handle);
/*!
* \brief Get the handle to the NDArray of underlying data
* \param handle the handle pointer to the data iterator
* \param out handle to underlying data NDArray
* \return 0 when success, -1 when failure happens
*/
int MXDataIterGetData(DataIterHandle handle,
NDArrayHandle *out);
/*!
* \brief Get the image index by array.
* \param handle the handle pointer to the data iterator
* \param out_index output index of the array.
* \param out_size output size of the array.
* \return 0 when success, -1 when failure happens
*/
int MXDataIterGetIndex(DataIterHandle handle,
uint64_t **out_index,
uint64_t *out_size);
/*!
* \brief Get the padding number in current data batch
* \param handle the handle pointer to the data iterator
* \param pad pad number ptr
* \return 0 when success, -1 when failure happens
*/
int MXDataIterGetPadNum(DataIterHandle handle,
int *out);
/*!
* \brief Get the handle to the NDArray of underlying label
* \param handle the handle pointer to the data iterator
* \param out the handle to underlying label NDArray
* \return 0 when success, -1 when failure happens
*/
int MXDataIterGetLabel(DataIterHandle handle,
NDArrayHandle *out);
//--------------------------------------------
// Part 6: basic KVStore interface
//--------------------------------------------
/*!
* \brief Initialized ps-lite environment variables
* \param num_vars number of variables to initialize
* \param keys environment keys
* \param vals environment values
*/
int MXInitPSEnv(mx_uint num_vars,
const char **keys,
const char **vals);
/*!
* \brief Create a kvstore
* \param type the type of KVStore
* \param out The output type of KVStore
* \return 0 when success, -1 when failure happens
*/
( run in 1.372 second using v1.01-cache-2.11-cpan-cdf2f3d4e48 )