Public API Reference

Module for constructing self-contained power system objects.

Supertype for all PowerSystems components. All subtypes must include a InfrastructureSystemsInternal member. Subtypes should call InfrastructureSystemsInternal() by default, but also must provide a constructor that allows existing values to be deserialized.

Supertype for "devices" (bus, line, etc.)

get_base_power(c::Component) -> Float64

Default behavior of a component. If there is no base_power field, assume is in the system's base power.

set_dynamic_injector!(static_injector::T<:StaticInjection, dynamic_injector::U<:Union{Nothing, DynamicInjection}) -> Union{Nothing, DynamicInjection}

Any StaticInjection struct that wants to support dynamic injectors must implement this method to set the value.

The method is only for internal uses.

clear_services!(device::Device) -> Any

Remove all services attached to the device.

has_service(device::Device, service::Service) -> Bool

Return true if the service is attached to the device.

has_service(device::Device, _::Type{T<:Service}) -> Bool

Return true if a service with type T is attached to the device.

remove_service!(device::Device, service::Service)

Remove a service from a device.

Throws ArgumentError if the service is not attached to the device.

Supertype for all generation technologies

Supertype for all Hydropower generation technologies

Supertype for all renewable generation technologies Requires the implementation of get_ratingand get_power_factor methods

Supertype for all Thermal generation technologies

get_max_active_power(d::T<:RenewableGen) -> Any

Return the max active power for the Renewable Generation calculated as the rating * power_factor

Return the max reactive power for the Renewable Generation calculated as the rating * power_factor

Represents a geographical region of system components.

All subtypes must implement the method get_aggregation_topology_accessor.

Abstract type to represent the structure and interconnectedness of the system

get_aggregation_topology_accessor(_::Type{T<:AggregationTopology}) -> typeof(get_area)

Return the method to be called on a Bus to get its AggregationTopology value for this type.

Abstract type of Devices that inject current/power

Abstract type for all components used to compose a DynamicInjection device

Abstract type for all dynamic injection types

get_dynamic_components(device::T<:DynamicInjection) -> Base.Generator{_A, _B} where {_A, _B}

Return all the dynamic components of a DynamicInjection device

get_states_types(d::DynamicComponent) -> Vector{StateTypes}

Default implementation of get_state_types for dynamic components. Assumes all states are
Differential

get_breakpoint_upperbounds(vc::VariableCost{Vector{Tuple{Float64, Float64}}}) -> Vector{Float64}

Calculates the upper bounds of a variable cost function represented as a collection of piece-wise linear segments.

get_slopes(vc::VariableCost{Vector{Tuple{Float64, Float64}}}) -> Vector{Float64}

Calculates the slopes for the variable cost represented as a piece wise linear cost function. This function returns n - slopes for n - piecewise linear elements in the function. The first element of the return array corresponds to the average cost at the minimum operating point. If your formulation uses n -1 slopes, you can disregard the first component of the array. If the first point in the variable cost has a quantity of 0.0, the first slope returned will be 0.0, otherwise, the first slope represents the trajectory to get from the origin to the first point in the variable cost.

Abstract type for time series stored in the system. Components store references to these through TimeSeriesMetadata values so that data can reside on storage media instead of memory.

Abstract type for time_series that are stored in a system. Users never create them or get access to them. Stores references to TimeSeriesData.

mutable struct Deterministic <: AbstractDeterministic
    name::String
    data::Union{
        SortedDict{Dates.DateTime, Vector{CONSTANT}},
        SortedDict{Dates.DateTime, Vector{POLYNOMIAL}},
        SortedDict{Dates.DateTime, Vector{PWL}},
    }
    resolution::Dates.Period
    scaling_factor_multiplier::Union{Nothing, Function}
    internal::InfrastructureSystemsInternal
end

A deterministic forecast for a particular data field in a Component.

Arguments

• name::String: user-defined name
• data::Union{SortedDict{Dates.DateTime, Vector{CONSTANT}}, SortedDict{Dates.DateTime, Vector{POLYNOMIAL}}, SortedDict{Dates.DateTime, Vector{PWL}}}: timestamp - scalingfactor
• resolution::Dates.Period: forecast resolution
• scaling_factor_multiplier::Union{Nothing, Function}: Applicable when the time series data are scaling factors. Called on the associated component to convert the values.
• internal::InfrastructureSystemsInternal

Deterministic(name::AbstractString, input_data::AbstractDict{Dates.DateTime, var"#s117"} where var"#s117"<:TimeSeries.TimeArray; normalization_factor, scaling_factor_multiplier) -> Deterministic

Construct Deterministic from a Dict of TimeArrays.

Arguments

• name::AbstractString: user-defined name
• input_data::AbstractDict{Dates.DateTime, TimeSeries.TimeArray}: time series data.
• normalization_factor::NormalizationFactor = 1.0: optional normalization factor to apply to each data entry
• scaling_factor_multiplier::Union{Nothing, Function} = nothing: If the data are scaling factors then this function will be called on the component and applied to the data when get_time_series_array is called.
• timestamp = :timestamp: If the values are DataFrames is passed then this must be the column name that contains timestamps.

Deterministic(name::AbstractString, filename::AbstractString, component::InfrastructureSystems.InfrastructureSystemsComponent, resolution::Dates.Period; normalization_factor, scaling_factor_multiplier) -> Deterministic

Construct Deterministic from a CSV file. The first column must be a timestamp in DateTime format and the columns the values in the forecast window.

Arguments

• name::AbstractString: user-defined name
• filename::AbstractString: name of CSV file containing data
• component::InfrastructureSystemsComponent: component associated with the data
• normalization_factor::NormalizationFactor = 1.0: optional normalization factor to apply to each data entry
• scaling_factor_multiplier::Union{Nothing, Function} = nothing: If the data are scaling factors then this function will be called on the component and applied to the data when get_time_series_array is called.

Deterministic(name::AbstractString, series_data::InfrastructureSystems.RawTimeSeries, resolution::Dates.Period; normalization_factor, scaling_factor_multiplier) -> Deterministic

Construct Deterministic from RawTimeSeries.

Deterministic(forecast::Deterministic, data) -> Deterministic

Construct a new Deterministic from an existing instance and a subset of data.

get_data(value::Deterministic) -> Union{DataStructures.SortedDict{Dates.DateTime, Vector{Vector{Tuple{Float64, Float64}}}, Ord} where Ord<:Base.Order.Ordering, DataStructures.SortedDict{Dates.DateTime, Vector{Float64}, Ord} where Ord<:Base.Order.Ordering, DataStructures.SortedDict{Dates.DateTime, Vector{Tuple{Float64, Float64}}, Ord} where Ord<:Base.Order.Ordering}

Get Deterministic data.

get_name(value::Deterministic) -> String

Get Deterministic name.

get_resolution(value::Deterministic) -> Dates.Period

Get Deterministic resolution.

get_scaling_factor_multiplier(value::Deterministic) -> Union{Nothing, Function}

Get Deterministic scaling_factor_multiplier.

set_data!(value::Deterministic, val) -> Any

Set Deterministic data.

set_name!(value::Deterministic, val) -> Any

Set Deterministic name.

set_resolution!(value::Deterministic, val) -> Any

Set Deterministic resolution.

set_scaling_factor_multiplier!(value::Deterministic, val) -> Any

Set Deterministic scaling_factor_multiplier.

mutable struct Probabilistic <: Forecast
    name::String
    resolution::Dates.Period
    percentiles::Vector{Float64}
    data::Union{
        SortedDict{Dates.DateTime, Matrix{CONSTANT}},
        SortedDict{Dates.DateTime, Matrix{POLYNOMIAL}},
        SortedDict{Dates.DateTime, Matrix{PWL}},
    }
    scaling_factor_multiplier::Union{Nothing, Function}
    internal::InfrastructureSystemsInternal
end

A Probabilistic forecast for a particular data field in a Component.

Arguments

• name::String: user-defined name
• resolution::Dates.Period: forecast resolution
• percentiles::Vector{Float64}: Percentiles for the probabilistic forecast
• data::Union{SortedDict{Dates.DateTime, Matrix{CONSTANT}}, SortedDict{Dates.DateTime, Matrix{POLYNOMIAL}}, SortedDict{Dates.DateTime, Matrix{PWL}}}: timestamp - scalingfactor
• scaling_factor_multiplier::Union{Nothing, Function}: Applicable when the time series data are scaling factors. Called on the associated component to convert the values.
• internal::InfrastructureSystemsInternal

Probabilistic(name::AbstractString, input_data::AbstractDict, percentiles::Vector{T} where T, resolution::Dates.Period; normalization_factor, scaling_factor_multiplier) -> Probabilistic

Construct Probabilistic from a SortedDict of Arrays.

Arguments

• name::AbstractString: user-defined name
• input_data::AbstractDict{Dates.DateTime, Matrix{Float64}}: time series data.
• percentiles: Percentiles represented in the probabilistic forecast
• resolution::Dates.Period: The resolution of the forecast in Dates.Period`
• normalization_factor::NormalizationFactor = 1.0: optional normalization factor to apply to each data entry
• scaling_factor_multiplier::Union{Nothing, Function} = nothing: If the data are scaling factors then this function will be called on the component and applied to the data when get_time_series_array is called.

Probabilistic(name::AbstractString, input_data::AbstractDict{Dates.DateTime, var"#s117"} where var"#s117"<:TimeSeries.TimeArray, percentiles::Vector{Float64}; normalization_factor, scaling_factor_multiplier) -> Probabilistic

Construct Probabilistic from a Dict of TimeArrays.

Arguments

• name::AbstractString: user-defined name
• input_data::AbstractDict{Dates.DateTime, TimeSeries.TimeArray}: time series data.
• percentiles: Percentiles represented in the probabilistic forecast
• normalization_factor::NormalizationFactor = 1.0: optional normalization factor to apply to each data entry
• scaling_factor_multiplier::Union{Nothing, Function} = nothing: If the data are scaling factors then this function will be called on the component and applied to the data when get_time_series_array is called.
• timestamp = :timestamp: If the values are DataFrames is passed then this must be the column name that contains timestamps.

Probabilistic(name::AbstractString, series_data::InfrastructureSystems.RawTimeSeries, percentiles::Vector{T} where T, resolution::Dates.Period; normalization_factor, scaling_factor_multiplier) -> Probabilistic

Construct Deterministic from RawTimeSeries.

get_data(value::Probabilistic) -> Union{DataStructures.SortedDict{Dates.DateTime, Matrix{Vector{Tuple{Float64, Float64}}}, Ord} where Ord<:Base.Order.Ordering, DataStructures.SortedDict{Dates.DateTime, Matrix{Float64}, Ord} where Ord<:Base.Order.Ordering, DataStructures.SortedDict{Dates.DateTime, Matrix{Tuple{Float64, Float64}}, Ord} where Ord<:Base.Order.Ordering}

Get Probabilistic data.

get_name(value::Probabilistic) -> String

Get Probabilistic name.

get_percentiles(value::Probabilistic) -> Vector{Float64}

Get Probabilistic percentiles.

get_resolution(value::Probabilistic) -> Dates.Period

Get Probabilistic resolution.

get_scaling_factor_multiplier(value::Probabilistic) -> Union{Nothing, Function}

Get Probabilistic scaling_factor_multiplier.

set_data!(value::Probabilistic, val) -> Any

Set Probabilistic data.

set_name!(value::Probabilistic, val) -> Any

Set Probabilistic name.

set_percentiles!(value::Probabilistic, val) -> Any

Set Probabilistic percentiles.

set_resolution!(value::Probabilistic, val) -> Any

Set Probabilistic resolution.

set_scaling_factor_multiplier!(value::Probabilistic, val) -> Any

Set Probabilistic scaling_factor_multiplier.

mutable struct Scenarios <: Forecast
    name::String
    resolution::Dates.Period
    scenario_count::Int64
    data::Union{
        SortedDict{Dates.DateTime, Matrix{CONSTANT}},
        SortedDict{Dates.DateTime, Matrix{POLYNOMIAL}},
        SortedDict{Dates.DateTime, Matrix{PWL}},
    }
    scaling_factor_multiplier::Union{Nothing, Function}
    internal::InfrastructureSystemsInternal
end

A Discrete Scenario Based time series for a particular data field in a Component.

Arguments

• name::String: user-defined name
• resolution::Dates.Period: forecast resolution
• scenario_count::Int64: Number of scenarios
• data::Union{SortedDict{Dates.DateTime, Matrix{CONSTANT}}, SortedDict{Dates.DateTime, Matrix{POLYNOMIAL}}, SortedDict{Dates.DateTime, Matrix{PWL}}}: timestamp - scalingfactor
• scaling_factor_multiplier::Union{Nothing, Function}: Applicable when the time series data are scaling factors. Called on the associated component to convert the values.
• internal::InfrastructureSystemsInternal

Scenarios(name::AbstractString, input_data::AbstractDict, resolution::Dates.Period; normalization_factor, scaling_factor_multiplier) -> Scenarios

Construct Scenarios from a SortedDict of Arrays.

Arguments

• name::AbstractString: user-defined name
• input_data::AbstractDict{Dates.DateTime, Matrix{Float64}}: time series data.
• resolution::Dates.Period: The resolution of the forecast in Dates.Period`
• normalization_factor::NormalizationFactor = 1.0: optional normalization factor to apply to each data entry
• scaling_factor_multiplier::Union{Nothing, Function} = nothing: If the data are scaling factors then this function will be called on the component and applied to the data when get_time_series_array is called.

Scenarios(name::AbstractString, input_data::AbstractDict{Dates.DateTime, var"#s117"} where var"#s117"<:TimeSeries.TimeArray; normalization_factor, scaling_factor_multiplier) -> Scenarios

Construct Scenarios from a Dict of TimeArrays.

Arguments

• name::AbstractString: user-defined name
• input_data::AbstractDict{Dates.DateTime, TimeSeries.TimeArray}: time series data.
• normalization_factor::NormalizationFactor = 1.0: optional normalization factor to apply to each data entry
• scaling_factor_multiplier::Union{Nothing, Function} = nothing: If the data are scaling factors then this function will be called on the component and applied to the data when get_time_series_array is called.
• timestamp = :timestamp: If the values are DataFrames is passed then this must be the column name that contains timestamps.

get_data(value::Scenarios) -> Union{DataStructures.SortedDict{Dates.DateTime, Matrix{Vector{Tuple{Float64, Float64}}}, Ord} where Ord<:Base.Order.Ordering, DataStructures.SortedDict{Dates.DateTime, Matrix{Float64}, Ord} where Ord<:Base.Order.Ordering, DataStructures.SortedDict{Dates.DateTime, Matrix{Tuple{Float64, Float64}}, Ord} where Ord<:Base.Order.Ordering}

Get Scenarios data.

get_name(value::Scenarios) -> String

Get Scenarios name.

get_resolution(value::Scenarios) -> Dates.Period

Get Scenarios resolution.

get_scaling_factor_multiplier(value::Scenarios) -> Union{Nothing, Function}

Get Scenarios scaling_factor_multiplier.

get_scenario_count(value::Scenarios) -> Int64

Get Scenarios scenario_count.

set_data!(value::Scenarios, val) -> Any

Set Scenarios data.

set_name!(value::Scenarios, val) -> Any

Set Scenarios name.

set_resolution!(value::Scenarios, val) -> Any

Set Scenarios resolution.

set_scaling_factor_multiplier!(value::Scenarios, val) -> Any

Set Scenarios scaling_factor_multiplier.

set_scenario_count!(value::Scenarios, val) -> Any

Set Scenarios scenario_count.

mutable struct DeterministicSingleTimeSeries <: AbstractDeterministic
    single_time_series::SingleTimeSeries
    initial_timestamp::Dates.DateTime
    interval::Dates.Period
    count::Int
    horizon::Int
end

A deterministic forecast for a particular data field in a Component that wraps a SingleTimeSeries.

Arguments

• single_time_series::SingleTimeSeries: wrapped SingleTimeSeries object
• initial_timestamp::Dates.DateTime: time series availability time
• interval::Dates.Period: time step between forecast windows
• count::Int: number of forecast windows
• horizon::Int: length of this time series

mutable struct SingleTimeSeries <: StaticTimeSeries
    name::String
    data::TimeSeries.TimeArray
    scaling_factor_multiplier::Union{Nothing, Function}
    internal::InfrastructureSystemsInternal
end

A deterministic forecast for a particular data field in a Component.

Arguments

• name::String: user-defined name
• data::TimeSeries.TimeArray: timestamp - scalingfactor
• scaling_factor_multiplier::Union{Nothing, Function}: Applicable when the time series data are scaling factors. Called on the associated component to convert the values.
• internal::InfrastructureSystemsInternal

SingleTimeSeries(name::AbstractString, filename::AbstractString, component::InfrastructureSystems.InfrastructureSystemsComponent, resolution::Dates.Period; normalization_factor, scaling_factor_multiplier) -> SingleTimeSeries

Construct SingleTimeSeries from a CSV file. The file must have a column that is the name of the component.

Arguments

• name::AbstractString: user-defined name
• filename::AbstractString: name of CSV file containing data
• component::InfrastructureSystemsComponent: component associated with the data
• resolution::Dates.Period: resolution of the time series
• normalization_factor::NormalizationFactor = 1.0: optional normalization factor to apply to each data entry
• scaling_factor_multiplier::Union{Nothing, Function} = nothing: If the data are scaling factors then this function will be called on the component and applied to the data when get_time_series_array is called.

SingleTimeSeries(name::AbstractString, data::Union{DataFrames.DataFrame, TimeSeries.TimeArray}; normalization_factor, scaling_factor_multiplier, timestamp) -> SingleTimeSeries

Construct SingleTimeSeries from a TimeArray or DataFrame.

Arguments

• name::AbstractString: user-defined name
• data::Union{TimeSeries.TimeArray, DataFrames.DataFrame}: time series data
• normalization_factor::NormalizationFactor = 1.0: optional normalization factor to apply to each data entry
• scaling_factor_multiplier::Union{Nothing, Function} = nothing: If the data are scaling factors then this function will be called on the component and applied to the data when get_time_series_array is called.
• timestamp = :timestamp: If a DataFrame is passed then this must be the column name that contains timestamps.

SingleTimeSeries(time_series::SingleTimeSeries, data::TimeSeries.TimeArray) -> Any

Creates a new SingleTimeSeries from an existing instance and a subset of data.

SingleTimeSeries(name::String, resolution::Dates.Period, initial_time::Dates.DateTime, time_steps::Int64) -> SingleTimeSeries

Construct SingleTimeSeries after constructing a TimeArray from initial_time and time_steps.

from(time_series::SingleTimeSeries, timestamp) -> SingleTimeSeries

Return a time_series truncated starting with timestamp.

get_count(value::DeterministicSingleTimeSeries) -> Int64

Get DeterministicSingleTimeSeries count.

get_data(value::SingleTimeSeries) -> TimeSeries.TimeArray

Get SingleTimeSeries data.

get_horizon(value::DeterministicSingleTimeSeries) -> Int64

Get DeterministicSingleTimeSeries horizon.

get_initial_timestamp(value::DeterministicSingleTimeSeries) -> Dates.DateTime

Get DeterministicSingleTimeSeries initial_timestamp.

get_interval(value::DeterministicSingleTimeSeries) -> Dates.Period

Get DeterministicSingleTimeSeries interval.

get_name(value::SingleTimeSeries) -> String

Get SingleTimeSeries name.

get_resolution(value::SingleTimeSeries) -> Dates.Period

Get SingleTimeSeries resolution.

get_scaling_factor_multiplier(value::SingleTimeSeries) -> Union{Nothing, Function}

Get SingleTimeSeries scaling_factor_multiplier.

get_single_time_series(value::DeterministicSingleTimeSeries) -> SingleTimeSeries

Get DeterministicSingleTimeSeries single_time_series.

head(time_series::SingleTimeSeries) -> Any

Return a time_series with only the first num values.

set_count!(value::DeterministicSingleTimeSeries, val) -> Any

Set DeterministicSingleTimeSeries count.

set_data!(value::SingleTimeSeries, val) -> Any

Set SingleTimeSeries data.

set_horizon!(value::DeterministicSingleTimeSeries, val) -> Any

Set DeterministicSingleTimeSeries horizon.

set_initial_timestamp!(value::DeterministicSingleTimeSeries, val) -> Any

Set DeterministicSingleTimeSeries initial_timestamp.

set_interval!(value::DeterministicSingleTimeSeries, val) -> Any

Set DeterministicSingleTimeSeries interval.

set_name!(value::SingleTimeSeries, val) -> Any

Set SingleTimeSeries name.

set_scaling_factor_multiplier!(value::SingleTimeSeries, val) -> Any

Set SingleTimeSeries scaling_factor_multiplier.

set_single_time_series!(value::DeterministicSingleTimeSeries, val) -> Any

Set DeterministicSingleTimeSeries single_time_series.

tail(time_series::SingleTimeSeries) -> Any

Return a time_series with only the ending num values.

to(time_series::SingleTimeSeries, timestamp) -> SingleTimeSeries

Return a time_series truncated after timestamp.

when(time_series::SingleTimeSeries, period::Function, t::Integer) -> Any

Refer to TimeSeries.when(). Underlying data is copied.

get_initial_times(f::Forecast) -> DataStructures.SDMKeyIteration

Return the initial times in the forecast.

get_total_period(f::Forecast) -> Any

Return the total period covered by the forecast.

get_window(forecast::Forecast, index::Int64; len) -> Any

Return the forecast window corresponsing to interval index.

index_to_initial_time(forecast::Forecast, index::Int64) -> Any

Return the Dates.DateTime corresponding to an interval index.

make_time_array(forecast::Forecast, start_time::Dates.DateTime; len) -> Any

Return a TimeSeries.TimeArray for one forecast window.

get_next_time(cache::InfrastructureSystems.TimeSeriesCache) -> Any

Return the timestamp for the next read with get_next_time_series_array!.

Return nothing if all data has been read.

get_next_time_series_array!(cache::InfrastructureSystems.TimeSeriesCache) -> Any

Return the next TimeSeries.TimeArray.

Returns nothing when all data has been read. Call reset! to restart. Call get_next_time to check the start time.

Reads from storage if the data is not already in cache.

Arguments

• cache::StaticTimeSeriesCache: cached instance

System

A power system defined by fields for base_power, components, and time series.

System(base_power)
System(base_power, buses, components...)
System(base_power, buses, generators, loads, branches, storage, services; kwargs...)
System(base_power, buses, generators, loads; kwargs...)
System(file; kwargs...)
System(; buses, generators, loads, branches, storage, base_power, services, kwargs...)
System(; kwargs...)

Arguments

• base_power::Float64: the base power value for the system
• buses::Vector{Bus}: an array of buses
• components...: Each element must be an iterable containing subtypes of Component.

Keyword arguments

• ext::Dict: Contains user-defined parameters. Should only contain standard types.
• runchecks::Bool: Run available checks on input fields and when add_component! is called. Throws InvalidRange if an error is found.
• time_series_in_memory::Bool=false: Store time series data in memory instead of HDF5.
• enable_compression::Bool=false: Enable compression of time series data in HDF5.
• compression::CompressionSettings: Allows customization of HDF5 compression settings.
• config_path::String: specify path to validation config file

System(sys_file::AbstractString, dyr_file::AbstractString; kwargs...) -> Any

Parse static and dynamic data directly from PSS/e text files. Automatically generates all the relationships between the available dynamic injection models and the static counterpart

Each dictionary indexed by id contains a vector with 5 of its components:

• Machine
• Shaft
• AVR
• TurbineGov
• PSS

Files must be parsed from a .raw file (PTI data format) and a .dyr file.

Examples:

raw_file = "Example.raw"
dyr_file = "Example.dyr"
sys = System(raw_file, dyr_file)

System(file_path::AbstractString; kwargs...) -> Any

Constructs a System from a file path ending with .m, .RAW, or .json

System(data, base_power; internal, kwargs...) -> Any

Construct a System from InfrastructureSystems.SystemData

System(base_power; kwargs...) -> Any

Construct an empty System. Useful for building a System while parsing raw data.

System(base_power::Float64, buses::Vector{Bus}, components...; kwargs...) -> System

System constructor when components are constructed externally.

System(::Nothing; buses, generators, loads, branches, storage, base_power, services, kwargs...) -> System

Constructs a non-functional System for demo purposes.

System(data::PowerSystemTableData; time_series_resolution, time_series_in_memory, time_series_directory, runchecks, kwargs...) -> System

Construct a System from PowerSystemTableData data.

Arguments

• time_series_resolution::Union{DateTime, Nothing}=nothing: only store time_series that match this resolution.
• time_series_in_memory::Bool=false: Store time series data in memory instead of HDF5 file
• time_series_directory=nothing: Store time series data in directory instead of tmpfs
• runchecks::Bool=true: Validate struct fields.

Throws DataFormatError if time_series with multiple resolutions are detected.

• A time_series has a different resolution than others.
• A time_series has a different horizon than others.

System(pm_data::PowerModelsData; kwargs...) -> Any

Constructs a System from PowerModelsData.

Arguments

• pm_data::Union{PowerModelsData, Union{String, IO}}: PowerModels data object or supported

load flow case (*.m, *.raw)

Keyword arguments

• ext::Dict: Contains user-defined parameters. Should only contain standard types.
• runchecks::Bool: Run available checks on input fields and when add_component! is called. Throws InvalidRange if an error is found.
• time_series_in_memory::Bool=false: Store time series data in memory instead of HDF5.
• config_path::String: specify path to validation config file
• pm_data_corrections::Bool=true : Run the PowerModels data corrections (aka :validate in PowerModels)
• import_all:Bool=false : Import all fields from PTI files

Examples

sys = System(
    pm_data, config_path = "ACTIVSg25k_validation.json",
    bus_name_formatter = x->string(x["name"]*"-"*string(x["index"])),
    load_name_formatter = x->strip(join(x["source_id"], "_"))
)

get_time_series_multiple(sys::System) -> Channel{Any}
get_time_series_multiple(sys::System, filter_func; type, name) -> Channel{Any}

Return an iterator of time series in order of initial time.

Note that passing a filter function can be much slower than the other filtering parameters because it reads time series data from media.

Call collect on the result to get an array.

Arguments

• data::SystemData: system
• filter_func = nothing: Only return time series for which this returns true.
• type = nothing: Only return time series with this type.
• name = nothing: Only return time series matching this value.

Examples

for time_series in get_time_series_multiple(sys)
    @show time_series
end

ts = collect(get_time_series_multiple(sys; type = SingleTimeSeries))

set_name!(sys::System, component::Component, name::AbstractString)

Set the name for a component that is attached to the system.

to_json(sys::System, filename::AbstractString; force, runchecks)

Serializes a system to a JSON string.

Arguments

• sys::System: system
• filename::AbstractString: filename to write

Keyword arguments

• force::Bool = false: whether to overwrite existing files
• check::Bool = false: whether to run system validation checks

Refer to check_component for exceptions thrown if check = true.

add_component!(sys::System, dyn_injector::DynamicInjection, static_injector::StaticInjection; kwargs...)

Add a dynamic injector to the system.

Throws ArgumentError if the name does not match the staticinjector name. Throws ArgumentError if the staticinjector is not attached to the system.

All rules for the generic add_component! method also apply.

add_component!(sys::System, component::T<:Component; skip_validation, kwargs...)

Add a component to the system.

Throws ArgumentError if the component's name is already stored for its concrete type. Throws ArgumentError if any Component-specific rule is violated. Throws InvalidRange if any of the component's field values are outside of defined valid range.

Examples

sys = System(100.0)

# Add a single component.
add_component!(sys, bus)

# Add many at once.
buses = [bus1, bus2, bus3]
generators = [gen1, gen2, gen3]
foreach(x -> add_component!(sys, x), Iterators.flatten((buses, generators)))

add_components!(sys::System, components)

Add many components to the system at once.

Throws ArgumentError if the component's name is already stored for its concrete type. Throws ArgumentError if any Component-specific rule is violated. Throws InvalidRange if any of the component's field values are outside of defined valid range.

Examples

sys = System(100.0)

buses = [bus1, bus2, bus3]
generators = [gen1, gen2, gen3]
foreach(x -> add_component!(sys, x), Iterators.flatten((buses, generators)))

add_service!(device::Device, service::Service, sys::System)

Similar to add_service! but for Service and Device already stored in the system. Performs validation checks on the device and the system

Arguments

• device::Device: Device
• service::Service: Service
• sys::System: system

add_service!(sys::System, service::Service, contributing_devices; kwargs...)

Similar to add_component! but for services.

Arguments

• sys::System: system
• service::Service: service to add
• contributing_devices: Must be an iterable of type Device

add_service!(sys::System, service::Service, contributing_device::Device; kwargs...)

Similar to add_component! but for services.

Arguments

• sys::System: system
• service::Service: service to add
• contributing_device::Device: Valid Device

add_service!(sys::System, service::StaticReserveGroup, contributing_services::Vector{var"#s220"} where var"#s220"<:Service; skip_validation, kwargs...)

Similar to add_component! but for StaticReserveGroup.

Arguments

• sys::System: system
• service::StaticReserveGroup: service to add
• contributing_services: contributing services to the group

add_service!(sys::System, service::StaticReserveGroup; skip_validation, kwargs...)

Similar to add_component! but for StaticReserveGroup.

Arguments

• sys::System: system
• service::StaticReserveGroup: service to add

add_time_series!(sys::System, metadata_file::AbstractString; resolution)

Add time series data from a metadata file or metadata descriptors.

Arguments

• sys::System: system
• metadata_file::AbstractString: metadata file for timeseries that includes an array of IS.TimeSeriesFileMetadata instances or a vector.
• resolution::DateTime.Period=nothing: skip time series that don't match this resolution.

add_time_series!(sys::System, components, time_series::TimeSeriesData)

Add the same time series data to multiple components.

This is significantly more efficent than calling add_time_series! for each component individually with the same data because in this case, only one time series array is stored.

Throws ArgumentError if a component is not stored in the system.

add_time_series!(sys::System, component::Component, time_series::TimeSeriesData)

Add time series data to a component.

Throws ArgumentError if the component is not stored in the system.

add_time_series!(sys::System, file_metadata::Vector{InfrastructureSystems.TimeSeriesFileMetadata}; resolution)

Add time series data from a metadata file or metadata descriptors.

Arguments

• sys::System: system
• timeseries_metadata::Vector{IS.TimeSeriesFileMetadata}: metadata for timeseries
• resolution::DateTime.Period=nothing: skip time series that don't match this resolution.

check(sys::System)

Check system consistency and validity.

check_component(sys::System, component::Component)

Check the values of a component.

Throws InvalidRange if any of the component's field values are outside of defined valid range.

Throws InvalidValue if the custom validate method for the type fails its check.

check_components(sys::System)

Check the values of all components. See check_component for exceptions thrown.

clear_components!(sys::System)

Remove all components from the system.

clear_ext!(sys::System)

Clear any value stored in ext.

clear_time_series!(sys::System)

Remove all time series data from the system.

convert_component!(linetype::Type{Line}, line::MonitoredLine, sys::System; kwargs...)

Converts a MonitoredLine component to a Line component and replaces the original in the system

convert_component!(linetype::Type{MonitoredLine}, line::Line, sys::System; kwargs...)

Converts a Line component to a MonitoredLine component and replaces the original in the system

copy_time_series!(dst::Component, src::Component; name_mapping, scaling_factor_multiplier_mapping)

Efficiently add all time series data in one component to another by copying the underlying references.

Arguments

• dst::Component: Destination component
• src::Component: Source component
• name_mapping::Dict = nothing: Optionally map src names to different dst names. If provided and src has a time series with a name not present in namemapping, that time series will not copied. If namemapping is nothing then all time series will be copied with src's names.
• scaling_factor_multiplier_mapping::Dict = nothing: Optionally map src scalingfactormultipliers to dst scalingfactormultipliers. Same behaviors as name_mapping.

get_aggregation_topology_mapping(_::Type{T<:AggregationTopology}, sys::System) -> Dict{String, Vector{Bus}}

Return a mapping of AggregationTopology name to vector of buses within it.

get_base_power(sys::System) -> Float64

Return the system's base power.

get_bus(sys::System, bus_number::Int64) -> Any

Return bus with bus_number.

get_bus(sys::System, name::String) -> Union{Nothing, Bus}

Return bus with name.

get_bus_numbers(sys::System) -> Vector{Int64}

Return a sorted vector of bus numbers in the system.

get_buses(sys::System, aggregator::AggregationTopology) -> Vector{Bus}

Return a vector of buses contained within the AggregationTopology.

get_buses(sys::System, bus_numbers::Set{Int64}) -> Vector{Bus}

Return all buses values with bus_numbers.

Get the component of type T with name. Returns nothing if no component matches. If T is an abstract type then the names of components across all subtypes of T must be unique.

See get_components_by_name for abstract types with non-unique names across subtypes.

Throws ArgumentError if T is not a concrete type and there is more than one component with requested name

get_components(_::Type{T<:Component}, sys::System) -> InfrastructureSystems.FlattenIteratorWrapper{_A} where _A

Returns an iterator of components. T can be concrete or abstract. Call collect on the result if an array is desired.

Examples

iter = PowerSystems.get_components(ThermalStandard, sys)
iter = PowerSystems.get_components(Generator, sys)
iter = PowerSystems.get_components(Generator, sys, x->(PowerSystems.get_available(x)))
generators = collect(PowerSystems.get_components(Generator, sys))

See also: iterate_components

Get the components of abstract type T with name. Note that PowerSystems enforces unique names on each concrete type but not across concrete types.

See get_component if the concrete type is known.

Throws ArgumentError if T is not an abstract type.

get_components_in_aggregation_topology(_::Type{T<:StaticInjection}, sys::System, aggregator::AggregationTopology) -> Vector{_A} where _A

Return a vector of components with buses in the AggregationTopology.

get_compression_settings(sys::System) -> CompressionSettings

Return the compression settings used for system data such as time series arrays.

get_contributing_device_mapping(sys::System) -> Dict{NamedTuple{(:type, :name), Tuple{DataType, String}}, ServiceContributingDevices}

Return an instance of ServiceContributingDevicesMapping.

Return a vector of devices contributing to the service.

get_ext(sys::System) -> Union{Nothing, Dict{String, Any}}

Return a user-modifiable dictionary to store extra information.

get_forecast_horizon(sys::System) -> Int64

Return the horizon for all forecasts.

get_forecast_initial_times(sys::System) -> Any

Return the initial times for all forecasts.

get_forecast_initial_timestamp(sys::System) -> Dates.DateTime

Return the initial_timestamp for all forecasts.

get_forecast_interval(sys::System) -> Dates.Period

Return the interval for all forecasts.

get_forecast_total_period(sys::System) -> Any

Return the total period covered by all forecasts.

get_forecast_window_count(sys::System) -> Int64

Return the window count for all forecasts.

get_frequency(sys::System) -> Float64

Return the system's frequency.

get_runchecks(sys::System) -> Bool

Return true if checks are enabled on the system.

get_time_series_resolution(sys::System) -> Dates.Period

Return the resolution for all time series.

iterate_components(sys::System) -> Channel{Any}

Iterates over all components.

Examples

for component in iterate_components(sys)
    @show component
end

See also: get_components

Remove a component from the system by its value.

Throws ArgumentError if the component is not stored.

Remove a component from the system by its name.

Throws ArgumentError if the component is not stored.

remove_time_series!(sys::System, _::Type{T<:TimeSeriesData}, component::Component, name::String)

Remove the time series data for a component and time series type.

remove_time_series!(sys::System, _::Type{T<:TimeSeriesData}) -> Union{Nothing, Int64}

Remove all the time series data for a time series type.

sanitize_component!(component::Component, sys::System) -> Union{Nothing, NamedTuple{(:min, :max), Tuple{Float64, Float64}}}

Sanitize component values.

set_contributing_services!(sys::System, service::StaticReserveGroup, val::Vector{var"#s222"} where var"#s222"<:Service) -> Vector{var"#s222"} where var"#s222"<:Service

Set StaticReserveGroup contributing_services with check

set_runchecks!(sys::System, value::Bool)

Enable or disable system checks. Applies to component addition as well as overall system consistency.

set_units_base_system!(system::System, settings::String)

Sets the units base for the getter functions on the devices. It modifies the behavior of all getter functions

transform_single_time_series!(sys::System, horizon::Int64, interval::Dates.Period)

Transform all instances of SingleTimeSeries to DeterministicSingleTimeSeries.

validate_component(component::Component) -> Bool

Validate the component fields using only those fields. Refer to validate_component_with_system to use other System data for the validation.

Return true if the instance is valid.

validate_component_with_system(component::Component, sys::System) -> Bool

Validate a component against System data. Return true if the instance is valid.

Refer to validate_component if the validation logic only requires data contained within the instance.

get_max_active_power(d::T<:Device) -> Any

Return the max active power for a device from getactivepower_limits.max

get_max_reactive_power(d::RenewableDispatch) -> Any

Return the max reactive power for the Renewable Generation calculated as the rating * powerfactor if reactivepower_limits is nothing

Return the max reactive power for a device from getreactivepower_limits.max

Return a time series corresponding to the given parameters.

Arguments

• ::Type{T}: Concrete subtype of TimeSeriesData to return
• component::InfrastructureSystemsComponent: Component containing the time series
• name::AbstractString: name of time series
• start_time::Union{Nothing, Dates.DateTime} = nothing: If nothing, use the initial_timestamp of the time series. If T is a subtype of Forecast then start_time must be the first timstamp of a window.
• len::Union{Nothing, Int} = nothing: Length in the time dimension. If nothing, use the entire length.
• count::Union{Nothing, Int} = nothing: Only applicable to subtypes of Forecast. Number of forecast windows starting at start_time to return. Defaults to all available.

get_time_series_array(component::InfrastructureSystems.InfrastructureSystemsComponent, time_series::StaticTimeSeries) -> Any
get_time_series_array(component::InfrastructureSystems.InfrastructureSystemsComponent, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime}; len, ignore_scaling_factors) -> Any

Return a TimeSeries.TimeArray from a cached StaticTimeSeries instance.

If the data are scaling factors then the stored scalingfactormultiplier will be called on the component and applied to the data unless ignorescalingfactors is true.

See also StaticTimeSeriesCache.

get_time_series_array(component::InfrastructureSystems.InfrastructureSystemsComponent, forecast::Forecast, start_time::Dates.DateTime; len, ignore_scaling_factors) -> Any

Return a TimeSeries.TimeArray for one forecast window from a cached Forecast instance.

If the data are scaling factors then the stored scalingfactormultiplier will be called on the component and applied to the data unless ignorescalingfactors is true.

See also ForecastCache.

Return a TimeSeries.TimeArray from storage for the given time series parameters.

If the data are scaling factors then the stored scalingfactormultiplier will be called on the component and applied to the data unless ignorescalingfactors is true.

get_time_series_timestamps(component::InfrastructureSystems.InfrastructureSystemsComponent, forecast::Forecast)
get_time_series_timestamps(component::InfrastructureSystems.InfrastructureSystemsComponent, forecast::Forecast, start_time::Union{Nothing, Dates.DateTime}; len) -> Vector{D} where D<:Dates.TimeType

Return a vector of timestamps from a cached Forecast instance.

get_time_series_timestamps(component::InfrastructureSystems.InfrastructureSystemsComponent, time_series::StaticTimeSeries) -> Vector{D} where D<:Dates.TimeType
get_time_series_timestamps(component::InfrastructureSystems.InfrastructureSystemsComponent, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime}; len) -> Vector{D} where D<:Dates.TimeType

Return a vector of timestamps from a cached StaticTimeSeries instance.

get_time_series_timestamps(::Type{T<:TimeSeriesData}, component::InfrastructureSystems.InfrastructureSystemsComponent, name::AbstractString; start_time, len) -> Vector{D} where D<:Dates.TimeType

Return a vector of timestamps from storage for the given time series parameters.

get_time_series_values(component::InfrastructureSystems.InfrastructureSystemsComponent, time_series::StaticTimeSeries) -> Any
get_time_series_values(component::InfrastructureSystems.InfrastructureSystemsComponent, time_series::StaticTimeSeries, start_time::Union{Nothing, Dates.DateTime}; len, ignore_scaling_factors) -> Any

Return an Array of values from a cached StaticTimeSeries instance for the requested time series parameters.

get_time_series_values(component::InfrastructureSystems.InfrastructureSystemsComponent, forecast::Forecast, start_time::Dates.DateTime; len, ignore_scaling_factors) -> Any

Return an Array of values for one forecast window from a cached Forecast instance.

Return an Array of values from storage for the requested time series parameters.

If the data size is small and this will be called many times, consider using the version that accepts a cached TimeSeriesData instance.

Nodal incidence matrix (Adjacency) is an N x N matrix describing a power system with N buses. It represents the directed connectivity of the buses in a power system.

The Adjacency Struct is indexed using the Bus Numbers, no need for them to be sequential

Builds a Adjacency from a collection of buses and branches. The return is an N x N Adjacency Array indexed with the bus numbers.

Keyword arguments

• check_connectivity::Bool: Checks connectivity of the network using Goderya's algorithm

Builds a Adjacency from the system. The return is an N x N Adjacency Array indexed with the bus numbers.

Keyword arguments

• check_connectivity::Bool: Checks connectivity of the network using Goderya's algorithm
• connectivity_method::Function = goderya_connectivity: method (goderya_connectivity or dfs_connectivity) for connectivity validation

Nodal admittance matrix (Ybus) is an N x N matrix describing a power system with N buses. It represents the nodal admittance of the buses in a power system.

The Ybus Struct is indexed using the Bus Numbers, no need for them to be sequential

Builds a Ybus from a collection of buses and branches. The return is a Ybus Array indexed with the bus numbers and the branch names.

Keyword arguments

• check_connectivity::Bool: Checks connectivity of the network using Goderya's algorithm
• connectivity_method::Function = goderya_connectivity: method (goderya_connectivity or dfs_connectivity) for connectivity validation

Builds a Ybus from the system. The return is a Ybus Array indexed with the bus numbers and the branch names.

Keyword arguments

• check_connectivity::Bool: Checks connectivity of the network using Goderya's algorithm
• connectivity_method::Function = goderya_connectivity: method (goderya_connectivity or dfs_connectivity) for connectivity validation

validate_connectivity(sys::System; connectivity_method) -> Bool

Checks the network connectivity of the system.

Keyword arguments

• connectivity_method::Function = goderya_connectivity: Specifies the method used as Goderya's algorithm (goderya_connectivity) or depth first search/network traversal (dfs_connectivity)
• Note that the default Goderya method is more efficient, but is resource intensive and may not scale well on large networks.

Power Transfer Distribution Factors (PTDF) indicate the incremental change in real power that occurs on transmission lines due to real power injections changes at the buses.

The PTDF struct is indexed using the Bus numbers and branch names

Builds the PTDF matrix from a group of branches and nodes. The return is a PTDF array indexed with the bus numbers.

Keyword arguments

• dist_slack::Vector{Float64}: Vector of weights to be used as distributed slack bus. The distributed slack vector has to be the same length as the number of buses

Builds the PTDF matrix from a system. The return is a PTDF array indexed with the bus numbers.

Keyword arguments

• dist_slack::Vector{Float64}: Vector of weights to be used as distributed slack bus. The distributed slack vector has to be the same length as the number of buses

Line Outage Distribution Factors (LODFs) are a sensitivity measure of how a change in a line’s flow affects the flows on other lines in the system.

Builds the LODF matrix from a group of branches and nodes. The return is a LOLDF array indexed with the branch name.

Keyword arguments

• dist_slack::Vector{Float64}: Vector of weights to be used as distributed slack bus. The distributed slack vector has to be the same length as the number of buses

Builds the LODF matrix from a system. The return is a LOLDF array indexed with the branch name.

Keyword arguments

• dist_slack::Vector{Float64}: Vector of weights to be used as distributed slack bus. The distributed slack vector has to be the same length as the number of buses

get_data(mat::PowerSystems.PowerNetworkMatrix) -> Any

returns the raw array data of the PowerNetworkMatrix

get_lookup(mat::PowerSystems.PowerNetworkMatrix) -> Any

returns the lookup tuple of the `PowerNetworkMatrix`. The first entry corresponds
to the first dimension and the second entry corresponds to the second dimension. For
instance in Ybus the first dimension is buses and second dimension is buses too, and in
PTDF the first dimension is branches and the second dimension is buses

solve_powerflow!(system::System; finite_diff, kwargs...) -> Bool

Solves a the power flow into the system and writes the solution into the relevant structs. Updates generators active and reactive power setpoints and branches active and reactive power flows (calculated in the From - To direction) (see flow_val)

Supports solving using Finite Differences Method (instead of using analytic Jacobian) by setting finite_diff = true. Supports passing NLsolve kwargs in the args. By default shows the solver trace.

Arguments available for nlsolve:

• method : See NLSolve.jl documentation for available solvers
• xtol: norm difference in x between two successive iterates under which convergence is declared. Default: 0.0.
• ftol: infinite norm of residuals under which convergence is declared. Default: 1e-8.
• iterations: maximum number of iterations. Default: 1_000.
• store_trace: should a trace of the optimization algorithm's state be stored? Default: false.
• show_trace: should a trace of the optimization algorithm's state be shown on STDOUT? Default: false.
• extended_trace: should additifonal algorithm internals be added to the state trace? Default: false.

Examples

solve_powerflow!(sys)
# Passing NLsolve arguments
solve_powerflow!(sys, method = :newton)
# Using Finite Differences
solve_powerflow!(sys, finite_diff = true)

solve_powerflow(system::System; finite_diff, kwargs...) -> Union{Bool, Dict{String, DataFrames.DataFrame}}

Similar to solve_powerflow!(sys) but does not update the system struct with results. Returns the results in a dictionary of dataframes.

Examples

res = solve_powerflow(sys)
# Passing NLsolve arguments
res = solve_powerflow(sys, method = :newton)
# Using Finite Differences
res = solve_powerflow(sys, finite_diff = true)

PowerSystemTableData(directory::AbstractString, base_power::Float64, user_descriptor_file::AbstractString; descriptor_file, generator_mapping_file, timeseries_metadata_file) -> PowerSystemTableData

Reads in all the data stored in csv files The general format for data is folder: gen.csv branch.csv bus.csv .. load.csv

Arguments

• directory::AbstractString: directory containing CSV files
• base_power::Float64: base power for System
• user_descriptor_file::AbstractString: customized input descriptor file
• descriptor_file=POWER_SYSTEM_DESCRIPTOR_FILE: PowerSystems descriptor file
• generator_mapping_file=GENERATOR_MAPPING_FILE: generator mapping configuration file

Container for data parsed by PowerModels

PowerModelsData(file::Union{IO, String}; kwargs...) -> PowerModelsData

Constructs PowerModelsData from a raw file. Currently Supports MATPOWER and PSSE data files parsed by PowerModels.

TamuSystem(tamu_folder::AbstractString; kwargs...) -> Any

Creates a system from a PSS/e .RAW (v33) load flow case, and an associated .csv with MW load time series data. The format is established by the Texas A&M University Test Case Archive

The general format for data is folder: [casename].raw [casename]loadtimeseriesMW.csv

Arguments

• directory::AbstractString: directory containing RAW and CSV files

Examples

sys = TamuSystem(
    "./ACTIVSg25k",
    config_path = "ACTIVSg25k_validation.json",
    bus_name_formatter = x->string(x["name"]*"-"*string(x["index"])),
    load_name_formatter = x->strip(join(x["source_id"], "_"))
)

add_dyn_injectors!(sys::System, dyr_file::AbstractString)

Add to a system already created the dynamic components. The system should already be parsed from a .raw file.

Examples:

dyr_file = "Example.dyr"
add_dyn_injectors!(sys, dyr_file)

configure_logging(; console_level, file_level, filename) -> MultiLogger

Creates console and file loggers.

Note: Log messages may not be written to the file until flush() or close() is called on the returned logger.

Arguments

• console_level = Logging.Error: level for console messages
• file_level = Logging.Info: level for file messages
• filename::Union{Nothing, AbstractString} = "power-systems.log": log file; pass nothing to disable file logging

Example

logger = configure_logging(console_level = Logging.Info)
@info "log message"
close(logger)