API Reference

Complete documentation of all classes, methods, and functions in TinyRL.

Quick Links

Category	Classes/Functions
Core	ag::Tensor, ag::Matrix
Layers	nn::Linear, nn::Conv2D, nn::LayerNorm, nn::Sequential
Activations	relu, leaky_relu, tanh, softmax, softplus
Optimizers	ag::SGD, ag::RMSProp, ObGD
Math	sum, mean, exp, log, pow, sqrt, transpose

---

Table of Contents

• Core Classes
• ag::Tensor
• ag::Matrix
• Neural Network Layers
• nn::Linear
• nn::Conv2D
• nn::LayerNorm
• Activation Functions
• nn::Sequential
• Optimizers
• ag::SGD
• ag::RMSProp
• ObGD (Stream-X module)
• Utility Functions

---

Core Classes

ag::Tensor

The main tensor class supporting automatic differentiation.

Constructor

Tensor(Matrix value, bool requires_grad = false);
Tensor(const Matrix& value, bool requires_grad, const std::string& name);

Parameter	Type	Default	Description
value	Matrix	required	Underlying matrix data
requires_grad	bool	false	Track gradients
name	string	none	Optional name for debugging

Methods

Value and Gradient Access

Method	Returns	Description
value()	const Matrix&	Underlying matrix
grad()	const Matrix&	Gradient matrix
requires_grad()	bool	Whether tracking gradients
zero_grad()	void	Zero gradients

Computational Graph

Method	Description
backward()	Backpropagate gradients
clear_graph()	Free computational graph
detach()	Detach from graph

Shape Operations

Method	Returns	Description
shape()	Shape	Tensor dimensions (4D array)
size()	size_t	Total number of elements
numel()	int	Number of elements
item()	Float	Scalar value (for 1-element tensors)
matmul(other)	Tensor	Matrix multiplication
transpose()	Tensor	Transposed tensor (swaps dims 0 and 1)
reshape(shape)	Tensor	Reshape tensor to new dimensions (copy)
flatten()	Tensor	Flatten to {numel(), 1, 1, 1} (use nn::Flatten to keep batch)

Operators

// Element-wise (with broadcasting)
tensor1 + tensor2    // Addition
tensor1 - tensor2    // Subtraction
tensor1 * tensor2    // Multiplication
tensor1 / tensor2    // Division

// Scalar operations
tensor + scalar
tensor * scalar
scalar - tensor

Example

#include "autograd.h"

ag::Tensor x(ag::Matrix::Random(2, 3), true, "input");
ag::Tensor y(ag::Matrix::Random(3, 2), true, "weights");

auto z = x.matmul(y);
auto loss = ag::sum(z);
loss.backward();

std::cout << "x gradients:\n" << x.grad() << std::endl;
std::cout << "y gradients:\n" << y.grad() << std::endl;

---

ag::Matrix

Base matrix class for tensor operations. Provides the underlying data storage and basic matrix operations.

Constructors

Matrix()                                       // Default constructor
Matrix(int rows, int cols)                     // 2D matrix (shape {rows, cols, 1, 1})
Matrix(int rows, int cols, Float value)        // 2D matrix filled with value
Matrix(Shape shape)                            // 4D tensor (Shape = std::array<int,4>)
Matrix(Shape shape, Float value)               // 4D tensor filled with value
Matrix(std::initializer_list<std::initializer_list<Float>> values) // 2D initializer

Static Factory Methods

// Random matrices
Matrix::Random(int rows, int cols)                    // 2D random matrix
Matrix::Random(int dim1, int dim2, int dim3, int dim4) // 4D random tensor
Matrix::Random(Shape shape)                           // 4D random tensor

// Constant matrices
Matrix::Zeros(int rows, int cols)                     // Zero-filled matrix
Matrix::Zeros(int dim1, int dim2, int dim3, int dim4) // Zero-filled 4D tensor
Matrix::Zeros(Shape shape)                            // Zero-filled 4D tensor

Matrix::Ones(int rows, int cols)                      // Matrix filled with ones
Matrix::Ones(int dim1, int dim2, int dim3, int dim4)  // 4D tensor filled with ones
Matrix::Ones(Shape shape)                             // 4D tensor filled with ones

Matrix::Constant(int rows, int cols, Float value)     // Constant-filled matrix
Matrix::Constant(int dim1, int dim2, int dim3, int dim4, Float value) // 4D tensor
Matrix::Constant(Shape shape, Float value)            // 4D tensor

Core Methods

Access and Information

• rows() - Number of rows (2D only)
• cols() - Number of columns (2D only)
• shape() - Returns dimensions as Shape (std::array)
• data() - Direct access to underlying data
• size() - Total number of elements
• numel() - Total number of elements (int)

Element Access

// 2D access
matrix(i, j)                    // Access element at (i, j)

// 4D access
matrix(batch, channel, height, width)  // Access 4D tensor element

Matrix Operations

• transpose() - Returns transposed matrix
• reshape(Shape) - Reshapes to new dimensions
• flatten() - Flattens to {numel(), 1, 1, 1}

Element-wise Operations

• sum() - Sum of all elements
• mean() - Mean of all elements
• colwiseSum() - Column-wise sums
• rowwiseSum() - Row-wise sums
• square() - Square each element
• sqrt() - Square root of each element
• abs() - Absolute value of each element
• exp() - Exponential of each element
• log() - Natural log of each element
• pow(Float) - Power of each element

Utility Methods

• block(row, col, row_count, col_count) - 2D sub-matrix (2D only)
• clone() - Copy the matrix
• zero() / fill(Float) - Fill with zeros or a constant

Static Methods

// Convolution operations
Matrix::conv2d_forward(input, kernel, stride, padding)   // 2D convolution
Matrix::conv2d_backward(input, kernel, grad_out, grad_input, grad_kernel, stride, padding)

Operators

// Matrix arithmetic
matrix1 + matrix2    // Matrix addition
matrix1 - matrix2    // Matrix subtraction
matrix * scalar      // Scalar multiplication
matrix / scalar      // Scalar division

Usage Example

#include "matrix.h"

// Create matrices
ag::Matrix A = ag::Matrix::Random(3, 4);
ag::Matrix B = ag::Matrix::Random(4, 2);
ag::Matrix C = ag::Matrix::Zeros(3, 2);

// Perform operations
auto result = A.matmul(B);
auto squared = result.square();
auto sum = squared.sum();

std::cout << "Result shape: " << result.shape()[0] << "x" << result.shape()[1] << std::endl;
std::cout << "Sum: " << sum << std::endl;

Neural Network Layers

nn::Linear

Fully connected (dense) layer for neural networks.

Constructor

Linear(int input_dim, int output_dim, bool requires_grad = true)
Linear(int input_dim, int output_dim, Float sparsity, bool requires_grad = true)

Parameters: - input_dim: Number of input features - output_dim: Number of output features - sparsity: Fraction of weights set to zero (sparse init only) - requires_grad: Whether weights track gradients

Members

• weights: Tensor containing the weight matrix
• bias: Tensor containing the bias vector (if enabled)

Methods

• forward(const Tensor& input) - Performs forward pass
• get_parameters() - Returns vector of trainable parameters

Usage Example

#include "layers.h"

// Create linear layer
nn::Linear layer(784, 128);  // 784 inputs, 128 outputs

// Forward pass
ag::Tensor input(ag::Matrix::Random(32, 784), false);
ag::Tensor output = layer.forward(input);

// Access parameters
auto params = layer.get_parameters();
std::cout << "Weights shape: " << layer.weights.shape()[0] << "x" << layer.weights.shape()[1] << std::endl;

nn::Conv2D

2D convolutional layer for neural networks.

Constructor

Conv2D(int in_channels, int out_channels, int kernel_size, int stride = 1, int padding = 0)

Parameters: - in_channels: Number of input channels - out_channels: Number of output channels - kernel_size: Size of the convolutional kernel - stride: Stride of the convolution (default: 1) - padding: Padding size (default: 0)

Members

• weights: Tensor containing the convolutional kernels
• bias: Tensor containing the bias terms (if enabled)

Methods

• forward(const Tensor& input) - Performs forward pass
• get_parameters() - Returns vector of trainable parameters

Usage Example

#include "layers.h"

// Create convolutional layer
nn::Conv2D conv(3, 16, 3, 1, 1);  // 3 input channels, 16 output channels, 3x3 kernel

// Forward pass
ag::Tensor input(ag::Matrix::Random(1, 3, 32, 32), false);  // Batch, channels, height, width
ag::Tensor output = conv.forward(input);

std::cout << "Output shape: " << output.shape()[0] << "x" << output.shape()[1] 
          << "x" << output.shape()[2] << "x" << output.shape()[3] << std::endl;

nn::LayerNorm

Layer normalization for stabilizing training. Normalizes over entire input with no learnable parameters.

Constructor

LayerNorm(float eps = 1e-5f)

Parameters: - eps: Small value to prevent division by zero (default: 1e-5)

Methods

• forward(const Tensor& input) - Performs forward pass
• has_parameters() - Returns false (no learnable parameters)

Activation Functions

ReLU

ag::Tensor relu(const Tensor& input)

LeakyReLU

ag::Tensor leaky_relu(const Tensor& input, Float negative_slope = 0.01)

Tanh

ag::Tensor tanh(const Tensor& input)

Softmax

ag::Tensor softmax(const Tensor& input)

Applies softmax over all elements of the input tensor.

Softplus

ag::Tensor softplus(const Tensor& input)

nn::Sequential

Container for composing multiple layers into a sequential model.

Constructor

Sequential()

Methods

• add(std::shared_ptr<Layer> layer) - Add a layer to the sequence
• add(Layer&& layer) - Add a layer by value (auto-wrapped)
• forward(const Tensor& input) - Forward pass through all layers
• zero_grad() - Zero gradients for all layers
• layers() - Returns vector of all layers
• size() / empty() / clear() - Container utilities

Usage Example

#include "layers.h"

// Create sequential model
nn::Sequential model;
model.add(nn::Linear(784, 128));
model.add(nn::ReLU());
model.add(nn::Linear(128, 10));

// Forward pass
ag::Tensor input(ag::Matrix::Random(32, 784), false);
ag::Tensor output = model.forward(input);

// Get all parameters for optimizer
auto layers = model.layers();

Optimizers

ag::SGD

Stochastic Gradient Descent optimizer.

Constructor

ag::SGD(Float learning_rate)

Parameters: - learning_rate: Learning rate for parameter updates (must be positive)

Methods

• add_parameters(const std::vector<std::shared_ptr<Layer>>& layers) - Add parameters from layers
• zero_grad() - Zero out all gradients
• step() - Update parameters using gradients

Usage Example

#include "optimizer.h"

// Create optimizer
ag::SGD optimizer(0.01f);

// Add parameters
optimizer.add_parameters(model.layers());

// Training loop
for (int epoch = 0; epoch < num_epochs; ++epoch) {
    optimizer.zero_grad();
    auto output = model.forward(input);
    auto loss = compute_loss(output, target);
    loss.backward();
    optimizer.step();
}

ag::RMSProp

RMSProp optimizer with adaptive learning rates. Includes ESP32-S3 SIMD optimizations.

Constructor

ag::RMSProp(Float lr = 0.01f, Float alpha = 0.99f, Float eps = 1e-8f)

Parameters: - lr: Learning rate (must be positive) - alpha: Decay rate for moving average (must be in (0, 1)) - eps: Small constant for numerical stability

Methods

• add_parameters(const std::vector<std::shared_ptr<Layer>>& layers) - Add parameters from layers
• zero_grad() - Zero out all gradients
• step() - Update parameters using adaptive learning rates

Usage Example

#include "optimizer.h"

// Create optimizer
ag::RMSProp optimizer(0.001f, 0.99f, 1e-8f);
optimizer.add_parameters(model.layers());

// Training loop (same pattern as SGD)
for (int epoch = 0; epoch < num_epochs; ++epoch) {
    optimizer.zero_grad();
    auto loss = compute_loss(model.forward(input), target);
    loss.backward();
    optimizer.step();
}

ObGD

Overshooting-bounded Gradient Descent optimizer for online learning (Stream-X module).

Constructor

ObGD(Float learning_rate, Float gamma, Float lambda, Float kappa)

Parameters: - learning_rate: Learning rate - gamma: Discount factor for TD learning - lambda: Eligibility trace decay parameter - kappa: Overshooting bound parameter

Methods

• add_parameters(const std::vector<std::shared_ptr<nn::Layer>>& layers) - Add parameters from layers
• step(Float delta, bool reset = false) - Online parameter update with TD error
• zero_grad() - Zero out all gradients

Utility Functions

Math Operations

Element-wise Operations

ag::Tensor relu(const Tensor& input)
ag::Tensor leaky_relu(const Tensor& input, double negative_slope = 0.01)
ag::Tensor tanh(const Tensor& input)
ag::Tensor softmax(const Tensor& input)
ag::Tensor softplus(const Tensor& input)
ag::Tensor exp(const Tensor& input)
ag::Tensor log(const Tensor& input)
ag::Tensor sqrt(const Tensor& input)
ag::Tensor pow(const Tensor& input, double exponent)

Reduction Operations

ag::Tensor sum(const Tensor& input)
ag::Tensor mean(const Tensor& input)

Matrix Operations

ag::Tensor matmul(const Tensor& a, const Tensor& b)
ag::Tensor transpose(const Tensor& input)

Graph Visualization

Computational Graph

void draw_graph(const Tensor& tensor, const std::string& filename)

Parameters: - tensor: Root tensor of the computational graph - filename: Output filename for the graph visualization

Usage:

// Create computation
auto x = ag::Tensor(ag::Matrix::Random(2, 3), true, "x");
auto y = ag::Tensor(ag::Matrix::Random(3, 2), true, "y");
auto z = x.matmul(y);
auto loss = ag::sum(z);

// Visualize graph
ag::draw_graph(loss, "computation_graph.dot");

// Convert to image (requires Graphviz)
// dot -Tpng computation_graph.dot -o graph.png

Random Number Generation

Seed Management

void manual_seed(unsigned int seed)

Parameters: - seed: Random seed for reproducible results

Usage Example

#include "rng.h"

// Set random seed for reproducibility
ag::manual_seed(42);

// Create random tensors
auto tensor1 = ag::Tensor(ag::Matrix::Random(3, 4), true);
auto tensor2 = ag::Tensor(ag::Matrix::Random(4, 2), true);

---

For more detailed examples and usage patterns, see the Examples Guide.