c_api.h 11.1 KB
Newer Older
Guolin Ke's avatar
Guolin Ke committed
1
2
3
4
#ifndef LIGHTGBM_C_API_H_
#define LIGHTGBM_C_API_H_
#include<cstdint>

5
6
7
8
9
10
11
12
13

/*!
* To avoid type conversion on large data, most of our expose interface support both for float_32 and float_64.
* Except following:
* 1. gradients and hessians. 
* 2. Get current score for training data and validation
* The reason is becaused they are called frequently, the type-conversion on them maybe time cost. 
*/

Guolin Ke's avatar
Guolin Ke committed
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
#ifdef __cplusplus
#define DLL_EXTERN_C extern "C"
#else
#define DLL_EXTERN_C
#endif

#ifdef _MSC_VER
#define DllExport DLL_EXTERN_C __declspec(dllexport)
#else
#define DllExport DLL_EXTERN_C
#endif

typedef void* DatesetHandle;
typedef void* BoosterHandle;

/*!
* \brief get string message of the last error
*  all function in this file will return 0 when success
*  and -1 when an error occured,
* \return const char* error inforomation
*/
DllExport const char* LGBM_GetLastError();


// --- start Dataset inferfaces

/*!
* \brief load data set from file like the command_line LightGBM do
Guolin Ke's avatar
Guolin Ke committed
42
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
* \param filename the name of the file
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out a loaded dataset
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_CreateDatasetFromFile(const char* filename,
  const char* parameters,
  const DatesetHandle* reference,
  DatesetHandle* out);

/*!
* \brief load data set from binary file like the command_line LightGBM do
* \param filename the name of the file
* \param out a loaded dataset
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_CreateDatasetFromBinaryFile(const char* filename,
  DatesetHandle* out);

/*!
* \brief create a dataset from CSR format
* \param indptr pointer to row headers
* \param indices findex
* \param data fvalue
67
* \param float_type 0 for float_32 1 for float_64
Guolin Ke's avatar
Guolin Ke committed
68
69
70
* \param nindptr number of rows in the matix + 1
* \param nelem number of nonzero elements in the matrix
* \param num_col number of columns; when it's set to 0, then guess from data
Guolin Ke's avatar
Guolin Ke committed
71
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
72
73
74
75
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
* \return 0 when success, -1 when failure happens
*/
76
77
78
79
DllExport int LGBM_CreateDatasetFromCSR(const uint32_t* indptr,
  const uint32_t* indices,
  const void* data,
  int float_type,
Guolin Ke's avatar
Guolin Ke committed
80
81
82
  uint64_t nindptr,
  uint64_t nelem,
  uint64_t num_col,
Guolin Ke's avatar
Guolin Ke committed
83
  const char* parameters,
Guolin Ke's avatar
Guolin Ke committed
84
85
86
87
88
89
90
91
  const DatesetHandle* reference,
  DatesetHandle* out);

/*!
* \brief create a dataset from CSC format
* \param col_ptr pointer to col headers
* \param indices findex
* \param data fvalue
92
* \param float_type 0 for float_32 1 for float_64
Guolin Ke's avatar
Guolin Ke committed
93
94
95
* \param nindptr number of rows in the matix + 1
* \param nelem number of nonzero elements in the matrix
* \param num_row number of rows; when it's set to 0, then guess from data
Guolin Ke's avatar
Guolin Ke committed
96
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
97
98
99
100
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
* \return 0 when success, -1 when failure happens
*/
101
102
103
104
DllExport int LGBM_CreateDatasetFromCSC(const uint32_t* col_ptr,
  const uint32_t* indices,
  const void* data,
  int float_type,
Guolin Ke's avatar
Guolin Ke committed
105
106
107
  uint64_t nindptr,
  uint64_t nelem,
  uint64_t num_row,
Guolin Ke's avatar
Guolin Ke committed
108
  const char* parameters,
Guolin Ke's avatar
Guolin Ke committed
109
110
111
112
113
114
  const DatesetHandle* reference,
  DatesetHandle* out);

/*!
* \brief create dataset from dense matrix
* \param data pointer to the data space
115
* \param float_type 0 for float_32 1 for float_64
Guolin Ke's avatar
Guolin Ke committed
116
117
* \param nrow number of rows
* \param ncol number columns
118
* \param is_row_major 1 for row major, 0 for column major
Guolin Ke's avatar
Guolin Ke committed
119
* \param missing which value to represent missing value
Guolin Ke's avatar
Guolin Ke committed
120
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
121
122
123
124
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
* \return 0 when success, -1 when failure happens
*/
125
126
DllExport int LGBM_CreateDatasetFromMat(const void* data,
  int float_type,
Guolin Ke's avatar
Guolin Ke committed
127
128
  uint64_t nrow,
  uint64_t ncol,
129
130
  int is_row_major,
  double missing,
Guolin Ke's avatar
Guolin Ke committed
131
  const char* parameters,
Guolin Ke's avatar
Guolin Ke committed
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
  const DatesetHandle* reference,
  DatesetHandle* out);

/*!
* \brief free space for dataset
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_DatasetFree(DatesetHandle* handle);

/*!
* \brief save dateset to binary file
* \param handle a instance of dataset
* \param filename file name
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_DatasetSaveBinary(DatesetHandle handle,
  const char* filename);

/*!
* \brief set vector to a content in info
* \param handle a instance of dataset
* \param field_name field name, can be label, weight, group
154
* \param field_data pointer to vector
Guolin Ke's avatar
Guolin Ke committed
155
* \param field_len number of element in field_data
156
* \param type float_32:0, uint32_t:1
Guolin Ke's avatar
Guolin Ke committed
157
158
159
160
161
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_DatasetSetField(DatesetHandle handle,
  const char* field_name,
  const void* field_data,
Guolin Ke's avatar
Guolin Ke committed
162
  uint64_t num_element,
Guolin Ke's avatar
Guolin Ke committed
163
164
165
  int type);

/*!
166
* \brief get info vector from dataset
Guolin Ke's avatar
Guolin Ke committed
167
168
169
170
* \param handle a instance of data matrix
* \param field_name field name
* \param out_len used to set result length
* \param out_ptr pointer to the result
171
* \param out_type  float_32:0, uint32_t:1
Guolin Ke's avatar
Guolin Ke committed
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_DatasetGetField(DatesetHandle handle,
  const char* field_name,
  uint64_t* out_len,
  const void** out_ptr,
  int* out_type);

/*!
* \brief get number of data.
* \param handle the handle to the dataset
* \param out The address to hold number of data
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_DatasetGetNumData(DatesetHandle handle,
  uint64_t* out);

/*!
* \brief get number of features
* \param handle the handle to the dataset
* \param out The output of number of features
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_DatasetGetNumFeature(DatesetHandle handle,
  uint64_t* out);

// --- start Booster interfaces

/*!
* \brief create an new boosting learner
* \param train_data traning data set
* \param valid_datas validation data sets
* \param valid_names names of validation data sets
* \param n_valid_datas number of validation set
* \param parameters format: 'key1=value1 key2=value2'
* \prama out handle of created Booster
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_BoosterCreate(DatesetHandle train_data,
  DatesetHandle valid_datas[],
  const char* valid_names[],
  int n_valid_datas,
  const char* parameters,
  BoosterHandle* out);

/*!
* \brief load an exsiting boosting from model file
* \param filename filename of model
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_BoosterLoadFromModelfile(
  const char* filename,
  BoosterHandle* out);

/*!
* \brief free obj in handle
* \param handle handle to be freed
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_BoosterFree(BoosterHandle handle);

/*!
* \brief update the model in one round
* \param handle handle
* \param is_finished 1 means finised
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_BoosterUpdateOneIter(BoosterHandle handle, int* is_finished);

/*!
* \brief update the model, by directly specify gradient and second order gradient,
*       this can be used to support customized loss function
* \param handle handle
* \param grad gradient statistics
* \param hess second order gradient statistics
247
* \param float_type 0 for float_32, 1 for float_64
Guolin Ke's avatar
Guolin Ke committed
248
249
250
251
252
253
254
255
256
257
258
* \param is_finished 1 means finised
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle,
  float* grad,
  float* hess,
  int* is_finished);

/*!
* \brief get evaluation for training data and validation datas
* \param handle handle
Guolin Ke's avatar
Guolin Ke committed
259
* \param data 0:training data, 1: 1st valid data, 2:2nd valid data ...
Guolin Ke's avatar
Guolin Ke committed
260
261
262
* \param out_result the string containing evaluation statistics
* \return 0 when success, -1 when failure happens
*/
Guolin Ke's avatar
Guolin Ke committed
263
264
265
DllExport int LGBM_BoosterEval(BoosterHandle handle,
  int data,
  const char** out_result);
Guolin Ke's avatar
Guolin Ke committed
266
267
268
269
270

/*!
* \brief make prediction for training data and validation datas
this can be used to support customized eval function
* \param handle handle
Guolin Ke's avatar
Guolin Ke committed
271
* \param data 0:training data, 1: 1st valid data, 2:2nd valid data ...
Guolin Ke's avatar
Guolin Ke committed
272
273
* \param predict_type
*          0:raw score
274
*          1:with sigmoid/softmax transform(if needed)
Guolin Ke's avatar
Guolin Ke committed
275
276
277
278
*          2:leaf index
* \param out_result used to set a pointer to array
* \return 0 when success, -1 when failure happens
*/
Guolin Ke's avatar
Guolin Ke committed
279
280
DllExport int LGBM_BoosterPredict(BoosterHandle handle,
  int data,
Guolin Ke's avatar
Guolin Ke committed
281
  int predict_type,
Guolin Ke's avatar
Guolin Ke committed
282
  const float** out_result);
Guolin Ke's avatar
Guolin Ke committed
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301

/*!
* \brief make prediction for an new data set
* \param handle handle
* \param indptr pointer to row headers
* \param indices findex
* \param data fvalue
* \param nindptr number of rows in the matix + 1
* \param nelem number of nonzero elements in the matrix
* \param num_col number of columns; when it's set to 0, then guess from data
* \param predict_type
*          0:raw score
*          1:with sigmoid transform(if needed)
*          2:leaf index
* \param n_used_trees number of used tree
* \param out_result used to set a pointer to array
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_BoosterPredictForCSR(BoosterHandle handle,
302
303
304
305
  const uint32_t* indptr,
  const uint32_t* indices,
  const void* data,
  int float_type,
Guolin Ke's avatar
Guolin Ke committed
306
307
308
309
310
  uint64_t nindptr,
  uint64_t nelem,
  uint64_t num_col,
  int predict_type,
  uint64_t n_used_trees,
311
  const double** out_result);
Guolin Ke's avatar
Guolin Ke committed
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330

/*!
* \brief make prediction for an new data set
* \param handle handle
* \param col_ptr pointer to col headers
* \param indices findex
* \param data fvalue
* \param nindptr number of rows in the matix + 1
* \param nelem number of nonzero elements in the matrix
* \param num_row number of rows; when it's set to 0, then guess from data
* \param predict_type
*          0:raw score
*          1:with sigmoid transform(if needed)
*          2:leaf index
* \param n_used_trees number of used tree
* \param out_result used to set a pointer to array
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_BoosterPredictForCSC(BoosterHandle handle,
331
332
333
334
  const uint32_t* col_ptr,
  const uint32_t* indices,
  const void* data,
  int float_type,
Guolin Ke's avatar
Guolin Ke committed
335
336
337
338
339
  uint64_t nindptr,
  uint64_t nelem,
  uint64_t num_row,
  int predict_type,
  uint64_t n_used_trees,
340
  const double** out_result);
Guolin Ke's avatar
Guolin Ke committed
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357

/*!
* \brief make prediction for an new data set
* \param handle handle
* \param data pointer to the data space
* \param nrow number of rows
* \param ncol number columns
* \param missing which value to represent missing value
* \param predict_type
*          0:raw score
*          1:with sigmoid transform(if needed)
*          2:leaf index
* \param n_used_trees number of used tree
* \param out_result used to set a pointer to array
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_BoosterPredictForMat(BoosterHandle handle,
358
359
  const void* data,
  int float_type,
Guolin Ke's avatar
Guolin Ke committed
360
361
  uint64_t nrow,
  uint64_t ncol,
362
  double missing,
Guolin Ke's avatar
Guolin Ke committed
363
364
  int predict_type,
  uint64_t n_used_trees,
365
  const double** out_result);
Guolin Ke's avatar
Guolin Ke committed
366
367
368
369
370
371
372
373
374
375
376
377
378

/*!
* \brief save model into file
* \param handle handle
* \param is_finished 1 means finised
* \param filename file name
* \return 0 when success, -1 when failure happens
*/
DllExport int LGBM_BoosterSaveModel(BoosterHandle handle,
  int is_finished,
  const char* filename);

#endif // LIGHTGBM_C_API_H_