Skip to content

PyConvexity Documentation

Welcome to PyConvexity - a Python library for energy system modeling and optimization.

Overview

PyConvexity provides a comprehensive toolkit for:

  • Energy System Modeling: Define networks, components, and time series data
  • PyPSA Integration: Seamless conversion to and from PyPSA networks
  • Data Import/Export: Excel and NetCDF file support
  • Optimization: Built-in solvers and optimization workflows
  • Validation: Robust data validation and type checking

Installation

pip install pyconvexity

Basic Usage

import pyconvexity as px
import numpy as np

# Create a new energy system model database
px.create_database_with_schema("my_model.db")

# Create a network
with px.database_context("my_model.db") as conn:
    network_req = px.CreateNetworkRequest(
        name="My Energy Network",
        description="Example renewable energy system",
        start_time="2024-01-01 00:00:00",
        end_time="2024-01-02 00:00:00",
        time_resolution="H"
    )
    network_id = px.create_network(conn, network_req)

    # Create carriers (energy types)
    ac_carrier = px.create_carrier(conn, network_id, "AC")

    # Create components
    bus_id = px.create_component(
        conn, network_id, "BUS", "Main Bus",
        latitude=40.7128, longitude=-74.0060,
        carrier_id=ac_carrier
    )

    # Set component attributes
    px.set_static_attribute(conn, bus_id, "v_nom", px.StaticValue(230.0))

    conn.commit()

# Work with timeseries data (high-performance API)
solar_profile = np.maximum(0, np.sin(np.linspace(0, np.pi, 24)) * 100)
px.set_timeseries("my_model.db", generator_id, "p_max_pu", solar_profile)

# Get timeseries data
ts = px.get_timeseries("my_model.db", generator_id, "p_max_pu")
print(f"✅ Created network {network_id} with {ts.length} hourly data points")

Features

🔋 Core Functionality

  • Network and component management
  • Ultra-fast timeseries data handling (binary serialization)
  • Attribute validation and type safety
  • High-level API for common operations

🔌 PyPSA Integration

  • Automatic network conversion
  • Batch data loading for performance
  • Full PyPSA component support

📊 Data I/O

  • Excel import/export with validation
  • NetCDF file support
  • CSV data handling

âš¡ Optimization

  • Multiple solver support (HiGHS, Gurobi, etc.)
  • Optimization result analysis
  • Performance monitoring

License

This project is licensed under the MIT License.