pyconvexity 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

pyconvexity/timeseries.py

@@ -0,0 +1,327 @@
+"""
+High-level timeseries API for PyConvexity.
+
+This module provides the main interface for working with timeseries data,
+matching the efficient patterns used in the Rust implementation.
+
+Key Features:
+- Ultra-fast binary serialization (matches Rust exactly)
+- Array-based data structures for maximum performance
+- Unified API for getting/setting timeseries data
+- Backward compatibility with legacy point-based format
+- Efficient sampling and filtering operations
+"""
+
+import sqlite3
+from typing import List, Optional, Union
+import numpy as np
+
+from pyconvexity.core.database import database_context
+from pyconvexity.core.types import Timeseries, TimeseriesMetadata
+from pyconvexity.models.attributes import (
+    get_timeseries as _get_timeseries,
+    get_timeseries_metadata as _get_timeseries_metadata,
+    set_timeseries_attribute,
+    serialize_values_to_binary,
+    deserialize_values_from_binary,
+    get_timeseries_length_from_binary
+)
+
+
+# ============================================================================
+# HIGH-LEVEL TIMESERIES API
+# ============================================================================
+
+def get_timeseries(
+    db_path: str,
+    component_id: int,
+    attribute_name: str,
+    scenario_id: Optional[int] = None,
+    start_index: Optional[int] = None,
+    end_index: Optional[int] = None,
+    max_points: Optional[int] = None
+) -> Timeseries:
+    """
+    Get timeseries data with efficient array-based format.
+    
+    This is the main function for retrieving timeseries data. It returns
+    a Timeseries object with values as a flat array for maximum performance.
+    
+    Args:
+        db_path: Path to the database file
+        component_id: Component ID
+        attribute_name: Name of the attribute (e.g., 'p', 'p_set', 'marginal_cost')
+        scenario_id: Scenario ID (uses master scenario if None)
+        start_index: Start index for range queries (optional)
+        end_index: End index for range queries (optional)
+        max_points: Maximum number of points for sampling (optional)
+        
+    Returns:
+        Timeseries object with efficient array-based data
+        
+    Example:
+        >>> ts = get_timeseries("model.db", component_id=123, attribute_name="p")
+        >>> print(f"Length: {ts.length}, Values: {ts.values[:5]}")
+        Length: 8760, Values: [100.5, 95.2, 87.3, 92.1, 88.7]
+        
+        # Get a subset of the data
+        >>> ts_subset = get_timeseries("model.db", 123, "p", start_index=100, end_index=200)
+        >>> print(f"Subset length: {ts_subset.length}")
+        Subset length: 100
+        
+        # Sample large datasets
+        >>> ts_sampled = get_timeseries("model.db", 123, "p", max_points=1000)
+        >>> print(f"Sampled from {ts.length} to {ts_sampled.length} points")
+    """
+    with database_context(db_path, read_only=True) as conn:
+        return _get_timeseries(
+            conn, component_id, attribute_name, scenario_id,
+            start_index, end_index, max_points
+        )
+
+
+def get_timeseries_metadata(
+    db_path: str,
+    component_id: int,
+    attribute_name: str,
+    scenario_id: Optional[int] = None
+) -> TimeseriesMetadata:
+    """
+    Get timeseries metadata without loading the full data.
+    
+    This is useful for checking the size and properties of a timeseries
+    before deciding whether to load the full data.
+    
+    Args:
+        db_path: Path to the database file
+        component_id: Component ID
+        attribute_name: Name of the attribute
+        scenario_id: Scenario ID (uses master scenario if None)
+        
+    Returns:
+        TimeseriesMetadata with length and type information
+        
+    Example:
+        >>> meta = get_timeseries_metadata("model.db", 123, "p")
+        >>> print(f"Length: {meta.length}, Type: {meta.data_type}, Unit: {meta.unit}")
+        Length: 8760, Type: float, Unit: MW
+    """
+    with database_context(db_path, read_only=True) as conn:
+        return _get_timeseries_metadata(conn, component_id, attribute_name, scenario_id)
+
+
+def set_timeseries(
+    db_path: str,
+    component_id: int,
+    attribute_name: str,
+    values: Union[List[float], np.ndarray, Timeseries],
+    scenario_id: Optional[int] = None
+) -> None:
+    """
+    Set timeseries data using efficient array-based format.
+    
+    This is the main function for storing timeseries data. It accepts
+    various input formats and stores them efficiently in the database.
+    
+    Args:
+        db_path: Path to the database file
+        component_id: Component ID
+        attribute_name: Name of the attribute
+        values: Timeseries values as list, numpy array, or Timeseries object
+        scenario_id: Scenario ID (uses master scenario if None)
+        
+    Example:
+        # Set from a list
+        >>> values = [100.5, 95.2, 87.3, 92.1, 88.7]
+        >>> set_timeseries("model.db", 123, "p_set", values)
+        
+        # Set from numpy array
+        >>> import numpy as np
+        >>> values = np.random.normal(100, 10, 8760)  # Hourly data for a year
+        >>> set_timeseries("model.db", 123, "p_max_pu", values)
+        
+        # Set from existing Timeseries object
+        >>> ts = get_timeseries("model.db", 456, "p")
+        >>> set_timeseries("model.db", 123, "p_set", ts)
+    """
+    # Convert input to list of floats
+    if isinstance(values, Timeseries):
+        values_list = values.values
+    elif isinstance(values, np.ndarray):
+        values_list = values.tolist()
+    elif isinstance(values, list):
+        values_list = [float(v) for v in values]
+    else:
+        raise ValueError("values must be List[float], numpy.ndarray, or Timeseries")
+    
+    with database_context(db_path) as conn:
+        set_timeseries_attribute(conn, component_id, attribute_name, values_list, scenario_id)
+
+
+def get_multiple_timeseries(
+    db_path: str,
+    requests: List[dict],
+    max_points: Optional[int] = None
+) -> List[Timeseries]:
+    """
+    Get multiple timeseries efficiently in a single database connection.
+    
+    This is more efficient than calling get_timeseries multiple times
+    when you need to load many timeseries from the same database.
+    
+    Args:
+        db_path: Path to the database file
+        requests: List of dicts with keys: component_id, attribute_name, scenario_id (optional)
+        max_points: Maximum number of points for sampling (applied to all)
+        
+    Returns:
+        List of Timeseries objects in the same order as requests
+        
+    Example:
+        >>> requests = [
+        ...     {"component_id": 123, "attribute_name": "p"},
+        ...     {"component_id": 124, "attribute_name": "p"},
+        ...     {"component_id": 125, "attribute_name": "p", "scenario_id": 2}
+        ... ]
+        >>> timeseries_list = get_multiple_timeseries("model.db", requests)
+        >>> print(f"Loaded {len(timeseries_list)} timeseries")
+    """
+    results = []
+    
+    with database_context(db_path, read_only=True) as conn:
+        for request in requests:
+            component_id = request["component_id"]
+            attribute_name = request["attribute_name"]
+            scenario_id = request.get("scenario_id")
+            
+            ts = _get_timeseries(
+                conn, component_id, attribute_name, scenario_id,
+                None, None, max_points
+            )
+            results.append(ts)
+    
+    return results
+
+
+# ============================================================================
+# UTILITY FUNCTIONS
+# ============================================================================
+
+def timeseries_to_numpy(timeseries: Timeseries) -> np.ndarray:
+    """
+    Convert Timeseries to numpy array for scientific computing.
+    
+    Args:
+        timeseries: Timeseries object
+        
+    Returns:
+        numpy array with float32 dtype for memory efficiency
+        
+    Example:
+        >>> ts = get_timeseries("model.db", 123, "p")
+        >>> arr = timeseries_to_numpy(ts)
+        >>> print(f"Mean: {arr.mean():.2f}, Std: {arr.std():.2f}")
+    """
+    return np.array(timeseries.values, dtype=np.float32)
+
+
+def numpy_to_timeseries(
+    array: np.ndarray,
+    data_type: str = "float",
+    unit: Optional[str] = None,
+    is_input: bool = True
+) -> Timeseries:
+    """
+    Convert numpy array to Timeseries object.
+    
+    Args:
+        array: numpy array of values
+        data_type: Data type string (default: "float")
+        unit: Unit string (optional)
+        is_input: Whether this is input data (default: True)
+        
+    Returns:
+        Timeseries object
+        
+    Example:
+        >>> import numpy as np
+        >>> arr = np.random.normal(100, 10, 8760)
+        >>> ts = numpy_to_timeseries(arr, unit="MW")
+        >>> print(f"Created timeseries with {ts.length} points")
+    """
+    values = array.tolist() if hasattr(array, 'tolist') else list(array)
+    return Timeseries(
+        values=[float(v) for v in values],
+        length=len(values),
+        start_index=0,
+        data_type=data_type,
+        unit=unit,
+        is_input=is_input
+    )
+
+
+def validate_timeseries_alignment(
+    db_path: str,
+    network_id: int,
+    values: Union[List[float], np.ndarray, Timeseries]
+) -> dict:
+    """
+    Validate that timeseries data aligns with network time periods.
+    
+    Args:
+        db_path: Path to the database file
+        network_id: Network ID
+        values: Timeseries values to validate
+        
+    Returns:
+        Dictionary with validation results
+        
+    Example:
+        >>> values = [100.0] * 8760  # Hourly data for a year
+        >>> result = validate_timeseries_alignment("model.db", 1, values)
+        >>> if result["is_valid"]:
+        ...     print("Timeseries is properly aligned")
+        ... else:
+        ...     print(f"Alignment issues: {result['issues']}")
+    """
+    # Convert to list of floats
+    if isinstance(values, Timeseries):
+        values_list = values.values
+    elif isinstance(values, np.ndarray):
+        values_list = values.tolist()
+    elif isinstance(values, list):
+        values_list = [float(v) for v in values]
+    else:
+        raise ValueError("values must be List[float], numpy.ndarray, or Timeseries")
+    
+    with database_context(db_path, read_only=True) as conn:
+        # Get network time periods
+        from pyconvexity.models.network import get_network_time_periods
+        try:
+            time_periods = get_network_time_periods(conn, network_id)
+            expected_length = len(time_periods)
+            actual_length = len(values_list)
+            
+            is_valid = actual_length == expected_length
+            issues = []
+            
+            if actual_length < expected_length:
+                issues.append(f"Missing {expected_length - actual_length} time periods")
+            elif actual_length > expected_length:
+                issues.append(f"Extra {actual_length - expected_length} time periods")
+            
+            return {
+                "is_valid": is_valid,
+                "expected_length": expected_length,
+                "actual_length": actual_length,
+                "issues": issues
+            }
+            
+        except Exception as e:
+            return {
+                "is_valid": False,
+                "expected_length": 0,
+                "actual_length": len(values_list),
+                "issues": [f"Failed to get network time periods: {e}"]
+            }
+

pyconvexity/validation/rules.py

@@ -10,7 +10,7 @@ import logging
 from typing import Dict, Any, Optional, List
 
 from pyconvexity.core.types import (
-    ValidationRule, StaticValue, TimeseriesPoint, TimePeriod, TimeseriesValidationResult
+    ValidationRule, StaticValue, TimePeriod, TimeseriesValidationResult
 )
 from pyconvexity.core.errors import (
     ValidationError, InvalidDataType
@@ -194,7 +194,7 @@ def validate_static_value(value: StaticValue, rule: ValidationRule) -> None:
 def validate_timeseries_alignment(
     conn: sqlite3.Connection,
     network_id: int,
-    timeseries: List[TimeseriesPoint]
+    timeseries: List[float]
 ) -> TimeseriesValidationResult:
     """
     Validate timeseries alignment with network periods.

{pyconvexity-0.1.2.dist-info → pyconvexity-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyconvexity
-Version: 0.1.2
+Version: 0.1.4
 Summary: Python library for energy system modeling and optimization with PyPSA
 Author-email: Convexity Team <info@convexity.com>
 License: MIT
@@ -32,6 +32,9 @@ Requires-Dist: xlsxwriter>=3.0.0; extra == "excel"
 Provides-Extra: netcdf
 Requires-Dist: netcdf4>=1.6.0; extra == "netcdf"
 Requires-Dist: xarray>=2022.3.0; extra == "netcdf"
+Provides-Extra: data
+Requires-Dist: country-converter>=1.0.0; extra == "data"
+Requires-Dist: pyyaml>=6.0.0; extra == "data"
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
@@ -40,7 +43,7 @@ Requires-Dist: isort>=5.10.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: pre-commit>=2.20.0; extra == "dev"
 Provides-Extra: all
-Requires-Dist: pyconvexity[excel,netcdf,pypsa]; extra == "all"
+Requires-Dist: pyconvexity[data,excel,netcdf,pypsa]; extra == "all"
 
 # PyConvexity
 

pyconvexity-0.1.4.dist-info/RECORD

@@ -0,0 +1,46 @@
+pyconvexity/__init__.py,sha256=eiAFroO4n-z8F0jTLpJgBIO7vtSxu9ovu3G2N-qqpUo,4783
+pyconvexity/_version.py,sha256=Wzf5T3NBDfhQoTnhnRNHSlAsE0XMqbclXG-M81Vas70,22
+pyconvexity/timeseries.py,sha256=4p1Tdpa1otqDvCq2zppA4tw660sF_XWb8Xobib-cCms,11340
+pyconvexity/core/__init__.py,sha256=MgVa5rrRWIi2w1UI1P4leiBntvHeeOPv0Thm0DEXBHo,1209
+pyconvexity/core/database.py,sha256=M02q4UkJqAPeTXuwng9I7kHm16reJ7eq7wccWxnhE5I,15227
+pyconvexity/core/errors.py,sha256=HhrrOOEBJrzyB56_pmqh3NWvX6uHqWWNkdE5XM16rYI,2881
+pyconvexity/core/types.py,sha256=LkB49qklA-9ObI0br0IazfVxvWvYzQrYMdwzrqqAMYQ,11335
+pyconvexity/data/README.md,sha256=-tyDHVjqzfWbVvgM4yYYx8cysmgvFXI6plVQNxSHBmo,3156
+pyconvexity/data/__init__.py,sha256=BrgC3LGSlReLbC0EpM6UxywwUHxRvts379CvZFE0qWU,514
+pyconvexity/data/__pycache__/__init__.cpython-313.pyc,sha256=F2XXlQZlN5aoFmi7Ar1B3RW-DZjIUqp81fr3zNsPxpY,617
+pyconvexity/data/loaders/__init__.py,sha256=6xPtOmH2n1mNby7ZjA-2Mk9F48Q246RNsyMnCnJ6gwA,60
+pyconvexity/data/loaders/cache.py,sha256=nnz8bV3slSehOT0alexFga9tM1XoJqWHBGqaXvz132U,7299
+pyconvexity/data/loaders/__pycache__/__init__.cpython-313.pyc,sha256=AuT3aXy3v5gssxdD1_CBaKqNAVmDt6GBwFSyAe3jHow,265
+pyconvexity/data/loaders/__pycache__/cache.cpython-313.pyc,sha256=9_xMQN6AciMzbzhCmWAzvEKRXfRINmfRsO8Dyg0_CUQ,9804
+pyconvexity/data/schema/01_core_schema.sql,sha256=Ww3eD71JGIBNw-t_eVJ6TVGju-sEDzpLqyRGqGDje54,18871
+pyconvexity/data/schema/02_data_metadata.sql,sha256=oOfwa3PLY2_8rxKDD4cpDeqP5I_PdahcF8m6cSKStJM,10732
+pyconvexity/data/schema/03_validation_data.sql,sha256=1rKFi9y6jQ2OnfH32jnIKnZ5WtB8eG43hz0OVJhwn3w,58325
+pyconvexity/data/schema/04_scenario_schema.sql,sha256=sL4PySJNHIthXsnoJ2T5pdXUbpAi94ld0XGuU8LwNuQ,4641
+pyconvexity/data/sources/__init__.py,sha256=Dn6_oS7wB-vLjMj2YeXlmIl6hNjACbicimSabKxIWnc,108
+pyconvexity/data/sources/gem.py,sha256=Ft2pAYsWe1V9poRge2Q4xdNt15XkG-USSR0XR9KFmsY,14935
+pyconvexity/data/sources/__pycache__/__init__.cpython-313.pyc,sha256=9x5FyLxmTE5ZRaEFNSF375KBd_rDLY6pGHGSWPpcxxA,313
+pyconvexity/data/sources/__pycache__/gem.cpython-313.pyc,sha256=CFyCxtqSg-_M9PiGgWcXl4A3OGDrfYi6NHFpDXW8__Q,14485
+pyconvexity/io/__init__.py,sha256=glGzXBRGHROrTS8xe-RTGyRQUgsaksafxXVt9GpW63E,803
+pyconvexity/io/excel_exporter.py,sha256=pjgvTs5vq9K61mNOVutEzaH5Zx4FgrDG4Xc_YmXhE5o,48483
+pyconvexity/io/excel_importer.py,sha256=M7YcBqKUVzOMoR5HN-v8M2UnZgHRfhqgXBMUVD10-IQ,56898
+pyconvexity/io/netcdf_exporter.py,sha256=AMM-uXBj8sh86n5m57aZ6S7LulAyIx_HM-eM-26BrWQ,7428
+pyconvexity/io/netcdf_importer.py,sha256=nv4CYYqnbCBeznwCU_JGBMTbg-BGNpXKlsqbu2R8fTU,72152
+pyconvexity/models/__init__.py,sha256=-CEdfjwOp-6XvR4vVyV1Z6umF1axs82zzvv7VRZNcys,1690
+pyconvexity/models/attributes.py,sha256=LTvYF0hl56HeLjS8ZVocZWLhbLRTNhmZ5gUKxf93eSE,18254
+pyconvexity/models/components.py,sha256=yccDW9ROtjsk5eIO38Tr420VUj9KeV03IVLrfmZgj3c,14942
+pyconvexity/models/network.py,sha256=ePydR3l60-AaOBbrA4uld3hu3X9sB7GOSyBYMh3_rBA,13117
+pyconvexity/models/scenarios.py,sha256=6-devNWZccnFeQr3IsP19GkO6Ixp914RKD-6lIduN-A,5164
+pyconvexity/solvers/__init__.py,sha256=zoVf6T2Tmyj2XOeiVbEvaIMOX584orqCz1q9t1oXy0M,674
+pyconvexity/solvers/pypsa/__init__.py,sha256=KZqYDo7CvwB-5Kp784xxxtdn5kRcmn3gGSRlaQdDA4c,554
+pyconvexity/solvers/pypsa/api.py,sha256=u1MTSZkCxXMukSUQ83oDz_pWf4kRXKV_Bk7b0yd7lV4,16762
+pyconvexity/solvers/pypsa/batch_loader.py,sha256=eQb8B11akQYtH3aK93WAOoXEI-ktk4imATw9gaYDNR4,13547
+pyconvexity/solvers/pypsa/builder.py,sha256=ikcLPzcrTE0e3Fv6zZPIUTTEL0zMDMYI0s8te6sA0j4,24174
+pyconvexity/solvers/pypsa/constraints.py,sha256=uX0X_EDFak7YtnjgNxj3CSv1nxDQI-fT4eg9lyySAv4,13678
+pyconvexity/solvers/pypsa/solver.py,sha256=NFZ4_8inW-xHkv7pTrfq09vkKFINDwdTuJAQTn8lMfg,54555
+pyconvexity/solvers/pypsa/storage.py,sha256=T-0qEryiEy_8G4KiscPoiiWvTPd_OGqpLczW0_Xm85E,87331
+pyconvexity/validation/__init__.py,sha256=_6SVqXkaDFqmagub_O064Zm_QIdBrOra-Gvvbo9vM4I,549
+pyconvexity/validation/rules.py,sha256=6Kak12BVfUpjmgB5B7Wre55eGc5e1dvIdFca-vN-IFI,9296
+pyconvexity-0.1.4.dist-info/METADATA,sha256=fN4rhmba5CvT3EWLdpadovCMQUvZSZC7pcuV-Q1eD44,4880
+pyconvexity-0.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pyconvexity-0.1.4.dist-info/top_level.txt,sha256=wFPEDXVaebR3JO5Tt3HNse-ws5aROCcxEco15d6j64s,12
+pyconvexity-0.1.4.dist-info/RECORD,,

pyconvexity-0.1.2.dist-info/RECORD

@@ -1,20 +0,0 @@
-pyconvexity/__init__.py,sha256=mEtafBwQ1A9s-hEv3o3XeXlJ7iFtbdS691wVUUw5miY,3303
-pyconvexity/_version.py,sha256=Cu2pGbVzHvik6YUUC3R9lxs9dHnXZq1Uj0YfLLblLUs,133
-pyconvexity/core/__init__.py,sha256=4SYAE4zqzGIRFSP4IoT7EzK-LCTB1HLe9EWhfi2aUmU,1253
-pyconvexity/core/database.py,sha256=4OW1sgwDT4ltxdW6b250ytTlsC9sk26Rz0VrveXSL4A,9605
-pyconvexity/core/errors.py,sha256=HhrrOOEBJrzyB56_pmqh3NWvX6uHqWWNkdE5XM16rYI,2881
-pyconvexity/core/types.py,sha256=eoVOAcDJWzjJKO9lYN7O17Us0XbahBpVBwv6uxdldh0,8508
-pyconvexity/data/schema/01_core_schema.sql,sha256=Vt6vASZEASPPQYuhtsARLj3PxP7VdZtfxmGcs-Id-xc,18785
-pyconvexity/data/schema/02_data_metadata.sql,sha256=9E7tnBBu0wc4w3YijyPf_vG_8KVFyu7cu59TyAP5F94,21818
-pyconvexity/data/schema/03_validation_data.sql,sha256=1rKFi9y6jQ2OnfH32jnIKnZ5WtB8eG43hz0OVJhwn3w,58325
-pyconvexity/data/schema/04_scenario_schema.sql,sha256=sL4PySJNHIthXsnoJ2T5pdXUbpAi94ld0XGuU8LwNuQ,4641
-pyconvexity/models/__init__.py,sha256=eVwf0ZTTEq1nM9M3NSMvj2yLPUOPNKMXv2A5GLT34-c,1470
-pyconvexity/models/attributes.py,sha256=gh02j_hpSeyCNg0Jt20i7Y7wOntajnuzI926W5wzA3Q,14130
-pyconvexity/models/components.py,sha256=K7QWelMVU_D18skvBZbap9dxP2AMS2116fcpmemkE6U,14629
-pyconvexity/models/network.py,sha256=-itmot8StUdXogDpZUhGVIUC5uAEucYQ1LiTN1vPdA4,12923
-pyconvexity/validation/__init__.py,sha256=_6SVqXkaDFqmagub_O064Zm_QIdBrOra-Gvvbo9vM4I,549
-pyconvexity/validation/rules.py,sha256=bshO2Ibw8tBurg708Dmf79rIBoGV32t-jNHltjap9Pw,9323
-pyconvexity-0.1.2.dist-info/METADATA,sha256=Lmk43_bNLN4jVbnqynhutZq9sK29vywiwbKBFjAWL7M,4751
-pyconvexity-0.1.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-pyconvexity-0.1.2.dist-info/top_level.txt,sha256=wFPEDXVaebR3JO5Tt3HNse-ws5aROCcxEco15d6j64s,12
-pyconvexity-0.1.2.dist-info/RECORD,,