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!* 🔬✨