Evaluation library

This is the fastest way to evaluate a model. The library provides a C API and a simple C++ wrapper API. The C API interface can be accessed from any programming language.

BuildBuild

Source codeSource code

CatBoost source code is stored as a Git repository on GitHub at https://github.com/catboost/catboost/. You can obtain a local copy of this Git repository by running the following command from a command line interpreter (you need to have Git command line tools installed):

git clone https://github.com/catboost/catboost.git

Build using CMakeBuild using CMake

Build using Ya MakeBuild using Ya Make

1. Setup build environment

2. Open the catboost directory from the local copy of the CatBoost repository.

3. Run the following command:

   Shared library

   Static library (only for Linux and macOS)

   ./ya make -r [optional parameters] catboost/libs/model_interface
   

   The output directory catboost/libs/model_interface will contain:

   OS	Files
   Linux	libcatboostmodel.so
   macOS	libcatboostmodel.dylib
   Windows	catboostmodel.lib and catboostmodel.dll

   ./ya make -r [optional parameters] catboost/libs/model_interface/static
   

   The output directory catboost/libs/model_interface/static will contain a pair of artifacts:

   • liblibcatboostmodel.o. This part contains symbols that require forced initialization.
   • libcatboostmodel.a. This part contains all other symbols.

   Useful parameters:

   Parameter	Description
   -DCUDA_ROOT	The path to CUDA. This parameter is required to support training on GPU.
   -DHAVE_CUDA=no	Disable CUDA support. This speeds up compilation. By default, the package is built with CUDA support if CUDA Toolkit is installed.

Build using Make (Linux-only)Build using Make (Linux-only)

Choose the preferred way to use the evaluation library and compile it accordingly:

export CXX=/path/to/clang++
export CC=/path/to/clang

make -f make/model_interface.CLANG50-LINUX-X86_64.makefile

export CXX=/path/to/clang++
export CC=/path/to/clang

make -f make/model_interface_static.CLANG50-LINUX-X86_64.makefile

UsageUsage

The CatBoost model can be loaded from a file or initialized from the buffer memory.

C APIC API

Perform the following steps to use this API:

1. Use the methods from the c_api.h file (refer to the doxygen-style documentation for details).

   Sample C code without include statements:

   float floatFeatures[100];
   char* catFeatures[2] = {"1", "2"};
   double result[1];
   ModelCalcerHandle modelHandle;
   modelHandle = ModelCalcerCreate();
   if (!LoadFullModelFromFile(modelHandle, "model.cbm")) {
       printf("LoadFullModelFromFile error message: %s\n", GetErrorString());
   }
   if (!CalcModelPrediction(
           modelHandle,
           1,
           &floatFeatures, 100,
           &catFeatures, 2,
           &result, 1
       )) {
       printf("CalcModelPrediction error message: %s\n", GetErrorString());
   }
   ModelCalcerDelete(modelHandle);
   

2. Add the required libraries to the linking command.

   Linker is often invoked through the compiler call, examples below assume that.

   Shared library

   Static library built using CMake

   Static library built using Ya Make or Make (Linux or macOS only)

   • Linux or macOS

     Example:

     clang++ <your sources and options> -L<path_to_dir_with_libcatboostmodel> -lcatboostmodel
     

   • Windows

     Example:

     cl.exe <your sources and options> /link <path_to_dir_with_libcatboostmodel>\catboostmodel.lib
     

   The shared library must be accessible from the dynamic library loader search path. See your operating system documentation for the details.

   Add both global and non-global parts to the linker input. global part requires passing special platform-specific flags to force the required initialization of symbols.

   See per-platform examples below:

   • Linux

     On Linux additional libraries libdl and libpthread have to be added to the linker input as well.

     clang++ <your sources and options> -nodefaultlibs -lpthread -ldl -Wl,--whole-archive <catboost_lib_dir>/libcatboostmodel_static.global.a -Wl,--no-whole-archive <catboost_lib_dir>/libcatboostmodel_static.a
     

   • macOS

     clang++ <your sources and options> <catboost_lib_dir>/libcatboostmodel_static.a
     -Wl,-force_load,<catboost_lib_dir>/libcatboostmodel_static.global.a
     

   • Windows

     When using c_api.h with the static library the additional define CATBOOST_API_STATIC_LIB is required.

     cl.exe <your sources and options> /DCATBOOST_API_STATIC_LIB /link /WHOLEARCHIVE:<catboost_lib_dir>\catboostmodel_static.global.lib <catboost_lib_dir>\catboostmodel_static.lib
     

   Add both liblibcatboostmodel.o and libcatboostmodel.a to the linker input.

   On Linux additional libraries libdl and libpthread have to be added to the linker input as well.

   Example:

   clang++ <your sources and options> liblibcatboostmodel.o libcatboostmodel.a -ldl -lpthread
   

C++ wrapper APIC++ wrapper API

A C++ wrapper for the C API interface is also available.

Refer to the wrapped_calcer.h file and the sample CMake project in the CatBoost repository for more details.

Usage example:

ModelCalcerWrapper calcer("model.cbm");
std::vector<float> floatFeatures(100);
std::vector<std::string> catFeatures = {"one", "two", "three"};
std::cout << calcer.Calc(floatFeatures, catFeatures) << std::endl;

ModelCalcerWrapper also has a constructor to read data from the memory buffer.

Related informationRelated information

Source code and a CMake usage example