==================
Model Documentation
==================

**Comprehensive documentation included with every model**

.. epigraph::

   **Complete transparency.** Every VerveStacks model includes comprehensive documentation that travels with the model, ensuring you understand exactly what you're working with.

Documentation Structure
=======================

Each VerveStacks model includes a detailed ``README.md`` file that provides complete information about the model's construction, data sources, and validation results.

Processing Parameters
---------------------

**Individual Plant Tracking**
  Detailed breakdown of power plant coverage, showing which facilities are tracked individually versus aggregated by technology.

**CCS Retrofit Potential**
  Analysis of carbon capture and storage retrofit opportunities for existing coal and gas plants, including capacity penalties and technical feasibility.

**Capacity Thresholds**
  Clear documentation of modeling thresholds and aggregation decisions for different plant sizes and technologies.

Data Sources & Coverage
-----------------------

**Primary Data Sources**
- **Global Energy Monitor (GEM)**: Individual power plant specifications, locations, and technical parameters
- **IRENA Statistics**: Global renewable capacity and generation data (2000-2022)
- **EMBER Climate**: Electricity generation, capacity, and emissions tracking
- **REZoning-Atlite Integration**: Enhanced renewable characterization with weather-based capacity factors

**Coverage Statistics**
  Quantified data coverage including percentage of capacity from plant-level data, total plants tracked, and missing capacity estimates.

**Data Processing Notes**
  Transparent documentation of data gaps, assumptions made, and quality assurance procedures applied.

Model Structure
---------------

**File Organization**
- **Source Data**: Model-agnostic Excel format for maximum compatibility
- **VEDA Model Files**: Complete TIMES-compatible model ready for execution
- **Scenario Files**: NGFS climate scenarios and policy assumptions
- **Documentation**: Complete methodology and validation results

Advanced Features (When Applicable)
====================================

Temporal Modeling
-----------------
**For models with timeslice analysis:**

**Stress Period Identification**
  Sophisticated analysis identifying critical operational periods including scarcity (renewable shortage), surplus (excess generation), and volatile (high variability) periods.

**Visual Analysis**
  Comprehensive charts showing renewable energy patterns, stress periods, and timeslice aggregation justification.

**Multi-Scale Resolution**
  Base aggregation with critical period enhancement for operational realism.

Grid Modeling
-------------
**For models with spatial resolution:**

**Network Visualization**
  Interactive maps showing transmission infrastructure, power plant locations, and renewable energy zones.

**Spatial Clustering**
  Documentation of demand regions, generation clusters, and renewable zones with geographic validation.

**Transmission Modeling**
  Net transfer capacity estimation and grid constraint analysis.

AR6 Climate Scenarios
----------------------
**For models with climate integration:**

**Scenario Analysis**
  Detailed breakdown of IPCC AR6 pathways including CO2 pricing, electricity growth, hydrogen deployment, and transport electrification.

**Regional Context**
  Country-specific analysis within broader regional decarbonization patterns.

**Policy Insights**
  Quantified implications of different climate ambition levels for national energy planning.

Quality Assurance
==================

**Validation Framework**
  Every model undergoes systematic validation against historical data, cross-dataset consistency checks, and geographic verification.

**Transparency Standards**
  Complete data lineage documentation showing the path from global datasets to model parameters.

**Reproducibility**
  All processing steps documented with clear methodology for independent verification.

**Known Limitations**
  Honest assessment of data gaps, modeling assumptions, and recommended use cases.

Accessing Documentation
=======================

**README Location**
  The comprehensive README.md file is included in every model download and provides immediate access to all documentation.

**Live Updates**
  Documentation is regenerated with each model update, ensuring current information about data sources and methodology.

**User-Friendly Format**
  Documentation uses clear language and visual elements, making technical information accessible to policy analysts and researchers.

**Complete Traceability**
  Every parameter and assumption can be traced back to its source data and processing logic.

Documentation Philosophy
========================

**User-Centered**
  Documentation focuses on what users need to know to apply the model effectively, not implementation details.

**Assumption Transparency**
  All modeling choices, data gaps, and limitations are clearly documented and justified.

**Visual Communication**
  Extensive use of charts, maps, and diagrams to communicate complex technical information clearly.

**Professional Standards**
  Documentation meets academic and policy analysis standards for transparency and reproducibility.