Massive update documentation for PowerSimulations #1099

rodrigomha · 2024-04-23T00:08:08Z

Preview PR docs: Not working for now

Massive update on docstrings and markdowns for documentation of PowerSimulations.

I will update the nomenclature to follow the following structure:

Lowercase letters are used for variables, e.g., p for power.
Uppercase letters are used for parameters, e.g., C for costs.
Subscripts are used for indexing, e.g., (\cdot)_t for indexing at time t.
Superscripts are used for descriptions, e.g., (\cdot)^\text{th} to describe a thermal (th) variable/parameter.
Bold letters are used for vectors, e.g., \boldsymbol{p} = \{p\}_{1,\dots,24}.

TODO for formulations:

TODO docs:

Simulation feedforwards
Debugging infeasible models

TODO definitions:

TODO docstrings:

Docstrings

For next round of documentation:

Model developer guide: DeviceModel
Model developer guide: DecisionModel
Subsystem explanations

add fix to service bid

github-actions · 2024-04-23T00:52:45Z

Performance Results

Version	Precompile Time
Main	3.306117011
This Branch	3.412366792

Version	Build Time
Main-Build Time Precompile	49.97515415
Main-Build Time Postcompile	2.359731154
This Branch-Build Time Precompile	54.540582953
This Branch-Build Time Postcompile	2.515036504

Version	Solve Time
Main-Solve Time Precompile	651.675156431
Main-Solve Time Postcompile	639.978951977
This Branch-Solve Time Precompile	391.359268194
This Branch-Solve Time Postcompile	365.7897431

rodrigomha · 2024-04-26T22:26:46Z

Preview is broken for now, given the requirements of using other branches of PSY and IS

jd-lara · 2024-04-26T22:47:36Z

src/core/formulations.jl

@@ -33,7 +33,7 @@ Formulation type to enable standard dispatch with a range and enforce intertempo
 """
 struct ThermalStandardDispatch <: AbstractThermalDispatchFormulation end
 """
-Formulation type to enable basic dispatch without any intertemporal constraints and relaxed minimum generation. *may not work with PWL cost definitions*


Only in non-convex cases.

rodrigomha · 2024-05-11T05:04:38Z

I'm done with this docs for now @jd-lara @claytonpbarrows

jd-lara · 2024-05-13T17:20:21Z

docs/src/formulation_library/Branch.md

@@ -1,67 +1,356 @@
 # `PowerSystems.Branch` Formulations

+!!! note
+    The usage of reactive power variables and constraints will depend on the network model used, i.e. if it uses (or not) reactive power. If the network model is purely active power based, then no variables and constraints related to reactive power are created. For the sake of completion, if the formulation allows the usage of reactive power it will be included.


Suggested change

The usage of reactive power variables and constraints will depend on the network model used, i.e. if it uses (or not) reactive power. If the network model is purely active power based, then no variables and constraints related to reactive power are created. For the sake of completion, if the formulation allows the usage of reactive power it will be included.

The use of reactive power variables and constraints will depend on the network model used, i.e., whether it uses (or does not use) reactive power. If the network model is purely active power-based, reactive power variables and related constraints are not created.

jd-lara · 2024-05-13T17:30:22Z

docs/src/formulation_library/Feedforward.md

+In PowerSimulations, chronologies define where information is flowing. There are two types
+of chronologies.
+
+- inter-stage chronologies: Define how information flows between stages. e.g. day-ahead solutions are used to inform economic dispatch problems
+- intra-stage chronologies: Define how information flows between multiple executions of a single stage. e.g. the dispatch setpoints of the first period of an economic dispatch problem are constrained by the ramping limits from setpoints in the final period of the previous problem.
+
+The definition of exactly what information is passed using the defined chronologies is accomplished using **FeedForwards**.
+
+Specifically, a FeedForward is used to define what to do with information being passed with an inter-stage chronology in a Simulation. The most common FeedForward is the `SemiContinuousFeedForward` that affects the semi-continuous range constraints of thermal generators in the economic dispatch problems based on the value of the (already solved) unit-commitment variables.
+
+The creation of a FeedForward requires at least to specify the `component_type` on which the FeedForward will be applied. The `source` variable specify which variable will be taken from the problem solved, for example the commitment variable of the thermal unit in the unit commitment problem. Finally, the `affected_values` specify which variables will be affected in the problem to be solved, for example the next economic dispatch problem.


Suggested change

In PowerSimulations, chronologies define where information is flowing. There are two types

of chronologies.

- inter-stage chronologies: Define how information flows between stages. e.g. day-ahead solutions are used to inform economic dispatch problems

- intra-stage chronologies: Define how information flows between multiple executions of a single stage. e.g. the dispatch setpoints of the first period of an economic dispatch problem are constrained by the ramping limits from setpoints in the final period of the previous problem.

The definition of exactly what information is passed using the defined chronologies is accomplished using **FeedForwards**.

Specifically, a FeedForward is used to define what to do with information being passed with an inter-stage chronology in a Simulation. The most common FeedForward is the `SemiContinuousFeedForward` that affects the semi-continuous range constraints of thermal generators in the economic dispatch problems based on the value of the (already solved) unit-commitment variables.

The creation of a FeedForward requires at least to specify the `component_type` on which the FeedForward will be applied. The `source` variable specify which variable will be taken from the problem solved, for example the commitment variable of the thermal unit in the unit commitment problem. Finally, the `affected_values` specify which variables will be affected in the problem to be solved, for example the next economic dispatch problem.

**FeedForwards** are the mechanism to define how information is shared between models. Specifically, a FeedForward defines what to do with information passed with an inter-stage chronology in a Simulation. The most common FeedForward is the `SemiContinuousFeedForward` that affects the semi-continuous range constraints of thermal generators in the economic dispatch problems based on the value of the (already solved) unit-commitment variables.

The creation of a FeedForward requires at least specifying the `component_type` on which the FeedForward will be applied. The `source` variable specifies which variable will be taken from the problem solved, for example, the commitment variable of the thermal unit in the unit commitment problem. Finally, the `affected_values` specify which variables will be affected in the problem to be solved, for example, the next economic dispatch problem.

I removed the chronologies mentioned since that's related to the initial conditions and not specifically to the feedforwards.

jd-lara · 2024-05-13T17:32:14Z

docs/src/formulation_library/Feedforward.md

+
+**Parameters:**
+
+The parameter `FixValueParameter` is used to match the result obtained from the source variable (from an upper level problem).


Suggested change

The parameter `FixValueParameter` is used to match the result obtained from the source variable (from an upper level problem).

The parameter `FixValueParameter` is used to match the result obtained from the source variable (from the simulation state).

jd-lara · 2024-05-13T17:40:54Z

docs/src/formulation_library/Feedforward.md

+
+**Parameters:**
+
+The parameter `LowerBoundValueParameter` is used to store the result obtained from the source variable (from an upper level problem) that will be used as a lower bound to the affected variable.


Suggested change

The parameter `LowerBoundValueParameter` is used to store the result obtained from the source variable (from an upper level problem) that will be used as a lower bound to the affected variable.

The parameter `LowerBoundValueParameter` is used to store the result obtained from the source variable (from the simulation state) that will be used as a lower bound to the affected variable.

we should not mention this upper level state etc.

jd-lara · 2024-05-13T17:46:17Z

docs/src/formulation_library/General.md

@@ -118,7 +118,7 @@ Adds an objective function cost term according to:

 **Impact of different cost configurations:**

-The following table describes all possible configuration of the `StorageManagementCost` with the target constraint in hydro or storage device models. Cases 1(a) & 2(a) will have no impact of the models operations and the target constraint will be rendered useless. In most cases that have no energy target and a non-zero value for ``C^{value}``, if this cost is too high (``C^{value} >> 0``) or too low (``C^{value} <<0``) can result in either the model holding on to stored energy till the end or the model not storing any energy in the device. This is caused by the fact that when energy target is zero, we have ``E_t = - E^{shortage}_t``, and ``- E^{shortage}_t * C^{value}`` in the objective function is replaced by ``E_t * C^{value}``, thus resulting in ``C^{value}`` to be seen as the cost of stored energy.
+The following table describes all possible configuration of the `StorageCost` with the target constraint in hydro or storage device models. Cases 1(a) & 2(a) will have no impact of the models operations and the target constraint will be rendered useless. In most cases that have no energy target and a non-zero value for ``C^{value}``, if this cost is too high (``C^{value} >> 0``) or too low (``C^{value} <<0``) can result in either the model holding on to stored energy till the end or the model not storing any energy in the device. This is caused by the fact that when energy target is zero, we have ``E_t = - E^{shortage}_t``, and ``- E^{shortage}_t * C^{value}`` in the objective function is replaced by ``E_t * C^{value}``, thus resulting in ``C^{value}`` to be seen as the cost of stored energy.


Suggested change

The following table describes all possible configuration of the `StorageCost` with the target constraint in hydro or storage device models. Cases 1(a) & 2(a) will have no impact of the models operations and the target constraint will be rendered useless. In most cases that have no energy target and a non-zero value for ``C^{value}``, if this cost is too high (``C^{value} >> 0``) or too low (``C^{value} <<0``) can result in either the model holding on to stored energy till the end or the model not storing any energy in the device. This is caused by the fact that when energy target is zero, we have ``E_t = - E^{shortage}_t``, and ``- E^{shortage}_t * C^{value}`` in the objective function is replaced by ``E_t * C^{value}``, thus resulting in ``C^{value}`` to be seen as the cost of stored energy.

The following table describes all possible configurations of the `StorageCost` with the target constraint in hydro or storage device models. Cases 1(a) & 2(a) will not impact the model's operations, and the target constraint will be rendered useless. In most cases that have no energy target and a non-zero value for ``C^{value}``, if this cost is too high (``C^{value} >> 0``) or too low (``C^{value} <<0``) can result in either the model holding on to stored energy till the end of the model not storing any energy in the device. This is caused by the fact that when the energy target is zero, we have ``E_t = - E^{shortage}_t``, and ``- E^{shortage}_t * C^{value}`` in the objective function is replaced by ``E_t * C^{value}``, thus resulting in ``C^{value}`` to be seen as the cost of stored energy.

jd-lara · 2024-05-13T17:46:56Z

docs/src/formulation_library/Introduction.md

+\end{align*}
+```
+
+Note that the `StaticPowerLoad` does not impose any cost to the objective function or any constraint, but add its power demand to the supply-balance demand of the `CopperPlatePowerModel` used. Since we are using the `ThermalDispatchNoMin` formulation for the thermal generation, the lower bound for the power is 0, instead of ``P^\text{th,min}``. In addition, we are assuming a linear cost ``C^\text{th}``. Finally, the `RenewableFullDispatch` formulation allows the dispatch of the renewable unit to be between 0 and its maximum injection time series ``p_t^\text{re,param}``.


Suggested change

Note that the `StaticPowerLoad` does not impose any cost to the objective function or any constraint, but add its power demand to the supply-balance demand of the `CopperPlatePowerModel` used. Since we are using the `ThermalDispatchNoMin` formulation for the thermal generation, the lower bound for the power is 0, instead of ``P^\text{th,min}``. In addition, we are assuming a linear cost ``C^\text{th}``. Finally, the `RenewableFullDispatch` formulation allows the dispatch of the renewable unit to be between 0 and its maximum injection time series ``p_t^\text{re,param}``.

Note that the `StaticPowerLoad` does not impose any cost to the objective function or constraint but adds its power demand to the supply-balance demand of the `CopperPlatePowerModel` used. Since we are using the `ThermalDispatchNoMin` formulation for the thermal generation, the lower bound for the power is 0, instead of ``P^\text{th,min}``. In addition, we are assuming a linear cost ``C^\text{th}``. Finally, the `RenewableFullDispatch` formulation allows the dispatch of the renewable unit between 0 and its maximum injection time series ``p_t^\text{re,param}``.

jd-lara · 2024-05-13T17:47:21Z

docs/src/formulation_library/Introduction.md

+In the formulations described in the other pages, the nomenclature is as follows:
+- Lowercase letters are used for variables, e.g., ``p`` for power.
+- Uppercase letters are used for parameters, e.g., ``C`` for costs.
+- Subscripts are used for indexing, e.g., ``(\cdot)_t`` for indexing at time ``t``.
+- Superscripts are used for descriptions, e.g., ``(\cdot)^\text{th}`` to describe a thermal (th) variable/parameter.
+- Bold letters are used for vectors, e.g., ``\boldsymbol{p} = \{p\}_{1,\dots,24}``.


Suggested change

In the formulations described in the other pages, the nomenclature is as follows:

- Lowercase letters are used for variables, e.g., ``p`` for power.

- Uppercase letters are used for parameters, e.g., ``C`` for costs.

- Subscripts are used for indexing, e.g., ``(\cdot)_t`` for indexing at time ``t``.

- Superscripts are used for descriptions, e.g., ``(\cdot)^\text{th}`` to describe a thermal (th) variable/parameter.

- Bold letters are used for vectors, e.g., ``\boldsymbol{p} = \{p\}_{1,\dots,24}``.

In the formulations described in the other pages, the nomenclature is as follows:

- Lowercase letters are used for variables, e.g., ``p`` for power.

- Uppercase letters are used for cost parameters, e.g., ``C``.

- Subscripts are used for indexing, e.g., ``(\cdot)_t`` for indexing at time ``t``.

- Superscripts are used for descriptions, e.g., ``(\cdot)^\text{th}`` to describe a thermal (th) variable/parameter.

- Bold letters are used for vectors, e.g., ``\boldsymbol{p} = \{p\}_{1,\dots,24}``.

jd-lara · 2024-05-13T17:48:12Z

docs/src/formulation_library/Load.md

-mdtable(combo_table, latex = false)
-```
+!!! note
+    The usage of reactive power variables and constraints will depend on the network model used, i.e. if it uses (or not) reactive power. If the network model is purely active power based, then no variables and constraints related to reactive power are created. For the sake of completion, if the formulation allows the usage of reactive power it will be included.


Suggested change

The usage of reactive power variables and constraints will depend on the network model used, i.e. if it uses (or not) reactive power. If the network model is purely active power based, then no variables and constraints related to reactive power are created. For the sake of completion, if the formulation allows the usage of reactive power it will be included.

The use of reactive power variables and constraints will depend on the network model used, i.e., whether it uses (or does not use) reactive power. If the network model is purely active power-based, reactive power variables and related constraints are not created.

jd-lara · 2024-05-13T17:48:55Z

docs/src/formulation_library/Feedforward.md

+
+**Parameters:**
+
+The parameter `UpperBoundValueParameter` is used to store the result obtained from the source variable (from an upper level problem) that will be used as an upper bound to the affected variable.


Suggested change

The parameter `UpperBoundValueParameter` is used to store the result obtained from the source variable (from an upper level problem) that will be used as an upper bound to the affected variable.

The parameter `UpperBoundValueParameter` stores the result obtained from the source variable (from the state) that will be used as an upper bound to the affected variable.

jd-lara · 2024-05-13T17:50:48Z

docs/src/formulation_library/Service.md

+
+**Objective:**
+
+The `ServiceRequirementVariable` is added as a piecewise linear cost based on the decreasing offers listed in the `variable_cost` time series. These decreasing cost represent the scarcity prices of not having sufficient reserves. For example, if the variable ``\text{req} = 0``, then a really high cost is paid for not having enough reserves, and if ``\text{req}`` is larger, then a lower cost (or even zero) is paid. TODO: actual implementation. 


Still a TODO?

jd-lara · 2024-05-13T19:02:36Z

I think the PR looks good for now for me but I am worried about not catching typos and such
we need to review in detail before release

jd-lara and others added 8 commits March 26, 2024 18:07

add fix to service bid

7004603

undo changes

36ef59b

Merge pull request #1096 from NREL-Sienna/jd/fix_service_bid

9730681

add fix to service bid

Update Project.toml

2334364

add Introduction for formulations

4c82558

update Network formulations

37bc1a4

update docstrings

badd6a7

reorder make.jl

a6cb30b

rodrigomha added the documentation label Apr 23, 2024

rodrigomha requested review from claytonpbarrows and jd-lara April 23, 2024 00:08

rodrigomha self-assigned this Apr 23, 2024

jd-lara changed the base branch from main to psy4 April 23, 2024 16:32

rodrigomha added 4 commits April 25, 2024 17:12

add three thermal formulations

2805166

update formulation typo

1d5339c

update docstring

f294d93

add additional thermal formulations

cdf7410

jd-lara reviewed Apr 26, 2024

View reviewed changes

rodrigomha added 10 commits April 29, 2024 12:15

update variable symbols

5177413

update docstrings for formulations

346a313

export slack for flows

add41c3

add service TODO docs

ff2b8f1

update network docs

018b28b

update renewable docs

d332f45

update load docs

7164f3a

update branch docs

2b4a6bc

export slack flow variables

21f8ab8

fix typo

7a071a0

rodrigomha added 8 commits May 10, 2024 20:37

add phaseshifter docs

fb5e024

update docstrings

3c45bb5

fix continous typo to continuous

704559f

add docstring to ff slack variables

24b0ba2

add docstrings to ff structs

c70185b

update ff docstrings

1603655

finish ff docs

69fb26e

Merge branch 'psy4' into team/psi_docs_efforts

9ee8324

rodrigomha marked this pull request as ready for review May 11, 2024 05:04

rodrigomha changed the base branch from psy4 to rh/cost_funcs_updates_psy4 May 11, 2024 05:20

rodrigomha added 3 commits May 10, 2024 22:21

Merge branch 'rh/cost_funcs_updates_psy4' into team/psi_docs_efforts

ebee15c

update typos

45e9cce

Merge branch 'rh/cost_funcs_updates_psy4' into team/psi_docs_efforts

abd8295

jd-lara reviewed May 13, 2024

View reviewed changes

update reactive power note

7b1ab3e

jd-lara reviewed May 13, 2024

View reviewed changes

rodrigomha added 2 commits May 13, 2024 11:13

update comments

59c0ba4

fix typo

2fce166

rodrigomha merged commit 34b9c5e into rh/cost_funcs_updates_psy4 May 13, 2024
1 of 6 checks passed

jd-lara deleted the team/psi_docs_efforts branch May 15, 2024 06:34

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Massive update documentation for PowerSimulations #1099

Massive update documentation for PowerSimulations #1099

rodrigomha commented Apr 23, 2024 •

edited

Loading

github-actions bot commented Apr 23, 2024

rodrigomha commented Apr 26, 2024

jd-lara Apr 26, 2024

rodrigomha commented May 11, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara May 13, 2024

jd-lara commented May 13, 2024

	The usage of reactive power variables and constraints will depend on the network model used, i.e. if it uses (or not) reactive power. If the network model is purely active power based, then no variables and constraints related to reactive power are created. For the sake of completion, if the formulation allows the usage of reactive power it will be included.
	The use of reactive power variables and constraints will depend on the network model used, i.e., whether it uses (or does not use) reactive power. If the network model is purely active power-based, reactive power variables and related constraints are not created.


		Parameters:

		The parameter `FixValueParameter` is used to match the result obtained from the source variable (from an upper level problem).


		Parameters:

		The parameter `LowerBoundValueParameter` is used to store the result obtained from the source variable (from an upper level problem) that will be used as a lower bound to the affected variable.


		Parameters:

		The parameter `UpperBoundValueParameter` is used to store the result obtained from the source variable (from an upper level problem) that will be used as an upper bound to the affected variable.


		Objective:

		The `ServiceRequirementVariable` is added as a piecewise linear cost based on the decreasing offers listed in the `variable_cost` time series. These decreasing cost represent the scarcity prices of not having sufficient reserves. For example, if the variable ``\text{req} = 0``, then a really high cost is paid for not having enough reserves, and if ``\text{req}`` is larger, then a lower cost (or even zero) is paid. TODO: actual implementation.

Massive update documentation for PowerSimulations #1099

Massive update documentation for PowerSimulations #1099

Conversation

rodrigomha commented Apr 23, 2024 • edited Loading

github-actions bot commented Apr 23, 2024

rodrigomha commented Apr 26, 2024

Choose a reason for hiding this comment

rodrigomha commented May 11, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jd-lara commented May 13, 2024

rodrigomha commented Apr 23, 2024 •

edited

Loading