A Python Framework for Large-Scale Solar PV Potential and Techno-Economic Scenario Analysis

OverviewThis repository contains the complete, reproducible Python pipeline for the national-scale assessment of solar photovoltaic (PV) potential and economic viability across Iran. The code accompanies the research paper: "National-Scale Solar PV Potential and Investment Site Selection in Iran Using Multi-Criteria Decision Making". The pipeline is designed to process massive spatiotemporal climate datasets (76 years of hourly ERA5-Land data, exceeding 650,000 records), integrate high-resolution geospatial constraints, and evaluate complex techno-economic scenarios. It outputs high-resolution maps, comprehensive statistical summaries, and spatial decision-support data. --- 1. System Requirements & DependenciesThe code is written in Python 3.9+ and requires the following libraries. It is highly recommended to use a virtual environment (e.g., Conda) to manage dependencies:- Climate & Geospatial Processing: `xarray`, `rioxarray`, `rasterio`, `geopandas`- Numerical & Data Manipulation: `numpy`, `pandas`, `scipy`- Financial Modeling: `numpy_financial`- Visualization: `matplotlib` (configured for high-resolution 600 DPI outputs)- Utilities: `tqdm` (for progress bars), `openpyxl` (for Excel exports), `pickle`, `gzip`, `hashlib` (for caching). --- 2. Input Data RequirementsThe pipeline requires the following datasets, which must be placed in the directories specified in the `CONFIG` section at the top of the script: 1. ERA5-Land Reanalysis Data (NetCDF format): - SSRD (Surface Solar Radiation Downwards): Hourly accumulated radiation (J/m²). - T2M (2-meter Air Temperature): Hourly temperature (K). - Format: Files should be named systematically (e.g., `era5_land_YYYY_MM.nc`) to allow the script to match SSRD and T2M files based on the year and month extracted via regular expressions.2. Administrative Boundary: - A Shapefile (`.shp`) defining the national borders of Iran (EPSG:4326). Used for masking the ERA5-Land grid and clipping the final maps.3. Topographic Data (GeoTIFF): - DEM (Digital Elevation Model), Slope (degrees), and Aspect (0–360°). The script reprojects these to EPSG:4326 and clips them to the Iran boundary.4. Land Cover Data (GeoTIFF): - ESA WorldCover 2021 (10m resolution), providing 11 land cover classes. Used to determine usable land fractions.5. City Locations (KML): - A folder containing KML files with placemarks for Iranian cities. Used to calculate the nearest-city distance using a KD-Tree algorithm. --- 3. Detailed Computational Logic & Pipeline Phases Phase 1: Data Acquisition & Preprocessing- De-accumulation: ERA5-Land SSRD is accumulated from 00:00 UTC. The script calculates the hourly difference: `SSRD(t) - SSRD(t-1)`. Negative differences (due to the daily reset) are floored at zero, and values are divided by 3600 to convert to W/m².- Night Masking: A dynamic sinusoidal mask is applied based on the month and hour to remove non-physical positive radiation values that occur during nighttime.- Physical Filter: Values exceeding 1500 W/m² are capped, and negative values are zeroed.- Thermal Derating: If T2M is available, the module temperature is calculated as `T_module = T_2m + 25°C`. The derating factor is `f_T = 1 + (-0.004) * (T_module - 25)`, clipped between 0.70 and 1.05. If T2M is missing, a default factor of 0.90 is applied. Phase 2: PV Energy Potential (Three Tiers)The script computes PV power density (`P_PV = G * 0.21 * (1-0.14) * 0.86 * f_T`) and explicitly distinguishes three tiers:- Tier 1 (Theoretical Incident): Total solar energy hitting the ground (calculated for all 28,564 valid ERA5-Land grid cells, each 121 km²).- Tier 2 (Technical Convertible): Electricity generated assuming 100% panel coverage on all grid cells (an unattainable upper bound).- Tier 3 (Economically Exploitable): Panel counts are constrained by land cover (e.g., bare land: 15%, shrubland: 12%, cropland: 5%) and slope (e.g., <2°: 100%, >15°: 0%). The maximum installable panels per cell are calculated, and capacity is reported both theoretically (100% of usable land) and realistically (using the Iranian documented land requirement of 1.5 ha/MW). Phase 3: Economic Analysis- Contractual Scenarios: Three 20-year scenarios are modeled: Article 61 (2,850 Toman/kWh), Green Board (7,000 Toman/kWh), and Article 12 (0.10 USD/kWh at 85,000 Toman/USD).- Financial Structure: - CAPEX: 300 USD/kW + fixed land/grid costs. - Financing: 70% debt at 15% interest over 7 years, 30% equity. - O&M: 1.0–1.2% of CAPEX. - Taxes: 25% corporate tax rate. - Degradation: 0.5% annual module degradation. - Inflation: Dynamic cumulative inflation based on Central Bank of Iran historical data (1950–2025), capped at 15%.- Metrics: Net Present Value (NPV), Internal Rate of Return (IRR) via robust bisection, Simple Payback Period, and Levelized Cost of Energy (LCOE on levered cash flows).- Break-even Analysis: Determines the minimum number of panels required for NPV = 0 using a binary search algorithm.- Monte Carlo Simulation: 1,000 iterations per scenario, randomly sampling CAPEX (±15%), Tariff (±10%), and Discount Rate (±20%) to quantify uncertainty.- Government Support Packages: Evaluates five policy interventions: - P0: Baseline (no support). - P1: Tax credit (25% → 10%). - P2: Tax credit + Free land + Concessional debt (10%). - P3: P2 + 20% Tariff premium (FiT guarantee). - P4: Full package (Tax 5%, Free land, 30% FiT, 50% insurance subsidy, 8% debt). Phase 4: MCDM Site Ranking- Criteria (7): AEP, Land Cover, Elevation (Gaussian regional optimums), Slope (Sigmoid centered at 8°), Aspect (Cosine-squared for South), City Distance (Inverse decay), and Economics (N_max).- Weight Combination: The final weight is a blend of three independent sets: - 35% Expert weights (Table 2 of the paper). - 35% Economic weights (absolute correlation with N_max). - 30% Entropy weights (Shannon entropy of the normalized score matrix).- Sensitivity & Optimization: - Perturbs each criterion's weight (0.5x to 2.0x) to test the stability of the Top-10 ranking. - Performs a greedy optimization to find the weight distribution that maximizes the sum of NPV for the Top-50 cells. --- 4. Detailed Output DescriptionThe pipeline generates a rich set of outputs in the `OUTPUT_DIR` and `ANALYSIS_OUTPUT_DIR`: Excel Workbooks- `complete_grid.xlsx`: - All_Grids: Lat, Lon, SSRD, PV power, AEP, DEM, Slope, Aspect, Land Cover, Distance to city, N_max, Theoretical Capacity (MW), Realistic Capacity (MW). - Buildable_Only: Filtered to exclude restricted land covers. - Summary: National totals for theoretical vs. realistic capacity.- `potential_economics.xlsx`: Separate sheets for each scenario (Article 61, Green Board, Article 12) containing NPV, IRR, LCOE, Payback, CAPEX, and Break-even panel counts.- `mcdm_pooled.xlsx` & `mcdm_per_scenario.xlsx`: Ranked candidate sites with individual criterion scores, final MCDM score, and all economic metrics.- `government_packages.xlsx`: The best NPV and number of viable cells for P0–P4 across all scenarios.- `weight_sensitivity_detailed.xlsx`: Rank changes for the top 5 cells when each weight is perturbed. Figures (High-Resolution PNG & SVG)- `Figure_1_potential_3panel`: Monthly SSRD, Incident vs. Convertible energy, and Cumulative energy over 1950–2025.- `figure_2_temporal_4panel`: Diurnal cycle, Annual cycle, Seasonal bars, and Decadal trend.- `stability_plot`: Annual mean SSRD with Mann-Kendall trend and Sen's slope.- `map_01_aep` & `map_02_ssrd`: Professional spatial maps with compass roses and scale bars.- `map_03_mcdm` & `combined_3maps`: Spatial distribution of the final MCDM scores and top-ranked candidate sites.- `scenario_comparison_econ` & `scenario_comparison_breakeven`: Bar charts and scatter plots comparing NPV, IRR, Payback, and Break-even across scenarios.- `monte_carlo_3x3_combined`: 9-panel histograms (a–i) showing the P5, P50, and P95 percentiles for NPV, IRR, and LCOE under uncertainty.- `weight_sensitivity_topN_heatmap` & `weight_optimization_chart`: Visualizations of the MCDM robustness and NPV-maximizing weights. --- 5. Reusability, Applications, and ExtensibilityThis code is highly modular and can be adapted for various research and policy applications:- Regional Scalability: The code is not hard-coded to Iran. By replacing the `SHAPEFILE_PATH` and adjusting the ERA5-Land file paths, the entire pipeline (from data processing to MCDM and economics) can be run for any country, continent, or custom region.- Alternative Datasets: The `read_nc_file` and preprocessing functions can be modified to ingest NASA POWER, MERRA-2, or satellite-derived data (e.g., CAMS).- Policy Analysis: The economic module (including the 5 government packages and Monte Carlo) can be used to simulate the impact of new subsidies, tax reforms, or feed-in tariffs on renewable investments.- Technology Adaptation: While designed for PV, the core MCDM and economic logic (with minor parameter changes) can be applied to Concentrated Solar Power (CSP), wind farms, or hybrid systems.- Educational Use: The code serves as a comprehensive template for teaching advanced geospatial data analysis, financial modeling, and multi-criteria decision-making in Python. --- 6. Reproducibility & PerformanceProcessing 76 years of hourly ERA5-Land data requires significant computational resources (RAM and CPU). To ensure reproducibility without re-running the massive data extraction every time, the script uses:- Caching (`cache_result`): Hashes function inputs and saves the outputs as `.pkl.gz` files.- Checkpointing (`save_checkpoint`): Saves the progress of the ERA5-Land extraction every 10 files. If the script is interrupted, it resumes from the last checkpoint.- Test Mode: Setting `TEST_MODE = True` in the `main()` function restricts the analysis to the year 1950, allowing users to test the pipeline quickly before committing to the full 76-year run.