Txeo: a Modern C++ Wrapper for TensorFlow
๐ Overview
Txeo is a lightweight and intuitive C++ wrapper for TensorFlow, designed to simplify TensorFlow C++ development while preserving high performance and flexibility. Built entirely with Modern C++, Txeo allows developers to use TensorFlow with the ease of a high-level API, eliminating the complexity of its low-level C++ interface.
โจ Features
๐ฆ Intuitive API โ A clean and modern C++ interface, simplifying TensorFlow C++ usage.
โ A clean and modern C++ interface, simplifying TensorFlow C++ usage. ๐ง High-Level Tensor Abstraction โ Easily create, manipulate, and operate on tensors.
โ Easily create, manipulate, and operate on tensors. ๐พ Flexible Tensor IO โ Seamless reading and writing of tensors to text files.
โ Seamless reading and writing of tensors to text files. ๐ Simplified Model Loading โ Load and run saved TensorFlow models with minimal setup.
โ Load and run saved TensorFlow models with minimal setup. โก XLA Acceleration โ Effortlessly enable or disable TensorFlowโs XLA optimizations.
โ Effortlessly enable or disable TensorFlowโs XLA optimizations. ๐ Near-Native Performance โ Achieves 99.35% to 99.79% of native TensorFlow speed with negligible overhead.
โ Achieves with negligible overhead. ๐ก Encapsulated TensorFlow API โ Fully abstracts TensorFlow internals for a cleaner, more maintainable experience.
๐ Performance Comparison
Txeo was benchmarked against the native TensorFlow C++ API using inference from a saved multiclassification convolution model.
Model and other info: 279,610 parameters 1 Softmax Output Layer with 10 classes 3 Fully-Connected ReLU Convolutional Layers with 200 nodes each Input : 210,000 grayscale images (28ร28). CPU : AMD Ryzen 7 5700X CPU TensorFlow : Compiled with CPU optimization
๐ Results Overview
Compiler Txeo (ฮผs) TensorFlow (ฮผs) Difference (%) GCC 233,994 232,494 +0.65% Intel 234,489 232,683 +0.78% Clang 236,858 234,016 +1.21%
The performance overhead is negligible , ranging from 0.65% to 1.21% .
, ranging from . Txeoโs abstraction layer provides ease of use with almost no cost to performance.
โก Installation Guide
Supported OS: ๐ง Linux (Tested on Ubuntu and Manjaro). โ ๏ธ Windows and macOS are not yet officially supported.
๐ง (Tested on Ubuntu and Manjaro). Build Tools: ๐ Essential C/C++ development tools.
๐ Essential C/C++ development tools. CMake: ๐ Built with v3.25+ .
๐ Built with . Compilers: ๐ป Requires a C++20-compatible compiler: โ
Clang (Tested with v19.1.2 ) โ
GCC (Tested with v13.2.0 ) โ
Intel (Tested with v2025.0.4 ) ๐ Supports concepts, ranges, and other C++20 features .
๐ป Requires a C++20-compatible compiler: Dependencies: ๐ TensorFlow 2.18.0 โ GitHub ๐ Protobuf 3.21.9 โ GitHub
๐นOption 1: Installation Steps with Precompiled Binaries (Fastest Way)
This method installs TensorFlow and Protobuf binaries into /opt/ .
1๏ธโฃ Download and install Protobuf
wget https://github.com/rdabra/txeo/releases/download/v1.0.0/libprotobuf-3.21.9-linux-x64.tar.gz sudo tar -xzf libprotobuf-3.21.9-linux-x64.tar.gz -C /opt/ echo " export Protobuf_ROOT_DIR=/opt/protobuf " >> ~ /.bashrc source ~ /.bashrc
2๏ธโฃ Download and install TensorFlow
Choose the correct version based on your system:
Version Download ๐ป Without CPU optimizations libtensorflow-2.18-linux-x64-cpu.tar.gz ๐ With CPU optimizations: libtensorflow-2.18-linux-x64-cpu-opt.tar.gz ๐ฎ With GPU support: libtensorflow-2.18-linux-x64-gpu.tar.gz
๐ก Important Note : The Protobuf and TensorFlow source codes used for compiling the binaries above were not modified in any way. These assets are only provided to simplify installation for Txeo users.
Installing TensorFlow binaries:
wget https://github.com/rdabra/txeo/releases/download/v1.0.0/libtensorflow-2.18-linux-x64-cpu.tar.gz sudo tar -xzf libtensorflow-2.18-linux-x64-cpu.tar.gz -C /opt/ echo " export TensorFlow_ROOT_DIR=/opt/tensorflow " >> ~ /.bashrc source ~ /.bashrc
3๏ธโฃ Clone and install Txeo
Installing Txeo and making libraries visible via library path:
git clone https://github.com/rdabra/txeo.git cd txeo mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release make -j $( nproc ) sudo make install echo " export LD_LIBRARY_PATH=/opt/tensorflow/lib:/opt/txeo/lib: $LD_LIBRARY_PATH " >> ~ /.bashrc
๐นOption 2: Installation Steps with Protobuf and TensorFlow built from source (may take a long time)
1๏ธโฃ Clone and install Protobuf
git clone https://github.com/protocolbuffers/protobuf.git cd protobuf git checkout refs/tags/v3.21.9 cmake -S. -Bcmake-out -G Ninja -DCMAKE_INSTALL_PREFIX= " /opt/protobuf " -Dprotobuf_ABSL_PROVIDER=package -Dprotobuf_BUILD_TESTS=OFF cd cmake-out cmake --build . sudo cmake --install . echo " export Protobuf_ROOT_DIR=/opt/protobuf " >> ~ /.bashrc source ~ /.bashrc
2๏ธโฃ Clone and install Tensorflow
โ ๏ธ Important: Ensure Bazel is installed before proceeding. You can use Bazelisk to manage Bazel versions: Bazelisk GitHub. For the gcc compiler, key -std=gnu2x must be removed.
git clone https://github.com/tensorflow/tensorflow.git cd tensorflow git checkout refs/tags/v2.18.0 ./configure bazel build -c opt --copt=-std=gnu2x --copt=-mavx --copt=-mavx2 --copt=-mfma --copt=-msse4.1 --copt=-msse4.2 //tensorflow:libtensorflow_cc.so //tensorflow:libtensorflow_framework.so //tensorflow:install_headers
Copying libraries and includes accordingly:
cd bazel-bin sudo mkdir /opt/tensorflow sudo cp -r tensorflow/include /opt/tensorflow sudo mkdir /opt/tensorflow/lib sudo cp -r tensorflow/ * .so * /opt/tensorflow/lib echo " export TensorFlow_ROOT_DIR=/opt/tensorflow " >> ~ /.bashrc source ~ /.bashrc
3๏ธโฃ Installing Txeo
git clone https://github.com/rdabra/txeo.git cd txeo mkdir build && cd build cmake .. -DCMAKE_BUILD_TYPE=Release make -j $( nproc ) sudo make install echo " export LD_LIBRARY_PATH=/opt/tensorflow/lib:/opt/txeo/lib: $LD_LIBRARY_PATH " >> ~ /.bashrc
๐ Basic Usage
This section provides two simple C++ examples to help you get started with Txeo.
๐ Prerequisite: Before compiling, ensure that TensorFlow and Txeo are properly installed in /opt/ .
If necessary, add the library paths: export LD_LIBRARY_PATH=/opt/tensorflow/lib:/opt/txeo/lib: $LD_LIBRARY_PATH
๐น A Simple CMakeLists.txt
To compile a project using Txeo, use the following CMakeLists.txt file.
# CMakeLists.txt cmake_minimum_required ( VERSION 3.25) project (HelloTxeo LANGUAGES CXX) # Set C++ standard set (CMAKE_CXX_STANDARD 20) set (CMAKE_CXX_STANDARD_REQUIRED ON ) # Manually specify Txeo installation paths set (TXEO_INCLUDE_DIR "/opt/txeo/include" ) set (TXEO_LIBRARY "/opt/txeo/lib/libtxeo.so" ) # Manually specify TensorFlow paths set (TENSORFLOW_INCLUDE_DIR "/opt/tensorflow/include" ) set (TENSORFLOW_CC_LIBRARY "/opt/tensorflow/lib/libtensorflow_cc.so" ) set (TENSORFLOW_FRAMEWORK "/opt/tensorflow/lib/libtensorflow_framework.so" ) # Create an executable add_executable (hello_txeo main.cpp) # Include directories for Txeo and TensorFlow target_include_directories (hello_txeo PRIVATE ${TXEO_INCLUDE_DIR} ${TENSORFLOW_INCLUDE_DIR} ) # Link Txeo and TensorFlow manually target_link_libraries (hello_txeo PRIVATE ${TXEO_LIBRARY} ${TENSORFLOW_CC_LIBRARY} ${TENSORFLOW_FRAMEWORK} ) # Optionally set rpath for runtime library search set_target_properties (hello_txeo PROPERTIES INSTALL_RPATH "/opt/txeo/lib;/opt/tensorflow/lib" )
๐ก Note: If TensorFlow is installed in a different location, update TENSORFLOW_INCLUDE_DIR and TENSORFLOW_LIBRARY paths accordingly.
๐ข Example 1: Tensor Basics
Here is a code sample where a 3x3 txeo::Tensor is defined, written to a file and then another instance is created from the saved file.
// main.cpp # include " txeo/Tensor.h " # include " txeo/TensorIO.h " # include < iostream > using namespace txeo ; using namespace std ; int main () { // 3ร3 tensor created from a list of double values in row-major order Tensor< double > tensor ({ 3 , 3 }, { 1 . 0f , 2 . 0f , 3 . 0f , 4 . 0f , 5 . 0f , 6 . 0f , 7 . 0f , 8 . 0f , 9 . 0f }); // Save tensor to file TensorIO::write_textfile (tensor, " tensor.txt " ); // Load tensor from file auto loaded_tensor = TensorIO::read_textfile< double >( " tensor.txt " ); // Reshapes the loaded tensor to one order (one axis) loaded_tensor. reshape ({ 9 }); // Display loaded tensor cout << loaded_tensor << endl; return 0 ; }
๐ฎ Example 2: Running Inference with a Saved Model
This example loads a saved TensorFlow model, performs inference on an input tensor, and saves the output:
// main.cpp # include " txeo/Predictor.h " # include " txeo/Tensor.h " # include " txeo/TensorIO.h " using namespace txeo ; using namespace std ; int main () { // Define paths to model and input/output tensors string model_path{ " path/to/saved_model " }; string input_path{ " path/to/input_tensor.txt " }; string output_path{ " path/to/output_tensor.txt " }; // Load the model Predictor< float > predictor{model_path}; // Read input tensor from file auto input = TensorIO::read_textfile< float >(input_path); // Run inference auto output = predictor. predict (input); // Save output tensor to file TensorIO::write_textfile (output, output_path); return 0 ; }
๐ก Note: Ensure that "path/to/saved_model" contains a valid TensorFlow model before running this example.
๐ For more samples, please visit the examples folder.
๐ Documentation with extensive usage examples is available at txeo site.
๐ Roadmap
Txeo is actively evolving! Here are some of the upcoming features:
๐๏ธ Training Capabilities
Model Training - Enable training models using TensorFlow C++.
- Enable training models using TensorFlow C++. Backpropagation Support - Implement automatic differentiation.
- Implement automatic differentiation. Gradient Descent & Optimizers - Integrate optimizers like SGD and Adam.
๐ข Advanced Tensor Operations
Matrix Multiplication ( matmul ) - Perform tensor dot products.
- Perform tensor dot products. Broadcasting Support - Support element-wise operations on different shapes.
- Support element-wise operations on different shapes. Reduction Operations ( sum , mean , max ) - Compute statistics on tensors.
- Compute statistics on tensors. Linear Algebra Functions (SVD, QR decomposition) - Matrix Computations on tensors.
๐ Model Saving & Loading Enhancements
Checkpointing - Save model weights at different training stages.
- Save model weights at different training stages. Frozen Graph Support - Load & optimize frozen models for inference.
๐ฌ Contact
For any inquiries or contributions:
๐ License
Txeo is licensed under the Apache License 2.0, meaning it is open-source, free to use, modify, and distribute, while requiring proper attribution.
๐ Third-Party Licenses
Txeo depends on third-party libraries that have their own licenses:
TensorFlow C++ - Licensed under Apache License 2.0 ๐ TensorFlow License ๐ TensorFlow GitHub
- Licensed under Protobuf - Licensed under BSD 3-Clause ๐ Protobuf License
- Licensed under