ExplanDataHandler Class

The ExplanDataHandler class processes input data for the optimization model used in QuESt Planning. This class provides functionality to load, manipulate, and prepare datasets required for simulation and optimization.

Authors: C. Newlun and W. Olis

Class Initialization

class ExplanDataHandler

Initializes the ExplanDataHandler class with default attributes.

Attributes:

• block_selection: Selected block type for load profile segmentation.

• tx_model: Transmission model type.

• trans_expansion: Determines whether transmission expansion is enabled.

• load_growth (default: 1.5): Annual load growth rate.

• load_forecast: Selected load forecast.

• es_cost: Energy storage cost type (e.g., Base, Low, High).

• ldes_switch: Enables/disables long-duration energy storage options.

• solver: Optimization solver used.

• years: Simulation years.

• season_time_duration: Seasonal time weights.

Public Methods

set_data_ls_index(data_ls)

Sets or initializes the data list index.

Parameters:

• data_ls (list): List of data categories. If None, defaults to predefined categories.

Example Usage:

>>> handler.set_data_ls_index(['branch', 'bus', 'load'])

Simulation Parameters

set_start_year(year)

Sets the start year of the simulation.

Parameters:

• year (int): Start year.

Example Usage:

>>> handler.set_start_year(2025)

set_end_year(year)

Sets the end year of the simulation.

Parameters:

• year (int): End year.

Example Usage:

>>> handler.set_end_year(2030)

set_year_gap(value)

Sets the interval between simulation years.

Parameters:

• value (int): Year gap.

Example Usage:

>>> handler.set_year_gap(5)

set_years_hours(years)

Defines the simulation years and calculates year gaps.

Parameters:

• years (list): List of simulation years.

Example Usage:

>>> handler.set_years_hours([2025, 2030, 2035])

Modeling Configuration

set_tx_model(value)

Sets the transmission model type.

Parameters:

• value (str): Transmission model type. Options include “Transportation” or “Copper Sheet”.

Example Usage:

>>> handler.set_tx_model("Copper Sheet")

set_block_selection(value)

Defines the block selection for load profiles.

Parameters:

• value (str): Block selection type (e.g., ‘Full_year’, ‘Peak_Day’).

Example Usage:

>>> handler.set_block_selection("Peak_Day")

set_discount_rate(value)

Sets the discount rate used in modeling.

Parameters:

• value (float): Discount rate (e.g., 0.05 for 5%).

Example Usage:

>>> handler.set_discount_rate(0.05)

set_scenario(value)

Sets the scenario name for the simulation.

Parameters:

• value (str): Scenario name.

Example Usage:

>>> handler.set_scenario("High Load Growth")

Data Management

get_data()

Loads all data from CSV files into the load_data attribute.

Dependencies:

• Requires data_ls and data_dir to be properly initialized.

Example Usage:

>>> handler.get_data()

get_tech_nums()

Defines generator technology categories and assigns tech numbers for each category.

Example Usage:

>>> handler.get_tech_nums()

define_bus_nums()

Defines bus numbers for different technology categories and creates mappings for network edges.

Example Usage:

>>> handler.define_bus_nums()

Visualization

plot_load_profile(fig, ax, load_forecast)

Plots the system-wide load profile using Matplotlib.

Parameters:

• fig (matplotlib.figure.Figure): Figure object.

• ax (matplotlib.axes.Axes): Axes object.

• load_forecast (str): Column name for load forecast data.

Example Usage:

>>> fig, ax = plt.subplots()
>>> handler.plot_load_profile(fig, ax, 'Base Forecast')

create_network_diagram(fig, ax, use_map)

Creates a network diagram of the system.

Parameters:

• fig (matplotlib.figure.Figure): Figure object.

• ax (matplotlib.axes.Axes): Axes object.

• use_map (bool): Whether to overlay on a geographic map.

Example Usage:

>>> fig, ax = plt.subplots()
>>> handler.create_network_diagram(fig, ax, False)

Advanced Functionality

add_candidate_tech(tech, storage)

Adds candidate technology characteristics to the database.

Parameters:

• tech (dict): Candidate technology characteristics.

• storage (bool): Indicates whether the technology is energy storage.

Example Usage:

>>> tech = {
...     'Name': 'Solar_Cand',
...     'Candidate Capacity': 500,
...     'Capacity Credit': 0.8,
...     'Lead Time': 3,
...     'Deployable Year': 2026,
...     'PTC Credit': 0.02,
...     'ITC Credit': 0.1,
...     'Lifetime': 25,
...     'Ramp Rate': 1.0
... }
>>> handler.add_candidate_tech(tech, storage=True)

API Reference

For a detailed reference of all methods, attributes, and inherited properties, refer to the autodoc-generated content below.

QuESt Planning - explan data handler used to process input data for the optimization model Authors: C. Newlun and W. Olis

class quest_planning.explan.explan_data_handler.ExplanDataHandler

Bases: object

add_candidate_tech(tech, storage)

Add candidate technology selection from user to the database

tech - candidate tech characteristics in dict form

capex_es_energy_par_adjust()

For energy storage technologies energy rating cost

Returns:

capex_es_energy_df_dict

Return type:

Dictionary of capex data with correct indices

capex_es_pwr_par_adjust()

For energy storage technologies power rating cost

Returns:

capex_es_pwr_df_dict

Return type:

Dictionary of capex data with correct indices

capex_par_adjust()

For non-energy storage technologies, adjust capex data

Returns:

capex_df_dict

Return type:

Dictionary of capex data with correct indices

construct_load_blocks()

Construct load blocks (time steps) based on user input WARNING: Not all selections work!

create_network_diagram(fig, ax, use_map)

create_season_map()

Creates season map

Return type:

None.

current_generation_mix_piechart(fig, ax)

Show current generation mix via piechart

define_bus_nums()

Define bus numbers to be used in model to define sets

find_system_energy()

Determines the annual system energy

Returns:

energy_pivot

Return type:

Returns annual system energy

find_system_peak()

Determines the annual system peak

Returns:

peak_pivot

Return type:

Dictionary of annual peak

fp_par_adjust()

Adjust fuel price data for model input

Returns:

fuel_df_dict

Return type:

Dictionary of fuel price data

get_data()

Load all data from csv files for input into the model.

get_tech_nums()

Develop generator tech number sets - Improved process flow TODO: move to csv files for improved usability

load_par_adjust()

Adjust the load parameter to be inputted into the pyomo models

Parameters:

• df (input dataframe)

• bus_frac (array of percenatages to distribute load)

• block_selection (specify block selection)

Returns:

load_dict

Return type:

dictionary containing input ready data

plot_load_profile(fig, ax, load_forecast)

Plot load profile for power system data page

plot_load_profile_plotly(load_forecast)

Plot load profile for power system data page using plotly (optional)

ren_profile_par_adj(tech_type)

Renewable profile adjustment for model input

Parameters:

tech_type (Technology type)

Returns:

ren_df_all_years

Return type:

dictionary for model input

round_params(data_dict)

Optional function to round parameter values

set_base_currency_year(value)

Set base currency year

set_block_selection(value)

Set the block selection type

set_capital_cost_trend(value)

Set the capital cost trend for energy storage

set_co2_intensity_policy(value)

Enforce co2 policy

set_co2_policy(value)

Enforce co2 policy

set_custom_retirement_years(custom_retirement, ng_retirement_year, coal_retirement_year, nuclear_retirement_year, oil_retirement_year)

Sets custom retirement options based on fuel type :param custom_retirement: :type custom_retirement: Custom retirement option TRUE or FALSE :param ng_retirement_year: :type ng_retirement_year: Retirement year of natural gas :param coal_retirement_year: :type coal_retirement_year: Retirement year of coal :param nuclear_retirement_year: :type nuclear_retirement_year: Retirement year of nuclear :param oil_retirement_year: :type oil_retirement_year: Retirement year of oil

set_data_ls_index(data_ls)

set_discount_rate(value)

Set the discount rate

set_end_effects(value)

Set end effects

set_end_year(year)

Set the end year of the simulation period

set_es_cost(value)

Set the annual load growth

set_es_lifetime_cost_option(value)

Set option to evaluate ES lifetime extension (replacement) cost

set_es_lifetime_extension(value)

Set number of years to asses lifetime extension of new ES assets

set_es_soc_min_max(soc_min, soc_max, ini_level)

Set ES SOC minimum, maximum, and initial level

set_ldes_switch(value)

Set the ldes_switch

set_load_growth(value)

Set the annual load growth used if a full load forecast is not uploaded

set_load_profile(value)

Set the load profile selection

set_mva_base(value)

Set mva base

set_reserve_params(prm, reg_res_req, spin_res_req, flex_res_w_req, flex_res_s_req)

Set reserves requirements (Convert to percent)

set_reserves_option(value)

set_resource_bus_limits(d)

set_retirements(value)

Set the retirement selections - GUI Only

set_rps_schedule(value, option)

Set the RPS schedule - GUI Only

set_scenario(value)

Set the scenario name

set_solver(value)

Set the optimization solver

set_start_year(year)

Set the start year of the simulation period

set_system_name(value)

set_system_wide_gas_max(value)

Set system-wide maximum gas expansion

set_system_wide_solar_max(value)

Set system-wide maximum solar investment

set_system_wide_tx_expansion_max(value)

Set system wide maximum transmission expansion

set_system_wide_wind_max(value)

Set system-wide maximum wind investment

set_tax_credit_end_year(value)

Set tax credit end year

set_tax_credits_option(value)

Set option to enforce tax credits

set_transmission_expansion(value)

Set the transmission expansion type

set_tx_model(value)

Set the transmission model type

set_voll(value)

Set the value of lost load

set_year_gap(value)

Set the year gap of the simulation period

set_years_hours(years)

Define years and year gap