KortexDL Python Bindings

High-Performance Neural Network Framework for Python
Powered by C++20, Intel oneAPI MKL, and pybind11

---

🚀 Features

• ⚡ Zero-Copy NumPy Integration: Direct memory access for maximum performance
• 🧠 CNN Layers: Conv2d, MaxPool2d, BatchNorm2d with full backpropagation
• 🎯 Dense Networks: Fully connected layers with 8 activation functions
• 📊 Multiple Loss Functions: MSE, MAE, Binary/Categorical Cross-Entropy, and more
• 🧪 Comprehensive Test Suite: 42 passing tests covering all functionality
• 🔧 Easy Installation: Simple pip install -e . setup

---

📦 Installation

Prerequisites

• Python 3.8+
• Intel oneAPI Toolkit 2025.2+ (includes MKL)
• NumPy

Quick Install

# Clone repository
git clone https://github.com/Mostafasaad1/bison_framework_DL.git
cd bison_framework_DL/kortexdl-python

# Source Intel oneAPI environment
source ~/intel/oneapi/setvars.sh

# Install in editable mode (builds C++ extension automatically)
pip install -e .

Verify Installation

import kortexdl as bd

print(f"KortexDL version: {bd.__version__}")
print(f"Bindings available: {bd.BINDINGS_AVAILABLE}")

# Test basic functionality
net = bd.Network([10, 20, 10], bd.ActivationType.ReLU)
print("✅ KortexDL installed successfully!")

---

🔥 Quick Start

Simple Dense Network

import kortexdl as bd
import numpy as np

# Create network: 784 → 128 → 10
net = bd.Network([784, 128, 10], bd.ActivationType.ReLU)

# Prepare data
X_train = np.random.randn(100, 784).astype(np.float32)
y_train = np.random.randint(0, 10, (100, 10)).astype(np.float32)

# Train
for epoch in range(10):
    loss = net.train_batch(X_train, y_train, bd.LossType.MSE, 
                           lr=0.01, batch_size=32)
    print(f"Epoch {epoch}, Loss: {loss:.4f}")

# Predict
predictions = net.forward(X_train[0], batch_size=1, training=False)

Convolutional Neural Network

import kortexdl as bd
import numpy as np

# Create CNN layers
conv1 = bd.Conv2d(in_channels=3, out_channels=16, kernel_size=3, 
                  stride=1, padding=1)
bn1 = bd.BatchNorm2d(num_features=16)
pool1 = bd.MaxPool2d(kernel_size=2, stride=2)

# Forward pass (NCHW format)
x = np.random.randn(4, 3, 32, 32).astype(np.float32)  # Batch of 4 images

x = conv1.forward(x)      # → (4, 16, 32, 32)
x = bn1.forward(x)        # → (4, 16, 32, 32)
x = pool1.forward(x)      # → (4, 16, 16, 16)

print(f"Final shape: {x.shape}")

See examples/ for complete examples.

---

📚 API Reference

Core Components

Network

Fully connected neural network.

net = bd.Network(
    layer_sizes=[784, 128, 64, 10],
    activation=bd.ActivationType.ReLU
)

# Training
loss = net.train_batch(X, y, bd.LossType.MSE, lr=0.01, batch_size=32)

# Inference
output = net.forward(input_data, batch_size=1, training=False)

# Access layers
layers = net.getLayersMutable()
weights = layers[0].get_weights()

Layer

Note: Layer class is exposed but typically used internally by Network.

layer = bd.Layer(input_size=10, output_size=5, 
                 activation=bd.ActivationType.Tanh)
layer.initialize_weights()

output = layer.forward(input_data, batch_size)
layer.backward(input_data, grad_output, learning_rate=0.0, batch_size)

# Access gradients
grad_w = layer.get_grad_weights()
grad_b = layer.get_grad_biases()

---

CNN Layers

Conv2d

2D Convolution layer.

conv = bd.Conv2d(
    in_channels=3,
    out_channels=64,
    kernel_size=3,
    stride=1,
    padding=1
)

output = conv.forward(input)  # Input: (N, C_in, H, W)
grad = conv.backward(grad_output)

MaxPool2d

Max pooling layer.

pool = bd.MaxPool2d(kernel_size=2, stride=2)
output = pool.forward(input)
grad = pool.backward(grad_output)

BatchNorm2d

Batch normalization for 2D data.

bn = bd.BatchNorm2d(num_features=64)
output = bn.forward(input)  # Normalizes per channel
grad = bn.backward(grad_output)

---

Enums

ActivationType

Available: Linear, ReLU, LeakyReLU, ELU, Sigmoid, Tanh, Swish, Softmax

bd.ActivationType.ReLU
bd.ActivationType.Sigmoid
bd.ActivationType.Tanh
# ... see enums_bindings.cpp for complete list

LossType

Available: MSE, MAE, BINARY_CE, CATEGORICAL_CE, HUBER, HINGE, SQUARED_HINGE, KL_DIVERGENCE, POISSON, LOG_COSH

bd.LossType.MSE
bd.LossType.CATEGORICAL_CE
bd.LossType.BINARY_CE

OptimizerType

Creation only - SGD, Adam, AdamW, Momentum, Nesterov, RMSprop, Adagrad, Adadelta, Adamax, Nadam, Ftrl, Lion

opt = bd.create_optimizer(bd.OptimizerType.Adam, learning_rate=0.001)
# Note: Optimizer.update() is NOT bound to Python (see Known Limitations)

---

🧪 Testing

Run the comprehensive test suite:

cd kortexdl-python
python -m pytest tests/ -v

Test Coverage (as of v2.0):

• ✅ 42 tests passed
• ⏭️ 7 tests skipped (unbound CNN layers)
• ⚠️ 2 tests xfailed (documented optimizer limitations)

See TESTING.md for details.

---

⚠️ Known Limitations

Missing Optimizer Bindings

The C++ Optimizer classes are implemented but not fully accessible from Python:

• Optimizer.update() method is not bound
• Network.train_batch_with_optimizer() is not bound

Current Workaround: Use Network.train_batch() which uses internal SGD.

Status: Documented in tests/test_optimizers.py as xfail tests.

Limited Activation Functions

Only 8 activation types are currently exposed (not the full 15 implemented in C++):

• Bound: Linear, ReLU, LeakyReLU, ELU, Sigmoid, Tanh, Swish, Softmax
• Not Bound: GELU, SELU, Mish, Softplus, Softsign, HardSigmoid, HardTanh

See src/bindings/enums_bindings.cpp for the authoritative list.

Unbound CNN Layers

Some CNN layers exist in C++ but are not yet bound:

• DepthwiseConv2d
• ConvTranspose2d
• Upsample

---

🛠️ Development

Running Tests

# All tests
python -m pytest tests/ -v

# Specific test file
python -m pytest tests/test_core.py -v

# With coverage (may crash on cleanup - use -p no:cov to disable)
python -m pytest tests/ -v -p no:cov

Building from Source

# Clean build
rm -rf build *.egg-info
pip install -e .

# Rebuild C++ only
cd build && cmake --build . --target _kortexdl_core -j$(nproc)

---

📊 Performance Tips

1. Use dtype=np.float32: All arrays must be float32
2. Contiguous arrays: Ensure np.ascontiguousarray() for best performance
3. Batch processing: Larger batches = better MKL utilization
4. MKL threads: export MKL_NUM_THREADS=$(nproc)
5. Source oneAPI: Always run source ~/intel/oneapi/setvars.sh before using

---

🔗 Links

• C++ Core: ../kortexdl-cpp
• Examples: examples/
• Tests: tests/
• Core Audit Report: ../docs/core_audit_report.md

---

📄 License

MIT License - see LICENSE file.

---

Built with ❤️ by Mostafa Saad
Powered by Intel oneAPI MKL and pybind11

GitHub • Documentation • Report Issue