pyconvexity 0.1.1__py3-none-any.whl → 0.1.3__py3-none-any.whl

pyconvexity/models/scenarios.py

@@ -0,0 +1,177 @@
+"""
+Scenario management operations for PyConvexity.
+
+Provides operations for creating and managing scenarios within networks.
+"""
+
+import sqlite3
+import logging
+from typing import List, Optional
+from datetime import datetime
+
+from pyconvexity.core.errors import ValidationError, DatabaseError
+
+logger = logging.getLogger(__name__)
+
+
+def create_scenario(
+    conn: sqlite3.Connection,
+    network_id: int,
+    name: str,
+    description: Optional[str] = None,
+    is_master: bool = False,
+) -> int:
+    """
+    Create a new scenario for a network.
+    
+    Args:
+        conn: Database connection
+        network_id: ID of the network
+        name: Name of the scenario
+        description: Optional description
+        is_master: Whether this is a master scenario (default False)
+        
+    Returns:
+        ID of the newly created scenario
+        
+    Raises:
+        ValidationError: If network doesn't exist or scenario name conflicts
+        DatabaseError: If creation fails
+    """
+    
+    # Validate network exists
+    cursor = conn.execute("SELECT COUNT(*) FROM networks WHERE id = ?", (network_id,))
+    if cursor.fetchone()[0] == 0:
+        raise ValidationError(f"Network with ID {network_id} not found")
+    
+    # Check for name conflicts within the network
+    cursor = conn.execute(
+        "SELECT COUNT(*) FROM scenarios WHERE network_id = ? AND name = ?",
+        (network_id, name)
+    )
+    if cursor.fetchone()[0] > 0:
+        raise ValidationError(f"Scenario with name '{name}' already exists in network {network_id}")
+    
+    # Insert the scenario (database triggers will handle master scenario uniqueness)
+    cursor = conn.execute(
+        "INSERT INTO scenarios (network_id, name, description, is_master, created_at) "
+        "VALUES (?, ?, ?, ?, datetime('now'))",
+        (network_id, name, description, is_master)
+    )
+    
+    scenario_id = cursor.lastrowid
+    if not scenario_id:
+        raise DatabaseError("Failed to create scenario")
+    
+    logger.info(f"Created scenario '{name}' (ID: {scenario_id}) for network {network_id}")
+    return scenario_id
+
+
+def list_scenarios(conn: sqlite3.Connection, network_id: int) -> List[dict]:
+    """
+    List all scenarios for a network.
+    
+    Args:
+        conn: Database connection
+        network_id: ID of the network
+        
+    Returns:
+        List of scenario dictionaries with keys: id, network_id, name, description, is_master, created_at
+        
+    Raises:
+        DatabaseError: If query fails
+    """
+    
+    cursor = conn.execute(
+        "SELECT id, network_id, name, description, is_master, created_at "
+        "FROM scenarios "
+        "WHERE network_id = ? "
+        "ORDER BY is_master DESC, created_at ASC",
+        (network_id,)
+    )
+    
+    scenarios = []
+    for row in cursor.fetchall():
+        scenarios.append({
+            'id': row[0],
+            'network_id': row[1],
+            'name': row[2],
+            'description': row[3],
+            'is_master': bool(row[4]),
+            'created_at': row[5],
+        })
+    
+    logger.debug(f"Found {len(scenarios)} scenarios for network {network_id}")
+    return scenarios
+
+
+def get_scenario(conn: sqlite3.Connection, scenario_id: int) -> dict:
+    """
+    Get a specific scenario by ID.
+    
+    Args:
+        conn: Database connection
+        scenario_id: ID of the scenario
+        
+    Returns:
+        Scenario dictionary with keys: id, network_id, name, description, is_master, created_at
+        
+    Raises:
+        ValidationError: If scenario not found
+        DatabaseError: If query fails
+    """
+    
+    cursor = conn.execute(
+        "SELECT id, network_id, name, description, is_master, created_at "
+        "FROM scenarios "
+        "WHERE id = ?",
+        (scenario_id,)
+    )
+    
+    row = cursor.fetchone()
+    if not row:
+        raise ValidationError(f"Scenario with ID {scenario_id} not found")
+    
+    return {
+        'id': row[0],
+        'network_id': row[1],
+        'name': row[2],
+        'description': row[3],
+        'is_master': bool(row[4]),
+        'created_at': row[5],
+    }
+
+
+def delete_scenario(conn: sqlite3.Connection, scenario_id: int) -> None:
+    """
+    Delete a scenario (cannot delete master scenarios).
+    
+    Args:
+        conn: Database connection
+        scenario_id: ID of the scenario to delete
+        
+    Raises:
+        ValidationError: If scenario not found or is master scenario
+        DatabaseError: If deletion fails
+    """
+    
+    # Check if scenario exists and is not master
+    cursor = conn.execute(
+        "SELECT is_master FROM scenarios WHERE id = ?",
+        (scenario_id,)
+    )
+    
+    row = cursor.fetchone()
+    if not row:
+        raise ValidationError(f"Scenario with ID {scenario_id} not found")
+    
+    if row[0]:  # is_master
+        raise ValidationError("Cannot delete master scenario")
+    
+    # Delete the scenario (this will cascade to delete related component attributes)
+    cursor = conn.execute("DELETE FROM scenarios WHERE id = ?", (scenario_id,))
+    
+    if cursor.rowcount == 0:
+        raise DatabaseError("Failed to delete scenario")
+    
+    logger.info(f"Deleted scenario {scenario_id}")

pyconvexity/solvers/__init__.py

@@ -0,0 +1,29 @@
+"""
+Solver module for PyConvexity.
+
+Provides interfaces to various optimization solvers for energy system modeling.
+"""
+
+# Try to import PyPSA solver with graceful fallback
+try:
+    from pyconvexity.solvers.pypsa import (
+        solve_network,
+        build_pypsa_network,
+        solve_pypsa_network,
+        load_network_components,
+        apply_constraints,
+        store_solve_results
+    )
+    
+    __all__ = [
+        "solve_network",
+        "build_pypsa_network", 
+        "solve_pypsa_network",
+        "load_network_components",
+        "apply_constraints",
+        "store_solve_results"
+    ]
+    
+except ImportError:
+    # PyPSA not available
+    __all__ = []

pyconvexity/solvers/pypsa/__init__.py

@@ -0,0 +1,24 @@
+"""
+PyPSA solver integration for PyConvexity.
+
+Provides high-level and low-level APIs for building PyPSA networks from database,
+solving them, and storing results back to the database.
+"""
+
+from pyconvexity.solvers.pypsa.api import (
+    solve_network,
+    build_pypsa_network,
+    solve_pypsa_network,
+    load_network_components,
+    apply_constraints,
+    store_solve_results
+)
+
+__all__ = [
+    "solve_network",
+    "build_pypsa_network",
+    "solve_pypsa_network", 
+    "load_network_components",
+    "apply_constraints",
+    "store_solve_results"
+]

pyconvexity/solvers/pypsa/api.py

@@ -0,0 +1,398 @@
+"""
+High-level API for PyPSA solver integration.
+
+Provides user-friendly functions for the most common workflows.
+"""
+
+import logging
+from typing import Dict, Any, Optional, Callable
+
+from pyconvexity.core.database import database_context
+from pyconvexity.solvers.pypsa.builder import NetworkBuilder
+from pyconvexity.solvers.pypsa.solver import NetworkSolver
+from pyconvexity.solvers.pypsa.storage import ResultStorage
+from pyconvexity.solvers.pypsa.constraints import ConstraintApplicator
+
+logger = logging.getLogger(__name__)
+
+
+def solve_network(
+    db_path: str,
+    network_id: int,
+    scenario_id: Optional[int] = None,
+    solver_name: str = "highs",
+    solver_options: Optional[Dict[str, Any]] = None,
+    constraints_dsl: Optional[str] = None,
+    discount_rate: Optional[float] = None,
+    progress_callback: Optional[Callable[[int, str], None]] = None,
+    return_detailed_results: bool = True
+) -> Dict[str, Any]:
+    """
+    Complete solve workflow: build PyPSA network from database, solve, store results.
+    
+    This is the main high-level function that most users should use. It handles
+    the complete workflow of loading data from database, building a PyPSA network,
+    solving it, and storing results back to the database.
+    
+    Args:
+        db_path: Path to the database file
+        network_id: ID of the network to solve
+        scenario_id: Optional scenario ID (uses master scenario if None)
+        solver_name: Solver to use (default: "highs")
+        solver_options: Optional solver-specific options
+        constraints_dsl: Optional DSL constraints to apply
+        discount_rate: Optional discount rate for multi-period optimization
+        progress_callback: Optional callback for progress updates (progress: int, message: str)
+        return_detailed_results: If True, return comprehensive results; if False, return simple status
+        
+    Returns:
+        Dictionary with solve results - comprehensive if return_detailed_results=True, simple status otherwise
+        
+    Raises:
+        DatabaseError: If database operations fail
+        ValidationError: If network data is invalid
+        ImportError: If PyPSA is not available
+    """
+    if progress_callback:
+        progress_callback(0, "Starting network solve...")
+    
+    with database_context(db_path) as conn:
+        # Load network configuration with scenario awareness (matches old code)
+        from pyconvexity.models import get_network_config
+        network_config = get_network_config(conn, network_id, scenario_id)
+        if progress_callback:
+            progress_callback(8, "Loaded network configuration")
+        
+        # Use configuration values with parameter overrides
+        effective_discount_rate = discount_rate if discount_rate is not None else network_config.get('discount_rate', 0.05)
+        
+        # Build network
+        if progress_callback:
+            progress_callback(10, "Building PyPSA network...")
+            
+        builder = NetworkBuilder()
+        network = builder.build_network(conn, network_id, scenario_id, progress_callback)
+        
+        if progress_callback:
+            progress_callback(50, f"Network built: {len(network.buses)} buses, {len(network.generators)} generators")
+        
+        # Apply constraints
+        constraint_applicator = ConstraintApplicator()
+        if constraints_dsl or progress_callback:
+            if progress_callback:
+                progress_callback(60, "Applying constraints...")
+            constraint_applicator.apply_constraints(conn, network_id, network, scenario_id, constraints_dsl)
+        
+        # Solve network
+        if progress_callback:
+            progress_callback(70, f"Solving with {solver_name}...")
+            
+        solver = NetworkSolver()
+        solve_result = solver.solve_network(
+            network, 
+            solver_name=solver_name,
+            solver_options=solver_options,
+            discount_rate=effective_discount_rate,  # Use effective discount rate from config
+            conn=conn,
+            network_id=network_id,
+            scenario_id=scenario_id,
+            constraint_applicator=constraint_applicator
+        )
+        
+        if progress_callback:
+            progress_callback(85, "Storing results...")
+        
+        # Store results - ALWAYS store results regardless of return_detailed_results flag
+        storage = ResultStorage()
+        storage_result = storage.store_results(
+            conn, network_id, network, solve_result, scenario_id
+        )
+        
+        if progress_callback:
+            progress_callback(100, "Solve completed successfully")
+        
+        # Return simple status if requested (for sidecar/async usage)
+        # Results are now stored in database regardless of this flag
+        if not return_detailed_results:
+            return {
+                "success": solve_result.get("success", False),
+                "message": "Solve completed successfully" if solve_result.get("success") else "Solve failed",
+                "error": solve_result.get("error") if not solve_result.get("success") else None,
+                "network_id": network_id,
+                "scenario_id": scenario_id
+            }
+        
+        # Combine results in comprehensive format for detailed analysis
+        comprehensive_result = {
+            **solve_result,
+            "storage_stats": storage_result,
+            "network_id": network_id,
+            "scenario_id": scenario_id
+        }
+        
+        # Transform to include sidecar-compatible format
+        return _transform_to_comprehensive_format(comprehensive_result)
+
+
+def build_pypsa_network(
+    db_path: str,
+    network_id: int,
+    scenario_id: Optional[int] = None,
+    progress_callback: Optional[Callable[[int, str], None]] = None
+) -> 'pypsa.Network':
+    """
+    Build PyPSA network object from database.
+    
+    This function loads all network data from the database and constructs
+    a PyPSA Network object ready for solving or analysis. Useful when you
+    want to inspect or modify the network before solving.
+    
+    Args:
+        db_path: Path to the database file
+        network_id: ID of the network to build
+        scenario_id: Optional scenario ID (uses master scenario if None)
+        progress_callback: Optional callback for progress updates
+        
+    Returns:
+        PyPSA Network object ready for solving
+        
+    Raises:
+        DatabaseError: If database operations fail
+        ValidationError: If network data is invalid
+        ImportError: If PyPSA is not available
+    """
+    with database_context(db_path) as conn:
+        builder = NetworkBuilder()
+        return builder.build_network(conn, network_id, scenario_id, progress_callback)
+
+
+def solve_pypsa_network(
+    network: 'pypsa.Network',
+    db_path: str,
+    network_id: int,
+    scenario_id: Optional[int] = None,
+    solver_name: str = "highs",
+    solver_options: Optional[Dict[str, Any]] = None,
+    store_results: bool = True,
+    progress_callback: Optional[Callable[[int, str], None]] = None
+) -> Dict[str, Any]:
+    """
+    Solve PyPSA network and optionally store results back to database.
+    
+    This function takes an existing PyPSA network (e.g., from build_pypsa_network),
+    solves it, and optionally stores the results back to the database.
+    
+    Args:
+        network: PyPSA Network object to solve
+        db_path: Path to the database file (needed for result storage)
+        network_id: ID of the network (for result storage)
+        scenario_id: Optional scenario ID
+        solver_name: Solver to use (default: "highs")
+        solver_options: Optional solver-specific options
+        store_results: Whether to store results back to database (default: True)
+        progress_callback: Optional callback for progress updates
+        
+    Returns:
+        Dictionary with solve results and statistics
+        
+    Raises:
+        DatabaseError: If database operations fail (when store_results=True)
+        ImportError: If PyPSA is not available
+    """
+    if progress_callback:
+        progress_callback(0, f"Solving network with {solver_name}...")
+    
+    # Solve network
+    solver = NetworkSolver()
+    solve_result = solver.solve_network(
+        network,
+        solver_name=solver_name,
+        solver_options=solver_options
+    )
+    
+    if progress_callback:
+        progress_callback(70, "Solve completed")
+    
+    # Store results if requested
+    if store_results:
+        if progress_callback:
+            progress_callback(80, "Storing results...")
+            
+        with database_context(db_path) as conn:
+            storage = ResultStorage()
+            storage_result = storage.store_results(
+                conn, network_id, network, solve_result, scenario_id
+            )
+            solve_result["storage_stats"] = storage_result
+    
+    if progress_callback:
+        progress_callback(100, "Complete")
+    
+    return solve_result
+
+
+def load_network_components(
+    db_path: str, 
+    network_id: int, 
+    scenario_id: Optional[int] = None
+) -> Dict[str, Any]:
+    """
+    Load all network components and attributes as structured data.
+    
+    This low-level function loads network data without building a PyPSA network.
+    Useful for analysis, validation, or building custom network representations.
+    
+    Args:
+        db_path: Path to the database file
+        network_id: ID of the network to load
+        scenario_id: Optional scenario ID
+        
+    Returns:
+        Dictionary containing all network components and metadata
+        
+    Raises:
+        DatabaseError: If database operations fail
+    """
+    with database_context(db_path) as conn:
+        builder = NetworkBuilder()
+        return builder.load_network_data(conn, network_id, scenario_id)
+
+
+def apply_constraints(
+    network: 'pypsa.Network',
+    db_path: str,
+    network_id: int,
+    scenario_id: Optional[int] = None,
+    constraints_dsl: Optional[str] = None
+) -> None:
+    """
+    Apply custom constraints to PyPSA network.
+    
+    This function applies database-stored constraints and optional DSL constraints
+    to an existing PyPSA network. Modifies the network in-place.
+    
+    Args:
+        network: PyPSA Network object to modify
+        db_path: Path to the database file
+        network_id: ID of the network
+        scenario_id: Optional scenario ID
+        constraints_dsl: Optional DSL constraints string
+        
+    Raises:
+        DatabaseError: If database operations fail
+        ValidationError: If constraints are invalid
+    """
+    with database_context(db_path) as conn:
+        constraint_applicator = ConstraintApplicator()
+        constraint_applicator.apply_constraints(
+            conn, network_id, network, scenario_id, constraints_dsl
+        )
+
+
+def store_solve_results(
+    network: 'pypsa.Network',
+    db_path: str,
+    network_id: int,
+    scenario_id: Optional[int],
+    solve_metadata: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Store PyPSA solve results back to database.
+    
+    This low-level function stores solve results from a PyPSA network back
+    to the database. Useful when you want full control over the solving process
+    but still want to store results in the standard format.
+    
+    Args:
+        network: Solved PyPSA Network object
+        db_path: Path to the database file
+        network_id: ID of the network
+        scenario_id: Scenario ID for result storage
+        solve_metadata: Dictionary with solve metadata (solver_name, solve_time, etc.)
+        
+    Returns:
+        Dictionary with storage statistics
+        
+    Raises:
+        DatabaseError: If database operations fail
+    """
+    with database_context(db_path) as conn:
+        storage = ResultStorage()
+        return storage.store_results(
+            conn, network_id, network, solve_metadata, scenario_id
+        )
+
+
+def _transform_to_comprehensive_format(pyconvexity_result: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Transform pyconvexity result to comprehensive format that includes both
+    the original structure and sidecar-compatible fields.
+    
+    This ensures compatibility with existing sidecar code while providing
+    a clean API for direct pyconvexity users.
+    
+    Args:
+        pyconvexity_result: Result from pyconvexity solve operations
+        
+    Returns:
+        Comprehensive result with both original and sidecar-compatible fields
+    """
+    try:
+        # Extract basic solve information
+        success = pyconvexity_result.get("success", False)
+        status = pyconvexity_result.get("status", "unknown")
+        solve_time = pyconvexity_result.get("solve_time", 0.0)
+        objective_value = pyconvexity_result.get("objective_value")
+        
+        # Extract storage stats
+        storage_stats = pyconvexity_result.get("storage_stats", {})
+        component_stats = storage_stats.get("component_stats", {})
+        network_stats = storage_stats.get("network_stats", {})
+        
+        # Create comprehensive result that includes both formats
+        comprehensive_result = {
+            # Original pyconvexity format (for direct users)
+            **pyconvexity_result,
+            
+            # Sidecar-compatible format (for backward compatibility)
+            "network_statistics": {
+                "total_generation_mwh": network_stats.get("total_generation_mwh", 0.0),
+                "total_load_mwh": network_stats.get("total_load_mwh", 0.0),
+                "unmet_load_mwh": network_stats.get("unmet_load_mwh", 0.0),
+                "total_cost": network_stats.get("total_cost", objective_value or 0.0),
+                "num_buses": network_stats.get("num_buses", 0),
+                "num_generators": network_stats.get("num_generators", 0),
+                "num_loads": network_stats.get("num_loads", 0),
+                "num_lines": network_stats.get("num_lines", 0),
+                "num_links": network_stats.get("num_links", 0)
+            },
+            
+            "component_storage_stats": {
+                "stored_bus_results": component_stats.get("stored_bus_results", 0),
+                "stored_generator_results": component_stats.get("stored_generator_results", 0),
+                "stored_unmet_load_results": component_stats.get("stored_unmet_load_results", 0),
+                "stored_load_results": component_stats.get("stored_load_results", 0),
+                "stored_line_results": component_stats.get("stored_line_results", 0),
+                "stored_link_results": component_stats.get("stored_link_results", 0),
+                "stored_storage_unit_results": component_stats.get("stored_storage_unit_results", 0),
+                "stored_store_results": component_stats.get("stored_store_results", 0),
+                "skipped_attributes": component_stats.get("skipped_attributes", 0),
+                "errors": component_stats.get("errors", 0)
+            },
+            
+            # Additional compatibility fields
+            "multi_period": pyconvexity_result.get("multi_period", False),
+            "years": pyconvexity_result.get("years", [])
+        }
+        
+        return comprehensive_result
+        
+    except Exception as e:
+        logger.error(f"Failed to transform result to comprehensive format: {e}", exc_info=True)
+        # Return original result with error info if transformation fails
+        return {
+            **pyconvexity_result,
+            "transformation_error": str(e),
+            "network_statistics": {},
+            "component_storage_stats": {}
+        }