Skip to main content

API Reference

Public interfaces commonly used by developers.

Core​

pv_tools/optimiser.py​

  • main(c: Dict, log_file: Optional[str] = None, typical_consumption: Optional[List[float]] = None) -> List[float]

    • Estimate a typical 24h consumption profile (kW) from billing if not provided.

  • optimise(c: Dict, typical_consumption: List[float]) -> Tuple[Dict, Dict]

    • Run the selected financing optimizer and compute results (system size, savings/ROI, ESG, etc.). Returns (results, updated_config).

pv_tools/production_modeling.py​

  • modelSetup(c: Dict) -> Dict

    • Load tariffs/prices/ESG/inverters/CT rating, resolve latitude/longitude, handle SELCO export rate; returns enhanced config.

  • historical_monthly_avg(c: Dict) -> pd.DataFrame

    • Monthly production per kWp with uncertainty bounds (scaled by parameters.efficiency_scaling).
    • Columns: month, mean, low_bound, upp_bound.

  • historical_hourly_power(c: Dict) -> pd.DataFrame

    • Hourly PV production and metadata from PVGIS; columns include time, P (kW/kWp), year, month, day, …

  • power_and_energy(c: Dict, daily_consumption: ArrayLike, original_data: Optional[pd.DataFrame] = None) -> Tuple[pd.DataFrame, float, pd.DataFrame]

    • Core energy/billing aggregation:
      • Computes hourly net power_delta, optional BESS sizing/simulation, and monthly aggregates.
      • Returns (monthly_data, storage_size_kWh, original_hourly_df).
    • monthly_data includes E_consumed, E_produced, E_grid_draw, exported_kWh, export_credit_RM, bill_excluding_solar, bill_without_solar, bill_equivalent_solar, peak_sun_hours, etc.

Utilities​

pv_tools/utilities/technical.py​

  • calculate_bill(c: Dict, tariff_category: str, total_consumption: float, peak_power_demand: Optional[float] = None, peak_fraction: Optional[float] = None) -> float

    • TNB bill including ICPT and KWTBB. Handles negative consumption (export via SMP_export.rate).

  • solve_pre_surcharge_bill(c: Dict, tariff_category: str, final_bill: float, peak_power_demand: Optional[float] = None, peak_fraction: Optional[float] = None) -> float

    • Reverse bill to monthly kWh, used by main.

  • size_inverters(c: Dict, peak_power_production: float) -> List[float]

    • Selects one or more inverter sizes to meet peak PV AC power.

Additional helpers for CT/fuse and management cost are available in the same module.

pv_tools/utilities/finance.py​

  • calculate_npv(cash_flows: List[float], discount_rate: float) -> float
  • calculate_irr(cash_flows: List[float], guess: float = 0.1) -> float
  • calculate_loan_payment(principal: float, annual_rate: float, years: int) -> float
  • generate_amortization_schedule(...) -> pd.DataFrame

pv_tools/utilities/bess.py​

  • class BatteryModel(capacity_kwh: float, power_rating_kw: float, efficiency: float = 0.90, min_soc: float = 0.2, max_soc: float = 1.0)
    • Methods: charge(power_kw, duration_h), discharge(power_kw, duration_h), get_degradation_factor(), get_effective_capacity()

pv_tools/utilities/processes.py​

  • API and processing helpers (coordinates, PVGIS data, aggregations).

Optimizers​

  • Dynamic import per config:
    • pv_tools.optimizers.{Tokenization|TermLoan}.{PPA|DirectPurchase}
    • Each module exposes a callable with signature: (c: Dict, typical_consumption: List[float]) -> Tuple[Dict, Dict]