treelite
Macros | Typedefs | Functions | Variables
c_api.h File Reference

C API of Treelite, used for interfacing with other languages. More...

#include <stdint.h>
#include <stdio.h>
Include dependency graph for c_api.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros

#define TREELITE_EXTERN_C
 
#define TREELITE_DLL   TREELITE_EXTERN_C __attribute__((visibility("default")))
 
#define TREELITE_DLL_STRUCT   TREELITE_EXTERN_C struct __attribute__((visibility("default")))
 

Typedefs

typedef void * TreeliteModelHandle
 Handle to a decision tree ensemble model. More...
 
typedef void * TreeliteModelBuilderHandle
 Handle to a model builder object. More...
 
typedef void * TreeliteGTILConfigHandle
 Handle to a configuration of GTIL predictor. More...
 
typedef struct TreelitePyBufferFrame TreelitePyBufferFrame
 Represent a frame in the Python buffer protocol (PEP 3118). More...
 

Functions

int TreeliteLoadXGBoostModelLegacyBinary (char const *filename, char const *config_json, TreeliteModelHandle *out)
 Load a model file generated by XGBoost (dmlc/xgboost), stored in the legacy binary format. More...
 
int TreeliteLoadXGBoostModelLegacyBinaryFromMemoryBuffer (void const *buf, size_t len, char const *config_json, TreeliteModelHandle *out)
 Load an XGBoost model from a memory buffer using the legacy binary format. More...
 
int TreeliteLoadXGBoostModel (char const *filename, char const *config_json, TreeliteModelHandle *out)
 Load a model file generated by XGBoost (dmlc/xgboost), stored in the JSON format. More...
 
int TreeliteLoadXGBoostModelFromString (char const *json_str, size_t length, char const *config_json, TreeliteModelHandle *out)
 Load an XGBoost model from a JSON string. More...
 
int TreeliteLoadLightGBMModel (char const *filename, char const *config_json, TreeliteModelHandle *out)
 Load a model file generated by LightGBM (Microsoft/LightGBM). The model file must contain a decision tree ensemble. More...
 
int TreeliteLoadLightGBMModelFromString (char const *model_str, char const *config_json, TreeliteModelHandle *out)
 Load a LightGBM model from a string. The string should be created with the model_to_string() method in LightGBM. More...
 
int TreeliteLoadSKLearnRandomForestRegressor (int n_estimators, int n_features, int n_targets, int64_t const *node_count, int64_t const **children_left, int64_t const **children_right, int64_t const **feature, double const **threshold, double const **value, int64_t const **n_node_samples, double const **weighted_n_node_samples, double const **impurity, TreeliteModelHandle *out)
 Load a scikit-learn RandomForestRegressor model from a collection of arrays. Refer to https://scikit-learn.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the meaning of the arrays in detail. Note that this function can also be used to load an ensemble of extremely randomized trees (sklearn.ensemble.ExtraTreesRegressor). More...
 
int TreeliteLoadSKLearnIsolationForest (int n_estimators, int n_features, int64_t const *node_count, int64_t const **children_left, int64_t const **children_right, int64_t const **feature, double const **threshold, double const **value, int64_t const **n_node_samples, double const **weighted_n_node_samples, double const **impurity, double ratio_c, TreeliteModelHandle *out)
 Load a scikit-learn IsolationForest model from a collection of arrays. Refer to https://scikit-learn.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the meaning of the arrays in detail. More...
 
int TreeliteLoadSKLearnRandomForestClassifier (int n_estimators, int n_features, int n_targets, int32_t const *n_classes, int64_t const *node_count, int64_t const **children_left, int64_t const **children_right, int64_t const **feature, double const **threshold, double const **value, int64_t const **n_node_samples, double const **weighted_n_node_samples, double const **impurity, TreeliteModelHandle *out)
 Load a scikit-learn RandomForestClassifier model from a collection of arrays. Refer to https://scikit-learn.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the meaning of the arrays in detail. Note that this function can also be used to load an ensemble of extremely randomized trees (sklearn.ensemble.ExtraTreesClassifier). More...
 
int TreeliteLoadSKLearnGradientBoostingRegressor (int n_iter, int n_features, int64_t const *node_count, int64_t const **children_left, int64_t const **children_right, int64_t const **feature, double const **threshold, double const **value, int64_t const **n_node_samples, double const **weighted_n_node_samples, double const **impurity, double const *base_scores, TreeliteModelHandle *out)
 Load a scikit-learn GradientBoostingRegressor model from a collection of arrays. Refer to https://scikit-learn.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the meaning of the arrays in detail. Note: GradientBoostingRegressor does not support multiple targets (outputs). More...
 
int TreeliteLoadSKLearnGradientBoostingClassifier (int n_iter, int n_features, int n_classes, int64_t const *node_count, int64_t const **children_left, int64_t const **children_right, int64_t const **feature, double const **threshold, double const **value, int64_t const **n_node_samples, double const **weighted_n_node_samples, double const **impurity, double const *base_scores, TreeliteModelHandle *out)
 Load a scikit-learn GradientBoostingClassifier model from a collection of arrays. Refer to https://scikit-learn.org/stable/auto_examples/tree/plot_unveil_tree_structure.html to learn the meaning of the arrays in detail. Note: GradientBoostingClassifier does not support multiple targets (outputs). More...
 
int TreeliteLoadSKLearnHistGradientBoostingRegressor (int n_iter, int n_features, int64_t const *node_count, void const **nodes, int expected_sizeof_node_struct, uint32_t n_categorical_splits, uint32_t const **raw_left_cat_bitsets, uint32_t const *known_cat_bitsets, uint32_t const *known_cat_bitsets_offset_map, int32_t const *features_map, int64_t const **categories_map, double const *base_scores, TreeliteModelHandle *out)
 Load a scikit-learn HistGradientBoostingRegressor model from a collection of arrays. Note: HistGradientBoostingRegressor does not support multiple targets (outputs). More...
 
int TreeliteLoadSKLearnHistGradientBoostingClassifier (int n_iter, int n_features, int n_classes, int64_t const *node_count, void const **nodes, int expected_sizeof_node_struct, uint32_t n_categorical_splits, uint32_t const **raw_left_cat_bitsets, uint32_t const *known_cat_bitsets, uint32_t const *known_cat_bitsets_offset_map, int32_t const *features_map, int64_t const **categories_map, double const *base_scores, TreeliteModelHandle *out)
 Load a scikit-learn HistGradientBoostingClassifier model from a collection of arrays. Note: HistGradientBoostingClassifier does not support multiple targets (outputs). More...
 
int TreeliteGetModelBuilder (char const *json_str, TreeliteModelBuilderHandle *out)
 Initialize a model builder object from a JSON string. More...
 
int TreeliteDeleteModelBuilder (TreeliteModelBuilderHandle model_builder)
 Delete model builder object from memory. More...
 
int TreeliteModelBuilderStartTree (TreeliteModelBuilderHandle model_builder)
 Start a new tree. More...
 
int TreeliteModelBuilderEndTree (TreeliteModelBuilderHandle model_builder)
 End the current tree. More...
 
int TreeliteModelBuilderStartNode (TreeliteModelBuilderHandle model_builder, int node_key)
 Start a new node. More...
 
int TreeliteModelBuilderEndNode (TreeliteModelBuilderHandle model_builder)
 End the current node. More...
 
int TreeliteModelBuilderNumericalTest (TreeliteModelBuilderHandle model_builder, int32_t split_index, double threshold, int default_left, char const *cmp, int left_child_key, int right_child_key)
 Declare the current node as a numerical test node, where the test is of form [feature value] [cmp] [threshold]. Data points for which the test evaluates to True will be mapped to the left child node; all other data points (for which the test evaluates to False) will be mapped to the right child node. More...
 
int TreeliteModelBuilderCategoricalTest (TreeliteModelBuilderHandle model_builder, int32_t split_index, int default_left, uint32_t const *category_list, size_t category_list_len, int category_list_right_child, int left_child_key, int right_child_key)
 Declare the current node as a categorical test node, where the test is of form [feature value] \in [category list]. More...
 
int TreeliteModelBuilderLeafScalar (TreeliteModelBuilderHandle model_builder, double leaf_value)
 Declare the current node as a leaf node with a scalar output. More...
 
int TreeliteModelBuilderLeafVectorFloat32 (TreeliteModelBuilderHandle model_builder, float const *leaf_vector, size_t leaf_vector_len)
 Declare the current node as a leaf node with a vector output (float32) More...
 
int TreeliteModelBuilderLeafVectorFloat64 (TreeliteModelBuilderHandle model_builder, double const *leaf_vector, size_t leaf_vector_len)
 Declare the current node as a leaf node with a vector output (float64) More...
 
int TreeliteModelBuilderGain (TreeliteModelBuilderHandle model_builder, double gain)
 Specify the gain (loss reduction) that's resulted from the current split. More...
 
int TreeliteModelBuilderDataCount (TreeliteModelBuilderHandle model_builder, uint64_t data_count)
 Specify the number of data points (samples) that are mapped to the current node. More...
 
int TreeliteModelBuilderSumHess (TreeliteModelBuilderHandle model_builder, double sum_hess)
 Specify the weighted sample count or the sum of Hessians for the data points that are mapped to the current node. More...
 
int TreeliteModelBuilderCommitModel (TreeliteModelBuilderHandle model_builder, TreeliteModelHandle *out)
 Conclude model building and obtain the final model object. More...
 
int TreeliteDumpAsJSON (TreeliteModelHandle handle, int pretty_print, char const **out_json_str)
 Dump a model object as a JSON string. More...
 
int TreeliteGetInputType (TreeliteModelHandle model, char const **out_str)
 Query the input type of a Treelite model object. More...
 
int TreeliteGetOutputType (TreeliteModelHandle model, char const **out_str)
 Query the output type of a Treelite model object. More...
 
int TreeliteQueryNumTree (TreeliteModelHandle model, size_t *out)
 Query the number of trees in the model. More...
 
int TreeliteQueryNumFeature (TreeliteModelHandle model, int *out)
 Query the number of features used in the model. More...
 
int TreeliteConcatenateModelObjects (TreeliteModelHandle const *objs, size_t len, TreeliteModelHandle *out)
 Concatenate multiple model objects into a single model object by copying all member trees into the destination model object. More...
 
int TreeliteFreeModel (TreeliteModelHandle handle)
 Delete model from memory. More...
 
int TreeliteSerializeModelToFile (TreeliteModelHandle handle, char const *filename)
 Serialize (persist) a model object to disk. More...
 
int TreeliteDeserializeModelFromFile (char const *filename, TreeliteModelHandle *out)
 Deserialize (load) a model object from disk. More...
 
int TreeliteSerializeModelToBytes (TreeliteModelHandle handle, char const **out_bytes, size_t *out_bytes_len)
 Serialize (persist) a model object to a byte sequence. More...
 
int TreeliteDeserializeModelFromBytes (char const *bytes, size_t bytes_len, TreeliteModelHandle *out)
 Deserialize (load) a model object from a byte sequence. More...
 
int TreeliteSerializeModelToPyBuffer (TreeliteModelHandle handle, TreelitePyBufferFrame **out_frames, size_t *out_num_frames)
 Serialize a model object using the Python buffer protocol (PEP 3118). More...
 
int TreeliteDeserializeModelFromPyBuffer (TreelitePyBufferFrame *frames, size_t num_frames, TreeliteModelHandle *out)
 Deserialize a model object using the Python buffer protocol (PEP 3118). More...
 
int TreeliteGTILParseConfig (char const *config_json, TreeliteGTILConfigHandle *out)
 Load a configuration for GTIL predictor from a JSON string. More...
 
int TreeliteGTILDeleteConfig (TreeliteGTILConfigHandle handle)
 Delete a GTIL configuration from memory. More...
 
int TreeliteGTILGetOutputShape (TreeliteModelHandle model, uint64_t num_row, TreeliteGTILConfigHandle config, uint64_t const **out, uint64_t *out_ndim)
 Given a data matrix, query the necessary shape of array to hold predictions for all data points. More...
 
int TreeliteGTILPredict (TreeliteModelHandle model, void const *input, char const *input_type, uint64_t num_row, void *output, TreeliteGTILConfigHandle config)
 Predict with a 2D dense array. More...
 
int TreeliteGTILPredictSparse (TreeliteModelHandle model, void const *data, char const *input_type, uint64_t const *col_ind, uint64_t const *row_ptr, uint64_t num_row, void *output, TreeliteGTILConfigHandle config)
 Predict with sparse data with CSR (compressed sparse row) layout. More...
 
int TreeliteGetHeaderField (TreeliteModelHandle model, char const *name, TreelitePyBufferFrame *out_frame)
 Get a field in the header. More...
 
int TreeliteGetTreeField (TreeliteModelHandle model, uint64_t tree_id, char const *name, TreelitePyBufferFrame *out_frame)
 Get a field in a tree. More...
 
int TreeliteSetHeaderField (TreeliteModelHandle model, char const *name, TreelitePyBufferFrame frame)
 Set a field in the header. More...
 
int TreeliteSetTreeField (TreeliteModelHandle model, uint64_t tree_id, char const *name, TreelitePyBufferFrame frame)
 Set a field in a tree. More...
 
char const * TreeliteGetLastError (void)
 Display last error; can be called by multiple threads Note. Each thread will get the last error occured in its own context. More...
 
int TreeliteRegisterLogCallback (void(*callback)(char const *))
 Register callback function for LOG(INFO) messages – helpful messages that are not errors. Note: This function can be called by multiple threads. The callback function will run on the thread that registered it. More...
 
int TreeliteRegisterWarningCallback (void(*callback)(char const *))
 Register callback function for LOG(WARNING) messages Note: This function can be called by multiple threads. The callback function will run on the thread that registered it. More...
 

Variables

char * format
 
size_t itemsize
 
size_t nitem
 
char const * TREELITE_VERSION
 

Detailed Description

C API of Treelite, used for interfacing with other languages.

Copyright (c) 2017-2023 by Contributors

Author
Hyunsu Cho

Macro Definition Documentation

◆ TREELITE_DLL

#define TREELITE_DLL   TREELITE_EXTERN_C __attribute__((visibility("default")))

◆ TREELITE_DLL_STRUCT

#define TREELITE_DLL_STRUCT   TREELITE_EXTERN_C struct __attribute__((visibility("default")))

◆ TREELITE_EXTERN_C

#define TREELITE_EXTERN_C

Function Documentation

◆ TreeliteGetLastError()

char const* TreeliteGetLastError ( void  )

Display last error; can be called by multiple threads Note. Each thread will get the last error occured in its own context.

Returns
Error string

◆ TreeliteRegisterLogCallback()

int TreeliteRegisterLogCallback ( void(*)(char const *)  callback)

Register callback function for LOG(INFO) messages – helpful messages that are not errors. Note: This function can be called by multiple threads. The callback function will run on the thread that registered it.

Returns
0 for success, -1 for failure

◆ TreeliteRegisterWarningCallback()

int TreeliteRegisterWarningCallback ( void(*)(char const *)  callback)

Register callback function for LOG(WARNING) messages Note: This function can be called by multiple threads. The callback function will run on the thread that registered it.

Returns
0 for success, -1 for failure

Variable Documentation

◆ TREELITE_VERSION

char const* TREELITE_VERSION
extern