site-calc-investment 1.2.0__tar.gz → 1.2.1__tar.gz

{site_calc_investment-1.2.0 → site_calc_investment-1.2.1}/CHANGELOG.md

@@ -5,6 +5,19 @@ All notable changes to the Site-Calc Investment Client will be documented in thi
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1] - 2026-02-03
+
+### Fixed
+- **README Quick Start**: Fixed example code to use correct model classes and valid parameter values
+  - Use `TimeSpanInvestment` instead of `TimeSpan`
+  - Use valid `objective` values (`maximize_profit`, `minimize_cost`, `maximize_self_consumption`)
+  - Add required `project_lifetime_years` to `InvestmentParameters`
+  - Fix `time_limit_seconds` max value (900, not 3600)
+- **Capabilities table**: Corrected timeout from "3600 seconds" to "900 seconds (15 minutes) max"
+- **QUICK_START.md**: Added `pypi` environment name for Trusted Publishing setup
+
+---
+
 ## [1.2.0] - 2026-02-03
 
 ### Changed

{site_calc_investment-1.2.0 → site_calc_investment-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: site-calc-investment
-Version: 1.2.0
+Version: 1.2.1
 Summary: Python client for Site-Calc investment planning (capacity sizing, ROI analysis)
 Project-URL: Homepage, https://github.com/stranma/site-calc-investment
 Project-URL: Documentation, https://github.com/stranma/site-calc-investment#readme
@@ -52,9 +52,10 @@ from datetime import datetime
 from zoneinfo import ZoneInfo
 from site_calc_investment import InvestmentClient
 from site_calc_investment.models import (
-    TimeSpan, Resolution, Site, Battery, ElectricityImport,
+    Resolution, Site, Battery, ElectricityImport, ElectricityExport,
     InvestmentPlanningRequest, InvestmentParameters, OptimizationConfig
 )
+from site_calc_investment.models.requests import TimeSpanInvestment
 
 # Initialize client
 client = InvestmentClient(
@@ -62,13 +63,16 @@ client = InvestmentClient(
     api_key="inv_your_api_key_here"
 )
 
-# Create 10-year planning horizon (1-hour resolution)
-timespan = TimeSpan(
+# Create 1-week planning horizon (1-hour resolution)
+timespan = TimeSpanInvestment(
     start=datetime(2025, 1, 1, tzinfo=ZoneInfo("Europe/Prague")),
-    intervals=87600,  # 10 years × 8760 hours/year
+    intervals=168,  # 1 week = 7 days × 24 hours
     resolution=Resolution.HOUR_1
 )
 
+# Generate hourly prices (example: day/night pattern)
+prices = [30.0 if h % 24 < 6 else 80.0 if 8 <= h % 24 < 20 else 50.0 for h in range(168)]
+
 # Define devices (NO ancillary_services field)
 battery = Battery(
     name="Battery1",
@@ -82,14 +86,20 @@ battery = Battery(
 
 grid_import = ElectricityImport(
     name="GridImport",
-    properties={"price": prices_10y, "max_import": 8.0}
+    properties={"price": prices, "max_import": 10.0}
+)
+
+grid_export = ElectricityExport(
+    name="GridExport",
+    properties={"price": prices, "max_export": 10.0}
 )
 
-site = Site(site_id="investment_site", devices=[battery, grid_import])
+site = Site(site_id="investment_site", devices=[battery, grid_import, grid_export])
 
 # Investment parameters
 inv_params = InvestmentParameters(
     discount_rate=0.05,
+    project_lifetime_years=10,                  # Required field
     device_capital_costs={"Battery1": 500000},  # €500k CAPEX
     device_annual_opex={"Battery1": 5000}       # €5k/year O&M
 )
@@ -100,19 +110,17 @@ request = InvestmentPlanningRequest(
     timespan=timespan,
     investment_parameters=inv_params,
     optimization_config=OptimizationConfig(
-        objective="maximize_npv",
-        time_limit_seconds=3600
+        objective="maximize_profit",  # Options: maximize_profit, minimize_cost, maximize_self_consumption
+        time_limit_seconds=300        # Max 900 seconds (15 min)
     )
 )
 
 job = client.create_planning_job(request)
-result = client.wait_for_completion(job.job_id, poll_interval=30, timeout=7200)
+result = client.wait_for_completion(job.job_id, poll_interval=5, timeout=600)
 
-# Display investment metrics
-metrics = result.summary.investment_metrics
-print(f"NPV: €{metrics.npv:,.0f}")
-print(f"IRR: {metrics.irr*100:.2f}%")
-print(f"Payback: {metrics.payback_period_years:.1f} years")
+print(f"Status: {result.status}")
+print(f"Solver: {result.summary.solver_status}")
+print(f"Profit: €{result.summary.expected_profit:,.2f}")
 ```
 
 ## Features
@@ -135,7 +143,7 @@ print(f"Payback: {metrics.payback_period_years:.1f} years")
 | Resolution | 1-hour only |
 | ANS Support | No |
 | Binary Variables | Relaxed to continuous |
-| Timeout | 3600 seconds (1 hour) |
+| Timeout | 900 seconds (15 minutes) max |
 
 ## Supported Devices
 
@@ -203,7 +211,7 @@ print(comparison)  # DataFrame with NPV, IRR, costs, revenues
 
 ## Documentation
 
-Full documentation available at: https://docs.site-calc.example.com/investment-client
+Full documentation available at: https://github.com/stranma/site-calc-investment#readme
 
 ## Examples
 

{site_calc_investment-1.2.0 → site_calc_investment-1.2.1}/QUICK_START.md

@@ -114,7 +114,7 @@ To enable `pip install site-calc-investment`:
      - Owner: `YOUR-GITHUB-USERNAME`
      - Repository name: `site-calc-investment`
      - Workflow name: `publish.yml`
-     - Environment name: (leave empty)
+     - Environment name: `pypi`
 
 3. **Done!** No API tokens needed (uses trusted publishing)
 

{site_calc_investment-1.2.0 → site_calc_investment-1.2.1}/README.md

@@ -15,9 +15,10 @@ from datetime import datetime
 from zoneinfo import ZoneInfo
 from site_calc_investment import InvestmentClient
 from site_calc_investment.models import (
-    TimeSpan, Resolution, Site, Battery, ElectricityImport,
+    Resolution, Site, Battery, ElectricityImport, ElectricityExport,
     InvestmentPlanningRequest, InvestmentParameters, OptimizationConfig
 )
+from site_calc_investment.models.requests import TimeSpanInvestment
 
 # Initialize client
 client = InvestmentClient(
@@ -25,13 +26,16 @@ client = InvestmentClient(
     api_key="inv_your_api_key_here"
 )
 
-# Create 10-year planning horizon (1-hour resolution)
-timespan = TimeSpan(
+# Create 1-week planning horizon (1-hour resolution)
+timespan = TimeSpanInvestment(
     start=datetime(2025, 1, 1, tzinfo=ZoneInfo("Europe/Prague")),
-    intervals=87600,  # 10 years × 8760 hours/year
+    intervals=168,  # 1 week = 7 days × 24 hours
     resolution=Resolution.HOUR_1
 )
 
+# Generate hourly prices (example: day/night pattern)
+prices = [30.0 if h % 24 < 6 else 80.0 if 8 <= h % 24 < 20 else 50.0 for h in range(168)]
+
 # Define devices (NO ancillary_services field)
 battery = Battery(
     name="Battery1",
@@ -45,14 +49,20 @@ battery = Battery(
 
 grid_import = ElectricityImport(
     name="GridImport",
-    properties={"price": prices_10y, "max_import": 8.0}
+    properties={"price": prices, "max_import": 10.0}
+)
+
+grid_export = ElectricityExport(
+    name="GridExport",
+    properties={"price": prices, "max_export": 10.0}
 )
 
-site = Site(site_id="investment_site", devices=[battery, grid_import])
+site = Site(site_id="investment_site", devices=[battery, grid_import, grid_export])
 
 # Investment parameters
 inv_params = InvestmentParameters(
     discount_rate=0.05,
+    project_lifetime_years=10,                  # Required field
     device_capital_costs={"Battery1": 500000},  # €500k CAPEX
     device_annual_opex={"Battery1": 5000}       # €5k/year O&M
 )
@@ -63,19 +73,17 @@ request = InvestmentPlanningRequest(
     timespan=timespan,
     investment_parameters=inv_params,
     optimization_config=OptimizationConfig(
-        objective="maximize_npv",
-        time_limit_seconds=3600
+        objective="maximize_profit",  # Options: maximize_profit, minimize_cost, maximize_self_consumption
+        time_limit_seconds=300        # Max 900 seconds (15 min)
     )
 )
 
 job = client.create_planning_job(request)
-result = client.wait_for_completion(job.job_id, poll_interval=30, timeout=7200)
+result = client.wait_for_completion(job.job_id, poll_interval=5, timeout=600)
 
-# Display investment metrics
-metrics = result.summary.investment_metrics
-print(f"NPV: €{metrics.npv:,.0f}")
-print(f"IRR: {metrics.irr*100:.2f}%")
-print(f"Payback: {metrics.payback_period_years:.1f} years")
+print(f"Status: {result.status}")
+print(f"Solver: {result.summary.solver_status}")
+print(f"Profit: €{result.summary.expected_profit:,.2f}")
 ```
 
 ## Features
@@ -98,7 +106,7 @@ print(f"Payback: {metrics.payback_period_years:.1f} years")
 | Resolution | 1-hour only |
 | ANS Support | No |
 | Binary Variables | Relaxed to continuous |
-| Timeout | 3600 seconds (1 hour) |
+| Timeout | 900 seconds (15 minutes) max |
 
 ## Supported Devices
 
@@ -166,7 +174,7 @@ print(comparison)  # DataFrame with NPV, IRR, costs, revenues
 
 ## Documentation
 
-Full documentation available at: https://docs.site-calc.example.com/investment-client
+Full documentation available at: https://github.com/stranma/site-calc-investment#readme
 
 ## Examples
 

site_calc_investment-1.2.1/examples/01_basic_capacity_planning.py

@@ -0,0 +1,173 @@
+"""Basic Capacity Planning Example
+
+This example demonstrates a simple 1-week battery optimization
+for capacity sizing and investment ROI analysis.
+"""
+
+import os
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+from site_calc_investment import (
+    Battery,
+    ElectricityExport,
+    ElectricityImport,
+    InvestmentClient,
+    InvestmentParameters,
+    InvestmentPlanningRequest,
+    OptimizationConfig,
+    Site,
+)
+from site_calc_investment.models.requests import TimeSpanInvestment
+
+
+def main():
+    # Get credentials from environment
+    api_url = os.environ.get("INVESTMENT_API_URL_DEV") or os.environ.get("INVESTMENT_API_URL")
+    api_key = os.environ.get("INVESTMENT_API_KEY_DEV") or os.environ.get("INVESTMENT_API_KEY")
+
+    if not api_url or not api_key:
+        print("ERROR: Set INVESTMENT_API_URL and INVESTMENT_API_KEY environment variables")
+        return
+
+    # Initialize client
+    client = InvestmentClient(
+        base_url=api_url,
+        api_key=api_key,
+    )
+
+    # Create 1-week planning horizon (1-hour resolution)
+    timespan = TimeSpanInvestment(
+        start=datetime(2025, 1, 1, tzinfo=ZoneInfo("Europe/Prague")),
+        intervals=168,  # 1 week = 7 days x 24 hours
+    )
+    print(f"Planning horizon: {timespan.intervals} hourly intervals ({timespan.intervals / 24:.0f} days)")
+
+    # Generate price profile with day/night pattern
+    prices = []
+    for hour in range(168):
+        hour_of_day = hour % 24
+        if 9 <= hour_of_day <= 20:
+            prices.append(80.0)  # Day: high price
+        else:
+            prices.append(30.0)  # Night: low price
+
+    print(f"Price profile generated: {len(prices)} values")
+    print("  Day price: EUR 80/MWh, Night price: EUR 30/MWh")
+
+    # Define 10 MW / 20 MWh battery (2-hour duration)
+    battery = Battery(
+        name="Battery1",
+        properties={
+            "capacity": 20.0,  # MWh
+            "max_power": 10.0,  # MW (2-hour discharge)
+            "efficiency": 0.90,  # 90% round-trip
+            "initial_soc": 0.5,  # Start at 50%
+        },
+    )
+
+    # Market devices (grid connections)
+    grid_import = ElectricityImport(
+        name="GridImport",
+        properties={"price": prices, "max_import": 20.0},
+    )
+
+    grid_export = ElectricityExport(
+        name="GridExport",
+        properties={"price": prices, "max_export": 20.0},
+    )
+
+    # Create site
+    site = Site(
+        site_id="battery_investment_site",
+        description="Battery capacity planning example",
+        devices=[battery, grid_import, grid_export],
+    )
+
+    # Investment parameters
+    inv_params = InvestmentParameters(
+        discount_rate=0.05,  # 5% discount rate
+        project_lifetime_years=10,  # Required field
+        device_capital_costs={
+            "Battery1": 2_000_000  # EUR 2M CAPEX (EUR 100/kWh)
+        },
+        device_annual_opex={
+            "Battery1": 20_000  # EUR 20k/year O&M
+        },
+    )
+
+    # Create optimization request
+    request = InvestmentPlanningRequest(
+        sites=[site],
+        timespan=timespan,
+        investment_parameters=inv_params,
+        optimization_config=OptimizationConfig(
+            objective="maximize_profit",  # Options: maximize_profit, minimize_cost, maximize_self_consumption
+            time_limit_seconds=300,  # 5 minutes max
+            relax_binary_variables=True,
+        ),
+    )
+
+    print("\n" + "=" * 60)
+    print("Submitting optimization job...")
+    print("=" * 60)
+
+    # Submit job
+    job = client.create_planning_job(request)
+    print(f"\nJob ID: {job.job_id}")
+    print(f"Status: {job.status}")
+
+    # Wait for completion
+    print("\nWaiting for optimization to complete...")
+
+    result = client.wait_for_completion(
+        job.job_id,
+        poll_interval=5,  # Check every 5 seconds
+        timeout=600,  # 10 minute maximum
+    )
+
+    print("\n" + "=" * 60)
+    print("OPTIMIZATION RESULTS")
+    print("=" * 60)
+
+    # Summary
+    summary = result.summary
+    print(f"\nSolver Status: {summary.solver_status}")
+    print(f"Solve Time: {summary.solve_time_seconds:.1f}s")
+
+    if summary.expected_profit is not None:
+        print(f"Expected Profit: EUR {summary.expected_profit:,.2f}")
+
+    # Investment metrics (if available)
+    if result.investment_metrics:
+        metrics = result.investment_metrics
+        print("\nINVESTMENT METRICS:")
+        if metrics.total_revenue_10y is not None:
+            print(f"  Total Revenue (10y):  EUR {metrics.total_revenue_10y:>15,.0f}")
+        if metrics.total_costs_10y is not None:
+            print(f"  Total Costs (10y):    EUR {metrics.total_costs_10y:>15,.0f}")
+        if metrics.npv is not None:
+            print(f"  NPV:                  EUR {metrics.npv:>15,.0f}")
+        if metrics.irr is not None:
+            print(f"  IRR:                       {metrics.irr * 100:>15.2f}%")
+        if metrics.payback_period_years is not None:
+            print(f"  Payback Period:            {metrics.payback_period_years:>15.1f} years")
+
+    # Device schedules (first 24 hours)
+    site_result = result.sites.get("battery_investment_site")
+    if site_result:
+        battery_schedule = site_result.device_schedules.get("Battery1")
+        if battery_schedule and battery_schedule.flows.get("electricity"):
+            print("\nBATTERY OPERATION (First 24 hours):")
+            el_flow = battery_schedule.flows["electricity"]
+            soc = battery_schedule.soc or []
+
+            for hour in range(min(24, len(el_flow))):
+                soc_str = f"{soc[hour]:.1%}" if hour < len(soc) else "N/A"
+                print(f"  Hour {hour:2d}:  Power {el_flow[hour]:>7.2f} MW  |  SOC {soc_str}")
+
+    print("\n" + "=" * 60)
+
+
+if __name__ == "__main__":
+    main()

site_calc_investment-1.2.1/examples/02_scenario_comparison.py

@@ -0,0 +1,210 @@
+"""Scenario Comparison Example
+
+This example compares three different battery sizes to find the optimal
+capacity for investment.
+"""
+
+import os
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+from site_calc_investment import (
+    Battery,
+    ElectricityExport,
+    ElectricityImport,
+    InvestmentClient,
+    InvestmentParameters,
+    InvestmentPlanningRequest,
+    OptimizationConfig,
+    Site,
+    compare_scenarios,
+)
+from site_calc_investment.models.requests import TimeSpanInvestment
+
+
+def create_prices(days: int = 7):
+    """Create price profile with daily pattern."""
+    prices = []
+    for day in range(days):
+        for hour in range(24):
+            if 9 <= hour <= 20:
+                prices.append(80.0)  # Day: high price
+            else:
+                prices.append(30.0)  # Night: low price
+    return prices
+
+
+def create_scenario(
+    client: InvestmentClient,
+    capacity_mwh: float,
+    prices: list,
+    timespan: TimeSpanInvestment,
+) -> tuple:
+    """Create and run a scenario with given battery capacity.
+
+    Returns:
+        (scenario_name, result)
+    """
+    scenario_name = f"{capacity_mwh:.0f} MWh Battery"
+    print(f"\n{'=' * 60}")
+    print(f"SCENARIO: {scenario_name}")
+    print(f"{'=' * 60}")
+
+    # Battery sized for 2-hour duration
+    battery = Battery(
+        name="Battery1",
+        properties={
+            "capacity": capacity_mwh,
+            "max_power": capacity_mwh / 2,  # 2-hour discharge
+            "efficiency": 0.90,
+            "initial_soc": 0.5,
+        },
+    )
+
+    grid_import = ElectricityImport(
+        name="GridImport",
+        properties={"price": prices, "max_import": 50.0},
+    )
+
+    grid_export = ElectricityExport(
+        name="GridExport",
+        properties={"price": prices, "max_export": 50.0},
+    )
+
+    site = Site(
+        site_id=f"site_{capacity_mwh:.0f}mwh",
+        devices=[battery, grid_import, grid_export],
+    )
+
+    # Capital cost: EUR 100/kWh
+    capex = capacity_mwh * 1000 * 100  # EUR 100/kWh
+
+    # O&M: EUR 1/kWh/year
+    opex = capacity_mwh * 1000 * 1  # EUR 1/kWh/year
+
+    inv_params = InvestmentParameters(
+        discount_rate=0.05,
+        project_lifetime_years=10,  # Required field
+        device_capital_costs={"Battery1": capex},
+        device_annual_opex={"Battery1": opex},
+    )
+
+    request = InvestmentPlanningRequest(
+        sites=[site],
+        timespan=timespan,
+        investment_parameters=inv_params,
+        optimization_config=OptimizationConfig(
+            objective="maximize_profit",  # Valid options: maximize_profit, minimize_cost, maximize_self_consumption
+            time_limit_seconds=300,
+        ),
+    )
+
+    print(f"  Capacity:   {capacity_mwh:.0f} MWh")
+    print(f"  Power:      {capacity_mwh / 2:.0f} MW")
+    print(f"  CAPEX:      EUR {capex:,.0f}")
+    print(f"  Annual O&M: EUR {opex:,.0f}")
+
+    job = client.create_planning_job(request)
+    print(f"\n  Job ID: {job.job_id}")
+    print("  Waiting for completion...")
+
+    result = client.wait_for_completion(job.job_id, poll_interval=5, timeout=600)
+
+    print(f"  Completed in {result.summary.solve_time_seconds:.0f}s")
+
+    if result.investment_metrics:
+        metrics = result.investment_metrics
+        npv_str = f"EUR {metrics.npv:,.0f}" if metrics.npv else "N/A"
+        irr_str = f"{metrics.irr * 100:.2f}%" if metrics.irr else "N/A"
+        payback_str = f"{metrics.payback_period_years:.1f} years" if metrics.payback_period_years else "N/A"
+        print(f"\n  NPV:     {npv_str}")
+        print(f"  IRR:     {irr_str}")
+        print(f"  Payback: {payback_str}")
+
+    return scenario_name, result
+
+
+def main():
+    print("=" * 60)
+    print("BATTERY CAPACITY SIZING: SCENARIO COMPARISON")
+    print("=" * 60)
+    print("\nComparing three battery sizes over 1-week horizon")
+    print("Goal: Find optimal capacity for maximum profit")
+
+    # Get credentials from environment
+    api_url = os.environ.get("INVESTMENT_API_URL_DEV") or os.environ.get("INVESTMENT_API_URL")
+    api_key = os.environ.get("INVESTMENT_API_KEY_DEV") or os.environ.get("INVESTMENT_API_KEY")
+
+    if not api_url or not api_key:
+        print("\nERROR: Set INVESTMENT_API_URL and INVESTMENT_API_KEY environment variables")
+        return
+
+    # Initialize client
+    client = InvestmentClient(
+        base_url=api_url,
+        api_key=api_key,
+    )
+
+    # 1-week planning
+    timespan = TimeSpanInvestment(
+        start=datetime(2025, 1, 1, tzinfo=ZoneInfo("Europe/Prague")),
+        intervals=168,  # 1 week
+    )
+    prices = create_prices(days=7)
+
+    print(f"\nPrices: {len(prices)} hourly values")
+    print("  Day price: EUR 80/MWh, Night price: EUR 30/MWh")
+
+    # Test three capacities
+    capacities = [10.0, 20.0, 30.0]  # MWh
+
+    scenarios = []
+    for capacity in capacities:
+        name, result = create_scenario(client, capacity, prices, timespan)
+        scenarios.append((name, result))
+
+    # Compare scenarios
+    print("\n" + "=" * 60)
+    print("SCENARIO COMPARISON")
+    print("=" * 60)
+
+    names = [s[0] for s in scenarios]
+    results = [s[1] for s in scenarios]
+
+    comparison = compare_scenarios(results, names=names)
+
+    # Print comparison table
+    print(f"\n{'Scenario':<20} {'Profit':>15} {'NPV':>15} {'IRR':>10}")
+    print("-" * 65)
+
+    for i, name in enumerate(comparison["names"]):
+        profit = comparison.get("profit", [None] * len(names))[i]
+        npv = comparison.get("npv", [None] * len(names))[i]
+        irr = comparison.get("irr", [None] * len(names))[i]
+
+        profit_str = f"EUR {profit:,.0f}" if profit is not None else "N/A"
+        npv_str = f"EUR {npv:,.0f}" if npv is not None else "N/A"
+        irr_str = f"{irr * 100:.2f}%" if irr is not None else "N/A"
+
+        print(f"{name:<20} {profit_str:>15} {npv_str:>15} {irr_str:>10}")
+
+    # Find optimal by profit
+    profit_values = comparison.get("profit", [])
+    if profit_values:
+        valid_profits = [(i, v) for i, v in enumerate(profit_values) if v is not None]
+        if valid_profits:
+            best_idx, best_profit = max(valid_profits, key=lambda x: x[1])
+            best_name = comparison["names"][best_idx]
+
+            print("\n" + "=" * 60)
+            print(f"OPTIMAL CONFIGURATION: {best_name}")
+            print("=" * 60)
+            print(f"  Profit: EUR {best_profit:,.0f}")
+    else:
+        print("\nNo profit data available for comparison")
+
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()

{site_calc_investment-1.2.0 → site_calc_investment-1.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "site-calc-investment"
-version = "1.2.0"
+version = "1.2.1"
 description = "Python client for Site-Calc investment planning (capacity sizing, ROI analysis)"
 readme = "README.md"
 requires-python = ">=3.10"

{site_calc_investment-1.2.0 → site_calc_investment-1.2.1}/site_calc_investment/__init__.py

@@ -3,7 +3,7 @@
 Python client for long-term capacity planning and investment ROI analysis.
 """
 
-__version__ = "1.2.0"
+__version__ = "1.2.1"
 
 from site_calc_investment.analysis import (
     aggregate_annual,

site_calc_investment-1.2.0/examples/01_basic_capacity_planning.py

@@ -1,172 +0,0 @@
-"""Basic Capacity Planning Example
-
-This example demonstrates a simple 10-year battery optimization
-for capacity sizing and investment ROI analysis.
-"""
-
-from site_calc_investment import (
-    Battery,
-    BatteryProperties,
-    ElectricityExport,
-    ElectricityImport,
-    InvestmentClient,
-    InvestmentParameters,
-    InvestmentPlanningRequest,
-    MarketExportProperties,
-    MarketImportProperties,
-    OptimizationConfig,
-    Site,
-    TimeSpan,
-)
-
-
-def main():
-    # Initialize client
-    client = InvestmentClient(
-        base_url="https://api.site-calc.example.com",
-        api_key="inv_your_api_key_here",
-    )
-
-    # Create 10-year planning horizon (1-hour resolution)
-    timespan = TimeSpan.for_years(start_year=2025, years=10)
-    print(f"Planning horizon: {timespan.years} years ({timespan.intervals} hourly intervals)")
-
-    # Generate simple price profile with 2% annual escalation
-    base_hourly_prices = []
-    for hour in range(24):
-        # Higher prices during day (peak)
-        if 9 <= hour <= 20:
-            price = 40.0
-        else:
-            price = 25.0
-        base_hourly_prices.append(price)
-
-    # Extend to 10 years with 2% annual escalation
-    prices_10y = []
-    for year in range(10):
-        escalation_factor = 1.02**year
-        year_prices = [p * escalation_factor for p in base_hourly_prices] * 365
-        prices_10y.extend(year_prices)
-
-    print(f"Price profile generated: {len(prices_10y)} values")
-    print(f"  Year 1 avg: €{sum(prices_10y[:8760]) / 8760:.2f}/MWh")
-    print(f"  Year 10 avg: €{sum(prices_10y[-8760:]) / 8760:.2f}/MWh")
-
-    # Define 10 MW / 20 MWh battery (2-hour duration)
-    battery = Battery(
-        name="Battery1",
-        properties=BatteryProperties(
-            capacity=20.0,  # MWh
-            max_power=10.0,  # MW (2-hour discharge)
-            efficiency=0.90,  # 90% round-trip
-            initial_soc=0.5,  # Start at 50%
-        ),
-    )
-
-    # Market devices (grid connections)
-    grid_import = ElectricityImport(
-        name="GridImport", properties=MarketImportProperties(price=prices_10y, max_import=20.0)
-    )
-
-    grid_export = ElectricityExport(
-        name="GridExport", properties=MarketExportProperties(price=prices_10y, max_export=20.0)
-    )
-
-    # Create site
-    site = Site(
-        site_id="battery_investment_site",
-        description="10-year battery capacity planning",
-        devices=[battery, grid_import, grid_export],
-    )
-
-    # Investment parameters
-    inv_params = InvestmentParameters(
-        discount_rate=0.05,  # 5% discount rate
-        device_capital_costs={
-            "Battery1": 2_000_000  # €2M CAPEX (€100/kWh)
-        },
-        device_annual_opex={
-            "Battery1": 20_000  # €20k/year O&M
-        },
-    )
-
-    # Create optimization request
-    request = InvestmentPlanningRequest(
-        sites=[site],
-        timespan=timespan,
-        investment_parameters=inv_params,
-        optimization_config=OptimizationConfig(
-            objective="maximize_npv",
-            time_limit_seconds=300,  # 5 minutes
-            relax_binary_variables=True,
-        ),
-    )
-
-    print("\n" + "=" * 80)
-    print("Submitting optimization job...")
-    print("=" * 80)
-
-    # Submit job
-    job = client.create_planning_job(request)
-    print(f"\nJob ID: {job.job_id}")
-    print(f"Status: {job.status}")
-
-    # Wait for completion (with progress updates)
-    print("\nWaiting for optimization to complete...")
-    print("(This may take 15-60 minutes for 10-year horizon)")
-
-    result = client.wait_for_completion(
-        job.job_id,
-        poll_interval=30,  # Check every 30 seconds
-        timeout=7200,  # 2 hour maximum
-    )
-
-    print("\n" + "=" * 80)
-    print("OPTIMIZATION RESULTS")
-    print("=" * 80)
-
-    # Summary
-    summary = result.summary
-    print(f"\nSolver Status: {summary.solver_status}")
-    print(f"Solve Time: {summary.solve_time_seconds:.1f}s ({summary.solve_time_seconds / 60:.1f} min)")
-
-    # Financial metrics
-    if summary.investment_metrics:
-        metrics = summary.investment_metrics
-        print("\nFINANCIAL METRICS:")
-        print(f"  Total Revenue (10y):  €{metrics.total_revenue_period:>15,.0f}")
-        print(f"  Total Costs (10y):    €{metrics.total_costs_period:>15,.0f}")
-        print(f"  Net Profit (10y):     €{summary.expected_profit:>15,.0f}")
-        print(f"\n  NPV:                  €{metrics.npv:>15,.0f}")
-        print(f"  IRR:                   {metrics.irr * 100:>15.2f}%")
-        print(f"  Payback Period:        {metrics.payback_period_years:>15.1f} years")
-
-        # Annual breakdown
-        if metrics.annual_revenue_by_year:
-            print("\nANNUAL BREAKDOWN:")
-            revenues = metrics.annual_revenue_by_year
-            costs = metrics.annual_costs_by_year
-            for year, (revenue, cost) in enumerate(zip(revenues, costs), 1):
-                print(f"  Year {year:2d}:  Revenue €{revenue:>10,.0f}  |  Cost €{cost:>10,.0f}")
-
-    # Device schedules (first and last 24 hours)
-    site_result = result.sites["battery_investment_site"]
-    battery_schedule = site_result.device_schedules["Battery1"]
-
-    print("\nBATTERY OPERATION (First 24 hours):")
-    el_flow = battery_schedule.flows["electricity"]
-    soc = battery_schedule.soc
-
-    for hour in range(24):
-        print(f"  Hour {hour:2d}:  Power {el_flow[hour]:>6.2f} MW  |  SOC {soc[hour]:>5.1%}")
-
-    print("\nBATTERY OPERATION (Last 24 hours):")
-    for hour in range(-24, 0):
-        actual_hour = hour % 24
-        print(f"  Hour {actual_hour:2d}:  Power {el_flow[hour]:>6.2f} MW  |  SOC {soc[hour]:>5.1%}")
-
-    print("\n" + "=" * 80)
-
-
-if __name__ == "__main__":
-    main()

site_calc_investment-1.2.0/examples/02_scenario_comparison.py

@@ -1,197 +0,0 @@
-"""Scenario Comparison Example
-
-This example compares three different battery sizes to find the optimal
-capacity for a 10-year investment.
-"""
-
-from site_calc_investment import (
-    Battery,
-    BatteryProperties,
-    ElectricityExport,
-    ElectricityImport,
-    InvestmentClient,
-    InvestmentParameters,
-    InvestmentPlanningRequest,
-    MarketExportProperties,
-    MarketImportProperties,
-    OptimizationConfig,
-    Site,
-    TimeSpan,
-    compare_scenarios,
-)
-
-
-def create_prices(years: int = 10, escalation_rate: float = 0.02):
-    """Create price profile with daily pattern and annual escalation."""
-    base_hourly = []
-    for hour in range(24):
-        if 9 <= hour <= 20:
-            price = 40.0
-        else:
-            price = 25.0
-        base_hourly.append(price)
-
-    prices = []
-    for year in range(years):
-        factor = (1 + escalation_rate) ** year
-        prices.extend([p * factor for p in base_hourly] * 365)
-
-    return prices
-
-
-def create_scenario(
-    client: InvestmentClient,
-    capacity_mwh: float,
-    prices: list,
-    timespan: TimeSpan,
-) -> tuple:
-    """Create and run a scenario with given battery capacity.
-
-    Returns:
-        (scenario_name, result)
-    """
-    scenario_name = f"{capacity_mwh:.0f} MWh Battery"
-    print(f"\n{'=' * 80}")
-    print(f"SCENARIO: {scenario_name}")
-    print(f"{'=' * 80}")
-
-    # Battery sized for 2-hour duration
-    battery = Battery(
-        name="Battery1",
-        properties=BatteryProperties(
-            capacity=capacity_mwh,
-            max_power=capacity_mwh / 2,  # 2-hour discharge
-            efficiency=0.90,
-            initial_soc=0.5,
-        ),
-    )
-
-    grid_import = ElectricityImport(name="GridImport", properties=MarketImportProperties(price=prices, max_import=50.0))
-
-    grid_export = ElectricityExport(name="GridExport", properties=MarketExportProperties(price=prices, max_export=50.0))
-
-    site = Site(site_id=f"site_{capacity_mwh:.0f}mwh", devices=[battery, grid_import, grid_export])
-
-    # Capital cost: €100/kWh
-    capex = capacity_mwh * 1000 * 100  # €100/kWh
-
-    # O&M: €1/kWh/year
-    opex = capacity_mwh * 1000 * 1  # €1/kWh/year
-
-    inv_params = InvestmentParameters(
-        discount_rate=0.05, device_capital_costs={"Battery1": capex}, device_annual_opex={"Battery1": opex}
-    )
-
-    request = InvestmentPlanningRequest(
-        sites=[site],
-        timespan=timespan,
-        investment_parameters=inv_params,
-        optimization_config=OptimizationConfig(objective="maximize_npv", time_limit_seconds=300),
-    )
-
-    print(f"  Capacity:  {capacity_mwh:.0f} MWh")
-    print(f"  Power:     {capacity_mwh / 2:.0f} MW")
-    print(f"  CAPEX:     €{capex:,.0f}")
-    print(f"  Annual O&M: €{opex:,.0f}")
-
-    job = client.create_planning_job(request)
-    print(f"\n  Job ID: {job.job_id}")
-    print("  Waiting for completion...")
-
-    result = client.wait_for_completion(job.job_id, poll_interval=30, timeout=7200)
-
-    print(f"  ✅ Completed in {result.summary.solve_time_seconds:.0f}s")
-
-    if result.summary.investment_metrics:
-        metrics = result.summary.investment_metrics
-        print(f"\n  NPV:       €{metrics.npv:>12,.0f}")
-        print(f"  IRR:        {metrics.irr * 100:>12.2f}%")
-        print(f"  Payback:    {metrics.payback_period_years:>12.1f} years")
-
-    return scenario_name, result
-
-
-def main():
-    print("=" * 80)
-    print("BATTERY CAPACITY SIZING: SCENARIO COMPARISON")
-    print("=" * 80)
-    print("\nComparing three battery sizes over 10-year horizon")
-    print("Goal: Find optimal capacity for maximum NPV")
-
-    # Initialize client
-    client = InvestmentClient(
-        base_url="https://api.site-calc.example.com",
-        api_key="inv_your_api_key_here",
-    )
-
-    # 10-year planning
-    timespan = TimeSpan.for_years(2025, 10)
-    prices = create_prices(years=10, escalation_rate=0.02)
-
-    print(f"\nPrices: {len(prices)} hourly values")
-    print(f"  Year 1 avg: €{sum(prices[:8760]) / 8760:.2f}/MWh")
-    print(f"  Year 10 avg: €{sum(prices[-8760:]) / 8760:.2f}/MWh")
-
-    # Test three capacities
-    capacities = [10.0, 20.0, 30.0]  # MWh
-
-    scenarios = []
-    for capacity in capacities:
-        name, result = create_scenario(client, capacity, prices, timespan)
-        scenarios.append((name, result))
-
-    # Compare scenarios
-    print("\n" + "=" * 80)
-    print("SCENARIO COMPARISON")
-    print("=" * 80)
-
-    names = [s[0] for s in scenarios]
-    results = [s[1] for s in scenarios]
-
-    comparison = compare_scenarios(results, names=names)
-
-    # Print comparison table
-    print(f"\n{'Scenario':<20} {'NPV':>15} {'IRR':>10} {'Payback':>12} {'Revenue':>15} {'Costs':>15}")
-    print("-" * 100)
-
-    for i, name in enumerate(comparison["names"]):
-        npv = comparison["npv"][i]
-        irr = comparison["irr"][i]
-        payback = comparison["payback_years"][i]
-        revenue = comparison["total_revenue"][i]
-        costs = comparison["total_costs"][i]
-
-        npv_str = f"€{npv:,.0f}" if npv is not None else "N/A"
-        irr_str = f"{irr * 100:.2f}%" if irr is not None else "N/A"
-        payback_str = f"{payback:.1f} yrs" if payback is not None else "N/A"
-
-        print(f"{name:<20} {npv_str:>15} {irr_str:>10} {payback_str:>12} €{revenue:>13,.0f} €{costs:>13,.0f}")
-
-    # Find optimal
-    npv_values = [(i, v) for i, v in enumerate(comparison["npv"]) if v is not None]
-    if npv_values:
-        best_idx, best_npv = max(npv_values, key=lambda x: x[1])
-        best_name = comparison["names"][best_idx]
-
-        print("\n" + "=" * 80)
-        print(f"OPTIMAL CONFIGURATION: {best_name}")
-        print("=" * 80)
-        print(f"  NPV:       €{best_npv:,.0f}")
-        print(f"  IRR:        {comparison['irr'][best_idx] * 100:.2f}%")
-        print(f"  Payback:    {comparison['payback_years'][best_idx]:.1f} years")
-        print(f"  10y Revenue: €{comparison['total_revenue'][best_idx]:,.0f}")
-        print(f"  10y Costs:   €{comparison['total_costs'][best_idx]:,.0f}")
-        print(f"  10y Profit:  €{comparison['profit'][best_idx]:,.0f}")
-        print("=" * 80)
-
-    # Calculate NPV per MWh of capacity
-    print("\nCAPEX EFFICIENCY:")
-    for i, capacity in enumerate(capacities):
-        npv = comparison["npv"][i]
-        if npv is not None:
-            npv_per_mwh = npv / capacity
-            print(f"  {capacity:.0f} MWh:  €{npv_per_mwh:,.0f} NPV per MWh")
-
-
-if __name__ == "__main__":
-    main()