pyconvexity 0.4.8__py3-none-any.whl

pyconvexity/core/types.py

@@ -0,0 +1,400 @@
+"""
+Core data types for PyConvexity.
+
+These types mirror the Rust implementation while providing Python-specific
+enhancements and better type safety.
+"""
+
+import json
+from dataclasses import dataclass
+from typing import Dict, Any, Optional, List, Union
+
+
+class StaticValue:
+    """
+    Represents a static (non-time-varying) attribute value.
+
+    Mirrors the Rust StaticValue enum while providing Python conveniences.
+    Supports float, int, bool, and string values with proper type conversion.
+    """
+
+    def __init__(self, value: Union[float, int, bool, str]):
+        # Check bool before int since bool is subclass of int in Python
+        if isinstance(value, bool):
+            self.data = {"Boolean": value}
+        elif isinstance(value, float):
+            self.data = {"Float": value}
+        elif isinstance(value, int):
+            self.data = {"Integer": value}
+        elif isinstance(value, str):
+            self.data = {"String": value}
+        else:
+            raise ValueError(f"Unsupported value type: {type(value)}")
+
+    def to_json(self) -> str:
+        """
+        Return raw value as JSON to match Rust serialization format.
+
+        Rust stores: 123.45, 42, true, "hello"
+        Not: {"Float": 123.45}, {"Integer": 42}, etc.
+        """
+        import math
+
+        if "Float" in self.data:
+            float_val = self.data["Float"]
+            # Ensure finite values only
+            if not math.isfinite(float_val):
+                raise ValueError(
+                    f"Cannot serialize non-finite float value: {float_val}"
+                )
+            return json.dumps(float_val)
+        elif "Integer" in self.data:
+            return json.dumps(self.data["Integer"])
+        elif "Boolean" in self.data:
+            return json.dumps(self.data["Boolean"])
+        elif "String" in self.data:
+            return json.dumps(self.data["String"])
+        else:
+            # Fallback to original format if unknown
+            return json.dumps(self.data)
+
+    def data_type(self) -> str:
+        """Get data type name - mirrors Rust implementation"""
+        if "Float" in self.data:
+            return "float"
+        elif "Integer" in self.data:
+            return "int"
+        elif "Boolean" in self.data:
+            return "boolean"
+        elif "String" in self.data:
+            return "string"
+        else:
+            return "unknown"
+
+    def as_f64(self) -> float:
+        """Convert to float, mirroring Rust implementation"""
+        if "Float" in self.data:
+            return self.data["Float"]
+        elif "Integer" in self.data:
+            return float(self.data["Integer"])
+        elif "Boolean" in self.data:
+            return 1.0 if self.data["Boolean"] else 0.0
+        else:
+            try:
+                return float(self.data["String"])
+            except ValueError:
+                return 0.0
+
+    def value(self) -> Union[float, int, bool, str]:
+        """Get the raw Python value"""
+        if "Float" in self.data:
+            return self.data["Float"]
+        elif "Integer" in self.data:
+            return self.data["Integer"]
+        elif "Boolean" in self.data:
+            return self.data["Boolean"]
+        elif "String" in self.data:
+            return self.data["String"]
+        else:
+            raise ValueError("Unknown data type in StaticValue")
+
+    def __repr__(self) -> str:
+        return f"StaticValue({self.value()})"
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, StaticValue):
+            return self.data == other.data
+        return False
+
+
+@dataclass
+class Timeseries:
+    """
+    Efficient timeseries data structure matching the new Rust implementation.
+
+    Stores values as a flat array for maximum performance, matching the
+    unified Rust Timeseries struct.
+    """
+
+    values: List[float]
+    length: int
+    start_index: int
+    data_type: str
+    unit: Optional[str]
+    is_input: bool
+
+    def __post_init__(self):
+        # Ensure length matches values array
+        self.length = len(self.values)
+        # Ensure all values are float32-compatible
+        self.values = [float(v) for v in self.values]
+
+    def get_value(self, index: int) -> Optional[float]:
+        """Get value at specific index."""
+        if 0 <= index < len(self.values):
+            return self.values[index]
+        return None
+
+    def get_range(self, start: int, end: int) -> List[float]:
+        """Get a range of values efficiently."""
+        end = min(end, len(self.values))
+        start = min(start, end)
+        return self.values[start:end]
+
+    def sample(self, max_points: int) -> "Timeseries":
+        """Apply sampling if the timeseries is too large."""
+        if len(self.values) <= max_points:
+            return self
+
+        step = len(self.values) // max_points
+        sampled_values = []
+
+        for i in range(0, len(self.values), max(1, step)):
+            sampled_values.append(self.values[i])
+
+        # Always include the last point if not already included
+        if self.values and sampled_values[-1] != self.values[-1]:
+            sampled_values.append(self.values[-1])
+
+        return Timeseries(
+            values=sampled_values,
+            length=len(sampled_values),
+            start_index=self.start_index,
+            data_type=self.data_type,
+            unit=self.unit,
+            is_input=self.is_input,
+        )
+
+    def slice(self, start_index: int, end_index: int) -> "Timeseries":
+        """Apply range filtering."""
+        start = max(0, start_index - self.start_index)
+        end = max(0, end_index - self.start_index)
+        end = min(end, len(self.values))
+        start = min(start, end)
+
+        return Timeseries(
+            values=self.values[start:end],
+            length=end - start,
+            start_index=self.start_index + start,
+            data_type=self.data_type,
+            unit=self.unit,
+            is_input=self.is_input,
+        )
+
+
+@dataclass
+class TimeseriesMetadata:
+    """
+    Metadata about a timeseries without loading the full data.
+
+    Mirrors Rust TimeseriesMetadata struct.
+    """
+
+    length: int
+    start_time: int
+    end_time: int
+    start_index: int
+    end_index: int
+    data_type: str
+    unit: Optional[str]
+    is_input: bool
+
+
+@dataclass
+class TimePeriod:
+    """
+    Represents a time period in the network's time axis.
+
+    Mirrors Rust TimePeriod structure.
+    """
+
+    timestamp: int
+    period_index: int
+    formatted_time: str
+
+
+@dataclass
+class TimeseriesValidationResult:
+    """
+    Result of validating timeseries alignment with network time periods.
+
+    Mirrors Rust TimeseriesValidationResult.
+    """
+
+    is_valid: bool
+    missing_periods: List[int]
+    extra_periods: List[int]
+    total_network_periods: int
+    provided_periods: int
+
+
+@dataclass
+class ValidationRule:
+    """
+    Validation rule for component attributes.
+
+    Mirrors Rust ValidationRule with all fields.
+    """
+
+    component_type: str
+    attribute_name: str
+    data_type: str
+    unit: Optional[str]
+    default_value_string: Optional[str]
+    allowed_storage_types: str
+    allows_static: bool
+    allows_timeseries: bool
+    is_required: bool
+    is_input: bool
+    description: Optional[str]
+    default_value: Optional[StaticValue]
+
+
+class AttributeValue:
+    """
+    Represents either a static value or timeseries data for a component attribute.
+
+    Uses efficient Timeseries format for optimal performance.
+    Mirrors Rust AttributeValue enum.
+    """
+
+    def __init__(self, value: Union[StaticValue, Timeseries]):
+        if isinstance(value, StaticValue):
+            self.variant = "Static"
+            self.static_value = value
+            self.timeseries_value = None
+        elif isinstance(value, Timeseries):
+            self.variant = "Timeseries"
+            self.static_value = None
+            self.timeseries_value = value
+        else:
+            raise ValueError(
+                f"AttributeValue must be StaticValue or Timeseries, got {type(value)}"
+            )
+
+    @classmethod
+    def static(cls, value: StaticValue) -> "AttributeValue":
+        """Create a static attribute value"""
+        return cls(value)
+
+    @classmethod
+    def timeseries(cls, timeseries: Timeseries) -> "AttributeValue":
+        """Create a timeseries attribute value (new format)"""
+        return cls(timeseries)
+
+    def is_static(self) -> bool:
+        """Check if this is a static value"""
+        return self.variant == "Static"
+
+    def is_timeseries(self) -> bool:
+        """Check if this is a timeseries value"""
+        return self.variant == "Timeseries"
+
+    def as_timeseries(self) -> Optional[Timeseries]:
+        """Get the timeseries data in new format"""
+        return self.timeseries_value if self.is_timeseries() else None
+
+    def __repr__(self) -> str:
+        if self.is_static():
+            return f"AttributeValue.static({self.static_value})"
+        else:
+            length = len(self.timeseries_value.values) if self.timeseries_value else 0
+            return f"AttributeValue.timeseries({length} points)"
+
+
+@dataclass
+class Component:
+    """
+    Represents a component in the energy system model (single network per database).
+
+    Mirrors Rust Component struct.
+    """
+
+    id: int
+    component_type: str
+    name: str
+    longitude: Optional[float] = None
+    latitude: Optional[float] = None
+    carrier_id: Optional[int] = None
+    bus_id: Optional[int] = None
+    bus0_id: Optional[int] = None
+    bus1_id: Optional[int] = None
+
+
+@dataclass
+class Network:
+    """
+    Represents a network/model in the system.
+
+    Enhanced version of network information with additional metadata.
+    """
+
+    id: int
+    name: str
+    description: Optional[str] = None
+    time_start: Optional[str] = None
+    time_end: Optional[str] = None
+    time_interval: Optional[str] = None
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None
+
+
+@dataclass
+class CreateComponentRequest:
+    """
+    Request structure for creating a new component (single network per database).
+
+    Mirrors Rust CreateComponentRequest.
+    """
+
+    component_type: str
+    name: str
+    description: Optional[str] = None
+    longitude: Optional[float] = None
+    latitude: Optional[float] = None
+    carrier_id: Optional[int] = None
+    bus_id: Optional[int] = None
+    bus0_id: Optional[int] = None
+    bus1_id: Optional[int] = None
+
+
+@dataclass
+class CreateNetworkRequest:
+    """
+    Request structure for creating a new network.
+
+    Mirrors Rust CreateNetworkRequest.
+    """
+
+    name: str
+    description: Optional[str] = None
+    time_resolution: Optional[str] = None
+    start_time: Optional[str] = None
+    end_time: Optional[str] = None
+
+
+@dataclass
+class Carrier:
+    """
+    Represents an energy carrier (e.g., electricity, heat, gas).
+    """
+
+    id: int
+    name: str
+    co2_emissions: float = 0.0
+    color: Optional[str] = None
+    nice_name: Optional[str] = None
+
+
+@dataclass
+class Scenario:
+    """
+    Represents a scenario within a network.
+    """
+
+    id: int
+    name: str
+    description: Optional[str] = None
+    is_master: bool = False
+    created_at: Optional[str] = None
+    updated_at: Optional[str] = None

pyconvexity/dashboard.py

@@ -0,0 +1,265 @@
+"""
+Dashboard configuration for Convexity app visualization.
+
+Allows programmatic configuration of the analytics dashboard layout
+that will be displayed when the model is loaded in the Convexity app.
+
+Example:
+    >>> from pyconvexity.dashboard import set_dashboard_config, DashboardConfig, auto_layout
+    >>> 
+    >>> charts = [
+    ...     {
+    ...         "id": "dispatch-1",
+    ...         "title": "Generation by Carrier",
+    ...         "visible": True,
+    ...         "view": {
+    ...             "timeseries": {
+    ...                 "component": "Generator",
+    ...                 "attribute": "p",
+    ...                 "group_by": "carrier"
+    ...             }
+    ...         }
+    ...     },
+    ...     {
+    ...         "id": "lmp-1",
+    ...         "title": "Locational Marginal Prices",
+    ...         "visible": True,
+    ...         "view": {
+    ...             "timeseries": {
+    ...                 "component": "Bus",
+    ...                 "attribute": "marginal_price"
+    ...             }
+    ...         }
+    ...     }
+    ... ]
+    >>> 
+    >>> config = DashboardConfig(charts=charts, layout=auto_layout(charts))
+    >>> set_dashboard_config(conn, config)
+"""
+
+import json
+import sqlite3
+from dataclasses import dataclass, field, asdict
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class DashboardConfig:
+    """
+    Dashboard configuration for the Convexity app analytics view.
+    
+    Attributes:
+        charts: List of chart configurations. Each chart is a dict with:
+            - id: Unique identifier (e.g., "dispatch-1", "lmp-main")
+            - title: Display title
+            - visible: Whether chart is shown
+            - view: Chart type configuration (see below)
+            - filters: Optional chart-specific filters
+            
+        layout: List of layout positions. Each position is a dict with:
+            - i: Chart ID (must match a chart's id)
+            - x: Grid column (0-11)
+            - y: Grid row
+            - w: Width in grid units (max 12)
+            - h: Height in grid units
+            
+        selected_scenario_id: Pre-selected scenario ID (optional)
+        selected_ensemble_name: Pre-selected ensemble name (optional)
+        selected_bus_id: Pre-selected bus ID for filtering (optional)
+    
+    Chart View Types:
+        Timeseries (dispatch, LMP, etc.):
+            {"timeseries": {"component": "Generator", "attribute": "p", "group_by": "carrier"}}
+            {"timeseries": {"component": "Bus", "attribute": "marginal_price"}}
+            {"timeseries": {"component": "Load", "attribute": "p"}}
+            
+        Network map:
+            {"network": {"network": true}}
+            
+        Statistics/Summary:
+            {"statistic": {"statistic": "optimal_capacity", "metric": "capacity"}}
+            {"statistic": {"statistic": "total_cost"}}
+    """
+    charts: List[Dict[str, Any]]
+    layout: List[Dict[str, Any]]
+    selected_scenario_id: Optional[int] = None
+    selected_ensemble_name: Optional[str] = None
+    selected_bus_id: Optional[int] = None
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary for JSON serialization."""
+        result = {
+            "charts": self.charts,
+            "layout": self.layout,
+        }
+        # Only include optional fields if set (matches Rust's skip_serializing_if)
+        if self.selected_scenario_id is not None:
+            result["selected_scenario_id"] = self.selected_scenario_id
+        if self.selected_ensemble_name is not None:
+            result["selected_ensemble_name"] = self.selected_ensemble_name
+        if self.selected_bus_id is not None:
+            result["selected_bus_id"] = self.selected_bus_id
+        return result
+
+
+def set_dashboard_config(conn: sqlite3.Connection, config: DashboardConfig) -> int:
+    """
+    Save dashboard configuration to the database.
+    
+    This configuration will be loaded by the Convexity app when the model
+    is opened, setting up the analytics dashboard with the specified charts
+    and layout.
+    
+    Args:
+        conn: Database connection
+        config: Dashboard configuration
+        
+    Returns:
+        Row ID of the stored configuration
+        
+    Example:
+        >>> config = DashboardConfig(
+        ...     charts=[{"id": "dispatch-1", "title": "Dispatch", "visible": True, 
+        ...              "view": {"timeseries": {"component": "Generator", "attribute": "p", "group_by": "carrier"}}}],
+        ...     layout=[{"i": "dispatch-1", "x": 0, "y": 0, "w": 12, "h": 40}]
+        ... )
+        >>> set_dashboard_config(conn, config)
+    """
+    data_json = json.dumps(config.to_dict())
+    data_bytes = data_json.encode('utf-8')
+    
+    # Check if analytics config exists
+    cursor = conn.execute(
+        "SELECT id FROM network_data_store WHERE category = 'analytics_view' AND name = 'default'"
+    )
+    row = cursor.fetchone()
+    
+    if row:
+        # Update existing
+        row_id = row[0]
+        conn.execute(
+            "UPDATE network_data_store SET data = ?, updated_at = datetime('now') WHERE id = ?",
+            (data_bytes, row_id)
+        )
+    else:
+        # Insert new
+        conn.execute(
+            """INSERT INTO network_data_store (category, name, data_format, data, created_at, updated_at)
+               VALUES ('analytics_view', 'default', 'json', ?, datetime('now'), datetime('now'))""",
+            (data_bytes,)
+        )
+        row_id = conn.execute("SELECT last_insert_rowid()").fetchone()[0]
+    
+    conn.commit()
+    return row_id
+
+
+def get_dashboard_config(conn: sqlite3.Connection) -> Optional[DashboardConfig]:
+    """
+    Get the current dashboard configuration from the database.
+    
+    Args:
+        conn: Database connection
+        
+    Returns:
+        DashboardConfig if one exists, None otherwise
+    """
+    cursor = conn.execute(
+        """SELECT data FROM network_data_store 
+           WHERE category = 'analytics_view' 
+           ORDER BY updated_at DESC LIMIT 1"""
+    )
+    row = cursor.fetchone()
+    
+    if not row:
+        return None
+    
+    data_bytes = row[0]
+    if isinstance(data_bytes, bytes):
+        data_str = data_bytes.decode('utf-8')
+    else:
+        data_str = data_bytes
+        
+    data = json.loads(data_str)
+    
+    return DashboardConfig(
+        charts=data.get("charts", []),
+        layout=data.get("layout", []),
+        selected_scenario_id=data.get("selected_scenario_id"),
+        selected_ensemble_name=data.get("selected_ensemble_name"),
+        selected_bus_id=data.get("selected_bus_id"),
+    )
+
+
+def auto_layout(charts: List[Dict[str, Any]], cols: int = 12) -> List[Dict[str, Any]]:
+    """
+    Automatically generate layout positions for charts.
+    
+    Places charts in a vertical stack, each taking full width.
+    Timeseries charts get height 40, others get height 20.
+    
+    Args:
+        charts: List of chart configurations
+        cols: Grid columns (default 12)
+        
+    Returns:
+        List of layout position dicts
+        
+    Example:
+        >>> charts = [
+        ...     {"id": "dispatch-1", "title": "Dispatch", "visible": True, 
+        ...      "view": {"timeseries": {...}}},
+        ...     {"id": "network-1", "title": "Network", "visible": True,
+        ...      "view": {"network": {"network": True}}}
+        ... ]
+        >>> layout = auto_layout(charts)
+        >>> # Returns: [{"i": "dispatch-1", "x": 0, "y": 0, "w": 12, "h": 40}, ...]
+    """
+    layout = []
+    y = 0
+    
+    for chart in charts:
+        if not chart.get("visible", True):
+            continue
+            
+        chart_id = chart["id"]
+        view = chart.get("view", {})
+        
+        # Determine chart dimensions based on type
+        if "timeseries" in view:
+            w, h = 12, 40
+        elif "network" in view:
+            w, h = 6, 40
+        elif "statistic" in view:
+            w, h = 6, 20
+        else:
+            w, h = 12, 20
+        
+        layout.append({
+            "i": chart_id,
+            "x": 0,
+            "y": y,
+            "w": w,
+            "h": h,
+        })
+        
+        y += h
+    
+    return layout
+
+
+def clear_dashboard_config(conn: sqlite3.Connection) -> bool:
+    """
+    Remove any existing dashboard configuration.
+    
+    Args:
+        conn: Database connection
+        
+    Returns:
+        True if a config was deleted, False if none existed
+    """
+    cursor = conn.execute(
+        "DELETE FROM network_data_store WHERE category = 'analytics_view' AND name = 'default'"
+    )
+    conn.commit()
+    return cursor.rowcount > 0