Binary serialization

The library provides utility functions to serialize and deserialize various types of data in binary format.

These functions are especially useful for optimizing performance by caching expensive computations: serialize results once, then use deserialization to reload them quickly in future runs, avoiding recomputation.

They can also be used to transfer data between C++, Python, Matlab implementations.

Supported Types

The serialization system currently supports:

Built-in types (e.g., int, double, float) that are trivially copyable. The raw memory of the variables is directly written to or read from the stream ;
Interval objects ;
Matrix structures such as [Interval]Matrix, [Interval]Vector, and [Interval]Row, with either scalar or Interval elements ;
Any SampledTraj<T> objects, as long as serialize functions are defined for type T.

All functions assume that the given streams are open and valid for the requested operation.

Example of use

The serialization system consists of two core functions: serialize(...) and deserialize(...), which handle binary input/output of supported types. In C++, the functions can be used with any std::ostream or std::istream object (for example, binary files). In Python, however, their usage is currently limited to file objects.

Below are some example to illustrate how the interface works:

x1 = IntervalVector([[0,1],[-oo,0],Interval.pi()])
# x1 = [ [0, 1] ; [-inf, 0] ; [3.14159, 3.1416] ]

# Serializing the interval vector
with open("data.cdc", "wb") as f:
  serialize(f, x1)

# Deserializing the interval vector (possibly in another project)
x2 = IntervalVector()
with open("data.cdc", "rb") as f:
  deserialize(f, x2)

# x1 == x2

IntervalVector x1({{0,1},{-oo,0},Interval::pi()});
// x1 = [ [0, 1] ; [-inf, 0] ; [3.14159, 3.1416] ]

// Serializing the interval vector
std::ofstream out("data.cdc", std::ios::binary);
serialize(out, x1);
out.close();

// Deserializing the interval vector (possibly in another project)
IntervalVector x2;
std::ifstream in("data.cdc", std::ios::binary);
deserialize(in, x2);
in.close();

// x1 == x2

x1 = IntervalVector([[0,1],[-oo,0],Interval().pi]);
% x1 = [ [0, 1] ; [-inf, 0] ; [3.14159, 3.1416] ]

% Serializing the interval vector
serialize(py.open('data.cdc', 'wb'), x1);

% Deserializing the interval vector (possibly in another project)
x2 = IntervalVector();
deserialize(py.open('data.cdc', 'rb'), x2);

% x1 == x2

In this example, the .cdc extension is optional and serves as a suggested convention for Codac data.

Notes

All serialization assumes consistent architecture (e.g., same endianness and sizeof(double)) between writing and reading.
For custom types, serialization functions can be extended by writing new serialize/deserialize overloads.
When (de)serializing from/to files, check that streams are open and valid before use.

Available functions

template<typename T> inline void codac2::serialize(std::ostream &f, const T &x)

Writes the binary representation of a trivially copyable object to the given output stream.

Binary structure:

[raw memory of x]

Parameters:

f – output stream
x – object/variable to be serialized

template<typename T> inline void codac2::deserialize(std::istream &f, T &x)

Reads the binary representation of a trivially copyable object from the given input stream.

Binary structure:

[raw memory of x]

Parameters:

f – input stream
x – object to be deserialized

inline void codac2::serialize(std::ostream &f, const Interval &x)

Writes the binary representation of an Interval object to the given output stream.

Interval

binary structure:

[double_lb][double_ub]

Parameters:

f – output stream
x – Interval object to be serialized

inline void codac2::deserialize(std::istream &f, Interval &x)

Creates an Interval object from the binary representation given in an input stream.

Interval

binary structure:

[double_lb][double_ub]

Parameters:

f – input stream
x – Interval object to be deserialized

template<typename T, int R = -1, int C = -1> inline void codac2::serialize(std::ostream &f, const Eigen::Matrix<T, R, C> &x)

Writes the binary representation of an Eigen::Matrix to the given output stream. The structure can be a matrix, a row, a vector, with double or Interval components.

Matrix

binary structure:

[Index_rows][Index_cols][element_00][element_01]…[element_rc]

Parameters:

f – output stream
x – matrix structure to be serialized

template<typename T, int R = -1, int C = -1> inline void codac2::deserialize(std::istream &f, Eigen::Matrix<T, R, C> &x)

Reads the binary representation of an Eigen::Matrix from the given input stream. The structure can be a matrix, a row, a vector, with double or Interval components.

Matrix

binary structure:

[Index_rows][Index_cols][element_00][element_01]…[element_rc]

Parameters:

f – input stream
x – matrix structure to be deserialized

template<typename T> inline void codac2::serialize(std::ostream &f, const SampledTraj<T> &x)

Writes the binary representation of a SampledTraj object to the given output stream.

SampledTraj binary structure:

[nb_samples][t0][x0][t1][x1]…[tn][xn]

Parameters:

f – output stream
x – SampledTraj object to be serialized

template<typename T> inline void codac2::deserialize(std::istream &f, SampledTraj<T> &x)

Reads the binary representation of a SampledTraj object from the given input stream.

SampledTraj binary structure:

[nb_samples][t0][x0][t1][x1]…[tn][xn]

Parameters:

f – input stream
x – SampledTraj object to be deserialized

Technical documentation

See the C++ API documentation of these functions.