SITER-Solar/README.md

# SITER Solar Installation Project

A solar energy installation proposal using NREL PVWatts API for production estimates and analysis of actual billing data.

## Overview

This project provides tools for analyzing solar panel installation economics, including:

- NREL PVWatts API integration for production estimates
- Financial analysis with ROI and payback calculations
- Multiple system size scenario comparisons
- Integration with Base Power battery backup systems

## Quick Start

### Prerequisites

- Docker (recommended)
- Or: bash, curl, jq, bc

### Run Analysis

```bash
# Build and run in Docker (recommended)
docker build -f Dockerfile.test -t siter-solar-test .
docker run --rm siter-solar-test /app/solar-analysis/siter-solar-analysis.sh

# Or run directly (if dependencies are installed)
./solar-analysis/siter-solar-analysis.sh
```

### Examples

```bash
# Basic analysis with defaults
./solar-analysis/siter-solar-analysis.sh

# Compare different system sizes
./solar-analysis/siter-solar-analysis.sh --scenarios

# Custom configuration
./solar-analysis/siter-solar-analysis.sh -p 20 -w 400 --lat 30.5 --lon -97.7

# JSON output for programmatic use
./solar-analysis/siter-solar-analysis.sh --json

# With your NREL API key (avoids rate limits)
NREL_API_KEY=your_key ./solar-analysis/siter-solar-analysis.sh --scenarios
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `NREL_API_KEY` | `DEMO_KEY` | Your NREL API key |
| `SITER_LAT` | `30.44` | Site latitude |
| `SITER_LON` | `-97.62` | Site longitude |

### Command Line Options

```
Usage: siter-solar-analysis.sh [OPTIONS]

Options:
  --lat VALUE            Site latitude (default: 30.44)
  --lon VALUE            Site longitude (default: -97.62)
  -p, --panels NUM       Number of panels (default: 16)
  -w, --watts WATTS      Watts per panel (default: 250)
  -t, --tilt DEGREES     Array tilt in degrees (default: 30)
  -a, --azimuth DEGREES  Array azimuth (default: 180)
  -l, --losses PERCENT   System losses percent (default: 14)
  --scenarios            Run multiple system size scenarios
  --json                 Output as JSON
  --verbose              Enable verbose output
  -h, --help             Show help message
  -v, --version          Show version
```

## Testing

Run the test suite inside Docker:

```bash
docker build -f Dockerfile.test -t siter-solar-test .
docker run --rm siter-solar-test
```

Tests use [BATS (Bash Automated Testing System)](https://github.com/bats-core/bats-core).

## Project Structure

```
siter-solar/
├── README.md                 # This file
├── AGENTS.md                 # Agent documentation (SDLC rules)
├── .env.example              # Environment template
├── .gitignore                # Excludes private data
├── Dockerfile.test           # Test environment
├── v2-siter-solar-plan.md    # Main proposal document
├── images/                   # SVG diagrams
│   ├── v2-image-1.svg        # System architecture
│   ├── v2-image-2.svg        # Monthly production chart
│   ├── v2-image-3.svg        # ROI/payback timeline
│   └── v2-image-4.svg        # System size comparison
└── solar-analysis/           # Analysis tools
    ├── siter-solar-analysis.sh  # Main bash script
    ├── tests/                   # BATS test suite
    │   └── siter-solar-analysis.bats
    ├── solar_estimate.py     # DEPRECATED
    ├── solar_optimal.py      # DEPRECATED
    ├── solar_optimized.py    # DEPRECATED
    ├── Dockerfile            # Production image
    └── run-analysis.sh       # Docker wrapper
```

## Key Parameters

| Parameter | Value | Notes |
|-----------|-------|-------|
| System Capacity | 4.0 kW DC | 16 × 250W panels |
| Array Type | Fixed Open Rack | Ground mount |
| Tilt | 30° | Optimal for latitude |
| Azimuth | 180° | South-facing |
| Losses | 14% (default) | Can optimize to 8% |

## Financial Model

The analysis uses the following assumptions:

- **Self-consumption:** 60% of production (avoids $0.085/kWh)
- **Grid export:** 40% of production (credits $0.04/kWh)
- **Base Power contract:** Fixed rate through Oct 2028
- **Solar buyback:** Credits apply to entire bill

### ROI Calculation

1. Annual production from NREL PVWatts (kWh/year)
2. Self-consumption value: 60% × production × $0.085/kWh
3. Export value: 40% × production × $0.04/kWh
4. Total annual value = self-consumption + export
5. Payback = Total investment / annual value

## NREL API

This project uses the [NREL PVWatts API](https://developer.nrel.gov/docs/solar/pvwatts/v6/).

Get your free API key at: https://developer.nrel.gov/signup/

**Rate Limits:**
- DEMO_KEY: 1 request/second, 1000 requests/hour
- Personal key: Higher limits

## Development

See [AGENTS.md](AGENTS.md) for development guidelines, including:

- SDLC requirements (Docker-only development)
- Testing requirements
- Privacy requirements
- Commit conventions

## License

See [LICENSE](LICENSE) file.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes following SDLC rules in AGENTS.md
4. Ensure all tests pass
5. Submit a pull request

## Resources

- [NREL PVWatts API Documentation](https://developer.nrel.gov/docs/solar/pvwatts/v6/)
- [Base Power Solar Integration](https://www.basepowercompany.com/with-solar)
- [Sol-Ark Inverters](https://www.ecodirect.com/)