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 AC nodes or Areas)

Supertype for all AC transmission devices (devices connecting AC nodes only)

Supertype for all branches

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

Supertype for all Three Winding Transformer types

Supertype for all Two Terminal HVDC transmission devices between AC Buses. Not to be confused with DCBranch

Supertype for all Two Winding Transformer types

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.

clear_turbines!(device::HydroReservoir)

Remove all turbines attached to the reservoir.

has_downstream_turbine(
    reservoir::HydroReservoir,
    turbine::PowerSystems.HydroUnit
) -> Bool

Return true if the reservoir has attached the upstream turbine.

has_downstream_turbine(reservoir::HydroReservoir) -> Bool

Return true if any downstream hydro unit is attached to the reservoir.

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.

has_upstream_turbine(
    reservoir::HydroReservoir,
    turbine::PowerSystems.HydroUnit
) -> Bool

Return true if the reservoir has attached the upstream turbine.

has_upstream_turbine(reservoir::HydroReservoir) -> Bool

Return true if any upstream hydro unit is attached to the reservoir.

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

Remove a service from a device.

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

remove_turbine!(
    reservoir::HydroReservoir,
    device::HydroTurbine
)

Remove a reservoir from a device.

Throws ArgumentError if the reservoir 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) -> Float64

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

get_max_reactive_power(d::RenewableGen) -> Float64

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.

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

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"#get_subsystem_components##0#get_subsystem_components##1"{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"#get_dynamic_components##2#get_dynamic_components##3", I} where I<:(Base.Iterators.Zip{Is} where Is<:Tuple{Any, Tuple})), F<:(PowerSystems.var"#get_dynamic_components##0#get_dynamic_components##1"{<: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
• ImportExportCost

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_shut_down(
    device::StaticInjection,
    cost::MarketBidCost;
    start_time,
    len
) -> Union{Float64, TimeSeries.TimeArray}

Retrieve the shutdown 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_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 StartUpStagess; if the field is not a time series, the function returns a single StartUpStages.

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}
) -> Union{ForecastKey, StaticTimeSeriesKey}

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}
) -> Union{ForecastKey, StaticTimeSeriesKey}

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, ForecastKey, StaticTimeSeriesKey}

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_shut_down!(
    sys::System,
    component::StaticInjection,
    data::Union{Float64, TimeSeriesData}
) -> Union{Float64, ForecastKey, StaticTimeSeriesKey}

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

Arguments

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

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

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

Arguments

• sys::System: PowerSystem System
• component::StaticInjection: Static injection device
• data::Union{Float64, StartUpStages, IS.TimeSeriesData},: the data. If a time series, must be of eltype NTuple{3, Float64} – to represent a single value in a time series, use (value, 0.0, 0.0).

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}
) -> Union{ForecastKey, StaticTimeSeriesKey}

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.

ACBusTypes

Enumeration of AC power system bus types (MATPOWER Table B‑1). Each variant corresponds to a standard bus classification used in power flow and steady‑state network models:

• PQ (1): Load bus — active (P) and reactive (Q) power injections are specified; the bus voltage magnitude and angle are solved by the power‑flow algorithm.
• PV (2): Generator (PV) bus — active power (P) and voltage magnitude (V) are specified; reactive power (Q) and voltage angle are solved.
• REF (3): Reference bus — a named reference for the system voltage angle; often equivalent to a slack bus in semantics but provided separately for clarity.
• ISOLATED (4): Isolated bus — not connected to the main network (islanded or disconnected); typically excluded from the global power‑flow solution.
• SLACK (5): Slack bus — balances the system active and reactive power mismatch and sets the reference voltage angle (commonly one per connected network).

Notes

• Numeric values follow the MATPOWER convention for bus type codes.
• Use the enum members (e.g., ACBusTypes.PQ, ACBusTypes.SLACK) when constructing or interpreting network data structures to ensure clarity and compatibility with MATPOWER-based data conventions.

Reference: MATPOWER manual, Table B‑1 (http://www.pserc.cornell.edu/matpower/MATPOWER-manual.pdf).

AngleUnits

An enumeration of angular measurement units used throughout the PowerSystems package.

Values

• DEGREES: Angles expressed in degrees.
• RADIANS: Angles expressed in radians.

Usage Use AngleUnits to make unit semantics explicit for functions, fields, and APIs that accept or return angular values. When performing trigonometric calculations with Base functions (sin, cos, etc.), convert degrees to radians (e.g., θ * π/180) if the unit is DEGREES.

Examples julia> unit = AngleUnits.DEGREES AngleUnits.DEGREES

julia> θ = 30.0 julia> θ_rad = unit == AngleUnits.DEGREES ? θ * (π/180) : θ

DiscreteControlledBranchStatus

Enumeration describing the controlled (commanded) status of a branch device (such as a breaker or a switch) in a power system model.

Values

• OPEN = 0: The device is open (interrupting state) — the branch is non-conducting.
• CLOSED = 1: The device is closed (conducting state) — the branch provides a normal conduction path.

Notes

• This enum represents the intended or commanded state used by control and protection logic; it may differ from actual measured/telemetry state during faults or failures.
• The integer encoding (0/1) is chosen for compact storage and interop with serialization or external data formats.

DiscreteControlledBranchType

An enumeration representing different types of discrete controlled branches in power systems.

Values

• SWITCH = 0: Represents a switch device that can be opened or closed
• BREAKER = 1: Represents a circuit breaker that can interrupt current flow
• OTHER = 2: Represents other types of discrete controlled branch devices

FACTSOperationModes

Enumeration defining the operational modes for FACTS (Flexible AC Transmission System) devices. Based on PSSE POM v33 Manual specifications.

Values

• OOS = 0: Out-of-service mode where both Series and Shunt links are open
• NML = 1: Normal mode of operation where both Series and Shunt links are operating
• BYP = 2: Bypass mode where Series link is bypassed (acts like zero impedance line) and Shunt link operates as a STATCOM

HydroTurbineType

Enumeration of hydro turbine types supported in PowerSystems.jl.

This type is used to categorize hydroelectric generators by their turbine design and operating head. It provides a standardized set of turbine types to ensure consistent modeling and data handling across different systems.

Values

• UNKNOWN : Default value when the turbine type is not specified.
• PELTON : Impulse turbine, typically used for high-head, low-flow sites.
• FRANCIS : Reaction turbine, widely used for medium-head applications.
• KAPLAN : Adjustable-blade propeller turbine for low-head, high-flow sites.
• TURGO : Impulse turbine similar to Pelton but suitable for higher flow rates.
• CROSSFLOW : Banki-Michell (crossflow) impulse turbine, robust for small hydro.
• BULB : Compact Kaplan variant, typically installed in low-head run-of-river plants.
• DERIAZ : Diagonal flow reaction turbine with variable pitch blades.
• PROPELLER : Fixed-blade propeller turbine, simpler than Kaplan but less efficient at part load.
• OTHER : Placeholder for less common or custom turbine designs.

ImpedanceCorrectionTransformerControlMode

Enumeration defining the control modes for impedance correction in transformers, based on PSS/E transformer control definitions.

Values

• PHASE_SHIFT_ANGLE = 1: Control mode for phase-shifting transformers where the impedance correction is applied based on the phase shift angle. Used when the transformer primarily controls power flow through phase angle adjustment.
• TAP_RATIO = 2: Control mode for tap-changing transformers where the impedance correction is applied based on the tap ratio. Used when the transformer primarily controls voltage magnitude through tap position changes.

Notes

This enumeration corresponds to PSS/E transformer control field definitions for determining how impedance corrections are calculated and applied in power flow and dynamic simulation studies.

LoadConformity

WECC-defined enumeration for load conformity classification used in dynamic modeling.

Load conformity indicates whether a load follows system voltage and frequency variations according to WECC modeling standards:

• NON_CONFORMING = 0: Load that does not respond predictably to voltage and frequency changes, typically representing constant power loads or loads with complex control systems
• CONFORMING = 1: Load that responds predictably to voltage and frequency variations, following standard load modeling practices for dynamic studies
• UNDEFINED = 2: Load conformity status is not specified or unknown

This classification is essential for WECC dynamic studies as it determines how loads are modeled during system disturbances and stability analysis.

MotorLoadTechnology

An enumeration representing different motor load technologies used in industrial applications.

Values

• INDUCTION: Induction motor technology, commonly used for general-purpose applications
• SYNCHRONOUS: Synchronous motor technology, used for applications requiring constant speed
• UNDETERMINED: Motor technology type is not specified or unknown

PrimeMovers

Enumeration of prime mover types used in electric power generation, as defined by the U.S. Energy Information Administration (EIA) Form 923 instructions.

Prime movers are the engines, turbines, water wheels, or similar machines that drive electric generators or provide mechanical energy for other purposes. This enumeration provides standardized codes for different types of prime movers used in power plants.

PVe is used for photovoltaic systems renaming from EIA PV to avoid conflict with BusType.PV

References

• EIA Form 923 Instructions

See Also

• ThermalStandard: Uses prime mover information for generator specifications
• ThermalMultiStart: Uses prime mover information for generator specifications

ReservoirDataType

Enumeration of reservoir accounting unit classes.

This enum identifies the type of data recorded or tracked for a reservoir. Use these values when specifying the kind of measurement or accounting quantity associated with a reservoir (for example in time series, storage models, reporting, or data exchange).

Values

• USABLE_VOLUME: Volume available for operations and dispatch (active storage). Typically reported in cubic meters (m³) or other volumetric units.
• TOTALVOLUME: Total reservoir volume including dead and active storage. Reported in the same volumetric units as USABLEVOLUME.
• HEAD: Hydraulic head or water surface elevation relative to a datum, typically reported in meters (m).
• ENERGY: Stored or deliverable energy associated with the reservoir (e.g., potential energy or expected generation), often expressed in MWh, GWh, or joules.

ReservoirLocation

Enumeration representing the location of a hydro reservoir relative to its associated turbine.

Values

• HEAD: The reservoir is located upstream of the turbine, typically at a higher elevation.
• TAIL: The reservoir is located downstream of the turbine at a lower or same elevation.

StorageTech

Enumeration of energy storage technologies used in power systems.

Values

• PTES: Pumped thermal energy storage
• LIB: Lithium-ion Battery
• LAB: Lead Acid Battery
• FLWB: Redox Flow Battery
• SIB: Sodium Ion Battery
• ZIB: Zinc Ion Battery
• HGS: Hydrogen Gas Storage
• LAES: Liquid Air Energy Storage
• OTHER_CHEM: Chemical Storage (other than specified)
• OTHER_MECH: Mechanical Storage (other than specified)
• OTHER_THERM: Thermal Storage (other than specified)

This enumeration is used to classify different types of energy storage systems based on their underlying technology and storage mechanism.

ThermalFuels

Enumeration of thermal fuel types based on AER (Aggregated Energy Reporting) fuel codes as defined by the U.S. Energy Information Administration (EIA) Form 923.

The fuel codes represent standardized categories for reporting fuel consumption in electric power generation, covering major thermal fuel types including:

• Coal and coal-derived fuels
• Natural gas and petroleum products
• Nuclear fuel
• Biomass and waste fuels
• Other thermal energy sources

Reference: EIA Form 923 Instructions (https://www.eia.gov/survey/form/eia_923/instructions.pdf) General Coal and Geothermal codes not directly from the current EIA 923 form but kept for compatibility with older versions of the form. See also: ThermalStandard

WindingCategory

An enumeration representing different types of transformer windings used in power system analysis. Reflects how to interpret the Transformer Impedance Correction Table (TICT) winding association as described in ImpedanceCorrectionData.

Values

• TR2W_WINDING = 0: Winding associated with a two-winding transformer (Transformer2W) connected to a tap-changing transformer's ImpedanceCorrectionData
• PRIMARY_WINDING = 1: Primary winding of a three-winding transformer (Transformer3W) associated with a ImpedanceCorrectionData
• SECONDARY_WINDING = 2: Secondary winding of a three-winding transformer (Transformer3W) associated with a ImpedanceCorrectionData
• TERTIARY_WINDING = 3: Tertiary winding of a three-winding transformer (Transformer3W) associated with a ImpedanceCorrectionData

This enumeration is used to categorize transformer windings based on their role and configuration in the power system model, particularly in relation to tap-changing transformers.

WindingGroupNumber

Enumeration defining transformer winding group numbers based on IEC 60076-1 standard. These numbers represent the phase displacement between primary and secondary windings of three-phase transformers.

Valid Values

• UNDEFINED = -99: Undefined or unspecified winding group
• GROUP_0 = 0: 0° phase displacement (Yy0, Dd0, Dz0)
• GROUP_1 = 1: -30° phase displacement (Yy1, Dd1, Dz1)
• GROUP_5 = 5: -150° phase displacement (Yy5, Dd5, Dz5)
• GROUP_6 = 6: 180° phase displacement (Yy6, Dd6, Dz6)
• GROUP_7 = 7: 150° phase displacement (Yy7, Dd7, Dz7)
• GROUP_11 = 11: 30° phase displacement (Yy11, Dd11, Dz11)

Notes

The phase displacement is measured from the primary to secondary winding, with positive angles representing a lead and negative angles representing a lag. Clock notation follows the convention where each hour represents 30°.

Attribute that contains the representation of the status of the component forced outage. The time series data for fixed outages can be obtained from the simulation of a stochastic process or historical information.

Arguments

• outage_status::String: The forced outage status in the model. 1 represents outaged and 0 represents available.
• internal::InfrastructureSystemsInternal: power system internal reference, do not modify

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

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.

Attribute that contains information regarding the Impedance Correction Table (ICT) rows defined in the Table.

Arguments

• table_number::Int64: Row number of the ICT to be linked with a specific Transformer component.
• impedance_correction_curve::PiecewiseLinearData: Function to define intervals (tap ratio/angle shift) in the Transformer component.
• transformer_winding::WindingCategory: Indicates the winding to which the ICT is linked to for a Transformer component.
• transformer_control_mode::String: Defines the control modes of the Transformer, whether is for off-nominal turns ratio or phase angle shifts.
• internal::InfrastructureSystemsInternal: power system internal reference, do not modify

get_impedance_correction_curve(
    value::ImpedanceCorrectionData
) -> PiecewiseLinearData

Get ImpedanceCorrectionData function_data.

get_table_number(value::ImpedanceCorrectionData) -> Int64

Get ImpedanceCorrectionData table_number.

get_transformer_control_mode(
    value::ImpedanceCorrectionData
) -> ImpedanceCorrectionTransformerControlMode

Get ImpedanceCorrectionData transformer_control_mode.

get_transformer_winding(
    value::ImpedanceCorrectionData
) -> WindingCategory

Get ImpedanceCorrectionData transformer_winding.

Attribute to store Geographic Information about the system components

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

• startup_fuel_offtake::LinearCurve: (default of 0) Fuel consumption at the unit startup proceedure. Additional cost to the startup costs and related only to the initial fuel required to start the unit. represented as a LinearCurve

• 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, startup_fuel_offtake, vom_cost)
FuelCurve(value_curve, fuel_cost)
FuelCurve(value_curve, fuel_cost, startup_fuel_offtake, vom_cost)
FuelCurve(value_curve, power_units, fuel_cost)
FuelCurve(; value_curve, power_units, fuel_cost, startup_fuel_offtake, 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_concave(cost::ProductionVariableCostCurve) -> Any

Calculate the concavity of the underlying data

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_concave(curve::ValueCurve) -> Bool

Calculate the concavity of the underlying data

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
    interval::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
• interval::Dates.Period: forecast interval
• 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};
    resolution,
    interval,
    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.
• resolution::Union{Nothing, Dates.Period} = nothing: If nothing, infer resolution from the data. Otherwise, it must be the difference between each consecutive timestamps. Resolution is required if the resolution is irregular, such as with Dates.Month or Dates.Year.
• interval::Union{Nothing, Dates.Period} = nothing: If nothing, infer interval from the data. Otherwise, it must be the difference in time between the start of each window. Interval is required if the interval is irregular, such as with Dates.Month or Dates.Year.
• 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;
    interval,
    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;
    interval,
    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"#iterate_windows_common##0#iterate_windows_common##1"{Deterministic}} where I<:(DataStructures.IterableObject{C, DataStructures.EntireContainer, DataStructures.KeysIter, DataStructures.NoTokens, DataStructures.ForwardIter} where C<:(DataStructures.SortedDict{K, D, Ord} where {Ord<:Base.Order.Ordering, D, K}))

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"#iterate_windows##0#iterate_windows##1"{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
    interval::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
• interval::Dates.Period: forecast interval
• 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{Dates.DateTime, <:TimeSeries.TimeArray},
    percentiles::Vector{Float64};
    resolution,
    interval,
    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
• resolution::Union{Nothing, Dates.Period} = nothing: If nothing, infer resolution from the data. Otherwise, this must be the difference between each consecutive timestamps. This is required if the resolution is irregular, such as Dates.Month or Dates.Year.
• interval::Union{Nothing, Dates.Period} = nothing: If nothing, infer interval from the data. Otherwise, it must be the difference in time between the start of each window. Interval is required if the type is irregular, such as with Dates.Month or Dates.Year.
• 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,
    data::DataStructures.SortedDict{Dates.DateTime, Matrix{Float64}},
    percentiles::Vector,
    resolution::Dates.Period;
    interval,
    normalization_factor,
    scaling_factor_multiplier
) -> Probabilistic

Construct Probabilistic from a SortedDict of Arrays.

Arguments

• name::AbstractString: user-defined name
• 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`
• interval::Union{Nothing, Dates.Period}: If nothing, infer interval from the data. Otherwise, it must be the difference in time between the start of each window. Interval is required if the type is irregular, such as with Dates.Month or Dates.Year.
• 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,
    series_data::InfrastructureSystems.RawTimeSeries,
    percentiles::Vector,
    resolution::Dates.Period;
    interval,
    normalization_factor,
    scaling_factor_multiplier
)

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"#iterate_windows_common##0#iterate_windows_common##1"{Probabilistic}} where I<:(DataStructures.IterableObject{C, DataStructures.EntireContainer, DataStructures.KeysIter, DataStructures.NoTokens, DataStructures.ForwardIter} where C<:(DataStructures.SortedDict{K, D, Ord} where {Ord<:Base.Order.Ordering, D, K}))

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
    interval::Dates.Period
    scenario_count::Int
    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
• interval::Dates.Period: forecast interval
• scenario_count::Int: 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{Dates.DateTime, <:TimeSeries.TimeArray};
    resolution,
    interval,
    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.
• resolution::Union{Nothing, Dates.Period} = nothing: If nothing, infer resolution from the data. Otherwise, it must be the difference between each consecutive timestamps. Resolution is required if the type is irregular, such as with Dates.Month or Dates.Year.
• interval::Union{Nothing, Dates.Period} = nothing: If nothing, infer interval from the data. Otherwise, it must be the difference in time between the start of each window. Interval is required if the type is irregular, such as with Dates.Month or Dates.Year.
• 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(
    name::AbstractString,
    data::DataStructures.SortedDict{Dates.DateTime, Matrix{Float64}},
    resolution::Dates.Period;
    interval,
    normalization_factor,
    scaling_factor_multiplier
) -> Scenarios

Construct Scenarios from a SortedDict of Arrays.

Arguments

• name::AbstractString: user-defined name
• input_data::SortedDict{Dates.DateTime, Matrix{Float64}}: time series data.
• resolution::Dates.Period: The resolution of the forecast in Dates.Period
• interval::Union{Nothing, Dates.Period}: If nothing, infer interval from the data. Otherwise, this must be the difference in time between the start of each window. Interval is required if the type is irregular, such as with Dates.Month or Dates.Year.
• 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(
    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"#iterate_windows_common##0#iterate_windows_common##1"{Scenarios}} where I<:(DataStructures.IterableObject{C, DataStructures.EntireContainer, DataStructures.KeysIter, DataStructures.NoTokens, DataStructures.ForwardIter} where C<:(DataStructures.SortedDict{K, D, Ord} where {Ord<:Base.Order.Ordering, D, K}))

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,
    resolution
) -> 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::Symbol = :timestamp: If a DataFrame is passed then this must be the column name that contains timestamps.
• resolution::Union{Nothing, Dates.Period} = nothing: If nothing, infer resolution from the data. Otherwise, it must be the difference between each consecutive timestamps. Resolution is required if the resolution is irregular, such as with Dates.Month or Dates.Year.

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 scaling_factor_multiplier 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 time_series with a name not present in name_mapping, that time_series will not copied. If name_mapping 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 time_series with a multiplier not present in scaling_factor_multiplier_mapping, that time_series will not copied. If scaling_factor_multiplier_mapping is nothing then all time_series will be copied with src's multipliers.

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

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

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,
    resolution,
    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
• resolution::Union{Nothing, Dates.Period} = nothing: Required if resolution is needed to uniquely identify the 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},
    forecast::Forecast;
    start_time,
    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(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    time_series::StaticTimeSeries;
    start_time,
    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},
    key::TimeSeriesKey;
    start_time,
    len,
    ignore_scaling_factors
) -> Any

Return a TimeSeries.TimeArray from storage, using a time series key.

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
• 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 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 by name, get_time_series_values, get_time_series_timestamps

get_time_series_array(
    ::Type{T<:TimeSeriesData},
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    name::AbstractString;
    resolution,
    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
• resolution::Union{Nothing, Dates.Period} = nothing: Required if resolution is needed to uniquely identify the 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,
    resolution
) -> 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::Union{Nothing, ::Type{<:TimeSeriesData}} = nothing: Only return time_series with this type.
• name::Union{Nothing, AbstractString} = nothing: Only return time_series matching this value.
• resolution::Union{Nothing, Dates.Period} = 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},
    forecast::Forecast;
    start_time,
    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(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    time_series::StaticTimeSeries;
    start_time,
    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},
    key::TimeSeriesKey;
    start_time,
    len
) -> Vector{D} where D<:Dates.TimeType

Return a vector of timestamps from storage, using a time series key.

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 of time-series to retrieve (i.e. number of timestamps). If nothing, use the entire length.

See also: get_time_series_timestamps by name, get_time_series_array, get_time_series_values

get_time_series_timestamps(
    ::Type{T<:TimeSeriesData},
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    name::AbstractString;
    resolution,
    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
• resolution::Union{Nothing, Dates.Period} = nothing: Required if resolution is needed to uniquely identify the 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},
    forecast::Forecast;
    start_time,
    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(
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    time_series::StaticTimeSeries;
    start_time,
    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},
    key::TimeSeriesKey;
    start_time,
    len,
    ignore_scaling_factors
) -> Any

Return a vector of time series data without timestamps from storage, using a time series key.

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 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 by name, get_time_series_array, get_time_series_timestamps

get_time_series_values(
    ::Type{T<:TimeSeriesData},
    owner::Union{InfrastructureSystems.InfrastructureSystemsComponent, SupplementalAttribute},
    name::AbstractString;
    resolution,
    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
• resolution::Union{Nothing, Dates.Period} = nothing: Required if resolution is needed to uniquely identify the 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};
    kwargs...
) -> Bool

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

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

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_resolution
• 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.
• file::AbstractString: Path to a Matpower, PSSE, or JSON file ending with .m, .raw, or .json

Keyword arguments

• name::String: System name.
• description::String: System description.
• 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.
• generator_mapping: A dictionary mapping generator names to their corresponding topologies. This is used to associate generators with their respective buses when parsing from CSV.
• 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.
• timeseries_metadata_file: Path to a file containing time series metadata descriptors. This is used to add time series data to the system from files.
• time_series_read_only::Bool=false: Open the time series store in read-only mode. This is useful for reading time series data without modifying it.
• 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")
• bus_name_formatter: A function that takes a Bus and returns a string to use as the bus name when parsing PSSe or Matpower files.
• load_name_formatter: A function that takes an ElectricLoad and returns a string to use as the load names when parsing PSSe or Matpower files.
• loadzone_name_formatter: A function that takes a LoadZone and returns a string to use as the load zone name when parsing PSSe or Matpower files.
• gen_name_formatter: A function that takes a Generator and returns a string to use as the generator name when parsing PSSe or Matpower files.
• shunt_name_formatter: A function that takes the fixed shunt data and returns a string to use as the FixedAdmittance name when parsing PSSe or Matpower files.
• branch_name_formatter: A function that takes a Branch and returns a string to use as the branch name when parsing PSSe or Matpower files.
• pm_data_corrections::Bool: A function that applies the correction to the data from PowerModels.jl.
• import_all::Bool: A boolean flag to indicate whether to import all available data when parsing PSSe or Matpower files. The additional data will be stored in the ext dictionary and can be retrieved using get_ext
• internal::IS.InfrastructureSystemsInternal: Internal structure for InfrastructureSystems.jl. This is used only during JSON de-seralization, do not pass it when building a System manually.

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; name = "My Power System")
sys = System(100.0; name = "My Power System", description = "System corresponds to scenario A")
sys= System(path_to_my_psse_raw_file; # PSSE file bus names are not unique
    bus_name_formatter = x -> strip(string(x["name"])) * "-" * string(x["index"]),
)
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,
    try_reimport,
    kwargs...
) -> Any

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

If the file is JSON, then assign_new_uuids = true will generate new UUIDs for the system and all components. If the file is .raw, then try_reimport = false will skip searching for a <name>_export_metadata.json file in the same directory.

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.

get_associated_components(
    sys::System,
    attribute::SupplementalAttribute;
    component_type
) -> Any

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

Arguments

• sys::System: the System to search
• attribute::SupplementalAttribute: Only return components associated with this attribute.
• component_type::Union{Nothing, <:Component}: Optional type of the components to return. Can be concrete or abstract. If not provided, all components associated with the attribute will be returned.

get_associated_components(
    sys::System,
    attribute_type::Type{<:SupplementalAttribute};
    component_type
) -> Any

Return a vector of components that are associated to one or more supplemental attributes of the given type.

get_available_component(
    sys::System,
    uuid::Base.UUID
) -> Union{Nothing, InfrastructureSystems.InfrastructureSystemsComponent}

Get the available component by UUID.

get_available_component(
    ::Type{T<:Component},
    sys::System,
    args...;
    kwargs...
) -> Union{Nothing, InfrastructureSystems.InfrastructureSystemsComponent}

Like get_component but also returns nothing if the component is not get_available.

get_available_components(
    sys::System,
    attribute::SupplementalAttribute
)

Like [get_components](@ref getcomponents( sys::System, attribute::SupplementalAttribute ) but returns only components that are [`getavailable`](@ref).

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

Like get_components but returns only components that are get_available.

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

Like get_components but returns only components that are get_available. ```

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(
    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

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

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

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_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...
) -> Union{ForecastKey, StaticTimeSeriesKey}

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...
) -> Union{ForecastKey, StaticTimeSeriesKey}

Add time series data to a component. Assign optional features to differentiate time series of the same type with the same name but with different data.

Returns a key that can later be used to retrieve the time series data.

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

Examples

ts1 = Deterministic(
    name = "max_active_power",
    data = deterministic_data,
    resolution = Dates.Hour(1),
)
ts2 = SingleTimeSeries(
    name = "max_active_power",
    data = time_array_1,
)
ts3 = SingleTimeSeries(
    name = "max_active_power",
    data = time_array_2,
)
key1 = add_time_series!(system, component, ts1)
key2 = add_time_series!(system, component, ts2, scenario = "high")
key3 = add_time_series!(system, component, ts3, scenario = "low")
ts1_b = get_time_series(component, key1)
ts2_b = get_time_series(component, key2)
ts3_b = get_time_series(component, key3)

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.

begin_supplemental_attributes_update(
    func::Function,
    sys::System
) -> Any

Begin an update of supplemental attributes. Use this function when adding or removing many supplemental attributes in order to improve performance.

If an error occurs during the update, changes will be reverted.

Examples

begin_supplemental_attributes_update(sys) do
    add_supplemental_attribute!(sys, component1, attribute1)
    add_supplemental_attribute!(sys, component2, attribute2)
end

begin_time_series_update(func::Function, sys::System) -> Any

Begin an update of time series. Use this function when adding many time series arrays in order to improve performance.

If an error occurs during the update, changes will be reverted.

Using this function to remove time series is currently not supported.

Examples

begin_time_series_update(sys) do
    add_time_series!(sys, component1, time_series1)
    add_time_series!(sys, component2, time_series2)
end

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

Add time series in bulk.

Prefer use of begin_time_series_update.

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)

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.

Arguments

• sys::System: the base system from which the subsystems are derived
• subsystem::String: the name of the subsystem to extract from the original system

Keyword arguments

• runchecks::Bool: (default = true) whether to run system validation checks.

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

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

get_associated_supplemental_attributes(
    sys::System,
    ::Type{T<:InfrastructureSystems.InfrastructureSystemsComponent};
    attribute_type
) -> Any

get_associated_supplemental_attributes(obj)

Retrieves supplemental attributes associated with the given object.

This function extracts and returns additional metadata or auxiliary information that is linked to the specified object, typically used for extended functionality or configuration purposes.

Arguments

• obj: The object for which to retrieve associated supplemental attributes

Returns

• Collection of supplemental attributes associated with the input object

Examples

gen_attr_pairs = get_component_supplemental_attribute_pairs(
    GeometricDistributionForcedOutage,
    ThermalStandard,
    sys,
)
for (gen, attr) in gen_attr_pairs
    @show summary(gen) summary(attr)
end

my_generators = [gen1, gen2, gen3]
gen_attr_pairs_limited = get_component_supplemental_attribute_pairs(
    GeometricDistributionForcedOutage,
    ThermalStandard,
    sys,
    components = my_generators,
)
for (gen, attr) in gen_attr_pairs_limited
    @show summary(gen) summary(attr)
end

get_base_power(sys::System) -> Float64

Return the system's base power.

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

Return ACBus with name.

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

Return ACBus 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 an AggregationTopology.

Examples

area = get_component(Area, system, "my_area"); # Get an Area named my_area
area_buses = get_buses(system, area)

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

Return ACBuses from a set of identification numbers

Examples

# View all the bus ID numbers in the System
get_number.(get_components(ACBus, system))
# Select a subset
buses_by_ID = get_buses(system, Set(101:110))

get_component_supplemental_attribute_pairs(
    ::Type{T<:Component},
    ::Type{U<:SupplementalAttribute},
    sys::System;
    components,
    attributes
) -> Array{NamedTuple{(:component, :supplemental_attribute), var"#s177"}, 1} where var"#s177"<:Tuple{Component, SupplementalAttribute}

Return a vector of NamedTuples with pairs of components and supplemental attributes that are associated with each other. Limit by components and attributes if provided.

The return type is NamedTuple{(:component, :supplemental_attribute), Tuple{T, U}}[] where T is the component type and U is the supplemental attribute type.

Arguments

• sys::System: System containing the components and attributes.
• ::Type{T}: Type of the components to filter by. Can be concrete or abstract.
• ::Type{U}: Type of the supplemental attributes to filter by. Can be concrete or abstract.
• components: Optional iterable. If set, filter pairs where the component is in this iterable.
• attributes: Optional iterable. If set, filter pairs where the supplemental attribute is in this iterable.

Examples

gen_attr_pairs = get_component_supplemental_attribute_pairs(
    GeometricDistributionForcedOutage,
    ThermalStandard,
    sys,
)
for (gen, attr) in gen_attr_pairs
    @show summary(gen) summary(attr)
end

my_generators = [gen1, gen2, gen3]
gen_attr_pairs_limited = get_component_supplemental_attribute_pairs(
    GeometricDistributionForcedOutage,
    ThermalStandard,
    sys,
    components = my_generators,
)
for (gen, attr) in gen_attr_pairs_limited
    @show summary(gen) summary(attr)
end

get_components_by_name(
    _::Type{T<:Component},
    sys::System,
    name::AbstractString
) -> Vector{<: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_connected_head_reservoirs(
    sys::System,
    turbine::PowerSystems.HydroUnit
) -> Vector

Return a vector of connected head reservoirs to the turbine. Reservoirs that have the turbine in their downstream_turbines field are head reservoirs of such turbine.

get_connected_tail_reservoirs(
    sys::System,
    turbine::PowerSystems.HydroUnit
) -> Vector

Return a vector of connected tail reservoirs to the turbine. Reservoirs that have the turbine in their upstream_turbines field are tail reservoirs of such turbine.

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

Return an instance of ServiceContributingDevicesMapping.

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

Return a vector of devices contributing to the service.

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

Return a vector of devices contributing to the service.

get_contributing_reserve_mapping(
    sys::System
) -> Dict{@NamedTuple{type::DataType, name::String}, PowerSystems.AGCContributingReserves}

Return an instance of AGCContributingReservesMapping.

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_summary_table(
    sys::System
) -> DataFrames.DataFrame

Return a DataFrame with the number of forecasts for components and supplemental attributes.

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_static_time_series_summary_table(
    sys::System
) -> DataFrames.DataFrame

Return a DataFrame with the number of static time series for components and supplemental attributes.

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_turbine_head_reservoirs_mapping(
    sys::System
) -> Dict{@NamedTuple{type::DataType, name::String}, TurbineConnectedDevices}

Return an instance of TurbineConnectedDevicesMapping.

get_turbine_tail_reservoirs_mapping(
    sys::System
) -> Dict{@NamedTuple{type::DataType, name::String}, TurbineConnectedDevices}

Return an instance of TurbineConnectedDevicesMapping.

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
) -> InfrastructureSystems.FlattenIteratorWrapper{InfrastructureSystems.InfrastructureSystemsComponent, I} where I<:(Vector)

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"#iterate_container##0#iterate_container##1"}}

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: begin_time_series_update

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_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},
    owner::Union{SupplementalAttribute, Component},
    name::String
)

Remove the time series data for a component or supplemental attribute 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_bus_number!(sys::System, bus::ACBus, number::Int64)

Set the number of a bus.

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,
    units::Union{UnitSystem, String}
)

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

Examples

set_units_base_system!(sys, "NATURAL_UNITS")

set_units_base_system!(sys, UnitSystem.SYSTEM_BASE)

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

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
• resolution::Union{Nothing, Dates.Period} = nothing: If set, only transform time series with this resolution.

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.

with_units_base(
    f::Function,
    c::Component,
    units::Union{UnitSystem, String}
) -> Any

A "context manager" that sets the Component's units base to the given value, executes the function, then sets the units base back.

Examples

active_power_mw = with_units_base(component, UnitSystem.NATURAL_UNITS) do
    get_active_power(component)
end
# now active_power_mw is in natural units no matter what units base the system is in

with_units_base(
    f::Function,
    sys::System,
    units::Union{UnitSystem, String}
) -> Any

A "context manager" that sets the System's units base to the given value, executes the function, then sets the units base back.

Examples

active_power_mw = with_units_base(sys, UnitSystem.NATURAL_UNITS) do
    get_active_power(gen)
end
# now active_power_mw is in natural units no matter what units base the system is in

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

Given some ComponentContainer-like source of components to draw from, such as a PowerSystems.System, a ComponentSelector picks out a certain subset of them based on some user-defined selection criteria. A ComponentSelector can also be used to name that subset of components or to split it up into groups. The same ComponentSelector can be used to apply the same set of selection criteria to multiple sources of components. The primary use case for ComponentSelector is to support repeatable multi-scenario post-processing analytics (see e.g. PowerAnalytics.jl).

Formally, instances of ComponentSelector represent lazy, partitioned, named, source-independent collections of InfrastructureSystemsComponents.

Core Interface

• make_selector: factory function to handle ComponentSelector creation; end users should use this rather than calling the constructors directly.
• get_groups: get the groups that make up a ComponentSelector, which will themselves be represented as ComponentSelectors.
• get_components: get all the components that make up a ComponentSelector, ignoring how they are grouped. A component should appear in the get_components of a given selector if and only if it appears in the get_components of at least one of that selector's groups.
• get_name: get the name of the ComponentSelector. All ComponentSelectors have a name, whether it is specified by the user or created automatically.
• rebuild_selector: create a new ComponentSelector from an existing one with some details (e.g., the name or the grouping behavior) tweaked.

Availability Filtering

Besides the core interface, also provided are get_component for ComponentSelector subtypes that can only refer to at most one component; and get_available_component, get_available_components, and get_available_groups, which work the same as the corresponding functions without available except they only consider components for which get_available is true.

scope_limiter Filtering

The ComponentSelector methods of get_component, get_components, and get_groups, and the corresponding _available_ variants, take an optional first argument scope_limiter::Union{Function, Nothing}. If a function is passed in here, it will be used as a filter function to limit the components under consideration before the ComponentSelector's criteria are evaluated.

get_name(selector::ComponentSelector) -> Any

Get the name of the ComponentSelector. This is either a user-specified name passed in at creation or a name automatically generated from the selector's specification.

Examples

sel = make_selector(RenewableDispatch)
get_name(sel)  # "RenewableDispatch"

Factory function to create the appropriate subtype of ComponentSelector given the arguments. Users should call this rather than manually constructing ComponentSelectors.

Arguments

Several methods of this function have a parameter groupby::Union{Symbol, Function}, which specifies how the selector is grouped for the purposes of get_groups. The groupby argument has the following semantics:

• groupby = :each (default): each component that makes up the selector forms its own group. The number of groups from get_groups will be equal to the number of components from get_components.
• groupby = :all: all components that make up the selector are put into the same group. get_groups will yield one group.
• groupby = partition_function: if the argument is a user-supplied function, the function will be applied to each component; all components with the same result under the function will be grouped together, with the name of the group specified by the function's output.

Other arguments are documented on a per-method basis.

Examples

See the methods.

make_selector(
    filter_func::Function,
    component_type::Type{<:InfrastructureSystems.InfrastructureSystemsComponent};
    name,
    groupby
) -> InfrastructureSystems.FilterComponentSelector

Make a ComponentSelector from a filter function and a type of component. The filter function must accept instances of component_type as a sole argument and return a Bool. Optionally provide a grouping behavior and/or name for the selector. Selectors constructed this way point to all the components of the given type that satisfy the filter function, grouped by the groupby argument (see the base make_selector documentation).

Arguments

• filter_func::Function: the filter function to apply to components
• component_type::Type{<:InfrastructureSystemsComponent}: the type of component to select
• groupby::Union{Symbol, Function} = :each: the grouping behavior (see the base make_selector documentation)
• name::Union{String, Nothing} = nothing: the name of the selector; if not provided, one will be constructed automatically

Examples

sel1 = make_selector(RenewableDispatch, x -> get_prime_mover_type(x) == PrimeMovers.PVe)
sel2 = make_selector(RenewableDispatch, x -> get_prime_mover_type(x) == PrimeMovers.PVe; groupby = :all)
sel3 = make_selector(RenewableDispatch, x -> get_prime_mover_type(x) == PrimeMovers.PVe; name = "my_selector")

See also: make_selector unified function documentation

make_selector(
    component::InfrastructureSystems.InfrastructureSystemsComponent;
    name
) -> InfrastructureSystems.NameComponentSelector

Make a ComponentSelector from a component, pointing to a single component with the same type and name as the one given. Optionally provide a name for the selector. Selectors constructed this way contain exactly one group, which contains one component if the target component exists and zero if it doesn't.

Arguments

• component::InfrastructureSystemsComponent: the component whose type and name specify the target of this selector
• name::Union{String, Nothing} = nothing: the name of the selector; if not provided, one will be constructed automatically

Examples

sel1 = make_selector(my_component)
sel2 = make_selector(my_component; name = "my_selector")

See also: make_selector unified function documentation

make_selector(
    component_type::Type{<:InfrastructureSystems.InfrastructureSystemsComponent},
    component_name::AbstractString;
    name
) -> InfrastructureSystems.NameComponentSelector

Make a ComponentSelector pointing to a single component with the given type and name. Optionally provide a name for the selector. Selectors constructed this way contain exactly one group, which contains one component if the target component exists and zero if it doesn't.

Arguments

• component_type::Type{<:InfrastructureSystemsComponent}: the type of the target component
• component_name::AbstractString: the name of the target component
• name::Union{String, Nothing} = nothing: the name of the selector; if not provided, one will be constructed automatically

Examples

sel1 = make_selector(ThermalStandard, "322_CT_6")
sel2 = make_selector(ThermalStandard, "322_CT_6"; name = "my_selector")

See also: make_selector unified function documentation

make_selector(
    component_type::Type{<:InfrastructureSystems.InfrastructureSystemsComponent};
    groupby,
    name
) -> InfrastructureSystems.TypeComponentSelector

Make a ComponentSelector from a type of component. Optionally provide a grouping behavior and/or name for the selector. Selectors constructed this way point to all the components of the given type, grouped by the groupby argument (see the base make_selector documentation).

Arguments

• component_type::Type{<:InfrastructureSystemsComponent}: the type of component to select
• groupby::Union{Symbol, Function} = :each: the grouping behavior (see the base make_selector documentation)
• name::Union{String, Nothing} = nothing: the name of the selector; if not provided, one will be constructed automatically

Examples

sel1 = make_selector(RenewableDispatch)
sel2 = make_selector(RenewableDispatch; groupby = :all)
sel3 = make_selector(RenewableDispatch; name = "my_selector")

See also: make_selector unified function documentation

make_selector(
    content::ComponentSelector...;
    name
) -> InfrastructureSystems.ListComponentSelector

Make a ComponentSelector from several existing ComponentSelectors. Optionally provide a name for the selector. Selectors constructed this way contain one group for each of the selectors they were constructed with.

Arguments

• content::ComponentSelector...: the list of selectors that should form the groups
• name::Union{String, Nothing} = nothing: the name of the selector; if not provided, one will be constructed automatically

Examples

sel1 = make_selector(make_selector(ThermalStandard), make_selector(RenewableDispatch))
sel2 = make_selector(make_selector(ThermalStandard), make_selector(RenewableDispatch); name = "my_selector")

See also: make_selector unified function documentation

rebuild_selector(
    selector::InfrastructureSystems.ListComponentSelector;
    name,
    groupby
) -> InfrastructureSystems.ListComponentSelector

Returns a ComponentSelector functionally identical to the input selector except with the changes to its fields specified in the keyword arguments. It is not guaranteed that the result will have the same concrete type.

Examples

Suppose you have a selector with manual groups and you want to group by :each:

sel = make_selector(make_selector(ThermalStandard), make_selector(RenewableDispatch))
sel_each = rebuild_selector(sel; groupby = :each)  # will be a RegroupedComponentSelector

rebuild_selector(
    selector::ComponentSelector;
    name
) -> InfrastructureSystems.ListComponentSelector

Returns a ComponentSelector functionally identical to the input selector except with the changes to its fields specified in the keyword arguments.

Examples

Suppose you have a selector with name = "my_name. If you instead wanted name = "your_name:

sel = make_selector(ThermalStandard, "322_CT_6"; name = "my_name")
sel_yours = rebuild_selector(sel; name = "your_name")

rebuild_selector(
    selector::DynamicallyGroupedComponentSelector;
    name,
    groupby
) -> Any

Returns a ComponentSelector functionally identical to the input selector except with the changes to its fields specified in the keyword arguments.

Examples

Suppose you have a selector with groupby = :all. If you instead wanted groupby = :each:

sel = make_selector(ThermalStandard; groupby = :all)
sel_each = rebuild_selector(sel; groupby = :each)

get_available_component(
    selector::SingularComponentSelector,
    sys::System
) -> Union{Nothing, InfrastructureSystems.InfrastructureSystemsComponent}

Like get_component but only operates on components for which get_available is true.

get_available_component(
    scope_limiter::Union{Nothing, Function},
    selector::SingularComponentSelector,
    sys::System
) -> Union{Nothing, InfrastructureSystems.InfrastructureSystemsComponent}

Like get_component but only operates on components for which get_available is true.

get_available_components(
    selector::ComponentSelector,
    sys::System
) -> Any

Like get_components but only operates on components for which get_available is true.

get_available_components(
    scope_limiter::Union{Nothing, Function},
    selector::ComponentSelector,
    sys::System
) -> Any

Like get_components but only operates on components for which get_available is true.

get_available_groups(
    selector::ComponentSelector,
    sys::System
) -> Any

Like get_groups but only operates on components for which get_available is true.

get_available_groups(
    scope_limiter::Union{Nothing, Function},
    selector::ComponentSelector,
    sys::System
) -> Any

Like get_groups but only operates on components for which get_available is true.

get_component(
    selector::SingularComponentSelector,
    sys::System
) -> Union{Nothing, InfrastructureSystems.InfrastructureSystemsComponent}

Get the component of the System that makes up the SingularComponentSelector; nothing if there is none.

Arguments

• selector::SingularComponentSelector: the SingularComponentSelector whose component to retrieve
• sys::System: the system from which to draw components

get_component(
    scope_limiter::Union{Nothing, Function},
    selector::SingularComponentSelector,
    sys::System
) -> Union{Nothing, InfrastructureSystems.InfrastructureSystemsComponent}

Get the component of the System that makes up the SingularComponentSelector; nothing if there is none. Optionally specify a filter function scope_limiter as the first argument to limit the components that should be considered.

Arguments

• scope_limiter::Union{Function, Nothing}: see ComponentSelector
• selector::SingularComponentSelector: the SingularComponentSelector whose component to retrieve
• sys::System: the system from which to draw components

get_components(
    selector::ComponentSelector,
    sys::System
) -> Any

Get the components of the System that make up the ComponentSelector.

Arguments

• selector::ComponentSelector: the ComponentSelector whose components to retrieve
• sys::System: the system from which to draw components

get_components(
    scope_limiter::Union{Nothing, Function},
    selector::ComponentSelector,
    sys::System
) -> Any

Get the components of the System that make up the ComponentSelector. Optionally specify a filter function scope_limiter as the first argument to limit the components that should be considered.

Arguments

• scope_limiter::Union{Function, Nothing}: see ComponentSelector
• selector::ComponentSelector: the ComponentSelector whose components to retrieve
• sys::System: the system from which to draw components

get_groups(selector::ComponentSelector, sys::System) -> Any

Get the groups that make up the ComponentSelector.

Arguments

• selector::ComponentSelector: the ComponentSelector whose groups to retrieve
• sys::System: the system from which to draw components

get_groups(
    scope_limiter::Union{Nothing, Function},
    selector::ComponentSelector,
    sys::System
) -> Any

Get the groups that make up the ComponentSelector. Optionally specify a filter function scope_limiter as the first argument to limit the components that should be considered.

Arguments

• scope_limiter::Union{Function, Nothing}: see ComponentSelector
• selector::ComponentSelector: the ComponentSelector whose groups to retrieve
• sys::System: the system from which to draw components

PluralComponentSelectors whose grouping is determined by a groupby field. The semantics of this field are described at make_selector.

ComponentSelector subtype that may refer to multiple components.

ComponentSelector subtype that can only refer to zero or one components. get_components will always return zero or one components; get_component will return the component directly if there is one and return nothing if there is not.

component_to_qualified_string(
    component_type::Type{<:InfrastructureSystems.InfrastructureSystemsComponent},
    component_name::AbstractString
) -> Any

Canonical way to turn an InfrastructureSystemsComponent specification/instance into a unique-per-system string.

subtype_to_string(
    subtype::Type{<:InfrastructureSystems.InfrastructureSystemsComponent}
) -> String

Canonical way to turn an InfrastructureSystemsComponent subtype into a unique string.

get_active_power_limits(
    _::Device
) -> @NamedTuple{min::Float64, max::Float64}

Generic fallback function for getting active power limits. Throws ArgumentError for devices that don't implement this function.

get_aggregation_topology_accessor(
    _::Type{Area}
) -> typeof(get_area)

Return the appropriate accessor function for the given aggregation topology type. For Area types, returns get_area; for LoadZone types, returns get_load_zone.

get_aggregation_topology_accessor(
    _::Type{LoadZone}
) -> typeof(get_load_zone)

Return the appropriate accessor function for the given aggregation topology type. For Area types, returns get_area; for LoadZone types, returns get_load_zone.

get_from_to_flow_limit(a::AreaInterchange) -> Float64

Get the flow limits from source Area to destination Area for an AreaInterchange.

get_max_active_power(d::StaticInjection) -> Float64

Return the max active power for a device as the max field in the named tuple returned by get_active_power_limits.

get_max_active_power(
    d::Union{InterruptibleStandardLoad, StandardLoad}
) -> Float64

Calculate the maximum active power for a StandardLoad or InterruptibleStandardLoad by summing the maximum constant, impedance, and current components assuming a 1.0 voltage magnitude at the bus.

get_max_active_power_flow_limit(
    tx::TransmissionInterface
) -> Float64

Get the maximum active power flow limit for a TransmissionInterface.

get_max_reactive_power(d::RenewableDispatch) -> Float64

Return the max reactive power for a RenewableDispatch generator calculated as the rating * power_factor if the field reactive_power_limits is nothing

get_max_reactive_power(d::StaticInjection) -> Float64

Return the max reactive power for a device as the max field in the named tuple returned by get_reactive_power_limits.

get_min_active_power_flow_limit(
    tx::TransmissionInterface
) -> Float64

Get the minimum active power flow limit for a TransmissionInterface.

get_power_factor(_::Device) -> Float64

Generic fallback function for getting power factor. Throws ArgumentError for devices that don't implement this function.

get_rating(_::Device) -> Union{Nothing, Float64}

Generic fallback function for getting device rating. Throws ArgumentError for devices that don't implement this function.

get_reactive_power_limits(
    _::Device
) -> Union{Nothing, @NamedTuple{min::Float64, max::Float64}}

Generic fallback function for getting reactive power limits. Throws ArgumentError for devices that don't implement this function.

get_to_from_flow_limit(a::AreaInterchange) -> Float64

Get the flow limits from destination Area to source Area for an AreaInterchange.

get_α(t::Union{TapTransformer, Transformer2W}) -> Float64

Calculate the phase shift angle α for a TapTransformer or Transformer2W based on its winding group number. Returns the angle in radians, calculated as -(π/6) * winding_group_number. If the winding_group_number is WindingGroupNumber.UNDEFINED, returns 0.0 and issues a warning.

get_α_primary(t::Transformer3W) -> Float64

Calculate the phase shift angle α for the primary winding of a Transformer3W based on its primary winding group number. Returns the angle in radians, calculated as -(π/6) * primary_group_number. If primary_group_number is WindingGroupNumber.UNDEFINED, returns 0.0 and issues a warning.

get_α_secondary(t::Transformer3W) -> Float64

Calculate the phase shift angle α for the secondary winding of a Transformer3W based on its secondary winding group number. Returns the angle in radians, calculated as -(π/6) * secondary_group_number. If secondary_group_number is WindingGroupNumber.UNDEFINED, returns 0.0 and issues a warning.

get_α_tertiary(t::Transformer3W) -> Float64

Calculate the phase shift angle α for the tertiary winding of a Transformer3W based on its tertiary winding group number. Returns the angle in radians, calculated as -(π/6) * tertiary_group_number. If tertiary_group_number is WindingGroupNumber.UNDEFINED, returns 0.0 and issues a warning.

set_area!(bus::ACBus, area::Area) -> Area

Set the Area for an ACBus.

set_load_zone!(bus::ACBus, load_zone::LoadZone) -> LoadZone

Set the LoadZone for an ACBus.

TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to
) -> TwoTerminalGenericHVDCLine
TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to,
    loss
) -> TwoTerminalGenericHVDCLine
TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to,
    loss,
    services
) -> TwoTerminalGenericHVDCLine
TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to,
    loss,
    services,
    ext
) -> TwoTerminalGenericHVDCLine

Deprecated method for the old TwoTerminalHVDCLine that returns the new TwoTerminalGenericHVDCLine. This constructor is used for some backward compatibility and will be removed in a future version.

TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to,
    loss::Union{LinearCurve, PiecewiseIncrementalCurve}
) -> TwoTerminalGenericHVDCLine
TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to,
    loss::Union{LinearCurve, PiecewiseIncrementalCurve},
    services
) -> TwoTerminalGenericHVDCLine
TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to,
    loss::Union{LinearCurve, PiecewiseIncrementalCurve},
    services,
    ext
) -> TwoTerminalGenericHVDCLine

Deprecated method for the old TwoTerminalHVDCLine that returns the new TwoTerminalGenericHVDCLine. This constructor is used for some backward compatibility and will be removed in a future version.

TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to,
    loss::@NamedTuple{l0::Float64, l1::Float64}
) -> TwoTerminalGenericHVDCLine
TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to,
    loss::@NamedTuple{l0::Float64, l1::Float64},
    services
) -> TwoTerminalGenericHVDCLine
TwoTerminalHVDCLine(
    name,
    available,
    active_power_flow,
    arc,
    active_power_limits_from,
    active_power_limits_to,
    reactive_power_limits_from,
    reactive_power_limits_to,
    loss::@NamedTuple{l0::Float64, l1::Float64},
    services,
    ext
) -> TwoTerminalGenericHVDCLine

Deprecated method for the old TwoTerminalHVDCLine that returns the new TwoTerminalGenericHVDCLine. This constructor is used for some backward compatibility and will be removed in a future version.