c_api.h 35.3 KB
Newer Older
Guolin Ke's avatar
Guolin Ke committed
1
2
#ifndef LIGHTGBM_C_API_H_
#define LIGHTGBM_C_API_H_
ww's avatar
ww committed
3

4
#include <cstdint>
wxchan's avatar
wxchan committed
5
6
#include <cstring>

7
8
9
/*!
* To avoid type conversion on large data, most of our expose interface support both for float_32 and float_64.
* Except following:
wxchan's avatar
wxchan committed
10
* 1. gradients and hessians.
11
* 2. Get current score for training data and validation
wxchan's avatar
wxchan committed
12
* The reason is because they are called frequently, the type-conversion on them maybe time cost.
13
14
*/

15
#include <LightGBM/export.h>
Guolin Ke's avatar
Guolin Ke committed
16

Guolin Ke's avatar
typo  
Guolin Ke committed
17
typedef void* DatasetHandle;
Guolin Ke's avatar
Guolin Ke committed
18
19
typedef void* BoosterHandle;

Guolin Ke's avatar
Guolin Ke committed
20
21
22
23
#define C_API_DTYPE_FLOAT32 (0)
#define C_API_DTYPE_FLOAT64 (1)
#define C_API_DTYPE_INT32   (2)
#define C_API_DTYPE_INT64   (3)
24
#define C_API_DTYPE_INT8    (4)
Guolin Ke's avatar
Guolin Ke committed
25
26
27
28

#define C_API_PREDICT_NORMAL     (0)
#define C_API_PREDICT_RAW_SCORE  (1)
#define C_API_PREDICT_LEAF_INDEX (2)
29
#define C_API_PREDICT_CONTRIB    (3)
30

Guolin Ke's avatar
Guolin Ke committed
31
32
/*!
* \brief get string message of the last error
wxchan's avatar
wxchan committed
33
*  all function in this file will return 0 when succeed
Guolin Ke's avatar
Guolin Ke committed
34
35
36
*  and -1 when an error occured,
* \return const char* error inforomation
*/
37
LIGHTGBM_C_EXPORT const char* LGBM_GetLastError();
Guolin Ke's avatar
Guolin Ke committed
38

Guolin Ke's avatar
Guolin Ke committed
39
// --- start Dataset interface
Guolin Ke's avatar
Guolin Ke committed
40
41
42
43

/*!
* \brief load data set from file like the command_line LightGBM do
* \param filename the name of the file
Guolin Ke's avatar
Guolin Ke committed
44
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
45
46
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out a loaded dataset
wxchan's avatar
wxchan committed
47
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
48
*/
49
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromFile(const char* filename,
50
51
52
                                                 const char* parameters,
                                                 const DatasetHandle reference,
                                                 DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
53

54
/*!
55
56
* \brief create a empty dataset by sampling data.
* \param sample_data sampled data, grouped by the column.
57
* \param sample_indices indices of sampled data.
58
* \param ncol number columns
59
60
* \param num_per_col Size of each sampling column
* \param num_sample_row Number of sampled rows
61
62
63
64
65
* \param num_total_row number of total rows
* \param parameters additional parameters
* \param out created dataset
* \return 0 when succeed, -1 when failure happens
*/
66
67
68
69
70
71
72
73
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromSampledColumn(double** sample_data,
                                                          int** sample_indices,
                                                          int32_t ncol,
                                                          const int* num_per_col,
                                                          int32_t num_sample_row,
                                                          int32_t num_total_row,
                                                          const char* parameters,
                                                          DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
74
75
76
77
78
79
80
81
82

/*!
* \brief create a empty dataset by reference Dataset
* \param reference used to align bin mapper
* \param num_total_row number of total rows
* \param out created dataset
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateByReference(const DatasetHandle reference,
83
84
                                                    int64_t num_total_row,
                                                    DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
85
86
87
88
89
90
91
92
93
94
95
96

/*!
* \brief push data to existing dataset, if nrow + start_row == num_total_row, will call dataset->FinishLoad
* \param dataset handle of dataset
* \param data pointer to the data space
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param nrow number of rows
* \param ncol number columns
* \param start_row row start index
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRows(DatasetHandle dataset,
97
98
99
100
101
                                           const void* data,
                                           int data_type,
                                           int32_t nrow,
                                           int32_t ncol,
                                           int32_t start_row);
Guolin Ke's avatar
Guolin Ke committed
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

/*!
* \brief push data to existing dataset, if nrow + start_row == num_total_row, will call dataset->FinishLoad
* \param dataset handle of dataset
* \param indptr pointer to row headers
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
* \param indices findex
* \param data fvalue
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param nindptr number of rows in the matrix + 1
* \param nelem number of nonzero elements in the matrix
* \param num_col number of columns
* \param start_row row start index
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetPushRowsByCSR(DatasetHandle dataset,
118
119
120
121
122
123
124
125
126
                                                const void* indptr,
                                                int indptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t nindptr,
                                                int64_t nelem,
                                                int64_t num_col,
                                                int64_t start_row);
Guolin Ke's avatar
Guolin Ke committed
127

Guolin Ke's avatar
Guolin Ke committed
128
129
130
/*!
* \brief create a dataset from CSR format
* \param indptr pointer to row headers
wxchan's avatar
wxchan committed
131
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
Guolin Ke's avatar
Guolin Ke committed
132
133
* \param indices findex
* \param data fvalue
wxchan's avatar
wxchan committed
134
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
Guolin Ke's avatar
Guolin Ke committed
135
* \param nindptr number of rows in the matrix + 1
Guolin Ke's avatar
Guolin Ke committed
136
* \param nelem number of nonzero elements in the matrix
wxchan's avatar
wxchan committed
137
* \param num_col number of columns
Guolin Ke's avatar
Guolin Ke committed
138
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
139
140
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
wxchan's avatar
wxchan committed
141
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
142
*/
143
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSR(const void* indptr,
144
145
146
147
148
149
150
151
152
153
                                                int indptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t nindptr,
                                                int64_t nelem,
                                                int64_t num_col,
                                                const char* parameters,
                                                const DatasetHandle reference,
                                                DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
154
155
156
157

/*!
* \brief create a dataset from CSC format
* \param col_ptr pointer to col headers
wxchan's avatar
wxchan committed
158
* \param col_ptr_type type of col_ptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
Guolin Ke's avatar
Guolin Ke committed
159
160
* \param indices findex
* \param data fvalue
wxchan's avatar
wxchan committed
161
162
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param ncol_ptr number of cols in the matrix + 1
Guolin Ke's avatar
Guolin Ke committed
163
* \param nelem number of nonzero elements in the matrix
wxchan's avatar
wxchan committed
164
* \param num_row number of rows
Guolin Ke's avatar
Guolin Ke committed
165
166
167
* \param parameters additional parameters
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
wxchan's avatar
wxchan committed
168
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
169
*/
170
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromCSC(const void* col_ptr,
171
172
173
174
175
176
177
178
179
180
                                                int col_ptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t ncol_ptr,
                                                int64_t nelem,
                                                int64_t num_row,
                                                const char* parameters,
                                                const DatasetHandle reference,
                                                DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
181
182
183
184

/*!
* \brief create dataset from dense matrix
* \param data pointer to the data space
wxchan's avatar
wxchan committed
185
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
Guolin Ke's avatar
Guolin Ke committed
186
187
* \param nrow number of rows
* \param ncol number columns
188
* \param is_row_major 1 for row major, 0 for column major
Guolin Ke's avatar
Guolin Ke committed
189
* \param parameters additional parameters
Guolin Ke's avatar
Guolin Ke committed
190
191
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
wxchan's avatar
wxchan committed
192
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
193
*/
194
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMat(const void* data,
195
196
197
198
199
200
201
                                                int data_type,
                                                int32_t nrow,
                                                int32_t ncol,
                                                int is_row_major,
                                                const char* parameters,
                                                const DatasetHandle reference,
                                                DatasetHandle* out);
Guolin Ke's avatar
Guolin Ke committed
202

203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
/*!
* \brief create dataset from array of dense matrices
* \param data pointer to the data space
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param nrow number of rows
* \param ncol number columns
* \param parameters additional parameters
* \param reference used to align bin mapper with other dataset, nullptr means don't used
* \param out created dataset
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetCreateFromMats(int32_t nmat,
                                                 const void** data,
                                                 int data_type,
                                                 int32_t* nrow,
                                                 int32_t ncol,
                                                 int is_row_major,
                                                 const char* parameters,
                                                 const DatasetHandle reference,
                                                 DatasetHandle* out);

wxchan's avatar
wxchan committed
224
225
226
227
228
229
230
231
232
/*!
* \brief Create subset of a data
* \param handle handle of full dataset
* \param used_row_indices Indices used in subset
* \param num_used_row_indices len of used_row_indices
* \param parameters additional parameters
* \param out subset of data
* \return 0 when succeed, -1 when failure happens
*/
233
LIGHTGBM_C_EXPORT int LGBM_DatasetGetSubset(
234
  const DatasetHandle handle,
wxchan's avatar
wxchan committed
235
236
237
  const int32_t* used_row_indices,
  int32_t num_used_row_indices,
  const char* parameters,
Guolin Ke's avatar
typo  
Guolin Ke committed
238
  DatasetHandle* out);
wxchan's avatar
wxchan committed
239

Guolin Ke's avatar
Guolin Ke committed
240
241
242
243
244
245
246
/*!
* \brief save feature names to Dataset
* \param handle handle
* \param feature_names feature names
* \param num_feature_names number of feature names
* \return 0 when succeed, -1 when failure happens
*/
247
LIGHTGBM_C_EXPORT int LGBM_DatasetSetFeatureNames(
Guolin Ke's avatar
typo  
Guolin Ke committed
248
  DatasetHandle handle,
Guolin Ke's avatar
Guolin Ke committed
249
  const char** feature_names,
Guolin Ke's avatar
Guolin Ke committed
250
  int num_feature_names);
Guolin Ke's avatar
Guolin Ke committed
251

252
253
254
255
256
257
258
259

/*!
* \brief get feature names of Dataset
* \param handle handle
* \param feature_names feature names, should pre-allocate memory
* \param num_feature_names number of feature names
* \return 0 when succeed, -1 when failure happens
*/
260
LIGHTGBM_C_EXPORT int LGBM_DatasetGetFeatureNames(
261
262
  DatasetHandle handle,
  char** feature_names,
Guolin Ke's avatar
Guolin Ke committed
263
  int* num_feature_names);
264
265


Guolin Ke's avatar
Guolin Ke committed
266
267
/*!
* \brief free space for dataset
wxchan's avatar
wxchan committed
268
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
269
*/
270
LIGHTGBM_C_EXPORT int LGBM_DatasetFree(DatasetHandle handle);
Guolin Ke's avatar
Guolin Ke committed
271
272

/*!
273
* \brief save dataset to binary file
Guolin Ke's avatar
Guolin Ke committed
274
275
* \param handle a instance of dataset
* \param filename file name
wxchan's avatar
wxchan committed
276
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
277
*/
278
LIGHTGBM_C_EXPORT int LGBM_DatasetSaveBinary(DatasetHandle handle,
279
                                             const char* filename);
Guolin Ke's avatar
Guolin Ke committed
280

281
282
283
284
285
286
287
288
289
/*!
* \brief save dataset to text file, intended for debugging use only
* \param handle a instance of dataset
* \param filename file name
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetDumpText(DatasetHandle handle,
                                           const char* filename);

Guolin Ke's avatar
Guolin Ke committed
290
291
/*!
* \brief set vector to a content in info
wxchan's avatar
wxchan committed
292
293
*        Note: group and group only work for C_API_DTYPE_INT32
*              label and weight only work for C_API_DTYPE_FLOAT32
Guolin Ke's avatar
Guolin Ke committed
294
* \param handle a instance of dataset
wxchan's avatar
wxchan committed
295
* \param field_name field name, can be label, weight, group, group_id
296
* \param field_data pointer to vector
Guolin Ke's avatar
Guolin Ke committed
297
* \param num_element number of element in field_data
wxchan's avatar
wxchan committed
298
299
* \param type C_API_DTYPE_FLOAT32 or C_API_DTYPE_INT32
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
300
*/
301
LIGHTGBM_C_EXPORT int LGBM_DatasetSetField(DatasetHandle handle,
302
303
304
305
                                           const char* field_name,
                                           const void* field_data,
                                           int num_element,
                                           int type);
Guolin Ke's avatar
Guolin Ke committed
306
307

/*!
308
* \brief get info vector from dataset
Guolin Ke's avatar
Guolin Ke committed
309
310
311
312
* \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
wxchan's avatar
wxchan committed
313
314
* \param out_type  C_API_DTYPE_FLOAT32 or C_API_DTYPE_INT32
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
315
*/
316
LIGHTGBM_C_EXPORT int LGBM_DatasetGetField(DatasetHandle handle,
317
318
319
320
                                           const char* field_name,
                                           int* out_len,
                                           const void** out_ptr,
                                           int* out_type);
Guolin Ke's avatar
Guolin Ke committed
321

322
323
324
325
326
327
328
329

/*!
* \brief Update parameters for a Dataset
* \param handle a instance of data matrix
* \param parameters parameters
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetUpdateParam(DatasetHandle handle, const char* parameters);

Guolin Ke's avatar
Guolin Ke committed
330
331
332
333
/*!
* \brief get number of data.
* \param handle the handle to the dataset
* \param out The address to hold number of data
wxchan's avatar
wxchan committed
334
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
335
*/
336
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumData(DatasetHandle handle,
337
                                             int* out);
Guolin Ke's avatar
Guolin Ke committed
338
339
340
341
342

/*!
* \brief get number of features
* \param handle the handle to the dataset
* \param out The output of number of features
wxchan's avatar
wxchan committed
343
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
344
*/
345
LIGHTGBM_C_EXPORT int LGBM_DatasetGetNumFeature(DatasetHandle handle,
346
                                                int* out);
Guolin Ke's avatar
Guolin Ke committed
347

348
349
350
351
352
353
354
355
356
/*!
* \brief Add features from source to target, then free source
* \param target The handle of the dataset to add features to
* \param source The handle of the dataset to take features from
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_DatasetAddFeaturesFrom(DatasetHandle target,
                                                  DatasetHandle source);

Guolin Ke's avatar
Guolin Ke committed
357
358
359
360
// --- start Booster interfaces

/*!
* \brief create an new boosting learner
Guolin Ke's avatar
Guolin Ke committed
361
* \param train_data training data set
Guolin Ke's avatar
Guolin Ke committed
362
363
* \param parameters format: 'key1=value1 key2=value2'
* \prama out handle of created Booster
wxchan's avatar
wxchan committed
364
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
365
*/
366
LIGHTGBM_C_EXPORT int LGBM_BoosterCreate(const DatasetHandle train_data,
367
368
                                         const char* parameters,
                                         BoosterHandle* out);
Guolin Ke's avatar
Guolin Ke committed
369
370

/*!
Guolin Ke's avatar
Guolin Ke committed
371
* \brief load an existing boosting from model file
Guolin Ke's avatar
Guolin Ke committed
372
* \param filename filename of model
wxchan's avatar
wxchan committed
373
* \param out_num_iterations number of iterations of this booster
Guolin Ke's avatar
Guolin Ke committed
374
* \param out handle of created Booster
wxchan's avatar
wxchan committed
375
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
376
*/
377
LIGHTGBM_C_EXPORT int LGBM_BoosterCreateFromModelfile(
Guolin Ke's avatar
Guolin Ke committed
378
  const char* filename,
Guolin Ke's avatar
Guolin Ke committed
379
  int* out_num_iterations,
Guolin Ke's avatar
Guolin Ke committed
380
381
  BoosterHandle* out);

382
383
384
385
386
387
388
389
390
391
392
/*!
* \brief load an existing boosting from string
* \param model_str model string
* \param out_num_iterations number of iterations of this booster
* \param out handle of created Booster
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterLoadModelFromString(
  const char* model_str,
  int* out_num_iterations,
  BoosterHandle* out);
wxchan's avatar
wxchan committed
393

Guolin Ke's avatar
Guolin Ke committed
394
395
396
/*!
* \brief free obj in handle
* \param handle handle to be freed
wxchan's avatar
wxchan committed
397
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
398
*/
399
LIGHTGBM_C_EXPORT int LGBM_BoosterFree(BoosterHandle handle);
Guolin Ke's avatar
Guolin Ke committed
400

401
402
403
/*!
* \brief Shuffle Models
*/
404
LIGHTGBM_C_EXPORT int LGBM_BoosterShuffleModels(BoosterHandle handle, int start_iter, int end_iter);
405

wxchan's avatar
wxchan committed
406
407
408
409
410
411
/*!
* \brief Merge model in two booster to first handle
* \param handle handle, will merge other handle to this
* \param other_handle
* \return 0 when succeed, -1 when failure happens
*/
412
LIGHTGBM_C_EXPORT int LGBM_BoosterMerge(BoosterHandle handle,
413
                                        BoosterHandle other_handle);
wxchan's avatar
wxchan committed
414
415
416
417
418
419
420

/*!
* \brief Add new validation to booster
* \param handle handle
* \param valid_data validation data set
* \return 0 when succeed, -1 when failure happens
*/
421
LIGHTGBM_C_EXPORT int LGBM_BoosterAddValidData(BoosterHandle handle,
422
                                               const DatasetHandle valid_data);
wxchan's avatar
wxchan committed
423
424
425
426
427
428
429

/*!
* \brief Reset training data for booster
* \param handle handle
* \param train_data training data set
* \return 0 when succeed, -1 when failure happens
*/
430
LIGHTGBM_C_EXPORT int LGBM_BoosterResetTrainingData(BoosterHandle handle,
431
                                                    const DatasetHandle train_data);
wxchan's avatar
wxchan committed
432
433
434
435
436
437
438

/*!
* \brief Reset config for current booster
* \param handle handle
* \param parameters format: 'key1=value1 key2=value2'
* \return 0 when succeed, -1 when failure happens
*/
439
LIGHTGBM_C_EXPORT int LGBM_BoosterResetParameter(BoosterHandle handle, const char* parameters);
wxchan's avatar
wxchan committed
440
441

/*!
Guolin Ke's avatar
Guolin Ke committed
442
* \brief Get number of class
wxchan's avatar
wxchan committed
443
444
445
446
* \param handle handle
* \param out_len number of class
* \return 0 when succeed, -1 when failure happens
*/
447
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumClasses(BoosterHandle handle, int* out_len);
wxchan's avatar
wxchan committed
448

Guolin Ke's avatar
Guolin Ke committed
449
450
451
/*!
* \brief update the model in one round
* \param handle handle
Guolin Ke's avatar
Guolin Ke committed
452
* \param is_finished 1 means finised(cannot split any more)
wxchan's avatar
wxchan committed
453
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
454
*/
455
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIter(BoosterHandle handle, int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
456

Guolin Ke's avatar
Guolin Ke committed
457
458
459
460
461
462
463
464
465
466
/*!
* \brief Refit the tree model using the new data (online learning)
* \param handle handle
* \param leaf_preds 
* \param nrow number of rows of leaf_preds
* \param ncol number of columns of leaf_preds
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterRefit(BoosterHandle handle, const int32_t* leaf_preds, int32_t nrow, int32_t ncol);

Guolin Ke's avatar
Guolin Ke committed
467
468
469
470
471
472
/*!
* \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
Guolin Ke's avatar
Guolin Ke committed
473
* \param is_finished 1 means finised(cannot split any more)
wxchan's avatar
wxchan committed
474
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
475
*/
476
LIGHTGBM_C_EXPORT int LGBM_BoosterUpdateOneIterCustom(BoosterHandle handle,
477
478
479
                                                      const float* grad,
                                                      const float* hess,
                                                      int* is_finished);
Guolin Ke's avatar
Guolin Ke committed
480
481

/*!
wxchan's avatar
wxchan committed
482
* \brief Rollback one iteration
Guolin Ke's avatar
Guolin Ke committed
483
* \param handle handle
wxchan's avatar
wxchan committed
484
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
485
*/
486
LIGHTGBM_C_EXPORT int LGBM_BoosterRollbackOneIter(BoosterHandle handle);
wxchan's avatar
wxchan committed
487
488
489
490
491
492

/*!
* \brief Get iteration of current boosting rounds
* \param out_iteration iteration of boosting rounds
* \return 0 when succeed, -1 when failure happens
*/
493
LIGHTGBM_C_EXPORT int LGBM_BoosterGetCurrentIteration(BoosterHandle handle, int* out_iteration);
Guolin Ke's avatar
Guolin Ke committed
494

495
496
497
498
499
500
501
502
503
504
505
506
507
508
/*!
* \brief Get number of tree per iteration
* \param out_tree_per_iteration number of tree per iteration
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterNumModelPerIteration(BoosterHandle handle, int* out_tree_per_iteration);

/*!
* \brief Get number of weak sub-models
* \param out_models number of weak sub-models
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterNumberOfTotalModel(BoosterHandle handle, int* out_models);

Guolin Ke's avatar
Guolin Ke committed
509
/*!
Guolin Ke's avatar
Guolin Ke committed
510
* \brief Get number of eval
wxchan's avatar
wxchan committed
511
512
513
* \param out_len total number of eval results
* \return 0 when succeed, -1 when failure happens
*/
514
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalCounts(BoosterHandle handle, int* out_len);
wxchan's avatar
wxchan committed
515
516

/*!
wxchan's avatar
wxchan committed
517
* \brief Get name of eval
wxchan's avatar
wxchan committed
518
* \param out_len total number of eval results
Guolin Ke's avatar
typo  
Guolin Ke committed
519
* \param out_strs names of eval result, need to pre-allocate memory before call this
wxchan's avatar
wxchan committed
520
521
* \return 0 when succeed, -1 when failure happens
*/
522
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEvalNames(BoosterHandle handle, int* out_len, char** out_strs);
wxchan's avatar
wxchan committed
523

wxchan's avatar
wxchan committed
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
/*!
* \brief Get name of features
* \param out_len total number of features
* \param out_strs names of features, need to pre-allocate memory before call this
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterGetFeatureNames(BoosterHandle handle, int* out_len, char** out_strs);

/*!
* \brief Get number of features
* \param out_len total number of features
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumFeature(BoosterHandle handle, int* out_len);

wxchan's avatar
wxchan committed
539
540
/*!
* \brief get evaluation for training data and validation data
Guolin Ke's avatar
Guolin Ke committed
541
542
Note: 1. you should call LGBM_BoosterGetEvalNames first to get the name of evaluation results
2. should pre-allocate memory for out_results, you can get its length by LGBM_BoosterGetEvalCounts
Guolin Ke's avatar
Guolin Ke committed
543
* \param handle handle
wxchan's avatar
wxchan committed
544
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
Guolin Ke's avatar
Guolin Ke committed
545
* \param out_len len of output result
wxchan's avatar
wxchan committed
546
547
* \param out_result float arrary contains result
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
548
*/
549
LIGHTGBM_C_EXPORT int LGBM_BoosterGetEval(BoosterHandle handle,
550
551
552
                                          int data_idx,
                                          int* out_len,
                                          double* out_results);
Guolin Ke's avatar
Guolin Ke committed
553
554
555
556
557
558
559
560
561
562

/*!
* \brief Get number of predict for inner dataset
this can be used to support customized eval function
Note:  should pre-allocate memory for out_result, its length is equal to num_class * num_data
* \param handle handle
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
* \param out_len len of output result
* \return 0 when succeed, -1 when failure happens
*/
563
LIGHTGBM_C_EXPORT int LGBM_BoosterGetNumPredict(BoosterHandle handle,
564
565
                                                int data_idx,
                                                int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
566

Guolin Ke's avatar
Guolin Ke committed
567
/*!
Guolin Ke's avatar
Guolin Ke committed
568
* \brief Get prediction for training data and validation data
Guolin Ke's avatar
Guolin Ke committed
569
570
this can be used to support customized eval function
Note:  should pre-allocate memory for out_result, its length is equal to num_class * num_data
Guolin Ke's avatar
Guolin Ke committed
571
* \param handle handle
wxchan's avatar
wxchan committed
572
* \param data_idx 0:training data, 1: 1st valid data, 2:2nd valid data ...
Guolin Ke's avatar
Guolin Ke committed
573
* \param out_len len of output result
Guolin Ke's avatar
Guolin Ke committed
574
* \param out_result used to set a pointer to array, should allocate memory before call this function
wxchan's avatar
wxchan committed
575
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
576
*/
577
LIGHTGBM_C_EXPORT int LGBM_BoosterGetPredict(BoosterHandle handle,
578
579
580
                                             int data_idx,
                                             int64_t* out_len,
                                             double* out_result);
Guolin Ke's avatar
Guolin Ke committed
581

582
583
584
585
/*!
* \brief make prediction for file
* \param handle handle
* \param data_filename filename of data file
wxchan's avatar
wxchan committed
586
587
588
589
590
591
* \param data_has_header data file has header or not
* \param predict_type
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
Guolin Ke's avatar
Guolin Ke committed
592
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction.
593
* \param result_filename filename of result file
wxchan's avatar
wxchan committed
594
* \return 0 when succeed, -1 when failure happens
595
*/
596
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForFile(BoosterHandle handle,
597
598
599
600
                                                 const char* data_filename,
                                                 int data_has_header,
                                                 int predict_type,
                                                 int num_iteration,
601
                                                 const char* parameter,
602
                                                 const char* result_filename);
603

Guolin Ke's avatar
Guolin Ke committed
604
605
606
/*!
* \brief Get number of prediction
* \param handle handle
Guolin Ke's avatar
Guolin Ke committed
607
* \param num_row
Guolin Ke's avatar
Guolin Ke committed
608
609
610
611
612
* \param predict_type
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
613
* \param out_len length of prediction
Guolin Ke's avatar
Guolin Ke committed
614
615
* \return 0 when succeed, -1 when failure happens
*/
616
LIGHTGBM_C_EXPORT int LGBM_BoosterCalcNumPredict(BoosterHandle handle,
617
618
619
620
                                                 int num_row,
                                                 int predict_type,
                                                 int num_iteration,
                                                 int64_t* out_len);
Guolin Ke's avatar
Guolin Ke committed
621

Guolin Ke's avatar
Guolin Ke committed
622
623
/*!
* \brief make prediction for an new data set
Guolin Ke's avatar
Guolin Ke committed
624
*        Note:  should pre-allocate memory for out_result,
wxchan's avatar
wxchan committed
625
626
*               for noraml and raw score: its length is equal to num_class * num_data
*               for leaf index, its length is equal to num_class * num_data * num_iteration
Guolin Ke's avatar
Guolin Ke committed
627
628
* \param handle handle
* \param indptr pointer to row headers
wxchan's avatar
wxchan committed
629
* \param indptr_type type of indptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
Guolin Ke's avatar
Guolin Ke committed
630
631
* \param indices findex
* \param data fvalue
wxchan's avatar
wxchan committed
632
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
Guolin Ke's avatar
Guolin Ke committed
633
* \param nindptr number of rows in the matrix + 1
Guolin Ke's avatar
Guolin Ke committed
634
635
636
* \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
wxchan's avatar
wxchan committed
637
638
639
640
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
Guolin Ke's avatar
Guolin Ke committed
641
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction.
wxchan's avatar
wxchan committed
642
* \param out_len len of output result
Guolin Ke's avatar
Guolin Ke committed
643
* \param out_result used to set a pointer to array, should allocate memory before call this function
wxchan's avatar
wxchan committed
644
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
645
*/
646
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSR(BoosterHandle handle,
647
648
649
650
651
652
653
654
655
656
                                                const void* indptr,
                                                int indptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t nindptr,
                                                int64_t nelem,
                                                int64_t num_col,
                                                int predict_type,
                                                int num_iteration,
657
                                                const char* parameter,
658
659
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679

/*!
* \brief make prediction for an new data set
*        Note:  should pre-allocate memory for out_result,
*               for noraml and raw score: its length is equal to num_class * num_data
*               for leaf index, its length is equal to num_class * num_data * num_iteration
* \param handle handle
* \param col_ptr pointer to col headers
* \param col_ptr_type type of col_ptr, can be C_API_DTYPE_INT32 or C_API_DTYPE_INT64
* \param indices findex
* \param data fvalue
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
* \param ncol_ptr number of cols in the matrix + 1
* \param nelem number of nonzero elements in the matrix
* \param num_row number of rows
* \param predict_type
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
Guolin Ke's avatar
Guolin Ke committed
680
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction.
Guolin Ke's avatar
Guolin Ke committed
681
682
683
684
* \param out_len len of output result
* \param out_result used to set a pointer to array, should allocate memory before call this function
* \return 0 when succeed, -1 when failure happens
*/
685
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForCSC(BoosterHandle handle,
686
687
688
689
690
691
692
693
694
695
                                                const void* col_ptr,
                                                int col_ptr_type,
                                                const int32_t* indices,
                                                const void* data,
                                                int data_type,
                                                int64_t ncol_ptr,
                                                int64_t nelem,
                                                int64_t num_row,
                                                int predict_type,
                                                int num_iteration,
696
                                                const char* parameter,
697
698
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
699
700
701

/*!
* \brief make prediction for an new data set
wxchan's avatar
wxchan committed
702
703
704
*        Note:  should pre-allocate memory for out_result,
*               for noraml and raw score: its length is equal to num_class * num_data
*               for leaf index, its length is equal to num_class * num_data * num_iteration
Guolin Ke's avatar
Guolin Ke committed
705
706
* \param handle handle
* \param data pointer to the data space
wxchan's avatar
wxchan committed
707
* \param data_type type of data pointer, can be C_API_DTYPE_FLOAT32 or C_API_DTYPE_FLOAT64
Guolin Ke's avatar
Guolin Ke committed
708
709
* \param nrow number of rows
* \param ncol number columns
Guolin Ke's avatar
Guolin Ke committed
710
* \param is_row_major 1 for row major, 0 for column major
Guolin Ke's avatar
Guolin Ke committed
711
* \param predict_type
wxchan's avatar
wxchan committed
712
713
714
715
*          C_API_PREDICT_NORMAL: normal prediction, with transform (if needed)
*          C_API_PREDICT_RAW_SCORE: raw score
*          C_API_PREDICT_LEAF_INDEX: leaf index
* \param num_iteration number of iteration for prediction, <= 0 means no limit
Guolin Ke's avatar
Guolin Ke committed
716
* \param parameter Other parameters for the parameters, e.g. early stopping for prediction.
wxchan's avatar
wxchan committed
717
* \param out_len len of output result
Guolin Ke's avatar
Guolin Ke committed
718
* \param out_result used to set a pointer to array, should allocate memory before call this function
wxchan's avatar
wxchan committed
719
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
720
*/
721
LIGHTGBM_C_EXPORT int LGBM_BoosterPredictForMat(BoosterHandle handle,
722
723
724
725
726
727
728
                                                const void* data,
                                                int data_type,
                                                int32_t nrow,
                                                int32_t ncol,
                                                int is_row_major,
                                                int predict_type,
                                                int num_iteration,
729
                                                const char* parameter,
730
731
                                                int64_t* out_len,
                                                double* out_result);
Guolin Ke's avatar
Guolin Ke committed
732
733
734
735

/*!
* \brief save model into file
* \param handle handle
wxchan's avatar
wxchan committed
736
* \param num_iteration, <= 0 means save all
Guolin Ke's avatar
Guolin Ke committed
737
* \param filename file name
wxchan's avatar
wxchan committed
738
* \return 0 when succeed, -1 when failure happens
Guolin Ke's avatar
Guolin Ke committed
739
*/
740
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModel(BoosterHandle handle,
741
                                            int start_iteration,
742
743
                                            int num_iteration,
                                            const char* filename);
Guolin Ke's avatar
Guolin Ke committed
744

745
746
747
748
749
750
751
752
753
754
/*!
* \brief save model to string
* \param handle handle
* \param num_iteration, <= 0 means save all
* \param buffer_len string buffer length, if buffer_len < out_len, re-allocate buffer
* \param out_len actual output length
* \param out_str string of model, need to pre-allocate memory before call this
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterSaveModelToString(BoosterHandle handle,
755
                                                    int start_iteration,
756
                                                    int num_iteration,
757
758
                                                    int64_t buffer_len,
                                                    int64_t* out_len,
759
                                                    char* out_str);
760

wxchan's avatar
wxchan committed
761
762
763
/*!
* \brief dump model to json
* \param handle handle
764
* \param num_iteration, <= 0 means save all
wxchan's avatar
wxchan committed
765
766
* \param buffer_len string buffer length, if buffer_len < out_len, re-allocate buffer
* \param out_len actual output length
Guolin Ke's avatar
typo  
Guolin Ke committed
767
* \param out_str json format string of model, need to pre-allocate memory before call this
wxchan's avatar
wxchan committed
768
769
* \return 0 when succeed, -1 when failure happens
*/
770
LIGHTGBM_C_EXPORT int LGBM_BoosterDumpModel(BoosterHandle handle,
771
                                            int start_iteration,
772
                                            int num_iteration,
773
774
                                            int64_t buffer_len,
                                            int64_t* out_len,
775
                                            char* out_str);
776

Guolin Ke's avatar
Guolin Ke committed
777
/*!
Guolin Ke's avatar
Guolin Ke committed
778
* \brief Get leaf value
Guolin Ke's avatar
Guolin Ke committed
779
780
781
782
783
784
* \param handle handle
* \param tree_idx index of tree
* \param leaf_idx index of leaf
* \param out_val out result
* \return 0 when succeed, -1 when failure happens
*/
785
LIGHTGBM_C_EXPORT int LGBM_BoosterGetLeafValue(BoosterHandle handle,
786
787
788
                                               int tree_idx,
                                               int leaf_idx,
                                               double* out_val);
Guolin Ke's avatar
Guolin Ke committed
789
790
791
792
793
794
795
796
797

/*!
* \brief Set leaf value
* \param handle handle
* \param tree_idx index of tree
* \param leaf_idx index of leaf
* \param val leaf value
* \return 0 when succeed, -1 when failure happens
*/
798
LIGHTGBM_C_EXPORT int LGBM_BoosterSetLeafValue(BoosterHandle handle,
799
800
801
                                               int tree_idx,
                                               int leaf_idx,
                                               double val);
802

803
804
805
806
807
808
809
810
811
812
813
814
815
/*!
* \brief get model feature importance
* \param handle handle
* \param num_iteration, <= 0 means use all
* \param importance_type: 0 for split, 1 for gain
* \param out_results output value array
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_BoosterFeatureImportance(BoosterHandle handle,
                                                    int num_iteration,
                                                    int importance_type,
                                                    double* out_results);

816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
/*!
* \brief Initilize the network
* \param machines represent the nodes, format: ip1:port1,ip2:port2
* \param local_listen_port
* \param listen_time_out
* \param num_machines
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_NetworkInit(const char* machines,
                                       int local_listen_port,
                                       int listen_time_out,
                                       int num_machines);

/*!
* \brief Finalize the network
* \return 0 when succeed, -1 when failure happens
*/
LIGHTGBM_C_EXPORT int LGBM_NetworkFree();

835
836
LIGHTGBM_C_EXPORT int LGBM_NetworkInitWithFunctions(int num_machines, int rank,
                                                    void* reduce_scatter_ext_fun,
837
                                                    void* allgather_ext_fun);
838

Guolin Ke's avatar
Guolin Ke committed
839
840

#if defined(_MSC_VER)
841
#define THREAD_LOCAL __declspec(thread)
Guolin Ke's avatar
Guolin Ke committed
842
843
844
#else
#define THREAD_LOCAL thread_local
#endif
845
// exception handle and error msg
846
static char* LastErrorMsg() { static THREAD_LOCAL char err_msg[512] = "Everything is fine"; return err_msg; }
847

848
#pragma warning(disable : 4996)
849
inline void LGBM_SetLastError(const char* msg) {
wxchan's avatar
wxchan committed
850
  std::strcpy(LastErrorMsg(), msg);
851
852
}

853
#endif  // LIGHTGBM_C_API_H_