🚀 T-Tensor

Mini-framework de Deep Learning con CUDA/C++ y Bindings de Python.
Rápido. Directo. Ligero. Sin dependencias gigantes.

🌐 Visita el Sitio Oficial | 📖 Documentación | ⚡ Inicio Rápido

---

✨ Características Principales

🚀 Rendimiento	🧠 IA & Autograd	🐍 Integración
CUDA Kernels: Operaciones aceleradas por GPU para un entrenamiento veloz.	Motor Autograd: Sistema de diferenciación automática construido desde cero.	Python Bindings: Usa el poder de C++ con la simplicidad de Python.
Arquitectura Modular: Separación clara entre el core (C++) y la interfaz.	Optimizadores: Soporte para SGD, Adam y funciones de activación personalizadas.	Zero-Bloat: Sin dependencias pesadas, ideal para sistemas con recursos limitados.

🛠️ Tech Stack & Requisitos

• Lenguajes: C++17 y Python 3.12.
• Build System: CMake + PyBind11.
• OS: Windows 10/11 (Próximamente soporte nativo para Linux).

---

📋 Contenido

1. Vision general
2. Instalacion
3. Importacion y organizacion
4. Modulo device
5. Modulo tensor
6. Modulo nn
7. Modulo optim
8. Modulo loss
9. Modulo data
10. Guia de entrenamiento
11. Ejemplos listos para copiar
12. Buenas practicas y errores comunes

---

1. Vision general

T-Tensor incluye todo lo que necesitas para entrenar redes neuronales desde cero:

Modulo	Que hace
🧮 Tensor + Autograd	Tensores en CPU/GPU con backward() automatico
🔁 Operaciones	matmul, add, relu, softmax, log, sum, reshape...
🧱 Capas nn	Linear, ReLU, Sigmoid, Softmax, Sequential
🚀 Optimizadores	SGD, Adam
📉 Perdidas	MSELoss, CrossEntropyLoss
📂 Data pipeline	CSVDataset, DataLoader con shuffle
🖥️ GPU Manager	Seleccion y reporte de hardware CUDA automatico

---

2. Instalacion

✅ Compatibilidad probada

Estas combinaciones han sido verificadas en el proyecto:

Componente	Versiones probadas
OS	Windows 10/11
Python	3.12.x
CUDA Toolkit	12.8
Visual Studio	18 2026 (x64)
CMake	3.18+

🧰 Entorno de desarrollo (contributors)

Para contribuir y ejecutar tests/lint localmente:

python -m pip install --upgrade pip
python -m pip install -r requirements-dev.txt

🔧 Desde el repositorio (compilacion desde fuente)

git clone https://github.com/Gilberto-Galan/Mini-Framework-Deep-Learning-T-Tensor.git
cd Mini-Framework-Deep-Learning-T-Tensor
pip install .

🧪 Desde TestPyPI (version de prueba)

python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple ttensor==0.1.0

✅ Verificacion:

python -c "import ttensor; print('OK')"

🛠️ Compilacion manual con Visual Studio 18 2026 (Windows)

Si prefieres validar el framework compilando manualmente con CMake:

$PYBIND11_DIR = python -c "import pathlib, pybind11; print((pathlib.Path(pybind11.__file__).resolve().parent / 'share' / 'cmake' / 'pybind11').as_posix())"
cmake -S . -B build -G "Visual Studio 18 2026" -A x64 -DCMAKE_CUDA_FLAGS="--allow-unsupported-compiler" -Dpybind11_DIR="$PYBIND11_DIR"
cmake --build build --config Release

Smoke test recomendado:

python -c "import ttensor; print('OK')"
python examples/xor_cpu.py
python -m pytest -q tests

---

3. Importacion y organizacion

¿Ya usas PyTorch? Te vas a sentir como en casa. Todo viene de ttensor:

import ttensor
from ttensor import (
	Device, Tensor, DeviceManager,
	Module, Linear, ReLU, Sigmoid, Softmax, Sequential,
	Optimizer, SGD, Adam,
	MSELoss, CrossEntropyLoss,
	Dataset, CSVDataset, DataLoader,
)

Importaciones principales y su utilidad:

Importacion	Para que sirve
from ttensor import Tensor	Estructura base para crear tensores en CPU/GPU, aplicar operaciones y usar autograd con backward().
from ttensor import Linear, ReLU, Sigmoid, Softmax, Sequential	Construccion de modelos neuronales: capas densas, activaciones y composicion de red en secuencia.
from ttensor import SGD, Adam	Optimizadores para actualizar parametros del modelo con los gradientes calculados.
from ttensor import CSVDataset, DataLoader	Carga de datos desde CSV y entrega de mini-batches con opcion de shuffle por epoca.

---

4. Modulo device — Gestion de GPU/CPU 🖥️

Enum Device

• Device.CPU
• Device.GPU

Clase DeviceManager

Metodos principales:

• initialize(preferred_device_id=0)
• set_device(device_id)
• device_count()
• active_device_id()
• available_devices()
• get_info()
• update_memory_info()
• has_enough_vram(required_bytes)
• set_prefer_managed_memory(enabled)
• should_use_managed_memory()
• print_report()

Ejemplo:

from ttensor import DeviceManager

DeviceManager.initialize()
DeviceManager.print_report()

info = DeviceManager.get_info()
print("GPU:", info.name)
print("VRAM total:", info.total_memory)
print("VRAM libre:", info.free_memory)

---

5. Modulo tensor — El corazon del framework 🧮

Crear tensores

from ttensor import Tensor, Device

x = Tensor(4, 3, Device.GPU, True)  # rows, cols, device, requires_grad
x.fill_random(-0.1, 0.1)

y = Tensor.from_list([
	1.0, 2.0, 3.0,
	4.0, 5.0, 6.0,
], rows=2, cols=3, device=Device.CPU, requires_grad=False)

Utilidades

• fill(value)
• fill_random(low, high)
• set_data(values)
• tolist()
• item() para tensores 1x1
• print(limit=10)
• to_gpu() / to_cpu()
• shape
• requires_grad
• grad

Operaciones diferenciables

Estilo funcional:

z = Tensor.matmul(a, b)
z = Tensor.add(a, b)
z = Tensor.sub(a, b)
z = Tensor.mul(a, b)

z = Tensor.relu(x)
z = Tensor.sigmoid(x)
z = Tensor.softmax(x)
z = Tensor.log(x)
z = Tensor.exp(x)

s_all = Tensor.sum(x, axis=-1)   # escalar
s0 = Tensor.sum(x, axis=0)       # (1, cols)
s1 = Tensor.sum(x, axis=1)       # (rows, 1)

m_all = Tensor.mean(x, axis=-1)

r = Tensor.reshape(x, new_rows=2, new_cols=6)

Tambien con operadores:

z = a + b
z = a - b
z = a * b          # elemento a elemento
z = a @ b          # matmul

Backpropagation

loss.backward()        # si loss es escalar

# Si el tensor no es escalar, pasa gradiente explicito:
# output.backward(grad_output)

Reiniciar gradientes:

param.zero_grad()

---

6. Modulo nn — Construye tu red neuronal 🧱

Module

Base para capas y modelos. API:

• forward(input)
• __call__(input) (alias de forward)
• parameters()
• zero_grad()
• save(path)
• load(path)

Linear(in_features, out_features, device=Device.GPU)

Hace X @ W + b.

Activaciones

• ReLU()
• Sigmoid()
• Softmax()

Sequential([...])

Encadena capas.

Ejemplo:

from ttensor import Sequential, Linear, ReLU, Sigmoid

model = Sequential([
	Linear(2, 16),
	ReLU(),
	Linear(16, 1),
	Sigmoid(),
])

pred = model(x)

---

7. Modulo optim — Entrena rapido con SGD y Adam 🚀

SGD(params, lr)

opt = SGD(model.parameters(), lr=0.01)

Adam(params, lr, beta1=0.9, beta2=0.999, eps=1e-8)

opt = Adam(model.parameters(), lr=0.001)

Metodos comunes:

• step()
• zero_grad()

---

8. Modulo loss — Mide cuanto falla tu modelo 📉

MSELoss

Ideal para regresion.

criterion = MSELoss()
loss = criterion.forward(pred, target)

CrossEntropyLoss

Ideal para clasificacion multiclase con targets one-hot.

criterion = CrossEntropyLoss()
loss = criterion.forward(logits_or_probs, target_one_hot)

---

9. Modulo data — Carga datasets sin esfuerzo 📂

CSVDataset(path, label_cols, device=Device.GPU)

• path: archivo CSV
• label_cols: cuantas columnas finales son etiqueta(s)

DataLoader(dataset, batch_size, shuffle=True)

Metodos:

• reset()
• has_next()
• next_batch() -> retorna (X_batch, y_batch)

Ejemplo:

from ttensor import CSVDataset, DataLoader, Device

dataset = CSVDataset("data/train.csv", label_cols=1, device=Device.GPU)
loader = DataLoader(dataset, batch_size=32, shuffle=True)

loader.reset()
while loader.has_next():
	xb, yb = loader.next_batch()
	# entrenar

---

10. Guia de entrenamiento — Del dato al modelo entrenado 🎯

Esta es la plantilla que usaras en practicamente cualquier proyecto:

# 1) Definir datos
# 2) Definir modelo
# 3) Definir loss y optimizador
# 4) Loop: forward -> loss -> zero_grad -> backward -> step

for epoch in range(num_epochs):
	pred = model(x)
	loss = criterion.forward(pred, y)

	optimizer.zero_grad()
	loss.backward()
	optimizer.step()

---

11. Ejemplos listos para copiar ✂️

🔀 11.1 XOR — El clasico de las redes neuronales

from ttensor import Tensor, Device, Sequential, Linear, ReLU, Sigmoid, Adam, MSELoss

X = Tensor.from_list([
	0, 0,
	0, 1,
	1, 0,
	1, 1,
], rows=4, cols=2, device=Device.GPU, requires_grad=False)

y = Tensor.from_list([
	0,
	1,
	1,
	0,
], rows=4, cols=1, device=Device.GPU, requires_grad=False)

model = Sequential([
	Linear(2, 8),
	ReLU(),
	Linear(8, 1),
	Sigmoid(),
])

criterion = MSELoss()
optimizer = Adam(model.parameters(), lr=0.05)

for epoch in range(2000):
	pred = model(X)
	loss = criterion.forward(pred, y)

	optimizer.zero_grad()
	loss.backward()
	optimizer.step()

	if epoch % 200 == 0:
		print(f"epoch={epoch} loss={loss.item():.6f}")

print("pred:", model(X).tolist())

🎯 11.2 Clasificacion multiclase (Softmax + CrossEntropy)

from ttensor import Sequential, Linear, ReLU, Softmax, CrossEntropyLoss, Adam

# x: (batch, features)
# y: (batch, num_classes) one-hot

model = Sequential([
	Linear(4, 32),
	ReLU(),
	Linear(32, 3),
	Softmax(),
])

criterion = CrossEntropyLoss()
optimizer = Adam(model.parameters(), lr=0.001)

pred = model(x)
loss = criterion.forward(pred, y)
optimizer.zero_grad()
loss.backward()
optimizer.step()

---

12. Buenas practicas y errores comunes 💡

✅ Buenas practicas

• Usa DeviceManager.initialize() al inicio para verificar hardware.
• Mantiene X, y y el modelo en el mismo Device.
• Llama optimizer.zero_grad() antes de backward() en cada iteracion.
• En clasificacion multiclase, usa targets one-hot para CrossEntropyLoss.
• Verifica formas (shape) con frecuencia.

⚠️ Errores comunes

• Mezclar tensores CPU y GPU en una operacion.
• Usar item() en tensores que no son 1x1.
• Llamar backward() sin gradiente de salida para tensores no escalares.
• Dimensiones incompatibles en matmul:
  • Si a es (m, n), b debe ser (n, k).

---

🏁 Estado del framework

T-Tensor ya cubre el flujo completo para MLPs — listo para usar:

• ✅ Tensores + autograd con grafo dinamico
• ✅ Modulos y modelos (Sequential, Linear, activaciones)
• ✅ Optimizadores (SGD, Adam)
• ✅ Funciones de perdida (MSELoss, CrossEntropyLoss)
• ✅ Data pipeline con mini-batches y shuffle
• ✅ Ejecucion CUDA con seleccion automatica de GPU

---

Construido con C++, CUDA y pybind11 — por Gilberto Galan Si te resulta util, dale una ⭐ en GitHub!