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.
• 🔧 High-Level Tensor Abstraction – Easily create, manipulate, and operate on tensors.
• 💾 Flexible Tensor IO – Seamless reading and writing of tensors to text files.
• 🏗 Simplified Model Loading – Load and run saved TensorFlow models with minimal setup.
• ⚡ XLA Acceleration – Effortlessly enable or disable TensorFlow’s XLA optimizations.
• 🚀 Near-Native Performance – Achieves 99.35% to 99.79% of native TensorFlow speed 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%.
• Txeo’s abstraction layer provides ease of use with almost no cost to performance.

⚡ Installation Guide

🔹Requirements

• Supported OS: 🐧 Linux (Tested on Ubuntu and Manjaro).
  • ⚠️ Windows and macOS are not yet officially supported.
• Build Tools: 🛠 Essential C/C++ development tools.
• CMake: 🏗 Built with v3.25+.
• 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.
• 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 hosted at Netlify.

📆 Roadmap

Txeo is actively evolving! Here are some of the upcoming features:

🏋️ Training Capabilities

• Model Training - Enable training models using TensorFlow C++.
• Backpropagation Support - Implement automatic differentiation.
• Gradient Descent & Optimizers - Integrate optimizers like SGD and Adam.

🔢 Advanced Tensor Operations

• Matrix Multiplication (matmul) - Perform tensor dot products.
• Broadcasting Support - Support element-wise operations on different shapes.
• Reduction Operations (sum, mean, max) - 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.
• Frozen Graph Support - Load & optimize frozen models for inference.

📬 Contact

For any inquiries or contributions:

• GitHub Discussions: Start a discussion
• Issue Reporting: Open an issue
• Email: robertodias70@outlook.com (for serious inquiries only)

📜 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
  • Protobuf - Licensed under BSD 3-Clause
  • 📜 Protobuf License

📌 Note: The precompiled binaries of TensorFlow and Protobuf provided in the releases section are unmodified versions of the official source code.