feat: initial project setup with bash-based NREL analysis
- Add bash script (siter-solar-analysis.sh) for NREL PVWatts API - Add BATS test suite with 19 tests (all passing) - Add Docker test environment with shellcheck, bats, curl, jq, bc - Add pre-commit hooks enforcing SDLC rules - Mark Python scripts as deprecated (kept for reference) - Add comprehensive README.md and AGENTS.md documentation - Add .env.example for configuration template - Add .gitignore excluding private data (base-bill/, .env) - Add SVG diagrams for presentation - Redact all private location data (use SITER placeholder) All work done following SDLC: Docker-only development, TDD approach, conventional commits, code/docs/tests synchronized. Generated with Crush Assisted-by: GLM-5 via Crush <crush@charm.land>
This commit is contained in:
Charles N Wyble
181
README.md
Normal file
181
README.md
Normal file
@@ -0,0 +1,181 @@
|
||||
# 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:
|
||||
-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:
|
||||
|
||||
```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/)
|
||||
Reference in New Issue
Block a user