API Reference

This section provides detailed API documentation for all PyEPlan modules and classes.

Core Modules

Data Processing Module (datsys)

The data processing module handles historical weather data extraction and representative day clustering using PVGIS API.

class pyeplan.datsys(inp_folder='', lat=0.251148605450955, lon=32.404833929733, year=2016, pvcalc=1, pp=50, sys_loss=14, n_clust=1, pf_c=1, pf_p=1, sbase=1000, raddatabase=None)[source]

Bases: object

Data processing system for microgrid planning and operation.

This class handles all data processing operations including renewable energy resource assessment, time series clustering, and load profile processing. It integrates with PVGIS API to fetch solar irradiance and wind speed data for any location worldwide.

Variables:

  • loc – Load point locations and coordinates (pd.DataFrame)

  • pdem – Active power demand profiles (pd.DataFrame)

  • prep – Active power renewable generation profiles (pd.DataFrame)

  • lat – Latitude in decimal degrees (south is negative) (float)

  • lon – Longitude in decimal degrees (west is negative) (float)

  • startyear – Start year for data collection (int)

  • endyear – End year for data collection (int)

  • pvcalculation – PV calculation method (0=radiation only, 1=power+radiation) (int)

  • peakpower – Nominal power of PV system in kW (float)

  • loss – Sum of system losses in % (float)

  • trackingtype – Type of sun tracking system (int)

  • optimalinclination – Calculate optimum inclination angle (1=yes) (int)

  • optimalangles – Calculate optimum inclination and orientation (1=yes) (int)

  • outputformat – Output format for PVGIS data (str)

  • browser – Output format (0=stream, 1=file) (int)

  • n_clust – Number of clusters for time series clustering (int)

  • pf_c – Power factor at consumption points (float)

  • pf_p – Power factor at production points (float)

  • sbase – Base apparent power in kW (float)

  • data_link – PVGIS API URL with parameters (str)

  • data – Raw data from PVGIS API (pd.DataFrame)

  • local_time_zone – Local timezone for the location (str)

  • qrep – Reactive power renewable generation profiles (pd.DataFrame)

  • qdem – Reactive power demand profiles (pd.DataFrame)

  • inp_folder – Input folder path for data files (str)

Methods

data_extract()[source]

Extract and process time series data from PVGIS.

This method processes the raw data obtained from PVGIS API and converts it to local timezone. It extracts PV power, solar irradiance, and wind speed data and organizes them into time series format.

Returns:

None

Return type:

None

Raises:

ValueError – If required columns are missing in PVGIS response

Variables:

  • data_local_time – Processed data in local timezone

  • PV_power – PV power time series (if pvcalculation=1)

  • sol_irrad – Solar irradiance time series

  • wind_speed – Wind speed time series

Example

data_sys = datsys("input_folder", lat=0.25, lon=32.40)
data_sys.data_extract()
kmeans_clust()[source]

Perform K-means clustering on time series data.

This method applies K-means clustering algorithm to reduce the dimensionality of time series data by grouping similar time periods into clusters. It clusters PV power, solar irradiance, and wind speed data separately and generates representative scenarios for each cluster.

Returns:

None

Return type:

None

Raises:

ValueError – If output files are missing or have incorrect format

Variables:

  • psol – Clustered solar power scenarios

  • qsol – Clustered solar reactive power scenarios

  • pwin – Clustered wind power scenarios

  • qwin – Clustered wind reactive power scenarios

  • dtim – Duration of each cluster

Example

data_sys = datsys("input_folder", n_clust=5)
data_sys.data_extract()
data_sys.kmeans_clust()
optimalangles

Value of 1 for “yes”. All other values (or no value) mean “no”. Not relevant for tracking planes.

optimalinclination

Value of 1 for “yes”. All other values (or no value) mean “no”. Not relevant for 2-axis tracking.

outputformat

Choices: “csv” “basic” “json”

trackingtype

0 = fixed 1 = single horizontal axis aligned north-south, 2 = two-axis tracking, 3 = vertical axis tracking, 4 = single horizontal axis aligned east-west, 5 = single inclined axis aligned north-south

Key Methods:

  • data_extract(): Extract historical weather data from PVGIS API

  • kmeans_clust(): Apply K-means clustering for scenario reduction

  • _validate_output_format(): Validate PVGIS API output format

  • _normalize_column_names(): Normalize data column names

Example Usage:

from pyeplan import datsys

# Initialize data processing system
data_system = datsys(
    inp_folder="input_folder",
    lat=0.25,
    lon=32.40,
    year=2016,
    pvcalc=1,
    pp=50,
    sys_loss=14,
    n_clust=5
)

# Extract weather data from PVGIS
data_system.data_extract()

# Create representative days using K-means clustering
data_system.kmeans_clust()

Routing Module (rousys)

The routing module performs optimal network design using minimum spanning tree algorithms.

class pyeplan.rousys(inp_folder='', crs=35, typ=7, vbase=415, sbase=1)[source]

Bases: object

Routing system class for microgrid network topology optimization.

This class implements minimum spanning tree algorithms and electrical parameter calculations for microgrid network design. It processes geographical data, calculates optimal network topologies, and generates electrical line specifications.

Variables:

  • geol – Geographical locations of all nodes (latitude/longitude) (pd.DataFrame)

  • node – Number of nodes in the network (int)

  • cblt – Cable parameters and specifications (pd.DataFrame)

  • crs – Cross section of cables in mm² (int)

  • typ – Type of cables (int)

  • vbase – Line-to-line voltage in V (float)

  • sbase – Base three-phase apparent power in VA (float)

  • zbase – Base impedance in Ω (float)

  • ibase – Base current in A (float)

  • r – Per-unit resistance of selected cable (float)

  • x – Per-unit reactance of selected cable (float)

  • i – Per-unit current rating of selected cable (float)

  • p – Per-unit active power limit (float)

  • q – Per-unit reactive power limit (float)

  • inp_folder – Input folder path for data files (str)

Methods

  • min_spn_tre() – Generate minimum spanning tree network topology

min_spn_tre()[source]

Generate minimum spanning tree network topology.

This method implements Kruskal’s minimum spanning tree algorithm to find the optimal network topology that connects all nodes with minimum total cable length. It creates network visualizations and generates output files for routing and electrical line specifications.

Returns:

None

Return type:

None

Raises:

ValueError – If network creation fails or output files cannot be written

Output files generated:

  • path.png: Network topology visualization

  • network_map.html: Interactive network map visualization

  • rou_dist.csv: Routing distances between connected nodes

  • elin_dist.csv: Electrical line parameters and specifications

The method performs the following steps: 1. Creates a complete graph with all nodes 2. Calculates distances between all node pairs 3. Applies minimum spanning tree algorithm 4. Generates network visualizations (static PNG and interactive HTML) 5. Creates routing and electrical parameter files

Example

route_sys = rousys("input_folder")
route_sys.min_spn_tre()

Key Methods:

  • min_spn_tre(): Generate minimum spanning tree network topology

  • distance(): Calculate geographical distance between two points using Haversine formula

Example Usage:

from pyeplan import rousys

# Initialize routing system
routing_system = rousys(
    inp_folder="input_folder",
    crs=35,
    typ=7,
    vbase=415,
    sbase=1
)

# Generate optimal network topology
routing_system.min_spn_tre()

Investment and Operation Module (inosys)

The investment and operation module handles both long-term capacity expansion and short-term dispatch optimization using mixed-integer linear programming.

class pyeplan.inosys(inp_folder, ref_bus, dshed_cost=1000000, rshed_cost=500, phase=3, vmin=0.85, vmax=1.15, sbase=1, sc_fa=1)[source]

Bases: object

Investment and operation optimization system for microgrids.

This class formulates and solves mixed-integer linear programming problems for microgrid investment and operation optimization. It handles complex constraints including power balance, generator limits, battery storage, network constraints, and voltage limits.

The optimization problem considers: - Investment decisions for generators, storage, and renewables - Operational decisions for power generation and storage - Network constraints and voltage limits - Demand shedding and renewable curtailment - Battery energy storage system operation

Variables:

  • cgen – Conventional generator candidate data (pd.DataFrame)

  • egen – Existing conventional generator data (pd.DataFrame)

  • csol – Solar PV candidate data (pd.DataFrame)

  • esol – Existing solar PV data (pd.DataFrame)

  • cwin – Wind turbine candidate data (pd.DataFrame)

  • ewin – Existing wind turbine data (pd.DataFrame)

  • cbat – Battery storage candidate data (pd.DataFrame)

  • elin – Electrical line data (pd.DataFrame)

  • pdem – Active power demand profiles (pd.DataFrame)

  • qdem – Reactive power demand profiles (pd.DataFrame)

  • prep – Renewable active power profiles (pd.DataFrame)

  • qrep – Renewable reactive power profiles (pd.DataFrame)

  • psol – Solar power scenarios (pd.DataFrame)

  • qsol – Solar reactive power scenarios (pd.DataFrame)

  • pwin – Wind power scenarios (pd.DataFrame)

  • qwin – Wind reactive power scenarios (pd.DataFrame)

  • dtim – Time duration for each scenario (pd.DataFrame)

  • ncg – Number of candidate conventional generators (int)

  • neg – Number of existing conventional generators (int)

  • ncs – Number of candidate solar PV systems (int)

  • nes – Number of existing solar PV systems (int)

  • ncw – Number of candidate wind turbines (int)

  • new – Number of existing wind turbines (int)

  • ncb – Number of candidate battery systems (int)

  • nel – Number of electrical lines (int)

  • nbb – Number of buses/nodes (int)

  • ntt – Number of time periods (int)

  • noo – Number of scenarios (int)

  • cds – Demand shedding cost (float)

  • css – Solar curtailment cost (float)

  • cws – Wind curtailment cost (float)

  • sb – Base apparent power (float)

  • sf – Scaling factor (float)

  • ref_bus – Reference bus number (int)

  • vmin – Minimum voltage limit (float)

  • vmax – Maximum voltage limit (float)

  • inp_folder – Input folder path (str)

  • phase – Number of phases (int)

  • outdir – Output directory path (str)

Methods

  • solve() – Solve the investment and operation optimization problem

  • resCost() – Get optimization results - costs

  • resWind() – Get optimization results - wind generation

  • resBat() – Get optimization results - battery operation

  • resSolar() – Get optimization results - solar generation

  • resConv() – Get optimization results - conventional generation

  • resCurt() – Get optimization results - curtailment

resBat()[source]

Get the battery capacity investment results.

This method returns the optimal battery storage capacity investments including installed capacity and bus locations for each candidate battery system.

Returns:

Battery investment results with columns: - Installed Capacity (kW): Optimal capacity for each battery system - Bus: Bus number where battery is installed

Return type:

pandas.DataFrame

Raises:

Exception – If solve() method has not been successfully executed

Example

inv_sys = inosys("input_folder", ref_bus=0)
inv_sys.solve(invest=True)
battery_results = inv_sys.resBat()
resConv()[source]

Get the conventional generator capacity investment results.

This method returns the optimal conventional generator capacity investments including installed capacity and bus locations for each candidate conventional generator.

Returns:

Conventional generator investment results with columns: - Installed Capacity (kW): Optimal capacity for each generator - Bus: Bus number where generator is installed

Return type:

pandas.DataFrame

Raises:

Exception – If solve() method has not been successfully executed

Example

inv_sys = inosys("input_folder", ref_bus=0)
inv_sys.solve(invest=True)
conv_results = inv_sys.resConv()
resCost()[source]

Get the objective cost results.

This method returns the total costs breakdown including investment costs, operational costs, and total system costs from the optimization results as a pandas DataFrame.

Returns:

Cost breakdown with columns: - total costs: Total system cost - total investment costs: Investment cost component - total operation costs: Operational cost component

Return type:

pandas.DataFrame

Raises:

Exception – If solve() method has not been successfully executed or if the results directory doesn’t exist

Example

inv_sys = inosys("input_folder", ref_bus=0)
inv_sys.solve()
cost_results = inv_sys.resCost()
print(cost_results)
resCurt()[source]

Get the curtailment results.

This method returns the demand shedding and renewable curtailment results from the optimization, showing how much load was shed and how much renewable energy was curtailed.

Returns:

Dictionary containing three pandas.DataFrames: - ‘demand_shedding’: Demand shedding results (pds.csv) - ‘solar_curtailment’: Solar curtailment results (pss.csv) - ‘wind_curtailment’: Wind curtailment results (pws.csv)

Return type:

dict

Raises:

Exception – If solve() method has not been successfully executed

Example

inv_sys = inosys("input_folder", ref_bus=0)
inv_sys.solve()
curtailment_results = inv_sys.resCurt()
print(curtailment_results['demand_shedding'])
resSolar()[source]

Get the solar capacity investment results.

This method returns the optimal solar PV capacity investments including installed capacity and bus locations for each candidate solar PV system.

Returns:

Solar investment results with columns: - Installed Capacity (kW): Optimal capacity for each solar PV system - Bus: Bus number where solar PV is installed

Return type:

pandas.DataFrame

Raises:

Exception – If solve() method has not been successfully executed

Example

inv_sys = inosys("input_folder", ref_bus=0)
inv_sys.solve(invest=True)
solar_results = inv_sys.resSolar()
resWind()[source]

Get the wind capacity investment results.

This method returns the optimal wind turbine capacity investments including installed capacity and bus locations for each candidate wind turbine.

Returns:

Wind investment results with columns: - Installed Capacity (kW): Optimal capacity for each wind turbine - Bus: Bus number where wind turbine is installed

Return type:

pandas.DataFrame

Raises:

Exception – If solve() method has not been successfully executed

Example

inv_sys = inosys("input_folder", ref_bus=0)
inv_sys.solve(invest=True)
wind_results = inv_sys.resWind()
solve(solver='glpk', neos=False, invest=False, onlyopr=True, commit=False, solemail='', verbose=False)[source]

Solve the investment and operation problem.

This method formulates and solves a mixed-integer linear programming problem for microgrid investment and operation optimization. It creates a Pyomo model with all necessary constraints and solves it using the specified solver.

Parameters:

  • solver (str) – Solver to be used. Available: glpk, cbc, ipopt, gurobi (default: ‘glpk’)

  • neos (bool) – True/False indicates if using NEOS remote solver service (default: False)

  • invest (bool) – True/False indicates binary/continuous nature of investment-related decision variables (default: False)

  • onlyopr (bool) – True/False indicates if the problem will only solve the operation or both investment and operation (default: True)

  • commit (bool) – True/False indicates if using binary commitment variables for generators (default: False)

  • solemail (str) – Email address required for NEOS solver service (default: ‘’)

  • verbose (bool) – True/False indicates if solver output should be displayed (default: False)

Returns:

None

Return type:

None

Raises:

  • ValueError – If solver is not available or model formulation fails

  • RuntimeError – If optimization fails to converge or find feasible solution

The method performs the following steps: 1. Creates Pyomo model with sets, variables, and constraints 2. Defines objective function and all operational constraints 3. Solves the optimization problem using specified solver 4. Extracts and stores optimization results 5. Saves results to output files

Example

import pyeplan
sys_inv = pyeplan.inosys("wat_inv", ref_bus = 260)
sys_inv.solve(verbose=True)

Key Methods:

Optimization:

  • solve(): Solve the investment and operation optimization problem

Results Analysis:

  • resCost(): Get optimization results - costs

  • resWind(): Get optimization results - wind generation

  • resBat(): Get optimization results - battery operation

  • resSolar(): Get optimization results - solar generation

  • resConv(): Get optimization results - conventional generation

  • resCurt(): Get optimization results - curtailment

Example Usage:

from pyeplan import inosys

# Initialize planning system
planning_system = inosys(
    inp_folder="input_folder",
    ref_bus=0,
    dshed_cost=1000000,
    rshed_cost=500,
    phase=3,
    vmin=0.85,
    vmax=1.15,
    sbase=1,
    sc_fa=1
)

# Solve investment and operation optimization
planning_system.solve(
    solver='glpk',
    neos=False,
    invest=True,
    onlyopr=False,
    commit=False,
    solemail='',
    verbose=False
)

# Get results
costs = planning_system.resCost()
wind_results = planning_system.resWind()
battery_results = planning_system.resBat()

Utility Functions

Data Conversion Functions

  • pyomo2dfinv(): Convert Pyomo investment variables to pandas DataFrame

  • pyomo2dfopr(): Convert Pyomo operation variables to pandas DataFrame

  • pyomo2dfoprm(): Convert Pyomo operation variables to pandas DataFrame (modified)

Data Structures

Input Data Format

PyEPlan uses standardized CSV and Excel formats for input data:

Component Data:

  • Generator characteristics (capacity, costs, efficiency)

  • Storage system parameters (capacity, efficiency, lifetime)

  • Network line parameters (resistance, reactance, capacity)

  • Cable specifications (cross-section, resistance, current rating)

Time Series Data:

  • Load profiles (hourly/daily demand)

  • Renewable generation profiles (solar, wind)

  • Fuel prices and grid tariffs

Geographic Data:

  • Node coordinates (latitude, longitude)

  • Terrain and accessibility information

  • Climate zone classifications

Required Input Files:

Data Processing (datsys):

  • mgpc_dist.xlsx: Load point and load level data

Routing (rousys):

  • geol_dist.csv: Geographical coordinates of nodes

  • cblt_dist.csv: Cable parameters and specifications

Investment & Operation (inosys):

  • cgen_dist.csv: Conventional generator candidate data

  • egen_dist.csv: Existing conventional generator data

  • csol_dist.csv: Solar PV candidate data

  • esol_dist.csv: Existing solar PV data

  • cwin_dist.csv: Wind turbine candidate data

  • ewin_dist.csv: Existing wind turbine data

  • cbat_dist.csv: Battery storage candidate data

  • elin_dist.csv: Electrical line data

  • pdem_dist.csv: Active power demand profiles

  • qdem_dist.csv: Reactive power demand profiles

  • prep_dist.csv: Renewable active power profiles

  • qrep_dist.csv: Renewable reactive power profiles

  • psol_dist.csv: Solar power scenarios

  • qsol_dist.csv: Solar reactive power scenarios

  • pwin_dist.csv: Wind power scenarios

  • qwin_dist.csv: Wind reactive power scenarios

  • dtim_dist.csv: Time duration for each scenario

Output Data Format

Results Summary:

  • Optimal technology mix and sizing

  • Total system costs and performance metrics

  • Financial indicators (NPV, IRR, LCOE)

Detailed Results:

  • Hourly dispatch schedules

  • Network flows and losses

  • Reliability and adequacy metrics

Configuration Parameters

Data Processing Parameters:

  • lat, lon: Geographic coordinates

  • year: Data collection year

  • pvcalc: PV calculation method (0=radiation only, 1=power+radiation)

  • pp: Nominal power of PV system in kW

  • sys_loss: System losses in %

  • n_clust: Number of clusters for time series clustering

Routing Parameters:

  • crs: Cross section of cables in mm²

  • typ: Type of cables

  • vbase: Line-to-line voltage in V

  • sbase: Base apparent power in kW

Optimization Parameters:

  • ref_bus: Reference bus number

  • dshed_cost: Demand shedding cost

  • rshed_cost: Renewable shedding cost

  • vmin, vmax: Voltage limits in p.u.

  • phase: Number of phases

Error Handling

PyEPlan includes comprehensive error handling for:

  • Data Validation: Input data format and range checking

  • Solver Issues: Optimization solver failures and timeouts

  • Convergence Problems: Non-convergent optimization problems

  • Memory Issues: Large-scale problem memory management

  • API Communication: PVGIS API connection and data retrieval issues

Example Error Handling:

try:
    results = planning_system.solve(solver='glpk')
except ValueError as e:
    print(f"Data validation error: {e}")
except RuntimeError as e:
    print(f"Optimization error: {e}")
except MemoryError as e:
    print(f"Memory limit exceeded: {e}")

Performance Considerations

Large-Scale Problems:

  • Use representative day clustering to reduce problem size

  • Implement decomposition techniques for multi-year planning

  • Consider parallel processing for scenario analysis

Memory Management:

  • Monitor memory usage for large networks

  • Use sparse matrix representations where possible

  • Implement data streaming for large time series

Solver Selection:

  • Commercial solvers (Gurobi, CPLEX) for large problems

  • Open-source solvers (GLPK, CBC) for smaller problems

  • Consider solver-specific parameter tuning

PVGIS API Optimization:

  • Cache API responses for repeated queries

  • Use appropriate radiation database for geographic region

  • Handle API rate limits and timeouts gracefully