27-combi/SETUP_INSTRUCTIONS.md

Setup Instructions

Quick Setup

Step 1: Install Python venv (if needed)

On Debian/Ubuntu/WSL:

# 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

Step 2: Verify Setup

Run the verification script:

./verify_setup.sh

You should see all checks pass (✅).

Step 3: Generate Workbook

Linux/WSL:

./generate_excel.sh

Windows:

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:

# 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:

# 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:

# 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:

sudo apt update
sudo apt install python3-venv

Virtual environment creation fails

Try:

# 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:

# 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:

# 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:

./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