Skip to content

Library

Jump to bottom
Yue Wu edited this page Aug 29, 2016 · 3 revisions

Library Call

SOL provides a dynamic library named "sol.dll" on Windows or "libsol.so" on Unix like systems. Interfaces of the library are comprised of three parts: initialization, training/testing, and finalization.

Initialization of IO

Initialization of IO means to create a data iterator. The API is:

void* sol_CreateDataIter(int batch_size, int buf_size);

  • batch_size: the number of data samples in each mini-batch while loading data;

  • buf_size: number of mini-batches to cache while loading data.

With the created data iterator, users can load one or more data sequentially. The API is:

void* sol_LoadData(void* data_iter, const char* path, const char* format, int pass_num);

  • ** data_iter**: the created data iterator;

  • ** path**: path the training data;

  • ** format**: format of the data ('svm', 'csv', 'bin', etc.);

  • ** pass_num**: number of passes to go through the data.

Note: sol_LoadData can be called multiple times to add multiple training data. The data will be processed sequentially as they are added to the data iterator. This is in accordance with the target of online learning, where the data distribution may change over time.

Initialization of Model

Initialization of Model means to create a model instance. There are two ways: train from scratch and finetune from an existing model.

  1. Train from Scratch

Create a new clean model for training from scratch:

void* sol_CreateModel(const char* name, int class_num);
- **name**: name of the algorithm to be used;

- ** class_num**: number of classes to train.
  1. Finetune from Existing Model

Load an existing model for continuous training:

void* sol_RestorModel(const char* model_path);
- **model_path**: path to existing model
  1. Set Model Parameter
	void* sol_SetModelParameter(void* model, const char* param_name, const char* param_val);
- **model**: the model instance;

- **param_name**: name of the parameter ('loss', 'eta', etc.);

- **param_val**: value string of the parameter.
  1. Get Model Parameter
	void* sol_GetModelParameters(void* model, sol_get_parameter_callback callback, void* user_context);
- **model**: the model instance;

- **callback**: callback function to handle the parameters;

- **user_context**: flexible place to handle the parameter name and value

  typedef void (*sol_get_parameter_callback)(void* user_context, const char* param_name, const char* param_val);;
- **user_context**: flexible place to handle the parameter name and value

- **param_name**: name of the parameter ('loss', 'eta', etc.);

- **param_val**: value string of the parameter.

Training & Testing

The API to train a model is:

void sol_Train(void* model, void* data_iter);

  • model: the model instance;

  • data_iter: data iterator to be used for training.

The API to test a model is:

void sol_Test(void* model, void* data_iter, const char* output_path);

  • model: the trained model instance;

  • ** data_iter**: data iterator to be used for testing.

  • ** output_path**: path to save the predicted results, if no need to save, set to NULL.

The API to get the detailed prediction results of a model is:

int sol_Predict(void* model, void* data_iter, sol_predict_callback callback, void* user_context);

  • model model to be tested

  • ** data_iter** data iterator

  • ** callback** callback to handle the predicted results

  • ** user_context** flexible place to handle predicted results

  • return number of samples processed

The callback is defined as:

typedef void (*sol_predict_callback)(void* user_context, double label, double predict, int cls_num, float* scores);
  • user_context flexible place to handle predicted results
  • label groundtruth label
  • predict predicted label
  • cls_num number of classses
  • scores predicted scores

Finalization

Finalization is to release the initialized resources. The functions are:

void sol_ReleaseDataIter(void** data_iter);
//save model to a file
void sol_SaveModel(void* model, const char* model_path);
void sol_ReleaseModel(void** model);

Use Library on Windows Visual Studio

SOL can only be linked as a dynamic library to support the reflection of class names to class constructors. It is named as "sol.dll" on Windows. Interface of the library is in "sol/c_api.h". Suppose SOL is installed into "SOL/dist". The following shows an example to link SOL to another project in Visual Studio 2015.

  1. Create an empty Win32 C/C++ project.

  2. Add include path and library path to the created project. Properties -> Select All Configurations -> VC++ Directories.

  3. Add link libraries to the project. Linker -> Input -> add the library. In Release mode, add sol.lib. In Debug mode, add sold.lib.

  4. Test the program. Add a new source file and use the above APIs to test the library. The "SOL/tools/sol_c.cc" is a good example to use the Library Calls.

Use Library on Linux/Unix

Suppose SOL is installed into "SOL/dist"}. On linux, users need to set the include path, library link path, and linked libraries for "gcc/g++/clang/clang++" compilers.

  1. Include path:
-I <SOL>/dist/include

Then include "sol/c_api.h" in your source files.

  1. Link path and library
-L <SOL>/dist/bin -sol
Clone this wiki locally