Merge pull request #988 from NREL-Sienna/jd/custom_model_improvements

Jd/custom model improvements
NREL-Sienna · Sep 6, 2023 · 4fc6be7 · 4fc6be7 · jd-lara · Sep 6, 2023
2 parents 9d0a0fd + 33fe60b
commit 4fc6be7
Show file tree

Hide file tree

Showing 37 changed files with 510 additions and 1,259 deletions.
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "PowerSimulations"
 uuid = "e690365d-45e2-57bb-ac84-44ba829e73c4"
 authors = ["Jose Daniel Lara", "Clayton Barrows", "Daniel Thom", "Dheepak Krishnamurthy", "Sourabh Dalvi"]
-version = "0.21.4"
+version = "0.22.0"
 
 [deps]
 CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -6,6 +6,7 @@ DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterTools = "35a29f4d-8980-5a13-9543-d66fff28ecb8"
 GLPK = "60bf3e95-4087-53dc-ae20-288a0d20c6a6"
+HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
 InfrastructureSystems = "2cd47ed4-ca9b-11e9-27f2-ab636a7671f1"
 Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
 PowerSimulations = "e690365d-45e2-57bb-ac84-44ba829e73c4"

diff --git a/docs/make.jl b/docs/make.jl
@@ -23,8 +23,7 @@ pages = OrderedDict(
         "modeler_guide/modeling_faq.md",
     ],
     "Model Developer Guide" => Any[
-        "Adding Formulations" => "model_developer_guide/adding_new_device_formulation.md"
-        "Adding Problems" => "model_developer_guide/adding_new_problem_model.md"
+        "Operation Problem Structure" => "model_developer_guide/structure_of_operation_problem.md"
         "Troubleshooting" => "model_developer_guide/troubleshooting.md"
     ],
     "Code Base Developer Guide" => Any[
@@ -34,7 +33,6 @@ pages = OrderedDict(
     "Formulation Library" => Any[
         "General" => "formulation_library/General.md",
         "Thermal Generation" => "formulation_library/ThermalGen.md",
-        "Hydro Generation" => "formulation_library/HydroGen.md",
         "Renewable Generation" => "formulation_library/RenewableGen.md",
         "Load" => "formulation_library/Load.md",
         "Network" => "formulation_library/Network.md",

diff --git a/docs/src/api/PowerSimulations.md b/docs/src/api/PowerSimulations.md
@@ -130,14 +130,6 @@ PowerAboveMinimumVariable
 ReservationVariable
 ```
 
-### Common for Hydro and Storage Variables
-
-```@docs
-ActivePowerOutVariable
-ActivePowerInVariable
-EnergyVariable
-```
-
 ### Branches and Network Variables
 
 ```@docs
@@ -187,7 +179,6 @@ PieceWiseLinearCostConstraint
 ### Network Constraints
 
 ```@docs
-ActiveConstraint
 AreaDispatchBalanceConstraint
 AreaParticipationAssignmentConstraint
 BalanceAuxConstraint
@@ -236,18 +227,6 @@ EqualityConstraint
 
 ```
 
-### Hydro and Storage Constraints
-
-```@docs
-EnergyBalanceConstraint
-EnergyBudgetConstraint
-EnergyCapacityConstraint
-EnergyCapacityDownConstraint
-EnergyCapacityUpConstraint
-EnergyTargetConstraint
-RangeLimitConstraint
-```
-
 ### Branches Constraints
 
 ```@docs
@@ -279,19 +258,15 @@ FeedforwardEnergyTargetConstraint
 
 # Parameters
 
-### Time Series Parameters
+## Time Series Parameters
 
 ```@docs
 ActivePowerTimeSeriesParameter
 ReactivePowerTimeSeriesParameter
 RequirementTimeSeriesParameter
-EnergyTargetTimeSeriesParameter
-EnergyBudgetTimeSeriesParameter
-InflowTimeSeriesParameter
-OutflowTimeSeriesParameter
 ```
 
-### Variable Value Parameters
+## Variable Value Parameters
 
 ```@docs
 UpperBoundValueParameter

diff --git a/docs/src/formulation_library/HydroGen.md b/docs/src/formulation_library/HydroGen.md
diff --git a/docs/src/get_test_data.jl b/docs/src/get_test_data.jl
@@ -9,7 +9,7 @@ const PSY = PowerSystems
 
 include("../../../test/test_utils/get_test_data.jl")
 
-abstract type TestOpProblem <: PSI.DecisionProblem end
+abstract type TestOpProblem <: PSI.DefaultDecisionProblem end
 
 system = build_c_sys5_re(; add_reserves = true)
 solver = optimizer_with_attributes(Cbc.Optimizer)

diff --git a/docs/src/model_developer_guide/adding_new_problem_model.md b/docs/src/model_developer_guide/adding_new_problem_model.md
diff --git a/docs/src/model_developer_guide/structure_of_operation_problem.md b/docs/src/model_developer_guide/structure_of_operation_problem.md
@@ -0,0 +1,50 @@
+# Structure of an operations problem model
+
+In most cases operation problem models are optimization models. Although in `PowerSimulations.jl` it is
+possible to define arbitrary problems that can reflect heuristic decision rules, this is not the common case. This page focuses on explaining the structure of operations problems that employ an optimization problem and solver.
+
+The first aspect to consider when thinking about developing a model compatible with `PowerSimulations.jl` is that although we support all of `JuMP.jl` objects, you need to employ [anonymous constraints and variables in JuMP](https://jump.dev/JuMP.jl/stable/manual/variables/#anonymous_variables)
+and register the constraints, variables and other optimization objects into PowerSimulations.jl's optimization container. Otherwise the features to use your problem in the simulation like the coordination with other problems and post processing won't work.
+
+!!! info
+    The requirements for the simulation of Power Systems operations are more strict than solving an optimization problem once with just `JuMP.jl`. The requirements imposed by `PowerSimulations.jl` to integrate your models in a simulation are designed to help with other complex operations that go beyond `JuMP.jl` scope.
+
+!!! warning
+    All the code in this page is considered "pseudo-code". Copy-paste will likely not work out of the box. You need to develop the internals of the functions correctly for the examples below to work.
+
+## Registering a variable in the model
+
+To register a variable in the model, the developer must first allocate the container into the
+optimization container and then populate it. For example, it require start the build function as follows:
+
+!!! info
+    We recommend calling `import PowerSimulations` and defining the constant `CONST PSI = PowerSimulations` to
+    make it easier to read the code and determine which package is responsible for defining the functions.
+
+```julia
+    function PSI.build_model!(model::PSI.DecisionModel{MyCustomModel})
+        container = PSI.get_optimization_container(model)
+        PSI.set_time_steps!(container, 1:24)
+
+        # Create the container for the variable
+        variable = PSI.add_variable_container!(
+            container,
+            PSI.ActivePowerVariable(), # <- This variable is defined in PowerSimulations but the user can define their own
+            PSY.ThermalGeneration, # <- Device type for the variable. Can be from PSY or custom defined
+            devices_names, # <- First container dimension
+            time_steps, # <- Second container dimension
+        )
+
+        # Iterate over the devices and time to store the JuMP variables into the container.
+        for t in time_steps, d in devices
+            name = PSY.get_name(d)
+            variable[name, t] = JuMP.@variable(get_jump_model(container))
+            # It is possible to use PSY getter functions to retrieve data from the generators
+            # Any other variable property can be specified inside this loop.
+            JuMP.set_upper_bound(variable[name, t], UB_DATA) # <- Optional
+            JuMP.set_lower_bound(variable[name, t], LB_DATA) # <- Optional
+        end
+
+    return
+    end
+```
diff --git a/docs/src/modeler_guide/definitions.md b/docs/src/modeler_guide/definitions.md
@@ -2,20 +2,22 @@
 
 ## D
 
-* *Decision Problem*: A decision problem calculates the desired system operation based on forecasts of uncertain inputs and information about the state of the system. The output of a decision problem represents the policies used to drive the set-points of the system's devices, like generators or switches, and depends on the purpose of the problem.
+* *Decision Problem*: A decision problem calculates the desired system operation based on forecasts of uncertain inputs and information about the state of the system. The output of a decision problem represents the policies used to drive the set-points of the system's devices, like generators or switches, and depends on the purpose of the problem. See the [Decision Model Tutorial](op_problem_tutorial) to learn more about solving individual problems.
+
+* *Device Formulation*: The model of a device that is incorporated into a large system optimization models. For instance, the storage device model used inside of a Unit Commitment (UC) problem. A device model needs to follow some requirements to be integrated into operation problems.
 
 ## E
 
 * *Emulation Problem*: An emulation problem is used to mimic the system's behavior subject to an incoming decision and the realization of a forecasted inputs. The solution of the emulator produces outputs representative of the system performance when operating subject the policies resulting from the decision models.
 
 ## H
 
-* *Horizon*: The number of steps in the look-ahead of a decision problem. For instance, a Day-ahead problem usually has a 48 step horizon.
+* *Horizon*: The number of steps in the look-ahead of a decision problem. For instance, a Day-Ahead problem usually has a 48 step horizon. Check the time [Time Series Data Section in PowerSystems.jl](https://nrel-sienna.github.io/PowerSystems.jl/stable/modeler_guide/time_series/)
 
 ## I
 
-* *Interval*:
+* *Interval*: The amount of time between updates to the decision problem. For instance, Day-Ahead problems usually have a 24-hour intervals and Real-Time problems have 5-minute intervals. Check the time [Time Series Data Section in PowerSystems.jl](https://nrel-sienna.github.io/PowerSystems.jl/stable/modeler_guide/time_series/)
 
 ## R
 
-* *Resolution*: The amount of time between timesteps in a simulation. For instance 1-hour or 5-minutes. In Julia these are defined using the syntax `Hour(1)` and `Minute(5)`
+* *Resolution*: The amount of time between timesteps in a simulation. For instance 1-hour or 5-minutes. In Julia these are defined using the syntax `Hour(1)` and `Minute(5)`. Check the time [Time Series Data Section in PowerSystems.jl](https://nrel-sienna.github.io/PowerSystems.jl/stable/modeler_guide/time_series/)
diff --git a/docs/src/modeler_guide/running_a_simulation.md b/docs/src/modeler_guide/running_a_simulation.md
@@ -11,4 +11,6 @@ TODO
 
 ## Sequencing
 
-TODO
+In a typical simulation pipeline, we want to connect daily (24-hours) day-ahead unit commitment problems, with multiple economic dispatch problems. Usually, our day-ahead unit commitment problem will have an hourly (1-hour) resolution, while the economic dispatch will have a 5-minute resolution.
+
+Depending on your problem, it is common to use a 2-day look-ahead for unit commitment problems, so in this case, the Day-Ahead problem will have: resolution = Hour(1) with interval = Hour(24) and horizon = 48. In the case of the economic dispatch problem, it is common to use a look-ahead of two hours. Thus, the Real-Time problem will have: resolution = Minute(5), with interval = Minute(5) (we only store the first operating point) and horizon = 24 (24 time steps of 5 minutes are 120 minutes, that is 2 hours).
diff --git a/...er_guide/adding_new_device_formulation.md → ...utorials/adding_new_device_formulation.md b/...er_guide/adding_new_device_formulation.md → ...utorials/adding_new_device_formulation.md