xgboost
Classes | Macros | Typedefs | Functions
c_api.h File Reference

C API of XGBoost, used for interfacing to other languages. More...

#include <stddef.h>
#include <stdio.h>
#include <stdint.h>
Include dependency graph for c_api.h:

Go to the source code of this file.

Classes

struct  XGBoostBatchCSR
 Mini batch used in XGBoost Data Iteration. More...
 

Macros

#define XGB_EXTERN_C
 
#define XGB_DLL   XGB_EXTERN_C __attribute__ ((visibility ("default")))
 

Typedefs

typedef uint64_t bst_ulong
 
typedef void * DMatrixHandle
 handle to DMatrix More...
 
typedef void * BoosterHandle
 handle to Booster More...
 
typedef void * DataIterHandle
 handle to a external data iterator More...
 
typedef void * DataHolderHandle
 handle to a internal data holder. More...
 
typedef int XGBCallbackSetData(DataHolderHandle handle, XGBoostBatchCSR batch)
 Callback to set the data to handle,. More...
 
typedef int XGBCallbackDataIterNext(DataIterHandle data_handle, XGBCallbackSetData *set_function, DataHolderHandle set_function_handle)
 The data reading callback function. The iterator will be able to give subset of batch in the data. More...
 
typedef int XGDMatrixCallbackNext(DataIterHandle iter)
 Callback function prototype for getting next batch of data. More...
 
typedef void DataIterResetCallback(DataIterHandle handle)
 Callback function prototype for resetting external iterator. More...
 
typedef void * TrackerHandle
 Handle to the tracker. More...
 

Functions

void XGBoostVersion (int *major, int *minor, int *patch)
 Return the version of the XGBoost library being currently used. More...
 
int XGBuildInfo (char const **out)
 Get compile information of shared library. More...
 
const char * XGBGetLastError ()
 get string message of the last error More...
 
int XGBRegisterLogCallback (void(*callback)(const char *))
 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 XGBSetGlobalConfig (char const *config)
 Set global configuration (collection of parameters that apply globally). This function accepts the list of key-value pairs representing the global-scope parameters to be configured. The list of key-value pairs are passed in as a JSON string. More...
 
int XGBGetGlobalConfig (char const **out_config)
 Get current global configuration (collection of parameters that apply globally). More...
 
int XGDMatrixCreateFromFile (const char *fname, int silent, DMatrixHandle *out)
 load a data matrix More...
 
int XGDMatrixCreateFromURI (char const *config, DMatrixHandle *out)
 load a data matrix More...
 
int XGDMatrixCreateFromCSREx (const size_t *indptr, const unsigned *indices, const float *data, size_t nindptr, size_t nelem, size_t num_col, DMatrixHandle *out)
 create a matrix content from CSR format More...
 
int XGDMatrixCreateFromColumnar (char const *data, char const *config, DMatrixHandle *out)
 Create a DMatrix from columnar data. (table) More...
 
int XGDMatrixCreateFromCSR (char const *indptr, char const *indices, char const *data, bst_ulong ncol, char const *config, DMatrixHandle *out)
 Create a matrix from CSR matrix. More...
 
int XGDMatrixCreateFromDense (char const *data, char const *config, DMatrixHandle *out)
 Create a matrix from dense array. More...
 
int XGDMatrixCreateFromCSC (char const *indptr, char const *indices, char const *data, bst_ulong nrow, char const *config, DMatrixHandle *out)
 Create a matrix from a CSC matrix. More...
 
int XGDMatrixCreateFromCSCEx (const size_t *col_ptr, const unsigned *indices, const float *data, size_t nindptr, size_t nelem, size_t num_row, DMatrixHandle *out)
 create a matrix content from CSC format More...
 
int XGDMatrixCreateFromMat (const float *data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle *out)
 create matrix content from dense matrix More...
 
int XGDMatrixCreateFromMat_omp (const float *data, bst_ulong nrow, bst_ulong ncol, float missing, DMatrixHandle *out, int nthread)
 create matrix content from dense matrix More...
 
int XGDMatrixCreateFromDT (void **data, const char **feature_stypes, bst_ulong nrow, bst_ulong ncol, DMatrixHandle *out, int nthread)
 create matrix content from python data table More...
 
int XGDMatrixCreateFromCudaColumnar (char const *data, char const *config, DMatrixHandle *out)
 Create DMatrix from CUDA columnar format. (cuDF) More...
 
int XGDMatrixCreateFromCudaArrayInterface (char const *data, char const *config, DMatrixHandle *out)
 Create DMatrix from CUDA array. More...
 
int XGDMatrixCreateFromDataIter (DataIterHandle data_handle, XGBCallbackDataIterNext *callback, const char *cache_info, DMatrixHandle *out)
 Create a DMatrix from a data iterator. More...
 
int XGProxyDMatrixCreate (DMatrixHandle *out)
 Create a DMatrix proxy for setting data, can be free by XGDMatrixFree. More...
 
int XGDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)
 Create an external memory DMatrix with data iterator. More...
 
int XGQuantileDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterHandle ref, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, char const *config, DMatrixHandle *out)
 Create a Quantile DMatrix with data iterator. More...
 
int XGDeviceQuantileDMatrixCreateFromCallback (DataIterHandle iter, DMatrixHandle proxy, DataIterResetCallback *reset, XGDMatrixCallbackNext *next, float missing, int nthread, int max_bin, DMatrixHandle *out)
 Create a Device Quantile DMatrix with data iterator. More...
 
int XGProxyDMatrixSetDataCudaArrayInterface (DMatrixHandle handle, const char *c_interface_str)
 Set data on a DMatrix proxy. More...
 
int XGProxyDMatrixSetDataColumnar (DMatrixHandle handle, char const *c_interface_str)
 Set columnar (table) data on a DMatrix proxy. More...
 
int XGProxyDMatrixSetDataCudaColumnar (DMatrixHandle handle, const char *c_interface_str)
 Set data on a DMatrix proxy. More...
 
int XGProxyDMatrixSetDataDense (DMatrixHandle handle, char const *c_interface_str)
 Set data on a DMatrix proxy. More...
 
int XGProxyDMatrixSetDataCSR (DMatrixHandle handle, char const *indptr, char const *indices, char const *data, bst_ulong ncol)
 Set data on a DMatrix proxy. More...
 
int XGDMatrixSliceDMatrix (DMatrixHandle handle, const int *idxset, bst_ulong len, DMatrixHandle *out)
 create a new dmatrix from sliced content of existing matrix More...
 
int XGDMatrixSliceDMatrixEx (DMatrixHandle handle, const int *idxset, bst_ulong len, DMatrixHandle *out, int allow_groups)
 create a new dmatrix from sliced content of existing matrix More...
 
int XGDMatrixFree (DMatrixHandle handle)
 free space in data matrix More...
 
int XGDMatrixSaveBinary (DMatrixHandle handle, const char *fname, int silent)
 load a data matrix into binary file More...
 
int XGDMatrixSetInfoFromInterface (DMatrixHandle handle, char const *field, char const *c_interface_str)
 Set content in array interface to a content in info. More...
 
int XGDMatrixSetFloatInfo (DMatrixHandle handle, const char *field, const float *array, bst_ulong len)
 set float vector to a content in info More...
 
int XGDMatrixSetUIntInfo (DMatrixHandle handle, const char *field, const unsigned *array, bst_ulong len)
 
int XGDMatrixSetStrFeatureInfo (DMatrixHandle handle, const char *field, const char **features, const bst_ulong size)
 Set string encoded information of all features. More...
 
int XGDMatrixGetStrFeatureInfo (DMatrixHandle handle, const char *field, bst_ulong *size, const char ***out_features)
 Get string encoded information of all features. More...
 
int XGDMatrixSetDenseInfo (DMatrixHandle handle, const char *field, void const *data, bst_ulong size, int type)
 
int XGDMatrixGetFloatInfo (const DMatrixHandle handle, const char *field, bst_ulong *out_len, const float **out_dptr)
 get float info vector from matrix. More...
 
int XGDMatrixGetUIntInfo (const DMatrixHandle handle, const char *field, bst_ulong *out_len, const unsigned **out_dptr)
 get uint32 info vector from matrix More...
 
int XGDMatrixNumRow (DMatrixHandle handle, bst_ulong *out)
 get number of rows. More...
 
int XGDMatrixNumCol (DMatrixHandle handle, bst_ulong *out)
 get number of columns More...
 
int XGDMatrixNumNonMissing (DMatrixHandle handle, bst_ulong *out)
 Get number of valid values from DMatrix. More...
 
int XGDMatrixDataSplitMode (DMatrixHandle handle, bst_ulong *out)
 Get the data split mode from DMatrix. More...
 
int XGDMatrixGetDataAsCSR (DMatrixHandle const handle, char const *config, bst_ulong *out_indptr, unsigned *out_indices, float *out_data)
 Get the predictors from DMatrix as CSR matrix for testing. If this is a quantized DMatrix, quantized values are returned instead. More...
 
int XGDMatrixGetQuantileCut (DMatrixHandle const handle, char const *config, char const **out_indptr, char const **out_data)
 Export the quantile cuts used for training histogram-based models like hist and approx. Useful for model compression. More...
 
int XGBoosterCreate (const DMatrixHandle dmats[], bst_ulong len, BoosterHandle *out)
 create xgboost learner More...
 
int XGBoosterFree (BoosterHandle handle)
 free obj in handle More...
 
int XGBoosterSlice (BoosterHandle handle, int begin_layer, int end_layer, int step, BoosterHandle *out)
 Slice a model using boosting index. The slice m:n indicates taking all trees that were fit during the boosting rounds m, (m+1), (m+2), ..., (n-1). More...
 
int XGBoosterBoostedRounds (BoosterHandle handle, int *out)
 Get number of boosted rounds from gradient booster. When process_type is update, this number might drop due to removed tree. More...
 
int XGBoosterSetParam (BoosterHandle handle, const char *name, const char *value)
 set parameters More...
 
int XGBoosterGetNumFeature (BoosterHandle handle, bst_ulong *out)
 get number of features More...
 
int XGBoosterUpdateOneIter (BoosterHandle handle, int iter, DMatrixHandle dtrain)
 update the model in one round using dtrain More...
 
int XGBoosterBoostOneIter (BoosterHandle handle, DMatrixHandle dtrain, float *grad, float *hess, bst_ulong len)
 
int XGBoosterTrainOneIter (BoosterHandle handle, DMatrixHandle dtrain, int iter, char const *grad, char const *hess)
 Update a model with gradient and Hessian. This is used for training with a custom objective function. More...
 
int XGBoosterEvalOneIter (BoosterHandle handle, int iter, DMatrixHandle dmats[], const char *evnames[], bst_ulong len, const char **out_result)
 get evaluation statistics for xgboost More...
 
int XGBoosterPredict (BoosterHandle handle, DMatrixHandle dmat, int option_mask, unsigned ntree_limit, int training, bst_ulong *out_len, const float **out_result)
 make prediction based on dmat (deprecated, use XGBoosterPredictFromDMatrix instead) More...
 
int XGBoosterPredictFromDMatrix (BoosterHandle handle, DMatrixHandle dmat, char const *config, bst_ulong const **out_shape, bst_ulong *out_dim, float const **out_result)
 Make prediction from DMatrix, replacing XGBoosterPredict. More...
 
int XGBoosterPredictFromDense (BoosterHandle handle, char const *values, char const *config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)
 Inplace prediction from CPU dense matrix. More...
 
int XGBoosterPredictFromColumnar (BoosterHandle handle, char const *values, char const *config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)
 Inplace prediction from CPU columnar data. (Table) More...
 
int XGBoosterPredictFromCSR (BoosterHandle handle, char const *indptr, char const *indices, char const *values, bst_ulong ncol, char const *config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)
 Inplace prediction from CPU CSR matrix. More...
 
int XGBoosterPredictFromCudaArray (BoosterHandle handle, char const *values, char const *config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)
 Inplace prediction from CUDA Dense matrix (cupy in Python). More...
 
int XGBoosterPredictFromCudaColumnar (BoosterHandle handle, char const *values, char const *config, DMatrixHandle m, bst_ulong const **out_shape, bst_ulong *out_dim, const float **out_result)
 Inplace prediction from CUDA dense dataframe (cuDF in Python). More...
 
int XGBoosterLoadModel (BoosterHandle handle, const char *fname)
 Load model from existing file. More...
 
int XGBoosterSaveModel (BoosterHandle handle, const char *fname)
 Save model into existing file. More...
 
int XGBoosterLoadModelFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len)
 load model from in memory buffer More...
 
int XGBoosterSaveModelToBuffer (BoosterHandle handle, char const *config, bst_ulong *out_len, char const **out_dptr)
 Save model into raw bytes, return header of the array. User must copy the result out, before next xgboost call. More...
 
int XGBoosterSerializeToBuffer (BoosterHandle handle, bst_ulong *out_len, const char **out_dptr)
 Memory snapshot based serialization method. Saves everything states into buffer. More...
 
int XGBoosterUnserializeFromBuffer (BoosterHandle handle, const void *buf, bst_ulong len)
 Memory snapshot based serialization method. Loads the buffer returned from XGBoosterSerializeToBuffer. More...
 
int XGBoosterSaveJsonConfig (BoosterHandle handle, bst_ulong *out_len, char const **out_str)
 Save XGBoost's internal configuration into a JSON document. Currently the support is experimental, function signature may change in the future without notice. More...
 
int XGBoosterLoadJsonConfig (BoosterHandle handle, char const *config)
 Load XGBoost's internal configuration from a JSON document. Currently the support is experimental, function signature may change in the future without notice. More...
 
int XGBoosterDumpModel (BoosterHandle handle, const char *fmap, int with_stats, bst_ulong *out_len, const char ***out_dump_array)
 dump model, return array of strings representing model dump More...
 
int XGBoosterDumpModelEx (BoosterHandle handle, const char *fmap, int with_stats, const char *format, bst_ulong *out_len, const char ***out_dump_array)
 dump model, return array of strings representing model dump More...
 
int XGBoosterDumpModelWithFeatures (BoosterHandle handle, int fnum, const char **fname, const char **ftype, int with_stats, bst_ulong *out_len, const char ***out_models)
 dump model, return array of strings representing model dump More...
 
int XGBoosterDumpModelExWithFeatures (BoosterHandle handle, int fnum, const char **fname, const char **ftype, int with_stats, const char *format, bst_ulong *out_len, const char ***out_models)
 dump model, return array of strings representing model dump More...
 
int XGBoosterGetAttr (BoosterHandle handle, const char *key, const char **out, int *success)
 Get string attribute from Booster. More...
 
int XGBoosterSetAttr (BoosterHandle handle, const char *key, const char *value)
 Set or delete string attribute. More...
 
int XGBoosterGetAttrNames (BoosterHandle handle, bst_ulong *out_len, const char ***out)
 Get the names of all attribute from Booster. More...
 
int XGBoosterSetStrFeatureInfo (BoosterHandle handle, const char *field, const char **features, const bst_ulong size)
 Set string encoded feature info in Booster, similar to the feature info in DMatrix. More...
 
int XGBoosterGetStrFeatureInfo (BoosterHandle handle, const char *field, bst_ulong *len, const char ***out_features)
 Get string encoded feature info from Booster, similar to feature info in DMatrix. More...
 
int XGBoosterFeatureScore (BoosterHandle handle, const char *config, bst_ulong *out_n_features, char const ***out_features, bst_ulong *out_dim, bst_ulong const **out_shape, float const **out_scores)
 Calculate feature scores for tree models. When used on linear model, only the weight importance type is defined, and output scores is a row major matrix with shape [n_features, n_classes] for multi-class model. For tree model, out_n_feature is always equal to out_n_scores and has multiple definitions of importance type. More...
 
int XGTrackerCreate (char const *config, TrackerHandle *handle)
 Create a new tracker. More...
 
int XGTrackerWorkerArgs (TrackerHandle handle, char const **args)
 Get the arguments needed for running workers. This should be called after XGTrackerRun(). More...
 
int XGTrackerRun (TrackerHandle handle, char const *config)
 Start the tracker. The tracker runs in the background and this function returns once the tracker is started. More...
 
int XGTrackerWaitFor (TrackerHandle handle, char const *config)
 Wait for the tracker to finish, should be called after XGTrackerRun(). This function will block until the tracker task is finished or timeout is reached. More...
 
int XGTrackerFree (TrackerHandle handle)
 Free a tracker instance. This should be called after XGTrackerWaitFor(). If the tracker is not properly waited, this function will shutdown all connections with the tracker, potentially leading to undefined behavior. More...
 
int XGCommunicatorInit (char const *config)
 Initialize the collective communicator. More...
 
int XGCommunicatorFinalize (void)
 Finalize the collective communicator. More...
 
int XGCommunicatorGetRank (void)
 Get rank of the current process. More...
 
int XGCommunicatorGetWorldSize (void)
 Get the total number of processes. More...
 
int XGCommunicatorIsDistributed (void)
 Get if the communicator is distributed. More...
 
int XGCommunicatorPrint (char const *message)
 Print the message to the tracker. More...
 
int XGCommunicatorGetProcessorName (const char **name_str)
 Get the name of the processor. More...
 
int XGCommunicatorBroadcast (void *send_receive_buffer, size_t size, int root)
 Broadcast a memory region to all others from root. This function is NOT thread-safe. More...
 
int XGCommunicatorAllreduce (void *send_receive_buffer, size_t count, int data_type, int op)
 Perform in-place allreduce. This function is NOT thread-safe. More...
 

Detailed Description

C API of XGBoost, used for interfacing to other languages.

Copyright 2015-2024, XGBoost Contributors

Author
Tianqi Chen

Macro Definition Documentation

◆ XGB_DLL

#define XGB_DLL   XGB_EXTERN_C __attribute__ ((visibility ("default")))

◆ XGB_EXTERN_C

#define XGB_EXTERN_C

Typedef Documentation

◆ bst_ulong

typedef uint64_t bst_ulong