Cranium Neural Network Library

A pure Rust implementation of neural networks, inspired by the Cranium C library. This version maintains the same philosophy of simplicity and efficiency while leveraging Rust's safety guarantees and modern features.

Features

• Pure Rust: Zero unsafe code, leveraging Rust's ownership system

• Standard Dependencies: Uses only rand from std and optional alloc for no_std support

• Core Components:

  • Efficient matrix operations with row-major storage
  • Feedforward neural networks with configurable architecture
  • Multiple activation functions (Sigmoid, ReLU, Tanh, Softmax, Linear)
  • Multiple loss functions (Cross Entropy, MSE)
  • Momentum-based optimization with learning rate annealing
  • L2 regularization for preventing overfitting
  • Batch processing with data shuffling
  • Network serialization for model persistence

• Error Handling: Custom CraniumError type with proper error propagation

• Memory Safety: Zero unsafe code, leveraging Rust's ownership system

• Performance: Optimized matrix operations without SIMD dependencies

• Testing: Comprehensive test suite including integration tests

Installation

Add the following to your Cargo.toml:

[dependencies]
cranium = "0.1.0"

Usage

Here's a simple example of creating and training a neural network:

use cranium::{Network, NetworkConfig, Activation, Loss, TrainingConfig, Matrix, CraniumResult};

fn main() -> CraniumResult<()> {
    // Create network configuration
    let config = NetworkConfig {
        input_size: 2,
        hidden_sizes: &[3],
        output_size: 1,
        hidden_activations: &[Activation::ReLU],
        output_activation: Activation::Linear,
    };

    // Create network with error handling
    let mut network = Network::new(config, Loss::MSE)?;

    // Create training configuration
    let training_config = TrainingConfig {
        learning_rate: 0.01,
        batch_size: 32,
        epochs: 1000,
        shuffle: true,
        regularization: 0.001,
    };

    // Train network with proper error handling
    let losses = network.train(&input, &target, &training_config)?;
    println!("Final training loss: {:.6}", losses.last().unwrap());

    // Make predictions
    let predictions = network.predict(&test_input)?;
    Ok(())
}

Examples

XOR Problem

See the integration tests for a complete XOR problem example.

MNIST Digit Classification

See the examples directory for a complete MNIST digit classification example.

Implementation Details

Matrix Operations

• Row-major storage for efficient memory access
• Optimized matrix multiplication
• Element-wise operations (addition, multiplication)
• Matrix transpose and mapping operations

Neural Network

• Configurable network architecture
• Efficient forward and backward passes
• Proper error handling with custom error types
• Support for different activation and loss functions
• Batch processing with optional data shuffling

Error Handling

pub enum CraniumError {
    DimensionMismatch,
    InvalidConfig,
    NumericalError,
    UnsupportedOperation,
    IoError,
}

Performance Considerations

1. Memory Usage:

   • Efficient matrix storage
   • Minimal memory allocations
   • Configurable batch sizes

2. Computation:

   • Optimized matrix operations
   • Efficient forward and backward passes
   • Batch processing for better throughput

3. Numerical Stability:

   • Proper weight initialization
   • Numerically stable softmax implementation
   • Gradient handling for different activation functions

Differences from C Version

While inspired by the original C implementation, this Rust version offers several improvements:

• Memory safety through Rust's ownership system
• More comprehensive error handling
• Modern API design with Rust idioms
• Better documentation and examples
• Integration with Rust's ecosystem
• Optional no_std support for embedded systems

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by the original Cranium C library
• Built with Rust's excellent ecosystem
• Thanks to all contributors