IO

parse_file(network_file::String; dss2eng_extensions=Function[], transformations=Function[], import_all=true, kwargs...)

ONM version of PowerModelsDistribution.parse_file, which includes some dss2eng_extensions and transformations by default

parse_network(
    network_file::String
)::Tuple{Dict{String,Any},Dict{String,Any}}

Parses network file given by runtime arguments into its base network, i.e., not expanded into a multinetwork, and multinetwork, which is the multinetwork ENGINEERING representation of the network.

parse_network!(args::Dict{String,<:Any})::Dict{String,Any}

In-place version of parse_network, returns the ENGINEERING multinetwork data structure, which is available in args under args["network"], and adds the non-expanded ENGINEERING data structure under args["base_network"]

parse_events(
    events_file::String;
    validate::Bool=true
)::Vector{Dict{String,Any}}

Parses an events file into a raw events data structure

Validation

If validate=true (default), the parsed data structure will be validated against the latest Events Schema.

parse_events(
    raw_events::Vector{<:Dict{String,<:Any}},
    mn_data::Dict{String,<:Any}
)::Dict{String,Any}

Converts raw_events, e.g. loaded from JSON, and therefore in the format Vector{Dict}, to an internal data structure that closely matches the multinetwork data structure for easy merging (applying) to the multinetwork data structure.

Will attempt to find the correct subnetwork from the specified timestep by using "mn_lookup" in the multinetwork data structure.

Switch events

Will find the correct switch id from a source_id, i.e., the assettype.name from the source file, which for switches will be line.name, and create a data structure containing the properties defined in `eventdata` under the native ENGINEERING switch id.

Fault events

Will attempt to find the appropriate switches that need to be OPEN to isolate a fault, and disable them, i.e., set dispatchable=false, until the end of the duration of the fault, which is specified in milliseconds.

It will re-enable the switches, i.e., set dispatchable=true after the fault has ended, if the next timestep exists, but will not automatically set the switches to CLOSED again; this is a decision for the algorithm optimize_switches to make.

parse_events(
    events_file::String,
    mn_data::Dict{String,<:Any};
    validate::Bool=true
)::Dict{String,Any}

Parses raw events from events_file and passes it to parse_events to convert to the native data type.

Validation

If validate=true (default), the parsed data structure will be validated against the latest Events Schema.

parse_events!(
    args::Dict{String,<:Any};
    validate::Bool=true,
    apply::Bool=true
)::Dict{String,Any}

Parses events file in-place using parse_events, for use inside of entrypoint.

If apply, will apply the events to the multinetwork data structure.

Validation

If validate=true (default), the parsed data structure will be validated against the latest Events Schema.

parse_settings(
    settings_file::String;
    validate::Bool=true
    correct::Bool=true
)::Dict{String,Any}

Parses network settings JSON file.

Validation

If validate=true (default), the parsed data structure will be validated against the latest Settings Schema.

parse_settings!(
    args::Dict{String,<:Any};
    apply::Bool=true,
    validate::Bool=true
)::Dict{String,Any}

Parses settings file specifed in runtime arguments in-place

Will attempt to convert deprecated runtime arguments to appropriate network settings data structure.

Validation

If validate=true (default), the parsed data structure will be validated against the latest Settings Schema.

parse_faults(
    faults_file::String;
    validate::Bool=true
)::Dict{String,Any}

Parses fault JSON input files which have the same structure as the outputs from PowerModelsProtection.build_mc_fault_stuides

Expected JSON Structure

{
    "bus_name": {
        "fault_type": {
            "fault_key": {
                "g": [ [200, -100, -100], [-100, 200, -100], [-100, -100, 200]],
                "b": [ [0, 0, 0], [0, 0, 0], [0, 0, 0]],
                "status": "ENABLED",
                "fault_type": "fault_type",
                "bus": "bus_name",
                "name": "fault_key",
                "connections": [1, 2, 3]
            }
        }
    }
}

where "fault_type" is one of:

• "3p" : 3-phase
• "3pg" : 3-phase-to-ground
• "ll" : line-to-line
• "llg" : line-to-line-to-ground
• "ll" : line-to-line

"bus_name" is arbitrary, and just needs to match a bus's name in the network model.

"status" is a PowerModelsDistribution.Status Enum in String form, and must be either "ENABLED" or "DISABLED".

"g" and "b" are matrices in SI units.

"fault_type" in the deepest level is merely metadata and should match the "fault_type" key above.

"name" should match the fault key and is required to be an Integer.

"connections" is a Vector of Integers indicating the phases that the fault applies to.

For more details see PowerModelsProtection's documentation

Validation

If validate=true (default), the parsed data structure will be validated against the latest Faults Schema.

parse_inverters(
    inverter_file::String;
    validate::Bool=true
)::Dict{String,Any}

Parses an inverters JSON file, used in run_stability_analysis!

Validation

If validate=true (default), the parsed data structure will be validated against the latest Inverters Schema.

build_events_file(case_file::String, io::IO; kwargs...)

A helper function to save a rudamentary events data structure to io from a network case at path case_file.

build_events_file(eng::Dict{String,<:Any}, io::IO; kwargs...)

A helper function to save a rudamentary events data structure to io from a network case eng.

build_events_file(case_file::String, events_file::String; kwargs...)

A helper function to build a rudamentary events_file from a network case at path case_file.

build_events_file(eng::Dict{String,<:Any}, events_file::String; kwargs...)

A helper function to build a rudamentary events_file from a network case eng.

build_settings_file(network_file::String, settings_file::String; kwargs...)

Builds and writes a settings_file::String by parsing a network_file

build_settings_file(eng::Dict{String,<:Any}, settings_file::String; kwargs...)

Builds and writes a settings_file::String from a network data set eng::Dict{String,Any}

build_settings_file(
    network_file::String,
    settings_file::String="settings.json";
    kwargs...
)

Helper function to write a settings structure to an io for use with ONM from a network data structure eng::Dict{String,<:Any}.

apply_events(
    network::Dict{String,<:Any},
    events::Dict{String,<:Any}
)::Dict{String,Any}

Creates a copy of the multinetwork data structure network and applies the events in events to that data.

apply_events!(args::Dict{String,<:Any})::Dict{String,Any}

Applies events in-place using apply_events, for use inside of entrypoint

apply_settings(
    network::Dict{String,<:Any},
    settings::Dict{String,<:Any};
    multinetwork::Bool=true
)::Dict{String,Any}

Applies settings to single-network network

apply_settings!(args::Dict{String,Any}; multinetwork::Bool=true)::Dict{String,Any}

Applies settings to the network.

initialize_output(args::Dict{String,<:Any})::Dict{String,Any}

Initializes the empty data structure for "output_data"

get_protection_network_model(base_eng::Dict{String,<:Any})

Builds a network data model for use in Protection optimization from the base network model base_eng.

get_protection_network_model!(args::Dict{String,<:Any})

Builds a network data model for use in Protection settings optimization.

get_timestep_bus_types(::Dict{String,<:Any}, ::String)::Vector{Dict{String,String}}

Helper function for the variant where args["network"] hasn't been parsed yet.

get_timestep_bus_types(
    optimal_dispatch_solution::Dict{String,<:Any},
    network::Dict{String,<:Any}
)::Vector{Dict{String,String}}

Gets bus types (PQ, PV, ref, isolated) for each timestep from the optimal_dispatch_solution

get_timestep_bus_types!(args::Dict{String,<:Any})::Vector{Dict{String,String}}

Gets bus types (PQ, PV, ref, isolated) for each timestep from the optimal dispatch result and assigns it to args["output_data"]["Protection settings"]["bus_types"]

write_json(
    file::String,
    data::Dict{String,<:Any};
    indent::Union{Int,Missing}=missing
)

Write JSON data to file. If !ismissing(indent), JSON will be pretty-formatted with indent

get_option(network::Dict{String,<:Any}, path::Tuple{Vararg{String}}, default::Any=missing)::Any

Helper function to get a property at an arbitrary nested path in a network dictionary, returning the default value if path does not exist.

get_option(settings_file::String, path::Tuple{Vararg{String}}, default::Any=missing)::Any

Helper function for variant where settings_file has not been parsed yet.

get_setting(args::Dict{String,Any}, path::Tuple{Vararg{String}}, default::Any=missing)::Any

Helper function to get a property in settings at an arbitrary nested path in an args dictionary, returning the default value if path does not exist.

set_setting!(args::Dict{String,<:Any}, path::Tuple{Vararg{String}}, value::Any)

Helper function to set an option at path to value and then regenerate the multinetwork data from args.

set_settings!(args, options::Dict{Tuple{Vararg{String}},<:Any})

Helper function to set multiple options at path to value and then regenerate the multinetwork data from args, where the paths are the keys of the options input dictionary.

set_option!(network::Dict{String,<:Any}, path::Tuple{Vararg{String}}, value::Any)

Helper function to set a property in a network data structure at path to value

set_options!(settings::Dict{String,<:Any}, options::Dict{Tuple{Vararg{String}},<:Any})

Helper function to set multiple properties in an options at path::Tuple{Vararg{String}} to value::Any. This does not rebuild the network data structure.