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.)

Supertype for all AC branches (branches connecting at least one AC node)

Supertype for all branches

Supertype for all DC branches (branches that connect only DC nodes)

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::StaticInjection,
    dynamic_injector::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)

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 controllable loads

Supertype for all electric loads

Supertype for all static electric loads

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::RenewableGen) -> Any

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

get_max_reactive_power(d::RenewableGen) -> Any

Return the max reactive power for the Renewable Generation calculated as the rating * sin(acos(power_factor))

A reserve product to be able to respond to unexpected disturbances, such as the sudden loss of a transmission line or generator.

Used to specify if a Reserve is upwards, downwards, or symmetric

A downwards reserve to decrease generation or increase load

Downwards reserves are used when total load falls below its expected level, typically due to forecast errors or contingencies. Not work

A Reserve can be specified as a ReserveDown when it is defined.

A symmetric reserve, procuring the same quantity (MW) of both upwards and downwards reserves

A symmetric reserve is a special case. ReserveUp and ReserveDown can be used individually to specify different quantities of upwards and downwards reserves, respectively.

A Reserve can be specified as a ReserveSymmetric when it is defined.

An upwards reserve to increase generation or reduce load

Upwards reserves are used when total load exceeds its expected level, typically due to forecast errors or contingencies.

A Reserve can be specified as a ReserveUp when it is defined.

Supertype for energy storage technologies

Supertype for all system services

Services (or ancillary services) include additional requirements and support to ensure reliable electricity service to customers. Common services are reserve products to be able to respond quickly to unexpected disturbances, such as the sudden loss of a transmission line or generator.

Attribute that contains information regarding forced outages where the transition probabilities are modeled with geometric distributions. The outage probabilities and recovery probabilities can be modeled as time series.

Arguments

• time_to_recovery::Int: Time elapsed to recovery after a failure in Milliseconds.
• outage_transition_probability::Float64: Characterizes the probability of failure (1 - p) in the geometric distribution.
• internal::InfrastructureSystemsInternal: power system internal reference, do not modify

Attribute that contains information regarding planned outages.

Arguments

• outage_schedule::String: String name of the time series used for the scheduled outages
• internal::InfrastructureSystemsInternal: power system internal reference, do not modify

Attribute that contains the representation of the status of the component forced outage. The data can be obtained from the simulation of an stochastic process or historical information.

Arguments

• outage_status_scenario::String: String name of the time series used for the forced outage status in the model. 1 is used represent outaged and 0 for available.
• internal::InfrastructureSystemsInternal: power system internal reference, do not modify

get_mean_time_to_recovery(
    value::GeometricDistributionForcedOutage
) -> Float64

Get GeometricDistributionForcedOutage time_to_recovery.

get_outage_schedule(value::PlannedOutage) -> String

Get PlannedOutage outage_schedule.

get_outage_transition_probability(
    value::GeometricDistributionForcedOutage
) -> Float64

Get GeometricDistributionForcedOutage outage_transition_probability.

Represents a geographical region of system components.

All subtypes must implement the method get_aggregation_topology_accessor.

Abstract type to represent any type of Bus, AC or DC.

Abstract type to represent the structure and interconnectedness of the system

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

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

Abstract type for devices that inject power or current

A static injection is a steady state injection, such as modeling the output power of a generator held constant over a five-minute period.

Many StaticInjection models can accept a DynamicInjection model as an optional add-on for conducting dynamic simulations.

add_component_to_subsystem!(
    sys::System,
    subsystem_name::AbstractString,
    component::Component
)

Add a component to a subsystem.

add_subsystem!(sys::System, subsystem_name::AbstractString)

Add a new subsystem to the system.

get_assigned_subsystems(
    sys::System,
    component::Component
) -> Vector

Return a Vector of subsystem names that contain the component.

get_num_subsystems(sys::System) -> Int64

Return the number of subsystems stored in the system.

get_subsystem_components(
    sys::System,
    subsystem_name::AbstractString
) -> Base.Generator{Set{Base.UUID}, InfrastructureSystems.var"#419#420"{InfrastructureSystems.SystemData}}

Return a Generator of all components in the subsystem.

Throws ArgumentError if the subsystem name is not stored.

get_subsystems(
    sys::System
) -> Base.KeySet{String, Dict{String, Set{Base.UUID}}}

Return an iterator of all subsystem names in the system.

has_component(
    sys::System,
    subsystem_name::AbstractString,
    component::Component
) -> Bool

Return true if the component is in the subsystem.

has_subsystems(sys::System) -> Bool

Return true if the system has one or more subsystems.

is_assigned_to_subsystem(
    sys::System,
    component::Component,
    subsystem_name::AbstractString
) -> Bool

Return true if the component is assigned to the subsystem.

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

Return true if the component is assigned to any subsystems.

remove_component_from_subsystem!(
    sys::System,
    subsystem_name::AbstractString,
    component::Component
)

Remove a component from a subsystem.

Throws ArgumentError if the subsystem name or component is not stored.

remove_subsystem!(
    sys::System,
    subsystem_name::AbstractString
)

Remove a subsystem from the system.

Throws ArgumentError if the subsystem name is not stored.

Abstract type for a subsystem that contains multiple instances of StaticInjection

Subtypes must implement:

• get_subcomponents(subsystem::StaticInjectionSubsystem)

The subcomponents in subtypes must be attached to the System as masked components.

copy_subcomponent_time_series!(
    subsystem::StaticInjectionSubsystem,
    subcomponent::Component
)

Efficiently add all time series data in the subcomponent to the subsystem by copying the underlying references.

Abstract type for all components used to compose a DynamicInjection device

Abstract type for all Dynamic Devices

A dynamic injection is the continuous time response of a generator, typically modeled with differential equations.

DynamicInjection components can added on to StaticInjection components, which together define all the information needed to model the device in a dynamic simulation.

get_dynamic_components(
    device::DynamicInjection
) -> Base.Generator{I, F} where {I<:(Base.Iterators.Filter{PowerSystems.var"#6#8", I} where I<:(Base.Iterators.Zip{Is} where Is<:Tuple{Any, Tuple})), F<:(PowerSystems.var"#5#7"{<:DynamicInjection})}

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

Supertype for operational cost representations

Current concrete types include:

• ThermalGenerationCost
• HydroGenerationCost
• RenewableGenerationCost
• StorageCost
• LoadCost
• MarketBidCost

get_fuel_cost(
    component::StaticInjection;
    start_time,
    len
) -> Union{Float64, TimeSeries.TimeArray}

Get the fuel cost of the component's variable cost, which must be a FuelCurve.

get_decremental_initial_input(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{Nothing, TimeSeries.TimeArray}

Retrieve the decremental_initial_input for a StaticInjection device with a MarketBidCost.

get_decremental_offer_curves(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{CostCurve{PiecewiseIncrementalCurve}, TimeSeries.TimeArray}

Retrieve the decremental_offer_curves for a StaticInjection device with a MarketBidCost. If this field is a time series, the user may specify start_time and len and the function returns a TimeArray of Float64s; if the field is not a time series, the function returns a single Float64 or Nothing.

get_decremental_variable_cost(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{Nothing, CostCurve{PiecewiseIncrementalCurve}, TimeSeriesKey, TimeSeries.TimeArray}

Retrieve the variable cost bid for a StaticInjection device with a MarketBidCost. If any of the relevant fields (decremental_offer_curves, initial_input, no_load_cost) are time series, the user may specify start_time and len and the function returns a TimeArray of CostCurves; if the field is not a time series, the function returns a single CostCurve.

get_incremental_initial_input(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{Nothing, TimeSeries.TimeArray}

Retrieve the incremental_initial_input for a StaticInjection device with a MarketBidCost.

get_incremental_offer_curves(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{CostCurve{PiecewiseIncrementalCurve}, TimeSeries.TimeArray}

Retrieve the incremental_offer_curves for a StaticInjection device with a MarketBidCost. If this field is a time series, the user may specify start_time and len and the function returns a TimeArray of Float64s; if the field is not a time series, the function returns a single Float64 or Nothing.

get_incremental_variable_cost(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{Nothing, CostCurve{PiecewiseIncrementalCurve}, TimeSeriesKey, TimeSeries.TimeArray}

Retrieve the variable cost bid for a StaticInjection device with a MarketBidCost. If any of the relevant fields (incremental_offer_curves, initial_input, no_load_cost) are time series, the user may specify start_time and len and the function returns a TimeArray of CostCurves; if the field is not a time series, the function returns a single CostCurve.

get_no_load_cost(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{Nothing, Float64, TimeSeries.TimeArray}

Retrieve the no-load cost data for a StaticInjection device with a MarketBidCost. If this field is a time series, the user may specify start_time and len and the function returns a TimeArray of Float64s; if the field is not a time series, the function returns a single Float64 or Nothing.

get_services_bid(
    device::StaticInjection,
    cost::MarketBidCost,
    service::Service;
    start_time,
    len
) -> TimeSeries.TimeArray

Return service bid time series data for a StaticInjection device with a MarketBidCost. The user may specify start_time and len and the function returns a TimeArray of CostCurves.

get_start_up(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{@NamedTuple{hot::Float64, warm::Float64, cold::Float64}, TimeSeries.TimeArray}

Retrieve the startup cost data for a StaticInjection device with a MarketBidCost. If this field is a time series, the user may specify start_time and len and the function returns a TimeArray of Float64s; if the field is not a time series, the function returns a single Float64.

get_variable_cost(
    service::ReserveDemandCurve;
    start_time,
    len
) -> Union{CostCurve{PiecewiseIncrementalCurve}, TimeSeries.TimeArray}

Retrieve the variable cost data for a ReserveDemandCurve. The user may specify start_time and len and the function returns a TimeArray of CostCurves.

get_variable_cost(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{Nothing, CostCurve{PiecewiseIncrementalCurve}, TimeSeriesKey, TimeSeries.TimeArray}

Retrieve the variable cost bid for a StaticInjection device with a MarketBidCost. If any of the relevant fields (incremental_offer_curves, initial_input, no_load_cost) are time series, the user may specify start_time and len and the function returns a TimeArray of CostCurves; if the field is not a time series, the function returns a single CostCurve.

set_decremental_initial_input!(
    sys::System,
    component::StaticInjection,
    data::Union{Float64, TimeSeriesData}
) -> TimeSeriesKey

Set the decremental_initial_input for a StaticInjection device with a MarketBidCost to either a scalar or a time series.

Arguments

• sys::System: PowerSystem System
• component::StaticInjection: Static injection device
• time_series_data::Union{Float64, IS.TimeSeriesData},: the data. If a time series, must be of eltype Float64.

set_decremental_variable_cost!(
    sys::System,
    component::StaticInjection,
    data::Union{Nothing, CostCurve{PiecewiseIncrementalCurve}, TimeSeriesData},
    power_units::UnitSystem
)

Set the decremental variable cost bid for a StaticInjection device with a MarketBidCost.

Arguments

• sys::System: PowerSystem System
• component::StaticInjection: Static injection device
• time_series_data::Union{Nothing, IS.TimeSeriesData, CostCurve{PiecewiseIncrementalCurve}},: the data. If using a time series, must be of eltype PiecewiseStepData. PiecewiseIncrementalCurve is only accepted for single CostCurve and not accepted for time series data.
• power_units::UnitSystem: Units to be used for data.

set_fuel_cost!(
    sys::System,
    component::StaticInjection,
    data::Union{Float64, TimeSeriesData}
) -> Any

Set the fuel cost of the component's variable cost, which must be a FuelCurve.

set_incremental_initial_input!(
    sys::System,
    component::StaticInjection,
    data::Union{Float64, TimeSeriesData}
) -> TimeSeriesKey

Set the incremental_initial_input for a StaticInjection device with a MarketBidCost to either a scalar or a time series.

Arguments

• sys::System: PowerSystem System
• component::StaticInjection: Static injection device
• time_series_data::Union{Float64, IS.TimeSeriesData},: the data. If a time series, must be of eltype Float64.

set_incremental_variable_cost!(
    sys::System,
    component::StaticInjection,
    data::Union{Nothing, CostCurve{PiecewiseIncrementalCurve}, TimeSeriesData},
    power_units::UnitSystem
)

Set the incremental variable cost bid for a StaticInjection device with a MarketBidCost.

Arguments

• sys::System: PowerSystem System
• component::StaticInjection: Static injection device
• time_series_data::Union{Nothing, IS.TimeSeriesData, CostCurve{PiecewiseIncrementalCurve}},: the data. If using a time series, must be of eltype PiecewiseStepData. PiecewiseIncrementalCurve is only accepted for single CostCurve and not accepted for time series data.
• power_units::UnitSystem: Units to be used for data.

set_no_load_cost!(
    sys::System,
    component::StaticInjection,
    data::Union{Float64, TimeSeriesData}
) -> Union{Float64, TimeSeriesKey}

Set the no-load cost for a StaticInjection device with a MarketBidCost to either a scalar or a time series.

Arguments

• sys::System: PowerSystem System
• component::StaticInjection: Static injection device
• time_series_data::Union{Float64, IS.TimeSeriesData},: the data. If a time series, must be of eltype Float64.

set_service_bid!(
    sys::System,
    component::StaticInjection,
    service::Service,
    time_series_data::TimeSeriesData,
    power_units::UnitSystem
)

Adds service bids time-series data to the MarketBidCost.

Arguments

• sys::System: PowerSystem System
• component::StaticInjection: Static injection device
• service::Service,: Service for which the device is eligible to contribute
• time_series_data::IS.TimeSeriesData: TimeSeriesData

set_start_up!(
    sys::System,
    component::StaticInjection,
    data::Union{@NamedTuple{hot::Float64, warm::Float64, cold::Float64}, TimeSeriesData}
) -> Union{@NamedTuple{hot::Float64, warm::Float64, cold::Float64}, TimeSeriesKey}

Set the startup cost for a StaticInjection device with a MarketBidCost to either a single StartUpStages or a time series.

Arguments

• sys::System: PowerSystem System
• component::StaticInjection: Static injection device
• time_series_data::Union{StartUpStages, IS.TimeSeriesData},: the data. If a time series, must be of eltype NTuple{3, Float64}.

set_variable_cost!(
    _::System,
    component::ReserveDemandCurve,
    data::CostCurve{PiecewiseIncrementalCurve}
) -> CostCurve{PiecewiseIncrementalCurve}

Adds fixed energy market bids to the ReserveDemandCurve.

Arguments

• sys::System: PowerSystem System
• component::ReserveDemandCurve: the curve
• `timeseriesdata::CostCurve{PiecewiseIncrementalCurve}

set_variable_cost!(
    sys::System,
    component::ReserveDemandCurve,
    data::Union{Nothing, TimeSeriesData}
) -> TimeSeriesKey

Adds energy market bids time-series to the ReserveDemandCurve.

Arguments

• sys::System: PowerSystem System
• component::ReserveDemandCurve: the curve
• time_series_data::IS.TimeSeriesData: TimeSeriesData

set_variable_cost!(
    sys::System,
    component::StaticInjection,
    data::Union{Nothing, CostCurve{PiecewiseIncrementalCurve}, TimeSeriesData},
    power_units::UnitSystem
)

Set the incremental variable cost bid for a StaticInjection device with a MarketBidCost.

Arguments

• sys::System: PowerSystem System
• component::StaticInjection: Static injection device
• time_series_data::Union{Nothing, IS.TimeSeriesData, CostCurve{PiecewiseIncrementalCurve}},: the data. If using a time series, must be of eltype PiecewiseStepData. PiecewiseIncrementalCurve is only accepted for single CostCurve and not accepted for time series data.
• power_units::UnitSystem: Units to be used for data. Must be NATURAL_UNITS.

struct CostCurve{T<:ValueCurve} <: ProductionVariableCostCurve{T<:ValueCurve}

• value_curve::ValueCurve: The underlying ValueCurve representation of this ProductionVariableCostCurve

• power_units::UnitSystem: (default: natural units (MW)) The units for the x-axis of the curve

• vom_cost::LinearCurve: (default of 0) Additional proportional Variable Operation and Maintenance Cost in /(power_unit h), represented as a LinearCurve

CostCurve(value_curve, power_units, vom_cost)
CostCurve(; value_curve, power_units, vom_cost)

Direct representation of the variable operation cost of a power plant in currency. Composed of a ValueCurve that may represent input-output, incremental, or average rate data. The default units for the x-axis are MW and can be specified with power_units.

struct FuelCurve{T<:ValueCurve} <: ProductionVariableCostCurve{T<:ValueCurve}

• value_curve::ValueCurve: The underlying ValueCurve representation of this ProductionVariableCostCurve

• power_units::UnitSystem: (default: natural units (MW)) The units for the x-axis of the curve

• fuel_cost::Union{Float64, TimeSeriesKey}: Either a fixed value for fuel cost or the TimeSeriesKey to a fuel cost time series

• vom_cost::LinearCurve: (default of 0) Additional proportional Variable Operation and Maintenance Cost in /(power_unit h) represented as a LinearCurve

FuelCurve(value_curve, power_units, fuel_cost, vom_cost)
FuelCurve(value_curve, fuel_cost)
FuelCurve(value_curve, fuel_cost, vom_cost)
FuelCurve(value_curve, power_units, fuel_cost)
FuelCurve(; value_curve, power_units, fuel_cost, vom_cost)

Representation of the variable operation cost of a power plant in terms of fuel (MBTU, liters, m^3, etc.), coupled with a conversion factor between fuel and currency. Composed of a ValueCurve that may represent input-output, incremental, or average rate data. The default units for the x-axis are MW and can be specified with power_units.

get_fuel_cost(
    cost::FuelCurve
) -> Union{Float64, TimeSeriesKey}

Get the fuel cost or the name of the fuel cost time series

get_function_data(cost::ProductionVariableCostCurve) -> Any

Get the FunctionData representation of this ProductionVariableCostCurve's ValueCurve

get_initial_input(
    cost::ProductionVariableCostCurve
) -> Union{Nothing, Float64}

Get the initial_input field of this ProductionVariableCostCurve's ValueCurve (not defined for input-output data)

get_power_units(cost::ProductionVariableCostCurve) -> Any

Get the units for the x-axis of the curve

get_value_curve(cost::ProductionVariableCostCurve) -> Any

Get the underlying ValueCurve representation of this ProductionVariableCostCurve

get_vom_cost(cost::ProductionVariableCostCurve) -> Any

Get the variable operation and maintenance cost in currency/(power_units h)

is_convex(cost::ProductionVariableCostCurve) -> Any

Calculate the convexity of the underlying data

LinearCurve(proportional_term::Float64)
LinearCurve(proportional_term::Float64, constant_term::Float64)

A linear input-output curve, representing a constant marginal rate. May have zero no-load cost (i.e., constant average rate) or not.

Arguments

• proportional_term::Float64: marginal rate
• constant_term::Float64: optional, cost at zero production, defaults to 0.0

PiecewiseAverageCurve(initial_input::Union{Float64, Nothing}, x_coords::Vector{Float64}, slopes::Vector{Float64})

A piecewise linear curve specified by average rates between production points. May have nonzero initial value.

Arguments

• initial_input::Union{Float64, Nothing}: cost at minimum production point first(x_coords) (NOT at zero production), defines the start of the curve
• x_coords::Vector{Float64}: vector of n production points
• slopes::Vector{Float64}: vector of n-1 average rates/slopes of the curve segments between the points

PiecewiseIncrementalCurve(initial_input::Union{Float64, Nothing}, x_coords::Vector{Float64}, slopes::Vector{Float64})
PiecewiseIncrementalCurve(input_at_zero::Union{Nothing, Float64}, initial_input::Union{Float64, Nothing}, x_coords::Vector{Float64}, slopes::Vector{Float64})

A piecewise linear curve specified by marginal rates (slopes) between production points. May have nonzero initial value.

Arguments

• input_at_zero::Union{Nothing, Float64}: (optional, defaults to nothing) cost at zero production, does NOT represent a part of the curve
• initial_input::Union{Float64, Nothing}: cost at minimum production point first(x_coords) (NOT at zero production), defines the start of the curve
• x_coords::Vector{Float64}: vector of n production points
• slopes::Vector{Float64}: vector of n-1 marginal rates/slopes of the curve segments between the points

PiecewisePointCurve(points::Vector{Tuple{Float64, Float64}})

A piecewise linear curve specified by cost values at production points.

Arguments

• points::Vector{Tuple{Float64, Float64}} or similar: vector of (production, cost) pairs

QuadraticCurve(quadratic_term::Float64, proportional_term::Float64, constant_term::Float64)

A quadratic input-output curve, may have nonzero no-load cost.

Arguments

• quadratic_term::Float64: quadratic term of the curve
• proportional_term::Float64: proportional term of the curve
• constant_term::Float64: constant term of the curve

get_average_rates(
    vc::PiecewiseAverageCurve
) -> Vector{Float64}

Get the average rates that define the PiecewiseAverageCurve

get_constant_term(vc::LinearCurve) -> Float64

Get the constant term (i.e., intercept) of the LinearCurve

get_constant_term(vc::QuadraticCurve) -> Float64

Get the constant term of the QuadraticCurve

get_points(
    vc::PiecewisePointCurve
) -> Vector{@NamedTuple{x::Float64, y::Float64}}

Get the points that define the PiecewisePointCurve

get_proportional_term(vc::LinearCurve) -> Float64

Get the proportional term (i.e., slope) of the LinearCurve

get_proportional_term(vc::QuadraticCurve) -> Float64

Get the proportional (i.e., linear) term of the QuadraticCurve

get_quadratic_term(vc::QuadraticCurve) -> Float64

Get the quadratic term of the QuadraticCurve

get_slopes(vc::PiecewiseIncrementalCurve) -> Vector{Float64}

Fetch the slopes that define the PiecewiseIncrementalCurve

get_slopes(vc::PiecewisePointCurve) -> Vector{Float64}

Calculate the slopes of the line segments defined by the PiecewisePointCurve

get_x_coords(vc::PiecewiseAverageCurve) -> Vector{Float64}

Get the x-coordinates that define the PiecewiseAverageCurve

get_x_coords(
    vc::PiecewiseIncrementalCurve
) -> Vector{Float64}

Get the x-coordinates that define the PiecewiseIncrementalCurve

get_x_coords(vc::PiecewisePointCurve) -> Vector{Float64}

Get the x-coordinates of the points that define the PiecewisePointCurve

get_y_coords(vc::PiecewisePointCurve) -> Vector{Float64}

Get the y-coordinates of the points that define the PiecewisePointCurve

An average rate curve, relating the production quantity to the average cost rate from the origin: y = f(x)/x. Can be used, for instance, in the representation of a CostCurve where x is MW and y is currency/MWh, or in the representation of a FuelCurve where x is MW and y is fuel/MWh. Typically calculated by dividing absolute values of cost rate or fuel input rate by absolute values of electric power.

An incremental (or 'marginal') curve, relating the production quantity to the derivative of cost: y = f'(x). Can be used, for instance, in the representation of a CostCurve where x is MW and y is currency/MWh, or in the representation of a FuelCurve where x is MW and y is fuel/MWh.

An input-output curve, directly relating the production quantity to the cost: y = f(x). Can be used, for instance, in the representation of a CostCurve where x is MW and y is currency/hr, or in the representation of a FuelCurve where x is MW and y is fuel/hr.

Supertype that represents a unitless cost curve

Concrete subtypes are:

• LinearCurve
• QuadraticCurve
• PiecewisePointCurve
• PiecewiseIncrementalCurve
• PiecewiseAverageCurve

get_function_data(curve::ValueCurve) -> Any

Get the underlying FunctionData representation of this ValueCurve

get_initial_input(
    curve::Union{AverageRateCurve, IncrementalCurve}
) -> Union{Nothing, Float64}

Get the initial_input field of this ValueCurve (not defined for InputOutputCurve)

get_input_at_zero(curve::ValueCurve) -> Any

Get the input_at_zero field of this ValueCurve

is_convex(curve::ValueCurve) -> Bool

Calculate the convexity of the underlying data

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.

mutable struct Deterministic <: AbstractDeterministic
    name::String
    data::SortedDict
    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::SortedDict: 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, <: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(
    src::Deterministic,
    name::AbstractString;
    scaling_factor_multiplier
) -> Deterministic

Construct Deterministic that shares the data from an existing instance.

This is useful in cases where you want a component to use the same time series data for two different attributes.

Examples

resolution = Dates.Hour(1)
data = Dict(
    DateTime("2020-01-01T00:00:00") => ones(24),
    DateTime("2020-01-01T01:00:00") => ones(24),
)
# Define a Deterministic for the first attribute
forecast_max_active_power = Deterministic(
    "max_active_power",
    data,
    resolution,
    scaling_factor_multiplier = get_max_active_power,
)
add_time_series!(sys, generator, forecast_max_active_power)
# Reuse time series for second attribute
forecast_max_reactive_power = Deterministic(
    forecast_max_active_power,
    "max_reactive_power"
    scaling_factor_multiplier = get_max_reactive_power,
)
add_time_series!(sys, generator, forecast_max_reactive_power)

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

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

get_data(value::Deterministic) -> DataStructures.SortedDict

Get Deterministic data.

get_name(value::Deterministic) -> String

Get Deterministic name.

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

Get Deterministic resolution.

iterate_windows(
    forecast::Deterministic
) -> Base.Generator{I, InfrastructureSystems.var"#105#106"{Deterministic}} where I<:(DataStructures.SDMKeyIteration{T} where T<:DataStructures.SortedDict)

Iterate over the windows in a forecast

Examples

for window in iterate_windows(forecast)
    @show values(maximum(window))
end

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

Set Deterministic name.

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

A deterministic forecast that wraps a SingleTimeSeries

DeterministicSingleTimeSeries behaves exactly like a Deterministic, but instead of storing windows at each initial time it provides a view into the existing SingleTimeSeries at incrementing offsets. This avoids large data duplications when there are the overlapping windows between forecasts.

Can be used as a perfect forecast based on historical data when real forecast data is unavailable.

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

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

Get DeterministicSingleTimeSeries horizon.

iterate_windows(
    forecast::DeterministicSingleTimeSeries
) -> Union{Tuple{Any}, Base.Generator{I, InfrastructureSystems.var"#134#135"{DeterministicSingleTimeSeries}} where I<:(StepRangeLen{T, R, S, Int64} where {T, R>:Dates.DateTime, S})}

Iterate over the windows in a forecast

Examples

for window in iterate_windows(forecast)
    @show values(maximum(window))
end

mutable struct Probabilistic <: Forecast
    name::String
    resolution::Dates.Period
    percentiles::Vector{Float64}
    data::SortedDict
    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::SortedDict: 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,
    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, <: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,
    resolution::Dates.Period;
    normalization_factor,
    scaling_factor_multiplier
) -> Probabilistic

Construct Deterministic from RawTimeSeries.

Probabilistic(
    src::Probabilistic,
    name::AbstractString;
    scaling_factor_multiplier
) -> Probabilistic

Construct a Probabilistic that shares the data from an existing instance.

This is useful in cases where you want a component to use the same time series data for two different attributes.

get_data(value::Probabilistic) -> DataStructures.SortedDict

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.

iterate_windows(
    forecast::Probabilistic
) -> Base.Generator{I, InfrastructureSystems.var"#105#106"{Probabilistic}} where I<:(DataStructures.SDMKeyIteration{T} where T<:DataStructures.SortedDict)

Iterate over the windows in a forecast

Examples

for window in iterate_windows(forecast)
    @show values(maximum(window))
end

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

Set Probabilistic name.

mutable struct Scenarios <: Forecast
    name::String
    resolution::Dates.Period
    scenario_count::Int64
    data::SortedDict
    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::SortedDict: 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, <: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.

Scenarios(
    src::Scenarios,
    name::AbstractString;
    scaling_factor_multiplier
) -> Scenarios

Construct Scenarios that shares the data from an existing instance.

This is useful in cases where you want a component to use the same time series data for two different attributes.

get_data(value::Scenarios) -> DataStructures.SortedDict

Get Scenarios data.

get_name(value::Scenarios) -> String

Get Scenarios name.

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

Get Scenarios resolution.

get_scenario_count(value::Scenarios) -> Int64

Get Scenarios scenario_count.

iterate_windows(
    forecast::Scenarios
) -> Base.Generator{I, InfrastructureSystems.var"#105#106"{Scenarios}} where I<:(DataStructures.SDMKeyIteration{T} where T<:DataStructures.SortedDict)

Iterate over the windows in a forecast

Examples

for window in iterate_windows(forecast)
    @show values(maximum(window))
end

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

Set Scenarios name.

Supertype for static time series, which has one value per time point

Current concrete subtypes are:

• SingleTimeSeries

See also: Forecast

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

A single column of time series data for a particular data field in a Component.

In contrast with a forecast, this can represent one continual time series, such as a series of historical measurements or realizations or a single scenario (e.g. a weather year or different input assumptions).

Arguments

• name::String: user-defined name
• data::TimeSeries.TimeArray: timestamp - scalingfactor
• resolution::Dates.Period: Time duration between steps in the time series. The resolution must be the same throughout the time series
• 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(
    src::SingleTimeSeries,
    name::AbstractString;
    scaling_factor_multiplier
) -> SingleTimeSeries

Construct SingleTimeSeries that shares the data from an existing instance.

This is useful in cases where you want a component to use the same time series data for two different attribtues.

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.

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

Get SingleTimeSeries data.

get_name(value::SingleTimeSeries) -> String

Get SingleTimeSeries name.

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

Get SingleTimeSeries resolution.

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

Set SingleTimeSeries name.

Supertype for forecast time series Current concrete subtypes are:

• Deterministic
• DeterministicSingleTimeSeries
• Scenarios
• Probabilistic

Subtypes of Forecast must implement:

• get_horizon_count
• get_initial_times
• get_initial_timestamp
• get_name
• get_scaling_factor_multiplier
• get_window
• iterate_windows

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

Return the forecast window corresponsing to interval index.

Construct ForecastCache to automatically control caching of forecast data. Maintains some count of forecast windows in memory based on cache_size_bytes.

Call Base.iterate or get_next_time_series_array! to retrieve data. Each iteration will return a TimeSeries.TimeArray covering one forecast window of length horizon_count.

Arguments

• ::Type{T}: subtype of Forecast
• component::InfrastructureSystemsComponent: component
• name::AbstractString: forecast name
• start_time::Union{Nothing, Dates.DateTime} = nothing: forecast start time
• horizon_count::Union{Nothing, Int} = nothing: forecast horizon count
• cache_size_bytes = TIME_SERIES_CACHE_SIZE_BYTES: maximum size of data to keep in memory
• ignore_scaling_factors = false: controls whether to ignore scaling_factor_multiplier in the time series instance

Construct StaticTimeSeriesCache to automatically control caching of time series data. Maintains rows of data in memory based on cache_size_bytes.

Call Base.iterate or get_time_series_array to retrieve data. Each iteration will return a TimeSeries.TimeArray of size 1.

Arguments

• ::Type{T}: subtype of StaticTimeSeries
• component::InfrastructureSystemsComponent: component
• name::AbstractString: time series name
• cache_size_bytes = TIME_SERIES_CACHE_SIZE_BYTES: maximum size of data to keep in memory
• ignore_scaling_factors = false: controls whether to ignore scalingfactormultiplier in the time series instance

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

Examples

cache = ForecastCache(Deterministic, component, "max_active_power")
window1 = get_next_time_series_array!(cache)
window2 = get_next_time_series_array!(cache)

reset!(cache::InfrastructureSystems.TimeSeriesCache)

Reset parameters in order to start reading data from the beginning with get_next_time_series_array!

copy_time_series!(
    dst::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    src::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute};
    name_mapping,
    scaling_factor_multiplier_mapping
)

Efficiently add all time_series in one component to another by copying the underlying references.

Arguments

• dst::TimeSeriesOwners: Destination owner
• src::TimeSeriesOwners: Source owner
• name_mapping::Dict = nothing: Optionally map src names to different dst names. If provided and src has a timeseries with a name not present in namemapping, that timeseries 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 multipliers to different dst multipliers. If provided and src has a timeseries with a multiplier not present in scalingfactormultipliermapping, that timeseries will not copied. If scalingfactormultipliermapping is nothing then all time_series will be copied with src's multipliers.

get_time_series(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    key::TimeSeriesKey
) -> Any
get_time_series(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    key::TimeSeriesKey,
    start_time::Union{Nothing, Dates.DateTime}
) -> Any
get_time_series(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    key::TimeSeriesKey,
    start_time::Union{Nothing, Dates.DateTime},
    len::Union{Nothing, Int64}
) -> Any
get_time_series(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    key::TimeSeriesKey,
    start_time::Union{Nothing, Dates.DateTime},
    len::Union{Nothing, Int64},
    count::Union{Nothing, Int64}
) -> Any

Return the exact stored data in a time series, using a time series key look up

This will load all forecast windows into memory by default. Be aware of how much data is stored.

Specify start_time and len if you only need a subset of data.

Does not apply a scaling factor multiplier.

Arguments

• owner::TimeSeriesOwners: Component or attribute containing the time series
• key::TimeSeriesKey: the time series' key
• start_time::Union{Nothing, Dates.DateTime} = nothing: If nothing, use the initial_timestamp of the time series. If the time series is a subtype of Forecast then start_time must be the first timestamp 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.
• features...: User-defined tags that differentiate multiple time series arrays for the same component attribute, such as different arrays for different scenarios or years

See also: get_time_series by name

get_time_series(
    ::Type{T<:TimeSeriesData},
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    name::AbstractString;
    start_time,
    len,
    count,
    features...
) -> Any

Return the exact stored data in a time series

This will load all forecast windows into memory by default. Be aware of how much data is stored.

Specify start_time and len if you only need a subset of data.

Does not apply a scaling factor multiplier.

Arguments

• ::Type{T}: Concrete subtype of TimeSeriesData to return
• owner::TimeSeriesOwners: Component or attribute 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 timestamp 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.
• features...: User-defined tags that differentiate multiple time series arrays for the same component attribute, such as different arrays for different scenarios or years

See also: get_time_series_array, get_time_series_values, get_time_series by key

get_time_series_array(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    time_series::StaticTimeSeries;
    ...
) -> Any
get_time_series_array(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    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 time series data are scaling factors, the returned data will be scaled by the scaling factor multiplier by default.

Arguments

• owner::TimeSeriesOwners: Component or attribute containing the time series
• time_series::StaticTimeSeries: subtype of StaticTimeSeries (e.g., SingleTimeSeries)
• start_time::Union{Nothing, Dates.DateTime} = nothing: the first timestamp to retrieve. If nothing, use the initial_timestamp of the time series.
• len::Union{Nothing, Int} = nothing: Length of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length
• ignore_scaling_factors = false: If true, the time-series data will be multiplied by the result of calling the stored scaling_factor_multiplier function on the owner

See also: get_time_series_values, get_time_series_timestamps, StaticTimeSeriesCache, get_time_series_array by name from storage, get_time_series_array from a ForecastCache

get_time_series_array(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    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 time series data are scaling factors, the returned data will be scaled by the scaling factor multiplier by default.

Arguments

• owner::TimeSeriesOwners: Component or attribute containing the time series
• forecast::Forecast: a concrete subtype of Forecast
• start_time::Union{Nothing, Dates.DateTime} = nothing: the first timestamp of one of the forecast windows
• len::Union{Nothing, Int} = nothing: Length of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length.
• ignore_scaling_factors = false: If true, the time-series data will be multiplied by the result of calling the stored scaling_factor_multiplier function on the owner

See also get_time_series_values, get_time_series_timestamps, ForecastCache, get_time_series_array by name from storage, get_time_series_array from a StaticTimeSeriesCache

get_time_series_array(
    ::Type{T<:TimeSeriesData},
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    name::AbstractString;
    start_time,
    len,
    ignore_scaling_factors,
    features...
) -> Any

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

If the time series data are scaling factors, the returned data will be scaled by the scaling factor multiplier by default.

This will load all forecast windows into memory by default. Be aware of how much data is stored.

Specify start_time and len if you only need a subset of data.

Arguments

• ::Type{T}: the type of time series (a concrete subtype of TimeSeriesData)
• owner::TimeSeriesOwners: Component or attribute 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 timestamp of a window.
• len::Union{Nothing, Int} = nothing: Length of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length.
• ignore_scaling_factors = false: If true, the time-series data will be multiplied by the result of calling the stored scaling_factor_multiplier function on the owner
• features...: User-defined tags that differentiate multiple time series arrays for the same component attribute, such as different arrays for different scenarios or years

See also: get_time_series_values, get_time_series_timestamps, get_time_series_array from a StaticTimeSeriesCache, get_time_series_array from a ForecastCache

get_time_series_keys(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute}
) -> Vector

Return information about each time series array attached to the owner. This information can be used to call get_time_series(::TimeSeriesOwners, ::TimeSeriesKey).

get_time_series_multiple(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute};
    ...
) -> Union{Tuple{}, Channel{Any}}
get_time_series_multiple(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    filter_func;
    type,
    name
) -> Union{Tuple{}, Channel{Any}}

Returns an iterator of TimeSeriesData instances attached to the component or attribute.

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

• owner::TimeSeriesOwners: component or attribute from which to get time_series
• 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.

See also: get_time_series_multiple from a System

get_time_series_timestamps(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    time_series::StaticTimeSeries;
    ...
) -> Vector{D} where D<:Dates.TimeType
get_time_series_timestamps(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    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.

Arguments

• owner::TimeSeriesOwners: Component or attribute containing the time series
• time_series::StaticTimeSeries: subtype of StaticTimeSeries (e.g., SingleTimeSeries)
• start_time::Union{Nothing, Dates.DateTime} = nothing: the first timestamp to retrieve. If nothing, use the initial_timestamp of the time series.
• len::Union{Nothing, Int} = nothing: Length of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length

See also: get_time_series_array, get_time_series_values, StaticTimeSeriesCache, get_time_series_timestamps by name from storage, get_time_series_timestamps from a ForecastCache

get_time_series_timestamps(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    forecast::Forecast;
    ...
)
get_time_series_timestamps(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    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.

Arguments

• owner::TimeSeriesOwners: Component or attribute containing the time series
• forecast::Forecast: a concrete subtype of Forecast
• start_time::Union{Nothing, Dates.DateTime} = nothing: the first timestamp of one of the forecast windows
• len::Union{Nothing, Int} = nothing: Length of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length.

See also: get_time_series_array, get_time_series_values, ForecastCache, get_time_series_timestamps by name from storage, get_time_series_timestamps from a StaticTimeSeriesCache

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

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

Arguments

• ::Type{T}: the type of time series (a concrete subtype of TimeSeriesData)
• owner::TimeSeriesOwners: Component or attribute 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 timestamp of a window.
• len::Union{Nothing, Int} = nothing: Length of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length.
• features...: User-defined tags that differentiate multiple time series arrays for the same component attribute, such as different arrays for different scenarios or years

See also: get_time_series_array, get_time_series_values, get_time_series_timestamps from a StaticTimeSeriesCache, get_time_series_timestamps from a ForecastCache

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

Return an vector of timeseries data without timestamps from a cached StaticTimeSeries instance

Arguments

• owner::TimeSeriesOwners: Component or attribute containing the time series
• time_series::StaticTimeSeries: subtype of StaticTimeSeries (e.g., SingleTimeSeries)
• start_time::Union{Nothing, Dates.DateTime} = nothing: the first timestamp to retrieve. If nothing, use the initial_timestamp of the time series.
• len::Union{Nothing, Int} = nothing: Length of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length
• ignore_scaling_factors = false: If true, the time-series data will be multiplied by the result of calling the stored scaling_factor_multiplier function on the owner

See also: get_time_series_array, get_time_series_timestamps, StaticTimeSeriesCache, get_time_series_values by name from storage, get_time_series_values from a ForecastCache

get_time_series_values(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    forecast::Forecast,
    start_time::Dates.DateTime;
    len,
    ignore_scaling_factors
) -> Any

Return an vector of timeseries data without timestamps for one forecast window from a cached Forecast instance.

Arguments

• owner::TimeSeriesOwners: Component or attribute containing the time series
• forecast::Forecast: a concrete subtype of Forecast
• start_time::Union{Nothing, Dates.DateTime} = nothing: the first timestamp of one of the forecast windows
• len::Union{Nothing, Int} = nothing: Length of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length.
• ignore_scaling_factors = false: If true, the time-series data will be multiplied by the result of calling the stored scaling_factor_multiplier function on the owner

See also: get_time_series_array, get_time_series_timestamps, ForecastCache, get_time_series_values by name from storage, get_time_series_values from a StaticTimeSeriesCache

get_time_series_values(
    ::Type{T<:TimeSeriesData},
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    name::AbstractString;
    start_time,
    len,
    ignore_scaling_factors,
    features...
) -> Any

Return an vector of timeseries data without timestamps from storage

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

Arguments

• ::Type{T}: type of the time series (a concrete subtype of TimeSeriesData)
• owner::TimeSeriesOwners: Component or attribute 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 timestamp of a window.
• len::Union{Nothing, Int} = nothing: Length of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length.
• ignore_scaling_factors = false: If true, the time-series data will be multiplied by the result of calling the stored scaling_factor_multiplier function on the owner
• features...: User-defined tags that differentiate multiple time series arrays for the same component attribute, such as different arrays for different scenarios or years

See also: get_time_series_array, get_time_series_timestamps, get_time_series, get_time_series_values from a StaticTimeSeriesCache, get_time_series_values from a ForecastCache

has_time_series(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute}
) -> Any

Return true if the component or supplemental attribute has time series data.

has_time_series(
    val::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    _::Type{T<:TimeSeriesData}
) -> Any

Return true if the component or supplemental attribute has time series data of type T.

A unique key to identify and retrieve a Forecast

See: get_time_series_keys and get_time_series(::TimeSeriesOwners, ::TimeSeriesKey).

A unique key to identify and retrieve a StaticTimeSeries

See: get_time_series_keys and get_time_series(::TimeSeriesOwners, ::TimeSeriesKey).

Defines an association between a time series owner (component or supplemental attribute) and the time series metadata.

Examples

association1 = TimeSeriesAssociation(component, time_series)
association2 = TimeSeriesAssociation(component, time_series, scenario = "high")

Provides counts of time series including attachments to components and supplemental attributes.

Supertype for keys that can be used to access a desired time series dataset

Concrete subtypes:

• StaticTimeSeriesKey
• ForecastKey

Required methods:

• get_name
• get_time_series_type

The default methods rely on the field names name and time_series_type.

CompressionSettings(enabled, type, level, shuffle)

Provides customization of HDF5 compression settings.

• enabled::Bool: Controls whether compression is enabled.

• type::CompressionTypes: Specifies the type of compression to use.

• level::Int64: Supported values are 0-9. Higher values deliver better compression ratios but take longer.

• shuffle::Bool: Controls whether to enable the shuffle filter. Used with DEFLATE.

Refer to the HDF5.jl and HDF5 documentation for more details on the options.

Example

settings = CompressionSettings(
    enabled = true,
    type = CompressionTypes.DEFLATE,  # BLOSC is also supported
    level = 3,
    shuffle = true,
)

show_time_series(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute}
)

Show a table with time series data attached to the component.

A power system

System is the main data container in PowerSystems.jl, including basic metadata (base power, frequency), components (network topology, loads, generators, and services), and time series data.

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{ACBus}: an array of buses
• components...: Each element (e.g., buses, generators, ...) must be an iterable containing subtypes of Component.

Keyword arguments

• ext::Dict: Contains user-defined parameters. Should only contain standard types.
• frequency::Float64: (default = 60.0) Operating frequency (Hz)
• runchecks::Bool: Run available checks on input fields and when add_component! is called. Throws InvalidValue if an error is found.
• time_series_in_memory::Bool=false: Store time series data in memory instead of HDF5.
• time_series_directory::Union{Nothing, String}: Directory for the time series HDF5 file. Defaults to the tmp file system
• 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
• unit_system::String: (Default = "SYSTEM_BASE") Set the unit system for per-unitization while getting and setting data ("SYSTEM_BASE", "DEVICE_BASE", or "NATURAL_UNITS")

By default, time series data is stored in an HDF5 file in the tmp file system to prevent large datasets from overwhelming system memory (see Data Storage). If the system's time series data will be larger than the amount of tmp space available, use the time_series_directory parameter to change its location. You can also override the location by setting the environment variable SIENNA_TIME_SERIES_DIRECTORY to another directory.

HDF5 compression is not enabled by default, but you can enable it with enable_compression to get significant storage savings at the cost of CPU time. CompressionSettings can be used to customize the HDF5 compression.

If you know that your dataset will fit in your computer's memory, then you can increase performance by storing it in memory with time_series_in_memory.

Examples

sys = System(100.0; enable_compression = true)
sys = System(100.0; compression = CompressionSettings(
    enabled = true,
    type = CompressionTypes.DEFLATE,  # BLOSC is also supported
    level = 3,
    shuffle = true)
)
sys = System(100.0; time_series_in_memory = true)

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;
    assign_new_uuids,
    kwargs...
) -> Any

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

If the file is JSON then assignnewuuids = true will generate new UUIDs for the system and all components.

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

Construct a System from InfrastructureSystems.SystemData

System(
    base_power::Float64,
    buses::Vector{ACBus},
    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(base_power::Number; kwargs...) -> System

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

from_json(
    io::Union{IO, String},
    ::Type{System};
    runchecks,
    assign_new_uuids,
    kwargs...
) -> System

If assignnewuuids = true, generate new UUIDs for the system and all components.

Warning: time series data is not restored by this method. If that is needed, use the normal process to construct the system from a serialized JSON file instead, such as with System("sys.json").

get_name(sys::System) -> Union{Nothing, String}

Get the name of the system.

get_supplemental_attribute(
    sys::System,
    uuid::Base.UUID
) -> SupplementalAttribute

Return the supplemental attribute with the given uuid.

Throws ArgumentError if the attribute is not stored.

get_supplemental_attributes(
    filter_func::Function,
    _::Type{T<:SupplementalAttribute},
    sys::System
) -> InfrastructureSystems.FlattenIteratorWrapper{T, I} where {T<:SupplementalAttribute, I<:(Vector)}

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

Examples

iter = get_supplemental_attributes(GeometricDistributionForcedOutage, sys)
iter = get_supplemental_attributes(Outage, sys)
iter = get_supplemental_attributes(x -> get_mean_time_to_recovery(x) ==  >= 0.5, GeometricDistributionForcedOutage, sys)
outages = get_supplemental_attributes(GeometricDistributionForcedOutage, sys) do outage
    get_mean_time_to_recovery(x) ==  >= 0.5
end
outages = collect(get_supplemental_attributes(GeometricDistributionForcedOutage, sys))

See also: iterate_supplemental_attributes

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!(
    component::Component,
    name::AbstractString
) -> AbstractString

Set the name of a component.

Throws an exception if the component is attached to a system.

set_name!(
    sys::System,
    name::AbstractString
) -> AbstractString

Set the name of the system.

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;
    user_data,
    pretty,
    force,
    runchecks
)

Serializes a system to a JSON file and saves time series to an HDF5 file.

Arguments

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

Keyword arguments

• user_data::Union{Nothing, Dict} = nothing: optional metadata to record
• pretty::Bool = false: whether to pretty-print the JSON
• 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.

A component cannot be added to more than one System. Throws ArgumentError if the name does not match the static_injector name. Throws ArgumentError if the static_injector is not attached to the system.

All rules for the generic add_component! method also apply.

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

Add a component to the system.

A component cannot be added to more than one 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 InvalidValue 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)))

See also add_components!.

add_components!(sys::System, components)

Add many components to the system at once.

A component cannot be added to more than one 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 InvalidValue 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]
add_components!(sys, 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::ConstantReserveGroup,
    contributing_services::Vector{<:Service};
    skip_validation,
    kwargs...
)

Similar to add_component! but for ConstantReserveGroup.

Arguments

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

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

Similar to add_component! but for ConstantReserveGroup.

Arguments

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

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_supplemental_attribute!(
    sys::System,
    component::Component,
    attribute::SupplementalAttribute
)

Add a supplemental attribute to the component. The attribute may already be attached to a different component.

add_time_series!(
    sys::System,
    metadata_file::AbstractString;
    resolution
) -> Vector{TimeSeriesKey}

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;
    features...
) -> TimeSeriesKey

Add the same time series data to multiple components.

This function stores a single copy of the data. Each component will store a reference to that data. 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;
    features...
) -> TimeSeriesKey

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
) -> Vector{TimeSeriesKey}

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.

bulk_add_time_series!(
    sys::System,
    associations;
    batch_size
) -> Vector{TimeSeriesKey}

Add many time series in bulk

This method is advantageous when adding thousands of time series arrays because of the overhead in writing the time series to the underlying storage.

Arguments

• sys::System: system
• associations: Iterable of TimeSeriesAssociation instances. Using a Vector is not recommended. Pass a Generator or Iterator to avoid loading all time series data into system memory at once.
• batch_size::Int: (Default = 100) Number of time series to add per batch.

Examples

# Assumes `read_time_series` will return data appropriate for Deterministic forecasts
# based on the generator name and the filenames match the component and time series names.
resolution = Dates.Hour(1)
associations = (
    IS.TimeSeriesAssociation(
        gen,
        Deterministic(
            data = read_time_series(get_name(gen) * ".csv"),
            name = "get_max_active_power",
            resolution=resolution),
    )
    for gen in get_components(ThermalStandard, sys)
)
bulk_add_time_series!(sys, associations)

See also: open_time_series_store! to minimize HDF5 file handle overhead if you must add time series arrays one at a time

check(sys::System)

Check system consistency and validity.

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

Check the values of a component.

Throws InvalidValue if any of the component's field values are outside of defined valid range or if the custom validate method for the type fails its check.

check_components(sys::System, components)

Check the values of each component in an iterable of components. See check_component for exceptions thrown.

check_components(sys::System; check_masked_components)

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

check_components(
    sys::System,
    ::Type{T<:Component};
    check_masked_components
)

Check the values of components of a given abstract or concrete type. See check_component for exceptions thrown.

check_time_series_consistency(
    sys::System,
    _::Type{T<:TimeSeriesData}
) -> Union{Nothing, Tuple{Any, Any}}

Checks time series in the system for inconsistencies.

For SingleTimeSeries, returns a Tuple of initial_timestamp and length.

This is a no-op for subtypes of Forecast because those are already guaranteed to be consistent.

Throws InfrastructureSystems.InvalidValue if any time series is inconsistent.

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)

Clear all time series data from the system.

If you are storing time series data in an HDF5 file, this will will delete the HDF5 file and create a new one.

See also: remove_time_series!

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

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

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

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

convert_component!(
    sys::System,
    old_load::PowerLoad,
    new_type::Type{StandardLoad};
    kwargs...
)

Converts a PowerLoad component to a StandardLoad component and replaces the original in the system. Does not set any fields in StandardLoad that lack a PowerLoad equivalent.

filter_components_by_subsystem!(
    sys::System,
    subsystem::AbstractString;
    runchecks
)

Filter out all components that are not part of the subsystem.

from_subsystem(
    sys::System,
    subsystem::AbstractString;
    runchecks
) -> System

Construct a System from a subsystem of an existing system.

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

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

get_available_components(
    _::Type{T<:Component},
    sys::System
) -> InfrastructureSystems.FlattenIteratorWrapper{T, I} where {T<:Component, I<:(Vector)}

Returns iterator of available components in a System.

T can be a concrete or abstract Component type from the Type Tree and must have the method get_available implemented. Call collect on the result if an array is desired.

get_base_power(sys::System) -> Float64

Return the system's base power.

get_bus(
    sys::System,
    name::AbstractString
) -> Union{Nothing, InfrastructureSystems.InfrastructureSystemsComponent}

Return bus with name.

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

Return bus with bus_number.

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

Return a sorted vector of bus numbers in the system.

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

Return a vector of buses contained within the AggregationTopology.

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

Return all buses values with bus_numbers.

get_component(
    sys::System,
    uuid::Base.UUID
) -> InfrastructureSystems.InfrastructureSystemsComponent

Get the component by UUID.

get_component(
    _::Type{T<:Component},
    sys::System,
    name::AbstractString
) -> Union{Nothing, InfrastructureSystems.InfrastructureSystemsComponent}

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(
    sys::System,
    attribute::SupplementalAttribute
) -> Any

Return a vector of components that are attached to the supplemental attribute.

get_components(
    filter_func::Function,
    ::Type{T<:Component},
    sys::System;
    subsystem_name
) -> InfrastructureSystems.FlattenIteratorWrapper{T, I} where {T<:Component, I<:(Vector)}

Return an iterator of components of a given Type from a System, using an additional filter

T can be a concrete or abstract Component type from the Type Tree. Call collect on the result if an array is desired.

Examples

iter_coal = get_components(x -> get_fuel(x) == ThermalFuels.COAL, Generator, sys)
pv_gens =
    collect(get_components(x -> get_prime_mover_type(x) == PrimeMovers.PVe, Generator, sys))

See also: get_components, get_available_components, get_buses

get_components(
    ::Type{T<:Component},
    sys::System;
    subsystem_name
) -> InfrastructureSystems.FlattenIteratorWrapper{T, I} where {T<:Component, I<:(Vector)}

Return an iterator of components of a given Type from a System.

T can be a concrete or abstract Component type from the Type Tree. Call collect on the result if an array is desired.

Examples

iter = get_components(ThermalStandard, sys)
iter = get_components(Generator, sys)
generators = collect(get_components(Generator, sys))

See also: iterate_components, get_components with a filter, get_available_components, get_buses

get_components_by_name(
    _::Type{T<:Component},
    sys::System,
    name::AbstractString
) -> Vector{T} where T<:InfrastructureSystems.InfrastructureSystemsComponent

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{T} where T<:StaticInjection

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::DataType, name::String}, ServiceContributingDevices}

Return an instance of ServiceContributingDevicesMapping.

get_contributing_devices(
    sys::System,
    service::Service
) -> Vector

Return a vector of devices contributing to the service.

get_description(sys::System) -> Union{Nothing, String}

Get the description of the system.

get_existing_component_types(
    sys::System
) -> Vector{DataType}

Return all the component types in the system. It does not return masked components.

get_existing_device_types(sys::System) -> Vector{DataType}

Return all the device types in the system. It does not return component types or masked components.

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

Return a user-modifiable dictionary to store extra information.

get_forecast_horizon(sys::System) -> Any

Return the horizon for all forecasts.

get_forecast_initial_times(
    sys::System
) -> Union{Vector{Any}, Vector{Dates.DateTime}, StepRangeLen{T, R, S, Int64} where {T, R>:Dates.DateTime, S}}

Return the initial times for all forecasts.

get_forecast_initial_timestamp(sys::System) -> Any

Return the initial_timestamp for all forecasts.

get_forecast_interval(sys::System) -> Any

Return the interval for all forecasts.

get_forecast_window_count(sys::System) -> Any

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_counts(sys::System) -> TimeSeriesCounts

Returns counts of time series including attachments to components and supplemental attributes.

get_time_series_resolutions(
    sys::System;
    time_series_type
) -> Any

Return a sorted Vector of distinct resolutions for all time series of the given type (or all types).

get_units_base(system::System) -> String

Get the system's unit base)

has_component(
    sys::System,
    T::Type{<:Component},
    name::AbstractString
) -> Bool

Check to see if the component of type T with name exists.

has_component(sys::System, T::Type{<:Component})

Check to see if the component of type T exists.

is_component_in_aggregation_topology(
    comp::Component,
    aggregator::AggregationTopology
) -> Union{Missing, Bool}

Return whether the given component's bus is in the AggregationTopology.

iterate_components(
    sys::System
) -> Base.Iterators.Flatten{Base.Generator{Base.ValueIterator{Dict{DataType, Dict{String, <:InfrastructureSystems.InfrastructureSystemsComponent}}}, InfrastructureSystems.var"#110#111"}}

Iterates over all components.

Examples

for component in iterate_components(sys)
    @show component
end

See also: get_components

iterate_supplemental_attributes(
    sys::System
) -> Base.Iterators.Flatten{Base.Generator{Base.ValueIterator{Dict{DataType, Dict{Base.UUID, <:SupplementalAttribute}}}, InfrastructureSystems.var"#110#111"}}

Iterates over all supplemental_attributes.

Examples

for supplemental_attribute in iterate_supplemental_attributes(sys)
    @show supplemental_attribute
end

See also: get_supplemental_attributes

open_time_series_store!(
    func::Function,
    sys::System;
    ...
) -> Any
open_time_series_store!(
    func::Function,
    sys::System,
    mode,
    args...;
    kwargs...
) -> Any

Open the time series store for bulk additions or reads

This is recommended before calling add_time_series! many times because of the overhead associated with opening and closing an HDF5 file.

This is not necessary for an in-memory time series store.

Examples

# Assume there is a system with an array of Components and SingleTimeSeries
# stored in the variables components and single_time_series, respectively
open_time_series_store!(sys, "r+") do
    for (component, ts) in zip(components, single_time_series)
        add_time_series!(sys, component, ts)
    end
end

You can also use this function to make reads faster. Change the mode from "r+" to "r" to open the file read-only.

See also: bulk_add_time_series!

remove_component!(sys::System, component::Component)

Remove a component from the system by its value.

Throws ArgumentError if the component is not stored.

remove_component!(
    _::Type{T<:Component},
    sys::System,
    name::AbstractString
)

Remove a component from the system by its name.

Throws ArgumentError if the component is not stored.

remove_supplemental_attribute!(
    sys::System,
    component::Component,
    attribute::SupplementalAttribute
)

Remove the supplemental attribute from the component. The attribute will be removed from the system if it is not attached to any other component.

remove_supplemental_attribute!(
    sys::System,
    attribute::SupplementalAttribute
)

Remove the supplemental attribute from the system and all attached components.

remove_supplemental_attributes!(
    _::Type{T<:SupplementalAttribute},
    sys::System
)

Remove all supplemental attributes with the given type from the system.

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})

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

See also: clear_time_series!

If you are storing time series data in an HDF5 file, remove_time_series! does not actually free up file space (HDF5 behavior). If you want to remove all or most time series instances then consider using clear_time_series!. It will delete the HDF5 file and create a new one. PowerSystems has plans to automate this type of workflow.

sanitize_component!(component::Component, sys::System)

Sanitize component values.

set_contributing_services!(
    sys::System,
    service::ConstantReserveGroup,
    val::Vector{<:Service}
)

Set ConstantReserveGroup contributing_services with check

set_description!(
    sys::System,
    description::AbstractString
) -> AbstractString

Set the description of the system.

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::Dates.Period,
    interval::Dates.Period
)

Transform all instances of SingleTimeSeries in a System to DeterministicSingleTimeSeries

This can be used to generate a perfect forecast from historical measurements or realizations when actual forecasts are unavailable, without unnecessarily duplicating data.

If all SingleTimeSeries instances cannot be transformed then none will be.

Any existing DeterministicSingleTimeSeries forecasts will be deleted even if the inputs are invalid.

Arguments

• sys::System: System containing the components.
• horizon::Dates.Period: desired horizon of each forecast window
• interval::Dates.Period: desired interval between forecast windows

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.

show_time_series(sys::System)

Show a table with the summary of time series attached to the system.

show_components(
    sys::System,
    component_type::Type{<:Component};
    ...
)
show_components(
    sys::System,
    component_type::Type{<:Component},
    additional_columns::Union{Dict, Vector};
    kwargs...
)

Show all components of the given type in a table.

Arguments

• sys::System: System containing the components.
• component_type::Type{<:Component}: Type to display. Must be a concrete type.
• additional_columns::Union{Dict, Vector}: Additional columns to display. The Dict option is a mapping of column name to function. The function must accept a component. The Vector option is an array of field names for the component_type.

Extra keyword arguments are forwarded to PrettyTables.pretty_table.

Examples

show_components(sys, ThermalStandard)
show_components(sys, ThermalStandard, Dict("has_time_series" => x -> has_time_series(x)))
show_components(sys, ThermalStandard, [:active_power, :reactive_power])

generate_struct_file(
    definition::StructDefinition;
    filename,
    output_directory
)

Generate a Julia source code file for one struct from a StructDefinition.

Refer to StructDefinition and StructField for descriptions of the available fields.

Arguments

• definition::StructDefinition: Defines the struct and all fields.
• filename::AbstractString: Add the struct definition to this JSON file. Defaults to src/descriptors/power_system_structs.json
• output_directory::AbstractString: Generate the files in this directory. Defaults to src/models/generated

generate_struct_files(
    definitions;
    filename,
    output_directory
)

Generate Julia source code files for multiple structs from a iterable of StructDefinition instances.

Refer to StructDefinition and StructField for descriptions of the available fields.

Arguments

• definitions: Defines the structs and all fields.
• filename::AbstractString: Add the struct definition to this JSON file. Defaults to src/descriptors/power_system_structs.json
• output_directory::AbstractString: Generate the files in this directory. Defaults to src/models/generated

get_max_active_power(d::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

get_max_reactive_power(d::Device) -> Any

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

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

create_poly_cost(
    gen,
    cost_colnames
) -> Union{Tuple{LinearCurve, Float64}, Tuple{QuadraticCurve, Float64}}

create_poly_cost(gen, cost_colnames)

Return a Polynomial function cost based on the coeffiecients provided on gen.

Three supported cases,

1. If three values are passed then we have data looking like: a2 * x^2 + a1 * x + a0,
2. If a1 and a0 are passed then we have data looking like: a1 * x + a0,
3. If only a1 is passed then we have data looking like: a1 * x.

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)

parse_file(
    io::IO;
    import_all,
    validate,
    correct_branch_rating,
    filetype
) -> Any

Parses the iostream from a file

parse_file(
    file::String;
    import_all,
    validate,
    correct_branch_rating
) -> Any

parse_file(
    file;
    import_all = false,
    validate = true,
    correct_branch_rating = true,
)

Parses a Matpower .m file or PTI (PSS(R)E-v33) .raw file into a PowerModels data structure. All fields from PTI files will be imported if import_all is true (Default: false).

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)