### Install PowerSimulations (Development Version)

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/index.md

Installs the current development version of PowerSimulations.jl from the main branch using the Julia package manager.

```julia
]
add PowerSimulations#main
```

--------------------------------

### Install PowerSimulations (Stable Release)

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/index.md

Installs the latest stable release of the PowerSimulations.jl package using the Julia package manager.

```julia
]
add PowerSimulations
```

--------------------------------

### Simulation Models

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/api/PowerSimulations.md

Documentation for Simulation, InitialCondition, SimulationModels, and SimulationSequence. It covers the setup and execution of simulations, including sequencing and feedforward mechanisms.

```APIDOC
Simulation Models
  - InitialCondition
  - SimulationModels
  - SimulationSequence
  - Simulation
    - Constructors:
      - Simulation(::AbstractString, ::Dict)
    - Methods:
      - build!(::Simulation)
      - execute!(::Simulation)
  - Refer to the [Simulations Page](@ref running_a_simulation) for explanations on how to setup a Simulation, with Sequencing and Feedforwards.
```

--------------------------------

### Install PowerSystems and PowerSimulations

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/README.md

This snippet shows how to add the PowerSystems and PowerSimulations packages to a Julia environment using the package manager.

```julia
julia> ]
(v1.9) pkg> add PowerSystems
(v1.9) pkg> add PowerSimulations
```

--------------------------------

### Example Simulation Construction and Build

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/parallel_simulations.md

Provides an example of how to construct a Simulation object with specified parameters and then call the build! function. It includes error handling for build failures, checking the status returned by build!.

```julia
sim = Simulation(
    name=simulation_name,
    steps=partitions.num_steps,
    models=models,
    sequence=sequence,
    simulation_folder=output_dir,
)
status = build!(sim; partitions=partitions, index=index, serialize=isnothing(index))
if status != PSI.SimulationBuildStatus.BUILT
    error("Failed to build simulation: status=$status")
end
```

--------------------------------

### Example Optimization Problem Formulation

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/Introduction.md

Illustrates the abstract form of an optimization problem in PowerSimulations.jl using a DecisionModel with three DeviceModels. It shows the objective function and constraints for network and device models.

```math
\begin{align*}\\
    &\min_{\boldsymbol{x}}~ \text{Objective\_DeviceModelA} + \text{Objective\_DeviceModelB} + \text{Objective\_DeviceModelC} \\
    & ~\text{s.t.} \\
    & \hspace{0.9cm} \text{Constraints\_NetworkModel} \\
    & \hspace{0.9cm} \text{Constraints\_DeviceModelA} \\
    & \hspace{0.9cm} \text{Constraints\_DeviceModelB} \\
    & \hspace{0.9cm} \text{Constraints\_DeviceModelC} 
\end{align*}
```

--------------------------------

### Simulation Setup and Sequencing

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/running_a_simulation.md

This code block demonstrates the complete setup for a simulation pipeline in PowerSimulations.jl. It includes creating decision models for Unit Commitment (UC) and Economic Dispatch (ED), defining simulation models, specifying feedforwards, and configuring the simulation sequence with inter-problem chronologies.

```julia
# We assume that the templates for UC and ED are ready
# sys_da has the resolution of 1 hour:
# with the 24 hours interval and horizon of 48 hours.
# sys_rt has the resolution of 5 minutes:
# with a 5-minute interval and horizon of 2 hours (24 time steps)

# Create the UC Decision Model
decision_model_uc = DecisionModel(
    template_uc,
    sys_da;
    name = "UC",
    optimizer = optimizer_with_attributes(
        Xpress.Optimizer,
        "MIPRELSTOP" => 1e-1,
    ),
)

# Create the ED Decision Model
decision_model_ed = DecisionModel(
    template_ed,
    sys_rt;
    name = "ED",
    optimizer = optimizer_with_attributes(Xpress.Optimizer),
)

# Specify the SimulationModels using a Vector of decision_models: UC, ED
sim_models = SimulationModels (; 
    decision_models = [
        decision_model_uc,
        decision_model_ed,
    ],
)

# Create the FeedForwards:
semi_ff = SemiContinuousFeedforward (; 
    component_type = ThermalStandard,
    source = OnVariable,
    affected_values = [ActivePowerVariable],
)

# Specify the sequencing:
sim_sequence = SimulationSequence (; 
    # Specify the vector of decision models: sim_models
    models = sim_models,
    # Specify a Dict of feedforwards on which the FF applies
    # based on the DecisionModel name, in this case "ED"
    feedforwards = Dict(
        "ED" => [semi_ff],
    ),
    # Specify the chronology, in this case inter-stage
    ini_cond_chronology = InterProblemChronology(),
)

```

--------------------------------

### Accessing Simulation Results

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/api/PowerSimulations.md

Guides on accessing simulation results, including problem results and HDF5 storage.

```APIDOC
Modules = [PowerSimulations]
Pages   = ["simulation_results.jl", "simulation_problem_results.jl", "simulation_partition_results.jl", "hdf_simulation_store.jl"]
Order = [:type, :function]
Public = true
Private = false
```

--------------------------------

### Formulation Docstrings

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/README.md

Formulations used in the Valid DeviceModel table must include a docstring within the `src/core/formulations.jl` file. This ensures clarity and maintainability of the formulation definitions.

```julia
The Formulation in the @docs block must have a docstring in src/core/formulations.jl
```

--------------------------------

### Parameter Docstrings

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/README.md

Time Series Parameters require docstrings to be present in the `src/core/parameters.jl` file. This ensures that the parameters used for time series data are well-documented.

```julia
The Time Series Parameters must have docstrings in src/core/parameters.jl
```

--------------------------------

### Building and Executing a Simulation

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/running_a_simulation.md

Demonstrates the steps to build the decision models and simulation setup using `build!(sim)` and then execute the simulation using `execute!(sim)`. The execution can be configured with a progress bar.

```julia
# Build the decision models and simulation setup
build!(sim)

# Execute the simulation using the Optimizer specified in each DecisionModel
execute!(sim; enable_progress_bar = true)
```

--------------------------------

### Variable Docstrings

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/README.md

All variables defined within the system must have corresponding docstrings located in the `src/core/variables.jl` file. This documentation is crucial for understanding the purpose and usage of each variable.

```julia
The Variables must have docstrings in src/core/variables.jl
```

--------------------------------

### Running Parallel Simulations

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/parallel_simulations.md

Demonstrates how to initiate a parallel simulation using the `run_parallel_simulation` function. This example shows splitting a year-long simulation into weekly partitions and running them concurrently, specifying various execution parameters.

```julia
julia> include("my_simulation.jl")
julia> run_parallel_simulation(
        build_simulation,
        execute_simulation,
        script="my_simulation.jl",
        output_dir="my_simulation_output",
        name="my_simulation",
        num_steps=365,
        period=7,
        num_overlap_steps=1,
        num_parallel_processes=4,
        exeflags="--project=<path-to-your-julia-environment>",
    )
```

--------------------------------

### Read Variables, Parameters, Expressions, and Duals

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/read_results.md

Provides examples of reading specific types of results from a solved DecisionModel. It covers reading variables, parameters, expressions, and dual variables using dedicated functions.

```julia
# Read active power of Thermal Standard
thermal_active_power = read_variable(results, "ActivePowerVariable__ThermalStandard")

# Read max active power parameter of RenewableDispatch
renewable_param =
    read_parameter(results, "ActivePowerTimeSeriesParameter__RenewableDispatch")

# Read cost expressions of ThermalStandard units
cost_thermal = read_expression(results, "ProductionCostExpression__ThermalStandard")

# Read dual variables
dual_balance_constraint = read_dual(results, "CopperPlateBalanceConstraint__System")
```

--------------------------------

### Customizing Device Formulations with Attributes

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/definitions.md

Demonstrates how to customize device formulations in PowerSimulations.jl by specifying attributes. This example shows how to configure a StorageDispatchWithReserves device model, enabling or disabling features like reservation, cycling limits, and energy targets by setting corresponding attributes to true or false.

```julia
set_device_model!(
    template,
    DeviceModel(
        GenericBattery,
        StorageDispatchWithReserves;
        attributes = Dict{String, Any}(
            "reservation" => false,
            "cycling_limits" => false,
            "energy_target" => false,
            "complete_coverage" => false,
            "regularization" => false,
        ),
    ),
)
```

--------------------------------

### Execute Simulation Function Signature and Example

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/parallel_simulations.md

Defines the signature for the execute function and provides an example implementation. This function is responsible for running the simulation and must throw an exception if the execution fails, checking the return status.

```julia
function execute_simulation(sim, args...; kwargs...)
    status = execute!(sim)
    if status != PSI.RunStatus.SUCCESSFULLY_FINALIZED
        error("Simulation failed to execute: status=$status")
    end
end
```

--------------------------------

### Network Formulations Overview

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/Network.md

Lists available network formulations for PowerSimulations.jl and references formulations from PowerModels.jl.

```APIDOC
Available Network Models:
  CopperPlatePowerModel: Copper plate connection between all components, i.e. infinite transmission capacity
  AreaBalancePowerModel: Network model approximation to represent inter-area flow with each area represented as a single node
  PTDFPowerModel: Uses the PTDF factor matrix to compute the fraction of power transferred in the network across the branches
  AreaPTDFPowerModel: Uses the PTDF factor matrix to compute the fraction of power transferred in the network across the branches and balances power by Area instead of system-wide

PowerModels.jl Formulations:
  Exact non-convex models: ACPPowerModel, ACRPowerModel, ACTPowerModel.
  Linear approximations: DCPPowerModel, NFAPowerModel.
  Quadratic approximations: DCPLLPowerModel, LPACCPowerModel
  Quadratic relaxations: SOCWRPowerModel, SOCWRConicPowerModel, SOCBFPowerModel, SOCBFConicPowerModel, QCRMPowerModel, QCLSPowerModel.
  SDP relaxations: SDPWRMPowerModel, SparseSDPWRMPowerModel.

Reference: https://lanl-ansi.github.io/PowerModels.jl/stable/formulation-details/
```

--------------------------------

### PowerSystems.jl Thermal Unit Commitment Example

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/ThermalGen.md

Illustrative Julia code snippet demonstrating the usage of the ThermalMultiStartUnitCommitment model within the PowerSystems.jl framework. This example would typically involve setting up a system, defining a thermal unit, and then using the commitment model.

```Julia
using PowerSimulations
using PowerSystems

# Assume a system and device are already defined
# sys = System(...) 
# device = ...

# Create the commitment model for a thermal unit
# commitment_model = ThermalMultiStartUnitCommitment(device)

# Further steps would involve adding this model to a simulation sequence
# or optimization problem.
```

--------------------------------

### Emulation Models

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/api/PowerSimulations.md

Documentation for EmulationModel, including its constructors and methods for building, running, and solving emulation problems. It details how to initialize and manage emulation simulations with different configurations.

```APIDOC
EmulationModel
  - Constructors:
    - EmulationModel(::Type{M} where {M <: EmulationProblem}, ::ProblemTemplate, ::PSY.System, ::Union{Nothing, JuMP.Model})
    - EmulationModel(::AbstractString, ::MOI.OptimizerWithAttributes)
  - Methods:
    - build!(::EmulationModel)
    - run!(::EmulationModel)
    - solve!(::Int, ::EmulationModel{<:EmulationProblem}, ::Dates.DateTime, ::SimulationStore)
```

--------------------------------

### Get Contributing Devices

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/Service.md

Retrieves the set of all devices contributing to a specific service within the system.

```Julia
PowerSystems.get_contributing_devices(system, service)
```

--------------------------------

### Build Simulation

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/tutorials/pcm_simulation.md

Builds the simulation environment based on the defined models and sequence, preparing it for execution.

```julia
build!(sim)
```

--------------------------------

### Load Packages

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/tutorials/pcm_simulation.md

Loads necessary Julia packages for PowerSimulations, including PowerSystems, HydroPowerSimulations, PowerSystemCaseBuilder, Dates, and the HiGHS optimizer.

```Julia
using PowerSystems
using PowerSimulations
using HydroPowerSimulations
const PSI = PowerSimulations
using PowerSystemCaseBuilder
using Dates
using HiGHS #solver
```

--------------------------------

### Import PowerSimulations and PowerSystems

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/README.md

This snippet demonstrates how to import the PowerSimulations and PowerSystems packages into a Julia session for use in simulations.

```julia
using PowerSimulations
using PowerSystems
```

--------------------------------

### Initialize Simulation Results

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/tutorials/pcm_simulation.md

Loads the metadata for simulation results, allowing for efficient access to specific data points from different stages of the simulation.

```julia
results = SimulationResults(sim);
uc_results = get_decision_problem_results(results, "UC"); # UC stage result metadata
ed_results = get_decision_problem_results(results, "ED"); # ED stage result metadata
```

--------------------------------

### Define Optimizer

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/tutorials/decision_problem.md

Configures the optimizer to be used for solving the decision model. This example sets up the HiGHS optimizer with a relative gap tolerance of 0.5 for faster solutions.

```julia
solver = optimizer_with_attributes(HiGHS.Optimizer, "mip_rel_gap" => 0.5)
```

--------------------------------

### Create 5-Minute Real-Time System

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/tutorials/pcm_simulation.md

Constructs a PowerSystems.jl system using 5-minute resolution time series data for a real-time market, representing 15-minute ahead forecasted data.

```Julia
sys_RT = build_system(PSISystems, "modified_RTS_GMLC_RT_sys"; skip_serialization = true)
```

--------------------------------

### Build System Data

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/tutorials/decision_problem.md

Builds the power system data using the PowerSystemCaseBuilder.jl library. This function simplifies reproducing documentation examples by providing pre-defined system data.

```julia
sys = build_system(PSISystems, "modified_RTS_GMLC_DA_sys")
```

--------------------------------

### Example Infeasibility Conflict Output

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/debugging_infeasible_models.md

Demonstrates the typical output format when the irreducible infeasible set (IIS) is calculated, listing constraints and variables participating in the conflict.

```raw
Error: Constraints participating in conflict basis (IIS) 
│ 
│ ┌──────────────────────────────────────┐
│ │ CopperPlateBalanceConstraint__System │
│ ├──────────────────────────────────────┤
│ │                            (113, 26) │
│ └──────────────────────────────────────┘
│ ┌──────────────────────────────────┐
│ │ EnergyAssetBalance__HybridSystem │
│ ├──────────────────────────────────┤
│ │               ("317_Hybrid", 26) │
│ └──────────────────────────────────┘
│ ┌─────────────────────────────────────────────┐
│ │ PieceWiseLinearCostConstraint__HybridSystem │
│ ├─────────────────────────────────────────────┤
│ │                          ("317_Hybrid", 26) │
│ └─────────────────────────────────────────────┘
│ ┌────────────────────────────────────────────────┐
│ │ PieceWiseLinearCostConstraint__ThermalStandard │
│ ├────────────────────────────────────────────────┤
│ │                            ("202_STEAM_3", 26) │
│ │                            ("101_STEAM_3", 26) │
│ │                               ("118_CC_1", 26) │
│ │                            ("202_STEAM_4", 26) │
│ │                               ("315_CT_6", 26) │
│ │                            ("201_STEAM_3", 26) │
│ │                            ("102_STEAM_4", 26) │
│ └────────────────────────────────────────────────┘
│ ┌──────────────────────────────────────────────────────────────────────┐
│ │ ActivePowerVariableTimeSeriesLimitsConstraint__RenewableDispatch__ub │
│ ├──────────────────────────────────────────────────────────────────────┤
│ │                                                   ("122_WIND_1", 26) │
│ │                                                     ("324_PV_3", 26) │
│ │                                                     ("312_PV_1", 26) │
│ │                                                     ("102_PV_1", 26) │
│ │                                                     ("101_PV_1", 26) │
│ │                                                     ("324_PV_2", 26) │
│ │                                                     ("313_PV_2", 26) │
│ │                                                     ("104_PV_1", 26) │
│ │                                                     ("101_PV_2", 26) │
│ │                                                   ("309_WIND_1", 26) │
│ │                                                     ("310_PV_2", 26) │
│ │                                                     ("113_PV_1", 26) │
│ │                                                     ("314_PV_1", 26) │
│ │                                                     ("324_PV_1", 26) │
│ │                                                     ("103_PV_1", 26) │
│ │                                                   ("303_WIND_1", 26) │
│ │                                                     ("314_PV_2", 26) │
│ │                                                     ("102_PV_2", 26) │
│ │                                                     ("314_PV_3", 26) │
│ │                                                     ("320_PV_1", 26) │
│ │                                                     ("101_PV_3", 26) │
│ │                                                     ("319_PV_1", 26) │
│ │                                                     ("314_PV_4", 26) │
│ │                                                     ("310_PV_1", 26) │
│ │                                                     ("215_PV_1", 26) │
│ │                                                     ("313_PV_1", 26) │
│ │                                                     ("101_PV_4", 26) │
│ │                                                     ("119_PV_1", 26) │
│ └──────────────────────────────────────────────────────────────────────┘
│ ┌─────────────────────────────────────────────────────────────────────────────┐

```

--------------------------------

### Constructing a Simulation

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/running_a_simulation.md

Defines how to construct a simulation object with parameters such as name, steps, models, sequence, initial time, and simulation folder. It highlights the use of `mktempdir` for temporary log storage.

```julia
sim = Simulation(;
    name = "compact_sim",
    steps = 10, # 10 days
    models = sim_models,
    sequence = sim_sequence,
    # Specify the start_time as a DateTime: e.g. DateTime("2020-10-01T00:00:00")
    initial_time = start_time,
    # Specify a temporary folder to avoid storing logs if not needed
    simulation_folder = mktempdir(; cleanup = true),
)
```

--------------------------------

### Configure Simulation Logger Verbosity

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/logging.md

Sets the logging verbosity for a simulation when using the `build!` function. This example increases verbosity to Logging.Debug for file output and Logging.Info for console output.

```julia
import Logging
using PowerSimulations
simulation = Simulation(...)
build!(simulation; console_level = Logging.Info, file_level = Logging.Debug)
```

--------------------------------

### Jade Configuration Commands

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/parallel_simulations.md

Commands for interacting with Jade configurations, including showing configuration details and submitting jobs to an HPC cluster.

```bash
$ jade config show config.json
```

```bash
$ jade config hpc -c hpc_config.toml -t slurm  --walltime=04:00:00 -a <your-account>
```

```bash
$ jade submit-jobs config.json --per-node-batch-size=1 -o output
```

```bash
$ jade submit-jobs config.json --per-node-batch-size=1 -o output --resource-monitor-type periodic --resource-monitor-interval 3
```

--------------------------------

### Create Hourly Day-Ahead System

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/tutorials/pcm_simulation.md

Builds a PowerSystems.jl system with hourly data, representing day-ahead forecasted wind, solar, and load profiles using a predefined system configuration.

```Julia
sys_DA = build_system(PSISystems, "modified_RTS_GMLC_DA_sys"; skip_serialization = true)
```

--------------------------------

### Simulation Results Table

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/read_results.md

Example output format for simulation results, showing Decision Problem and Emulator results with key details like problem name, time, resolution, and number of steps.

```raw
Decision Problem Results
┌──────────────┬─────────────────────┬──────────────┬─────────────────────────┐
│ Problem Name │ Initial Time        │ Resolution   │ Last Solution Timestamp │
├──────────────┼─────────────────────┼──────────────┼─────────────────────────┤
│ ED           │ 2020-10-02T00:00:00 │ 60 minutes   │ 2020-10-09T23:00:00     │
│ UC           │ 2020-10-02T00:00:00 │ 1440 minutes │ 2020-10-09T00:00:00     │
└──────────────┴─────────────────────┴──────────────┴─────────────────────────┘

Emulator Results
┌─────────────────┬───────────┐
│ Name            │ Emulator  │
│ Resolution      │ 5 minutes │
│ Number of steps │ 2304      │
└─────────────────┴───────────┘
```

--------------------------------

### Building a ProblemTemplate

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/problem_templates.md

Demonstrates how to construct a `ProblemTemplate` by adding a `NetworkModel` and specifying `DeviceModel`s and `ServiceModels` for different device types.

```julia
template = ProblemTemplate()
set_network_model!(template, NetworkModel(CopperPlatePowerModel))
set_device_model!(template, PowerLoad, StaticPowerLoad)
set_device_model!(template, ThermalStandard, ThermalBasicUnitCommitment)
set_service_model!(template, VariableReserve{ReserveUp}, RangeReserve)
```

--------------------------------

### GroupReserve Static Parameters and Relevant Methods

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/Service.md

Describes the static parameters and relevant methods for the GroupReserve model, used for aggregating services. It includes the requirement parameter and methods to get contributing services and devices.

```APIDOC
Static Parameters:
  `Req` = `PowerSystems.get_requirement(service)`

Relevant Methods:
  `S_s` = `PowerSystems.get_contributing_services(system, service)`: Set (vector) of all contributing services to the group service `s` in the system.
  `D_{s_i}` = `PowerSystems.get_contributing_devices(system, service_aux)`: Set (vector) of all contributing devices to the service `s_i` in the system.
```

--------------------------------

### PowerSimulations CLI Main Function

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/parallel_simulations.md

Provides the main entry point for a Julia script to process simulation partition command-line arguments. It utilizes `process_simulation_partition_cli_args` with the defined `build_simulation` and `execute_simulation` functions.

```julia
function main()
    process_simulation_partition_cli_args(build_simulation, execute_simulation, ARGS...)
end

if abspath(PROGRAM_FILE) == @__FILE__
    main()
end
```

--------------------------------

### DeviceModel Table Documentation

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/README.md

Ensures the DeviceModel table is valid by modifying the device category within the filter function. This relates to the requirement that formulations in the Valid DeviceModel table must have a docstring in src/core/formulations.jl.

```julia
change the device category in the filter function
```

--------------------------------

### FixedOutput Formulation Details

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/General.md

Provides details on the `FixedOutput` formulation in PowerSimulations. It outlines the static parameters for ThermalGen and Storage, and lists the default time series parameter names for various device types. It also specifies that no variables, objective terms, or constraints are created for this formulation.

```APIDOC
FixedOutput:
  Description: Modeling formulation that does not create specific variables, objective terms, or constraints.
  Static Parameters:
    ThermalGen:
      P^th,max: Maximum active power (PowerSystems.get_max_active_power(device))
      Q^th,max: Maximum reactive power (PowerSystems.get_max_reactive_power(device))
    Storage:
      P^st,max: Maximum active power (PowerSystems.get_max_active_power(device))
      Q^st,max: Maximum reactive power (PowerSystems.get_max_reactive_power(device))
  Time Series Parameters:
    RenewableGen:
      Default Time Series Name: Maps parameter names to default time series names.
    ThermalGen:
      Default Time Series Name: Maps parameter names to default time series names.
    HydroGen:
      Default Time Series Name: Maps parameter names to default time series names.
    ElectricLoad:
      Default Time Series Name: Maps parameter names to default time series names.
  Expressions:
    Adds active and reactive parameters to respective balance expressions based on network formulations.
```

--------------------------------

### ThermalCompactUnitCommitment Variables

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/ThermalGen.md

Defines the primary variables used in the ThermalCompactUnitCommitment model, including power output, reactive power, and commitment status (on, start, stop). Each variable is associated with its bounds and symbolic representation.

```APIDOC
PowerAboveMinimumVariable:
  Bounds: [0.0, ]
  Symbol: "\Delta p^\text{th}"

ReactivePowerVariable:
  Bounds: [0.0, ]
  Symbol: "q^\text{th}"

OnVariable:
  Bounds: {0,1}
  Symbol: "u_t^\text{th}"

StartVariable:
  Bounds: {0,1}
  Symbol: "v_t^\text{th}"

StopVariable:
  Bounds: {0,1}
  Symbol: "w_t^\text{th}"
```

--------------------------------

### Time Series Parameters Documentation

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/README.md

Updates Time Series Parameters by changing the device category and formulation in the `get_default_time_series_names` method call. This aligns with the requirement that Time Series Parameters must have docstrings in src/core/parameters.jl.

```julia
change the device category and formulation in the `get_default_time_series_names` method call
```

--------------------------------

### PTDFPowerModel Documentation

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/Network.md

Details the PTDFPowerModel, including its slack variables, objective function modifications, expressions for power balance, and constraints for system balancing.

```APIDOC
PTDFPowerModel:
  Description: Models power flow using PTDF factors.
  Variables:
    SystemBalanceSlackUp:
      Bounds: [0.0, ]
      Default initial value: 0.0
      Default proportional cost: 1e6
      Symbol: "p^sl,up"
    SystemBalanceSlackDown:
      Bounds: [0.0, ]
      Default initial value: 0.0
      Default proportional cost: 1e6
      Symbol: "p^sl,dn"
  Objective:
    Adds a large proportional cost to the objective function if slack variables are used: `+ (p^sl,up + p^sl,dn) * 10^6`
  Expressions:
    Adds `p^sl,up` and `p^sl,dn` terms to the respective system-wide active power balance expressions `ActivePowerBalance`.
    Creates `ActivePowerBalance` expressions for each bus for branch flow calculation.
  Constraints:
    CopperPlateBalanceConstraint: Balances active power of all system components.
      Formula: `sum_{c in components} p_t^c = 0, forall t in {1, ..., T}`
    NodalBalanceActiveConstraint: For HVDC buses balance if DC components are connected to an HVDC network.
```

--------------------------------

### Julia Conda Environment Setup

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/parallel_simulations.md

Commands to set up a conda environment named 'conda_jl' for Julia, including Python and Conda itself. It also demonstrates setting the CONDA_JL_HOME environment variable and building the Conda package within Julia.

```julia
julia> run(`conda create -n conda_jl python conda`)
julia> ENV["CONDA_JL_HOME"] = joinpath(ENV["HOME"], ".conda-envs", "jade")  # change this to your path
pkg> build Conda
```

--------------------------------

### Define Simulation Models

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/tutorials/pcm_simulation.md

Sets up the `SimulationModels` by defining two decision models: one for Day-Ahead Unit Commitment (UC) using `template_uc` and `sys_DA`, and another for Real-Time Economic Dispatch (ED) using `template_ed` and `sys_RT`, both utilizing the previously defined solver.

```Julia
models = SimulationModels(;
    decision_models = [
        DecisionModel(template_uc, sys_DA; optimizer = solver, name = "UC"),
        DecisionModel(template_ed, sys_RT; optimizer = solver, name = "ED"),
    ],
)
```

--------------------------------

### Configure Parallel Simulation with Jade

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/modeler_guide/parallel_simulations.md

This Julia function configures a parallel simulation using the NREL-jade Python package via PyCall. It generates a JSON configuration file that specifies setup, teardown, and execution commands for each simulation partition.

```julia
function configure_parallel_simulation(
    script::AbstractString,
    num_steps::Integer,
    num_period_steps::Integer;
    num_overlap_steps::Integer=0,
    project_path=nothing,
    simulation_name="simulation",
    config_file="config.json",
    force=false,
)
    partitions = SimulationPartitions(num_steps, num_period_steps, num_overlap_steps)
    jgc = pyimport("jade.extensions.generic_command")
    julia_cmd = isnothing(project_path) ? "julia" : "julia --project=$project_path"
    setup_command = "$julia_cmd $script setup --simulation-name=$simulation_name " * 
    "--num-steps=$num_steps --num-period-steps=$num_period_steps " * 
    "--num-overlap-steps=$num_overlap_steps"
    teardown_command = "$julia_cmd $script join --simulation-name=$simulation_name"
    config = jgc.GenericCommandConfiguration(
        setup_command=setup_command,
        teardown_command=teardown_command,
    )

    for i in 1:get_num_partitions(partitions)
        cmd = "$julia_cmd $script execute --simulation-name=$simulation_name --index=$i"
        job = jgc.GenericCommandParameters(command=cmd, name="execute-$i")
        config.add_job(job)
    end

    config.dump(config_file, indent=2)
    println("Created Jade configuration in $config_file. " * 
            "Run 'jade submit-jobs [options] $config_file' to execute them.")
end
```

--------------------------------

### Specific Optimization Problem with Thermal and Renewable Units

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/Introduction.md

Presents a concrete optimization problem for a system with thermal and renewable generation units. It details the objective function and constraints, including power balance and generation limits.

```math
\begin{align*}\\
    &\min_{\boldsymbol{p}^\text{th}, \boldsymbol{p}^\text{re}}}~ \sum_{t=1}^{48} C^\text{th} p_t^\text{th} - C^\text{re} p_t^\text{re} \\
    & ~\text{s.t.} \\
    & \hspace{0.9cm} p_t^\text{th} + p_t^\text{re} = P_t^\text{load}, \quad \forall t \in {1,\dots, 48} \\
    & \hspace{0.9cm} 0 \le p_t^\text{th} \le P^\text{th,max} \\
    & \hspace{0.9cm} 0 \le p_t^\text{re} \le \text{ActivePowerTimeSeriesParameter}_t 
\end{align*}
```

--------------------------------

### ThermalMultiStartUnitCommitment Variables

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/ThermalGen.md

Defines the state and auxiliary variables used in the ThermalMultiStartUnitCommitment model. These include binary variables for unit status (on, start, stop) and continuous variables for power output and duration, along with their associated bounds and symbolic representations.

```APIDOC
PowerAboveMinimumVariable:
  Bounds: [0.0, ]
  Symbol: "\Delta p^\text{th}"

ReactivePowerVariable:
  Bounds: [0.0, ]
  Symbol: "q^\text{th}"

OnVariable:
  Bounds: {0,1}
  Symbol: "u_t^\text{th}"

StartVariable:
  Bounds: {0,1}
  Symbol: "v_t^\text{th}"

StopVariable:
  Bounds: {0,1}
  Symbol: "w_t^\text{th}"

ColdStartVariable:
  Bounds: {0,1}
  Symbol: "x_t^\text{th}"

WarmStartVariable:
  Bounds: {0,1}
  Symbol: "y_t^\text{th}"

HotStartVariable:
  Bounds: {0,1}
  Symbol: "z_t^\text{th}"

PowerOutput:
  Symbol: "P^\text{th}"
  Definition: "P^\text{th} = u^\text{th}P^\text{min} + \Delta p^\text{th}"

TimeDurationOn:
  Symbol: "V_t^\text{th}"
  Definition: "Computed post optimization by adding consecutive turned on variable u_t^\text{th}"

TimeDurationOff:
  Symbol: "W_t^\text{th}"
  Definition: "Computed post optimization by adding consecutive turned off variable 1 - u_t^\text{th}"
```

--------------------------------

### Network Constraints

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/api/PowerSimulations.md

Documentation for network-related constraints, including balance constraints, area participation, and nodal balance.

```APIDOC
Network Constraints:
  - CopperPlateBalanceConstraint
  - NodalBalanceActiveConstraint
  - NodalBalanceReactiveConstraint
  - AreaParticipationAssignmentConstraint
```

--------------------------------

### ThermalStandardUnitCommitment Variables

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/formulation_library/ThermalGen.md

Defines the primary variables used in the ThermalStandardUnitCommitment model, including active power, reactive power, and commitment status (on, start, stop). It also details slack variables for rate-of-change constraints and auxiliary variables for calculating time durations.

```APIDOC
ActivePowerVariable:
  Bounds: [0.0, ]
  Symbol: "p^th"

ReactivePowerVariable:
  Bounds: [0.0, ]
  Symbol: "q^th"

OnVariable:
  Bounds: {0,1}
  Symbol: "u_t^th"

StartVariable:
  Bounds: {0,1}
  Symbol: "v_t^th"

StopVariable:
  Bounds: {0,1}
  Symbol: "w_t^th"

RateofChangeConstraintSlackUp:
  Bounds: [0.0, ]
  Default initial value: 0.0
  Default proportional cost: 2e5
  Symbol: "p^sl,up"

RateofChangeConstraintSlackDown:
  Bounds: [0.0, ]
  Default initial value: 0.0
  Default proportional cost: 2e5
  Symbol: "p^sl,dn"

TimeDurationOn:
  Symbol: "V_t^th"
  Definition: Computed post optimization by adding consecutive turned on variable "u_t^th"

TimeDurationOff:
  Symbol: "W_t^th"
  Definition: Computed post optimization by adding consecutive turned off variable "1 - u_t^th"
```

--------------------------------

### Thermal Unit Constraints

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/api/PowerSimulations.md

Documentation for constraints specific to thermal units, including commitment, duration, ramp, and startup constraints.

```APIDOC
Thermal Unit Constraints:
  - ActiveRangeICConstraint
  - CommitmentConstraint
  - DurationConstraint
  - RampConstraint
  - StartupInitialConditionConstraint
  - StartupTimeLimitTemperatureConstraint
```

--------------------------------

### Build and Solve DecisionModel

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/tutorials/decision_problem.md

Demonstrates the construction of a DecisionModel using a template and system data, followed by building the model and solving it. Includes serialization of the optimization model.

```julia
problem = DecisionModel(template_uc, sys; optimizer = solver, horizon = Hour(24))
build!(problem; output_dir = mktempdir())
solve!(problem)
```

```julia
serialize_optimization_model(problem, save_path)
```

--------------------------------

### Services Variables

Source: https://github.com/nrel-sienna/powersimulations.jl/blob/main/docs/src/api/PowerSimulations.md

Documentation for variables related to services, such as reserve variables and system balance slack variables.

```APIDOC
Services Variables:
  - ActivePowerReserveVariable
  - ServiceRequirementVariable
  - SystemBalanceSlackUp
  - SystemBalanceSlackDown
  - ReserveRequirementSlack
  - InterfaceFlowSlackUp
  - InterfaceFlowSlackDown
```