API reference

Function-by-function listing of the public surface. The package carries almost no docstrings, so this page is maintained by hand; signatures below were read directly from the source.

Names marked (exported) can be called unqualified after using PowerModelsTopologicalActions. Everything else needs the PowerModelsTopologicalActions. prefix (or an alias such as _PMTP.).

Problem specifications

Optimal transmission switching

run_acdcots_AC (exported)

run_acdcots_AC(file::String, model_type::Type, solver; kwargs...)
run_acdcots_AC(data::Dict{String,Any}, model_type::Type, solver; kwargs...)

OTS with switchable AC branches. The String method parses the file and calls PowerModelsACDC.process_additional_data! before delegating to the Dict method.

• model_type — ACPPowerModel (only validated option)
• solver — a JuMP optimizer; MINLP-capable, e.g. Juniper
• kwargs — forwarded to PowerModels.solve_model; commonly setting = s

Returns a PowerModels result dictionary. Switching states appear at result["solution"]["branch"][id]["br_status"].

Model builder: build_acdcots_AC.

run_acdcots_DC (exported)

run_acdcots_DC(file::String, model_type::Type, solver; kwargs...)
run_acdcots_DC(data::Dict{String,Any}, model_type::Type, solver; kwargs...)

OTS with switchable DC branches and AC/DC converters. AC branches remain fixed.

Results at result["solution"]["branchdc"][id]["br_status"] and result["solution"]["convdc"][id]["conv_status"].

Model builder: build_acdcots_DC.

run_acdcots_AC_DC (exported)

run_acdcots_AC_DC(file::String, model_type::Type, solver; kwargs...)
run_acdcots_AC_DC(data::Dict{String,Any}, model_type::Type, solver; kwargs...)

Joint AC and DC OTS. All of the above are switchable simultaneously.

Model builder: build_acdcots_AC_DC.

Busbar splitting

run_acdc_BuS_AC

run_acdc_BuS_AC(data, model_constructor, optimizer; kwargs...)

Busbar splitting on AC busbars. data must be a network prepared by AC_busbars_split.

• model_constructor — ACPPowerModel, SOCWRPowerModel, QCRMPowerModel, or LPACCPowerModel
• optimizer — matched to the formulation, see Formulations

Results at result["solution"]["switch"][id]["status"].

Model builder: build_acdc_BuS_AC. Objective: objective_min_fuel_cost_ac_switch.

run_acdc_BuS_DC

run_acdc_BuS_DC(data, model_constructor, optimizer; kwargs...)

Busbar splitting on DC busbars. Requires a network prepared by DC_busbars_split.

Results at result["solution"]["dcswitch"][id]["status"].

Model builder: build_acdc_BuS_DC. Objective: objective_min_fuel_cost_dc_switch.

run_acdc_BuS_AC_DC

run_acdc_BuS_AC_DC(data, model_constructor, optimizer; kwargs...)

Simultaneous AC and DC busbar splitting. Requires a network prepared by both AC_busbars_split and DC_busbars_split.

Model builder: build_acdc_BuS_AC_DC. Objective: objective_min_fuel_cost_ac_dc_switch.

Data preparation

AC_busbars_split

AC_busbars_split(data_original, bus_to_be_split)
    → (data, switch_couples, extremes_ZIL)

Prepares a hybrid AC/DC network for AC busbar splitting. bus_to_be_split is an Int or a Vector{Int}. Copies its input.

Returns the expanded network, the switch-couple dictionary, and a map from each split busbar to the indices of its two halves. See Data model.

Requires data["switch"] to exist and to be empty. Resets data["dcswitch_couples"] to an empty dictionary, so call this before DC_busbars_split, not after.

DC_busbars_split

DC_busbars_split(data_original, bus_to_be_split)
    → (data, dcswitch_couples, extremes_ZIL_dc)

DC-side equivalent. Copies its input. Creates data["dcswitch"], overwriting any existing content. Preserves an existing data["switch_couples"], so it is safe to call after AC_busbars_split.

AC_busbar_split_AC_grid

AC_busbar_split_AC_grid(data, bus_to_be_split) → (data, switch_couples, extremes_ZIL)

For AC-only networks with no DC components. Mutates its input.

AC_busbars_split_ordered

AC_busbars_split_ordered(data, bus_to_be_split) → (data, switch_couples, extremes_ZIL)

Variant preserving bus ordering. Mutates its input.

Multiconductor variants

AC_busbars_split_multiconductor(data, bus_to_be_split)
DC_busbars_split_multiconductor(data, bus_to_be_split)
DC_busbars_split_multiconductor_updated(data, bus_to_be_split)

For bipolar / multiconductor DC modelling. DC switch entries carry an additional terminal key. Prefer DC_busbars_split_multiconductor_updated over the older variant.

Switch-couple helpers

compute_couples_of_switches(data)          → Dict
compute_couples_of_dcswitches(data)        → Dict
compute_couples_of_dcswitches_mc(data)     → Dict

Called internally by the split functions. Use directly if you have modified the switch set and need to rebuild the couples. compute_couples_of_switches_feas_check skips the duplicate-elimination step and keeps both orientations.

Element inspection

elements_AC_busbar_split(data) → Dict
elements_DC_busbar_split(data) → Dict

Reports which generators, loads, branches, and converters are attached to each busbar flagged for splitting. Prints as it goes. Lives in the module marked DO NOT USE, but is read-only and safe.

Feasibility checking

prepare_AC_feasibility_check_AC_busbars(
    result_dict, input_dict, input_ac_check, switch_couples, extremes_dict, input_base)

prepare_AC_feasibility_check_DC_busbars(
    result_dict, input_dict, input_ac_check, switch_couples, extremes_dict, input_base)

prepare_AC_feasibility_check_AC_busbars_multiconductor(...)
prepare_AC_feasibility_check_DC_busbars_multiconductor(...)

Reconstruct a fixed-topology network from a busbar-splitting result.

• result_dict — result from a run_acdc_BuS_* call
• input_dict — the split network that result came from
• input_ac_check — mutated in place; pass a deepcopy
• switch_couples, extremes_dict — from the corresponding split function
• input_base — the original, unsplit network

Returns nothing meaningful; the output is the mutated third argument. Then solve PowerModelsACDC.solve_acdcopf on it. Verbose by design. See AC feasibility check.

Reference extensions

add_ref_dcgrid_dcswitch!

add_ref_dcgrid_dcswitch!(ref::Dict{Symbol,<:Any}, data::Dict{String,<:Any})

Ref extension building the DC-grid arc structures plus DC switch arcs (:arcs_dc_sw, :busdc_arcs_sw). Applied automatically by the BuS problem specifications; you only need it if you are writing your own builder.

buspair_parameters_dc

buspair_parameters_dc(arcs_dcgrid_from, branches, buses)

Computes bus-pair level structures for the DC grid.

Objectives

objective_min_fuel_cost_ac_switch(pm)      # gen cost + AC coupler penalty
objective_min_fuel_cost_dc_switch(pm)      # gen cost + DC coupler penalty
objective_min_fuel_cost_ac_dc_switch(pm)   # gen cost + both

calc_gen_cost(pm)         # Σ cost[end-1] · pg  — LINEAR TERM ONLY
calc_ac_switch_cost(pm)   # Σ cost · (1 − z_switch) over non-auxiliary switches
calc_dc_switch_cost(pm)   # Σ cost · (1 − z_dcswitch) over non-auxiliary switches

Variables

Switch indicators and powers:

variable_switch_indicator(pm; nw, relax=false, report=true)      # z_switch    → :switch/:status
variable_dc_switch_indicator(pm; nw, relax=false, report=true)   # z_dcswitch  → :dcswitch/:status
variable_switch_power(pm; kwargs...)                             # psw, qsw
variable_dc_switch_power(pm; nw, bounded=true, report=true)      # p_dcsw
variable_switch_current(pm; kwargs...)

OTS indicators:

variable_dc_branch_indicator(pm; nw, relax=false, report=true)   # z_ots_dc  → :branchdc/:br_status
variable_dc_conv_indicator(pm; nw, relax=false, report=true)     # z_conv_dc → :convdc/:conv_status
variable_branch_ots(pm; nw, relax=false, report=true)
variable_voltage_slack_ots(pm; nw, bounded=true, report=false)

Setting relax = true replaces the binary declaration with box bounds [0, 1], which is useful for diagnosing whether a difficult solve is driven by the combinatorics or the physics.

Linearised and single-period variants exist with _linearised and _sp suffixes.

Constraints

Constraint templates are in src/core/constraint_template.jl; formulation-specific implementations are in src/formconv/ (converters) and src/formdcgrid/ (DC grid and switches), split by model type: acp.jl, wr.jl, wrm.jl, lpac.jl, dcp.jl, shared.jl.

Switch constraints:

OTS constraints:

Relaxation helpers

relaxation_complex_product_conic(m, a, b, c)
relaxation_complex_product_conic_on_off(m, a, b, c, d, z)
relaxation_complex_product_on_off(m, a, b, c, d)

Convex relaxations of c² + d² ≤ a·b, with on/off variants for the switched case.