// MIT License

//

// Copyright (c) 2021 Kai Zhu

//

// Permission is hereby granted, free of charge, to any person obtaining a copy

// of this software and associated documentation files (the "Software"), to deal

// in the Software without restriction, including without limitation the rights

// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell

// copies of the Software, and to permit persons to whom the Software is

// furnished to do so, subject to the following conditions:

//

// The above copyright notice and this permission notice shall be included in

// all copies or substantial portions of the Software.

//

// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR

// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,

// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE

// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,

// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE

// SOFTWARE.

// LINT_C_FILE

#if defined(SQLMATH_BASE_C2) && !defined(SQLMATH_BASE_H3)

#define SQLMATH_BASE_H3

#define LIGHTGBM_C_EXPORT typedef

#ifdef _WIN32

#define LGBM_DLSYM(func) \

func = (func##_t) GetProcAddress((HMODULE) lgbm_library, #func);

#else

#define LGBM_DLSYM(func) \

func = (func##_t) dlsym(lgbm_library, #func);

#endif // _WIN32

// https://github.com/microsoft/LightGBM/blob/v4.5.0/include/LightGBM/arrow.h

typedef struct ArrowSchema {

// Array type description

const char *format;

const char *name;

const char *metadata;

int64_t flags;

int64_t n_children;

struct ArrowSchema **children;

struct ArrowSchema *dictionary;

// Release callback

void (

*release

) (

struct ArrowSchema *

);

// Opaque producer-specific data

void *private_data;

} ArrowSchema;

typedef struct ArrowArray {

// Array data description

int64_t length;

int64_t null_count;

int64_t offset;

int64_t n_buffers;

int64_t n_children;

const void **buffers;

struct ArrowArray **children;

struct ArrowArray *dictionary;

// Release callback

void (

*release

) (

struct ArrowArray *

);

// Opaque producer-specific data

void *private_data;

} ArrowArray;

static void *lgbm_library = NULL;

#endif // SQLMATH_BASE_H3

// *INDENT-OFF*

/*jslint-disable*/

/*

shRollupFetch

{

"fetchList": [

{

"header": "\n#if defined(SQLMATH_BASE_C2) && !defined(SQLMATH_BASE_H4)\n#define SQLMATH_BASE_H4\n",

"replaceList": [

{

"aa": "\nLIGHTGBM_C_EXPORT ([^\\(]*?) (\\w*?)(\\([\\S\\s]*?\\));\n",

"bb": "\nLIGHTGBM_C_EXPORT $1 (*$2_t) $3;\nstatic $2_t $2 = NULL;\n",

"flags": "g",

"substr": ""

}

],

"url": "https://github.com/microsoft/LightGBM/blob/v4.5.0/include/LightGBM/c_api.h"

},

{

"footer": "\n}\n#endif // SQLMATH_BASE_H4\n",

"header": "static void LGBM_dlsym() {\n",

"replaceList": [

{

"aa": "\nLIGHTGBM_C_EXPORT ([^\\(]*?) (\\w*?)(\\([\\S\\s]*?\\));\n",

"bb": "\n^LGBM_DLSYM($2);\n",

"flags": "g",

"substr": ""

},

{

"aa": "^[^^].*?\n|^\n",

"bb": "",

"flags": "gm",

"substr": ""

},

{

"aa": "^[^z]",

"bb": "",

"flags": "gm",

"substr": ""

}

],

"url": "https://github.com/microsoft/LightGBM/blob/v4.5.0/include/LightGBM/c_api.h"

},

{

"comment": true,

"header": "\n#if defined(SQLMATH_NODEJS_C2) && !defined(SQLMATH_NODEJS_H3)\n#define SQLMATH_NODEJS_H3\n",

"url": "https://github.com/nodejs/node/blob/v10.22.1/LICENSE"

},

{

"url": "https://github.com/nodejs/node/blob/v10.22.1/src/node_api_types.h"

},

{

"footer": "\n#endif // SQLMATH_NODEJS_H3\n",

"replaceList": [

{

"aa": "^#include \"node_api_types.h\"",

"bb": "// hack-nodejs - inline header\n// $&",

"flags": "gm",

"substr": ""

}

],

"url": "https://github.com/nodejs/node/blob/v10.22.1/src/node_api.h"

}

],

"replaceList": []

}

-#define INLINE_FUNCTION inline

+// hack-lightgbm - fix warning

+#define INLINE_FUNCTION static inline

-#include <LightGBM/arrow.h>

-#include <LightGBM/export.h>

+// hack-lightgbm - inline header

+// #include <LightGBM/arrow.h>

+// #include <LightGBM/export.h>

*/

/*

repo https://github.com/microsoft/LightGBM/tree/v4.5.0

committed 2024-07-25T14:51:01Z

*/

/*

file https://github.com/microsoft/LightGBM/blob/v4.5.0/include/LightGBM/c_api.h

*/

#if defined(SQLMATH_BASE_C2) && !defined(SQLMATH_BASE_H4)

#define SQLMATH_BASE_H4

/*!

* \file c_api.h

* \copyright Copyright (c) 2016 Microsoft Corporation. All rights reserved.

* Licensed under the MIT License. See LICENSE file in the project root for license information.

* \note

* To avoid type conversion on large data, the most of our exposed interface supports both float32 and float64,

* except the following:

* 1. gradient and Hessian;

* 2. current score for training and validation data.

* .

* The reason is that they are called frequently, and the type conversion on them may be time-cost.

*/

#ifndef LIGHTGBM_C_API_H_

#define LIGHTGBM_C_API_H_

// hack-lightgbm - inline header

// #include <LightGBM/arrow.h>

// #include <LightGBM/export.h>

#ifdef __cplusplus

#include <cstdint>

#include <cstdio>

#include <cstring>

#else

#include <stdint.h>

#include <stdio.h>

#include <string.h>

#endif

typedef void* DatasetHandle; /*!< \brief Handle of dataset. */

typedef void* BoosterHandle; /*!< \brief Handle of booster. */

typedef void* FastConfigHandle; /*!< \brief Handle of FastConfig. */

typedef void* ByteBufferHandle; /*!< \brief Handle of ByteBuffer. */

#define C_API_DTYPE_FLOAT32 (0) /*!< \brief float32 (single precision float). */

#define C_API_DTYPE_FLOAT64 (1) /*!< \brief float64 (double precision float). */

#define C_API_DTYPE_INT32 (2) /*!< \brief int32. */

#define C_API_DTYPE_INT64 (3) /*!< \brief int64. */

#define C_API_PREDICT_NORMAL (0) /*!< \brief Normal prediction, with transform (if needed). */

#define C_API_PREDICT_RAW_SCORE (1) /*!< \brief Predict raw score. */

#define C_API_PREDICT_LEAF_INDEX (2) /*!< \brief Predict leaf index. */

#define C_API_PREDICT_CONTRIB (3) /*!< \brief Predict feature contributions (SHAP values). */

#define C_API_MATRIX_TYPE_CSR (0) /*!< \brief CSR sparse matrix type. */

#define C_API_MATRIX_TYPE_CSC (1) /*!< \brief CSC sparse matrix type. */

#define C_API_FEATURE_IMPORTANCE_SPLIT (0) /*!< \brief Split type of feature importance. */

#define C_API_FEATURE_IMPORTANCE_GAIN (1) /*!< \brief Gain type of feature importance. */

/*!

* \brief Get string message of the last error.

* \return Error information

*/

LIGHTGBM_C_EXPORT const char* (*LGBM_GetLastError_t) ();

static LGBM_GetLastError_t LGBM_GetLastError = NULL;

/*!

* \brief Dump all parameter names with their aliases to JSON.

* \param buffer_len String buffer length, if ``buffer_len < out_len``, you should re-allocate buffer

* \param[out] out_len Actual output length

* \param[out] out_str JSON format string of parameters, should pre-allocate memory

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DumpParamAliases_t) (int64_t buffer_len,

int64_t* out_len,

char* out_str);

static LGBM_DumpParamAliases_t LGBM_DumpParamAliases = NULL;

/*!

* \brief Register a callback function for log redirecting.

* \param callback The callback function to register

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_RegisterLogCallback_t) (void (*callback)(const char*));

static LGBM_RegisterLogCallback_t LGBM_RegisterLogCallback = NULL;

/*!

* \brief Get number of samples based on parameters and total number of rows of data.

* \param num_total_row Number of total rows

* \param parameters Additional parameters, namely, ``bin_construct_sample_cnt`` is used to calculate returned value

* \param[out] out Number of samples. This value is used to pre-allocate memory to hold sample indices when calling ``LGBM_SampleIndices``

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_GetSampleCount_t) (int32_t num_total_row,

const char* parameters,

int* out);

static LGBM_GetSampleCount_t LGBM_GetSampleCount = NULL;

/*!

* \brief Create sample indices for total number of rows.

* \note

* You should pre-allocate memory for ``out``, you can get its length by ``LGBM_GetSampleCount``.

* \param num_total_row Number of total rows

* \param parameters Additional parameters, namely, ``bin_construct_sample_cnt`` and ``data_random_seed`` are used to produce the output

* \param[out] out Created indices, type is int32_t

* \param[out] out_len Number of indices

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_SampleIndices_t) (int32_t num_total_row,

const char* parameters,

void* out,

int32_t* out_len);

static LGBM_SampleIndices_t LGBM_SampleIndices = NULL;

/*!

* \brief Get a ByteBuffer value at an index.

* \param handle Handle of byte buffer to be read

* \param index Index of value to return

* \param[out] out_val Byte value at index to return

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_ByteBufferGetAt_t) (ByteBufferHandle handle, int32_t index, uint8_t* out_val);

static LGBM_ByteBufferGetAt_t LGBM_ByteBufferGetAt = NULL;

/*!

* \brief Free space for byte buffer.

* \param handle Handle of byte buffer to be freed

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_ByteBufferFree_t) (ByteBufferHandle handle);

static LGBM_ByteBufferFree_t LGBM_ByteBufferFree = NULL;

/* --- start Dataset interface */

/*!

* \brief Load dataset from file (like LightGBM CLI version does).

* \param filename The name of the file

* \param parameters Additional parameters

* \param reference Used to align bin mapper with other dataset, nullptr means isn't used

* \param[out] out A loaded dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateFromFile_t) (const char* filename,

const char* parameters,

const DatasetHandle reference,

DatasetHandle* out);

static LGBM_DatasetCreateFromFile_t LGBM_DatasetCreateFromFile = NULL;

/*!

* \brief Allocate the space for dataset and bucket feature bins according to sampled data.

* \param sample_data Sampled data, grouped by the column

* \param sample_indices Indices of sampled data

* \param ncol Number of columns

* \param num_per_col Size of each sampling column

* \param num_sample_row Number of sampled rows

* \param num_local_row Total number of rows local to machine

* \param num_dist_row Number of total distributed rows

* \param parameters Additional parameters

* \param[out] out Created dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateFromSampledColumn_t) (double** sample_data,

int** sample_indices,

int32_t ncol,

const int* num_per_col,

int32_t num_sample_row,

int32_t num_local_row,

int64_t num_dist_row,

const char* parameters,

DatasetHandle* out);

static LGBM_DatasetCreateFromSampledColumn_t LGBM_DatasetCreateFromSampledColumn = NULL;

/*!

* \brief Allocate the space for dataset and bucket feature bins according to reference dataset.

* \param reference Used to align bin mapper with other dataset

* \param num_total_row Number of total rows

* \param[out] out Created dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateByReference_t) (const DatasetHandle reference,

int64_t num_total_row,

DatasetHandle* out);

static LGBM_DatasetCreateByReference_t LGBM_DatasetCreateByReference = NULL;

/*!

* \brief Initialize the Dataset for streaming.

* \param dataset Handle of dataset

* \param has_weights Whether the dataset has Metadata weights

* \param has_init_scores Whether the dataset has Metadata initial scores

* \param has_queries Whether the dataset has Metadata queries/groups

* \param nclasses Number of initial score classes

* \param nthreads Number of external threads that will use the PushRows APIs

* \param omp_max_threads Maximum number of OpenMP threads (-1 for default)

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetInitStreaming_t) (DatasetHandle dataset,

int32_t has_weights,

int32_t has_init_scores,

int32_t has_queries,

int32_t nclasses,

int32_t nthreads,

int32_t omp_max_threads);

static LGBM_DatasetInitStreaming_t LGBM_DatasetInitStreaming = NULL;

/*!

* \brief Allocate the space for dataset and bucket feature bins according to serialized reference dataset.

* \param ref_buffer A binary representation of the dataset schema (feature groups, bins, etc.)

* \param ref_buffer_size The size of the reference array in bytes

* \param num_row Number of total rows the dataset will contain

* \param num_classes Number of classes (will be used only in case of multiclass and specifying initial scores)

* \param parameters Additional parameters

* \param[out] out Created dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateFromSerializedReference_t) (const void* ref_buffer,

int32_t ref_buffer_size,

int64_t num_row,

int32_t num_classes,

const char* parameters,

DatasetHandle* out);

static LGBM_DatasetCreateFromSerializedReference_t LGBM_DatasetCreateFromSerializedReference = NULL;

/*!

* \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 of columns

* \param start_row Row start index

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetPushRows_t) (DatasetHandle dataset,

const void* data,

int data_type,

int32_t nrow,

int32_t ncol,

int32_t start_row);

static LGBM_DatasetPushRows_t LGBM_DatasetPushRows = NULL;

/*!

* \brief Push data to existing dataset.

* The general flow for a streaming scenario is:

* 1. create Dataset "schema" (e.g. ``LGBM_DatasetCreateFromSampledColumn``)

* 2. init them for thread-safe streaming (``LGBM_DatasetInitStreaming``)

* 3. push data (``LGBM_DatasetPushRowsWithMetadata`` or ``LGBM_DatasetPushRowsByCSRWithMetadata``)

* 4. call ``LGBM_DatasetMarkFinished``

* \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 of feature columns

* \param start_row Row start index, i.e., the index at which to start inserting data

* \param label Pointer to array with nrow labels

* \param weight Optional pointer to array with nrow weights

* \param init_score Optional pointer to array with nrow*nclasses initial scores, in column format

* \param query Optional pointer to array with nrow query values

* \param tid The id of the calling thread, from 0...N-1 threads

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetPushRowsWithMetadata_t) (DatasetHandle dataset,

const void* data,

int data_type,

int32_t nrow,

int32_t ncol,

int32_t start_row,

const float* label,

const float* weight,

const double* init_score,

const int32_t* query,

int32_t tid);

static LGBM_DatasetPushRowsWithMetadata_t LGBM_DatasetPushRowsWithMetadata = NULL;

/*!

* \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 Pointer to column indices

* \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 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_t) (DatasetHandle dataset,

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);

static LGBM_DatasetPushRowsByCSR_t LGBM_DatasetPushRowsByCSR = NULL;

/*!

* \brief Push CSR data to existing dataset. (See ``LGBM_DatasetPushRowsWithMetadata`` for more details.)

* \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 Pointer to column indices

* \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 nindptr Number of rows in the matrix + 1

* \param nelem Number of nonzero elements in the matrix

* \param start_row Row start index

* \param label Pointer to array with nindptr-1 labels

* \param weight Optional pointer to array with nindptr-1 weights

* \param init_score Optional pointer to array with (nindptr-1)*nclasses initial scores, in column format

* \param query Optional pointer to array with nindptr-1 query values

* \param tid The id of the calling thread, from 0...N-1 threads

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetPushRowsByCSRWithMetadata_t) (DatasetHandle dataset,

const void* indptr,

int indptr_type,

const int32_t* indices,

const void* data,

int data_type,

int64_t nindptr,

int64_t nelem,

int64_t start_row,

const float* label,

const float* weight,

const double* init_score,

const int32_t* query,

int32_t tid);

static LGBM_DatasetPushRowsByCSRWithMetadata_t LGBM_DatasetPushRowsByCSRWithMetadata = NULL;

/*!

* \brief Set whether or not the Dataset waits for a manual MarkFinished call or calls FinishLoad on itself automatically.

* Set to 1 for streaming scenario, and use ``LGBM_DatasetMarkFinished`` to manually finish the Dataset.

* \param dataset Handle of dataset

* \param wait Whether to wait or not (1 or 0)

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetSetWaitForManualFinish_t) (DatasetHandle dataset, int wait);

static LGBM_DatasetSetWaitForManualFinish_t LGBM_DatasetSetWaitForManualFinish = NULL;

/*!

* \brief Mark the Dataset as complete by calling ``dataset->FinishLoad``.

* \param dataset Handle of dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetMarkFinished_t) (DatasetHandle dataset);

static LGBM_DatasetMarkFinished_t LGBM_DatasetMarkFinished = NULL;

/*!

* \brief Create a dataset from CSR format.

* \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 Pointer to column indices

* \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 nindptr Number of rows in the matrix + 1

* \param nelem Number of nonzero elements in the matrix

* \param num_col Number of columns

* \param parameters Additional parameters

* \param reference Used to align bin mapper with other dataset, nullptr means isn't used

* \param[out] out Created dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateFromCSR_t) (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,

const char* parameters,

const DatasetHandle reference,

DatasetHandle* out);

static LGBM_DatasetCreateFromCSR_t LGBM_DatasetCreateFromCSR = NULL;

/*!

* \brief Create a dataset from CSR format through callbacks.

* \param get_row_funptr Pointer to ``std::function<void(int idx, std::vector<std::pair<int, double>>& ret)>``

* (called for every row and expected to clear and fill ``ret``)

* \param num_rows Number of rows

* \param num_col Number of columns

* \param parameters Additional parameters

* \param reference Used to align bin mapper with other dataset, nullptr means isn't used

* \param[out] out Created dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateFromCSRFunc_t) (void* get_row_funptr,

int num_rows,

int64_t num_col,

const char* parameters,

const DatasetHandle reference,

DatasetHandle* out);

static LGBM_DatasetCreateFromCSRFunc_t LGBM_DatasetCreateFromCSRFunc = NULL;

/*!

* \brief Create a dataset from CSC format.

* \param col_ptr Pointer to column headers

* \param col_ptr_type Type of ``col_ptr``, can be ``C_API_DTYPE_INT32`` or ``C_API_DTYPE_INT64``

* \param indices Pointer to row indices

* \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 ncol_ptr Number of columns in the matrix + 1

* \param nelem Number of nonzero elements in the matrix

* \param num_row Number of rows

* \param parameters Additional parameters

* \param reference Used to align bin mapper with other dataset, nullptr means isn't used

* \param[out] out Created dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateFromCSC_t) (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,

const char* parameters,

const DatasetHandle reference,

DatasetHandle* out);

static LGBM_DatasetCreateFromCSC_t LGBM_DatasetCreateFromCSC = NULL;

/*!

* \brief Create dataset from dense matrix.

* \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 of columns

* \param is_row_major 1 for row-major, 0 for column-major

* \param parameters Additional parameters

* \param reference Used to align bin mapper with other dataset, nullptr means isn't used

* \param[out] out Created dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateFromMat_t) (const void* data,

int data_type,

int32_t nrow,

int32_t ncol,

int is_row_major,

const char* parameters,

const DatasetHandle reference,

DatasetHandle* out);

static LGBM_DatasetCreateFromMat_t LGBM_DatasetCreateFromMat = NULL;

/*!

* \brief Create dataset from array of dense matrices.

* \param nmat Number 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 of columns

* \param is_row_major 1 for row-major, 0 for column-major

* \param parameters Additional parameters

* \param reference Used to align bin mapper with other dataset, nullptr means isn't used

* \param[out] out Created dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateFromMats_t) (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);

static LGBM_DatasetCreateFromMats_t LGBM_DatasetCreateFromMats = NULL;

/*!

* \brief Create dataset from Arrow.

* \param n_chunks The number of Arrow arrays passed to this function

* \param chunks Pointer to the list of Arrow arrays

* \param schema Pointer to the schema of all Arrow arrays

* \param parameters Additional parameters

* \param reference Used to align bin mapper with other dataset, nullptr means isn't used

* \param[out] out Created dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetCreateFromArrow_t) (int64_t n_chunks,

const ArrowArray* chunks,

const ArrowSchema* schema,

const char* parameters,

const DatasetHandle reference,

DatasetHandle *out);

static LGBM_DatasetCreateFromArrow_t LGBM_DatasetCreateFromArrow = NULL;

/*!

* \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 Length of ``used_row_indices``

* \param parameters Additional parameters

* \param[out] out Subset of data

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetGetSubset_t) (const DatasetHandle handle,

const int32_t* used_row_indices,

int32_t num_used_row_indices,

const char* parameters,

DatasetHandle* out);

static LGBM_DatasetGetSubset_t LGBM_DatasetGetSubset = NULL;

/*!

* \brief Save feature names to dataset.

* \param handle Handle of dataset

* \param feature_names Feature names

* \param num_feature_names Number of feature names

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetSetFeatureNames_t) (DatasetHandle handle,

const char** feature_names,

int num_feature_names);

static LGBM_DatasetSetFeatureNames_t LGBM_DatasetSetFeatureNames = NULL;

/*!

* \brief Get feature names of dataset.

* \param handle Handle of dataset

* \param len Number of ``char*`` pointers stored at ``out_strs``.

* If smaller than the max size, only this many strings are copied

* \param[out] num_feature_names Number of feature names

* \param buffer_len Size of pre-allocated strings.

* Content is copied up to ``buffer_len - 1`` and null-terminated

* \param[out] out_buffer_len String sizes required to do the full string copies

* \param[out] feature_names Feature names, should pre-allocate memory

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetGetFeatureNames_t) (DatasetHandle handle,

const int len,

int* num_feature_names,

const size_t buffer_len,

size_t* out_buffer_len,

char** feature_names);

static LGBM_DatasetGetFeatureNames_t LGBM_DatasetGetFeatureNames = NULL;

/*!

* \brief Free space for dataset.

* \param handle Handle of dataset to be freed

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetFree_t) (DatasetHandle handle);

static LGBM_DatasetFree_t LGBM_DatasetFree = NULL;

/*!

* \brief Save dataset to binary file.

* \param handle Handle of dataset

* \param filename The name of the file

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetSaveBinary_t) (DatasetHandle handle,

const char* filename);

static LGBM_DatasetSaveBinary_t LGBM_DatasetSaveBinary = NULL;

/*!

* \brief Create a dataset schema representation as a binary byte array (excluding data).

* \param handle Handle of dataset

* \param[out] out The output byte array

* \param[out] out_len The length of the output byte array (returned for convenience)

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetSerializeReferenceToBinary_t) (DatasetHandle handle,

ByteBufferHandle* out,

int32_t* out_len);

static LGBM_DatasetSerializeReferenceToBinary_t LGBM_DatasetSerializeReferenceToBinary = NULL;

/*!

* \brief Save dataset to text file, intended for debugging use only.

* \param handle Handle of dataset

* \param filename The name of the file

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetDumpText_t) (DatasetHandle handle,

const char* filename);

static LGBM_DatasetDumpText_t LGBM_DatasetDumpText = NULL;

/*!

* \brief Set vector to a content in info.

* \note

* - \a group only works for ``C_API_DTYPE_INT32``;

* - \a label and \a weight only work for ``C_API_DTYPE_FLOAT32``;

* - \a init_score only works for ``C_API_DTYPE_FLOAT64``.

* \param handle Handle of dataset

* \param field_name Field name, can be \a label, \a weight, \a init_score, \a group

* \param field_data Pointer to data vector

* \param num_element Number of elements in ``field_data``

* \param type Type of ``field_data`` pointer, can be ``C_API_DTYPE_INT32``, ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetSetField_t) (DatasetHandle handle,

const char* field_name,

const void* field_data,

int num_element,

int type);

static LGBM_DatasetSetField_t LGBM_DatasetSetField = NULL;

/*!

* \brief Set vector to a content in info.

* \note

* - \a group converts input datatype into ``int32``;

* - \a label and \a weight convert input datatype into ``float32``;

* - \a init_score converts input datatype into ``float64``.

* \param handle Handle of dataset

* \param field_name Field name, can be \a label, \a weight, \a init_score, \a group

* \param n_chunks The number of Arrow arrays passed to this function

* \param chunks Pointer to the list of Arrow arrays

* \param schema Pointer to the schema of all Arrow arrays

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetSetFieldFromArrow_t) (DatasetHandle handle,

const char* field_name,

int64_t n_chunks,

const ArrowArray* chunks,

const ArrowSchema* schema);

static LGBM_DatasetSetFieldFromArrow_t LGBM_DatasetSetFieldFromArrow = NULL;

/*!

* \brief Get info vector from dataset.

* \param handle Handle of dataset

* \param field_name Field name

* \param[out] out_len Used to set result length

* \param[out] out_ptr Pointer to the result

* \param[out] out_type Type of result pointer, can be ``C_API_DTYPE_INT32``, ``C_API_DTYPE_FLOAT32`` or ``C_API_DTYPE_FLOAT64``

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetGetField_t) (DatasetHandle handle,

const char* field_name,

int* out_len,

const void** out_ptr,

int* out_type);

static LGBM_DatasetGetField_t LGBM_DatasetGetField = NULL;

/*!

* \brief Raise errors for attempts to update dataset parameters.

* \param old_parameters Current dataset parameters

* \param new_parameters New dataset parameters

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetUpdateParamChecking_t) (const char* old_parameters,

const char* new_parameters);

static LGBM_DatasetUpdateParamChecking_t LGBM_DatasetUpdateParamChecking = NULL;

/*!

* \brief Get number of data points.

* \param handle Handle of dataset

* \param[out] out The address to hold number of data points

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetGetNumData_t) (DatasetHandle handle,

int* out);

static LGBM_DatasetGetNumData_t LGBM_DatasetGetNumData = NULL;

/*!

* \brief Get number of features.

* \param handle Handle of dataset

* \param[out] out The address to hold number of features

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetGetNumFeature_t) (DatasetHandle handle,

int* out);

static LGBM_DatasetGetNumFeature_t LGBM_DatasetGetNumFeature = NULL;

/*!

* \brief Get number of bins for feature.

* \param handle Handle of dataset

* \param feature Index of the feature

* \param[out] out The address to hold number of bins

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_DatasetGetFeatureNumBin_t) (DatasetHandle handle,

int feature,

int* out);

static LGBM_DatasetGetFeatureNumBin_t LGBM_DatasetGetFeatureNumBin = NULL;

/*!

* \brief Add features from ``source`` to ``target``.

* \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_t) (DatasetHandle target,

DatasetHandle source);

static LGBM_DatasetAddFeaturesFrom_t LGBM_DatasetAddFeaturesFrom = NULL;

/* --- start Booster interfaces */

/*!

* \brief Get int representing whether booster is fitting linear trees.

* \param handle Handle of booster

* \param[out] out The address to hold linear trees indicator

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterGetLinear_t) (BoosterHandle handle, int* out);

static LGBM_BoosterGetLinear_t LGBM_BoosterGetLinear = NULL;

/*!

* \brief Create a new boosting learner.

* \param train_data Training dataset

* \param parameters Parameters in format 'key1=value1 key2=value2'

* \param[out] out Handle of created booster

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterCreate_t) (const DatasetHandle train_data,

const char* parameters,

BoosterHandle* out);

static LGBM_BoosterCreate_t LGBM_BoosterCreate = NULL;

/*!

* \brief Load an existing booster from model file.

* \param filename Filename of model

* \param[out] out_num_iterations Number of iterations of this booster

* \param[out] out Handle of created booster

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterCreateFromModelfile_t) (const char* filename,

int* out_num_iterations,

BoosterHandle* out);

static LGBM_BoosterCreateFromModelfile_t LGBM_BoosterCreateFromModelfile = NULL;

/*!

* \brief Load an existing booster from string.

* \param model_str Model string

* \param[out] out_num_iterations Number of iterations of this booster

* \param[out] out Handle of created booster

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterLoadModelFromString_t) (const char* model_str,

int* out_num_iterations,

BoosterHandle* out);

static LGBM_BoosterLoadModelFromString_t LGBM_BoosterLoadModelFromString = NULL;

/*!

* \brief Get parameters as JSON string.

* \param handle Handle of booster

* \param buffer_len Allocated space for string

* \param[out] out_len Actual size of string

* \param[out] out_str JSON string containing parameters

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterGetLoadedParam_t) (BoosterHandle handle,

int64_t buffer_len,

int64_t* out_len,

char* out_str);

static LGBM_BoosterGetLoadedParam_t LGBM_BoosterGetLoadedParam = NULL;

/*!

* \brief Free space for booster.

* \param handle Handle of booster to be freed

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterFree_t) (BoosterHandle handle);

static LGBM_BoosterFree_t LGBM_BoosterFree = NULL;

/*!

* \brief Shuffle models.

* \param handle Handle of booster

* \param start_iter The first iteration that will be shuffled

* \param end_iter The last iteration that will be shuffled

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterShuffleModels_t) (BoosterHandle handle,

int start_iter,

int end_iter);

static LGBM_BoosterShuffleModels_t LGBM_BoosterShuffleModels = NULL;

/*!

* \brief Merge model from ``other_handle`` into ``handle``.

* \param handle Handle of booster, will merge another booster into this one

* \param other_handle Other handle of booster

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterMerge_t) (BoosterHandle handle,

BoosterHandle other_handle);

static LGBM_BoosterMerge_t LGBM_BoosterMerge = NULL;

/*!

* \brief Add new validation data to booster.

* \param handle Handle of booster

* \param valid_data Validation dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterAddValidData_t) (BoosterHandle handle,

const DatasetHandle valid_data);

static LGBM_BoosterAddValidData_t LGBM_BoosterAddValidData = NULL;

/*!

* \brief Reset training data for booster.

* \param handle Handle of booster

* \param train_data Training dataset

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterResetTrainingData_t) (BoosterHandle handle,

const DatasetHandle train_data);

static LGBM_BoosterResetTrainingData_t LGBM_BoosterResetTrainingData = NULL;

/*!

* \brief Reset config for booster.

* \param handle Handle of booster

* \param parameters Parameters in format 'key1=value1 key2=value2'

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterResetParameter_t) (BoosterHandle handle,

const char* parameters);

static LGBM_BoosterResetParameter_t LGBM_BoosterResetParameter = NULL;

/*!

* \brief Get number of classes.

* \param handle Handle of booster

* \param[out] out_len Number of classes

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterGetNumClasses_t) (BoosterHandle handle,

int* out_len);

static LGBM_BoosterGetNumClasses_t LGBM_BoosterGetNumClasses = NULL;

/*!

* \brief Update the model for one iteration.

* \param handle Handle of booster

* \param[out] is_finished 1 means the update was successfully finished (cannot split any more), 0 indicates failure

* \return 0 when succeed, -1 when failure happens

*/

LIGHTGBM_C_EXPORT int (*LGBM_BoosterUpdateOneIter_t) (BoosterHandle handle,

int* is_finished);

static LGBM_BoosterUpdateOneIter_t LGBM_BoosterUpdateOneIter = NULL;

/*!

* \brief Refit the tree model using the new data (online learning).

* \param handle Handle of booster

* \param leaf_preds Pointer to predicted leaf indices

* \param nrow Number of rows of ``leaf_preds``

* \param ncol Number of columns of ``leaf_preds``

* \return 0 when succeed, -1 when failure happens

*/