site-calc-investment 1.2.0__py3-none-any.whl

site_calc_investment/__init__.py

@@ -0,0 +1,100 @@
+"""Site-Calc Investment Client
+
+Python client for long-term capacity planning and investment ROI analysis.
+"""
+
+__version__ = "1.2.0"
+
+from site_calc_investment.analysis import (
+    aggregate_annual,
+    calculate_irr,
+    calculate_npv,
+    calculate_payback_period,
+    compare_scenarios,
+)
+from site_calc_investment.api.client import InvestmentClient
+from site_calc_investment.exceptions import (
+    ApiError,
+    AuthenticationError,
+    ForbiddenFeatureError,
+    JobNotFoundError,
+    LimitExceededError,
+    OptimizationError,
+    SiteCalcError,
+    TimeoutError,
+    ValidationError,
+)
+from site_calc_investment.models import (
+    CHP,
+    # Device models (NO ancillary_services)
+    Battery,
+    ElectricityDemand,
+    ElectricityExport,
+    ElectricityImport,
+    GasImport,
+    HeatAccumulator,
+    HeatDemand,
+    HeatExport,
+    InvestmentMetrics,
+    InvestmentParameters,
+    # Request models
+    InvestmentPlanningRequest,
+    InvestmentPlanningResponse,
+    # Response models
+    Job,
+    Location,
+    OptimizationConfig,
+    Photovoltaic,
+    Resolution,
+    Schedule,
+    # Site and configuration
+    Site,
+    # Core models
+    TimeSpan,
+)
+
+__all__ = [
+    # Client
+    "InvestmentClient",
+    # Core
+    "TimeSpan",
+    "Resolution",
+    "Location",
+    # Devices
+    "Battery",
+    "CHP",
+    "HeatAccumulator",
+    "Photovoltaic",
+    "HeatDemand",
+    "ElectricityDemand",
+    "ElectricityImport",
+    "ElectricityExport",
+    "GasImport",
+    "HeatExport",
+    # Configuration
+    "Site",
+    "Schedule",
+    "InvestmentParameters",
+    "OptimizationConfig",
+    # Requests/Responses
+    "InvestmentPlanningRequest",
+    "Job",
+    "InvestmentPlanningResponse",
+    "InvestmentMetrics",
+    # Analysis
+    "calculate_npv",
+    "calculate_irr",
+    "calculate_payback_period",
+    "aggregate_annual",
+    "compare_scenarios",
+    # Exceptions
+    "SiteCalcError",
+    "ApiError",
+    "ValidationError",
+    "AuthenticationError",
+    "ForbiddenFeatureError",
+    "LimitExceededError",
+    "TimeoutError",
+    "OptimizationError",
+    "JobNotFoundError",
+]

site_calc_investment/analysis/__init__.py

@@ -0,0 +1,17 @@
+"""Financial analysis helpers for investment planning."""
+
+from site_calc_investment.analysis.comparison import compare_scenarios
+from site_calc_investment.analysis.financial import (
+    aggregate_annual,
+    calculate_irr,
+    calculate_npv,
+    calculate_payback_period,
+)
+
+__all__ = [
+    "calculate_npv",
+    "calculate_irr",
+    "calculate_payback_period",
+    "aggregate_annual",
+    "compare_scenarios",
+]

site_calc_investment/analysis/comparison.py

@@ -0,0 +1,121 @@
+"""Scenario comparison utilities."""
+
+from typing import Any, Dict, List, Optional
+
+from site_calc_investment.models.responses import InvestmentPlanningResponse
+
+
+def compare_scenarios(
+    scenarios: List[InvestmentPlanningResponse],
+    names: Optional[List[str]] = None,
+) -> Dict[str, Any]:
+    """Compare multiple optimization scenarios.
+
+    Extracts key metrics from each scenario for easy comparison.
+
+    Args:
+        scenarios: List of optimization results
+        names: Optional names for each scenario (default: "Scenario 1", "Scenario 2", ...)
+
+    Returns:
+        Dictionary with comparison data suitable for printing or DataFrame conversion
+
+    Example:
+        >>> results = [result_5mw, result_10mw, result_15mw]
+        >>> comparison = compare_scenarios(results, names=["5 MW", "10 MW", "15 MW"])
+        >>> for name, metrics in zip(comparison["names"], comparison["npv"]):
+        ...     print(f"{name}: NPV = €{metrics:,.0f}")
+        5 MW: NPV = €1,250,000
+        10 MW: NPV = €1,850,000
+        15 MW: NPV = €1,600,000
+    """
+    if not scenarios:
+        raise ValueError("At least one scenario is required")
+
+    if names is None:
+        names = [f"Scenario {i + 1}" for i in range(len(scenarios))]
+
+    if len(names) != len(scenarios):
+        raise ValueError(f"Number of names ({len(names)}) must match number of scenarios ({len(scenarios)})")
+
+    comparison: Dict[str, Any] = {
+        "names": names,
+        "total_revenue": [],
+        "total_costs": [],
+        "profit": [],
+        "npv": [],
+        "irr": [],
+        "payback_years": [],
+        "solve_time_seconds": [],
+        "solver_status": [],
+    }
+
+    for scenario in scenarios:
+        summary = scenario.summary
+        inv_metrics = scenario.investment_metrics
+
+        # Calculate total revenue - use investment metrics if available
+        if inv_metrics and inv_metrics.total_revenue_10y is not None:
+            total_revenue = inv_metrics.total_revenue_10y
+        else:
+            # Fallback: calculate from profit + cost
+            profit = summary.expected_profit or 0.0
+            cost = summary.total_cost or 0.0
+            total_revenue = profit + cost
+
+        comparison["total_revenue"].append(total_revenue)
+        comparison["total_costs"].append(summary.total_cost)
+        comparison["profit"].append(summary.expected_profit)
+        comparison["npv"].append(inv_metrics.npv if inv_metrics else None)
+        comparison["irr"].append(inv_metrics.irr if inv_metrics else None)
+        comparison["payback_years"].append(inv_metrics.payback_period_years if inv_metrics else None)
+        comparison["solve_time_seconds"].append(summary.solve_time_seconds)
+        comparison["solver_status"].append(summary.solver_status)
+
+    return comparison
+
+
+def print_comparison(comparison: dict) -> None:
+    """Print scenario comparison in a readable format.
+
+    Args:
+        comparison: Comparison dictionary from compare_scenarios()
+
+    Example:
+        >>> comparison = compare_scenarios([result1, result2, result3], names=["Small", "Medium", "Large"])
+        >>> print_comparison(comparison)
+        === Scenario Comparison ===
+        ...
+    """
+    print("=" * 80)
+    print("SCENARIO COMPARISON")
+    print("=" * 80)
+
+    for i, name in enumerate(comparison["names"]):
+        print(f"\n{name}:")
+        print(f"  Total Revenue:   €{comparison['total_revenue'][i]:>15,.0f}")
+        print(f"  Total Costs:     €{comparison['total_costs'][i]:>15,.0f}")
+        print(f"  Profit:          €{comparison['profit'][i]:>15,.0f}")
+
+        if comparison["npv"][i] is not None:
+            print(f"  NPV:             €{comparison['npv'][i]:>15,.0f}")
+
+        if comparison["irr"][i] is not None:
+            print(f"  IRR:              {comparison['irr'][i] * 100:>15.2f}%")
+
+        if comparison["payback_years"][i] is not None:
+            print(f"  Payback:          {comparison['payback_years'][i]:>15.1f} years")
+
+        print(f"  Solve Time:       {comparison['solve_time_seconds'][i]:>15.1f}s")
+        print(f"  Solver Status:    {comparison['solver_status'][i]:>15}")
+
+    print("\n" + "=" * 80)
+
+    # Find best scenario by NPV
+    npv_values = [v for v in comparison["npv"] if v is not None]
+    if npv_values:
+        best_idx = comparison["npv"].index(max(npv_values))
+        print(f"\nBest Scenario (by NPV): {comparison['names'][best_idx]}")
+        print(f"NPV: €{comparison['npv'][best_idx]:,.0f}")
+
+    print("=" * 80)

site_calc_investment/analysis/financial.py

@@ -0,0 +1,202 @@
+"""Financial analysis functions."""
+
+from typing import List, Optional
+
+
+def calculate_npv(
+    cash_flows: List[float],
+    discount_rate: float,
+    initial_investment: float = 0,
+) -> float:
+    """Calculate Net Present Value.
+
+    NPV = Sum of (cash_flow_t / (1 + discount_rate)^t) + initial_investment
+
+    Args:
+        cash_flows: Annual cash flows (revenues - costs)
+        discount_rate: Discount rate (e.g., 0.05 for 5%)
+        initial_investment: Initial investment (negative for CAPEX, default: 0)
+
+    Returns:
+        Net present value in same currency as cash flows
+
+    Example:
+        >>> cash_flows = [100000, 105000, 110000, 115000, 120000]
+        >>> npv = calculate_npv(cash_flows, 0.05, initial_investment=-500000)
+        >>> print(f"NPV: €{npv:,.0f}")
+        NPV: €-23,162
+    """
+    npv = initial_investment
+
+    for t, cash_flow in enumerate(cash_flows, start=1):
+        npv += cash_flow / ((1 + discount_rate) ** t)
+
+    return npv
+
+
+def calculate_irr(cash_flows: List[float], initial_guess: float = 0.1) -> Optional[float]:
+    """Calculate Internal Rate of Return.
+
+    IRR is the discount rate that makes NPV = 0.
+    Uses Newton-Raphson method for root finding.
+
+    Args:
+        cash_flows: Annual cash flows INCLUDING initial investment as first element
+                   (e.g., [-500000, 100000, 105000, ...])
+        initial_guess: Starting guess for IRR (default: 0.1 = 10%)
+
+    Returns:
+        Internal rate of return as fraction (e.g., 0.12 = 12%), or None if no solution
+
+    Example:
+        >>> cash_flows = [-500000, 100000, 105000, 110000, 115000, 120000]
+        >>> irr = calculate_irr(cash_flows)
+        >>> if irr:
+        ...     print(f"IRR: {irr*100:.2f}%")
+        IRR: 8.52%
+    """
+    if len(cash_flows) < 2:
+        return None
+
+    # numpy.irr was removed in numpy 1.20+, use Newton-Raphson directly
+    return _irr_newton_raphson(cash_flows, initial_guess)
+
+
+def _irr_newton_raphson(cash_flows: List[float], initial_guess: float, max_iterations: int = 100) -> Optional[float]:
+    """Calculate IRR using Newton-Raphson method.
+
+    Args:
+        cash_flows: Cash flows with initial investment as first element
+        initial_guess: Starting guess
+        max_iterations: Maximum iterations
+
+    Returns:
+        IRR or None if no convergence
+    """
+    rate = initial_guess
+    tolerance = 1e-6
+
+    for _ in range(max_iterations):
+        # Calculate NPV and derivative
+        npv: float = 0.0
+        npv_derivative: float = 0.0
+
+        for t, cash_flow in enumerate(cash_flows):
+            discount_factor = (1 + rate) ** t
+            npv += cash_flow / discount_factor
+            if t > 0:
+                npv_derivative -= t * cash_flow / ((1 + rate) ** (t + 1))
+
+        # Check convergence
+        if abs(npv) < tolerance:
+            return rate
+
+        # Newton-Raphson update
+        if abs(npv_derivative) < tolerance:
+            return None  # Derivative too small
+
+        rate = rate - npv / npv_derivative
+
+        # Check for reasonable range
+        if rate < -0.99 or rate > 10:  # -99% to 1000%
+            return None
+
+    return None  # No convergence
+
+
+def calculate_payback_period(cash_flows: List[float]) -> Optional[float]:
+    """Calculate simple payback period.
+
+    Payback period is the time it takes for cumulative cash flows
+    to become positive (recover initial investment).
+
+    Args:
+        cash_flows: Annual cash flows INCLUDING initial investment as first element
+                   (e.g., [-500000, 100000, 105000, ...])
+
+    Returns:
+        Payback period in years (fractional), or None if never pays back
+
+    Example:
+        >>> cash_flows = [-500000, 100000, 120000, 140000, 160000]
+        >>> payback = calculate_payback_period(cash_flows)
+        >>> print(f"Payback: {payback:.1f} years")
+        Payback: 3.6 years
+    """
+    if len(cash_flows) < 2:
+        return None
+
+    cumulative: float = 0.0
+    for year, cash_flow in enumerate(cash_flows):
+        cumulative += cash_flow
+
+        if cumulative >= 0:
+            # Interpolate within the year
+            if year == 0:
+                return 0.0
+
+            # How much was needed at start of this year
+            prev_cumulative = cumulative - cash_flow
+
+            # Fraction of year needed
+            fraction = -prev_cumulative / cash_flow
+
+            # Return year - 1 + fraction because year 0 is initial investment
+            return (year - 1) + fraction
+
+    return None  # Never pays back
+
+
+def aggregate_annual(
+    hourly_values: List[float],
+    prices: Optional[List[float]] = None,
+    years: int = 1,
+) -> List[float]:
+    """Aggregate hourly values into annual totals.
+
+    If prices are provided, calculates annual revenue.
+    Otherwise, calculates annual sum (e.g., energy).
+
+    Args:
+        hourly_values: Hourly power or flow values (MW)
+        prices: Optional hourly prices (EUR/MWh)
+        years: Number of years (for validation)
+
+    Returns:
+        List of annual values (one per year)
+
+    Example:
+        >>> hourly_export = [2.5] * 8760 * 10  # 10 years of constant 2.5 MW
+        >>> prices = [30.0] * 8760 * 10
+        >>> annual_revenues = aggregate_annual(hourly_export, prices, years=10)
+        >>> print(f"Year 1 revenue: €{annual_revenues[0]:,.0f}")
+        Year 1 revenue: €657,000
+    """
+    hours_per_year = 8760
+    expected_length = hours_per_year * years
+
+    if len(hourly_values) != expected_length:
+        raise ValueError(f"Expected {expected_length} hourly values for {years} years, got {len(hourly_values)}")
+
+    if prices is not None and len(prices) != expected_length:
+        raise ValueError(f"Prices length {len(prices)} doesn't match hourly_values length {len(hourly_values)}")
+
+    annual_values = []
+
+    for year in range(years):
+        start_idx = year * hours_per_year
+        end_idx = (year + 1) * hours_per_year
+
+        year_values = hourly_values[start_idx:end_idx]
+
+        if prices is not None:
+            year_prices = prices[start_idx:end_idx]
+            # Revenue = sum(MW * hours * EUR/MWh) = sum(MW * EUR/MWh) for 1-hour intervals
+            annual_value = sum(v * p for v, p in zip(year_values, year_prices))
+        else:
+            # Just sum the values
+            annual_value = sum(year_values)
+
+        annual_values.append(annual_value)
+
+    return annual_values

site_calc_investment/api/__init__.py

@@ -0,0 +1,5 @@
+"""API client for investment optimization."""
+
+from site_calc_investment.api.client import InvestmentClient
+
+__all__ = ["InvestmentClient"]