INSTALL.md

# 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

1. **Visual Studio 2022** (Community Edition or higher)
   - Download from: https://visualstudio.microsoft.com/vs/
   - Install with "Desktop development with C++" workload

2. **CUDA Toolkit 13.0+**
   - Download from: https://developer.nvidia.com/cuda-toolkit
   - Install with default settings
   - Verify installation: `nvcc --version`

3. **CMake 3.20+**
   - Download from: https://cmake.org/download/
   - Add to system PATH during installation
   - Verify installation: `cmake --version`

4. **Git** (for cloning the repository)
   - Download from: https://git-scm.com/
   - Install with default settings

## 📦 Installation Steps

### Step 1: Clone the Repository

```bash
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:

```bash
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:

```bash
cd fashion-mnist-optical-evolution
```

Set CUDA environment variables:
```bash
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:
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Release
```

Build the project:
```bash
cmake --build build --config Release
```

### Step 5: Verify Installation

Check that the executable was created:
```bash
dir build\Release\fashion_mnist_trainer.exe
```

## 🏃‍♂️ Running the Training

### Quick Test (10 epochs)

```bash
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:
```bash
run_training.bat
```

Or run manually:
```bash
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%)**:
```bash
--epochs 100 --batch 256 --lr 5e-4 --fungi 128
```

**For Fast Experimentation**:
```bash
--epochs 10 --batch 512 --lr 1e-3 --fungi 64
```

**For Memory-Constrained GPUs**:
```bash
--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:
```bash
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:
```bash
--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:
```bash
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:
```bash
--lr 5e-4 --fungi 128 --epochs 100
```

### Debug Mode

Enable detailed debugging information:
```bash
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`:
```cpp
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`:
```cpp
constexpr int HIDDEN_SIZE = 1800;  // Hidden layer neurons
constexpr int MULTISCALE_SIZE = 2058;  // Feature dimensions
```

### Performance Profiling

Use NVIDIA Nsight for detailed GPU profiling:
```bash
nsys profile build\Release\fashion_mnist_trainer.exe --data_dir zalando_datasets --epochs 5
```

## 📈 Benchmarking

### Reproducible Results

For exact reproduction of 85.86% accuracy:
```bash
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:

1. **Run Quick Test**: Verify 10-epoch training works
2. **Full Training**: Run 100 epochs for best results
3. **Experiment**: Try different hyperparameters
4. **Contribute**: Submit improvements via GitHub
5. **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!* 🔬✨