# SunSolve P90 Analysis Client

A Python client library for connecting to the SunSolve P90 analysis service via gRPC. This package enables photovoltaic system P90 analysis with comprehensive uncertainty modeling and Monte Carlo simulations.

## Features

- **Direct gRPC Connection**: Secure, efficient communication with SunSolve P90 service
- **Uncertainty Analysis**: Apply probability distributions to solar resource, system losses, and operational parameters
- **Multi-Year Simulations**: Support for both Typical Mean Year (TMY) and multi-year actual datasets
- **Comprehensive Error Handling**: Custom exception classes for different error scenarios
- **Type Safety**: Full type annotations for better development experience
- **Weather Data Support**: Load data from PVW files and CSV formats

## Quick Start

### Installation

```bash
pip install sunsolve-p90-client
```

### Prerequisites

- Python 3.12+
- SunSolve account with **P90 Analysis subscription** ([sign up here](https://sunsolve.info/p90/signup))
- Network access to SunSolve servers

### Basic Usage

```python
from pvl_p90_client.client.p90_client import P90Client
from pvl_p90_client.grpcclient.uncertaintyMessages_pb2 import DistributionInput
from pvl_p90_client.helpers import pvl_login
from pvl_p90_client.helpers.request_helpers import (
    build_distribution,
    build_gaussian_distribution,
    build_request,
    load_weather_data_from_pvw_file,
)

# Connect to the P90 analysis service
with P90Client() as client:
    # Authenticate with your SunSolve credentials (prompts for username/password)
    credentials = pvl_login.login()

    # Load weather data from a PVW file (Typical Mean Year format)
    weather_data = load_weather_data_from_pvw_file("../data/sydney.pvw") or []

    # Add uncertainty distribution for Global Horizontal Irradiance (GHI)
    # This adds ±5% variation to solar irradiance values
    distributions = [
        build_distribution(
            input=DistributionInput.GHI,
            sim_to_sim_distribution=build_gaussian_distribution(1.0, 0.05)
        )
    ]

    # Create a minimal request with weather data and basic uncertainty
    # This uses default system parameters and simulation settings
    request = build_request(time_step_data=weather_data, distributions=distributions)

    # Send the analysis request and receive results
    summary, used_inputs = client.send_request(request, credentials, timeout=90.0)

    # Display results
    if summary:
        print(f"Analysis complete! Generated {len(summary.YearlyPValue)} yearly P-values")
        for pvalue in summary.YearlyPValue:  # Show all years
            print(f"  Year {pvalue.Year}: P{pvalue.P} = {pvalue.P50Deviation:.4f}")
    else:
        print("No analysis results received")
```

## What This Package Does

The SunSolve P90 Analysis Client enables you to:

- **Run Monte Carlo Simulations**: Calculate P-values (probability of exceedance) for photovoltaic energy production
- **Apply Uncertainty Distributions**: Model variability in solar resource, system performance, and operational factors
- **Process Weather Data**: Import and analyze weather datasets in multiple formats
- **Get Probabilistic Results**: Receive P5, P10, P50, P90, P95 confidence intervals for energy production

## Uncertainty Modeling

Apply probability distributions to key parameters:

- **Solar Resource**: GHI, temperature, wind speed variations
- **System Performance**: Module mismatch, inverter efficiency, soiling losses
- **Operational Factors**: Degradation rates, availability, curtailment

## Results

Get comprehensive probabilistic analysis including:

- **P-Values**: Probability of exceedance levels (P5, P10, P50, P90, P95)
- **Yearly Projections**: Multi-year degradation modeling
- **Monte Carlo Statistics**: Distribution analysis across thousands of simulations

## Support & Documentation

- **Documentation**: [docs.sunsolve.com/en/p90/](https://docs.sunsolve.com/en/p90/)
- **Getting Started**: [P90 Analysis Guide](https://docs.sunsolve.com/en/p90/getting-started/)
- **Contact**: [sunsolve.info/contact/](https://sunsolve.info/contact/)

---

**Note**: This package requires a SunSolve account with P90 Analysis subscription. Visit [sunsolve.info](https://sunsolve.info/p90/signup) to get started.