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

# 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

# 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:
  -k, --api-key KEY      NREL API key (or set NREL_API_KEY env var)
  --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:

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

Tests use BATS (Bash Automated Testing System).

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.

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 for development guidelines, including:

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

License

See 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
• Base Power Solar Integration
• Sol-Ark Inverters