update docs

docs/Project.toml

@@ -4,10 +4,12 @@ JuMP = "4076af6c-e467-56ae-b986-b466b2749572"
 HiGHS = "87dc4568-4c63-4d18-b0c0-bb2238e4078b"
 Ipopt = "b6b21f68-93f8-5de0-b562-5493be1d77c9"
 GLPK = "60bf3e95-4087-53dc-ae20-288a0d20c6a6"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 
 [compat]
 Documenter = "1.0.0"
 JuMP = "1.15.0"
 HiGHS = "1.5.0"
 Ipopt = "1.6.5"
-GLPK = "1.1.3"
+GLPK = "1.1.3"
+DocumenterCitations = "1"

docs/make.jl

@@ -1,16 +1,23 @@
 using Documenter, JuliaGrid
 using JuMP, HiGHS, Ipopt, GLPK
+using DocumenterCitations
+
+bib = CitationBibliography(
+    joinpath(@__DIR__, "src", "references.bib");
+    style=:numeric
+)
 
 makedocs(
     sitename = "JuliaGrid",
     modules = [JuliaGrid],
     clean = false,
     doctest = false,
+    plugins = [bib],
     format = Documenter.HTML(
-        assets = ["assets/tablestyle.css"],
+        assets = ["assets/tablestyle.css", "assets/citations.css"],
         prettyurls = get(ENV, "CI", nothing) == "true",
         collapselevel = 1
-        ),
+    ),
     pages =
         [
         "Introduction" => "index.md",
@@ -47,8 +54,9 @@ makedocs(
             "State Estimation" => "api/stateEstimation.md",
             "Power and Current Analysis" => "api/analysis.md",
             "Setup and Print" => "api/setupPrint.md"
-            ]
-        ],
+            ],
+        "Bibliography" => "bibliography.md",
+        ]
 )
 
 deploydocs(

docs/src/assets/citations.css

@@ -0,0 +1,17 @@
+.citation dl {
+  display: grid;
+  grid-template-columns: max-content auto; }
+.citation dt {
+  grid-column-start: 1; }
+.citation dd {
+  grid-column-start: 2;
+  margin-bottom: 0.75em; }
+.citation ul {
+ padding: 0 0 2.25em 0;
+ margin: 0;
+ list-style: none !important;}
+.citation ul li {
+ text-indent: -2.25em;
+ margin: 0.33em 0.5em 0.5em 2.25em;}
+.citation ol li {
+ padding-left:0.75em;}

docs/src/bibliography.md

@@ -0,0 +1,4 @@
+# Bibliography
+
+```@bibliography
+```

docs/src/index.md

@@ -3,28 +3,60 @@ JuliaGrid
 
 JuliaGrid is a fast, flexible and easy-to-use open-source tool for analysis and modification of power system configurations and measurement data. It represents a comprehensive framework for steady-state power system analysis written in the Julia programming language. The framework is available as a Julia package under MIT License. JuliaGrid is primarily designed for  researchers and academics, providing various state-of-the-art algorithms.
 
-JuliaGrid documentation consists of three main parts:
-* The manual provides users with guidance on how to use available functions, its return values, and offers instructions for modifying power system configurations, measurement data, and other user specific analysis.
-* The tutorials delve deeper into the theoretical underpinnings of state-of-the-art algorithms, allowing users to gain an in-depth understanding of the equations used in various functions.
-* API references offer a comprehensive list of objects, functions and methods within the package, categorised according to specific use-cases.
-
 The fremowork's architecture centres around code-reusability paradigm, allowing users a high level of customization for their experiments. To simplify, the overall logic for setting the experiments and its analysis can be as follows:
 * Users define a power system with/without measurement data.
 * Users select between the AC or DC model.
 * Users define the specific type of required analysis.
 * Finally, they solve the generated power system model.
 
-Below, we have provided a list of exhaustive examples in order to ease users in getting started with the JuliaGrid package. These examples highlight some of the functionalities that the framework offers.
+---
+
+## Installation Guide
+JuliaGrid is compatible with Julia version 1.9 and later. To get started with JuliaGrid, users should first install Julia and consider using a code editor for a smoother coding experience.
+
+---
+
+#### Install Julia
+Begin by [downloading and installing](https://julialang.org/downloads/) Julia. We can choose either the Current Stable Release or the Long-term Support Release.
+
+The Current Stable Release is the most recent version of Julia, providing access to the latest features and typically offering better performance. For most users, we recommend installing the Current Stable Release. The Long-term Support Release is an older version of Julia that has continued to receive bug and security fixes. However, it may not have the latest features or performance improvements.
+
+---
+
+#### Install Code Editor
+For a smoother development experience, we recommend using a code editor. While you can write Julia code in any text editor, using an integrated development environment (IDE) makes coding easier and more efficient. We suggest installing [Visual Studio Code](https://code.visualstudio.com/), which provides excellent support for Julia through its dedicated Julia extension. Visual Studio Code offers features like syntax highlighting, debugging, and autocompletion, making it an ideal choice for both beginners and experienced users.
+
+The [Julia extension](https://marketplace.visualstudio.com/items?itemName=julialang.language-julia) for Visual Studio Code includes built-in dynamic autocompletion, inline results, plot pane, integrated REPL, variable view, code navigation, and many other advanced language features.  For a step-by-step guide on how to use Julia in Visual Studio Code, you can follow the tutorial available [here](https://code.visualstudio.com/docs/languages/julia).
 
 ---
 
-#### Installation
-JuliaGrid is compatible with Julia version 1.9 and newer. To get the JuliaGrid package installed, execute the following Julia command:
+#### Install JuliaGrid
+To get the JuliaGrid package installed, execute the following Julia command:
 ```julia
 import Pkg
 Pkg.add("JuliaGrid")
 ```
 
+When a new version of JuliaGrid is released, you can update it with the following command:
+```julia
+import Pkg
+Pkg.update("JuliaGrid")
+```
+
+---
+
+## Documentation Structure
+JuliaGrid documentation consists of three main parts:
+* The manual provides users with guidance on how to use available functions, its return values, and offers instructions for modifying power system configurations, measurement data, and other user specific analysis.
+* The tutorials delve deeper into the theoretical underpinnings of state-of-the-art algorithms, allowing users to gain an in-depth understanding of the equations used in various functions.
+* API references offer a comprehensive list of objects, functions and methods within the package, categorised according to specific use-cases.
+
+---
+
+## Getting Started
+
+Below, we have provided a list of exhaustive examples in order to ease users in getting started with the JuliaGrid package. These examples highlight some of the functionalities that the framework offers.
+
 ---
 
 #### AC Power Flow
@@ -163,7 +195,8 @@ solve!(system, analysis)                 # Recompute voltage angles with the upd
 
 ---
 
-#### Contributors
+## Contributors
  - [Ognjen Kundacina](https://www.linkedin.com/in/ognjen-kundacina-machine-learning-guy/) - The Institute for Artificial Intelligence Research and Development of Serbia
  - [Muhamed Delalic](https://www.linkedin.com/in/muhameddelalic/) - University of Sarajevo, Bosnia and Herzegovina
- - [Mirsad Cosovic](https://www.linkedin.com/in/mirsad-cosovic-5a4972a9/) - University of Sarajevo, Bosnia and Herzegovina
+ - [Armin Teskeredzic](https://www.linkedin.com/in/armin-teskered%C5%BEi%C4%87-69a099231/) - RWTH Aachen University, Germany
+ - [Mirsad Cosovic](https://www.linkedin.com/in/mirsad-cosovic-5a4972a9/) - University of Sarajevo, Bosnia and Herzegovina

docs/src/manual/acStateEstimation.md

@@ -165,7 +165,7 @@ device.wattmeter.label
 device.varmeter.label
 nothing # hide
 ```
-Consequently, the power system becomes observable, allowing the user to proceed with forming the AC state estimation model and solving it. Ensuring the observability of the system does not guarantee obtaining accurate estimates of the state variables. Numerical ill-conditioning may adversely impact the state estimation algorithm. However, in most cases, efficient estimation becomes feasible when the system is observable [[1]](@ref ACStateEstimationReferenceManual).
+Consequently, the power system becomes observable, allowing the user to proceed with forming the AC state estimation model and solving it. Ensuring the observability of the system does not guarantee obtaining accurate estimates of the state variables. Numerical ill-conditioning may adversely impact the state estimation algorithm. However, in most cases, efficient estimation becomes feasible when the system is observable [korres2011observability](@cite).
 
 Additionally, it is worth mentioning that restoration might encounter difficulties due to the default zero pivot threshold set at `1e-5`. This threshold can be modified using the [`restorationGram!`](@ref restorationGram!(::PowerSystem, ::Measurement, ::Measurement, ::Island)) function.
 
@@ -295,7 +295,7 @@ addPmu!(system, device; to = "Branch 1", magnitude = 1.05, angle = 3.047)
 nothing # hide
 ```
 
-In the case of the rectangular system, inclusion resolves ill-conditioned problems arising in polar coordinates due to small values of current magnitudes. However, this approach's main disadvantage is related to measurement errors, as measurement errors correspond to polar coordinates. Therefore, the covariance matrix must be transformed from polar to rectangular coordinates [[4]](@ref ACStateEstimationReferenceManual). As a result, measurement errors of a single PMU are correlated, and the covariance matrix does not have a diagonal form. Despite that, the measurement error covariance matrix is usually considered as a diagonal matrix, affecting the accuracy of the state estimation.
+In the case of the rectangular system, inclusion resolves ill-conditioned problems arising in polar coordinates due to small values of current magnitudes. However, this approach's main disadvantage is related to measurement errors, as measurement errors correspond to polar coordinates. Therefore, the covariance matrix must be transformed from polar to rectangular coordinates [zhou2006alternative](@cite). As a result, measurement errors of a single PMU are correlated, and the covariance matrix does not have a diagonal form. Despite that, the measurement error covariance matrix is usually considered as a diagonal matrix, affecting the accuracy of the state estimation.
 
 In the example above, we specifically include PMUs where measurement error correlations are disregarded. This is evident through the precision matrix, which maintains a diagonal form:
 ```@repl ACSEWLS
@@ -324,15 +324,15 @@ addPmu!(system, device; from = "Branch 1", magnitude = 1.048, angle = -0.057, po
 nothing # hide
 ```
 
-This inclusion of PMUs provides more accurate state estimates compared to rectangular inclusion, but demands longer computing time. PMUs are handled in the same manner as SCADA measurements. However, this approach is susceptible to ill-conditioned problems arising in polar coordinates due to small values of current magnitudes [[2, 3]](@ref ACStateEstimationReferenceManual).
+This inclusion of PMUs provides more accurate state estimates compared to rectangular inclusion, but demands longer computing time. PMUs are handled in the same manner as SCADA measurements. However, this approach is susceptible to ill-conditioned problems arising in polar coordinates due to small values of current magnitudes [korres2012state, zhou2006alternative](@cite).
 
 !!! tip "Tip"
     It is important to note that with each individual phasor measurement, we can set the coordinate system, providing flexibility to include some in polar and some in rectangular systems. This flexibility is particularly valuable because bus voltage phasor measurements are preferably included in a polar coordinate system, while current phasor measurements are best suited to a rectangular coordinate system.
 
 ---
 
 ##### Alternative Formulation
-The resolution of the WLS state estimation problem using the conventional method typically progresses smoothly. However, it is widely acknowledged that in certain situations common to real-world systems, this method can be vulnerable to numerical instabilities. Such conditions might impede the algorithm from finding a satisfactory solution. In such cases, users may opt for an alternative formulation of the WLS state estimation, namely, employing an approach called orthogonal factorization [[5, Sec. 3.2]](@ref ACStateEstimationReferenceManual).
+The resolution of the WLS state estimation problem using the conventional method typically progresses smoothly. However, it is widely acknowledged that in certain situations common to real-world systems, this method can be vulnerable to numerical instabilities. Such conditions might impede the algorithm from finding a satisfactory solution. In such cases, users may opt for an alternative formulation of the WLS state estimation, namely, employing an approach called orthogonal factorization [aburbook; Sec. 3.2](@cite).
 
 This approach is suitable when measurement errors are uncorrelated, and the precision matrix remains diagonal. Therefore, as a preliminary step, we need to eliminate the correlation, as we did previously:
 ```@example ACSEWLS
@@ -446,7 +446,7 @@ print(system.bus.label, analysis.voltage.magnitude, analysis.voltage.angle)
 ---
 
 ## [Least Absolute Value Estimator](@id PMULAVtateEstimationSolutionManual)
-The LAV method presents an alternative estimation technique known for its increased robustness compared to WLS. While the WLS method relies on specific assumptions regarding measurement errors, robust estimators like LAV are designed to maintain unbiasedness even in the presence of various types of measurement errors and outliers. This characteristic often eliminates the need for extensive bad data processing procedures [[5, Ch. 6]](@ref ACStateEstimationReferenceManual). However, it is important to note that achieving robustness typically involves increased computational complexity.
+The LAV method presents an alternative estimation technique known for its increased robustness compared to WLS. While the WLS method relies on specific assumptions regarding measurement errors, robust estimators like LAV are designed to maintain unbiasedness even in the presence of various types of measurement errors and outliers. This characteristic often eliminates the need for extensive bad data processing procedures [aburbook; Ch. 6](@cite). However, it is important to note that achieving robustness typically involves increased computational complexity.
 
 To obtain an LAV estimator, users need to employ one of the [solvers](https://jump.dev/JuMP.jl/stable/packages/solvers/) listed in the JuMP documentation. In many common scenarios, the `Ipopt` solver proves sufficient to obtain a solution:
 ```@example ACSEWLS
@@ -784,17 +784,4 @@ magnitude, angle = toCurrent(system, analysis; label = "Branch 2")
 To calculate the current passing through the series impedance of the branch in the direction from the from-bus end to the to-bus end, we can use the following function:
 ```@repl WLSACStateEstimationSolution
 magnitude, angle = seriesCurrent(system, analysis; label = "Branch 2")
-```
-
----
-
-## [References](@id ACStateEstimationReferenceManual)
-[1] G. Korres, *Observability analysis based on echelon form of a reduced dimensional Jacobian matrix*, IEEE Trans. Power Syst., vol. 26, no. 4, pp. 2572–2573, 2011.
-
-[2] G. N. Korres and N. M. Manousakis, *State estimation and observability analysis for phasor measurement unit measured systems*, IET Gener. Transm. Dis., vol. 6, no. 9, 2012.
-
-[3] A. Gomez-Exposito, A. Abur, P. Rousseaux, A. de la Villa Jaen, and C. Gomez-Quiles, *On the use of PMUs in power system state estimation*, Proc. IEEE PSCC, 2011.
-
-[4] M. Zhou, V. A. Centeno, J. S. Thorp, and A. G. Phadke, *An alternative for including phasor measurements in state estimators*, IEEE Trans. Power Syst., vol. 21, no. 4, 2006.
-
-[5] A. Abur and A. Exposito, *Power System State Estimation: Theory and Implementation*, Taylor & Francis, 2004.
+```

docs/src/manual/dcStateEstimation.md

@@ -91,7 +91,7 @@ nothing # hide
 ---
 
 ##### Alternative Formulation
-The resolution of the WLS state estimation problem using the conventional method typically progresses smoothly. However, it is widely acknowledged that in certain situations common to real-world systems, this method can be vulnerable to numerical instabilities. Such conditions might impede the algorithm from finding a satisfactory solution. In such cases, users may opt for an alternative formulation of the WLS state estimation, namely, employing an approach called orthogonal factorization [[2, Sec. 3.2]](@ref DCStateEstimationReferenceManual).
+The resolution of the WLS state estimation problem using the conventional method typically progresses smoothly. However, it is widely acknowledged that in certain situations common to real-world systems, this method can be vulnerable to numerical instabilities. Such conditions might impede the algorithm from finding a satisfactory solution. In such cases, users may opt for an alternative formulation of the WLS state estimation, namely, employing an approach called orthogonal factorization [aburbook; Sec. 3.2](@cite).
 
 Specifically, by specifying the `Orthogonal` argument in the [`dcStateEstimation`](@ref dcStateEstimation) function, JuliaGrid implements a more robust approach to obtain the WLS estimator, which proves particularly beneficial when substantial differences exist among measurement variances:
 ```@example WLSDCStateEstimationSolution
@@ -175,7 +175,7 @@ nothing # hide
 ---
 
 ## [Least Absolute Value Estimator](@id DCLAVtateEstimationSolutionManual)
-The LAV method presents an alternative estimation technique known for its increased robustness compared to WLS. While the WLS method relies on specific assumptions regarding measurement errors, robust estimators like LAV are designed to maintain unbiasedness even in the presence of various types of measurement errors and outliers. This characteristic often eliminates the need for extensive bad data processing procedures [[2, Ch. 6]](@ref DCStateEstimationReferenceManual). However, it is important to note that achieving robustness typically involves increased computational complexity.
+The LAV method presents an alternative estimation technique known for its increased robustness compared to WLS. While the WLS method relies on specific assumptions regarding measurement errors, robust estimators like LAV are designed to maintain unbiasedness even in the presence of various types of measurement errors and outliers. This characteristic often eliminates the need for extensive bad data processing procedures [aburbook; Ch. 6](@cite). However, it is important to note that achieving robustness typically involves increased computational complexity.
 
 To obtain an LAV estimator, users need to employ one of the [solvers](https://jump.dev/JuMP.jl/stable/packages/solvers/) listed in the JuMP documentation. In many common scenarios, the Ipopt solver proves sufficient to obtain a solution:
 ```@example WLSDCStateEstimationSolution
@@ -409,11 +409,4 @@ Similarly, we can compute the active power flow at both the from-bus and to-bus
 ```@repl WLSDCStateEstimationSolution
 active = fromPower(system, analysis; label = "Branch 1")
 active = toPower(system, analysis; label = "Branch 1")
-```
-
----
-
-## [References](@id DCStateEstimationReferenceManual)
-[1] G. Korres, *Observability analysis based on echelon form of a reduced dimensional Jacobian matrix*, IEEE Trans. Power Syst., vol. 26, no. 4, pp. 2572–2573, 2011.
-
-[2] A. Abur and A. Exposito, *Power System State Estimation: Theory and Implementation*, Taylor & Francis, 2004.
+```