Go to the documentation of this file.
9 /* Note: Make sure to use slash-asterisk form of comments in this file
10  (like this one). Do not use double-slash (//). */
12 #ifndef TREELITE_C_API_H_
13 #define TREELITE_C_API_H_
15 #include "c_api_common.h"
23 typedef void* DMatrixHandle;
25 typedef void* ModelHandle;
27 typedef void* TreeBuilderHandle;
29 typedef void* ModelBuilderHandle;
31 typedef void* AnnotationHandle;
33 typedef void* CompilerHandle;
50 TREELITE_DLL int TreeliteDMatrixCreateFromFile(const char* path,
51  const char* format,
52  int nthread,
53  int verbose,
54  DMatrixHandle* out);
65 TREELITE_DLL int TreeliteDMatrixCreateFromCSR(const float* data,
66  const unsigned* col_ind,
67  const size_t* row_ptr,
68  size_t num_row,
69  size_t num_col,
70  DMatrixHandle* out);
80 TREELITE_DLL int TreeliteDMatrixCreateFromMat(const float* data,
81  size_t num_row,
82  size_t num_col,
83  float missing_value,
84  DMatrixHandle* out);
93 TREELITE_DLL int TreeliteDMatrixGetDimension(DMatrixHandle handle,
94  size_t* out_num_row,
95  size_t* out_num_col,
96  size_t* out_nelem);
105 TREELITE_DLL int TreeliteDMatrixGetPreview(DMatrixHandle handle,
106  const char** out_preview);
117 TREELITE_DLL int TreeliteDMatrixGetArrays(DMatrixHandle handle,
118  const float** out_data,
119  const uint32_t** out_col_ind,
120  const size_t** out_row_ptr);
127 TREELITE_DLL int TreeliteDMatrixFree(DMatrixHandle handle);
145 TREELITE_DLL int TreeliteAnnotateBranch(ModelHandle model,
146  DMatrixHandle dmat,
147  int nthread,
148  int verbose,
149  AnnotationHandle* out);
156 TREELITE_DLL int TreeliteAnnotationSave(AnnotationHandle handle,
157  const char* path);
163 TREELITE_DLL int TreeliteAnnotationFree(AnnotationHandle handle);
177 TREELITE_DLL int TreeliteCompilerCreate(const char* name,
178  CompilerHandle* out);
186 TREELITE_DLL int TreeliteCompilerSetParam(CompilerHandle handle,
187  const char* name,
188  const char* value);
208 TREELITE_DLL int TreeliteCompilerGenerateCode(CompilerHandle compiler,
209  ModelHandle model,
210  int verbose,
211  const char* dirpath);
217 TREELITE_DLL int TreeliteCompilerFree(CompilerHandle handle);
232 TREELITE_DLL int TreeliteLoadLightGBMModel(const char* filename,
233  ModelHandle* out);
241 TREELITE_DLL int TreeliteLoadXGBoostModel(const char* filename,
242  ModelHandle* out);
250 TREELITE_DLL int TreeliteLoadXGBoostModelFromMemoryBuffer(const void* buf,
251  size_t len,
252  ModelHandle* out);
261 TREELITE_DLL int TreeliteLoadProtobufModel(const char* filename,
262  ModelHandle* out);
271 TREELITE_DLL int TreeliteExportProtobufModel(const char* filename,
272  ModelHandle model);
279 TREELITE_DLL int TreeliteQueryNumTree(ModelHandle handle, size_t* out);
286 TREELITE_DLL int TreeliteQueryNumFeature(ModelHandle handle, size_t* out);
293 TREELITE_DLL int TreeliteQueryNumOutputGroups(ModelHandle handle, size_t* out);
301 TREELITE_DLL int TreeliteSetTreeLimit(ModelHandle handle, size_t limit);
308 TREELITE_DLL int TreeliteFreeModel(ModelHandle handle);
321 TREELITE_DLL int TreeliteCreateTreeBuilder(TreeBuilderHandle* out);
327 TREELITE_DLL int TreeliteDeleteTreeBuilder(TreeBuilderHandle handle);
334 TREELITE_DLL int TreeliteTreeBuilderCreateNode(TreeBuilderHandle handle,
335  int node_key);
342 TREELITE_DLL int TreeliteTreeBuilderDeleteNode(TreeBuilderHandle handle,
343  int node_key);
350 TREELITE_DLL int TreeliteTreeBuilderSetRootNode(TreeBuilderHandle handle,
351  int node_key);
368  TreeBuilderHandle handle,
369  int node_key, unsigned feature_id,
370  const char* opname,
371  double threshold, int default_left,
372  int left_child_key,
373  int right_child_key);
391  TreeBuilderHandle handle,
392  int node_key, unsigned feature_id,
393  const unsigned int* left_categories,
394  size_t left_categories_len,
395  int default_left,
396  int left_child_key,
397  int right_child_key);
406 TREELITE_DLL int TreeliteTreeBuilderSetLeafNode(TreeBuilderHandle handle,
407  int node_key,
408  double leaf_value);
421  int node_key,
422  const double* leaf_vector,
423  size_t leaf_vector_len);
439 TREELITE_DLL int TreeliteCreateModelBuilder(int num_feature,
440  int num_output_group,
441  int random_forest_flag,
442  ModelBuilderHandle* out);
451  const char* name,
452  const char* value);
458 TREELITE_DLL int TreeliteDeleteModelBuilder(ModelBuilderHandle handle);
472 TREELITE_DLL int TreeliteModelBuilderInsertTree(ModelBuilderHandle handle,
473  TreeBuilderHandle tree_builder,
474  int index);
482 TREELITE_DLL int TreeliteModelBuilderGetTree(ModelBuilderHandle handle,
483  int index,
484  TreeBuilderHandle *out);
491 TREELITE_DLL int TreeliteModelBuilderDeleteTree(ModelBuilderHandle handle,
492  int index);
501  ModelHandle* out);
504 #endif /* TREELITE_C_API_H_ */
int TreeliteModelBuilderSetModelParam(ModelBuilderHandle handle, const char *name, const char *value)
Set a model parameter.
int TreeliteModelBuilderGetTree(ModelBuilderHandle handle, int index, TreeBuilderHandle *out)
Get a reference to a tree in the ensemble.
int TreeliteLoadXGBoostModel(const char *filename, ModelHandle *out)
load a model file generated by XGBoost (dmlc/xgboost). The model file must contain a decision tree en...
int TreeliteFreeModel(ModelHandle handle)
delete model from memory
int TreeliteAnnotationSave(AnnotationHandle handle, const char *path)
save branch annotation to a JSON file
int TreeliteQueryNumTree(ModelHandle handle, size_t *out)
Query the number of trees in the model.
int TreeliteDMatrixCreateFromCSR(const float *data, const unsigned *col_ind, const size_t *row_ptr, size_t num_row, size_t num_col, DMatrixHandle *out)
create DMatrix from a (in-memory) CSR matrix
int TreeliteDMatrixFree(DMatrixHandle handle)
delete DMatrix from memory
int TreeliteModelBuilderDeleteTree(ModelBuilderHandle handle, int index)
Remove a tree from the ensemble.
int TreeliteCompilerSetParam(CompilerHandle handle, const char *name, const char *value)
set a parameter for a compiler
int TreeliteDeleteModelBuilder(ModelBuilderHandle handle)
Delete a model builder from memory.
int TreeliteTreeBuilderSetCategoricalTestNode(TreeBuilderHandle handle, int node_key, unsigned feature_id, const unsigned int *left_categories, size_t left_categories_len, int default_left, int left_child_key, int right_child_key)
Turn an empty node into a test node with categorical split. A list defines all categories that would ...
int TreeliteCreateTreeBuilder(TreeBuilderHandle *out)
Create a new tree builder.
int TreeliteAnnotationFree(AnnotationHandle handle)
delete branch annotation from memory
int TreeliteAnnotateBranch(ModelHandle model, DMatrixHandle dmat, int nthread, int verbose, AnnotationHandle *out)
annotate branches in a given model using frequency patterns in the training data. ...
int TreeliteQueryNumOutputGroups(ModelHandle handle, size_t *out)
Query the number of output groups of the model.
int TreeliteDMatrixCreateFromMat(const float *data, size_t num_row, size_t num_col, float missing_value, DMatrixHandle *out)
create DMatrix from a (in-memory) dense matrix
int TreeliteSetTreeLimit(ModelHandle handle, size_t limit)
keep first N trees of model, limit must smaller than number of trees.
int TreeliteModelBuilderInsertTree(ModelBuilderHandle handle, TreeBuilderHandle tree_builder, int index)
Insert a tree at specified location.
int TreeliteDMatrixGetArrays(DMatrixHandle handle, const float **out_data, const uint32_t **out_col_ind, const size_t **out_row_ptr)
extract three arrays (data, col_ind, row_ptr) that define a DMatrix.
int TreeliteTreeBuilderSetRootNode(TreeBuilderHandle handle, int node_key)
Set a node as the root of a tree.
void * TreeBuilderHandle
handle to tree builder class
Definition: c_api.h:27
int TreeliteDeleteTreeBuilder(TreeBuilderHandle handle)
Delete a tree builder from memory.
void * AnnotationHandle
handle to branch annotation data
Definition: c_api.h:31
int TreeliteModelBuilderCommitModel(ModelBuilderHandle handle, ModelHandle *out)
finalize the model and produce the in-memory representation
int TreeliteCompilerGenerateCode(CompilerHandle compiler, ModelHandle model, int verbose, const char *dirpath)
generate prediction code from a tree ensemble model. The code will be C99 compliant. One header file (.h) will be generated, along with one or more source files (.c).
int TreeliteCreateModelBuilder(int num_feature, int num_output_group, int random_forest_flag, ModelBuilderHandle *out)
Create a new model builder.
int TreeliteTreeBuilderSetLeafVectorNode(TreeBuilderHandle handle, int node_key, const double *leaf_vector, size_t leaf_vector_len)
Turn an empty node into a leaf vector node The leaf vector (collection of multiple leaf weights per l...
int TreeliteLoadXGBoostModelFromMemoryBuffer(const void *buf, size_t len, ModelHandle *out)
load an XGBoost model from a memory buffer.
int TreeliteDMatrixGetPreview(DMatrixHandle handle, const char **out_preview)
produce a human-readable preview of a DMatrix Will print first and last 25 non-zero entries...
void * ModelHandle
handle to a decision tree ensemble model
Definition: c_api.h:25
int TreeliteLoadLightGBMModel(const char *filename, ModelHandle *out)
load a model file generated by LightGBM (Microsoft/LightGBM). The model file must contain a decision ...
void * DMatrixHandle
handle to a data matrix
Definition: c_api.h:23
int TreeliteLoadProtobufModel(const char *filename, ModelHandle *out)
load a model in Protocol Buffers format. Protocol Buffers (google/protobuf) is a language- and platfo...
int TreeliteTreeBuilderSetNumericalTestNode(TreeBuilderHandle handle, int node_key, unsigned feature_id, const char *opname, double threshold, int default_left, int left_child_key, int right_child_key)
Turn an empty node into a test node with numerical split. The test is in the form [feature value] OP ...
int TreeliteCompilerCreate(const char *name, CompilerHandle *out)
create a compiler with a given name
int TreeliteExportProtobufModel(const char *filename, ModelHandle model)
export a model in Protocol Buffers format. Protocol Buffers (google/protobuf) is a language- and plat...
int TreeliteTreeBuilderDeleteNode(TreeBuilderHandle handle, int node_key)
Remove a node from a tree.
int TreeliteQueryNumFeature(ModelHandle handle, size_t *out)
Query the number of features used in the model.
int TreeliteDMatrixGetDimension(DMatrixHandle handle, size_t *out_num_row, size_t *out_num_col, size_t *out_nelem)
get dimensions of a DMatrix
void * ModelBuilderHandle
handle to ensemble builder class
Definition: c_api.h:29
void * CompilerHandle
handle to compiler class
Definition: c_api.h:33
int TreeliteTreeBuilderSetLeafNode(TreeBuilderHandle handle, int node_key, double leaf_value)
Turn an empty node into a leaf node.
int TreeliteDMatrixCreateFromFile(const char *path, const char *format, int nthread, int verbose, DMatrixHandle *out)
create DMatrix from a file
int TreeliteCompilerFree(CompilerHandle handle)
delete compiler from memory
int TreeliteTreeBuilderCreateNode(TreeBuilderHandle handle, int node_key)
Create an empty node within a tree.