API Reference

_axis_limits(lons, lats; pad) -> (lon_lo, lon_hi, lat_lo, lat_hi)

Return axis limits with pad fractional padding on each side (minimum 1°).

_convex_hull_2d(pts) -> Vector{Point2f}

Compute the 2-D convex hull via Andrew's monotone-chain algorithm. Pure Julia, no dependencies. Returns the hull vertices in counter-clockwise order. Falls back to the original point set for degenerate inputs (≤ 2 pts).

_draw_highres_highlight!(ax, nodes_df, cos_lat)

Overlay a semi-transparent convex-hull polygon on ax for every zone listed in CONFIG.high_res_zones, using the geographic positions in nodes_df. A single bold zone-code + "(high-res)" label is placed above the cluster.

Should be called BEFORE graphplot! so the network nodes render on top of the shaded area. No-op when CONFIG.high_res_zones is empty or when coordinates are unavailable.

_edge_info(g, node_info, lines_df) -> (edge_colors, edge_widths)

Build per-edge colour and width vectors (aligned with Graphs.edges(g)) from line-type metadata in lines_df.

:gray — AC line :red — AC tie-line :royalblue — DC interconnector (thicker)

_gis_params(n_orig, n_red) -> NamedTuple

Compute size-tier parameters for CairoMakie/GraphMakie plots based on the number of buses in the original and reduced networks. All functions that produce PNG output call this helper so visual quality scales automatically from a 6-bus test case to a 6792-bus European grid.

_red_node_sizes(nodes_df, rep_sz, hr_sz) -> Vector{Float32}

Per-node size vector for the reduced network. External zone representative nodes get rep_sz (large). Individual buses inside high-resolution zones get hr_sz (small), so the lines between them stay visible rather than being hidden under large markers. Falls back to all-rep_sz when no high-res zones are configured.

Binding-line MILP solved by HiGHS.

This method supersedes the older Z-allocation MILP above. It fits the AC recomputed TTC directly:

TTC_eq[t] = min_l C_eq[l] / abs(PTDF[t,l])

Physical upper-bound constraints are enforced for every relevant (transaction, line) pair; binary binding choices are restricted to likely limiting lines for scalability.

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

build_converter_map(converters_df::DataFrame) -> Dict{String,String}

Return a Dict mapping each DC terminal bus name to its connected AC substation bus name. Used by remapdcendpoints! to rewrite DCLine endpoints before numeric ID assignment.

build_dc_capacity_map(dclines_df, node_info, rep_node_ids; lines_df, tielines_df)

Build a Dict mapping representative-node pairs to aggregated DC capacity (pu).

Physical DC converter buses are remapped to a representative node in the same AC connected component whenever AC line data are provided. Intra-zone DC lines are skipped only when both endpoints are in the same AC component; intra-zone DC bridges between separate AC islands are kept. Multiple DC lines between the same representative-node pair are summed. This map is later used for additive TTC contribution and as a floor constraint in optimisation.

Returns

Dict{Tuple{Int,Int}, Float64} keyed by (minrepid, maxrepid)

calculate_all_ttc_results(Ybus, lines_df, tie_lines_df; dc_cap_map)

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

DC lines contribute additively: TTC(a,b) = TTCAC(a,b) + CDC(a,b)

Pass an empty Dict (default) when no DC lines are present — the function then behaves identically to the original.

When CONFIG.parallel_processing = true and Julia is started with multiple threads (e.g. julia --threads=auto), the TTC enumeration loop is distributed across all available threads using Threads.@threads :static. The PTDF basis computation (LU factorisation + back-solves) is always sequential because SuiteSparse UMFPACK back-solves are not thread-safe on a shared factorisation object.

Keyword arguments

• dc_cap_map : Dict{Tuple{Int,Int},Float64} from builddccapacitymap(). Keys are (minrepid, maxrep_id), values are capacity in pu.

calculate_ptdfs_reduced(Y_kron, rep_node_ids; high_res_ids)

Calculates PTDFs for the smaller equivalent network. Uses local indices for calculation and maps back to original IDs for output.

When high_res_ids is non-empty (high-resolution zone mode), pairs where both endpoints are in the high-res set are skipped: their PTDFs are determined by the original physical network, and including them would make the computation O(n_hires²) — infeasible for large zones. Cross-boundary and external-only pairs are still computed normally.

calculate_single_injection_ptdfs(Ybus; reference_bus=1)

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

Handles multi-island (multi-synchronous-zone) networks by detecting AC connected components and using one reference bus per component. Returns a nodecomponent vector so callers can identify cross-island transactions (TTCAC = Inf).

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_optimisation(
ttc_vals::Vector{Float64},
ttc_canonical::DataFrame;
model=model,
Type = CONFIG.optimisation_type,
synth_lines::Vector{Tuple{Int,Int}} = Tuple{Int,Int}[],
binding_dict::Union{Dict,Nothing} = nothing
)

Create TTC results directly from optimisation variables.

detect_islands(lines_df, tielines_df, node_info, dclines_df)

Build the original-network graph (AC + DC edges) and label each node with its connected-component island index. DC lines are included as graph edges so that DC-only connections appear in the plot and island detection is correct.

diagnose_islands(lines_df, tielines_df, node_info; dclines_df, top_n)

Analyse AC-only connected components and print a diagnostic report to help distinguish between physically-real islands and data-gap artefacts (e.g. missing transformers between voltage levels in the same zone).

Returns a summary DataFrame (one row per island, sorted largest-first) and the raw components / node_comp vectors for further use.

Columns in the returned DataFrame

• island_id: internal component index
• n_buses: number of buses in the island
• zones: semicolon-separated list of zones with bus counts, e.g. "DE(43);FR(12)"
• voltage_kv: semicolon-separated sorted unique voltage levels
• dc_bridge: true if a DC line links this island to another
• diagnosis: "SUSPECT", "DC-ONLY", "SINGLETON", or "REAL"
• suspect_zones: zones that triggered SUSPECT (empty otherwise)

Arguments

• lines_df, tielines_df: AC branch DataFrames (must have :From, :To)
• node_info: bus metadata (must have :new_id, :Zone, :baseKV)
• dclines_df: DC branch DataFrame (optional; used to flag DC-bridge islands)
• top_n: print only the top_n largest islands in the terminal (0 = all)

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

export_island_diagnostics(summary_df, output_path)

Write the island diagnostic summary DataFrame to a CSV file.

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 eleven-step network reduction analysis workflow:

1. Data loading and preprocessing (AC lines, tie-lines, transformers, DC lines, converters)
2. Island detection and original network plot (when CONFIG.enable_plots = true)
3. Y-bus assembly (AC only) and export of island diagnostics, bus ID map, line details
4. Representative node selection (auto by degree, or manual from Excel)
5. Virtual line filter and DC capacity map construction
6. Original network TTC/PTDF analysis (AC + additive DC, parallelised when parallel_processing = true)
7. Kron reduction of non-representative nodes
8. Reduced-network PTDF computation
9. Optimisation of equivalent line capacities (QP / LP / MIQP via JuMP + Ipopt / HiGHS)
10. Reduced network visualisation (when CONFIG.enable_plots = true)
11. TTC comparison and export of all results to CSV

Set CONFIG.has_dc_lines = true and provide a DCLines sheet in the Excel file to enable DC line integration.

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
• Island_Diagnostics_<suffix>.csv: Per-island summary (size, zones, voltage levels, diagnosis)
• Line_Details_<suffix>.csv: Comprehensive line information (per-unit parameters)
• TTC_Original_Network_<suffix>.csv: Original network TTC values (AC + DC columns)
• PTDF_Reduced_Network_<suffix>.csv: Reduced network PTDF values
• Equivalent_Capacities_<suffix>.csv: Optimised synthetic line capacities, reactances, and DC flags
• 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.

Three separate graphplot layers are drawn so each line type gets a reliable single-colour call:

• Gray — AC lines • Red — AC tie-lines • Blue — DC interconnectors (curved, so parallel AC+DC pairs appear distinct)

Uses Latitude/Longitude columns for geo-layout if present in node_info; otherwise uses a deterministic circular layout.

plot_network_gis(g, node_info, lines_df; title, show_names, node_sz) -> Figure

Plot the power network on a plain lon/lat axis. Nodes are coloured by zone; edges are coloured by type (gray = AC, red = tie-line, blue = DC). No external GIS data is required.

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.

plot_original_vs_reduced_gis(g_orig, nodes_orig, lines_orig,
                              g_red,  nodes_red,  lines_red;
                              main_title) -> Figure

Side-by-side lon/lat comparison (3000×1200 px). Left panel: full original network (nodes unlabelled for clarity). Right panel: reduced network (nodes labelled by name). Both panels share the same lon/lat bounding box from the original network.

process_converters(converters_df::DataFrame)

Clean and standardise the Converters sheet.

Each row represents one AC/DC interface: Fromnode — DC terminal bus name (bare OSM ID, e.g. way/920127890) Tonode — AC substation bus name (voltage-suffixed, e.g. way/920127890-380)

The same name-cleaning rules (uppercase + strip) used everywhere else are applied so that converter map keys match the names produced by renamebuses and renamedc_buses.

process_dclines(dclines_df::DataFrame, Sbase::Float64)

Process DC interconnector lines.

DC lines have no AC impedance parameters (R, X, B are set to zero and must NEVER be passed to formybuswith_shunt or any PTDF calculation). Their capacity contributes additively to inter-zonal TTC after AC reduction.

Required columns in the DCLines Excel sheet: Fromnode – sending-end bus name (must exist in Nodes sheet) Tonode – receiving-end bus name (must exist in Nodes sheet) CapacityMW – rated capacity in MW (symmetric; same limit both directions) EICCode – identifier (optional)

process_tielines(tielines_df::DataFrame)

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

process_transformers(transformers_df::DataFrame)

Prepare transformer data for integration with the AC line pipeline.

Transformers are treated as AC elements: IsTieLine = false, IsDCLine = false. The sheet must use the same column names as the Lines sheet for Fromnode, Tonode, X, and Capacity_MW. R and B columns are optional and default to 0 when absent.

Missing EIC codes are assigned synthetic identifiers.

remap_dc_endpoints!(dclines_df, converter_map)

Replace DC terminal bus names in DCLines with their connected AC substation bus names, using the map built from the Converters sheet.

DC cables physically connect between converter-station DC terminals. For PTDF/TTC analysis the relevant injection point is the AC bus adjacent to the converter, not the DC terminal itself. After remapping, every DC line endpoint refers to an AC bus that exists in the Y-bus, eliminating DC-terminal singleton islands and ensuring correct zone attribution in builddccapacity_map.

Endpoints with no converter entry are left unchanged; renamedcbuses will validate them and raise a descriptive error if they are also absent from the Nodes sheet.

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.

rename_dc_buses(dclines_df, bus_map)

Map DC line Fromnode/Tonode names to numerical IDs using the busmap produced by renamebuses. Validates that all DC bus names exist in the Nodes sheet and raises a descriptive error if any are missing.

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 nodes per zone by degree, using incident capacity as a tie-breaker. If an AC island is left without a representative, add the best-ranked bus from that island.
• "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.