include support for custom variable names in OPF models, and update docs

docs/src/index.md

@@ -1,7 +1,7 @@
 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 is a fast, flexible, and easy-to-use open-source tool for analyzing and modifying 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.
 
 The framework'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.

docs/src/manual/acOptimalPowerFlow.md

@@ -13,20 +13,8 @@ After obtaining the AC optimal power flow solution, JuliaGrid offers post-proces
 * [`power!`](@ref power!(::PowerSystem, ::ACPowerFlow)),
 * [`current!`](@ref current!(::PowerSystem, ::ACPowerFlow)).
 
-Furthermore, there are specialized functions dedicated to calculating specific types of powers related to particular buses and branches:
-* [`injectionPower`](@ref injectionPower(::PowerSystem, ::AC)),
-* [`supplyPower`](@ref supplyPower(::PowerSystem, ::ACPowerFlow)),
-* [`shuntPower`](@ref shuntPower(::PowerSystem, ::AC)),
-* [`fromPower`](@ref fromPower(::PowerSystem, ::AC)),
-* [`toPower`](@ref toPower(::PowerSystem, ::AC)),
-* [`seriesPower`](@ref seriesPower(::PowerSystem, ::AC)),
-* [`chargingPower`](@ref chargingPower(::PowerSystem, ::AC)).
+Additionally, specialized functions are available for calculating specific types of [powers](@ref ACPowerAnalysisAPI) or [currents](@ref ACCurrentAnalysisAPI) for individual buses, branches, or generators.
 
-Likewise, there are specialized functions dedicated to calculating specific types of currents related to particular buses or branches:
-* [`injectionCurrent`](@ref injectionCurrent(::PowerSystem, ::AC)),
-* [`fromCurrent`](@ref fromCurrent(::PowerSystem, ::AC)),
-* [`toCurrent`](@ref toCurrent(::PowerSystem, ::AC)),
-* [`seriesCurrent`](@ref seriesCurrent(::PowerSystem, ::AC)).
 
 ---
 
@@ -86,6 +74,15 @@ fieldnames(typeof(analysis.method.variable))
 
 ---
 
+##### Variable Names
+Users have the option to define custom variable names for printing and writing equations, which can help present them in a more compact form. For example:
+```@example ACOptimalPowerFlow
+analysis = acOptimalPowerFlow(system, Ipopt.Optimizer; magnitude = "V", angle = "θ")
+nothing # hide
+```
+
+---
+
 ##### Add Variables
 The user has the ability to easily add new variables to the defined AC optimal power flow model by using the [`@variable`](https://jump.dev/JuMP.jl/stable/api/JuMP/#JuMP.@variable) macro from the JuMP package. Here is an example:
 ```@example ACOptimalPowerFlow

docs/src/manual/acPowerFlow.md

@@ -19,21 +19,7 @@ After obtaining the AC power flow solution, JuliaGrid offers post-processing ana
 * [`power!`](@ref power!(::PowerSystem, ::ACPowerFlow)),
 * [`current!`](@ref current!(::PowerSystem, ::AC)).
 
-Furthermore, there are specialized functions dedicated to calculating specific types of powers related to particular buses, branches, or generators:
-* [`injectionPower`](@ref injectionPower(::PowerSystem, ::AC)),
-* [`supplyPower`](@ref supplyPower(::PowerSystem, ::ACPowerFlow)),
-* [`shuntPower`](@ref shuntPower(::PowerSystem, ::AC)),
-* [`fromPower`](@ref fromPower(::PowerSystem, ::AC)),
-* [`toPower`](@ref toPower(::PowerSystem, ::AC)),
-* [`seriesPower`](@ref seriesPower(::PowerSystem, ::AC)),
-* [`chargingPower`](@ref chargingPower(::PowerSystem, ::AC)),
-* [`generatorPower`](@ref generatorPower(::PowerSystem, ::ACPowerFlow)).
-
-Likewise, there are specialized functions dedicated to calculating specific types of currents related to particular buses or branches:
-* [`injectionCurrent`](@ref injectionCurrent(::PowerSystem, ::AC)),
-* [`fromCurrent`](@ref fromCurrent(::PowerSystem, ::AC)),
-* [`toCurrent`](@ref toCurrent(::PowerSystem, ::AC)),
-* [`seriesCurrent`](@ref seriesCurrent(::PowerSystem, ::AC)).
+Additionally, specialized functions are available for calculating specific types of [powers](@ref ACPowerAnalysisAPI) or [currents](@ref ACCurrentAnalysisAPI) for individual buses, branches, or generators.
 
 ---
 
@@ -50,13 +36,12 @@ addBus!(system; label = "Bus 3", type = 2)
 
 addGenerator!(system; bus = "Bus 2")
 
-acModel!(system)
 analysis = newtonRaphson(system)
 ```
 
 Initially, `Bus 1` is set as the slack bus (`type = 3`), and `Bus 2` and `Bus 3` are generator buses (`type = 2`). However, `Bus 3` does not have a generator, and JuliaGrid considers this a mistake and changes the corresponding bus to a demand bus (`type = 1`).
 
-After this step, JuliaGrid verifies the slack bus. Initially, the slack bus (`type = 3`) corresponds to `Bus 1`, but since it does not have an in-service generator connected to it, JuliaGrid recognizes it as an error. Therefore, JuliaGrid assigns a new slack bus from the available generator buses (`type = 2`) that have connected in-service generators. In this specific example, `Bus 2` becomes the new slack bus.
+After this step, JuliaGrid verifies the slack bus. Initially, the slack bus (`type = 3`) corresponds to `Bus 1`, but since it does not have an in-service generator connected to it, JuliaGrid recognizes it as another mistake. Therefore, JuliaGrid assigns a new slack bus from the available generator buses (`type = 2`) that have connected in-service generators. In this specific example, `Bus 2` becomes the new slack bus.
 
 ```@setup busType
 using JuliaGrid
@@ -90,7 +75,7 @@ Note that, if a bus is initially defined as the demand bus (`type = 1`) and late
 ---
 
 ## [Setup Starting Voltages](@id SetupStartingVoltagesManual)
-To begin analyzing the AC power flow in JuliaGrid, we must first establish the `PowerSystem` type and define the AC model by calling the [`acModel!`](@ref acModel!) function. Once the power system is set up, we can select one of the available methods for solving the AC power flow problem, such as [`newtonRaphson`](@ref newtonRaphson), [`fastNewtonRaphsonBX`](@ref fastNewtonRaphsonBX), [`fastNewtonRaphsonXB`](@ref fastNewtonRaphsonXB), or [`gaussSeidel`](@ref gaussSeidel).
+To begin analyzing the AC power flow in JuliaGrid, we must first establish the `PowerSystem` type. Once the power system is set up, we can select one of the available methods for solving the AC power flow problem, such as [`newtonRaphson`](@ref newtonRaphson), [`fastNewtonRaphsonBX`](@ref fastNewtonRaphsonBX), [`fastNewtonRaphsonXB`](@ref fastNewtonRaphsonXB), or [`gaussSeidel`](@ref gaussSeidel).
 
 Assuming we have selected the Newton-Raphson method, we can use the following code snippet:
 ```@example initializeACPowerFlow
@@ -113,7 +98,7 @@ analysis = newtonRaphson(system)
 nothing # hide
 ```
 
-Here, in this code snippet, the function [`newtonRaphson`](@ref newtonRaphson) generates starting voltage vectors in polar coordinates.
+Here, the function [`newtonRaphson`](@ref newtonRaphson) generates starting voltage vectors in polar coordinates.
 
 The starting voltage magnitudes are set to:
 ```@repl initializeACPowerFlow
@@ -185,7 +170,7 @@ Consequently, the iteration begins with a fixed set of voltage magnitude values
 ---
 
 ## [Power Flow Solution](@id ACPowerFlowSolutionManual)
-To solve the AC power flow problem using JuliaGrid, we first need to create the `PowerSystem` type and define the AC model by calling the [`acModel!`](@ref acModel!) function. Here is an example:
+To start, we will create a power system and define the AC model by invoking the [`acModel!`](@ref acModel!) function:
 ```@example ACPowerFlowSolution
 using JuliaGrid # hide
 @default(unit) # hide
@@ -223,7 +208,7 @@ nothing # hide
     ```julia DCPowerFlowSolution
     analysis = newtonRaphson(system, QR)
     ```
-    It is important to note that the capability to change the factorization method is exclusively available for the Newton-Raphson and fast Newton-Raphson methods.
+    The capability to change the factorization method is exclusively available for the Newton-Raphson and fast Newton-Raphson methods.
 
 This function sets up the desired method for an iterative process based on two functions: [`mismatch!`](@ref mismatch!(::PowerSystem, ::ACPowerFlow{NewtonRaphson})) and [`solve!`](@ref solve!(::PowerSystem, ::ACPowerFlow{NewtonRaphson})). The [`mismatch!`](@ref mismatch!(::PowerSystem, ::ACPowerFlow{NewtonRaphson})) function calculates the active and reactive power injection mismatches using the given voltage magnitudes and angles, while [`solve!`](@ref solve!(::PowerSystem, ::ACPowerFlow{NewtonRaphson})) computes the voltage magnitudes and angles.
 
@@ -275,7 +260,7 @@ nothing # hide
 The [`mismatch!`](@ref mismatch!(::PowerSystem, ::ACPowerFlow{NewtonRaphson})) function returns the maximum absolute values of active and reactive power injection mismatches, which are commonly used as a convergence criterion in iterative AC power flow algorithms. Note that the function can also be used to terminate the loop when using the Gauss-Seidel method, even though it is not required.
 
 !!! tip "Tip"
-    To ensure an accurate count of iterations, it is important for the user to place the iteration counter after the condition expressions within the if construct. Counting the iterations before this point can result in an incorrect number of iterations, as it leads to an additional iteration being performed.
+    To ensure an accurate count of iterations, the user should place the iteration counter after the condition expressions within the if construct.
 
 ---
 

docs/src/manual/dcPowerFlow.md

@@ -10,12 +10,7 @@ To solve the DC power flow problem and acquire bus voltage angles, make use of t
 After obtaining the solution for DC power flow, JuliaGrid offers a post-processing analysis function to compute active powers associated with buses, branches, and generators:
 * [`power!`](@ref power!(::PowerSystem, ::DCPowerFlow)).
 
-Additionally, there are specialized functions dedicated to calculating specific types of active powers related to particular buses, branches, or generators:
-* [`injectionPower`](@ref injectionPower(::PowerSystem, ::DCPowerFlow)),
-* [`supplyPower`](@ref supplyPower(::PowerSystem, ::DCPowerFlow)),
-* [`fromPower`](@ref fromPower(::PowerSystem, ::DCPowerFlow)),
-* [`toPower`](@ref toPower(::PowerSystem, ::DCPowerFlow)),
-* [`generatorPower`](@ref generatorPower(::PowerSystem, ::DCPowerFlow)).
+Additionally, specialized functions are available for calculating specific types of [powers](@ref DCPowerAnalysisAPI) for individual buses, branches, or generators.
 
 ---
 
@@ -37,7 +32,7 @@ dcModel!(system)
 analysis = dcPowerFlow(system)
 ```
 
-In this example, the slack bus (`type = 3`) corresponds to the `Bus 1`. However, this bus does not have an in-service generator connected to it. Consequently, JuliaGrid recognizes this as an error and attempts to assign a new slack bus from the available generator buses (`type = 2`) that have connected in-service generators. In this particular example, the `Bus 3` will become the new slack bus. As a result, we can observe the updated array of bus types:
+In this example, the slack bus (`type = 3`) corresponds to the `Bus 1`. However, this bus does not have an in-service generator connected to it. JuliaGrid considers this a mistake and attempts to assign a new slack bus from the available generator buses (`type = 2`) that have connected in-service generators. In this particular example, the `Bus 3` will become the new slack bus. As a result, we can observe the updated array of bus types:
 ```@setup busType
 using JuliaGrid # hide
 @default(unit) # hide

docs/src/manual/measurementModel.md

@@ -665,7 +665,7 @@ This procedure is applicable to all measurement devices, including voltmeters, a
 
 ---
 
-##### Load and Save Power System Data
+##### Load and Save Measurement Data
 When saving the measurements to an HDF5 file, the label type (strings or integers) will match the type chosen during system setup. Likewise, when loading data from an HDF5 file, the label type will be preserved as saved, regardless of what is set by the [`@labels`](@ref @labels) macro.