update docs

docs/src/manual/acPowerFlow.md

@@ -91,6 +91,8 @@ Note that, if a bus is initially defined as the demand bus (`type = 1`) and late
 To begin analysing the AC power flow in JuliaGrid, we must first establish the `PowerSystem` composite 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). Assuming we have selected the Newton-Raphson method, we can use the following code snippet:
 ```@example initializeACPowerFlow
 using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
@@ -134,6 +136,8 @@ system.bus.voltage.angle
 This method of specifying starting values has a significant advantage in that it allows the user to easily change the starting voltage magnitudes and angles, which play a crucial role in iterative methods. For instance, suppose we define our power system as follows:
 ```@example initializeACPowerFlowFlat
 using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
@@ -171,6 +175,8 @@ Consequently, when using the Newton-Raphson method, the iteration begins with a
 To solve the AC power flow problem using JuliaGrid, we first need to create the `PowerSystem` composite type and define the AC model by calling the [`acModel!`](@ref acModel!) function. Here is an example:
 ```@example ACPowerFlowSolution
 using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
@@ -252,6 +258,8 @@ The [`mismatch!`](@ref mismatch!(::PowerSystem, ::NewtonRaphson)) function retur
 After obtaining the solution from the AC power flow, we can calculate various electrical quantities related to buses, branches, and generators using the [`power!`](@ref power!(::PowerSystem, ::ACPowerFlow)) and [`current!`](@ref current!(::PowerSystem, ::ACPowerFlow)) functions. For instance, let us consider the power system for which we obtained the AC power flow solution:
 ```@example ComputationPowersCurrentsLosses
 using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
@@ -391,6 +399,8 @@ magnitude, angle = seriesCurrent(system, analysis; label = "Branch 2")
 The initial application of the reusable `PowerSystem` type is simple: it can be shared among various methods, which can yield benefits. For example, the Gauss-Seidel method is commonly used for a speedy approximate solution, whereas the Newton-Raphson method is typically utilized for the precise final solution. Thus, we can execute the Gauss-Seidel method for a limited number of iterations, as exemplified below:
 ```@example ReusingPowerSystemType
 using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
@@ -468,6 +478,8 @@ Therefore, to offer a straightforward method for reusing the `ACPowerFlow` abstr
 Let us take a look at the following power system, where we have performed an AC power flow analysis:
 ```@example ReusingACPowerFlowType
 using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
@@ -509,6 +521,8 @@ for iteration = 1:100
     solve!(system, analysis)
 end
 ```
+!!! info "Info"
+    Reusing the `ACPowerFlow` and proceeding directly to the iterations can also offer the advantage of starting with voltages obtained from the previous solution, resulting in a "warm" start.
 
 However, attempting to take` Generator 2` out-of-service is not possible, as this operation would yield incorrect results if we proceed directly to the iterations. In this case, executing the [`newtonRaphson`](@ref newtonRaphson) function is mandatory:
 ```@repl ReusingACPowerFlowType
@@ -525,23 +539,25 @@ The function [`reactiveLimit!`](@ref reactiveLimit!) can be used by the user to
 ```@example GeneratorReactivePowerLimits
 using JuliaGrid # hide
 @default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
-addBus!(system; label = 1, type = 3)
-addBus!(system; label = 2, type = 1, active = 0.5)
-addBus!(system; label = 3, type = 2, reactive = 0.05)
-addBus!(system; label = 4, type = 2, reactive = 0.05)
+addBus!(system; label = "Bus 1", type = 3)
+addBus!(system; label = "Bus 2", type = 1, active = 0.5)
+addBus!(system; label = "Bus 3", type = 2, reactive = 0.05)
+addBus!(system; label = "Bus 4", type = 2, reactive = 0.05)
 
-addBranch!(system; from = 1, to = 2, resistance = 0.01, reactance = 0.05)
-addBranch!(system; from = 1, to = 3, resistance = 0.02, reactance = 0.01)
-addBranch!(system; from = 2, to = 3, resistance = 0.03, reactance = 0.04)
-addBranch!(system; from = 2, to = 4, resistance = 0.03, reactance = 0.004)
+@branch(resistance = 0.015)
+addBranch!(system; from = "Bus 1", to = "Bus 2", reactance = 0.05)
+addBranch!(system; from = "Bus 1", to = "Bus 3", reactance = 0.01)
+addBranch!(system; from = "Bus 2", to = "Bus 3", reactance = 0.04)
+addBranch!(system; from = "Bus 2", to = "Bus 4", reactance = 0.004)
 
-@generator(minReactive = -0.4, maxReactive = 0.2)
-addGenerator!(system; bus = 1)
-addGenerator!(system; bus = 3, reactive = 0.8)
-addGenerator!(system; bus = 4, reactive = 0.9)
+@generator(minReactive = -0.4, maxReactive = 0.1)
+addGenerator!(system; label = "Generator 1", bus = "Bus 1")
+addGenerator!(system; label = "Generator 2", bus = "Bus 3", reactive = 0.8)
+addGenerator!(system; label = "Generator 3", bus = "Bus 4", reactive = 0.9)
 
 acModel!(system)
 
@@ -563,7 +579,7 @@ The output reactive power of the observed generators is subject to limits which
 [system.generator.capability.minReactive system.generator.capability.maxReactive]
 ```
 
-After obtaining the solution of the AC power flow analysis, the [`reactiveLimit!`](@ref reactiveLimit!) function is used to internally calculate the output powers of the generators and verify if these values exceed the defined limits. Consequently, the variable `violate` indicates whether there is a violation of limits. In the provided example, it can be observed that the second and third generators violate the maximum limit:
+After obtaining the solution of the AC power flow analysis, the [`reactiveLimit!`](@ref reactiveLimit!) function is used to internally calculate the output powers of the generators and verify if these values exceed the defined limits. Consequently, the variable `violate` indicates whether there is a violation of limits. In the provided example, it can be observed that the `Generator 2` and `Generator 3` violate the maximum limit:
 ```@repl GeneratorReactivePowerLimits
 violate
 ```
@@ -606,6 +622,7 @@ violate = reactiveLimit!(system, analysis)
 Looking at the following code example, we can see that the output limits of the generator are set only for the first generator that is connected to the slack bus:
 ```@example NewSlackBus
 using JuliaGrid # hide
+@default(unit) # hide
 @default(template) # hide
 
 system = powerSystem()

docs/src/manual/dcPowerFlow.md

@@ -41,6 +41,8 @@ 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 within the defined set of buses:
 ```@setup busType
 using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
@@ -73,6 +75,8 @@ analysis = dcPowerFlow(system)
 To solve the DC power flow problem using JuliaGrid, we start by creating the `PowerSystem` composite type and defining the DC model with the [`dcModel!`](@ref dcModel!) function. Here is an example:
 ```@example DCPowerFlowSolution
 using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
@@ -118,6 +122,8 @@ nothing # hide
 After obtaining the solution from the DC power flow, we can calculate powers related to buses, branches, and generators using the [`power!`](@ref power!(::PowerSystem, ::DCPowerFlow)) function. For instance, let us consider the power system for which we obtained the DC power flow solution:
 ```@example ComputationPowersCurrentsLosses
 using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 
@@ -280,7 +286,9 @@ solve!(system, analysis)
 
 However, if you intend to reuse the `DCPowerFlow` type once more, this time with the aim of modifying the status of the `Branch 3`:
 ```@setup ReusingDCPowerFlow
-using JuliaGrid 
+using JuliaGrid # hide
+@default(unit) # hide
+@default(template) # hide
 
 system = powerSystem()
 

src/powerFlow/acPowerFlow.jl

@@ -67,11 +67,8 @@ type, which includes the following fields:
 - `voltage`: the bus voltage magnitudes and angles;
 - `power`: the variable allocated to store the active and reactive powers;
 - `current`: the variable allocated to store the currents;
-- `jacobian`: the Jacobian matrix;
-- `mismatch`: the active and reactive power injection mismatches;
-- `increment`: the bus voltage magnitude and angle increments;
-- `pq`: indices of demand buses;
-- `pvpq`: indices of demand and generator buses.
+- `method`: contains the Jacobian matrix, power injection mismatches, bus voltage increments, and indices;
+- `uuid`: a universally unique identifier associated with the `PowerSystem` composite type.
 
 # Example
 ```jldoctest
@@ -200,18 +197,8 @@ type, which includes the following fields:
 - `voltage`: the bus voltage magnitudes and angles;
 - `power`: the variable allocated to store the active and reactive powers;
 - `current`: the variable allocated to store the currents;
-- `active`:
-  - `jacobian`: the Jacobian matrix associated with active power equations;
-  - `mismatch`: the active power injection mismatches;
-  - `increment`: the bus voltage angle increments;
-  - `factorization`: the factorized Jacobian matrix;
-- `reactive`:
-  - `jacobian`: the Jacobian matrix associated with reactive power equations;
-  - `mismatch`: the reative power injection mismatches;
-  - `increment`: the bus voltage magnitude increments;
-  - `factorization`: the factorized Jacobian matrix;
-- `pq`: indices of demand buses;
-- `pvpq`: indices of demand and generator buses.
+- `method`: contains Jacobian matrices, power injection mismatches, bus voltage increments, and indices;
+- `uuid`: a universally unique identifier associated with the `PowerSystem` composite type.
 
 # Example
 ```jldoctest
@@ -242,18 +229,8 @@ type, which includes the following fields:
 - `voltage`: the bus voltage magnitudes and angles;
 - `power`: the variable allocated to store the active and reactive powers;
 - `current`: the variable allocated to store the currents;
-- `active`:
-  - `jacobian`: the Jacobian matrix associated with active power equations;
-  - `mismatch`: the active power injection mismatches;
-  - `increment`: the bus voltage angle increments;
-  - `factorization`: the factorized Jacobian matrix;
-- `reactive`:
-  - `jacobian`: the Jacobian matrix associated with reactive power equations;
-  - `mismatch`: the reative power injection mismatches;
-  - `increment`: the bus voltage magnitude increments;
-  - `factorization`: the factorized Jacobian matrix;
-- `pq`: indices of demand buses;
-- `pvpq`: indices of demand and generator buses.
+- `method`: contains Jacobian matrices, power injection mismatches, bus voltage increments, and indices;
+- `uuid`: a universally unique identifier associated with the `PowerSystem` composite type.
 
 # Example
 ```jldoctest
@@ -462,9 +439,8 @@ type, which includes the following fields:
 - `voltage`: the bus voltage magnitudes and angles;
 - `power`: the variable allocated to store the active and reactive powers;
 - `current`: the variable allocated to store the currents;
-- `complex`: the bus complex voltages;
-- `pq`: indices of demand buses;
-- `pv`: indices of generator buses.
+- `method`: contains the bus complex voltages and indices;
+- `uuid`: a universally unique identifier associated with the `PowerSystem` composite type.
 
 # Example
 ```jldoctest
@@ -950,7 +926,7 @@ function reactiveLimit!(system::PowerSystem, analysis::ACPowerFlow)
                     for k = 1:bus.number
                         if bus.layout.type[k] == 2
                             labels = collect(keys(sort(system.bus.label; byvalue = true)))
-                            @info("The slack bus labeled $(labels[j]) is converted to generator bus, the bus labeled $(labels[k]) is the new slack bus.")
+                            @info("The slack bus labeled $(labels[j]) is converted to generator bus.\nThe bus labeled $(labels[k]) is the new slack bus.")
                             bus.layout.slack = k
                             bus.layout.type[k] = 3
                             break
@@ -1072,7 +1048,7 @@ end
 ######### Query About Bus ##########
 function addBus!(system::PowerSystem, analysis::ACPowerFlow; kwargs...)
     checkUUID(system.uuid, analysis.uuid)
-    throw(ErrorException("The ACPowerFlow argument cannot be reused when adding a new bus."))
+    throw(ErrorException("The ACPowerFlow cannot be reused when adding a new bus."))
 end
 
 ######### Query About Deamnd Bus ##########
@@ -1089,7 +1065,7 @@ end
 
 function shuntBus!(system::PowerSystem, analysis::FastNewtonRaphson; user...)
     checkUUID(system.uuid, analysis.uuid)
-    throw(ErrorException("The FastNewtonRaphson argument cannot be reused when the shunt element is altered."))
+    throw(ErrorException("The FastNewtonRaphson cannot be reused when the shunt element is altered."))
 end
 
 ######### Query About Branch ##########
@@ -1108,7 +1084,7 @@ end
 
 function addBranch!(system::PowerSystem, analysis::FastNewtonRaphson; kwargs...)
     checkUUID(system.uuid, analysis.uuid)
-    throw(ErrorException("The FastNewtonRaphson argument cannot be reused when adding a new branch."))
+    throw(ErrorException("The FastNewtonRaphson cannot be reused when adding a new branch."))
 end
 
 ######### Query About Status Branch ##########
@@ -1119,7 +1095,7 @@ end
 
 function statusBranch!(system::PowerSystem, analysis::FastNewtonRaphson; kwargs...)
     checkUUID(system.uuid, analysis.uuid)
-    throw(ErrorException("The FastNewtonRaphson argument cannot be reused when the branch status is altered."))
+    throw(ErrorException("The FastNewtonRaphson cannot be reused when the branch status is altered."))
 end
 
 ######### Query About Parameter Branch ##########
@@ -1130,7 +1106,7 @@ end
 
 function parameterBranch!(system::PowerSystem, analysis::FastNewtonRaphson; kwargs...)
     checkUUID(system.uuid, analysis.uuid)
-    throw(ErrorException("The FastNewtonRaphson argument cannot be reused when the branch parameters are altered."))
+    throw(ErrorException("The FastNewtonRaphson cannot be reused when the branch parameters are altered."))
 end
 
 ######### Query About Generator ##########
@@ -1158,7 +1134,7 @@ function statusGenerator!(system::PowerSystem, analysis::ACPowerFlow; label::L,
     index = system.generator.label[getLabel(system.generator, label, "generator")]
     indexBus = system.generator.layout.bus[index]
     if status == 0 && system.bus.layout.type[indexBus] in [2, 3] && length(system.bus.supply.generator[indexBus]) == 1
-        throw(ErrorException("The ACPowerFlow argument cannot be reused when all in-service generators are removed from the generator or slack bus."))
+        throw(ErrorException("The ACPowerFlow cannot be reused due to required bus type conversion."))
     end
 
     statusGenerator!(system; label, status)

src/powerFlow/dcPowerFlow.jl

@@ -23,6 +23,7 @@ following fields:
 - `voltage`: the variable allocated to store the bus voltage angles;
 - `power`: the variable allocated to store the active powers;
 - `factorization`: the factorized nodal matrix.
+- `uuid`: a universally unique identifier associated with the `PowerSystem` composite type.
 
 # Example
 ```jldoctest
@@ -127,7 +128,7 @@ end
 ######### Query About Bus ##########
 function addBus!(system::PowerSystem, analysis::DCPowerFlow; kwargs...)
     checkUUID(system.uuid, analysis.uuid)
-    throw(ErrorException("The DCPowerFlow argument cannot be reused when adding a new bus."))
+    throw(ErrorException("The DCPowerFlow cannot be reused when adding a new bus."))
 end
 
 ######### Query About Deamnd Bus ##########
@@ -145,19 +146,19 @@ end
 ######### Query About Branch ##########
 function addBranch!(system::PowerSystem, analysis::DCPowerFlow; kwargs...)
     checkUUID(system.uuid, analysis.uuid)
-    throw(ErrorException("The DCPowerFlow argument cannot be reused when adding a new branch."))
+    throw(ErrorException("The DCPowerFlow cannot be reused when adding a new branch."))
 end
 
 ######### Query About Status Branch ##########
 function statusBranch!(system::PowerSystem, analysis::DCPowerFlow; label::L, status::T)
     checkUUID(system.uuid, analysis.uuid)
-    throw(ErrorException("The DCPowerFlow argument cannot be reused when the branch status is altered."))
+    throw(ErrorException("The DCPowerFlow cannot be reused when the branch status is altered."))
 end
 
 ######### Query About Parameter Branch ##########
 function parameterBranch!(system::PowerSystem, analysis::DCPowerFlow; user...)
     checkUUID(system.uuid, analysis.uuid)
-    throw(ErrorException("The DCPowerFlow argument cannot be reused when the branch parameters are altered."))
+    throw(ErrorException("The DCPowerFlow cannot be reused when the branch parameters are altered."))
 end
 
 ######### Query About Generator ##########