API Reference

Aggregate a nodal component matrix (bus x hour) to zones using bus weights.

build_endogenous_rep_periods(loaddata, afdata, ordered_zone, ordered_gen, config_set; drtsdata=nothing)

Construct endogenous representative-day inputs using the advanced settings in HOPE_rep_day_settings.yml. Representative periods are built from a shared joint/planning feature pipeline using either:

• clustering_method = kmedoids for actual observed representative days, or
• clustering_method = kmeans for synthetic centroid representative periods.

Extreme and iterative refinement days remain actual observed days.

Build nodal mapping metadata for PCM output post-processing. Returns bus labels, bus->zone index mapping, zone->bus index lists, and bus load-share weights.

Build a nodal PTDF matrix for PCM reporting/decomposition. For PTDF mode, prefer user-provided nodal PTDF input when valid; otherwise compute PTDF from line endpoints and reactance using the selected reference bus. For angle-based nodal mode, compute an equivalent PTDF from the same branch data.

calculate_erec(case::AbstractString; kwargs...)

Run the V1 EREC workflow for a GTEP case:

1. solve the baseline expansion case with planning reserve disabled,
2. reconstruct the solved fleet as a fixed redispatch case,
3. compute weighted EUE-based EREC values for generators and/or storage,
4. optionally write result CSVs and CC-updated tables.

Compute nodal congestion components using line shadow prices and PTDF sensitivities relative to the selected reference bus.

Compute PTDF matrix from line incidence and reactance data.

Convenience wrapper for zonal PTDF construction from linedata. Reserved for a future zonal-PTDF network mode. Current PCM behavior does not call this function:

• network_model=1 uses zonal transport
• network_model=2/3 use nodal DCOPF

create_GTEP_model(
    config_set::Dict,
    input_data::Dict,
    OPTIMIZER::MOI.OptimizerWithAttributes,
) -> Model

Build a JuMP model for the Generation and Transmission Expansion Planning (GTEP) problem.

config_set is the parsed settings dictionary; input_data is the dictionary returned by load_data; OPTIMIZER is the solver handle returned by initiate_solver.

The model captures investment decisions for generators, energy storage, and transmission lines subject to capacity adequacy, carbon policy, and network constraints. Returns the un-solved JuMP.Model.

create_PCM_model(
    config_set::Dict,
    input_data::Dict,
    OPTIMIZER::MOI.OptimizerWithAttributes,
) -> Model

Build a JuMP model for the Production Cost Model (PCM).

config_set is the parsed settings dictionary; input_data is the dictionary returned by load_data; OPTIMIZER is the solver handle returned by initiate_solver.

Supports zonal and nodal (DC OPF) network models, unit commitment (MILP), flexible demand response, and operation reserve requirements. Returns the un-solved JuMP.Model.

default_aggregation_settings(config_set::AbstractDict=Dict{String,Any}())

Return default advanced settings for resource aggregation. These settings are loaded from Settings/HOPE_aggregation_settings.yml when resource_aggregation = 1.

default_erec_settings()

Return the default settings dictionary for the Equivalent Reliability Enhancement Capability (EREC) postprocessing workflow.

default_rep_day_settings(config_set::AbstractDict=Dict{String,Any}())

Return default advanced settings for endogenous representative-day construction. These settings are loaded from Settings/HOPE_rep_day_settings.yml when endogenous_rep_day = 1.

get_representative_ts(df, time_periods, ordered_cols, k=1)

Deprecated helper retained for backward compatibility. It builds one synthetic centroid day per time period, independently by column.

solve_model(config_set::Dict, input_data::Dict, model::Model)

Solve the HOPE optimization model and print results.

Arguments

• config_set::Dict: Configuration settings from YAML file
• input_data::Dict: Input data loaded from files
• model::Model: JuMP model to solve

Returns

• Model: The solved optimization model

Throws

• Optimization errors if model fails to solve

initiate_solver(case::AbstractString, solver::AbstractString) -> MOI.OptimizerWithAttributes

Read solver settings from <case>/Settings/<solver>_settings.yml and return a MOI.OptimizerWithAttributes object that can be passed to create_GTEP_model or create_PCM_model.

solver must be one of "cbc", "clp", "glpk", "highs", "scip", "gurobi", or "cplex". Commercial solvers (gurobi, scip, cplex) require the corresponding Julia package to be installed separately.

load_aggregation_settings(case_path::AbstractString, config_set::AbstractDict)

Load optional advanced aggregation settings from Settings/HOPE_aggregation_settings.yml. Missing files fall back to built-in defaults.

load_data(config_set::Dict, path::AbstractString) -> Dict

Load all input data for a HOPE case from the directory path.

config_set is the parsed HOPE_model_settings.yml dictionary; it controls the model mode ("GTEP" or "PCM"), the data subfolder (DataCase), and optional pre-processing such as resource aggregation and endogenous representative-day selection.

Returns a Dict whose keys include "Gendata", "Loaddata", "Zonedata", "Linedata", and other model-mode-specific tables.

load_erec_settings(case_path::AbstractString)

Load optional EREC settings from Settings/HOPE_erec_settings.yml. Missing files fall back to built-in defaults.

load_rep_day_settings(case_path::AbstractString, config_set::AbstractDict)

Load optional endogenous representative-day settings from Settings/HOPE_rep_day_settings.yml. Missing files fall back to built-in defaults and legacy time_periods from HOPE_model_settings.yml.

Parse optional per-line loss rates from a line table.

Accepted aliases include percentage- or fraction-style columns such as Loss (%), Loss_pct, Loss Factor, and Line_Loss_Percentage. Values greater than 1 are interpreted as percentages and divided by 100. Missing values default to 0.

Resolve a reference node from either:

• integer index in 1..n_nodes
• node id key found in nodeidxmap

resolve_rep_day_time_periods(config_set::AbstractDict)

Return endogenous representative-day time periods as an ordered vector of Pair{Int,NTuple{4,Int}}. Advanced settings are read from config_set["rep_day_settings"] when available, otherwise legacy config_set["time_periods"] is used.

run_hope(case::AbstractString)

Run HOPE for a single case directory.

case is the path to a HOPE case directory (e.g., "ModelCases/IEEE14_PCM_case"). Multiple path formats are accepted: "HOPE/ModelCases/name", "ModelCases/name", or just "name" are all resolved to the same case. The HOPE_MODELCASES_PATH environment variable can point to a directory that is searched when the case is not found locally.

The function reads Settings/HOPE_model_settings.yml, loads input data, initialises the solver, builds the optimisation model, solves it, and writes CSV results under <case>/output/.

run_hope_holistic(GTEP_case::AbstractString, PCM_case::AbstractString) -> Dict

Run the two-stage holistic GTEP→PCM workflow.

1. The GTEP stage solves the expansion planning problem for GTEP_case.
2. New capacity decisions (generators, storage, transmission lines) are injected into the PCM_case input data.
3. The PCM stage solves the production cost problem with the updated fleet.

Both case directories must share a consistent zonal topology; mismatches raise an ArgumentError before any solve is attempted.

Returns a Dict with keys "gtep_output" and "pcm_output" containing the respective result dictionaries.

run_hope_holistic_fresh(
    GTEP_source_case::AbstractString,
    PCM_source_case::AbstractString;
    gtep_tag::AbstractString = "gtep_run",
    pcm_tag::AbstractString  = "pcm_run",
    debug_stage_file::Union{Nothing,AbstractString} = nothing,
) -> Dict

Clone both source cases to fresh timestamped directories, then run run_hope_holistic.

Each cloned directory is named <source>_<tag>_<timestamp> and placed next to the source case. Input files are copied; existing output/ trees are excluded so each run starts from a clean state.

Returns the same Dict as run_hope_holistic, extended with keys "fresh_gtep_case_path" and "fresh_pcm_case_path" pointing to the cloned directories.

solve_model(config_set::Dict, input_data::Dict, model::Model) -> Dict

Call optimize! on model and return a results dictionary containing solve timing.

When write_shadow_prices = 1 is set in config_set and the model contains integer variables (unit commitment or binary investment decisions), a second LP solve with fixed discrete variables is performed to recover dual prices.

write_output(
    outpath::AbstractString,
    config_set::Dict,
    input_data::Dict,
    model::Model,
)

Write optimisation results to CSV files in the directory outpath.

For GTEP mode the outputs include capacity decisions, investment costs, and generation dispatch summaries. For PCM mode they include hourly dispatch schedules, locational marginal prices, and (optionally) shadow prices from the LP re-solve step. outpath is created if it does not already exist; existing files are overwritten.