Source code for space_pv_pvmodel.topology

"""Array I-V composition with idealized bypass diodes and fault scenarios.

The generating branch is an ideal single-diode characteristic with optional
series resistance and no shunt leakage. Parallel strings have blocking diodes
idealized as zero voltage drop, so reverse current into weak strings is excluded.
This is a bounded circuit-screening model, not an arcing or hot-spot simulation.
"""

from __future__ import annotations

from collections.abc import Sequence
from dataclasses import dataclass
from typing import Literal

import numpy as np
import pandas as pd
from numpy.typing import ArrayLike


[docs] @dataclass(frozen=True) class PVSubstring: """Equivalent generating substring and its bypass branch. ``diode_voltage_v`` is n*N_s*k*T/q. Photocurrent is not exact short-circuit current when a nonzero series resistance is supplied. An ``open`` fault opens the generating branch; a present bypass diode can still carry current. Set ``bypass_voltage_v=None`` for an unbypassed open circuit. A ``short`` faults the entire substring to zero voltage. """ photocurrent_a: float open_circuit_voltage_v: float diode_voltage_v: float = 0.6 series_resistance_ohm: float = 0.0 bypass_voltage_v: float | None = 0.5 fault: Literal["healthy", "open", "short"] = "healthy" def __post_init__(self) -> None: for name in ("photocurrent_a", "open_circuit_voltage_v", "series_resistance_ohm"): value = getattr(self, name) if not np.isfinite(value) or value < 0: raise ValueError(f"{name} must be finite and non-negative") if not np.isfinite(self.diode_voltage_v) or self.diode_voltage_v <= 0: raise ValueError("diode_voltage_v must be finite and positive") if self.open_circuit_voltage_v / self.diode_voltage_v > 700: raise ValueError("open-circuit to diode voltage ratio is numerically unsupported") if self.photocurrent_a > 0 and self.open_circuit_voltage_v == 0: raise ValueError("a generating substring needs a positive open-circuit voltage") if self.photocurrent_a == 0 and self.open_circuit_voltage_v != 0: raise ValueError("a dark substring must have zero open-circuit voltage") if self.bypass_voltage_v is not None and ( not np.isfinite(self.bypass_voltage_v) or self.bypass_voltage_v < 0 ): raise ValueError("bypass_voltage_v must be non-negative or None") if self.fault not in {"healthy", "open", "short"}: raise ValueError("fault must be healthy, open, or short")
def _substring_voltage(component: PVSubstring, current: np.ndarray) -> np.ndarray: if component.fault == "short": return np.zeros_like(current) if component.fault == "open" or component.photocurrent_a == 0: voltage = np.where(current > 0, -np.inf, 0.0) else: saturation = component.photocurrent_a / np.expm1( component.open_circuit_voltage_v / component.diode_voltage_v ) diode_argument = (component.photocurrent_a + saturation - current) / saturation with np.errstate(divide="ignore", invalid="ignore"): voltage = component.diode_voltage_v * np.log(np.maximum(diode_argument, 0.0)) voltage -= current * component.series_resistance_ohm if component.bypass_voltage_v is not None: voltage = np.maximum(voltage, -component.bypass_voltage_v) return voltage
[docs] def array_iv_curve( strings: Sequence[Sequence[PVSubstring]], voltage_v: ArrayLike | None = None, *, points: int = 501, ) -> pd.DataFrame: """Compose series substrings and parallel strings on a common voltage grid. Nonnegative voltage/current represent the generating quadrant. Bypass conduction is a constant voltage-drop approximation. Current is obtained by monotone bisection of each string's voltage-at-current relation. MPP attributes describe the sampled grid, so refine it for an accurate MPP. """ circuits = [list(string) for string in strings] if not circuits or any(not string for string in circuits): raise ValueError("provide at least one nonempty string") if any(not isinstance(cell, PVSubstring) for string in circuits for cell in string): raise TypeError("strings must contain PVSubstring objects") open_voltages = [ sum(cell.open_circuit_voltage_v for cell in string if cell.fault == "healthy") for string in circuits ] if voltage_v is None: if isinstance(points, bool) or int(points) != points or points < 2: raise ValueError("points must be an integer of at least two") voltage = np.linspace(0.0, max(max(open_voltages), 1.0), int(points)) else: voltage = np.asarray(voltage_v, dtype=float) if voltage.ndim != 1 or len(voltage) < 2: raise ValueError("voltage_v must have at least two points") if not np.all(np.isfinite(voltage)) or np.any(voltage < 0): raise ValueError("voltage_v must be finite and non-negative") if np.any(np.diff(voltage) <= 0): raise ValueError("voltage_v must be strictly increasing") string_currents = [] for string, open_voltage in zip(circuits, open_voltages, strict=True): broken = any(cell.fault == "open" and cell.bypass_voltage_v is None for cell in string) max_current = ( max(cell.photocurrent_a for cell in string if cell.fault != "short") if any(cell.fault != "short" for cell in string) else 0.0 ) if broken or max_current == 0 or open_voltage == 0: string_currents.append(np.zeros_like(voltage)) continue low = np.zeros_like(voltage) high = np.full_like(voltage, max_current * (1 + 1e-10)) for _ in range(80): midpoint = (low + high) / 2 available_voltage = sum(_substring_voltage(cell, midpoint) for cell in string) can_supply = available_voltage > voltage low = np.where(can_supply, midpoint, low) high = np.where(can_supply, high, midpoint) current = np.where(voltage >= open_voltage, 0.0, (low + high) / 2) string_currents.append(current) total_current = np.sum(string_currents, axis=0) result = pd.DataFrame({"voltage_v": voltage, "current_a": total_current}) result["power_w"] = voltage * total_current for index, current in enumerate(string_currents): result[f"string_{index}_current_a"] = current optimum = int(np.argmax(result["power_w"].to_numpy())) result.attrs.update( pmp_w=float(result["power_w"].iloc[optimum]), vmp_v=float(voltage[optimum]), imp_a=float(total_current[optimum]), model="ideal diode, series resistance, constant-drop bypass, ideal string blocking", ) return result