API Reference

pownet.core module

• pownet.core package
  • Submodules
  • pownet.core.data_processor module
    • DataProcessor
      • DataProcessor.calc_line_capacity()
      • DataProcessor.calc_line_susceptance()
      • DataProcessor.calc_stability_limit()
      • DataProcessor.calc_thermal_limit()
      • DataProcessor.check_user_line_capacities()
      • DataProcessor.create_cycle_map()
      • DataProcessor.create_ess_derate_factors()
      • DataProcessor.create_ess_derated_capacity()
      • DataProcessor.create_thermal_derate_factors()
      • DataProcessor.create_thermal_derated_capacity()
      • DataProcessor.execute_data_pipeline()
      • DataProcessor.load_transmission_data()
      • DataProcessor.run_all_processing_steps()
      • DataProcessor.write_cycle_map()
      • DataProcessor.write_data()
      • DataProcessor.write_ess_derated_capacity()
      • DataProcessor.write_thermal_derate_factors()
      • DataProcessor.write_thermal_derated_capacity()
      • DataProcessor.write_transmission_data()
  • pownet.core.model_builder module
    • ModelBuilder
      • ModelBuilder.build()
      • ModelBuilder.get_phydro()
      • ModelBuilder.update()
      • ModelBuilder.update_daily_hydropower_capacity()
  • pownet.core.output module
    • OutputProcessor
      • OutputProcessor.get_co2_emission()
      • OutputProcessor.get_contract_generation()
      • OutputProcessor.get_contract_hourly_cost()
      • OutputProcessor.get_contract_hourly_generation()
      • OutputProcessor.get_daily_demand()
      • OutputProcessor.get_daily_generation()
      • OutputProcessor.get_energy_storage_daily_state()
      • OutputProcessor.get_energy_storage_hourly_charge()
      • OutputProcessor.get_energy_storage_hourly_discharge()
      • OutputProcessor.get_energy_storage_hourly_state()
      • OutputProcessor.get_fuel_mix()
      • OutputProcessor.get_gen_by_fuel()
      • OutputProcessor.get_hourly_curtailment()
      • OutputProcessor.get_hourly_demand()
      • OutputProcessor.get_hourly_generation()
      • OutputProcessor.get_import_values()
      • OutputProcessor.get_max_line_usage()
      • OutputProcessor.get_monthly_demand()
      • OutputProcessor.get_monthly_generation()
      • OutputProcessor.get_nondispatch_hourly_capacity_factor()
      • OutputProcessor.get_thermal_unit_daily_dispatch()
      • OutputProcessor.get_thermal_unit_daily_duration()
      • OutputProcessor.get_thermal_unit_daily_startup_frequency()
      • OutputProcessor.get_thermal_unit_hourly_dispatch()
      • OutputProcessor.get_thermal_unit_hourly_status()
      • OutputProcessor.get_thermal_unit_mean_hourly_status()
      • OutputProcessor.get_thermal_unit_startup_frequency()
      • OutputProcessor.get_thermal_unit_total_duration()
      • OutputProcessor.get_thermal_unit_total_duration_and_frequency()
      • OutputProcessor.get_unit_hourly_generation()
      • OutputProcessor.get_variables()
      • OutputProcessor.load()
  • pownet.core.record module
    • SystemRecord
      • SystemRecord.get_flow_variables()
      • SystemRecord.get_init_conds()
      • SystemRecord.get_lmp()
      • SystemRecord.get_model_stats()
      • SystemRecord.get_node_variables()
      • SystemRecord.get_objvals()
      • SystemRecord.get_runtimes()
      • SystemRecord.get_systemwide_variables()
      • SystemRecord.keep()
      • SystemRecord.write_init_conds()
      • SystemRecord.write_simulation_results()
  • pownet.core.simulation module
    • Simulator
      • Simulator.get_flow_variables()
      • Simulator.get_node_variables()
      • Simulator.get_systemwide_variables()
      • Simulator.plot_fuelmix()
      • Simulator.plot_lmp()
      • Simulator.plot_thermal_units()
      • Simulator.run()
      • Simulator.write_results()
  • pownet.core.user_constraint module
    • UserConstraint
      • UserConstraint.add_constraints_to_model()
      • UserConstraint.register_constraint()
      • UserConstraint.register_constraint_with_update()
      • UserConstraint.remove_constraints()
      • UserConstraint.update_constraints()
  • pownet.core.visualizer module
    • Visualizer
      • Visualizer.plot_fuelmix_area()
      • Visualizer.plot_fuelmix_bar()
      • Visualizer.plot_generation_by_contracts()
      • Visualizer.plot_line_usage()
      • Visualizer.plot_lmp()
      • Visualizer.plot_mean_thermal_unit_hourly_status()
      • Visualizer.plot_power_flow()
      • Visualizer.plot_thermal_units()
      • Visualizer.plot_unit_storage_state()
• pownet.data_model package
  • pownet.data_model.reservoir module
• pownet.optim_model package
  • Subpackages
    • pownet.optim_model.constraints package
      • Submodules
      • pownet.optim_model.constraints.energy_storage_constr module
        • add_c_link_ess_charge()
        • add_c_link_ess_discharge()
        • add_c_link_ess_state()
        • add_c_unit_ess_balance()
        • add_c_unit_ess_balance_init()
      • pownet.optim_model.constraints.nondispatch_constr module
        • add_c_hourly_unit_ub()
        • add_c_hydro_limit_daily()
        • add_c_hydro_limit_daily_dict()
        • add_c_hydro_limit_weekly()
        • add_c_link_unit_pu()
      • pownet.optim_model.constraints.system_constr module
        • add_c_angle_diff()
        • add_c_flow_balance()
        • add_c_kirchhoff()
        • add_c_link_shortfall()
        • add_c_ref_node()
        • add_c_reserve_req_1()
        • add_c_reserve_req_2()
        • add_c_thermal_curtail_ess()
        • add_c_unit_curtail_ess()
        • add_c_unit_curtail_ess_daily()
      • pownet.optim_model.constraints.thermal_unit_constr module
        • add_c_link_ppbar()
        • add_c_link_pthermal()
        • add_c_link_pu_lower()
        • add_c_link_pu_upper()
        • add_c_link_spin()
        • add_c_link_uvw()
        • add_c_link_uvw_init()
        • add_c_min_down()
        • add_c_min_down_init()
        • add_c_min_up()
        • add_c_min_up_init()
        • add_c_peak_down_bound()
        • add_c_peak_up_bound()
        • add_c_ramp_down()
        • add_c_ramp_down_init()
        • add_c_ramp_up()
        • add_c_ramp_up_init()
      • Module contents
  • Submodules
  • pownet.optim_model.model module
    • PowerSystemModel
      • PowerSystemModel.check_feasible()
      • PowerSystemModel.get_model()
      • PowerSystemModel.get_objval()
      • PowerSystemModel.get_runtime()
      • PowerSystemModel.get_runtime_gurobi()
      • PowerSystemModel.get_runtime_highs()
      • PowerSystemModel.get_solution()
      • PowerSystemModel.get_solution_gurobi()
      • PowerSystemModel.get_solution_highs()
      • PowerSystemModel.get_status()
      • PowerSystemModel.optimize()
      • PowerSystemModel.optimize_with_rounding()
      • PowerSystemModel.print_added_constraints()
      • PowerSystemModel.solve_for_export_capacity()
      • PowerSystemModel.solve_for_export_prices()
      • PowerSystemModel.solve_for_lmp()
      • PowerSystemModel.solve_for_lmp_gurobi()
      • PowerSystemModel.solve_for_lmp_highs()
      • PowerSystemModel.write_ilp_mps()
      • PowerSystemModel.write_mps()
  • pownet.optim_model.objfunc module
    • get_marginal_cost_coeff()
    • get_thermal_fixed_coeff()
    • get_thermal_opex_coeff()
    • get_thermal_startup_coeff()
  • pownet.optim_model.rounding_algo module
    • check_binary_values()
    • fast_rounding()
    • find_fraction_vars()
    • get_variables()
    • optimize_with_rounding()
    • round_down()
    • round_up()
    • slow_rounding()
  • pownet.optim_model.variable_func module
    • add_var_with_variable_ub()
    • update_flow_vars()
    • update_var_with_variable_ub()
  • Module contents
• pownet.reservoir package
  • Submodules
  • pownet.reservoir.manager module
    • ReservoirManager
      • ReservoirManager.get_hydropower_ts()
      • ReservoirManager.load_reservoirs_from_csv()
      • ReservoirManager.reoperate()
      • ReservoirManager.simulate()
      • ReservoirManager.write_hydropower_to_csv()
    • find_upstream_flow()
  • pownet.reservoir.reservoir module
    • Reservoir
      • Reservoir.get_daily_hydropower()
      • Reservoir.get_hourly_hydropower()
      • Reservoir.get_operation_timeseries()
      • Reservoir.get_reop_daily_hydropower()
      • Reservoir.plot_state()
      • Reservoir.reoperate()
      • Reservoir.set_upstream_flow()
      • Reservoir.simulate()
  • pownet.reservoir.reservoir_functions module
    • adjust_hydropeaking()
    • calc_daily_hydropower()
    • calc_hourly_hydropower()
    • calc_level_from_storage()
    • calc_max_release()
    • calc_min_release()
    • calc_release_impact()
    • calc_target_level()
    • calc_target_storage()
    • convert_to_hourly_hydropower()
    • find_downstream_flow_fractions()
    • find_simulation_order()
    • find_upstream_units()
  • pownet.reservoir.solve_release module
    • solve_release_from_dispatch()
    • solve_release_from_target_storage()
  • Module contents
• pownet.stochastic package
  • Submodules
  • pownet.stochastic.demand module
    • DemandTSModel
      • DemandTSModel.monthly_models
      • DemandTSModel.pred_residuals
      • DemandTSModel.predictions
  • pownet.stochastic.kirsch_nowak module
    • KNN_identification()
    • chol_corr()
  • pownet.stochastic.solar module
    • SolarTSModel
      • SolarTSModel.monthly_models
      • SolarTSModel.pred_residuals
      • SolarTSModel.predictions
    • process_solar_series()
  • pownet.stochastic.timeseries_model module
    • TimeSeriesModel
      • TimeSeriesModel.find_best_model()
      • TimeSeriesModel.fit()
      • TimeSeriesModel.get_synthetic()
      • TimeSeriesModel.load_data()
      • TimeSeriesModel.monthly_models
      • TimeSeriesModel.plot_residuals()
      • TimeSeriesModel.pred_residuals
      • TimeSeriesModel.predict()
      • TimeSeriesModel.predictions
  • pownet.stochastic.timeseries_utils module
    • inverse_log1p()
    • inverse_yeojohnson()
    • post_process_solar()
    • transform_log1p()
    • transform_yeojohnson()
  • Module contents

This is the core module.

class pownet.core.DataProcessor(input_folder, model_name, year, frequency)

Bases: object

calc_line_capacity()

Calculate the capacity of line segments. The unit is in MW. Line capacity is the minimum of the thermal limit and the steady-state stability limit (a function of distance).

Note the calculated values are overwritten by user provided values in the transmission.csv file.

Return type:

None

calc_line_susceptance()

Calculate the susceptance of line segments. The unit is in Siemens (S).

Return type:

None

calc_stability_limit(source_kv, sink_kv, distance, n_circuits)

Calculates the theoretical steady-state stability limit of the transmission line.

This method applies the classical Power Transfer Equation for a lossless line (Chapter 5 of Power System Analysis and Design, Eq. 5.4.27).

Formula: P_max_circuit = (V_S * V_R) / X_total

Where: P_max_circuit: The maximum Real Power transfer per circuit in MW.

(Assumes Power Factor = 1.0, so MW = MVA).

V_S, V_R: The Line-to-Line voltages at sending and receiving ends in kV. X_total: The total reactance of the line in Ohms.

Calculated as (Reactance_per_km * distance).

Note on “Perfect Condition”: This calculates the static stability limit (steady-state). Practical operations typically constrain flow to a safety margin (e.g., 30-45 degrees load angle) well below this theoretical maximum.

Parameters:

• source_kv (int) – Voltage level of the source bus in kV.

• sink_kv (int) – Voltage level of the sink bus in kV.

• distance (float) – Length of the transmission line in km.

• n_circuits (int) – Number of parallel circuits (e.g., 2 for double-circuit).

Returns:

The combined stability limit for all circuits in MW.

Returns infinity if distance is 0 (co-located buses).

Return type:

int

calc_thermal_limit(source_kv, sink_kv, n_circuits)

Calculates the thermal rating (MVA) of the transmission line based on conductor ampacity (Chapter 5 of Power System Analysis and Design 5th See Example 5.6b).

Let ‘n_conductors’ parameter in ‘transmission_params’ represents the number of sub-conductors per phase (bundling factor).

Formula: S_thermal = sqrt(3) * V_line_LL * I_phase_max

Return type:

int

Where: S_thermal: The total Apparent Power capacity of the circuit in MVA.

(Note: S_thermal = P_real_power only when Power Factor = 1.0)

V_line_LL: The Line-to-Line voltage in kV (the standard voltage rating, e.g., 115 kV). I_phase_max: The maximum current capacity per phase in kilo-Amps (kA).

Calculated as (Ampacity per wire * Bundling Factor).

Args: source_kv (int): Voltage level of the source bus (kV). sink_kv (int): Voltage level of the sink bus (kV). n_circuits (int): Number of distinct circuits (e.g., double circuit tower = 2).

Returns: int: The maximum thermal capacity in MVA.

check_user_line_capacities()

The user can provide their own line capacities under user_line_cap column in transmission.csv. If this is the case, then it will be used instead of the calculated line capacities.

Return type:

None

create_cycle_map()

Create a cycle map for the power system. This is used to create the cycle constraints in the optimization model. The cycle map is a dictionary where the key is the cycle name and the value is a list of nodes in the cycle.

Return type:

None

create_ess_derate_factors(derate_factor=1.0)

Creates derate factors for ESS units.

Return type:

None

create_ess_derated_capacity()

Creates a dataframe of hourly derated capacity of ess units.

Return type:

None

create_thermal_derate_factors(derate_factor=1.0)

Creates derate factors for thermal units.

Return type:

None

create_thermal_derated_capacity()

Creates a dataframe of hourly derated capacity of thermal units.

Return type:

None

execute_data_pipeline()

Return type:

None

load_transmission_data()

Return type:

None

run_all_processing_steps()

Run all the data processing steps

Return type:

None

write_cycle_map()

Save the cycle map to a json file in model_library/{model_name}. The key is the cycle name and the value is a list of nodes in the cycle.

Return type:

None

write_data()

Write the processed data as csv files sharing a prefix pownet_ to the model folder

Return type:

None

write_ess_derated_capacity()

Return type:

None

write_thermal_derate_factors()

Return type:

None

write_thermal_derated_capacity()

Return type:

None

write_transmission_data()

Return type:

None

class pownet.core.ModelBuilder(inputs)

Bases: object

build(step_k, init_conds)

Build the initial optimization model by delegating to specialized builders.

Return type:

PowerSystemModel

get_phydro()

Get the hydro power variable from the model.

Return type:

tupledict

update(step_k, init_conds)

Update the existing model for a new step_k by delegating to specialized builders.

Return type:

PowerSystemModel

update_daily_hydropower_capacity(step_k, new_capacity)

Update the daily hydro capacity in the model.

Return type:

PowerSystemModel

class pownet.core.OutputProcessor

Bases: object

get_co2_emission(hourly_generation, co2_map=None)

Return the CO2 emissions for timestep. From Chowdhury, Dang, Nguyen, Koh, & Galelli. (2021).

coal: 1.04 Mton/MWh gas: 0.47 Mton/MWh oil : 0.73 Mton/MWh solid_waste: 0.170 Mton/MWh

From https://www.eia.gov/environment/emissions/co2_vol_mass.php: solid_waste: 49.89 kg/MMBtu (From 49.89 kg/MMBtu * 3.412 MMBtu/MWh * 1 Mton/1000 kg = 0.170 Mton/MWh)

get_contract_generation(node_variables, unit_contract)

Return type:

DataFrame

get_contract_hourly_cost(node_variables, unit_contract, contract_costs)

Return type:

DataFrame

get_contract_hourly_generation(node_variables, unit_contract)

Return type:

DataFrame

get_daily_demand(input_demand)

Return type:

Series

get_daily_generation(node_variables)

Return type:

DataFrame

get_energy_storage_daily_state(node_variables, max_storage)

Return type:

DataFrame

get_energy_storage_hourly_charge(node_variables)

Return type:

DataFrame

get_energy_storage_hourly_discharge(node_variables)

Return type:

DataFrame

get_energy_storage_hourly_state(node_variables, max_storage)

Return type:

DataFrame

get_fuel_mix(hourly_generation)

Return the fuel mix (%) for the whole simulation period.

Return type:

DataFrame

get_gen_by_fuel(hourly_generation)

Return the total generation for the whole simulation period.

Return type:

DataFrame

get_hourly_curtailment(node_variables, unit_type)

Return type:

DataFrame

get_hourly_demand(input_demand)

Return type:

Series

get_hourly_generation(node_variables)

Return type:

DataFrame

get_import_values(node_variables)

Return the import values for each timestep. Columns are generators. Index is the hour in the simulation year

Return type:

DataFrame

get_max_line_usage(flow_variables, line_locations, rated_line_capacities)

Calculates the maximum utilization for each transmission line.

This function takes the flow results from an optimization model, determines the peak flow on each line over the entire simulation horizon, and then calculates the utilization of each line as a percentage of its rated capacity. It also merges location data for the lines.

Parameters:

• flow_variables (pd.DataFrame) – DataFrame containing flow values for each line at each timestep. Expected columns: ‘node_a’, ‘node_b’, ‘value’ (flow magnitude), and ‘hour’.

• line_locations (pd.DataFrame) – DataFrame containing location or other metadata for each line. Expected to be indexed by a MultiIndex (‘source’, ‘sink’).

• rated_line_capacities (dict[tuple[str, str], int]) – Dictionary mapping line tuples (source_node, sink_node) to their rated power capacity (e.g., in MW).

Returns:

A DataFrame indexed by (‘source’, ‘sink’) with columns

including ‘max_line_usage’ (peak flow / rated capacity), columns from line_locations, and ‘rated_capacity’.

Return type:

pd.DataFrame

get_monthly_demand(input_demand)

Return type:

Series

get_monthly_generation(node_variables)

Return type:

DataFrame

get_nondispatch_hourly_capacity_factor(unit_type, node_variables, contracted_capacities, energy_storage_attach)

Return the capacity factor which is a function of generation and storage charging.

Return type:

DataFrame

get_thermal_unit_daily_dispatch(node_variables)

Return type:

DataFrame

get_thermal_unit_daily_duration(node_variables)

Return the daily online duration of each thermal unit. Rows are days and columns are units.

Return type:

DataFrame

get_thermal_unit_daily_startup_frequency(node_variables)

Return the frequency of startups for each thermal unit over the whole simulation period.

Return type:

DataFrame

get_thermal_unit_hourly_dispatch(node_variables)

Return type:

DataFrame

get_thermal_unit_hourly_status(node_variables)

Return type:

DataFrame

get_thermal_unit_mean_hourly_status(node_variables)

The hourly status of thermal units for each hour over the simulation period.

Return type:

DataFrame

get_thermal_unit_startup_frequency(node_variables)

Return the frequency of startups for each thermal unit over the whole simulation period.

Return type:

DataFrame

get_thermal_unit_total_duration(node_variables)

Return the total online duration of each thermal unit over the whole simulation period.

Return type:

DataFrame

get_thermal_unit_total_duration_and_frequency(node_variables)

Return data for histogram of frequency of startups and duration of committed hours in a year.

Return type:

DataFrame

get_unit_hourly_generation(node_variables)

Return type:

DataFrame

get_variables(node_variables, variables)

Return unit-level shortfall variables.

Return type:

DataFrame

load(inputs)

Load the input data.

Return type:

None

class pownet.core.Simulator(input_folder, model_name, model_year, frequency=50, use_spin_var=True, dc_opf='kirchhoff', spin_reserve_factor=0.15, spin_reserve_mw=None, line_loss_factor=0.075, line_capacity_factor=0.9, load_shortfall_penalty_factor=1000, load_curtail_penalty_factor=10, spin_shortfall_penalty_factor=1000)

Bases: object

Main class to run the simulation of the power system model

get_flow_variables()

Return the flow variables.

Return type:

DataFrame

get_node_variables()

Return the node-specific variables.

Return type:

DataFrame

get_systemwide_variables()

Return the system variables

Return type:

DataFrame

plot_fuelmix(chart_type, output_folder=None)

Plot the fuel mix of the power system

Parameters:

• chart_type (str) – The type of chart to plot. Choose between ‘bar’ and ‘area’.

• output_folder (str) – The folder to save the plot.

Return type:

None

Returns:

None

plot_lmp(output_folder=None)

Plot the locational marginal prices

Parameters:

output_folder (str) – The folder to save the plot.

Return type:

None

Returns:

None

plot_thermal_units(output_folder=None)

Plot the status of the thermal units

Parameters:

output_folder (str) – The folder to save the plot.

Return type:

None

Returns:

None

run(sim_horizon, steps_to_run, num_sim_days=365, to_process_inputs=True, solver='gurobi', log_to_console=True, mipgap=0.001, timelimit=600, num_threads=0, find_lmp=False)

Run the simulation of the power system model

Parameters:

• sim_horizon (int) – The simulation horizon in hours.

• steps_to_run (int) – The number of steps to run the simulation.

• to_process_inputs (bool) – Whether to process the input data.

• solver (str) – The solver to use for optimization.

• log_to_console (bool) – Whether to log the optimization output to the console.

• mipgap (float) – The MIP gap for the optimization.

• timelimit (int) – The time limit for the optimization in seconds.

• num_threads (int) – The number of threads to use for optimization.

• find_lmp (bool) – Whether to find the locational marginal prices.

Returns:

The system record object containing the simulation results.

Return type:

SystemRecord

write_results(output_folder)

Write the simulation results to files

Return type:

None

class pownet.core.SystemRecord(system_input, batch_mode=True, keep_record_each_step=False)

Bases: object

This class stores modeling outputs from each iteration. The results are stored in three dataframes: node_vars, flow_vars, and syswide_vars. The initial conditions are also stored in the class.

get_flow_variables()

Return the flow variables.

Return type:

DataFrame

get_init_conds()

Return the initial conditions for the simulation.

Return type:

dict[str, dict]

get_lmp()

Return the locational marginal prices (LMP) data.

Return type:

DataFrame

get_model_stats()

Return type:

DataFrame

get_node_variables()

Return node-specific variables. These variables include dispatch, unit status, unit switching, etc.

Return type:

DataFrame

get_objvals()

Return the objective values from each iteration.

Return type:

list[float]

get_runtimes()

Return the model runtime from each iteration.

Return type:

list[float]

get_systemwide_variables()

Return the system variables. We currently only have the system-wide spinning reserve shortfall.

Return type:

DataFrame

keep(runtime, objval, solution, step_k, lmp=None)

Keep the simulation results at the current simulation period step_k.

Parameters:

• runtime (float) – The runtime of the model.

• objval (float) – The objective value of the model.

• solution (pd.DataFrame) – The solution dataframe from the model.

• step_k (int) – The current simulation period.

• lmp (dict[str, float], optional) – The locational marginal prices. Defaults to None.

Return type:

None

Returns:

None

write_init_conds(output_folder)

Return type:

None

write_simulation_results(output_folder)

Write CSV files containing modeling results to the output directory.

Parameters:

output_folder (str) – The directory where the output files will be saved.

Return type:

None

Returns:

None

class pownet.core.UserConstraint(model)

Bases: object

add_constraints_to_model(step_k=1)

register_constraint(constraint, constr_name, **kwargs)

register_constraint_with_update(constraint, constr_name, **kwargs)

remove_constraints(constr_names)

update_constraints(step_k)

class pownet.core.Visualizer(model_id)

Bases: object

plot_fuelmix_area(dispatch, demand, output_folder=None)

Create an area plot of the fuel mix.

Parameters:

• dispatch (pd.DataFrame) – The dispatch of each generator.

• demand (pd.Series) – The demand of the system.

• output_folder (str) – If specified, then the plot is saved in the folder.

Return type:

None

Returns:

None

plot_fuelmix_bar(dispatch, demand, output_folder=None)

Create a bar plot of the fuel mix.

Parameters:

• dispatch (pd.DataFrame) – The dispatch of each generator.

• demand (pd.Series) – The demand of the system.

• output_folder (str) – If specified, then the plot is saved in the folder.

Return type:

None

Returns:

None

plot_generation_by_contracts(contract_generation)

Return type:

None

plot_line_usage(max_line_usage, output_folder=None)

Flow variables must have the max_line_usage column

Return type:

None

plot_lmp(lmp_df, output_folder=None, max_ylim=200)

Plots unique locational marginal price (LMP) timeseries. For each unique LMP timeseries, a representative node is chosen based on ordering in the dataframe.

Parameters:

• lmp_df (pd.DataFrame) – LMP timeseries.

• output_folder (str) – If specified, then the plot is saved in the folder.

• max_ylim (float) – Maximum y-axis limit.

Return type:

None

Returns:

None

plot_mean_thermal_unit_hourly_status(thermal_unit_mean_hourly_status, output_folder=None)

Return type:

None

plot_power_flow(flow_variables, figsize_per_line=(10, 2), fixed_legend_height_inches=0.5)

Plots the power flow on transmission lines over time.

Each unique transmission line (node_a to node_b) gets its own subplot. The y-axis label for each subplot is the line segment name. Legend is placed at the top center of the figure, occupying a fixed absolute height. Power flow is colored: - Green: Positive flow - Red: Negative flow - Black: Zero flow

Parameters:

• flow_variables (pd.DataFrame) – DataFrame with simulation results. Expected columns: ‘node_a’, ‘node_b’, ‘value’, ‘type’ (‘fwd’ or ‘bwd’), ‘hour’.

• figsize_per_line (tuple) – Tuple specifying (width, height_for_each_subplot_plot_area).

• fixed_legend_height_inches (float) – Absolute height in inches for the legend area at the top.

Return type:

None

plot_thermal_units(thermal_dispatch, unit_status, thermal_rated_capacity, output_folder=None)

Plot the on/off status of individual thermal units

Parameters:

• thermal_dispatch (pd.DataFrame) – The dispatch of each thermal unit.

• unit_status (pd.DataFrame) – The status of each thermal unit.

• thermal_rated_capacity (dict[str, float]) – Rated capacity of each thermal unit.

• output_folder (str) – If specified, then the plot is saved in the folder.

Return type:

None

Returns:

None

plot_unit_storage_state(hourly_storage_charge, hourly_storage_discharge, hourly_storage_state, output_folder=None)

Plot the hourly activity of the energy storage units.

Parameters:

• hourly_storage_charge (pd.Series) – Hourly charge data.

• hourly_storage_discharge (pd.Series) – Hourly discharge data.

• hourly_storage_state (pd.Series) – Hourly storage state data.

Return type:

None

pownet.coupler module

coupler.py: PowerWaterCoupler class to couple the power and water systems.

class pownet.coupler.PowerWaterCoupler(model_builder, reservoir_manager, solver='gurobi', mip_gap=0.0001, timelimit=600, log_to_console=False)

Bases: object

get_reop_iter()

get_reop_opt_time()

reoperate(step_k, max_reop_iter=100)

Reoperate the reservoirs based on the daily dispatch of the power system model. Note that we don’t reoperate on the first day of the simulation period.

Parameters:

step_k (int) – Current step in the simulation.

Return type:

None

Returns:

None

pownet.data_utils module

data_utils.py: functions for processing user inputs

pownet.data_utils.calc_remaining_duration(solution, sim_horizon, thermal_units, duration_dict, vartype)

Calculates the remaining duration (on or off) for each thermal unit.

This function analyzes the provided solution DataFrame to determine the latest timestep at which a specified event (startup or shutdown) occurred for each thermal unit. It then calculates the remaining duration based on the simulation horizon and the unit’s minimum required duration.

Parameters:

• solution (DataFrame) – A DataFrame containing the solution of the optimization model.

• sim_horizon (int) – The length of the simulation horizon.

• thermal_units (list[str]) – A list of thermal unit names.

• duration_dict (dict[str, int]) – A dictionary mapping unit names to their respective minimum durations.

• vartype (str) – The type of event to analyze. Either ‘startup’ or ‘shutdown’.

Return type:

dict[str, int]

Returns:

A dictionary mapping unit names to their remaining durations.

Raises:

ValueError – If the simulation horizon is shorter than the maximum duration of any thermal unit.

pownet.data_utils.calc_remaining_off_duration(solution, sim_horizon, thermal_units, TD)

Calculate the remaining shutdown duration for each thermal unit.

Parameters:

• solution (DataFrame) – A DataFrame containing the solution of the optimization model.

• sim_horizon (int) – The length of the simulation horizon.

• thermal_units (list[str]) – A list of thermal unit names.

• TD (dict[str, int]) – A dictionary mapping unit names to their respective minimum offline durations.

Return type:

dict[str, int]

Returns:

A dictionary mapping unit names to their remaining shutdown durations.

pownet.data_utils.calc_remaining_on_duration(solution, sim_horizon, thermal_units, TU)

Calculate the remaining online duration for each thermal unit.

Parameters:

• solution (DataFrame) – A DataFrame containing the solution of the optimization model.

• sim_horizon (int) – The length of the simulation horizon.

• thermal_units (list[str]) – A list of thermal unit names.

• TU (dict[str, int]) – A dictionary mapping unit names to their respective minimum online durations.

Return type:

dict[str, int]

Returns:

A dictionary mapping unit names to their remaining online durations.

pownet.data_utils.create_geoseries_columns(df)

Return type:

DataFrame

pownet.data_utils.create_init_condition(thermal_units, storage_units=None, ess_max_capacity=None)

Return dicts of system statuses in the format {(unit, hour): value}

Return type:

dict[(str, int), dict]

pownet.data_utils.get_capacity_value(t, unit, step_k, capacity_df)

Get the capacity value for a given unit and timestep. :type t: int :param t: The timestep. :type unit: str :param unit: The unit name. :type step_k: int :param step_k: The current simulation period. :type capacity_df: :param capacity_df: The dataframe containing the capacity values.

Return type:

float

Returns:

The capacity value for the given unit and timestep.

pownet.data_utils.get_current_time()

Return type:

str

pownet.data_utils.get_dates(year, num_days=365)

Return a dataframe of dates for the given year. The dataframe will have 365 rows, one for each day of the year. The columns are ‘date’ and ‘hour’. Exclude 29th February.

pownet.data_utils.get_datetime_index(year)

Return a datetime index for the given year. The index will have 8760 entries, one for each hour of the year. Exclude 29th February.

Return type:

DatetimeIndex

pownet.data_utils.get_edge_hour_from_varname(var_name)

Get the edge and hour from the variable name: flow_fwd[a,b,t] or flow_bwd[a,b,t].

Parameters:

var_name (str) – The name of the variable.

Return type:

tuple[tuple[str, str], int]

Returns:

The edge (tuple of two strings) and hour (int).

pownet.data_utils.get_fuel_color_map()

Return a map of fuel type to its color. This is defined in the database folder.

Return type:

dict

pownet.data_utils.get_fuel_mix_order()

Return the order of fuel mix for plotting. We use this list to order the node variables dataframe.

Return type:

list[str]

Returns

list[str]: The order of fuel mix.

pownet.data_utils.get_lines_params()

Return a dataframe of line parameters, located in database/transmission_params.csv

Return type:

DataFrame

pownet.data_utils.get_node_hour_from_flow_constraint(constraint_name)

Get the node and hour from the flow constraint name.

Parameters:

constraint_name (str) – The name of the constraint.

Return type:

tuple[str, int]

Returns:

The node and hour.

pownet.data_utils.get_unit_hour_from_varname(var_name)

Get the unit and hour from the variable name.

Parameters:

var_name (str) – The name of the variable.

Return type:

tuple[str, int]

Returns:

The unit and hour.

pownet.data_utils.parse_flow_variables(solution, sim_horizon, step_k)

Parses flow variables from the solution DataFrame. The flow variables are expected in the format: flow_fwd[node_a,node_b,t] or flow_bwd[node_a,node_b,t].

Parameters:

• solution (DataFrame) – The solution DataFrame with a ‘varname’ column.

• sim_horizon (int) – The length of the simulation horizon for a single step_k (e.g., 24 hours).

• step_k (int) – The current simulation period (1-indexed).

Returns:

A DataFrame with parsed flow variables, including

columns for ‘node_a’, ‘node_b’, ‘type’ (fwd/bwd), ‘value’, ‘timestep’ (relative to step_k), and ‘hour’ (absolute).

Return type:

pd.DataFrame

pownet.data_utils.parse_lmp(lmp, sim_horizon, step_k)

Parse the LMP dictionary and return a DataFrame.

Parameters:

• lmp (dict[str, float]) – The dictionary of LMP values.

• sim_horizon (int) – The length of the simulation horizon.

• step_k (int) – The current simulation period.

Returns:

The LMP DataFrame.

Return type:

pd.DataFrame

pownet.data_utils.parse_node_variables(solution, sim_horizon, step_k)

Parse the node variables from the solution DataFrame. Node variables are in the (node, t) format. Also, ensure binary values are rounded to 0 or 1.

Parameters:

• solution (DataFrame) – The solution DataFrame.

• sim_horizon (int) – The length of the simulation horizon.

• step_k (int) – The current simulation period.

Returns:

The node variables DataFrame

Return type:

pd.DataFrame

pownet.data_utils.parse_syswide_variables(solution, sim_horizon, step_k)

The system-wide variables are in the (t) format.

Parameters:

• solution (DataFrame) – The solution DataFrame.

• sim_horizon (int) – The length of the simulation horizon.

• step_k (int) – The current simulation period.

Returns:

The system-wide variables DataFrame

Return type:

pd.DataFrame

pownet.data_utils.remove_29feb(timeseries)

Clean and reindex flow data by removing February 29th and resetting the index.

Parameters:

timeseries (pd.Series) – Timeseries to be cleaned and reindexed.

Returns:

The cleaned and reindexed flow data.

Return type:

pd.Series

pownet.data_utils.write_df(df, output_folder, output_name, model_id)

Write a dataframe to the output folder.

Parameters:

• df (DataFrame) – The dataframe to write.

• output_name (str) – The name of the output file.

• model_id (str) – The model ID.

Return type:

None

Returns:

None

pownet.folder_utils module

folder_utils.py: Folder utility functions for pownet package.

pownet.folder_utils.get_database_dir()

Returns the database directory of the pownet package.

Return type:

str

pownet.folder_utils.get_home_dir()

Returns the home directory of the user. This is useful for testing purposes.

Return type:

str

pownet.folder_utils.get_pownet_dir()

Returns the root directory of the pownet package.

Return type:

str

pownet.folder_utils.get_test_dir()

Returns the test directory of the pownet package.

Return type:

str

pownet.input module

input.py: SystemInput class loads and checks the input data. It is used by other PowNet objects to access the input data.

class pownet.input.SystemInput(input_folder, model_name, year, sim_horizon, num_sim_days=365, use_spin_var=True, dc_opf='kirchhoff', use_nondispatch_status_var=False, spin_reserve_factor=0.15, spin_reserve_mw=None, gen_loss_factor=0.01, line_loss_factor=0.0001, line_capacity_factor=0.9, load_shortfall_penalty_factor=1000, load_curtail_penalty_factor=1000, spin_shortfall_penalty_factor=900, ess_discharge_shortfall_penalty_factor=900)

Bases: object

check_data()

Perform checks on the input data to ensure consistency and correctness.

get_unit_contracts()

Return type:

dict[str, str]

load_and_check_data()

Load and check the input data.

load_data()

Load the input data for the power system model. Timeseries are loaded as dataframes with the index starting at 1.

load_ess_params()

Load the techno-economic parameters of energy storage systems from energy_storage.csv.

load_thermal_unit_params()

Load the techno-economic parameters of thermal units from thermal_unit.csv.

print_summary()

update_capacity(capacity_df, unit_type)

Update a capacity timeseries of a given unit type (hydro, solar, wind, and import).

Parameters:

• capacity_df (DataFrame) – The new capacity timeseries.

• unit_type (str) – The type of the unit (hydro, solar, wind, import).

Raises:

• ValueError – If the given unit type is not supported.

• ValueError – If the length of the timeseries does not match the existing capacity timeseries.

• ValueError – If the timeseries does not contain all units of the given type.

Return type:

None