# PrecipGen Documentation

## Quick Start

- [Installation Guide](installation.md) - Get PrecipGen installed
- [User Guide](user_guide.md) - Learn to use PrecipGen's enhanced capabilities

## Reference

- [API Reference](api.md) - Complete function documentation
- [Mathematical Foundation](mathematical_foundation.md) - Algorithm details

## Overview

PrecipGen provides enhanced workflow integration with decoupled simulation engines:

### Enhanced Unified API (Recommended)

Complete workflow integration with all components accessible through single import:

```python
import precipgen as pg

# Enhanced CSV workflow with metadata preservation
precip_data = pg.load_csv_precipitation_data(
    "Logan_UT.csv", 
    station_name="Logan, UT",
    coordinates=(41.7370, -111.8338)
)

# Enhanced analytical engine with comprehensive capabilities
engine = pg.AnalyticalEngine(precip_data, wet_day_threshold=0.0254)
engine.initialize()

# Comprehensive statistics and visualization
engine.print_annual_precipitation_statistics()
engine.plot_annual_precipitation(save_path='annual_precip.png')

# Parameter-only simulation (no historical data required)
manifest = engine.generate_parameter_manifest()
simulator = pg.PrecipitationSimulator(parameters=manifest)
results = simulator.run_monte_carlo_simulation(n_realizations=100)
```

### Decoupled Simulation Engines

Parameter-only operation without historical data requirements:

```python
# Simulation works with parameters from any source
simulator = pg.PrecipitationSimulator(parameters=manifest)
results = simulator.run_monte_carlo_simulation(
    start_date='2025-01-01',
    end_date='2030-12-31',
    methods=['wgen'],  # Parameter-only methods
    n_realizations=50
)
```

## Key Features

- **🔧 Decoupled Architecture** - Simulation engines operate independently of data source requirements
- **📊 Enhanced Analytics** - Comprehensive precipitation analysis with automatic plotting and trend detection
- **🔄 Seamless Workflows** - Unified API enabling smooth transitions from data loading through analysis to simulation
- **📈 Richardson & Wright (1984) WGEN Algorithm** - Mathematically sound implementation with modern enhancements
- **🌡️ Non-stationary Climate Modeling** - Trend detection and seasonal parameter evolution
- **⚡ Stateful Simulation Engine** - Maintains state for external model integration
- **🌐 Enhanced Data Handling** - CSV and GHCN workflows with metadata preservation
- **🎯 Parameter-Only Simulation** - Generate synthetic data using pre-computed parameters from any source

## Documentation Structure

```
docs/
├── installation.md          # Installation instructions
├── user_guide.md           # Usage examples and best practices
├── api.md                  # Complete API documentation
├── mathematical_foundation.md  # Algorithm details and theory
└── README.md              # This overview
```

## Examples

Complete working examples are available in the [examples/](../examples/) directory:

- `workflow_integration_example.py` - Comprehensive demonstration of enhanced workflow integration
- `simple_workflow_example.py` - Demonstrates simplified API usage
- `decoupled_workflow_example.py` - Shows parameter-only simulation capabilities
- `standardized_api_example.py` - External integration patterns

## Getting Help

1. **Check the User Guide** - Most common questions are answered there
2. **Review API Reference** - Complete function documentation
3. **Examine Examples** - Working code for common use cases
4. **Mathematical Foundation** - Algorithm details and theory

## Contributing

See [CONTRIBUTING.md](../CONTRIBUTING.md) for development guidelines.

## License

MIT License - see [LICENSE](../LICENSE) file for details.