# Setup Instructions - BSD Conjecture Verification System

##  System Requirements

### Minimum Requirements
- **Python**: 3.8 or higher
- **RAM**: 4GB (8GB recommended for high-precision computations)
- **Disk Space**: 100MB for package + computation outputs
- **OS**: Linux, macOS, or Windows

### Recommended Environment
- **Python**: 3.10+
- **RAM**: 8GB+
- **CPU**: Multi-core for parallel computations
- **Mathematical Software**: Sage (optional, for advanced verification)

---

##  Installation Guide

### Step 1: Download and Extract

```bash
# Download the Zenodo package
wget [ZENODO_DOWNLOAD_URL]/BSD_Zenodo_Package.zip

# Extract
unzip BSD_Zenodo_Package.zip
cd BSD_Zenodo_Package
```

### Step 2: Python Environment Setup

#### Option A: Using pip (Recommended)
```bash
# Install core dependencies
pip install numpy sympy mpmath pytest pytest-cov

# Verify installation
python -c "import numpy, sympy, mpmath; print('Dependencies installed successfully')"
```

#### Option B: Using conda
```bash
# Create conda environment
conda create -n bsd_verification python=3.10
conda activate bsd_verification

# Install dependencies
conda install numpy sympy mpmath pytest pytest-cov
```

#### Option C: Virtual Environment (Isolated)
```bash
# Create virtual environment
python -m venv bsd_env
source bsd_env/bin/activate  # On Windows: bsd_env\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### Step 3: Configure Python Path

```bash
# Add source directory to Python path
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"

# On Windows:
# set PYTHONPATH=%PYTHONPATH%;%cd%\src

# Or permanently add to your shell profile:
echo 'export PYTHONPATH="${PYTHONPATH}:'$(pwd)'/src"' >> ~/.bashrc
source ~/.bashrc
```

### Step 4: Verification Test

```bash
# Test basic imports
cd tests
python -c "import sys; sys.path.append('../src'); from BSDProver import BSDProver; print(' BSDProver imported successfully')"

# Run quick verification
python test_calibration_quick.py
```

---

## Advanced Setup Options

### High-Precision Computation Setup

For computations requiring very high precision:

```bash
# Install additional precision libraries
pip install gmpy2  # GNU Multiple Precision Arithmetic Library (optional)

# For interval arithmetic (if available):
# pip install pyflint  # Python bindings for FLINT (optional)
```

### Sage Integration (Optional)

For the most comprehensive mathematical environment:

```bash
# Install SageMath (comprehensive mathematical software)
# Option 1: Conda
conda install -c conda-forge sage

# Option 2: System package manager (Ubuntu/Debian)
sudo apt-get install sagemath

# Option 3: From source (advanced users)
# See: https://doc.sagemath.org/html/en/installation/
```

### Performance Optimization

For large-scale computations:

```bash
# Install NumPy with optimized BLAS
pip uninstall numpy
pip install numpy[mkl]  # Intel MKL acceleration

# Or with OpenBLAS
pip install numpy scipy  # Usually comes with OpenBLAS
```

---

## 🧪 Testing Your Installation

### Quick Tests

```bash
# Basic functionality test
cd tests
python -c "
import sys
sys.path.append('../src')
from BSDProver import BSDProver
prover = BSDProver()
print(' BSDProver initialization successful')
"

# Component tests
python test_components.py  # Individual component tests
python test_import_only.py  # Import verification
```

### Full System Verification

```bash
# Literature validation (primary test)
python test_literature_validation.py

# Expected output should show:
# BSD conjecture SATISFIED (< 1% error)
# SUCCESS: Literature validation passed!
```

### Performance Benchmarks

```bash
# Quick calibration test (~30 seconds)
python test_calibration_quick.py

# Enhanced system test (~2-5 minutes)
python test_enhanced_system.py

# Full enhanced capabilities test (~5-10 minutes)
python test_enhanced_capabilities.py
```

---

##  Troubleshooting

### Common Issues

#### 1. Import Errors
```bash
# Error: ModuleNotFoundError: No module named 'BSDProver'
# Solution: Check Python path
export PYTHONPATH="${PYTHONPATH}:$(pwd)/src"
```

#### 2. Missing Dependencies
```bash
# Error: ModuleNotFoundError: No module named 'sympy'
# Solution: Install missing packages
pip install sympy mpmath numpy
```

#### 3. Precision Warnings
```bash
# Warning: "Arb/FLINT not available. Using fallback interval arithmetic."
# This is normal - the system falls back to pure Python arithmetic
# For enhanced precision, install: pip install pyflint (if available)
```

#### 4. Memory Issues
```bash
# Error: Memory error during high-precision computation
# Solution: Reduce precision in config or increase system RAM
# Edit: src/BSDProver/calibrated_config.py
# Reduce: "precision_digits": 50  (from 100)
```

#### 5. Deprecation Warnings
```bash
# Warning: SymPy deprecation warnings
# These are harmless - SymPy is updating function locations
# System continues to work correctly
```

### Platform-Specific Issues

#### Windows
```cmd
# Use forward slashes or double backslashes in paths
set PYTHONPATH=%PYTHONPATH%;%cd%\src

# If PowerShell execution policy issues:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```

#### macOS
```bash
# If using Apple Silicon (M1/M2):
# Some packages may need Rosetta 2
# Install with: softwareupdate --install-rosetta

# Use Homebrew Python if system Python causes issues:
brew install python@3.10
```

#### Linux
```bash
# If missing development headers:
sudo apt-get install python3-dev build-essential

# For CentOS/RHEL:
sudo yum install python3-devel gcc
```

---

##  Performance Expectations

### Computation Times (typical desktop)

| Test | Expected Time | Memory Usage |
|------|---------------|--------------|
| Quick calibration | 30 seconds | < 1GB |
| Literature validation | 1-2 minutes | < 2GB |
| Enhanced system test | 2-5 minutes | < 4GB |
| High-precision (conductor > 1000) | 10+ minutes | 4-8GB |

### Accuracy Expectations

| Component | Typical Accuracy | Literature Match |
|-----------|------------------|------------------|
| L-function | 0.001% error | Yes |
| BSD ratio | < 0.1% deviation |  Yes |
| Torsion order | Exact | Yes |
| Tamagawa numbers | Exact |  Yes |

---

##  Updates and Maintenance

### Keeping Updated

```bash
# Check for package updates
# (This would be automated in a live system)
# For now, download latest version from Zenodo

# Update dependencies
pip install --upgrade numpy sympy mpmath
```

### Contributing

If you find issues or improvements:

1. Document the issue with complete error messages
2. Include system information: `python --version`, OS, etc.
3. Provide minimal reproduction case
4. Check against latest version

---

##  Next Steps

After successful installation:

1. **Read the documentation**: `docs/ZENODO_SUBMISSION.md`
2. **Try examples**: `examples/demo_enhanced_bsd.py`
3. **Run your own curves**: Modify test files with your curve parameters
4. **Explore the API**: `docs/API_REFERENCE.md` (if available)

### Learning Path

1. **Start with**: `test_calibration_quick.py` - understand basic concepts
2. **Progress to**: `test_literature_validation.py` - see full validation
3. **Advanced usage**: `examples/enhanced_bsd_test.py` - comprehensive testing
4. **Research application**: Use `BSDProver` class in your own scripts

---

##  Support

### Self-Help Resources
- **Documentation**: `docs/` directory
- **Examples**: `examples/` directory
- **Test cases**: `tests/` directory
- **Source code**: `src/BSDProver/` (well-commented)