Skip to content

Getting Started

This guide will help you get up and running with PyConvexity.

Installation

pip install pyconvexity

From Source

git clone https://github.com/bayesian-energy/convexity-js.git
cd convexity-js/pyconvexity
pip install -e .

Dependencies

PyConvexity requires Python 3.9+ and has the following core dependencies:

  • pandas - Data manipulation
  • numpy - Numerical computing
  • sqlalchemy - Database operations

Optional Dependencies

  • pypsa - For PyPSA network integration
  • openpyxl - For Excel file support
  • netcdf4 - For NetCDF file support
  • gurobipy - For Gurobi optimization

Quick Start

1. Create a Database and Network

import pyconvexity as px

# Create a new database with schema
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 First Network",
        description="A simple 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)
    print(f"Created network ID: {network_id}")

2. Add Components

with px.database_context("my_model.db") as conn:
    # Create carriers (energy types)
    ac_carrier = px.create_carrier(conn, network_id, "AC")

    # Create a bus
    bus_id = px.create_component(
        conn, network_id, "BUS", "main_bus",
        latitude=40.7128, longitude=-74.0060,
        carrier_id=ac_carrier
    )

    # Create a generator
    generator_id = px.create_component(
        conn, network_id, "GENERATOR", "solar_pv",
        bus_id=bus_id, carrier_id=ac_carrier
    )

    conn.commit()

3. Set Attributes

# Set static attributes
with px.database_context("my_model.db") as conn:
    # Set generator capacity
    px.set_static_attribute(conn, generator_id, "p_nom", px.StaticValue(100.0))

    # Set bus voltage
    px.set_static_attribute(conn, bus_id, "v_nom", px.StaticValue(230.0))

    conn.commit()

4. Add Timeseries Data

import numpy as np

# Generate hourly solar generation profile
hours = 24
solar_profile = np.maximum(0, np.sin(np.linspace(0, np.pi, hours)) * 100)

# Set timeseries data using high-level API
px.set_timeseries(
    "my_model.db", 
    component_id=generator_id, 
    attribute_name="p_max_pu", 
    values=solar_profile
)

# Get timeseries data
ts = px.get_timeseries("my_model.db", generator_id, "p_max_pu")
print(f"Timeseries length: {ts.length}, First 5 values: {ts.values[:5]}")

5. Build PyPSA Network

from pyconvexity.solvers.pypsa import build_pypsa_network

# Convert to PyPSA network
with px.database_context("my_model.db") as conn:
    pypsa_network = build_pypsa_network(conn, network_id)
    print(f"PyPSA network created with {len(pypsa_network.buses)} buses")

    # Run optimization
    pypsa_network.optimize()
    print("Optimization completed!")

Next Steps

Need Help?