API Reference

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

Core Modules

Data Processing Module

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

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)[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.

Attributes:

loc (pd.DataFrame): Load point locations and coordinates pdem (pd.DataFrame): Active power demand profiles prep (pd.DataFrame): Active power renewable generation profiles lat (float): Latitude in decimal degrees (south is negative) lon (float): Longitude in decimal degrees (west is negative) startyear (int): Start year for data collection endyear (int): End year for data collection pvcalculation (int): PV calculation method (0=radiation only, 1=power+radiation) peakpower (float): Nominal power of PV system in kW loss (float): Sum of system losses in % trackingtype (int): Type of sun tracking system optimalinclination (int): Calculate optimum inclination angle (1=yes) optimalangles (int): Calculate optimum inclination and orientation (1=yes) outputformat (str): Output format for PVGIS data browser (int): Output format (0=stream, 1=file) n_clust (int): Number of clusters for time series clustering pf_c (float): Power factor at consumption points pf_p (float): Power factor at production points sbase (float): Base apparent power in kW data_link (str): PVGIS API URL with parameters data (pd.DataFrame): Raw data from PVGIS API local_time_zone (str): Local timezone for the location qrep (pd.DataFrame): Reactive power renewable generation profiles qdem (pd.DataFrame): Reactive power demand profiles inp_folder (str): Input folder path for data files

Methods:

data_extract(): Extract and process time series data kmeans_clust(): Perform K-means clustering on time series data

data

Data columns description as described by PVGIS:

Time = Date and hour P = PV system power (W) ** Column not included if pvcalc = 0 G(i) = Global irradiance on the inclined plane (plane of the array) (W/m2) H_sun = Sun height (degree) T2m = 2-m air temperature (degree Celsius) WS10m = 10-m total wind speed (m/s) Int = 1 means solar radiation values are reconstructed

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.

The method performs the following operations: 1. Converts UTC timestamps to local timezone 2. Extracts PV power data (if pvcalculation=1) 3. Extracts solar irradiance data 4. Extracts wind speed data 5. Creates power chronology file

Output files generated:

  • power_chrono.csv: PV power time series (if pvcalculation=1)

Attributes updated:

  • 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.

The method performs the following operations: 1. Applies K-means clustering to PV power data 2. Applies K-means clustering to solar irradiance data 3. Applies K-means clustering to wind speed data 4. Calculates cluster durations and representative values 5. Generates output files for clustered data

Output files generated:

  • psol_dist.csv: Clustered solar power scenarios

  • qsol_dist.csv: Clustered solar reactive power scenarios

  • pwin_dist.csv: Clustered wind power scenarios

  • qwin_dist.csv: Clustered wind reactive power scenarios

  • dtim_dist.csv: Duration of each cluster

The clustering process: - Uses k-means++ initialization for better convergence - Creates n_clust representative scenarios - Calculates cluster centers as representative values - Distributes remaining time periods evenly across clusters

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:

  • extract_weather_data(): Extract historical weather data from satellite sources

  • create_daily_profiles(): Generate 24-hour daily profiles for renewable generation

  • cluster_representative_days(): Apply machine learning algorithms for scenario reduction

  • validate_data(): Check data quality and consistency

Example Usage: .. code-block:: python

from pyeplan import datsys

# Initialize data processing system data_system = datsys()

# Extract weather data for a location weather_data = data_system.extract_weather_data(

latitude=1.2921, longitude=36.8219, start_date=’2020-01-01’, end_date=’2020-12-31’

)

# Create representative days rep_days = data_system.cluster_representative_days(

data=weather_data, n_clusters=5, method=’kmeans’

)

Routing Module

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.

Attributes:

geol (pd.DataFrame): Geographical locations of all nodes (latitude/longitude) node (int): Number of nodes in the network cblt (pd.DataFrame): Cable parameters and specifications crs (int): Cross section of cables in mm² typ (int): Type of cables vbase (float): Line-to-line voltage in V sbase (float): Base three-phase apparent power in VA zbase (float): Base impedance in Ω ibase (float): Base current in A r (float): Per-unit resistance of selected cable x (float): Per-unit reactance of selected cable i (float): Per-unit current rating of selected cable p (float): Per-unit active power limit q (float): Per-unit reactive power limit inp_folder (str): Input folder path for data files

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.

Output files generated:

  • path.png: Network topology 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 5. Creates routing and electrical parameter files

Example:
>>> route_sys = rousys("input_folder")
>>> route_sys.min_spn_tre()

Key Methods:

  • load_coordinates(): Load geographic coordinates of nodes

  • calculate_distances(): Compute distances between all node pairs

  • optimize_network(): Find optimal network topology

  • analyze_network(): Evaluate network performance metrics

Example Usage: .. code-block:: python

from pyeplan import rousys

# Initialize routing system routing_system = rousys()

# Load node coordinates routing_system.load_coordinates(‘coordinates.csv’)

# Optimize network design network = routing_system.optimize_network(

method=’mst’, cost_function=’distance’

)

# Analyze results results = routing_system.analyze_network(network)

Investment and Operation Planning Module

The investment and operation planning module handles both long-term capacity expansion and short-term dispatch optimization.

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

Attributes:

cgen (pd.DataFrame): Conventional generator candidate data egen (pd.DataFrame): Existing conventional generator data csol (pd.DataFrame): Solar PV candidate data esol (pd.DataFrame): Existing solar PV data cwin (pd.DataFrame): Wind turbine candidate data ewin (pd.DataFrame): Existing wind turbine data cbat (pd.DataFrame): Battery storage candidate data elin (pd.DataFrame): Electrical line data pdem (pd.DataFrame): Active power demand profiles qdem (pd.DataFrame): Reactive power demand profiles prep (pd.DataFrame): Renewable active power profiles qrep (pd.DataFrame): Renewable reactive power profiles psol (pd.DataFrame): Solar power scenarios qsol (pd.DataFrame): Solar reactive power scenarios pwin (pd.DataFrame): Wind power scenarios qwin (pd.DataFrame): Wind reactive power scenarios dtim (pd.DataFrame): Time duration for each scenario ncg (int): Number of candidate conventional generators neg (int): Number of existing conventional generators ncs (int): Number of candidate solar PV systems nes (int): Number of existing solar PV systems ncw (int): Number of candidate wind turbines new (int): Number of existing wind turbines ncb (int): Number of candidate battery systems nel (int): Number of electrical lines nbb (int): Number of buses/nodes ntt (int): Number of time periods noo (int): Number of scenarios cds (float): Demand shedding cost css (float): Solar curtailment cost cws (float): Wind curtailment cost sb (float): Base apparent power sf (float): Scaling factor ref_bus (int): Reference bus number vmin (float): Minimum voltage limit vmax (float): Maximum voltage limit inp_folder (str): Input folder path phase (int): Number of phases outdir (str): Output directory path

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]

Display the battery capacity investment results.

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

Returns:
pandas.DataFrame: Battery investment results with columns:

  • Installed Capacity (kW): Optimal capacity for each battery system

  • Bus: Bus number where battery is installed

Raises:

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

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

Display the conventional generator capacity investment results.

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

Returns:
pandas.DataFrame: Conventional generator investment results with columns:

  • Installed Capacity (kW): Optimal capacity for each generator

  • Bus: Bus number where generator is installed

Raises:

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

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

Display the objective cost results.

This method displays the total costs breakdown including investment costs, operational costs, and total system costs from the optimization results.

Returns:
pandas.DataFrame: Cost breakdown with columns:

  • total costs: Total system cost

  • total investment costs: Investment cost component

  • total operation costs: Operational cost component

Raises:

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

Example:
>>> inv_sys = inosys("input_folder", ref_bus=0)
>>> inv_sys.solve()
>>> inv_sys.resCost()
resCurt()[source]

Display the curtailment results.

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

Returns:

pandas.DataFrame: Curtailment results showing demand shedding and renewable curtailment amounts

Raises:

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

Example:
>>> inv_sys = inosys("input_folder", ref_bus=0)
>>> inv_sys.solve()
>>> inv_sys.resCurt()
resSolar()[source]

Display the solar capacity investment results.

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

Returns:
pandas.DataFrame: Solar investment results with columns:

  • Installed Capacity (kW): Optimal capacity for each solar PV system

  • Bus: Bus number where solar PV is installed

Raises:

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

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

Display the wind capacity investment results.

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

Returns:
pandas.DataFrame: Wind investment results with columns:

  • Installed Capacity (kW): Optimal capacity for each wind turbine

  • Bus: Bus number where wind turbine is installed

Raises:

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

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

Solve the investment and operation problem. :param str solver: Solver to be used. Available: glpk, cbc, ipopt, gurobi :param bool network: True/False indicates including/excluding network-related constraints :param bool invest: True/False indicates binary/continuous nature of investement-related decision variables :param bool onlyopr: True/False indicates if the problem will only solve the operation or both investment and operation :param bool commit: True/False indicates if ??? :param bool neos: True/False indicates if ??? :Example: >>> import pyeplan >>> sys_inv = pyeplan.inosys(“wat_inv”, ref_bus = 260) >>> sys_inv.solve()

Key Methods:

Investment Planning: * investment_planning(): Long-term capacity expansion optimization * analyze_investment(): Investment cost and performance analysis * sensitivity_analysis(): Parameter sensitivity evaluation

Operation Planning: * operation_planning(): Short-term dispatch optimization * analyze_operation(): Operation cost and performance analysis * unit_commitment(): Generator start-up/shut-down decisions

Example Usage: .. code-block:: python

from pyeplan import inosys

# Initialize planning system planning_system = inosys()

# Load input data planning_system.load_data(‘input_data.csv’)

# Run investment planning inv_results = planning_system.investment_planning(

horizon=10, discount_rate=0.08, reliability_target=0.99

)

# Run operation planning op_results = planning_system.operation_planning(

horizon=24, reserve_margin=0.15

)

# Analyze results planning_system.analyze_results(inv_results, op_results)

Data Structures

Input Data Format

PyEPLAN uses standardized CSV formats for input data:

Component Data:

  • Generator characteristics (capacity, costs, efficiency)

  • Storage system parameters (capacity, efficiency, lifetime)

  • Network line parameters (resistance, reactance, capacity)

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

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

General Parameters:

  • planning_horizon: Time horizon for investment planning (years)

  • discount_rate: Discount rate for financial calculations

  • reliability_target: Target system reliability level

Technical Parameters:

  • reserve_margin: Reserve capacity requirement

  • voltage_limits: Acceptable voltage deviation range

  • line_capacity: Maximum line loading limits

Economic Parameters:

  • fuel_prices: Fuel cost projections

  • technology_costs: Capital cost assumptions

  • grid_tariffs: Grid exchange price structure

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

Example Error Handling: .. code-block:: python

try:

results = planning_system.investment_planning()

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