PyCNN Framework

Python Convolutional Neural Network framework optimized for both CPU and GPU computing with advanced Cython acceleration

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

๐Ÿง  Advanced CNN Capabilities

๐Ÿ”ง Developer Experience

Installation

PyCNN requires Python version between 3.6 and 3.11 and can be installed with the following dependencies:

Requirements
# 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 Installation
git clone git+https://github.com/77AXEL/PyCNN.git
cd pycnn.pycnn
pip install -e .

Verify Installation

Python Test
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.

basic_example.py
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")
advanced_config.py
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)
prediction_example.py
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})")
pycnn_pytorch.py
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

custom_classification.py
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

transfer_learning.py
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

batch_evaluation.py
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

huggingface_example.py
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)

150
Pure NumPy
350
PyCNN CPU
400
PyCNN CUDA
225
TensorFlow Lite
425
PyTorch

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

Minimum 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