Usul is a Deep Neural Network and automatic differentiation library written in modern C++23 on top of xtensor. I wrote this library for people who want to express their models directly as mathematics in C++ and get all the fun stuff like auto-grad, back-prop and stuff like that, just write the maths, and Usul-cpp will handle the rest.
the way it works is simple, create a tensor using the tensor class, and you're good to go, so long as your data is in a tensor, you're good to go. However, right now there is only support for numerical data. For example:
Tensor A = {1.0, 2.0, 3.0};
Tensor B = {4.0, 5.0, 6.0};
auto Y = A + B;
std::cout << Y << '\n';Output (cheeky... I know, just like numpy):
{ 5., 7., 9. }, shape=(3)
The core class you interact with is Tensor, which is as a lightweight value-type handle wrapping a shared pointer of a Heart which owns your data, you do as well, but better let that stay where it is.
The actual tensor data and gradient state inside reside in the Heart structure, meaning your data and gradients are decoupled from the Tensor handle itself. Copying or passing a Tensor around is cheap, and the backend mixes std::shared_ptr (for parent tracking) and std::weak_ptr (inside backward pass closures) to propagate gradients efficiently without cyclic memory leaks.
Usul uses operator overloading so matrix mathematics is just plain text math. As an expression evaluates at runtime, each operation automatically registers a node into the compute graph, which is where Usul takes over:
Tensor A = {{1.0, 2.0}, {3.0, 4.0}};
Tensor B = {{4.0, 1.0}, {2.0, 2.0}};
auto add = A + B; // element-wise addition
auto sub = A - B; // element-wise subtraction
auto mul = A * B; // Hadamard (element-wise) multiplication
auto dot = A % B; // matrix multiplication (dot product)Beyond basic arithmetic, Usul also supports activation functions (ReLU, Sigmoid) that automatically register their derivatives into the compute graph along with other functions such as negate and resize.
You will need a C++23 compiler, CMake (3.20+), and vcpkg to pull xtensor and xtensor-blas.
cmake --preset vcpkg-default
cmake --build build
./build/UsulUsul has no plans on being big, however, that does not mean we cannot give it more super powers, upcoming are:
- optimiser functions such as SGD and Adam
- support for XGBoost
- and the biggest feature (in works), support for GPU acceleration (WebGPU)