Skip to content

Commit

Permalink
update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
mcosovic committed Sep 29, 2023
1 parent c04b307 commit 4a5f4a6
Show file tree
Hide file tree
Showing 14 changed files with 255 additions and 235 deletions.
120 changes: 63 additions & 57 deletions docs/src/tutorials/acOptimalPowerFlow.md

Large diffs are not rendered by default.

210 changes: 113 additions & 97 deletions docs/src/tutorials/acPowerFlow.md

Large diffs are not rendered by default.

46 changes: 23 additions & 23 deletions docs/src/tutorials/acdcModel.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,9 +59,9 @@ The equivalent unified ``\pi``-model for a branch ``(i,j) \in \mathcal{E}`` inci

The branch series admittance ``y_{ij}`` is inversely proportional to the branch series impedance ``z_{ij}``:
```math
y_{ij} = \frac{1}{z_{ij}} =
\frac{1}{{r_{ij}} + \text{j}x_{ij}} =
\frac{r_{ij}}{r_{ij}^2 + x_{ij}^2} - \text{j}\frac{x_{ij}}{r_{ij}^2 + x_{ij}^2} = g_{ij} + \text{j}b_{ij},
y_{ij} = \frac{1}{z_{ij}} =
\frac{1}{{r_{ij}} + \text{j}x_{ij}} =
\frac{r_{ij}}{r_{ij}^2 + x_{ij}^2} - \text{j}\frac{x_{ij}}{r_{ij}^2 + x_{ij}^2} = g_{ij} + \text{j}b_{ij},
```
where ``r_{ij}`` is a resistance, ``x_{ij}`` is a reactance, ``g_{ij}`` is a conductance and ``b_{ij}`` is a susceptance of the branch.

Expand Down Expand Up @@ -89,7 +89,7 @@ Within JuliaGrid, the total shunt conductances and susceptances of branches are

The transformer complex ratio ``\alpha_{ij}`` is defined:
```math
\alpha_{ij} = \cfrac{1}{\tau_{ij}}e^{-\text{j}\phi_{ij}},
\alpha_{ij} = \cfrac{1}{\tau_{ij}}e^{-\text{j}\phi_{ij}},
```
where ``\tau_{ij} \neq 0`` is a transformer turns ratio, while ``\phi_{ij}`` is a transformer phase shift angle, always located "from" bus end of the branch. Note, if ``\tau_{ij} = 1`` and ``\phi_{ij} = 0`` the model describes the line. In-phase transformers are defined if ``\tau_{ij} \neq 1``, ``\phi_{ij} = 0``, and ``y_{\text{s}ij} = 0``, while phase-shifting transformers are obtained if ``\tau_{ij} \neq 1``, ``\phi_{ij} \neq 0``, and ``y_{\text{s}ij} = 0``.

Expand Down Expand Up @@ -134,7 +134,7 @@ Let us consider an example, given in Figure 2, that will allow us an easy transi
!!! note "Info"
The current ``\bar{I}_{\text{sh}k}`` follows the convention of coming out from the bus in terms of its direction. When calculating powers related to shunt elements, this current direction is assumed. Therefore, in cases where power is positive, it signifies alignment with the assumed current direction, emerging away from the bus. Conversely, when power is negative, the direction is reversed, indicating a flow towards the bus.

According to the [unified branch model](@ref UnifiedBranchModelTutorials) each branch is described using the system of equations as follows:
According to the [Unified Branch Model](@ref UnifiedBranchModelTutorials) each branch is described using the system of equations as follows:
```math
\begin{bmatrix}
\bar{I}_{pk} \\ \bar{I}_{kp}
Expand Down Expand Up @@ -192,17 +192,17 @@ Next, the system of equations for buses ``i=1, \dots, n`` can be written in the
where ``\mathbf {\bar {V}} \in \mathbb{C}^{n}`` is the vector of bus complex voltages, and ``\mathbf {\bar {I}} \in \mathbb{C}^{n}`` is the vector of complex current injections at buses.

The matrix ``\mathbf{Y} = \mathbf{G} + \text{j}\mathbf{B} \in \mathbb{C}^{n \times n}`` is the bus or nodal admittance matrix, with elements:
* the diagonal elements, where ``i \in \mathcal{N}``, are equal to:
* the diagonal elements, where ``i \in \mathcal{N}``, are equal to:
```math
Y_{ii} = G_{ii} + \text{j}B_{ii} = {y}_{\text{sh}i} +
\sum\limits_{e \in \mathcal{E}, \; e(1) = i} \cfrac{1}{\tau_{ij}^2}({y}_{ij} + y_{\text{s}ij}) + \sum\limits_{e \in \mathcal{E}, \; e(2) = i} ({y}_{ij} + y_{\text{s}ij}),
```
* the non-diagonal elements, where ``i = e(1),\; j = e(2), \; e \in \mathcal{E}``, are equal to:
* the non-diagonal elements, where ``i = e(1),\; j = e(2), \; e \in \mathcal{E}``, are equal to:
```math
Y_{ij} = G_{ij} + \text{j}B_{ij} = -\alpha_{ij}^*{y}_{ij}
```
```math
Y_{ji} = G_{ji} + \text{j}B_{ji} = -\alpha_{ij}{y}_{ij}.
Y_{ji} = G_{ji} + \text{j}B_{ji} = -\alpha_{ij}{y}_{ij}.
```

When a branch is not incident (or adjacent) to a bus the corresponding element in the nodal admittance matrix ``\mathbf{Y}`` is equal to zero. The nodal admittance matrix ``\mathbf{Y}`` is a sparse (i.e., a small number of elements are non-zeros) for real-world power systems. Although it is often assumed that the matrix ``\mathbf{Y}`` is symmetrical, it is not a general case, for example, in the presence of phase shifting transformers the matrix ``\mathbf{Y}`` is not symmetrical [[2, Sec. 9.6]](@ref ACDCModelReferenceTutorials). JuliaGrid stores both the matrix ``\mathbf{Y}`` and its transpose ``\mathbf{Y}^T`` in the `ac` field of the `PowerSystem` composite type:
Expand All @@ -223,18 +223,18 @@ nothing # hide
---

##### [Unified Branch Model](@id DCUnifiedBranchModelTutorials)
According to the above assumptions, we start from the [unified branch model](@ref UnifiedBranchModelTutorials):
According to the above assumptions, we start from the [Unified Branch Model](@ref UnifiedBranchModelTutorials):
```math
\begin{bmatrix}
\bar{I}_{ij} \\ \bar{I}_{ji}
\end{bmatrix} = \cfrac{1}{\text{j}x_{ij}}
\begin{bmatrix}
\cfrac{1}{\tau_{ij}^2} && -\alpha_{ij}^*\\
-\alpha_{ij} && 1
\end{bmatrix}
\begin{bmatrix}
\bar{V}_{i} \\ \bar{V}_{j}
\end{bmatrix},
\begin{bmatrix}
\bar{I}_{ij} \\ \bar{I}_{ji}
\end{bmatrix} = \cfrac{1}{\text{j}x_{ij}}
\begin{bmatrix}
\cfrac{1}{\tau_{ij}^2} && -\alpha_{ij}^*\\
-\alpha_{ij} && 1
\end{bmatrix}
\begin{bmatrix}
\bar{V}_{i} \\ \bar{V}_{j}
\end{bmatrix},
```
where ``\bar{V}_{i} = \text{e}^{\text{j}\theta_{i}}`` and ``\bar{V}_{j} = \text{e}^{\text{j}\theta_{j}}``. Further, we have:
```math
Expand Down Expand Up @@ -272,7 +272,7 @@ Furthermore, the computed branch admittances in the DC framework are stored in t
𝐲 = system.model.dc.admittance
```

We can conclude that ``P_{ij}=-P_{ji}`` holds. With the DC model, the linear network equations relate active powers to bus voltage angles, versus complex currents to complex bus voltages in the AC model [[3]](@ref ACDCModelReferenceTutorials). Consequently, analogous to the [unified branch model](@ref UnifiedBranchModelTutorials) we can write:
We can conclude that ``P_{ij}=-P_{ji}`` holds. With the DC model, the linear network equations relate active powers to bus voltage angles, versus complex currents to complex bus voltages in the AC model [[3]](@ref ACDCModelReferenceTutorials). Consequently, analogous to the [Unified Branch Model](@ref UnifiedBranchModelTutorials) we can write:
```math
\begin{bmatrix}
P_{ij} \\ P_{ji}
Expand Down Expand Up @@ -378,7 +378,7 @@ The vector ``\mathbf {P} \in \mathbb{R}^{n}`` contains active power injections a

The vector ``\mathbf{P_\text{tr}} \in \mathbb{R}^{n}`` represents active powers related to the non-zero shift angle of transformers. This vector is stored in the `dc` field, and we can access it using:
```@repl ACDCModel
𝐏ₜᵣ = system.model.dc.shiftActivePower
𝐏ₜᵣ = system.model.dc.shiftPower
```

The vector ``\mathbf{P}_\text{sh} \in \mathbb{R}^{n}`` represents active powers consumed by shunt elements. We can access this vector using:
Expand All @@ -387,11 +387,11 @@ The vector ``\mathbf{P}_\text{sh} \in \mathbb{R}^{n}`` represents active powers
```

The bus or nodal matrix in the DC framework is given as ``\mathbf{B} \in \mathbb{C}^{n \times n}``, with elements:
* the diagonal elements, where ``i \in \mathcal{N}``, are equal to:
* the diagonal elements, where ``i \in \mathcal{N}``, are equal to:
```math
B_{ii} = \sum\limits_{e \in \mathcal{E},\; i \in e} \cfrac{1}{\tau_{ij}x_{ij}},
```
* the non-diagonal elements, where ``i = e(1),\; j = e(2), \; e \in \mathcal{E}``, are equal to:
* the non-diagonal elements, where ``i = e(1),\; j = e(2), \; e \in \mathcal{E}``, are equal to:
```math
B_{ij} = -\cfrac{1}{\tau_{ij}x_{ij}}
```
Expand Down
23 changes: 11 additions & 12 deletions docs/src/tutorials/dcOptimalPowerFlow.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ Moreover, we identify the set of generators as ``\mathcal{P} = \{1, \dots, n_g\}
In the DC optimal power flow, the active power outputs of the generators ``\mathbf {P}_{\text{g}} = [{P}_{\text{g}i}]``, ``i \in \mathcal{P}``, are represented as linear functions of the bus voltage angles ``\boldsymbol{\theta} = [{\theta}_{i}]``, ``i \in \mathcal{N}``. Therefore, the optimization variables in this model are the active power outputs of the generators and the bus voltage angles. The DC optimal power flow model has the form:
```math
\begin{aligned}
& {\text{minimize}} & & \sum_{i=1}^{n_\text{g}} f_i(P_{\text{g}i}) \\
& {\text{minimize}} & & \sum_{i \in \mathcal{P}} f_i(P_{\text{g}i}) \\
& \text{subject\;to} & & \theta_i - \theta_{\text{slack}} = 0,\;\;\; i \in \mathcal{N_{\text{sb}}} \\[3pt]
& & & h_{P_i}(\mathbf {P}_{\text{g}}, \boldsymbol{\theta}) = 0,\;\;\; \forall i \in \mathcal{N} \\[3pt]
& & & \theta_{ij}^\text{min} \leq \theta_i - \theta_j \leq \theta_{ij}^\text{max},\;\;\; \forall (i,j) \in \mathcal{E} \\[3pt]
Expand Down Expand Up @@ -181,18 +181,17 @@ The second equality constraint in the optimization problem is associated with th
```math
h_{P_i}(\mathbf {P}_{\text{g}}, \boldsymbol{\theta}) = 0,\;\;\; \forall i \in \mathcal{N}.
```
The equation is derived using the [unified branch model](@ref DCUnifiedBranchModelTutorials) and can be represented as:
The equation is derived using the [Unified Branch Model](@ref DCUnifiedBranchModelTutorials) and can be represented as:
```math
h_{P_i}(\mathbf {P}_{\text{g}}, \boldsymbol{\theta}) = \sum_{k=1}^{n_{\text{g}i}} P_{\text{g}k} - \sum_{k = 1}^n {B}_{ik} \theta_k - P_{\text{d}i} - P_{\text{sh}i} - P_{\text{tr}i}.
h_{P_i}(\mathbf {P}_{\text{g}}, \boldsymbol{\theta}) = \sum_{k \in \mathcal{P}_i} P_{\text{g}k} - \sum_{k = 1}^n {B}_{ik} \theta_k - P_{\text{d}i} - P_{\text{sh}i} - P_{\text{tr}i}.
```

In the equation above, ``P_{\text{g}k}`` represents the active power output of the ``k``-th generator connected to bus ``i \in \mathcal{N}``, and ``n_{\text{g}i}`` denotes the total number of generators connected to the same bus. More precisely, the variable ``P_{\text{g}k}`` represents the optimization variables, as well as the bus voltage angle ``\theta_k``.
In this equation, the set ``\mathcal{P}_i \subseteq \mathcal{P}`` encompasses all generators connected to bus ``i \in \mathcal{N}``, and ``P_{\text{g}k}`` represents the active power output of the ``k``-th generator within the set ``\mathcal{P}_i``. More precisely, the variable ``P_{\text{g}k}`` represents the optimization variable, as well as the bus voltage angle ``\theta_k``.

The constant terms in these equations are determined by the active power demand at bus ``P_{\text{d}i}``, the active power demanded by the shunt element ``P_{\text{sh}i}``, and power related to the shift angle of the phase transformers ``P_{\text{tr}i}``. The values representing these constant terms ``\mathbf{P}_{\text{d}} = [P_{\text{d}i}]``, ``\mathbf{P}_{\text{sh}} = [P_{\text{sh}i}]``, and ``\mathbf{P}_{\text{tr}} = [P_{\text{tr}i}]``, ``i, \in \mathcal{N}``, can be accessed as follows:
```@repl DCOptimalPowerFlow
𝐏ₒ = system.bus.demand.active
𝐏ₛₕ = system.bus.shunt.conductance
𝐏ₜᵣ = system.model.dc.shiftActivePower
𝐏ₜᵣ = system.model.dc.shiftPower
```

To retrieve this equality constraint from the model and access the corresponding variable, you can use the following code:
Expand Down Expand Up @@ -229,7 +228,7 @@ Here, the lower and upper bounds are determined based on the vector ``\mathbf{P}
𝐏ₘₐₓ = system.branch.flow.longTerm
```

The active power flow at branch ``(i,j) \in \mathcal{E}`` can be derived using the [unified branch model](@ref DCUnifiedBranchModelTutorials) and is given by the equation:
The active power flow at branch ``(i,j) \in \mathcal{E}`` can be derived using the [Unified Branch Model](@ref DCUnifiedBranchModelTutorials) and is given by the equation:
```math
h_{P_{ij}}(\theta_i, \theta_j) = \frac{1}{\tau_{ij} x_{ij} }(\theta_i - \theta_j - \phi_{ij}).
```
Expand Down Expand Up @@ -287,14 +286,14 @@ nothing # hide
```

!!! note "Info"
For a clear comprehension of the equations, symbols provided below, as well as for a better grasp of power directions, please refer to the [unified branch model](@ref UnifiedBranchModelTutorials).
For a clear comprehension of the equations, symbols provided below, as well as for a better grasp of power directions, please refer to the [Unified Branch Model](@ref UnifiedBranchModelTutorials).

---

##### Active Power Injections
To obtain the active power injection at buses, we can refer to section [DC Model](@ref DCModelTutorials), which provides the following expression:
```math
P_i = \sum_{j = 1}^n {B}_{ij} \theta_j + P_{\text{tr}i} + P_{\text{sh}i},\;\;\; i \in \mathcal{N}.
P_i = \sum_{j = 1}^n {B}_{ij} \theta_j + P_{\text{tr}i} + P_{\text{sh}i},\;\;\; \forall i \in \mathcal{N}.
```
Active power injections are stored as the vector ``\mathbf{P} = [P_i]``, and can be retrieved using the following commands:
```@repl DCOptimalPowerFlow
Expand All @@ -306,7 +305,7 @@ Active power injections are stored as the vector ``\mathbf{P} = [P_i]``, and can
##### Active Power Injections from the Generators
The active power supplied by generators to the buses can be calculated by summing the active power outputs of the generators obtained from the optimal DC power flow. This can be expressed as:
```math
P_{\text{s}i} = \sum_{k=1}^{n_{\text{g}i}} P_{\text{g}k},\;\;\; i \in \mathcal{N}.
P_{\text{s}i} = \sum_{k=1}^{n_{\text{g}i}} P_{\text{g}k},\;\;\; \forall i \in \mathcal{N}.
```
Here, ``P_{\text{g}k}`` represents the active power output of the ``k``-th generator connected to bus ``i \in \mathcal{N}``, and ``n_{\text{g}i}`` denotes the total number of generators connected to the same bus. We can obtain the vector of active power injected by generators to the buses, denoted as ``\mathbf{P}_{\text{s}} = [P_{\text{s}i}]``, using the following command:
```@repl DCOptimalPowerFlow
Expand All @@ -318,7 +317,7 @@ Here, ``P_{\text{g}k}`` represents the active power output of the ``k``-th gener
##### Active Power Flows
The active power flow at each "from" bus end ``i \in \mathcal{N}`` of branches can be obtained using the following equations:
```math
P_{ij} = \cfrac{1}{\tau_{ij} x_{ij}} (\theta_{i} -\theta_{j}-\phi_{ij}),\;\;\; (i,j) \in \mathcal{E}.
P_{ij} = \cfrac{1}{\tau_{ij} x_{ij}} (\theta_{i} -\theta_{j}-\phi_{ij}),\;\;\; \forall (i,j) \in \mathcal{E}.
```
The resulting active power flows are stored as the vector ``\mathbf{P}_{\text{i}} = [P_{ij}]``, which can be retrieved using the following command:
```@repl DCOptimalPowerFlow
Expand All @@ -327,7 +326,7 @@ The resulting active power flows are stored as the vector ``\mathbf{P}_{\text{i}

Similarly, the active power flow at each "to" bus end ``j \in \mathcal{N}`` of branches can be obtained as:
```math
P_{ji} = - P_{ij},\;\;\; (i,j) \in \mathcal{E}.
P_{ji} = - P_{ij},\;\;\; \forall (i,j) \in \mathcal{E}.
```
The resulting active power flows are stored as the vector ``\mathbf{P}_{\text{j}} = [P_{ji}]``, which can be retrieved using the following command:
```@repl DCOptimalPowerFlow
Expand Down
20 changes: 10 additions & 10 deletions docs/src/tutorials/dcPowerFlow.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# [DC Power Flow](@id DCPowerFlowTutorials)

JuliaGrid employs standard network components and the [unified branch model](@ref DCUnifiedBranchModelTutorials) to obtain the DC power flow solution. To begin, the `PowerSystem` composite type must be provided to JuliaGrid through the use of the [`powerSystem`](@ref powerSystem) function, as illustrated by the following example:
JuliaGrid employs standard network components and the [Unified Branch Model](@ref DCUnifiedBranchModelTutorials) to obtain the DC power flow solution. To begin, the `PowerSystem` composite type must be provided to JuliaGrid through the use of the [`powerSystem`](@ref powerSystem) function, as illustrated by the following example:
```@example PowerFlowSolutionDC
using JuliaGrid # hide
@default(unit) # hide
Expand Down Expand Up @@ -94,14 +94,14 @@ nothing # hide
```

!!! note "Info"
For a clear comprehension of the equations, symbols provided below, as well as for a better grasp of power directions, please refer to the [unified branch model](@ref UnifiedBranchModelTutorials).
For a clear comprehension of the equations, symbols provided below, as well as for a better grasp of power directions, please refer to the [Unified Branch Model](@ref UnifiedBranchModelTutorials).

---

##### Active Power Injections
To obtain the active power injection at buses, we can refer to section [DC Model](@ref DCModelTutorials), which provides the following expression:
```math
P_i = \sum_{j = 1}^n {B}_{ij} \theta_j + P_{\text{tr}i} + P_{\text{sh}i},\;\;\; i \in \mathcal{N}.
P_i = \sum_{j = 1}^n {B}_{ij} \theta_j + P_{\text{tr}i} + P_{\text{sh}i},\;\;\; \forall i \in \mathcal{N}.
```
Active power injections are stored as the vector ``\mathbf{P} = [P_i]``, and can be retrieved using the following commands:
```@repl PowerFlowSolutionDC
Expand All @@ -113,7 +113,7 @@ Active power injections are stored as the vector ``\mathbf{P} = [P_i]``, and can
##### Active Power Injections from the Generators
The active power supplied by generators to the buses can be calculated by summing the given generator active powers in the input data, except for the slack bus, which can be determined as:
```math
P_{\text{s}i} = P_i + P_{\text{d}i},\;\;\; i \in \mathcal{N}_{\text{sb}},
P_{\text{s}i} = P_i + P_{\text{d}i},\;\;\; \forall i \in \mathcal{N}_{\text{sb}},
```
where ``P_{\text{d}i}`` represents the active power demanded by consumers at the slack bus. The vector of active power injected by generators to the buses, denoted by ``\mathbf{P}_{\text{s}} = [P_{\text{s}i}]``, can be obtained using the following command:
```@repl PowerFlowSolutionDC
Expand All @@ -125,7 +125,7 @@ where ``P_{\text{d}i}`` represents the active power demanded by consumers at the
##### Active Power Flows
The active power flow at each "from" bus end ``i \in \mathcal{N}`` of branches can be obtained using the following equations:
```math
P_{ij} = \cfrac{1}{\tau_{ij} x_{ij}} (\theta_{i} -\theta_{j}-\phi_{ij}),\;\;\; (i,j) \in \mathcal{E}.
P_{ij} = \cfrac{1}{\tau_{ij} x_{ij}} (\theta_{i} -\theta_{j}-\phi_{ij}),\;\;\; \forall (i,j) \in \mathcal{E}.
```
The resulting active power flows are stored as the vector ``\mathbf{P}_{\text{i}} = [P_{ij}]``, which can be retrieved using the following command:
```@repl PowerFlowSolutionDC
Expand All @@ -134,7 +134,7 @@ The resulting active power flows are stored as the vector ``\mathbf{P}_{\text{i}

Similarly, the active power flow at each "to" bus end ``j \in \mathcal{N}`` of branches can be obtained as:
```math
P_{ji} = - P_{ij},\;\;\; (i,j) \in \mathcal{E}.
P_{ji} = - P_{ij},\;\;\; \forall (i,j) \in \mathcal{E}.
```
The resulting active power flows are stored as the vector ``\mathbf{P}_{\text{j}} = [P_{ji}]``, which can be retrieved using the following command:
```@repl PowerFlowSolutionDC
Expand All @@ -148,9 +148,9 @@ The output active power of each generator located at bus ``i \in \mathcal{N}_{\t
```math
P_{\text{g}i} = P_i + P_{\text{d}i},\;\;\; i \in \mathcal{N}_{\text{sb}}.
```
In the case of multiple generators connected to the slack bus, the first generator in the input data is assigned the obtained value of ``P_{\text{g}i}``. Then, this amount of power is reduced by the output active power of the other generators. Therefore, to get the vector of output active power of generators, i.e., ``\mathbf{P}_{\text{g}} = [P_{\text{g}i}]``, you can use the following command:
In the case of multiple generators connected to the slack bus, the first generator in the input data is assigned the obtained value of ``P_{\text{g}i}``. Then, this amount of power is reduced by the output active power of the other generators.

To retrieve the vector of active power outputs of generators, denoted as ``\mathbf{P}_{\text{g}} = [P_{\text{g}i}]``, ``i \in \mathcal{P}``, where the set ``\mathcal{P}`` represents the set of generators, users can utilize the following command:
```@repl PowerFlowSolutionDC
𝐏ₒ = analysis.power.generator.active
```

Please take into consideration that in this context, the term ``P_{\text{g}i}`` is interconnected with the group of generators represented by the set ``\mathcal{P} = \{1, \dots, n_g\}``.
```
2 changes: 1 addition & 1 deletion src/definition/powerSystem.jl
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ end
mutable struct DCModel
nodalMatrix::SparseMatrixCSC{Float64,Int64}
admittance::Array{Float64,1}
shiftActivePower::Array{Float64,1}
shiftPower::Array{Float64,1}
end

########### AC Model ###########
Expand Down
Loading

0 comments on commit 4a5f4a6

Please sign in to comment.