Overview
PyCNN is a specialized deep learning framework designed for Convolutional Neural Networks with a focus on performance and ease of use. Built on top of NumPy, CuPy, SciPy, and Pillow, it leverages C/C++ optimizations and Cython acceleration for exceptional performance on both CPU and GPU platforms.
You can try out a trained CNN model built with PYCNN on the CIFAR-10 dataset using this Hugging Face Space: pycnn_cifar10โคด
Core Architecture
The framework features a dual-backend system that automatically switches between CPU and CUDA implementations, providing optimal performance regardless of your hardware setup. The CPU backend utilizes highly optimized Cython, C, and C++ code for maximum efficiency.
Performance Optimized
Cython, C, and C++ acceleration for CPU operations with automatic CUDA support for GPU computing.
Flexible Architecture
Modular design supporting custom filters, multiple optimizers, and various dataset formats.
Built-in Visualization
Real-time training visualization and comprehensive performance monitoring tools.
Key Features
๐ High Performance Computing
- Dual Backend System: Automatic switching between optimized CPU and CUDA implementations
- Cython Acceleration: Critical operations implemented in Cython for maximum CPU performance
- C/C++ Integration: Low-level optimizations for computational bottlenecks
- Memory Efficient: Smart memory management and batch processing
๐ง Advanced CNN Capabilities
- 19 Built-in Filters: Comprehensive collection of edge detection, enhancement, and feature extraction filters
- Custom Architectures: Flexible layer configuration with customizable hidden layers
- Advanced Pooling: Optimized max pooling with configurable stride and window size
- Activation Functions: ReLU activation with support for custom functions
- Dataset Augmentation: Data augmentation support with a customizable type
- PyTorch Model Exportation: Export your PyCNN trained model to a PyTorch format to use it in PyTorch later
๐ง Developer Experience
- Simple API: Intuitive interface for rapid prototyping and development
- Multiple Data Sources: Support for local datasets and Hugging Face integration
- Model Persistence: Save and load trained models with cross-platform compatibility
- Real-time Monitoring: Built-in training visualization and progress tracking
Installation
PyCNN requires Python version between 3.6 and 3.11 and can be installed with the following dependencies:
# Core framework
pip install git+https://github.com/77AXEL/PyCNN.git
# Optional: For CUDA support
pip install cupy-cuda11x # or cupy-cuda12x for CUDA 12
# Optional: For Hugging Face datasets
pip install datasets
From Source
git clone git+https://github.com/77AXEL/PyCNN.git
cd pycnn.pycnn
pip install -e .
Verify Installation
from pycnn.pycnn import PyCNN
# Create instance and check backend
model = PyCNN()
print(f"Backend: {'CUDA' if model.use_cuda else 'CPU'}")
Quick Start Guide
Get started with PyCNN in just a few lines of code. This example shows how to create, train, and use a CNN for image classification.
from pycnn.pycnn import PyCNN
# Initialize the model
model = PyCNN()
# Configure network architecture
model.init(
batch_size=32,
layers=[128, 64],
learning_rate=0.001,
epochs=50
)
# Load dataset from local directory
model.dataset.local("./dataset", max_image=100, image_size=64)
# Train the model
model.train_model(visualize=True)
# Save the trained model
model.save_model("my_model.bin")
from pycnn.pycnn import PyCNN
# Initialize with CUDA support
model = PyCNN()
model.cuda(True) # Enable CUDA if available
# Configure Adam optimizer
model.adam(beta1=0.9, beta2=0.999, eps=1e-8)
# Custom filter configuration
custom_filters = [
[[-1, 0, 1], [-2, 0, 2], [-1, 0, 1]], # Sobel X
[[-1, -2, -1], [0, 0, 0], [1, 2, 1]] # Sobel Y
]
# Initialize with custom parameters
model.init(
batch_size=64,
layers=[256, 128, 64],
learning_rate=0.001,
epochs=100,
filters=custom_filters
)
# Load from Hugging Face with dataset augmentation
model.dataset.hf("cifar10", max_image=1000, aug=
[
1, # Left-Right Flip
2, # Top-Bottom Flip
3, # 90 degree rotation
4 # -90 degree rotation
]
)
# Train with early stopping
model.train_model(visualize=True, early_stop=10)
from pycnn.pycnn import PyCNN
# Load a pre-trained model
model = PyCNN()
model.load_model("my_model.bin")
# Make predictions on new images
predicted_class, confidence = model.predict("test_image.jpg")
print(f"Predicted class: {predicted_class}")
print(f"Confidence: {confidence:.4f}")
# Batch prediction example
import os
test_images = [f"test_{i}.jpg" for i in range(5)]
for img_path in test_images:
if os.path.exists(img_path):
pred_class, conf = model.predict(img_path)
print(f"{img_path}: {pred_class} ({conf:.3f})")
from pycnn.pycnn import PyCNN
from pycnn.pycnn import PyCNNTorchModel
from PIL import Image
import numpy as np
import torch
# Initialize PyCNN model
pycnn = PyCNN()
pycnn.init(
epochs=50,
layers=[64, 32],
learning_rate=0.0001
)
# Load dataset from Hugging Face
pycnn.dataset.hf("cifar10", max_image=50, aug=[])
# Configure Adam optimizer and train
pycnn.adam()
pycnn.train_model()
pycnn.torch("model.pth")
# Load PyTorch model from checkpoint
checkpoint = torch.load('model.pth', map_location='cpu')
model = PyCNNTorchModel(
checkpoint['layers'],
checkpoint['num_classes'],
checkpoint['filters'],
checkpoint['image_size']
)
model.load_state_dict(checkpoint['model_state_dict'])
model.eval()
# Prediction function
def predict(image_path):
img = Image.open(image_path).convert("RGB")
img = img.resize((checkpoint['image_size'], checkpoint['image_size']), Image.Resampling.LANCZOS)
img_array = np.array(img).astype(np.float32) / 255.0
img_tensor = torch.from_numpy(img_array).permute(2, 0, 1).unsqueeze(0)
with torch.no_grad():
output = model(img_tensor)
confidence, predicted_idx = torch.max(output, 1)
predicted_class = checkpoint['classes'][predicted_idx.item()]
print(f"Prediction: {predicted_class} (Confidence: {confidence.item()*100:.2f}%)")
# Make a prediction
predict("cifar10_test/airplane/airplane_3.png")
API Reference
PyCNN Class
The main class for creating and managing CNN models.
Initialization Methods
| Method | Parameters | Description |
|---|---|---|
| __init__() | None | Initialize PyCNN instance with default CPU backend |
| init() |
batch_size int layers list learning_rate float epochs int filters list |
Configure network architecture and training parameters |
| cuda() | use_cuda bool | Enable or disable CUDA acceleration |
| adam() |
beta1 float beta2 float eps float |
Configure Adam optimizer with momentum parameters |
Training Methods
| Method | Parameters | Description |
|---|---|---|
| train_model() |
visualize bool early_stop int |
Train the model with optional visualization and early stopping |
| predict() | img_path str | Make prediction on a single image, returns (class, confidence) |
Model Persistence
| Method | Parameters | Description |
|---|---|---|
| save_model() | path str | Save trained model to disk with cross-platform compatibility |
| load_model() | model_path str | Load pre-trained model from disk |
| torch() | path str | Save trained model to disk with PyTorch format |
Dataset Loader
Access through model.dataset for data loading operations.
| Method | Parameters | Description |
|---|---|---|
| local() |
path str max_image int image_size int |
Load dataset from local directory structure |
| hf() |
name str max_image int split str cached bool |
Load dataset from Hugging Face datasets hub |
Built-in Filters
PyCNN comes with 19 pre-defined convolutional filters for various image processing tasks:
Edge Detection
- Sobel X & Y filters
- Prewitt operators
- Laplacian filters
- Custom edge enhancement
Feature Enhancement
- Sharpening filters
- High-pass filters
- Contrast boosting
- Diagonal enhancement
Specialized Filters
- Blur and smoothing
- Corner detection
- Emboss effects
- Line detection
Examples & Use Cases
1. Image Classification with Custom Dataset
import os
from pycnn.pycnn import PyCNN
# Create dataset directory structure
# dataset/
# โโโ cats/
# โโโ dogs/
# โโโ birds/
def train_animal_classifier():
model = PyCNN()
# Configure for multi-class classification
model.init(
batch_size=16,
layers=[512, 256, 128],
learning_rate=0.0001,
epochs=75
)
# Load local dataset
model.dataset.local(
path="./animal_dataset",
max_image=500,
image_size=128
)
# Train with visualization
model.train_model(visualize=True, early_stop=15)
# Save the model
model.save_model("animal_classifier.bin")
return model
if __name__ == "__main__":
model = train_animal_classifier()
2. Transfer Learning with Pre-trained Features
from pycnn.pycnn import PyCNN
def fine_tune_model(base_model_path, new_dataset_path):
# Load pre-trained model
model = PyCNN()
model.load_model(base_model_path)
# Reduce learning rate for fine-tuning
model.learning_rate = 0.00001
# Load new dataset
model.dataset.local(
path=new_dataset_path,
max_image=200,
image_size=model.image_size
)
# Fine-tune with fewer epochs
model.epochs = 20
model.train_model(visualize=True)
return model
# Usage
fine_tuned_model = fine_tune_model(
"base_model.bin",
"./specialized_dataset"
)
3. Batch Processing and Evaluation
import os
from collections import defaultdict
from pycnn.pycnn import PyCNN
def evaluate_model(model_path, test_directory):
model = PyCNN()
model.load_model(model_path)
results = defaultdict(list)
total_correct = 0
total_images = 0
# Process each class directory
for class_name in os.listdir(test_directory):
class_path = os.path.join(test_directory, class_name)
if not os.path.isdir(class_path):
continue
class_correct = 0
class_total = 0
for image_file in os.listdir(class_path):
if image_file.lower().endswith(('.jpg', '.png', '.jpeg')):
image_path = os.path.join(class_path, image_file)
predicted_class, confidence = model.predict(image_path)
results[class_name].append({
'predicted': predicted_class,
'confidence': confidence,
'correct': predicted_class == class_name
})
if predicted_class == class_name:
class_correct += 1
total_correct += 1
class_total += 1
total_images += 1
# Print class-specific accuracy
class_accuracy = class_correct / class_total if class_total > 0 else 0
print(f"{class_name}: {class_accuracy:.4f} ({class_correct}/{class_total})")
# Overall accuracy
overall_accuracy = total_correct / total_images
print(f"Overall Accuracy: {overall_accuracy:.4f} ({total_correct}/{total_images})")
return results, overall_accuracy
# Usage
results, accuracy = evaluate_model("my_model.bin", "./test_dataset")
4. Working with Hugging Face Datasets
from pycnn.pycnn import PyCNN
def train_on_cifar10():
model = PyCNN()
# Enable CUDA if available
model.cuda(True)
# Configure Adam optimizer
model.adam(beta1=0.9, beta2=0.999)
# Initialize with appropriate architecture for CIFAR-10
model.init(
batch_size=64,
layers=[1024, 512, 256],
learning_rate=0.001,
epochs=100
)
# Load CIFAR-10 dataset
model.dataset.hf(
name="cifar10",
max_image=2000, # Limit for demo
split="train",
cached=True
)
# Train with early stopping
model.train_model(visualize=True, early_stop=10)
# Save the model
model.save_model("cifar10_model.bin")
return model
def train_on_custom_hf_dataset():
model = PyCNN()
# Try different popular datasets
datasets_to_try = [
"food101",
"oxford-iiit-pet",
"imagenet-1k"
]
for dataset_name in datasets_to_try:
try:
print(f"Trying to load {dataset_name}...")
model.dataset.hf(
name=dataset_name,
max_image=100, # Small sample
split="train"
)
print(f"Successfully loaded {dataset_name}")
break
except Exception as e:
print(f"Failed to load {dataset_name}: {e}")
return model
if __name__ == "__main__":
# Train on CIFAR-10
cifar_model = train_on_cifar10()
Performance & Benchmarks
PyCNN is optimized for high-performance computing with specialized acceleration for both CPU and GPU environments.
Performance Comparison
Training Speed Comparison (Images/Second)
Optimization Features
Cython Acceleration
Critical operations compiled to C for 2-3x performance improvement over pure NumPy on CPU.
CUDA Integration
Seamless GPU acceleration with CuPy for parallel computation on NVIDIA GPUs.
Memory Optimization
Efficient memory management with batch processing and automatic garbage collection.
Adaptive Backend
Automatic selection between CPU and GPU backends based on available hardware.
System Requirements
# CPU Requirements
Python: 3.7+
RAM: 4GB minimum, 8GB recommended
CPU: Multi-core processor (Intel/AMD)
# GPU Requirements (Optional)
NVIDIA GPU: GTX 1060 or better
CUDA: 11.0+ or 12.0+
VRAM: 4GB minimum, 8GB+ recommended
# Storage
Disk Space: 2GB for framework + dataset storage
Performance Tips
๐ก Optimization Recommendations
- Batch Size: Use larger batches (64-128) for GPU, smaller (16-32) for CPU
- Image Size: Start with 64x64 or 128x128 for faster iteration
- Early Stopping: Use early stopping to prevent overfitting and save time
- Learning Rate: Start with 0.001 for Adam, 0.01 for SGD
- Memory: Monitor RAM usage with large datasets, use max_image parameter