lowmind 2.2.0

lm.Tensor — N-dimensional array with automatic gradient tracking.

# ── Creating ────────────────────────────────────────────────
t = lm.Tensor([1., 2., 3.])                      # from list
t = lm.Tensor(np.array([[1, 2],[3, 4]]))          # from numpy
t = lm.Tensor(5.0, requires_grad=True)            # scalar with grad
lm.zeros(3, 4);  lm.ones(2, 2)                   # factory
lm.randn(10,10); lm.rand(5, 5)                   # random
lm.arange(0, 10, 2)   # → [0, 2, 4, 6, 8]

# ── Arithmetic ──────────────────────────────────────────────
c = a + b;  c = a - b;  c = a * b                # element-wise
c = a / b;  c = a ** 2; c = a @ b                # divide, power, matmul

# ── Reductions ──────────────────────────────────────────────
x.sum(axis=0);  x.mean(axis=(2, 3));  x.max(axis=1)

# ── Activations ─────────────────────────────────────────────
x.relu();  x.sigmoid();  x.tanh();  x.gelu()
x.softmax(axis=-1);  x.clip(-1, 1);  x.leaky_relu(0.01)

# ── Shape Ops ───────────────────────────────────────────────
x.reshape(6, 4);  x.flatten(start_dim=1)
x.transpose((0,2,1));  x.squeeze(1);  x.unsqueeze(0)

# ── Autograd Example ────────────────────────────────────────
x = lm.Tensor(3.0, requires_grad=True)
y = x**2 + 2*x + 1
y.backward()
print(x.grad)   # → 8.0  ✓  (dy/dx = 2x+2)

# Gradient clipping
lm.clip_grad_norm(model.parameters(), max_norm=1.0)

# ── Utilities ───────────────────────────────────────────────
t.item();  t.numpy();  t.detach();  t.copy()
t.shape;   t.ndim;    t.size;     t.zero_grad()

# Linear
lm.Linear(784, 256, bias=True)                   # (N,784)→(N,256)

# Convolution
lm.Conv2d(3, 32, kernel_size=3, stride=1, padding=1)   # (N,3,H,W)→(N,32,H,W)

# Normalization
lm.BatchNorm1d(256)    # for (N, features)
lm.BatchNorm2d(32)     # for (N, C, H, W)

# Pooling
lm.MaxPool2d(2, 2)     # halves spatial dims
lm.AvgPool2d(2)

# Utility
lm.Flatten(start_dim=1)
lm.Dropout(p=0.5)      # auto-disabled at model.eval()
lm.Embedding(10000, 128)

# ── Custom Module ───────────────────────────────────────────
class ResBlock(lm.Module):
    def __init__(self, d):
        super().__init__()
        self.fc1 = lm.Linear(d, d)
        self.bn  = lm.BatchNorm1d(d)
        self.fc2 = lm.Linear(d, d)

    def forward(self, x):
        return (self.bn(self.fc2(self.fc1(x).relu())) + x).relu()

# ── Sequential ──────────────────────────────────────────────
model = lm.Sequential(
    lm.Linear(784, 256), lm.ReLU(), lm.BatchNorm1d(256),
    lm.Dropout(0.3),     lm.Linear(256, 10),
)
model.num_parameters()    # count params
model.summary()           # architecture table

lm.cross_entropy_loss(logits, targets)             # classification
lm.cross_entropy_loss(logits, targets, reduction='sum')
lm.binary_cross_entropy_loss(probs, targets)       # binary
lm.binary_cross_entropy_loss(logits, targets, from_logits=True)
lm.mse_loss(preds, targets)                        # regression
lm.mae_loss(preds, targets)                        # outlier-robust
lm.huber_loss(preds, targets, delta=1.0)           # smooth L1
lm.nll_loss(log_probs, targets)                    # after log-softmax

# All share the same interface:
optimizer.zero_grad()  →  loss.backward()  →  optimizer.step()

lm.SGD(model.parameters(), lr=0.01, momentum=0.9,
       weight_decay=1e-4, nesterov=True)

lm.Adam(model.parameters(), lr=1e-3, betas=(0.9,0.999),
        eps=1e-8, amsgrad=False)

lm.AdamW(model.parameters(), lr=1e-3, weight_decay=0.01)   # ← preferred

lm.RMSprop(model.parameters(), lr=1e-3, alpha=0.99, momentum=0.0)

lm.AdaGrad(model.parameters(), lr=0.01)

Convergence (lower is better, epoch 10):

SGD       ████████████████████░░░░░░░  0.42
AdaGrad   ████████████████░░░░░░░░░░░  0.28
RMSprop   █████████████░░░░░░░░░░░░░░  0.31
Adam      ████████░░░░░░░░░░░░░░░░░░░  0.18 ⭐
AdamW     ███████░░░░░░░░░░░░░░░░░░░░  0.16 ⭐⭐

lm.StepLR(optimizer, step_size=10, gamma=0.5)
lm.MultiStepLR(optimizer, milestones=[30,60,90], gamma=0.1)
lm.ExponentialLR(optimizer, gamma=0.95)
lm.CosineAnnealingLR(optimizer, T_max=50, eta_min=1e-6)
lm.ReduceLROnPlateau(optimizer, mode='min', patience=5, factor=0.5)
lm.LinearWarmupLR(optimizer, warmup_steps=1000, target_lr=1e-3)
lm.CyclicLR(optimizer, base_lr=1e-4, max_lr=1e-1,
            step_size=2000, mode='triangular')   # step per batch!

# Datasets
ds = lm.TensorDataset(X_train, y_train)

class MyDataset(lm.Dataset):
    def __init__(self, X, y): self.X, self.y = X, y
    def __len__(self):         return len(self.X)
    def __getitem__(self, i):  return self.X[i], self.y[i]

# DataLoader
loader = lm.DataLoader(ds, batch_size=64, shuffle=True, drop_last=False)
for X_batch, y_batch in loader: ...

# Split
X_tr, X_val, y_tr, y_val = lm.train_test_split(
    X, y, test_size=0.2, shuffle=True, seed=42)

# Classification
lm.accuracy(preds, targets)                              # 0-1 float
lm.top_k_accuracy(logits, targets, k=5)
lm.precision(logits, targets, num_classes=10)            # macro
lm.recall(logits, targets,   num_classes=10)
lm.f1_score(logits, targets, num_classes=10)
lm.f1_score(logits, targets, num_classes=10, average='none')  # per-class
lm.confusion_matrix(logits, targets)                     # (C,C) array

# Regression
lm.r2_score(preds, targets)
lm.mean_squared_error(preds, targets)
lm.mean_absolute_error(preds, targets)

# Tabular / flat data
lm.MicroMLP(input_size=784, hidden_sizes=[256,128], output_size=10, dropout=0.3)

# Small images  (N, 3, 32, 32) → (N, 10)
lm.MicroCNN(in_channels=3, num_classes=10, input_size=32, dropout=0.2)

# Residual connections — more capacity
lm.TinyResNet(in_channels=3, num_classes=10, input_size=32, base_filters=16)

# ── Model I/O ───────────────────────────────────────────────
model.save('/path/model.lmz')             # compressed gzip
model.save('/path/model.lm', compress=False)
model.load('/path/model.lmz')
sd = model.state_dict()
model.load_state_dict(sd, strict=False)

lm.configure_memory(max_mb=128)          # set budget

monitor = lm.SystemMonitor()
monitor.print_status()                   # CPU%, RAM, temp
score   = monitor.health_score()         # 0–100
stats   = monitor.get_stats()

with lm.memory_trace("Forward Pass"):
    out = model(X)

lm.memory_manager.optimize_for_inference()
lm.memory_manager.get_memory_info()
# {'allocated_mb': 12.3, 'max_mb': 128.0, 'usage_percent': 9.6}

Export your trained LowMind Sequential models directly into standard, highly-efficient, standalone C++ header files ready to compile and run on microcontrollers (Arduino, ESP32, STM32) without Python!

import lowmind as lm

# 1. Define input shape (C, H, W) or flat features
input_shape = (1, 8, 8)

# 2. Export model weights, biases, and layers to a self-contained header file
lm.export_to_cpp(model, input_shape, "embedded_model.h", namespace="my_embedded_model")

Key Advantages:

• Ping-Pong Static Buffer Architecture: Avoids dynamic memory allocation (malloc/new) completely. Keeps memory consumption perfectly predictable and constant on small microcontrollers.
• Pure Self-Contained C++: Generated with standard <cmath> and arrays. Zero external dependencies required.
• Extensive Layer Support: Supports Linear, Conv2d, BatchNorm1d/BatchNorm2d, MaxPool2d, AvgPool2d, Flatten, ReLU, LeakyReLU, Sigmoid, Tanh, and Softmax layers.

Magnitude-based weight pruning API to zero out low-magnitude weights and calculate overall model sparsity.

import lowmind as lm

# Create a pruner for your model
pruner = lm.Pruner(model)

# Prune the entire model (skip biases by default) to a target sparsity ratio (0.0 to 1.0)
pruner.prune_model(sparsity_ratio=0.5)

# Prune specific weight parameters of a layer
pruner.prune_module_weight("fc.weight", sparsity_ratio=0.5)

# Re-apply pruning masks (vital to call after optimizer.step() during training)
optimizer.step()
pruner.apply_masks()

# Calculate current sparsity percentage of the model
sparsity_pct = pruner.calculate_sparsity()
print(f"Model Sparsity: {sparsity_pct:.2f}%")

Post-Training Integer (INT8) Quantization helper to convert float32 weights to simulated 8-bit integer weights.

import lowmind as lm

# In-place quantization of model weights to simulate 8-bit integers
model.quantize()

# Alternatively, extract integer weights and scale factor of a specific tensor
q_data, scale = lm.quantize_weight(model[0].weight)

# Wrap quantized data in a container
quantized_tensor = lm.QuantizedTensor(q_data, scale)

# Convert back to float32 representation
float_data = quantized_tensor.dequantize()

Simulate the effects of 8-bit integer quantization during training using Straight-Through Estimators (STE). This allows the model's weights to adapt and learn quantization robust features, resulting in almost 0% accuracy drop when finally quantized to INT8!

import lowmind as lm

# 1. Enable QAT (Straight-Through Estimators) on all layers of a model
lm.prepare_qat(model, enabled=True)

# 2. Train the model normally using any trainer or custom loop
# Standard SGD, Adam, and backpropagation are fully supported
trainer.fit(loader, epochs=5)

# 3. Toggle QAT off after training
lm.prepare_qat(model, enabled=False)

# 4. Perform final INT8 quantization
model.quantize()

Knowledge Distillation Trainer to transfer knowledge from a heavy, pre-trained Teacher model to a lightweight Student model.

import lowmind as lm

# Setup DistillationTrainer (combines hard label loss and soft temperature-scaled loss)
trainer = lm.DistillationTrainer(
    student_model=student_model,
    teacher_model=teacher_model,
    optimizer=optimizer,
    loss_fn=lm.cross_entropy_loss,
    temperature=3.0,  # Soft target scaling temperature (default 3.0)
    alpha=0.5,        # Coefficient weight for soft loss vs hard loss (default 0.5)
    clip_grad=1.0,
    grad_accum_steps=1,
    verbose=1
)

# Train the student model
history = trainer.fit(train_loader, val_loader, epochs=10)

Simulate large batch sizes on low-memory edge devices by accumulating gradients over multiple steps before performing an optimizer update.

import lowmind as lm

# Pass grad_accum_steps parameter to Trainer
trainer = lm.Trainer(
    model=model,
    optimizer=optimizer,
    loss_fn=lm.cross_entropy_loss,
    grad_accum_steps=4  # Accumulate over 4 steps (effectively 4x batch size)
)

Trade compute for massive memory savings on edge devices. Only save activations at checkpoints and recompute the rest during the backward pass on-the-fly.

import lowmind as lm

# Wrap Sequential block or any sub-module function in checkpoint
out = lm.checkpoint(model_block, input_tensor)

Check if hardware acceleration is active. Incorporates blazingly fast memory stride tricks and optional Numba Just-In-Time (JIT) compiler fallback to accelerate k-D convolutions at assembly-level speed (10x - 50x speedup!).

import lowmind as lm

# Check if hardware JIT/stride acceleration is active on this system
print("JIT Accelerated:", lm.is_jit_accelerated())

Exports a LowMind model to standard ONNX format for cross-platform deployment on PyTorch, TensorFlow, ONNX Runtime, TensorRT, or Android/iOS accelerators.

import lowmind as lm
import numpy as np

# Define dummy input
dummy_input = np.random.randn(1, 3, 32, 32).astype(np.float32)

# Export and verify to standard .onnx file
onnx_model = lm.export_to_onnx(model, dummy_input, "model.onnx")