API Reference

Linearized MILP formulation using Ipopt that enforces exactly one binding line per transaction. Objective: minimize sum of absolute TTC errors (L1 norm).

calculate_all_ttc_results(Ybus, lines_df, tie_lines_df)

Computes TTC for all canonical transactions (a < b) WITHOUT storing PTDFs. Memory-optimized for large-scale systems.

calculate_single_injection_ptdfs(Ybus; reference_bus=1)

Core Engine: Factorizes B matrix once and solves for unit injections.

calculate_ttc_from_ptdfs(ptdf_df, line_capacities)

Calculate the Total Transfer Capacity (TTC) for every canonical transaction (A < B). Returns DataFrame with TTC values and limiting line information.

clean_line_data(lines_df::DataFrame)

Clean line data by removing self-loops and assigning fake EIC codes to missing entries.

convert_line_to_pu!(lines_df::DataFrame, Sbase::Float64; in_pu::Bool=false)

Convert line parameters to per-unit values based on system base power. If in_pu is true, assumes R, X, B are already in per-unit and only converts capacity.

create_ttc_results_from_optimization(
ttc_vals::Vector{Float64},
ttc_canonical::DataFrame;
model=model,
Type = CONFIG.optimization_type,
synth_lines::Vector{Tuple{Int,Int}} = Tuple{Int,Int}[],
binding_dict::Union{Dict,Nothing} = nothing
)

Create TTC results directly from optimization variables.

detect_islands(lines_df::DataFrame, tielines_df::DataFrame, node_info::DataFrame)

export_bus_id_map(node_info, export_path)

Export a CSV file containing the mapping between old bus names and new numerical IDs.

Arguments

• node_info::DataFrame: Node information with oldname and newid columns
• export_path::String: Path where the CSV file will be saved

Output CSV Format

• old_name: Original bus names from input data
• new_id: Numerical IDs assigned during processing

export_detailed_line_info(lines_df, tielines_df, export_path)

Export comprehensive line information including both original names and numerical IDs.

Arguments

• lines_df::DataFrame: Regular transmission lines data
• tielines_df::DataFrame: Tie lines data
• export_path::String: Path where the CSV file will be saved

Output CSV Columns

• EIC_Code: European Identification Code for the line
• Fromnode, Tonode: Original bus names
• NewIDFrom, NewIDTo: Numerical bus IDs
• Voltage_level: Operating voltage level
• Length_km: Line length in kilometers
• CapacityMW, Capacitypu: Line capacity in MW and per-unit
• Rpu, Xpu, B_pu: Line parameters in per-unit
• IsTieLine: Boolean flag indicating if this is a tie line

form_ybus_with_shunt(lines_df, tie_lines_df, node_info, Sbase)

Form the network admittance matrix (Y-bus) including shunt elements. Returns a sparse complex matrix representing the network admittance.

kron_reduce_ybus(Ybus, rep_node_ids)

Perform Kron reduction on the original Ybus matrix to eliminate non-representative nodes.

The Kron reduction technique eliminates internal nodes while preserving the electrical relationships between the representative nodes. This creates an equivalent network with fewer nodes but equivalent transfer characteristics.

Arguments

• Ybus::SparseMatrixCSC{ComplexF64}: Original network admittance matrix
• rep_node_ids::Vector{Int}: Indices of representative nodes to retain

Returns

• Y_kron::SparseMatrixCSC{ComplexF64}: Reduced admittance matrix

Mathematical Background

The Kron reduction partitions the admittance matrix as:

Y = [K   L_T]
    [L   M  ]

where K connects representative nodes, M connects eliminated nodes, and L connects representative to eliminated nodes.

The reduced matrix is: Ykron = K - LT * M^(-1) * L

load_excel_data(file_path::String)

Load network data from Excel file with multiple sheets. Returns a dictionary containing DataFrames for lines, tielines, nodes, and generators.

main_full_analysis(input_data_dir, output_data_dir)

Complete network reduction analysis workflow including:

1. Data loading and preprocessing
2. Island detection (optional, when CONFIG.enable_plots = true)
3. Original network Y-bus and TTC/PTDF analysis
4. Representative node selection
5. Kron reduction
6. Virtual line filtering (when CONFIG.allow_virtual_lines = false)
7. Reduced network PTDF analysis
8. Optimization of equivalent capacities
9. Results comparison and export

Returns

Nothing. All results are written to CSV files in output_data_dir.

Output Files

All filenames use CONFIG.suffix as a postfix:

• Bus_ID_Map_<suffix>.csv: Mapping of original bus names to sequential integer IDs
• Line_Details_<suffix>.csv: Comprehensive line information
• Representative_Nodes_<suffix>.csv: Selected representative nodes per zone
• TTC_Original_Network_<suffix>.csv: Original network TTC values
• PTDF_Reduced_Network_<suffix>.csv: Reduced network PTDF values
• Equivalent_Capacities_<suffix>.csv: Optimized synthetic line capacities and reactances
• TTC_Comparison_<suffix>.csv: Comparison of original vs equivalent TTC values
• Network_Original_<suffix>.png: Original network plot (only when enable_plots = true)
• Network_Reduced_<suffix>.png: Reduced network plot (only when enable_plots = true)
• Network_Original_vs_Reduced_<suffix>.png: Side-by-side comparison plot (only when enable_plots = true)

plot_network(g, node_info, lines_df; title, n_size, f_size, show_names)

Plot a network graph with nodes coloured by island (connected component). Only called when CONFIG.enable_plots = true. Uses Latitude/Longitude columns for geo-layout if present in node_info, otherwise uses a spring layout.

plot_original_vs_reduced(g_orig, nodes_orig, lines_orig, g_red, nodes_red, lines_red, output_path)

Plot original and reduced networks side-by-side (1400×700 px) and save to output_path. Only called when CONFIG.enable_plots = true.

process_tielines(tielines_df::DataFrame)

Process tie-lines by sorting, removing duplicates, and handling missing EIC codes.

rename_buses(nodes_df, generators_df, lines_df, tie_lines_df, Sbase)

Rename buses, create numerical mapping, convert to per-unit, and preserve the IsRepresentative column from Excel.

reset_config!()

Resets the global CONFIG object to its default values. Useful for batch testing multiple case studies.

select_representative_nodes(Ybus::SparseMatrixCSC{ComplexF64}, node_info::DataFrame)

Select representative nodes using one of two modes controlled by CONFIG.repnodemode:

• "auto" (default): Select top CONFIG.rep_node_k_per_zone highest-degree nodes per zone
• "manual_excel": Use nodes marked in column IsRepresentative in the Nodes sheet

If manual mode is selected but the column is missing, falls back to auto mode with a warning. Always ensures :isrepresentative column exists in nodeinfo.

Config

Central configuration struct for the entire network reduction workflow. Modify the default values below to run different case studies.