API Reference

   

Device Models

List of structures and methods for Device models

PowerSimulations.DeviceModelType
DeviceModel(
    ::Type{D},
    ::Type{B},
    feedforwards::Vector{<:AbstractAffectFeedforward}
    use_slacks::Bool,
    duals::Vector{DataType},
    services::Vector{ServiceModel}
    attributes::Dict{String, Any}
)

Establishes the model for a particular device specified by type. Uses the keyword argument feedforward to enable passing values between operation model at simulation time

Arguments

  • ::Type{D} where D<:PSY.Device: Power System Device Type
  • ::Type{B} where B<:AbstractDeviceFormulation: Abstract Device Formulation
  • feedforward::Array{<:AbstractAffectFeedforward} = Vector{AbstractAffectFeedforward}() : use to pass parameters between models
  • use_slacks::Bool = false : Add slacks to the device model. Implementation is model dependent and not all models feature slacks
  • duals::Vector{DataType} = Vector{DataType}(): use to pass constraint type to calculate the duals. The DataType needs to be a valid ConstraintType
  • time_series_names::Dict{Type{<:TimeSeriesParameter}, String} = get_default_time_series_names(D, B) : use to specify time series names associated to the device`
  • attributes::Dict{String, Any} = get_default_attributes(D, B) : use to specify attributes to the device

Example

thermal_gens = DeviceModel(ThermalStandard, ThermalBasicUnitCommitment)
source

Formulations

Refer to the Formulations Page for each Abstract Device Formulation.

Problem Templates

PowerSimulations.ProblemTemplateType
ProblemTemplate(::Type{T}) where {T<:PM.AbstractPowerFormulation}

Creates a model reference of the PowerSimulations Optimization Problem.

Arguments

  • model::Type{T<:PM.AbstractPowerFormulation}:

Example

template = ProblemTemplate(CopperPlatePowerModel)

source
PowerSimulations.set_device_model!Method
set_device_model!(
    template::ProblemTemplate,
    component_type::Type{<:Device},
    formulation::Type{<:PowerSimulations.AbstractDeviceFormulation}
)

Sets the device model in a template using the component type and formulation. Builds a default DeviceModel

source
PowerSimulations.set_service_model!Method
set_service_model!(
    template::ProblemTemplate,
    service_name::String,
    service_type::Type{<:Service},
    formulation::Type{<:PowerSimulations.AbstractServiceFormulation}
)

Sets the service model in a template using a name and the service type and formulation. Builds a default ServiceModel with useservicename set to true.

source
PowerSimulations.set_service_model!Method
set_service_model!(
    template::ProblemTemplate,
    service_type::Type{<:Service},
    formulation::Type{<:PowerSimulations.AbstractServiceFormulation}
)

Sets the service model in a template using a ServiceModel instance.

source
PowerSimulations.template_economic_dispatchMethod
template_economic_dispatch(; kwargs...) -> ProblemTemplate
template_economic_dispatch(; kwargs...)

Creates a ProblemTemplate with default DeviceModels for an Economic Dispatch problem.

Example

template = templateeconomicdispatch()


# Accepted Key Words
- `network::Type{<:PM.AbstractPowerModel}` : override default network model settings
- `devices::Vector{DeviceModel}` : override default `DeviceModel` settings
- `services::Vector{ServiceModel}` : override default `ServiceModel` settings
source
PowerSimulations.template_unit_commitmentMethod
template_unit_commitment(; kwargs...) -> ProblemTemplate
template_unit_commitment(; kwargs...)

Creates a ProblemTemplate with default DeviceModels for a Unit Commitment problem.

Example

template = templateunitcommitment()


# Accepted Key Words
- `network::Type{<:PM.AbstractPowerModel}` : override default network model settings
- `devices::Vector{DeviceModel}` : override default `DeviceModel` settings
- `services::Vector{ServiceModel}` : override default `ServiceModel` settings
source
   

Decision Models

PowerSimulations.DecisionModelMethod
DecisionModel(
    directory::AbstractString,
    optimizer::MathOptInterface.OptimizerWithAttributes;
    jump_model,
    system
) -> Any

Construct an DecisionProblem from a serialized file.

Arguments

  • directory::AbstractString: Directory containing a serialized model
  • jump_model::Union{Nothing, JuMP.Model} = nothing: The JuMP model does not get serialized. Callers should pass whatever they passed to the original problem.
  • optimizer::Union{Nothing,MOI.OptimizerWithAttributes} = nothing: The optimizer does not get serialized. Callers should pass whatever they passed to the original problem.
  • system::Union{Nothing, PSY.System}: Optionally, the system used for the model. If nothing and systofile was set to true when the model was created, the system will be deserialized from a file.
source
PowerSimulations.DecisionModelMethod
DecisionModel{M}(
    template::AbstractProblemTemplate,
    sys::PSY.System,
    jump_model::Union{Nothing, JuMP.Model}=nothing;
    kwargs...) where {M<:DecisionProblem}

Build the optimization problem of type M with the specific system and template.

Arguments

  • ::Type{M} where M<:DecisionProblem: The abstract operation model type
  • template::AbstractProblemTemplate: The model reference made up of transmission, devices, branches, and services.
  • sys::PSY.System: the system created using Power Systems
  • jump_model::Union{Nothing, JuMP.Model}: Enables passing a custom JuMP model. Use with care
  • name = nothing: name of model, string or symbol; defaults to the type of template converted to a symbol.
  • optimizer::Union{Nothing,MOI.OptimizerWithAttributes} = nothing : The optimizer does not get serialized. Callers should pass whatever they passed to the original problem.
  • horizon::Dates.Period = UNSET_HORIZON: Manually specify the length of the forecast Horizon
  • resolution::Dates.Period = UNSET_RESOLUTION: Manually specify the model's resolution
  • warm_start::Bool = true: True will use the current operation point in the system to initialize variable values. False initializes all variables to zero. Default is true
  • system_to_file::Bool = true:: True to create a copy of the system used in the model.
  • initialize_model::Bool = true: Option to decide to initialize the model or not.
  • initialization_file::String = "": This allows to pass pre-existing initialization values to avoid the solution of an optimization problem to find feasible initial conditions.
  • deserialize_initial_conditions::Bool = false: Option to deserialize conditions
  • export_pwl_vars::Bool = false: True to export all the pwl intermediate variables. It can slow down significantly the build and solve time.
  • allow_fails::Bool = false: True to allow the simulation to continue even if the optimization step fails. Use with care.
  • optimizer_solve_log_print::Bool = false: Uses JuMP.unset_silent() to print the optimizer's log. By default all solvers are set to MOI.Silent()
  • detailed_optimizer_stats::Bool = false: True to save detailed optimizer stats log.
  • calculate_conflict::Bool = false: True to use solver to calculate conflicts for infeasible problems. Only specific solvers are able to calculate conflicts.
  • direct_mode_optimizer::Bool = false: True to use the solver in direct mode. Creates a JuMP.direct_model.
  • store_variable_names::Bool = false: to store variable names in optimization model. Decreases the build times.
  • rebuild_model::Bool = false: It will force the rebuild of the underlying JuMP model with each call to update the model. It increases solution times, use only if the model can't be updated in memory.
  • initial_time::Dates.DateTime = UNSET_INI_TIME: Initial Time for the model solve.
  • time_series_cache_size::Int = IS.TIME_SERIES_CACHE_SIZE_BYTES: Size in bytes to cache for each time array. Default is 1 MiB. Set to 0 to disable.

Example

template = ProblemTemplate(CopperPlatePowerModel, devices, branches, services)
OpModel = DecisionModel(MockOperationProblem, template, system)
source
PowerSimulations.DecisionModelMethod
DecisionModel(
    ::Type{M<:PowerSimulations.DecisionProblem},
    template::PowerSimulations.AbstractProblemTemplate,
    sys::System;
    ...
) -> DecisionModel
DecisionModel(
    ::Type{M<:PowerSimulations.DecisionProblem},
    template::PowerSimulations.AbstractProblemTemplate,
    sys::System,
    jump_model::Union{Nothing, JuMP.Model};
    kwargs...
) -> DecisionModel

Build the optimization problem of type M with the specific system and template

Arguments

  • ::Type{M} where M<:DecisionProblem: The abstract operation model type
  • template::AbstractProblemTemplate: The model reference made up of transmission, devices, branches, and services.
  • sys::PSY.System: the system created using Power Systems
  • jump_model::Union{Nothing, JuMP.Model} = nothing: Enables passing a custom JuMP model. Use with care.

Example

template = ProblemTemplate(CopperPlatePowerModel, devices, branches, services)
problem = DecisionModel(MyOpProblemType, template, system, optimizer)
source
PowerSimulations.DecisionModelMethod

Builds an empty decision model. This constructor is used for the implementation of custom decision models that do not require a template.

Arguments

  • ::Type{M} where M<:DecisionProblem: The abstract operation model type
  • sys::PSY.System: the system created using Power Systems
  • jump_model::Union{Nothing, JuMP.Model} = nothing: Enables passing a custom JuMP model. Use with care.

Example

problem = DecisionModel(system, optimizer)
source
PowerSimulations.build!Method
build!(
    model::DecisionModel;
    output_dir,
    recorders,
    console_level,
    file_level,
    disable_timer_outputs
)

Build the Decision Model based on the specified DecisionProblem.

Arguments

  • model::DecisionModel{<:DecisionProblem}: DecisionModel object
  • output_dir::String: Output directory for results
  • recorders::Vector{Symbol} = []: recorder names to register
  • console_level = Logging.Error:
  • file_level = Logging.Info:
  • disable_timer_outputs = false : Enable/Disable timing outputs
source
PowerSimulations.solve!Method
solve!(
    model::DecisionModel;
    export_problem_results,
    console_level,
    file_level,
    disable_timer_outputs,
    export_optimization_problem,
    kwargs...
) -> InfrastructureSystems.Simulation.RunStatusModule.RunStatus

Default solve method for models that conform to the requirements of DecisionModel{<: DecisionProblem}.

This will call build! on the model if it is not already built. It will forward all keyword arguments to that function.

Arguments

  • model::OperationModel = model: operation model
  • export_problem_results::Bool = false: If true, export OptimizationProblemResults DataFrames to CSV files. Reduces solution times during simulation.
  • console_level = Logging.Error:
  • file_level = Logging.Info:
  • disable_timer_outputs = false : Enable/Disable timing outputs
  • export_optimization_problem::Bool = true: If true, serialize the model to a file to allow re-execution later.

Examples

results = solve!(OpModel)
results = solve!(OpModel, export_problem_results = true)
source
PowerSimulations.solve!Method
solve!(
    step::Int64,
    model::DecisionModel,
    start_time::Dates.DateTime,
    store::PowerSimulations.SimulationStore;
    exports
) -> InfrastructureSystems.Simulation.RunStatusModule.RunStatus

Default solve method for a DecisionModel used inside of a Simulation. Solves problems that conform to the requirements of DecisionModel{<: DecisionProblem}

Arguments

  • step::Int: Simulation Step
  • model::OperationModel: operation model
  • start_time::Dates.DateTime: Initial Time of the simulation step in Simulation time.
  • store::SimulationStore: Simulation output store

Accepted Key Words

  • exports: realtime export of output. Use wisely, it can have negative impacts in the simulation times
source
   

Emulation Models

PowerSimulations.EmulationModelType
EmulationModel{M}(
    template::AbstractProblemTemplate,
    sys::PSY.System,
    jump_model::Union{Nothing, JuMP.Model}=nothing;
    kwargs...) where {M<:EmulationProblem}

Build the optimization problem of type M with the specific system and template.

Arguments

  • ::Type{M} where M<:EmulationProblem: The abstract Emulation model type
  • template::AbstractProblemTemplate: The model reference made up of transmission, devices, branches, and services.
  • sys::PSY.System: the system created using Power Systems
  • jump_model::Union{Nothing, JuMP.Model}: Enables passing a custom JuMP model. Use with care
  • name = nothing: name of model, string or symbol; defaults to the type of template converted to a symbol.
  • optimizer::Union{Nothing,MOI.OptimizerWithAttributes} = nothing : The optimizer does not get serialized. Callers should pass whatever they passed to the original problem.
  • warm_start::Bool = true: True will use the current operation point in the system to initialize variable values. False initializes all variables to zero. Default is true
  • system_to_file::Bool = true:: True to create a copy of the system used in the model.
  • initialize_model::Bool = true: Option to decide to initialize the model or not.
  • initialization_file::String = "": This allows to pass pre-existing initialization values to avoid the solution of an optimization problem to find feasible initial conditions.
  • deserialize_initial_conditions::Bool = false: Option to deserialize conditions
  • export_pwl_vars::Bool = false: True to export all the pwl intermediate variables. It can slow down significantly the build and solve time.
  • allow_fails::Bool = false: True to allow the simulation to continue even if the optimization step fails. Use with care.
  • calculate_conflict::Bool = false: True to use solver to calculate conflicts for infeasible problems. Only specific solvers are able to calculate conflicts.
  • optimizer_solve_log_print::Bool = false: Uses JuMP.unset_silent() to print the optimizer's log. By default all solvers are set to MOI.Silent()
  • detailed_optimizer_stats::Bool = false: True to save detailed optimizer stats log.
  • direct_mode_optimizer::Bool = false: True to use the solver in direct mode. Creates a JuMP.direct_model.
  • store_variable_names::Bool = false: True to store variable names in optimization model.
  • rebuild_model::Bool = false: It will force the rebuild of the underlying JuMP model with each call to update the model. It increases solution times, use only if the model can't be updated in memory.
  • initial_time::Dates.DateTime = UNSET_INI_TIME: Initial Time for the model solve.
  • time_series_cache_size::Int = IS.TIME_SERIES_CACHE_SIZE_BYTES: Size in bytes to cache for each time array. Default is 1 MiB. Set to 0 to disable.

Example

template = ProblemTemplate(CopperPlatePowerModel, devices, branches, services)
OpModel = EmulationModel(MockEmulationProblem, template, system)
source
PowerSimulations.EmulationModelMethod
EmulationModel(
    ::Type{M<:PowerSimulations.EmulationProblem},
    template::PowerSimulations.AbstractProblemTemplate,
    sys::System;
    ...
) -> EmulationModel
EmulationModel(
    ::Type{M<:PowerSimulations.EmulationProblem},
    template::PowerSimulations.AbstractProblemTemplate,
    sys::System,
    jump_model::Union{Nothing, JuMP.Model};
    kwargs...
) -> EmulationModel

Build the optimization problem of type M with the specific system and template

Arguments

  • ::Type{M} where M<:EmulationProblem: The abstract Emulation model type
  • template::AbstractProblemTemplate: The model reference made up of transmission, devices, branches, and services.
  • sys::PSY.System: the system created using Power Systems
  • jump_model::Union{Nothing, JuMP.Model}: Enables passing a custom JuMP model. Use with care

Example

template = ProblemTemplate(CopperPlatePowerModel, devices, branches, services)
problem = EmulationModel(MyEmProblemType, template, system, optimizer)
source
PowerSimulations.EmulationModelMethod
EmulationModel(
    directory::AbstractString,
    optimizer::MathOptInterface.OptimizerWithAttributes;
    jump_model,
    system,
    kwargs...
) -> Any

Construct an EmulationProblem from a serialized file.

Arguments

  • directory::AbstractString: Directory containing a serialized model.
  • optimizer::MOI.OptimizerWithAttributes: The optimizer does not get serialized. Callers should pass whatever they passed to the original problem.
  • jump_model::Union{Nothing, JuMP.Model} = nothing: The JuMP model does not get serialized. Callers should pass whatever they passed to the original problem.
  • system::Union{Nothing, PSY.System}: Optionally, the system used for the model. If nothing and systofile was set to true when the model was created, the system will be deserialized from a file.
source
PowerSimulations.build!Method
build!(
    model::EmulationModel;
    executions,
    output_dir,
    recorders,
    console_level,
    file_level,
    disable_timer_outputs
)

Implementation of build for any EmulationProblem

source
PowerSimulations.run!Method
run!(
    model::EmulationModel;
    export_problem_results,
    console_level,
    file_level,
    disable_timer_outputs,
    export_optimization_model,
    kwargs...
) -> InfrastructureSystems.Simulation.RunStatusModule.RunStatus

Default run method for problems that conform to the requirements of EmulationModel{<: EmulationProblem}

This will call build! on the model if it is not already built. It will forward all keyword arguments to that function.

Arguments

  • model::EmulationModel = model: Emulation model
  • optimizer::MOI.OptimizerWithAttributes: The optimizer that is used to solve the model
  • executions::Int: Number of executions for the emulator run
  • export_problem_results::Bool: If true, export OptimizationProblemResults DataFrames to CSV files.
  • output_dir::String: Required if the model is not already built, otherwise ignored
  • enable_progress_bar::Bool: Enables/Disable progress bar printing
  • export_optimization_model::Bool: If true, serialize the model to a file to allow re-execution later.

Examples

status = run!(model; optimizer = GLPK.Optimizer, executions = 10)
status = run!(model; output_dir = ./model_output, optimizer = GLPK.Optimizer, executions = 10)
source
PowerSimulations.solve!Method
solve!(
    step::Int64,
    model::EmulationModel,
    start_time::Dates.DateTime,
    store::PowerSimulations.SimulationStore;
    exports
) -> InfrastructureSystems.Simulation.RunStatusModule.RunStatus

Default solve method for an EmulationModel used inside of a Simulation. Solves problems that conform to the requirements of DecisionModel{<: DecisionProblem}

Arguments

  • step::Int: Simulation Step
  • model::OperationModel: operation model
  • start_time::Dates.DateTime: Initial Time of the simulation step in Simulation time.
  • store::SimulationStore: Simulation output store
  • exports = nothing: realtime export of output. Use wisely, it can have negative impacts in the simulation times
source
   

Service Models

List of structures and methods for Service models

PowerSimulations.ServiceModelType

Establishes the model for a particular services specified by type. Uses the keyword argument use_service_name to assign the model to a service with the same name as the name in the template. Uses the keyword argument feedforward to enable passing values between operation model at simulation time

Arguments

-::Type{D}: Power System Service Type -::Type{B}: Abstract Service Formulation

Accepted Key Words

  • feedforward::Array{<:AbstractAffectFeedforward} : use to pass parameters between models
  • use_service_name::Bool : use the name as the name for the service

Example

reserves = ServiceModel(PSY.VariableReserve{PSY.ReserveUp}, RangeReserve)

source
   

Simulation Models

Refer to the Simulations Page to explanations on how to setup a Simulation, with Sequencing and Feedforwards.

PowerSimulations.SimulationModelsType
SimulationModels(
    decision_models::Vector{<:DecisionModel},
    emulation_models::Union{Nothing, EmulationModel}
)

Stores the OperationProblem definitions to be used in the simulation. When creating the SimulationModels, the order in which the models are created determines the order on which the simulation is executed.

Arguments

  • decision_models::Vector{<:DecisionModel}: Vector of decision models.
  • emulation_models::Union{Nothing, EmulationModel}: Optional argument to include

an EmulationModel in the Simulation

Example

template_uc = template_unit_commitment()
template_ed = template_economic_dispatch()
my_decision_model_uc = DecisionModel(template_1, sys_uc, optimizer, name = "UC")
my_decision_model_ed = DecisionModel(template_ed, sys_ed, optimizer, name = "ED")
models = SimulationModels(
    decision_models = [
        my_decision_model_uc,
        my_decision_model_ed
    ]
)
source
PowerSimulations.SimulationSequenceType
SimulationSequence(
    models::SimulationModels,
    feedforward::Dict{String, Vector{<:AbstractAffectFeedforward}}
    ini_cond_chronology::InitialConditionChronology
)

Construct the simulation sequence between decision and emulation models.

Arguments

  • models::SimulationModels: Vector of decisions and emulation models.
  • feedforward = Dict{String, Vector{<:AbstractAffectFeedforward}}(): Optional dictionary to specify how information and variables are exchanged between decision and emulation models.
  • ini_cond_chronology::InitialConditionChronology = InterProblemChronology(): Define information sharing model between stages with InterProblemChronology

Example

template_uc = template_unit_commitment()
template_ed = template_economic_dispatch()
my_decision_model_uc = DecisionModel(template_1, sys_uc, optimizer, name = "UC")
my_decision_model_ed = DecisionModel(template_ed, sys_ed, optimizer, name = "ED")
models = SimulationModels(
    decision_models = [
        my_decision_model_uc,
        my_decision_model_ed
    ]
)
# The following sequence set the commitment variables (`OnVariable`) for `ThermalStandard` units from UC to ED.
sequence = SimulationSequence(;
    models = models,
    feedforwards = Dict(
        "ED" => [
            SemiContinuousFeedforward(;
                component_type = ThermalStandard,
                source = OnVariable,
                affected_values = [ActivePowerVariable],
            ),
        ],
    ),
)
source
PowerSimulations.SimulationType
Simulation(
    sequence::SimulationSequence,
    name::String,
    steps::Int
    models::SimulationModels,
    simulation_folder::String,
    initial_time::Union{Nothing, Dates.DateTime}
)

Construct the Simulation structure to run the sequence of decision and emulation models specified.

Arguments

  • sequence::SimulationSequence: Simulation sequence that specify how the decision and emulation models will be executed.
  • name::String: Name of the Simulation
  • steps::Int: Number of steps on which the sequence of models will be executed
  • models::SimulationModels: List of Decision and Emulation Models
  • simulation_folder::String: Folder on which results will be stored
  • initial_time::Union{Nothing, Dates.DateTime} = nothing: Initial time of which the simulation starts. If nothing it will default to the first timestamp of time series of the system.

Example

template_uc = template_unit_commitment()
template_ed = template_economic_dispatch()
my_decision_model_uc = DecisionModel(template_1, sys_uc, optimizer, name = "UC")
my_decision_model_ed = DecisionModel(template_ed, sys_ed, optimizer, name = "ED")
models = SimulationModels(
    decision_models = [
        my_decision_model_uc,
        my_decision_model_ed
    ]
)
# The following sequence set the commitment variables (`OnVariable`) for `ThermalStandard` units from UC to ED.
sequence = SimulationSequence(;
    models = models,
    feedforwards = Dict(
        "ED" => [
            SemiContinuousFeedforward(;
                component_type = ThermalStandard,
                source = OnVariable,
                affected_values = [ActivePowerVariable],
            ),
        ],
    ),
)

sim = Simulation(
    sequence = sequence,
    name = "Sim",
    steps = 5,
    models = models,
    simulation_folder = mktempdir(cleanup=true),
)
source
PowerSimulations.SimulationMethod
Simulation(directory::AbstractString, model_info::Dict)

Constructs Simulation from a serialized directory. Callers should pass any kwargs here that they passed to the original Simulation.

Arguments

  • directory::AbstractString: the directory returned from the call to serialize
  • model_info::Dict: Two-level dictionary containing model parameters that cannot be serialized. The outer dict should be keyed by the problem name. The inner dict must contain 'optimizer' and may contain 'jump_model'. These should be the same values used for the original simulation.
source
PowerSimulations.build!Method
build!(
    sim::Simulation;
    recorders,
    console_level,
    file_level,
    serialize,
    partitions,
    index
) -> InfrastructureSystems.Simulation.SimulationBuildStatusModule.SimulationBuildStatus

Build the Simulation, problems and the related folder structure.

Arguments

  • sim::Simulation: simulation object
  • recorders::Vector{Symbol} = []: recorder names to register
  • serialize::Bool = true: serializes the simulation objects in the simulation
  • console_level = Logging.Error:
  • file_level = Logging.Info:
source
PowerSimulations.execute!Method
execute!(
    sim::Simulation;
    kwargs...
) -> InfrastructureSystems.Simulation.RunStatusModule.RunStatus

Solves the simulation model for sequential Simulations.

Arguments

  • sim::Simulation=sim: simulation object created by Simulation()

The optional keyword argument exports controls exporting of results to CSV files as the simulation runs.

Example

sim = Simulation("Test", 7, problems, "/Users/folder")
execute!(sim::Simulation; kwargs...)
source
PowerSimulations.run_parallel_simulationMethod
run_parallel_simulation(
    build_function,
    execute_function;
    script,
    output_dir,
    name,
    num_steps,
    period,
    num_overlap_steps,
    num_parallel_processes,
    exeflags,
    force
)

Run a partitioned simulation in parallel on a local computer.

Arguments

  • build_function: Function reference that returns a built Simulation.
  • execute_function: Function reference that executes a Simulation.
  • script::AbstractString: Path to script that includes $build_function$ and $execute_function$.
  • output_dir::AbstractString: Path for simulation outputs
  • name::AbstractString: Simulation name
  • num_steps::Integer: Total number of steps in the simulation
  • period::Integer: Number of steps in each simulation partition
  • num_overlap_steps::Integer: Number of steps that each partition overlaps with the previous partition
  • num_parallel_processes: Number of partitions to run in parallel. If nothing, use the number of cores.
  • exeflags: Path to Julia project. Forwarded to Distributed.addprocs.
  • force: Overwrite the output directory if it already exists.
source
   

Chronology Models

PowerSimulations.InterProblemChronologyType
InterProblemChronology()

Type struct to select an information sharing model between stages that uses results from the most recent stage executed to calculate the initial conditions. This model takes into account solutions from stages defined with finer temporal resolutions

See also: IntraProblemChronology

source
PowerSimulations.IntraProblemChronologyType
IntraProblemChronology()

Type struct to select an information sharing model between stages that uses results from the same recent stage to calculate the initial conditions. This model ignores solutions from stages defined with finer temporal resolutions.

See also: InterProblemChronology

source

Variables

For a list of variables for each device refer to its Formulations page.

Common Variables

Thermal Unit Variables

Storage Unit Variables

Branches and Network Variables

Services Variables

PowerSimulations.ReserveRequirementSlackType

Struct to dispatch the creation of Reserve requirement slack variables. Used when there is not reserves in the system to satisfy the requirement.

Docs abbreviation: $r^\text{sl}$

source

Feedforward Variables

   

Constraints

Common Constraints

Network Constraints

Power Variable Limit Constraints

PowerSimulations.ActivePowerVariableLimitsConstraintType

Struct to create the constraint to limit active power expressions. For more information check Device Formulations.

The specified constraint depends on the UpperBound and LowerBound expressions, but in its most basic formulation is of the form:

\[P^\text{min} \le p_t \le P^\text{max}, \quad \forall t \in \{1,\dots,T\}\]

source

Services Constraints

PowerSimulations.RequirementConstraintType

Struct to create the constraint for satisfying active power reserve requirements. For more information check Service Formulations.

The constraint is as follows:

\[\sum_{d\in\mathcal{D}_s} r_{d,t} + r_t^\text{sl} \ge \text{Req},\quad \forall t\in \{1,\dots, T\} \quad \text{(for a ConstantReserve)} \\ \sum_{d\in\mathcal{D}_s} r_{d,t} + r_t^\text{sl} \ge \text{RequirementTimeSeriesParameter}_{t},\quad \forall t\in \{1,\dots, T\} \quad \text{(for a VariableReserve)}\]

source
PowerSimulations.ParticipationFractionConstraintType

Struct to create the constraint to participation assignments limits in the active power reserves. For more information check Service Formulations.

The constraint is as follows:

\[r_{d,t} \le \text{Req} \cdot \text{PF} ,\quad \forall d\in \mathcal{D}_s, \forall t\in \{1,\dots, T\} \quad \text{(for a ConstantReserve)} \\ r_{d,t} \le \text{RequirementTimeSeriesParameter}_{t} \cdot \text{PF}\quad \forall d\in \mathcal{D}_s, \forall t\in \{1,\dots, T\}, \quad \text{(for a VariableReserve)}\]

source
PowerSimulations.ReservePowerConstraintType

Struct to create the constraint for ensuring that NonSpinning Reserve can be delivered from turn-off thermal units.

For more information check Service Formulations for NonSpinningReserve.

The constraint is as follows:

\[r_{d,t} \le (1 - u_{d,t}^\text{th}) \cdot R^\text{limit}_d, \quad \forall d \in \mathcal{D}_s, \forall t \in \{1,\dots, T\}\]

source

Thermal Unit Constraints

PowerSimulations.ActiveRangeICConstraintType

Struct to create the constraint for starting up ThermalMultiStart units. For more information check ThermalGen Formulations for ThermalMultiStartUnitCommitment.

The specified constraint is formulated as:

\[\max\{P^\text{th,max} - P^\text{th,shdown}, 0\} \cdot w_1^\text{th} \le u^\text{th,init} (P^\text{th,max} - P^\text{th,min}) - P^\text{th,init}\]

source
PowerSimulations.CommitmentConstraintType

Struct to create the commitment constraint between the on, start, and stop variables. For more information check ThermalGen Formulations.

The specified constraints are formulated as:

\[u_1^\text{th} = u^\text{th,init} + v_1^\text{th} - w_1^\text{th} \\ u_t^\text{th} = u_{t-1}^\text{th} + v_t^\text{th} - w_t^\text{th}, \quad \forall t \in \{2,\dots,T\} \\ v_t^\text{th} + w_t^\text{th} \le 1, \quad \forall t \in \{1,\dots,T\}\]

source
PowerSimulations.RampConstraintType

Struct to create the RampConstraint associated with a specified thermal device or reserve service.

For thermal units, see more information in Thermal Formulations. The constraint is as follows:

\[-R^\text{th,dn} \le p_t^\text{th} - p_{t-1}^\text{th} \le R^\text{th,up}, \quad \forall t\in \{1, \dots, T\}\]

For Ramp Reserve, see more information in Service Formulations. The constraint is as follows:

\[r_{d,t} \le R^\text{th,up} \cdot \text{TF}\quad \forall d\in \mathcal{D}_s, \forall t\in \{1,\dots, T\}, \quad \text{(for ReserveUp)} \\ r_{d,t} \le R^\text{th,dn} \cdot \text{TF}\quad \forall d\in \mathcal{D}_s, \forall t\in \{1,\dots, T\}, \quad \text{(for ReserveDown)}\]

source

Renewable Unit Constraints

PowerSimulations.EqualityConstraintType

Struct to create the constraint that sets the reactive power to the power factor in the RenewableConstantPowerFactor formulation for renewable units.

For more information check RenewableGen Formulations.

The specified constraint is formulated as:

\[q_t^\text{re} = \text{pf} \cdot p_t^\text{re}, \quad \forall t \in \{1,\dots, T\}\]

source

Branches Constraints

PowerSimulations.FlowLimitConstraintType

Struct to create the constraint that set the flow limits through a PhaseShiftingTransformer.

For more information check Branch Formulations.

The specified constraint is formulated as:

\[-R^\text{max} \le f_t \le R^\text{max}, \quad \forall t \in \{1,\dots,T\}\]

source
PowerSimulations.FlowRateConstraintType

Struct to create the constraint that set the flow limits through an HVDC two-terminal branch.

For more information check Branch Formulations.

The specified constraint is formulated as:

\[R^\text{min} \le f_t \le R^\text{max}, \quad \forall t \in \{1,\dots,T\}\]

source
PowerSimulations.FlowRateConstraintFromToType

Struct to create the constraint that set the flow from-to limits through an HVDC two-terminal branch.

For more information check Branch Formulations.

The specified constraint is formulated as:

\[R^\text{from,min} \le f_t^\text{from-to} \le R^\text{from,max}, \forall t \in \{1,\dots, T\}\]

source
PowerSimulations.FlowRateConstraintToFromType

Struct to create the constraint that set the flow to-from limits through an HVDC two-terminal branch.

For more information check Branch Formulations.

The specified constraint is formulated as:

\[R^\text{to,min} \le f_t^\text{to-from} \le R^\text{to,max},\quad \forall t \in \{1,\dots, T\}\]

source
PowerSimulations.HVDCPowerBalanceType

Struct to create the constraints that set the power balance across a lossy HVDC two-terminal line.

For more information check Branch Formulations.

The specified constraints are formulated as:

\[\begin{align*} & f_t^\text{to-from} - f_t^\text{from-to} \le L_1 \cdot f_t^\text{to-from} - L_0,\quad \forall t \in \{1,\dots, T\} \\ & f_t^\text{from-to} - f_t^\text{to-from} \ge L_1 \cdot f_t^\text{from-to} + L_0,\quad \forall t \in \{1,\dots, T\} \\ & f_t^\text{from-to} - f_t^\text{to-from} \ge - M^\text{big} (1 - u^\text{dir}_t),\quad \forall t \in \{1,\dots, T\} \\ & f_t^\text{to-from} - f_t^\text{from-to} \ge - M^\text{big} u^\text{dir}_t,\quad \forall t \in \{1,\dots, T\} \\ \end{align*}\]

source
PowerSimulations.NetworkFlowConstraintType

Struct to create the constraint the AC branch flows depending on the network model. For more information check Branch Formulations.

The specified constraint depends on the network model chosen. The most common application is the StaticBranch in a PTDF Network Model:

\[f_t = \sum_{i=1}^N \text{PTDF}_{i,b} \cdot \text{Bal}_{i,t}, \quad \forall t \in \{1,\dots, T\}\]

source
PowerSimulations.RateLimitConstraintType

Struct to create the constraint that set the AC flow limits through branches.

For more information check Branch Formulations.

The specified constraint is formulated as:

\[\begin{align*} & f_t - f_t^\text{sl,up} \le R^\text{max},\quad \forall t \in \{1,\dots, T\} \\ & f_t + f_t^\text{sl,lo} \ge -R^\text{max},\quad \forall t \in \{1,\dots, T\} \end{align*}\]

source
PowerSimulations.PhaseAngleControlLimitType

Struct to create the constraint that set the angle limits through a PhaseShiftingTransformer.

For more information check Branch Formulations.

The specified constraint is formulated as:

\[\Theta^\text{min} \le \theta^\text{shift}_t \le \Theta^\text{max}, \quad \forall t \in \{1,\dots,T\}\]

source

Feedforward Constraints

PowerSimulations.FeedforwardSemiContinuousConstraintType

Struct to create the constraint for semicontinuous feedforward limits.

For more information check Feedforward Formulations.

The specified constraint is formulated as:

\[\begin{align*} & \text{ActivePowerRangeExpressionUB}_t := p_t^\text{th} - \text{on}_t^\text{th}P^\text{th,max} \le 0, \quad \forall t\in \{1, \dots, T\} \\ & \text{ActivePowerRangeExpressionLB}_t := p_t^\text{th} - \text{on}_t^\text{th}P^\text{th,min} \ge 0, \quad \forall t\in \{1, \dots, T\} \end{align*}\]

source
   

Parameters

Time Series Parameters

Variable Value Parameters

Objective Function Parameters

Results

Acessing Optimization Model

PowerSimulations.get_all_constraint_indexMethod
get_all_constraint_index(
    model::PowerSimulations.OperationModel
) -> Vector{Tuple{InfrastructureSystems.Optimization.ConstraintKey, Int64, Int64}}

Each Tuple corresponds to (conname, internalindex, moi_index)

source

Accessing Problem Results

Accessing Simulation Results

PowerSimulations.SimulationResultsType
SimulationResults(
    path::AbstractString,
    name::AbstractString;
    ...
) -> SimulationResults
SimulationResults(
    path::AbstractString,
    name::AbstractString,
    execution;
    ignore_status
) -> SimulationResults

Construct SimulationResults from a simulation output directory.

Arguments

  • path::AbstractString: Simulation output directory
  • name::AbstractString: Simulation name
  • execution::AbstractString: Execution number. Default is the most recent.
  • ignore_status::Bool: If true, return results even if the simulation failed.
source
InfrastructureSystems.Optimization.export_resultsMethod
export_results(results::SimulationResults, exports)

Export results to files in the results directory.

Arguments

  • results::SimulationResults: simulation results
  • exports: SimulationResultsExport or anything that can be passed to its constructor. (such as Dict or path to JSON file)

An example JSON file demonstrating possible options is below. Note that start_time, end_time, path, and format are optional.

{
  "decision_models": [
    {
      "name": "ED",
      "variables": [
        "P__ThermalStandard",
      ],
      "parameters": [
        "all"
      ]
    },
    {
      "name": "UC",
      "variables": [
        "On__ThermalStandard"
      ],
      "parameters": [
        "all"
      ],
      "duals": [
        "all"
      ]
    }
  ],
  "start_time": "2020-01-01T04:00:00",
  "end_time": null,
  "path": null,
  "format": "csv"
}
source
InfrastructureSystems.Optimization.read_aux_variableMethod
read_aux_variable(
    res::PowerSimulations.SimulationProblemResults{PowerSimulations.DecisionModelSimulationResults},
    args...;
    initial_time,
    count,
    store
) -> SortedDict{Any, Any, Base.Order.ForwardOrdering}

Return the values for the requested auxillary variables. It keeps requests when performing multiple retrievals.

Arguments

  • args: Can be a string returned from list_aux_variable_names or args that can be splatted into a AuxVarKey.
  • initial_time::Dates.DateTime : initial of the requested results
  • count::Int: Number of results
source
InfrastructureSystems.Optimization.read_dualMethod
read_dual(
    res::PowerSimulations.SimulationProblemResults{PowerSimulations.DecisionModelSimulationResults},
    args...;
    initial_time,
    count,
    store
) -> SortedDict{Any, Any, Base.Order.ForwardOrdering}

Return the values for the requested dual. It keeps requests when performing multiple retrievals.

Arguments

  • args: Can be a string returned from list_dual_names or args that can be splatted into a ConstraintKey.
  • initial_time::Dates.DateTime : initial of the requested results
  • count::Int: Number of results
  • store::SimulationStore: a store that has been opened for reading
source
InfrastructureSystems.Optimization.read_expressionMethod
read_expression(
    res::PowerSimulations.SimulationProblemResults{PowerSimulations.DecisionModelSimulationResults},
    args...;
    initial_time,
    count,
    store
) -> SortedDict{Any, Any, Base.Order.ForwardOrdering}

Return the values for the requested auxillary variables. It keeps requests when performing multiple retrievals.

Arguments

  • args: Can be a string returned from list_expression_names or args that can be splatted into a ExpressionKey.
  • initial_time::Dates.DateTime : initial of the requested results
  • count::Int: Number of results
source
InfrastructureSystems.Optimization.read_parameterMethod
read_parameter(
    res::PowerSimulations.SimulationProblemResults{PowerSimulations.DecisionModelSimulationResults},
    args...;
    initial_time,
    count,
    store
) -> SortedDict{Any, Any, Base.Order.ForwardOrdering}

Return the values for the requested parameter. It keeps requests when performing multiple retrievals.

Arguments

  • args: Can be a string returned from list_parameter_names or args that can be splatted into a ParameterKey.
  • initial_time::Dates.DateTime : initial of the requested results
  • count::Int: Number of results
source
InfrastructureSystems.Optimization.read_variableMethod
read_variable(
    res::PowerSimulations.SimulationProblemResults{PowerSimulations.DecisionModelSimulationResults},
    args...;
    initial_time,
    count,
    store
) -> SortedDict{Any, Any, Base.Order.ForwardOrdering}

Return the values for the requested variable. It keeps requests when performing multiple retrievals.

Arguments

  • args: Can be a string returned from list_variable_names or args that can be splatted into a VariableKey.
  • initial_time::Dates.DateTime : initial of the requested results
  • count::Int: Number of results
  • store::SimulationStore: a store that has been opened for reading

Examples

read_variable(results, ActivePowerVariable, ThermalStandard)
read_variable(results, "ActivePowerVariable__ThermalStandard")
source
PowerSimulations.load_results!Method
load_results!(
    res::PowerSimulations.SimulationProblemResults{PowerSimulations.DecisionModelSimulationResults},
    count::Int64;
    initial_time,
    variables,
    duals,
    parameters,
    aux_variables,
    expressions,
    store
)

Load the simulation results into memory for repeated reads. This is useful when loading results from remote locations over network connections, when reading the same data very many times, etc. Multiple calls augment the cache according to these rules, where "variable" means "variable, expression, etc.":

  • Requests for an already cached variable at a lesser count than already cached do not decrease the count of the cached variable
  • Requests for an already cached variable at a greater count than already cached do increase the count of the cached variable
  • Requests for new variables are fulfilled without evicting existing variables

Note that count is global across all variables, so increasing the count re-reads already cached variables. For each variable, each element must be the name encoded as a string, like "ActivePowerVariable__ThermalStandard" or a Tuple with its constituent types, like (ActivePowerVariable, ThermalStandard). To clear the cache, use Base.empty!.

Arguments

  • count::Int: Number of windows to load.
  • initial_time::Dates.DateTime : Initial time of first window to load. Defaults to first.
  • aux_variables::Vector{Union{String, Tuple}}: Optional list of aux variables to load.
  • duals::Vector{Union{String, Tuple}}: Optional list of duals to load.
  • expressions::Vector{Union{String, Tuple}}: Optional list of expressions to load.
  • parameters::Vector{Union{String, Tuple}}: Optional list of parameters to load.
  • variables::Vector{Union{String, Tuple}}: Optional list of variables to load.
source
PowerSimulations.load_results!Method
load_results!(
    res::PowerSimulations.SimulationProblemResults{PowerSimulations.EmulationModelSimulationResults};
    aux_variables,
    duals,
    expressions,
    parameters,
    variables
)

Load the simulation results into memory for repeated reads. This is useful when loading results from remote locations over network connections.

For each variable/parameter/dual, etc., each element must be the name encoded as a string, like "ActivePowerVariable__ThermalStandard"or a Tuple with its constituent types, like(ActivePowerVariable, ThermalStandard)`.

Arguments

  • aux_variables::Vector{Union{String, Tuple}}: Optional list of aux variables to load.
  • duals::Vector{Union{String, Tuple}}: Optional list of duals to load.
  • expressions::Vector{Union{String, Tuple}}: Optional list of expressions to load.
  • parameters::Vector{Union{String, Tuple}}: Optional list of parameters to load.
  • variables::Vector{Union{String, Tuple}}: Optional list of variables to load.
source
PowerSimulations.get_system!Method
get_system!(
    results::Union{OptimizationProblemResults, PowerSimulations.SimulationProblemResults};
    kwargs...
) -> Union{Nothing, InfrastructureSystems.InfrastructureSystemsType}

Return the system used for the problem. If the system hasn't already been deserialized or set with set_system! then deserialize and store it.

If the simulation was configured to serialize all systems to file then the returned system will include all data. If that was not configured then the returned system will include all data except time series data.

source
PowerSimulations.read_realized_variableMethod
read_realized_variable(
    res::PowerSimulations.SimulationProblemResults,
    variable::AbstractString;
    kwargs...
) -> Any

Return the final values for the requested variable for each time step for a problem.

Decision problem results are returned in a Dict{DateTime, DataFrame}.

Emulation problem results are returned in a DataFrame.

Limit the data sizes returned by specifying initial_time and count for decision problems or start_time and len for emulation problems.

See also load_results! to preload data into memory.

Arguments

  • variable::Union{String, Tuple}: Variable name as a string or a Tuple with variable type and device type.
  • initial_time::Dates.DateTime: Initial time of the requested results. Decision problems only.
  • count::Int: Number of results. Decision problems only.
  • start_time::Dates.DateTime: Start time of the requested results. Emulation problems only.
  • len::Int: Number of rows in each DataFrame. Emulation problems only.

Examples

julia > read_realized_variable(results, "ActivePowerVariable__ThermalStandard")
julia > read_realized_variable(results, (ActivePowerVariable, ThermalStandard))
source
PowerSimulations.read_realized_variablesMethod
read_realized_variables(
    res::PowerSimulations.SimulationProblemResults;
    kwargs...
) -> Dict

Return the final values for the requested variables for each time step for a problem.

Decision problem results are returned in a Dict{String, Dict{DateTime, DataFrame}}.

Emulation problem results are returned in a Dict{String, DataFrame}.

Limit the data sizes returned by specifying initial_time and count for decision problems or start_time and len for emulation problems.

If the Julia process is started with multiple threads, the code will read the variables in parallel.

See also load_results! to preload data into memory.

Arguments

  • variables::Vector{Union{String, Tuple}}: Variable name as a string or a Tuple with variable type and device type. If not provided then return all variables.
  • initial_time::Dates.DateTime: Initial time of the requested results. Decision problems only.
  • count::Int: Number of results. Decision problems only.
  • start_time::Dates.DateTime: Start time of the requested results. Emulation problems only.
  • len::Int: Number of rows in each DataFrame. Emulation problems only.

Examples

julia > variables_as_strings =
    ["ActivePowerVariable__ThermalStandard", "ActivePowerVariable__RenewableDispatch"]
julia > variables_as_types =
    [(ActivePowerVariable, ThermalStandard), (ActivePowerVariable, RenewableDispatch)]
julia > read_realized_variables(results, variables_as_strings)
julia > read_realized_variables(results, variables_as_types)
source
PowerSimulations.set_system!Method
set_system!(
    results::PowerSimulations.SimulationProblemResults,
    system::AbstractString
)

Set the system in the results instance.

Throws InvalidValue if the system UUID is incorrect.

Arguments

  • results::SimulationProblemResults: Results object
  • system::AbstractString: Path to the system json file

Examples

julia > set_system!(res, "my_path/system_data.json")
source

Simulation Recorder

PowerSimulations.list_simulation_eventsMethod
list_simulation_events(
    ::Type{T<:InfrastructureSystems.AbstractRecorderEvent},
    output_dir::AbstractString;
    ...
) -> Vector{T} where T<:PowerSimulations.AbstractSimulationStatusEvent
list_simulation_events(
    ::Type{T<:InfrastructureSystems.AbstractRecorderEvent},
    output_dir::AbstractString,
    filter_func::Union{Nothing, Function};
    step,
    model_name
) -> Vector{T} where T<:PowerSimulations.AbstractSimulationStatusEvent
list_simulation_events(
    ::Type{T},
    output_dir::AbstractString,
    filter_func::Union{Nothing, Function} = nothing;
    step = nothing,
    model = nothing,
) where {T <: IS.AbstractRecorderEvent}

List simulation events of type T in a simulation output directory.

Arguments

  • output_dir::AbstractString: Simulation output directory
  • filter_func::Union{Nothing, Function} = nothing: Refer to show_simulation_events.
  • step::Int = nothing: Filter events by step. Required if model is passed.
  • model::Int = nothing: Filter events by model.
source
PowerSimulations.show_recorder_eventsMethod
show_recorder_events(
    ::Type{T<:InfrastructureSystems.AbstractRecorderEvent},
    filename::AbstractString;
    ...
)
show_recorder_events(
    ::Type{T<:InfrastructureSystems.AbstractRecorderEvent},
    filename::AbstractString,
    filter_func::Union{Nothing, Function};
    wall_time,
    kwargs...
)
show_recorder_events(
    ::Type{T},
    filename::AbstractString,
    filter_func::Union{Nothing, Function} = nothing;
    wall_time = false,
    kwargs...,
) where {T <: IS.AbstractRecorderEvent}

Show the events of type T in a recorder file.

Arguments

  • ::Type{T}: Recorder event type
  • filename::AbstractString: recorder filename
  • filter_func::Union{Nothing, Function} = nothing: Optional function that accepts an event of type T and returns a Bool. Apply this function to each event and only return events where the result is true.
  • wall_time = false: If true, show the wall_time timestamp.
source
PowerSimulations.show_simulation_eventsMethod
show_simulation_events(
    ::Type{T<:InfrastructureSystems.AbstractRecorderEvent},
    output_dir::AbstractString;
    ...
)
show_simulation_events(
    ::Type{T<:InfrastructureSystems.AbstractRecorderEvent},
    output_dir::AbstractString,
    filter_func::Union{Nothing, Function};
    step,
    model,
    wall_time,
    kwargs...
)
show_simulation_events(
    ::Type{T},
    output_dir::AbstractString,
    filter_func::Union{Nothing,Function} = nothing;
    step = nothing,
    model = nothing,
    wall_time = false,
    kwargs...,
) where { T <: IS.AbstractRecorderEvent}

Show all simulation events of type T in a simulation output directory.

Arguments

  • ::Type{T}: Recorder event type
  • output_dir::AbstractString: Simulation output directory
  • filter_func::Union{Nothing, Function} = nothing: Refer to show_recorder_events.
  • step::Int = nothing: Filter events by step. Required if model is passed.
  • model::Int = nothing: Filter events by model.
  • wall_time = false: If true, show the wall_time timestamp.
source