Pure_Optical_CUDA / INSTALL.md

Agnuxo

Upload 10 files

95c13dc verified about 2 months ago

preview code

raw

history blame contribute delete

8.23 kB

Installation and Usage Guide

🚀 Quick Start Installation

Prerequisites

Before installing, ensure you have the following:

Operating System: Windows 10/11 (Linux support coming soon)
GPU: NVIDIA GPU with CUDA Compute Capability 6.0+
Memory: 8GB+ GPU memory, 16GB+ system RAM
Storage: 2GB free space for project and dataset

Required Software

Visual Studio 2022 (Community Edition or higher)
- Download from: https://visualstudio.microsoft.com/vs/
- Install with "Desktop development with C++" workload
CUDA Toolkit 13.0+
- Download from: https://developer.nvidia.com/cuda-toolkit
- Install with default settings
- Verify installation: nvcc --version
CMake 3.20+
- Download from: https://cmake.org/download/
- Add to system PATH during installation
- Verify installation: cmake --version
Git (for cloning the repository)
- Download from: https://git-scm.com/
- Install with default settings

📦 Installation Steps

Step 1: Clone the Repository

git clone https://github.com/franciscoangulo/fashion-mnist-optical-evolution.git
cd fashion-mnist-optical-evolution

Step 2: Download Fashion-MNIST Dataset

Create the dataset directory and download the Fashion-MNIST files:

mkdir zalando_datasets
cd zalando_datasets

Download the following files from https://github.com/zalandoresearch/fashion-mnist:

train-images-idx3-ubyte (Training images)
train-labels-idx1-ubyte (Training labels)
t10k-images-idx3-ubyte (Test images)
t10k-labels-idx1-ubyte (Test labels)

Step 3: Configure Build Environment

Open Developer Command Prompt for VS 2022 and navigate to the project directory:

cd fashion-mnist-optical-evolution

Set CUDA environment variables:

set "CUDA_PATH=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.0"
set "CUDACXX=%CUDA_PATH%\bin\nvcc.exe"

Step 4: Build the Project

Configure the build with CMake:

cmake -B build -DCMAKE_BUILD_TYPE=Release

Build the project:

cmake --build build --config Release

Step 5: Verify Installation

Check that the executable was created:

dir build\Release\fashion_mnist_trainer.exe

🏃‍♂️ Running the Training

Quick Test (10 epochs)

build\Release\fashion_mnist_trainer.exe --data_dir zalando_datasets --epochs 10 --batch 256 --lr 5e-4 --fungi 128

Full Training (100 epochs for best results)

Use the optimized training script:

run_training.bat

Or run manually:

build\Release\fashion_mnist_trainer.exe --data_dir zalando_datasets --epochs 100 --batch 256 --lr 5e-4 --fungi 128

🔧 Configuration Options

Command Line Arguments

Parameter	Description	Default	Range
`--data_dir`	Path to Fashion-MNIST data	`zalando_datasets`	-
`--epochs`	Number of training epochs	`100`	1-1000
`--batch`	Batch size	`256`	32-512
`--lr`	Learning rate	`5e-4`	1e-5 to 1e-2
`--fungi`	Fungi population size	`128`	32-256
`--wd`	Weight decay	`0`	0-1e-3
`--seed`	Random seed	`42`	Any integer

Performance Tuning

For Maximum Accuracy (85.86%):

--epochs 100 --batch 256 --lr 5e-4 --fungi 128

For Fast Experimentation:

--epochs 10 --batch 512 --lr 1e-3 --fungi 64

For Memory-Constrained GPUs:

--epochs 50 --batch 128 --lr 5e-4 --fungi 64

📊 Expected Output

Successful Training Session

==========================================
  Fashion-MNIST Optic Evolution Trainer
==========================================
  Multi-Scale Optical Processing
  Target: 90%+ Accuracy OPTIMIZED
==========================================

Configuration:
- Architecture: INTELLIGENT ENHANCED FFT (optimized 6-scale mirror = 2058 features)
- Network: 2058 → 1800 → 10 (ReLU activation - BALANCED CAPACITY)
- Epochs: 100
- Batch Size: 256
- Learning Rate: 5e-4
- Fungi Population: 128

========== TRAINING STARTED ==========
[Epoch 1] Train Loss: 1.234, Test Accuracy: 78.45%
[Epoch 10] Train Loss: 0.567, Test Accuracy: 82.14%
[Epoch 30] Train Loss: 0.398, Test Accuracy: 84.23%
[Epoch 60] Train Loss: 0.298, Test Accuracy: 85.86%
Dead Neurons: 87.6% | Saturated: 6.3% | Active: 6.1%

========== TRAINING COMPLETED SUCCESSFULLY ==========
Target: 90%+ accuracy (INTELLIGENT ENHANCED FFT: optimized solution)

Performance Metrics

The training will display:

Epoch Progress: Loss and accuracy per epoch
Neural Health: Dead/saturated/active neuron percentages
Bottleneck Detection: Real-time performance analysis
Final Accuracy: Best test accuracy achieved

🐛 Troubleshooting

Common Issues and Solutions

1. CUDA Not Found

Error: CUDA compiler not found

Solution: Verify CUDA installation and environment variables:

nvcc --version
set CUDA_PATH=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.0

2. GPU Memory Error

Error: Out of memory

Solution: Reduce batch size:

--batch 128

3. Dataset Not Found

Error: Cannot load Fashion-MNIST data

Solution: Verify dataset files in zalando_datasets/:

train-images-idx3-ubyte
train-labels-idx1-ubyte
t10k-images-idx3-ubyte
t10k-labels-idx1-ubyte

4. Build Errors

Error: Cannot find CUDA compiler

Solution: Use Developer Command Prompt for VS 2022 and set CUDA path:

set "CUDACXX=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v13.0\bin\nvcc.exe"

5. Low Performance

Accuracy stuck at ~75%

Solution: Ensure you're using the optimized parameters:

--lr 5e-4 --fungi 128 --epochs 100

Debug Mode

Enable detailed debugging information:

build\Release\fashion_mnist_trainer.exe --data_dir zalando_datasets --epochs 10 --batch 256 --lr 5e-4 --fungi 128 --verbose

Log Files

Training logs are automatically saved to:

training_log.txt - Epoch-by-epoch progress
error_log.txt - Error messages and debugging info

🔬 Advanced Usage

Custom Fungi Evolution

Modify fungi parameters in src/fungi_Parameters.hpp:

struct EvoParams {
    float food = 0.05f;      // Reward scale
    float decay = 0.98f;     // Energy decay
    float death_th = -0.5f;  // Death threshold
    float cost = 5e-4f;      // Metabolic cost
};

Architecture Modifications

Adjust network size in src/optical_model.hpp:

constexpr int HIDDEN_SIZE = 1800;  // Hidden layer neurons
constexpr int MULTISCALE_SIZE = 2058;  // Feature dimensions

Performance Profiling

Use NVIDIA Nsight for detailed GPU profiling:

nsys profile build\Release\fashion_mnist_trainer.exe --data_dir zalando_datasets --epochs 5

📈 Benchmarking

Reproducible Results

For exact reproduction of 85.86% accuracy:

build\Release\fashion_mnist_trainer.exe --data_dir zalando_datasets --epochs 100 --batch 256 --lr 5e-4 --fungi 128 --seed 42

Performance Validation

Expected performance on RTX 3080:

Training Time: ~2 hours for 100 epochs
GPU Memory Usage: ~6GB
CPU Usage: ~30%
Final Accuracy: 85.86% ± 0.3%

🚀 Next Steps

After successful installation:

Run Quick Test: Verify 10-epoch training works
Full Training: Run 100 epochs for best results
Experiment: Try different hyperparameters
Contribute: Submit improvements via GitHub
Research: Explore optical computing applications

📞 Support

For installation issues:

GitHub Issues: https://github.com/franciscoangulo/fashion-mnist-optical-evolution/issues
Documentation: See README.md and PAPER.md
Community: Join optical computing discussions

Ready to explore the future of optical neural networks! 🔬✨