High-Performance Neural Network Framework for Python
Powered by C++20, Intel oneAPI MKL, and pybind11
- ⚡ 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
- Python 3.8+
- Intel oneAPI Toolkit 2025.2+ (includes MKL)
- NumPy
# Clone repository
git clone https://github.com/Mostafasaad1/bison_framework_DL.git
cd bison_framework_DL/kortexdl-python
# Source Intel oneAPI environmentsource~/intel/oneapi/setvars.sh
# Install in editable mode (builds C++ extension automatically)
pip install -e .importkortexdlasbdprint(f"KortexDL version: {bd.__version__}")
print(f"Bindings available: {bd.BINDINGS_AVAILABLE}")
# Test basic functionalitynet=bd.Network([10, 20, 10], bd.ActivationType.ReLU)
print("✅ KortexDL installed successfully!")importkortexdlasbdimportnumpyasnp# Create network: 784 → 128 → 10net=bd.Network([784, 128, 10], bd.ActivationType.ReLU)
# Prepare dataX_train=np.random.randn(100, 784).astype(np.float32)
y_train=np.random.randint(0, 10, (100, 10)).astype(np.float32)
# Trainforepochinrange(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}")
# Predictpredictions=net.forward(X_train[0], batch_size=1, training=False)importkortexdlasbdimportnumpyasnp# Create CNN layersconv1=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 imagesx=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.
Fully connected neural network.
net=bd.Network(
layer_sizes=[784, 128, 64, 10],
activation=bd.ActivationType.ReLU
)
# Trainingloss=net.train_batch(X, y, bd.LossType.MSE, lr=0.01, batch_size=32)
# Inferenceoutput=net.forward(input_data, batch_size=1, training=False)
# Access layerslayers=net.getLayersMutable()
weights=layers[0].get_weights()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 gradientsgrad_w=layer.get_grad_weights()
grad_b=layer.get_grad_biases()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)Max pooling layer.
pool=bd.MaxPool2d(kernel_size=2, stride=2)
output=pool.forward(input)
grad=pool.backward(grad_output)Batch normalization for 2D data.
bn=bd.BatchNorm2d(num_features=64)
output=bn.forward(input) # Normalizes per channelgrad=bn.backward(grad_output)Available: Linear, ReLU, LeakyReLU, ELU, Sigmoid, Tanh, Swish, Softmax
bd.ActivationType.ReLUbd.ActivationType.Sigmoidbd.ActivationType.Tanh# ... see enums_bindings.cpp for complete listAvailable: MSE, MAE, BINARY_CE, CATEGORICAL_CE, HUBER, HINGE, SQUARED_HINGE, KL_DIVERGENCE, POISSON, LOG_COSH
bd.LossType.MSEbd.LossType.CATEGORICAL_CEbd.LossType.BINARY_CECreation 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)Run the comprehensive test suite:
cd kortexdl-python
python -m pytest tests/ -vTest 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.
The C++ Optimizer classes are implemented but not fully accessible from Python:
Optimizer.update()method is not boundNetwork.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.
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.
Some CNN layers exist in C++ but are not yet bound:
DepthwiseConv2dConvTranspose2dUpsample
# 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# Clean build
rm -rf build *.egg-info
pip install -e .# Rebuild C++ onlycd build && cmake --build . --target _kortexdl_core -j$(nproc)- Use
dtype=np.float32: All arrays must be float32 - Contiguous arrays: Ensure
np.ascontiguousarray()for best performance - Batch processing: Larger batches = better MKL utilization
- MKL threads:
export MKL_NUM_THREADS=$(nproc) - Source oneAPI: Always run
source ~/intel/oneapi/setvars.shbefore using
- C++ Core: ../kortexdl-cpp
- Examples: examples/
- Tests: tests/
- Core Audit Report: ../docs/core_audit_report.md
MIT License - see LICENSE file.
Built with ❤️ by Mostafa Saad
Powered by Intel oneAPI MKL and pybind11