27-combi/SETUP_INSTRUCTIONS.md

# Setup Instructions

## Quick Setup

### Step 1: Install Python venv (if needed)

**On Debian/Ubuntu/WSL:**
```bash
# Check your Python version first
python3 --version

# Install the matching venv package (replace 3.12 with your version)
sudo apt install python3.12-venv

# Or install the general package
sudo apt install python3-venv
```

**On Windows:**
- Python venv is usually included with Python installation
- If missing, reinstall Python from [python.org](https://www.python.org/downloads/)

### Step 2: Verify Setup

Run the verification script:
```bash
./verify_setup.sh
```

You should see all checks pass (✅).

### Step 3: Generate Workbook

**Linux/WSL:**
```bash
./generate_excel.sh
```

**Windows:**
```cmd
generate_excel.bat
```

## What the Scripts Do

1. **Create virtual environment** (`venv/`) - Isolated Python environment
2. **Install xlsxwriter** - Excel generation library
3. **Generate workbook** - Creates `DeFi_Collateral_Simulation.xlsx`
4. **Clean up** - Deactivates virtual environment

## Quick Fix

If you get "No such file or directory" for venv/bin/activate:

```bash
# Run the fix script
./fix_venv.sh

# Or manually clean up
rm -rf venv
```

Then install the venv package and try again.

## Troubleshooting

### "venv/bin/activate: No such file or directory"

**Solution:**
```bash
# Clean up incomplete venv
rm -rf venv

# Or use the fix script
./fix_venv.sh

# Then install venv package (see below)
```

### "ensurepip is not available"

**Solution:**
```bash
# Find your Python version
python3 --version

# Install matching venv package (example for Python 3.12)
sudo apt install python3.12-venv

# Or try the general package
sudo apt install python3-venv
```

### "python3-venv: command not found"

**Solution:**
```bash
sudo apt update
sudo apt install python3-venv
```

### Virtual environment creation fails

**Try:**
```bash
# Remove old venv if it exists
rm -rf venv

# Create fresh venv
python3 -m venv venv

# If that fails, install venv package first (see above)
```

### Permission denied

**Solution:**
```bash
# Make scripts executable
chmod +x generate_excel.sh
chmod +x verify_setup.sh
```

## Manual Setup (Alternative)

If the scripts don't work, you can do it manually:

```bash
# 1. Create virtual environment
python3 -m venv venv

# 2. Activate it
source venv/bin/activate

# 3. Install xlsxwriter
pip install xlsxwriter

# 4. Generate workbook
python generate_defi_simulation.py

# 5. Deactivate when done
deactivate
```

## Verification

After setup, verify everything works:

```bash
./verify_setup.sh
```

All checks should show ✅.

## Next Steps

Once the workbook is generated:
1. Open `DeFi_Collateral_Simulation.xlsx` in Excel or LibreOffice
2. Review the **Help** sheet for test cases
3. Follow `TEST_CHECKLIST.md` to verify functionality