Serialization Tool

This chapter introduces the serialization tool of OPTIMake. The serialization tool can serialize optimization problems and store them as binary files, and can also deserialize and read optimization problems from binary files. Typical use cases for this tool include:

• Problem reproduction: During development, you may need to reproduce the solving process of a certain problem. Using the serialization tool, you can save the current optimization problem as a binary file and reproduce and debug it on different platforms
• Test protection: During testing, you can serialize test cases into binary files as test cases for solving

info

• The serialization functionality is only enabled when enable_serialization is set to True in the code generation options; otherwise, empty functions are generated
• The serialization and deserialization functions involve dynamic memory allocation and deallocation
• The binary file stored by serialization does not contain the specific model definition, only the model's data, such as parameters and initial guesses

Using the vehicle problem as an example, after code generation, vehicle_solver.h contains the following interface functions for serialization:

• vehicle_serialization_to_buffer: Store the optimization problem to a buffer variable
• vehicle_serialization_save_buffer_to_file: Save the buffer variable to a file
• vehicle_serialization_save_to_file: Store the optimization problem to a file
• vehicle_serialization_load_from_file: Load the optimization problem from a file

Serialization

The serialization functionality is generally called before solving, so that the initial guess set by the user in the workspace can be stored. There are two modes:

• Directly store the optimization problem to a binary file
• Store the optimization problem to a buffer, then save the buffer to a binary file. A typical use case is recording optimization problems that fail to solve or produce abnormal results: store the optimization problem to a buffer before solving, and if solving fails or results are abnormal, save the buffer to a binary file

Below is a code snippet for directly storing the optimization problem to a binary file serialization.dat:

int save_ret = 0;
save_ret = vehicle_serialization_save_to_file(&prob, &option, &ws, "serialization.dat");

Below is a code snippet for storing the optimization problem to a buffer and then saving the buffer to a binary file:

int save_ret = 0;
Vehicle_SerializationBuffer buffer;
vehicle_serialization_to_buffer(&prob, &option, &ws, &buffer);
save_ret = vehicle_serialization_save_buffer_to_file(&buffer, "serialization.dat");

When serialization succeeds, save_ret is 1; otherwise, save_ret is 0.

Deserialization

Below is a code snippet for reading a binary file and solving:

int load_ret = 0;
load_ret = vehicle_serialization_load_from_file("serialization.dat", &prob, &option, &ws);
vehicle_solve(&prob, &option, &ws, &output);

When loading succeeds, load_ret is 1; otherwise, load_ret is 0 (e.g., when reading binary data from a different optimization problem).

Compatibility

The deserialization (loading) tool is designed with a best-effort loading principle, following these constraints:

• Compatible across different solver versions
• The number and order of model variables and parameters must be consistent with the binary file
• The number of model stages N must be consistent with the binary file
• Model constraints (equality, inequality, soft/hard constraints) may differ from the binary file