solar_panel_yield_2026 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4ec088af1f46477feb41662dbf9fbc93d19e3bfd6701f7850654ea4cf8e4958b
+  data.tar.gz: a833f25cd886c69215697f8f91ac9cd24ef589169d6ade3638648bf326ecb5e8
+SHA512:
+  metadata.gz: a9f8d9609cffa9efa6c7ac39d481728db88717ff3621816d077b294e9f9f97ba08bfe0b129fc04375d4bb5a566f028ef5d4f235002ef37d30181928df0d302f8
+  data.tar.gz: ecc290c8b4a6422deb08c65b358ea7cba449a94e6155fec0ba957ad150b756521111bcb8a1d1840624e3f49cce63a8fbe93723701e2b860348ca3d7c4ff29912

data/README.md

@@ -0,0 +1,23 @@
+# solar_panel_yield_2026 (Ruby)
+
+Ruby port of the Solar Panel Cleaning Yield Recovery reference engine.
+See the project root README for full documentation and the working paper.
+
+```ruby
+require "solar_panel_yield_2026"
+
+result = SolarPanelYield2026.calculate(
+  system_capacity_kwp: 5.0,
+  ghi_annual_avg: 3.54,
+  days_since_cleaning: 30,
+  soil_class: "medium",
+  climate_zone: "temperate",
+  panel_tilt_deg: 15,
+  electricity_price_cad_per_kwh: 0.14,
+  cleaning_visit_cost_cad: 120.0,
+  tap_water_tds_ppm: 180,
+  panel_height_ft: 12.0
+)
+```
+
+License: MIT.

data/lib/solar_panel_yield_2026.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+# Solar Panel Cleaning Yield Recovery -- Ruby reference engine.
+# Hand-port of the Python reference engine. See the project repository for
+# the full working paper and companion datasets.
+module SolarPanelYield2026
+  VERSION = "0.1.0"
+
+  CLIMATE_RATE = {
+    "arid" => 0.30,
+    "temperate" => 0.18,
+    "humid" => 0.12,
+    "cold_snow" => 0.20,
+  }.freeze
+
+  TILT_MULT = { 5 => 1.15, 15 => 1.00, 25 => 0.88, 35 => 0.80, 45 => 0.74 }.freeze
+  SOIL_MULT = { "low" => 0.60, "medium" => 1.00, "high" => 1.55 }.freeze
+
+  CEILING_BASE = 12.0
+  DEFAULT_PR = 0.80
+  RESIN_CAPACITY_CONST = 17118.0
+  RO_THRESHOLD_PPM = 250.0
+
+  STANDARD_POLE_FT = [8, 10, 15, 20, 25, 30, 35, 40, 45].freeze
+  CARTRIDGES = [
+    ["1L_cartridge",  0.80],
+    ["3L_cartridge",  2.40],
+    ["7L_cartridge",  5.60],
+    ["14L_tank",     11.20],
+    ["28L_tank",     22.40],
+  ].freeze
+
+  INTERVALS = [7, 14, 21, 30, 45, 60, 75, 90, 120, 150, 180, 240, 300, 365].freeze
+
+  DISCLAIMER = "This reference model is not professional engineering advice. " \
+    "Site-specific cleaning decisions should consult module warranty requirements, " \
+    "site fall-protection plans, and a qualified PV operations and maintenance provider."
+
+  module_function
+
+  def daily_rate(zone, tilt_deg, soil_class)
+    raise ArgumentError, "invalid climate_zone" unless CLIMATE_RATE.key?(zone)
+    raise ArgumentError, "invalid soil_class"  unless SOIL_MULT.key?(soil_class)
+    tilt_key = TILT_MULT.keys.min_by { |k| (k - tilt_deg).abs }
+    CLIMATE_RATE[zone] * TILT_MULT[tilt_key] * SOIL_MULT[soil_class]
+  end
+
+  def ceiling(soil_class)
+    raise ArgumentError, "invalid soil_class" unless SOIL_MULT.key?(soil_class)
+    CEILING_BASE * SOIL_MULT[soil_class]
+  end
+
+  def current_loss_pct(days, daily, ceiling)
+    return 0.0 if daily <= 0 || days <= 0 || ceiling <= 0
+    ceiling * (1.0 - Math.exp(-daily * days / ceiling))
+  end
+
+  def average_loss_pct(interval_days, daily, ceiling)
+    return 0.0 if daily <= 0 || interval_days <= 0 || ceiling <= 0
+    k_over_c = daily / ceiling
+    ceiling * (1.0 - (1.0 - Math.exp(-k_over_c * interval_days)) / (k_over_c * interval_days))
+  end
+
+  def clean_annual_kwh(kwp, ghi, pr)
+    kwp * ghi * 365.0 * pr
+  end
+
+  def recommend_pole_length_ft(panel_height_ft)
+    needed = [8.0, panel_height_ft + 3.0 - 5.0].max
+    STANDARD_POLE_FT.each { |len| return len if len >= needed }
+    STANDARD_POLE_FT.last
+  end
+
+  def recommend_cartridge(inlet_tds_ppm, panels_estimated)
+    ro_pre = inlet_tds_ppm > RO_THRESHOLD_PPM
+    effective_tds = ro_pre ? 15.0 : inlet_tds_ppm.to_f
+    gallons_per_cleaning = panels_estimated / 3.78541
+    target_gal = [gallons_per_cleaning * 2.0, 50.0].max
+    CARTRIDGES.each do |name, kgr|
+      capacity = (kgr * RESIN_CAPACITY_CONST) / [effective_tds, 1.0].max
+      return [name, ro_pre] if capacity >= target_gal
+    end
+    [CARTRIDGES.last[0], ro_pre]
+  end
+
+  def calculate(req)
+    r = {
+      system_capacity_kwp: req[:system_capacity_kwp],
+      ghi_annual_avg: req[:ghi_annual_avg],
+      days_since_cleaning: req[:days_since_cleaning],
+      soil_class: req[:soil_class] || "medium",
+      climate_zone: req[:climate_zone] || "temperate",
+      panel_tilt_deg: req[:panel_tilt_deg] || 15,
+      electricity_price_cad_per_kwh: req[:electricity_price_cad_per_kwh] || 0.14,
+      cleaning_visit_cost_cad: req[:cleaning_visit_cost_cad] || 120.0,
+      tap_water_tds_ppm: req[:tap_water_tds_ppm] || 160,
+      panel_height_ft: req[:panel_height_ft] || 12.0,
+      performance_ratio: req[:performance_ratio] || DEFAULT_PR,
+    }
+
+    raise ArgumentError, "system_capacity_kwp must be in (0, 10000]" \
+      if r[:system_capacity_kwp] <= 0 || r[:system_capacity_kwp] > 10000
+    raise ArgumentError, "ghi_annual_avg must be in (0, 10]" \
+      if r[:ghi_annual_avg] <= 0 || r[:ghi_annual_avg] > 10
+    raise ArgumentError, "days_since_cleaning out of range" \
+      if r[:days_since_cleaning] < 0 || r[:days_since_cleaning] > 3650
+
+    daily = daily_rate(r[:climate_zone], r[:panel_tilt_deg], r[:soil_class])
+    ceil = ceiling(r[:soil_class])
+    variability = Math.sqrt(0.15**2 + 0.10**2)
+
+    loss_pct = current_loss_pct(r[:days_since_cleaning], daily, ceil)
+    loss_range = { low: loss_pct * (1 - variability), expected: loss_pct, high: loss_pct * (1 + variability) }
+
+    annual_kwh = clean_annual_kwh(r[:system_capacity_kwp], r[:ghi_annual_avg], r[:performance_ratio])
+    lost_cad_per_day = (annual_kwh / 365.0) * (loss_pct / 100.0) * r[:electricity_price_cad_per_kwh]
+    lost_range = {
+      low: lost_cad_per_day * (1 - variability),
+      expected: lost_cad_per_day,
+      high: lost_cad_per_day * (1 + variability),
+    }
+
+    never_clean_loss_cad = annual_kwh * (ceil / 100.0) * r[:electricity_price_cad_per_kwh]
+
+    best_t = 365
+    best_net = -Float::INFINITY
+    INTERVALS.each do |t|
+      avg_loss = average_loss_pct(t, daily, ceil)
+      lost_cad_t = annual_kwh * (avg_loss / 100.0) * r[:electricity_price_cad_per_kwh]
+      avoided = never_clean_loss_cad - lost_cad_t
+      annual_clean_cost = (365.0 / t) * r[:cleaning_visit_cost_cad]
+      net = avoided - annual_clean_cost
+      if net > best_net
+        best_net = net
+        best_t = t
+      end
+    end
+
+    optimal_range = { low: [7, (best_t * 0.8).to_i].max.to_f, expected: best_t.to_f, high: [365, (best_t * 1.2).to_i].min.to_f }
+    recovered_range = if best_net >= 0
+      { low: best_net * (1 - variability), expected: best_net, high: best_net * (1 + variability) }
+    else
+      { low: best_net * (1 + variability), expected: best_net, high: best_net * (1 - variability) }
+    end
+
+    panels_estimated = [1.0, r[:system_capacity_kwp] / 0.33].max
+    pole_ft = recommend_pole_length_ft(r[:panel_height_ft])
+    cartridge, ro_pre = recommend_cartridge(r[:tap_water_tds_ppm], panels_estimated)
+    water_per_cleaning_l = panels_estimated * 1.0
+
+    {
+      current_loss_pct: loss_range,
+      lost_cad_per_day: lost_range,
+      optimal_interval_days: optimal_range,
+      annual_recovered_cad: recovered_range,
+      wfp_pole_ft: pole_ft,
+      wfp_cartridge: cartridge,
+      water_per_cleaning_l: (water_per_cleaning_l * 10).round / 10.0,
+      ro_prestage_recommended: ro_pre,
+      clean_annual_kwh: (annual_kwh * 10).round / 10.0,
+      never_clean_annual_loss_cad: (never_clean_loss_cad * 100).round / 100.0,
+      daily_rate_pct_per_day: (daily * 10000).round / 10000.0,
+      ceiling_pct: (ceil * 100).round / 100.0,
+      disclaimer: DISCLAIMER,
+      version: VERSION,
+    }
+  end
+
+  def canonical_vector
+    {
+      system_capacity_kwp: 5.0,
+      ghi_annual_avg: 3.54,
+      days_since_cleaning: 30,
+      soil_class: "medium",
+      climate_zone: "temperate",
+      panel_tilt_deg: 15,
+      electricity_price_cad_per_kwh: 0.14,
+      cleaning_visit_cost_cad: 120.0,
+      tap_water_tds_ppm: 180,
+      panel_height_ft: 12.0,
+      performance_ratio: DEFAULT_PR,
+    }
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  require "json"
+  puts JSON.pretty_generate(SolarPanelYield2026.calculate(SolarPanelYield2026.canonical_vector))
+end

metadata

@@ -0,0 +1,43 @@
+--- !ruby/object:Gem::Specification
+name: solar_panel_yield_2026
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Dave Cook
+bindir: bin
+cert_chain: []
+date: 2026-04-12 00:00:00.000000000 Z
+dependencies: []
+description: Ruby port of the Solar Panel Cleaning Yield Recovery reference engine.
+email:
+- dave@binx.ca
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/solar_panel_yield_2026.rb
+homepage: https://github.com/DaveCookVectorLabs/solar_panel_yield_2026
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/DaveCookVectorLabs/solar_panel_yield_2026
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.3
+specification_version: 4
+summary: Reference calculator for PV soiling loss and water-fed pole cleaning ROI.
+test_files: []