add new key for labeling

mcosovic · Oct 31, 2023 · 7dea95f · 7dea95f
1 parent 5268475
commit 7dea95f
Show file tree

Hide file tree

Showing 11 changed files with 153 additions and 113 deletions.
diff --git a/docs/src/api/measurementModel.md b/docs/src/api/measurementModel.md
@@ -8,27 +8,27 @@ For further information on this topic, please see the [Measurement Model] sectio
 * [`measurement`](@ref measurement)
 * [`saveMeasurement`](@ref saveMeasurement)
 
-###### Voltmeter Functions
+###### Voltmeter
 * [`addVoltmeter!`](@ref addVoltmeter!)
 * [`updateVoltmeter!`](@ref updateVoltmeter!)
 * [`@voltmeter`](@ref @voltmeter)
 
-###### Ammeter Functions
+###### Ammeter
 * [`addAmmeter!`](@ref addAmmeter!)
 * [`updateAmmeter!`](@ref updateAmmeter!)
 * [`@ammeter`](@ref @ammeter)
 
-###### Wattmeter Functions
+###### Wattmeter
 * [`addWattmeter!`](@ref addWattmeter!)
 * [`updateWattmeter!`](@ref updateWattmeter!)
 * [`@wattmeter`](@ref @wattmeter)
 
-###### Varmeter Functions
+###### Varmeter
 * [`addVarmeter!`](@ref addVarmeter!)
 * [`updateVarmeter!`](@ref updateVarmeter!)
 * [`@varmeter`](@ref @varmeter)
 
-###### PMU Functions
+###### PMU
 * [`addPmu!`](@ref addPmu!)
 * [`updatePmu!`](@ref updatePmu!)
 * [`@pmu`](@ref @pmu)
@@ -43,7 +43,7 @@ saveMeasurement
 
 ---
 
-## Voltmeter Functions
+## Voltmeter
 ```@docs
 addVoltmeter!(::PowerSystem, ::Measurement)
 addVoltmeter!(::PowerSystem, ::Measurement, ::AC)
@@ -53,7 +53,7 @@ updateVoltmeter!
 
 ---
 
-## Ammeter Functions
+## Ammeter
 ```@docs
 addAmmeter!(::PowerSystem, ::Measurement)
 addAmmeter!(::PowerSystem, ::Measurement, ::AC)
@@ -63,7 +63,7 @@ updateAmmeter!
 
 ---
 
-## Wattmeter Functions
+## Wattmeter
 ```@docs
 addWattmeter!(::PowerSystem, ::Measurement)
 addWattmeter!(::PowerSystem, ::Measurement, ::AC)
@@ -73,7 +73,7 @@ updateWattmeter!
 
 ---
 
-## Varmeter Functions
+## Varmeter
 ```@docs
 addVarmeter!(::PowerSystem, ::Measurement)
 addVarmeter!(::PowerSystem, ::Measurement, ::AC)
@@ -83,7 +83,7 @@ updateVarmeter!
 
 ---
 
-## PMU Functions
+## PMU
 ```@docs
 addPmu!(::PowerSystem, ::Measurement)
 addPmu!(::PowerSystem, ::Measurement, ::AC)

diff --git a/docs/src/api/powerSystemModel.md b/docs/src/api/powerSystemModel.md
@@ -8,17 +8,17 @@ For further information on this topic, please see the [Power System Model](@ref
 * [`powerSystem`](@ref powerSystem)
 * [`savePowerSystem`](@ref savePowerSystem)
 
-###### Bus Functions
+###### Bus
 * [`addBus!`](@ref addBus!)
 * [`updateBus!`](@ref updateBus!)
 * [`@bus`](@ref @bus)
 
-###### Branch Functions
+###### Branch
 * [`addBranch!`](@ref addBranch!)
 * [`updateBranch!`](@ref updateBranch!)
 * [`@branch`](@ref @branch)
 
-###### Generator Functions
+###### Generator
 * [`addGenerator!`](@ref addGenerator!)
 * [`updateGenerator!`](@ref updateGenerator!)
 * [`cost!`](@ref cost!)
@@ -38,7 +38,7 @@ savePowerSystem
 
 ---
 
-## Bus Functions
+## Bus
 ```@docs
 addBus!
 updateBus!
@@ -47,7 +47,7 @@ updateBus!
 
 ---
 
-## Branch Functions
+## Branch
 ```@docs
 addBranch!
 updateBranch!
@@ -56,7 +56,7 @@ updateBranch!
 
 ---
 
-## Generator Functions
+## Generator
 ```@docs
 addGenerator!
 updateGenerator!

diff --git a/docs/src/manual/powerSystemModel.md b/docs/src/manual/powerSystemModel.md
@@ -338,7 +338,8 @@ To reset the bus, branch, and generator templates to their default settings, use
 @default(generator)
 nothing # hide
 ```
-Additionally, users can reset all templates for the bus, branch, and generator components using the macro:
+
+Additionally, users can reset all templates using the macro:
 ```@example CreateBusTemplateUnits
 @default(template)
 nothing # hide

diff --git a/src/measurement/ammeter.jl b/src/measurement/ammeter.jl
@@ -1,8 +1,8 @@
 """
     addAmmeter!(system::PowerSystem, device::Measurement; label, from, to, magnitude,
-        variance, status, noise)
+        variance, noise, status)
 
-The function adds a new ammeter that measures branch current flow magnitude to the 
+The function adds a new ammeter that measures branch current magnitude to the 
 `Measurement` composite type within a given `PowerSystem` type. The ammeter can be added 
 to an already defined branch.
 
@@ -11,21 +11,22 @@ The ammeter is defined with the following keywords:
 * `label`: a unique label for the ammeter;
 * `from`: the label of the branch if the ammeter is located at the "from" bus end;
 * `to`: the label of the branch if the ammeter is located at the "to" bus end;
-* `magnitude` (pu or A): the branch current flow magnitude value;
-* `variance` (pu or A): the variance of the branch current flow magnitude measurement;
+* `magnitude` (pu or A): the branch current magnitude value;
+* `variance` (pu or A): the variance of the branch current magnitude measurement;
+* `noise`: specifies how to generate the measurement mean:
+  * `noise = true`: adds white Gaussian noise with the `variance` to the `magnitude`;
+  * `noise = false`: uses the `magnitude` value only.
 * `status`: the operating status of the ammeter:
   * `status = 1`: in-service;
   * `status = 0`: out-of-service;
-* `noise`: specifies how to generate the measurement mean:
-  * `noise = true`: Adds white Gaussian noise with the `variance` to the `magnitude`;
-  * `noise = false`: uses the `magnitude` value only.
+
 
 # Updates
 The function updates the `ammeter` field of the `Measurement` composite type.
 
 # Default Settings
-Default settings for certain keywords are as follows: `variance = 1e-2`, `status = 1`,
-`noise = true`, which apply to ammeters located at both the "from" and "to" bus ends.
+Default settings for certain keywords are as follows: `variance = 1e-2`, `noise = true`, 
+`status = 1`, which apply to ammeters located at both the "from" and "to" bus ends.
 Users can fine-tune these settings by explicitly specifying the variance and status for
 ammeters positioned on either the "from" or "to" bus ends of branches using the
 [`@ammeter`](@ref @ammeter) macro.
@@ -74,17 +75,19 @@ function addAmmeter!(system::PowerSystem, device::Measurement;
     location = checkLocation(ammeter, from, to)
 
     ammeter.number += 1
-    setLabel(ammeter, label, default.label, "ammeter")
+    labelBranch = getLabel(system.branch, location, "branch")
 
     index = system.branch.label[getLabel(system.branch, location, "branch")]
     push!(ammeter.layout.index, index)
 
     basePowerInv = 1 / (system.base.power.value * system.base.power.prefix)
     if ammeter.layout.from[end]
+        setLabel(ammeter, label, default.label, labelBranch; prefix = "From")
         defaultVariance = default.varianceFrom
         defaultStatus = default.statusFrom
         baseVoltage = system.base.voltage.value[system.branch.layout.from[index]] * system.base.voltage.prefix
     else
+        setLabel(ammeter, label, default.label, labelBranch; prefix = "to")
         defaultVariance = default.varianceTo
         defaultStatus = default.statusTo
         baseVoltage = system.base.voltage.value[system.branch.layout.to[index]] * system.base.voltage.prefix
@@ -101,8 +104,8 @@ end
 
 The function incorporates ammeters into the `Measurement` composite type for every branch
 within the `PowerSystem` type. These measurements are derived from the exact branch current
-flow magnitudes defined in the `AC` abstract type. These exact values are perturbed by 
-white Gaussian noise with the specified `variance` to obtain measurement data.
+magnitudes defined in the `AC` abstract type. These exact values are perturbed by white 
+Gaussian noise with the specified `variance` to obtain measurement data.
 
 # Keywords
 Users have the option to configure the following keywords:
@@ -196,9 +199,11 @@ function addAmmeter!(system::PowerSystem, device::Measurement, analysis::AC;
 
     count = 1
     basePowerInv = 1 / (system.base.power.value * system.base.power.prefix)
+    label = collect(keys(sort(system.branch.label; byvalue = true)))
     @inbounds for i = 1:2:ammeter.number
-        ammeter.label[replace(default.label, r"\?" => string(i))] = i
-        ammeter.label[replace(default.label, r"\?" => string(i + 1))] = i + 1
+        labelBranch = getLabel(system.branch, label[count], "branch")
+        setLabel(ammeter, missing, default.label, labelBranch; prefix = "From")
+        setLabel(ammeter, missing, default.label, labelBranch; prefix = "To")
 
         ammeter.layout.index[i] = count
         ammeter.layout.index[i + 1] = count
@@ -349,10 +354,10 @@ macro ammeter(kwargs...)
                 setfield!(template.ammeter, parameter, Bool(eval(kwarg.args[2])))
             elseif parameter == :label
                 label = string(kwarg.args[2])
-                if contains(label, "?")
+                if contains(label, "?") || contains(label, "!")
                     setfield!(template.ammeter, parameter, label)
                 else
-                    throw(ErrorException("The label template lacks the '?' symbol to indicate integer placement."))
+                    throw(ErrorException("The label template is missing the '?' or '!' symbols."))
                 end
             end
         else

diff --git a/src/measurement/load.jl b/src/measurement/load.jl
@@ -12,10 +12,10 @@ of existing ones.
 # Returns
 The `Measurement` composite type with the following fields:
 - `voltmeter`: bus voltage magnitude measurements;
-- `ammeter`: branch current flow magnitude measurements;
-- `wattmeter`: active power flow and injection measurements;
-- `varmeter`: reactive power flow and injection measurements;
-- `pmu`: bus voltage and branch current flow phasors measurements.
+- `ammeter`: branch current magnitude measurements;
+- `wattmeter`: active power injection and active power flow measurements;
+- `varmeter`: reactive power injection and reactive power flow measurements;
+- `pmu`: bus voltage and branch current phasors measurements.
 
 # Units
 JuliaGrid stores all data in per-units and radians format. 

diff --git a/src/measurement/pmu.jl b/src/measurement/pmu.jl
@@ -5,7 +5,7 @@
 The function adds a new PMU to the `Measurement` composite type within a given `PowerSystem`
 type. The PMU can be added to an already defined bus or branch. When defining the PMU, it
 is essential to provide the bus voltage magnitude and angle if the PMU is located at a bus 
-or the branch current flow magnitude and angle if the PMU is located at a branch.
+or the branch current magnitude and angle if the PMU is located at a branch.
 
 # Keywords
 The PMU is defined with the following keywords:
@@ -24,15 +24,15 @@ The PMU is defined with the following keywords:
   * `statusAngle = 1`: in-service;
   * `statusAngle = 0`: out-of-service;
 * `noise`: specifies how to generate the measurement means:
-  * `noise = true`: Adds white Gaussian noises with variances to the `magnitude` and `angle`;
+  * `noise = true`: adds white Gaussian noises with variances to the `magnitude` and `angle`;
   * `noise = false`: uses the `magnitude` and `angle` values only.
 
 # Updates
 The function updates the `pmu` field of the `Measurement` composite type.
 
 # Default Settings
 Default settings for certain keywords are as follows: `varianceMagnitude = 1e-5`,
-`statusMagnitude = 1`, `varianceAngle = 1e-5`,  `statusAngle = 1`, and `noise = true`,
+`statusMagnitude = 1`, `varianceAngle = 1e-5`, `statusAngle = 1`, and `noise = true`,
 which apply to PMUs located at the bus, as well as at both the "from" and "to" bus ends.
 Users can fine-tune these settings by explicitly specifying the variance and status for
 PMUs positioned at the buses, "from" bus ends, or "to" bus ends of branches using the
@@ -82,13 +82,13 @@ function addPmu!(system::PowerSystem, device::Measurement;
     pmu = device.pmu
     default = template.pmu
 
-    location = checkLocation(pmu, bus, from, to)
-
     pmu.number += 1
-    setLabel(pmu, label, default.label, "PMU")
+    location = checkLocation(pmu, bus, from, to)
 
     if pmu.layout.bus[end]
-        index = system.bus.label[getLabel(system.bus, location, "bus")]
+        labelBus = getLabel(system.bus, location, "bus")
+        index = system.bus.label[labelBus]
+        setLabel(pmu, label, default.label, labelBus)
 
         defaultVarianceMagnitude = default.varianceMagnitudeBus
         defaultVarianceAngle = default.varianceAngleBus
@@ -99,15 +99,18 @@ function addPmu!(system::PowerSystem, device::Measurement;
         prefixAngle = prefix.voltageAngle
         baseInv = 1 / (system.base.voltage.value[index] * system.base.voltage.prefix)
     else
-        index = system.branch.label[getLabel(system.branch, location, "branch")]
+        labelBranch = getLabel(system.branch, location, "branch")
+        index = system.branch.label[labelBranch]
         if pmu.layout.from[end]
+            setLabel(pmu, label, default.label, labelBranch; prefix = "From")
             defaultVarianceMagnitude = default.varianceMagnitudeFrom
             defaultVarianceAngle = default.varianceAngleFrom
             defaultMagnitudeStatus = default.statusMagnitudeFrom
             defaultAngleStatus = default.statusAngleFrom
 
             baseVoltage = system.base.voltage.value[system.branch.layout.from[index]] * system.base.voltage.prefix
         else
+            setLabel(pmu, label, default.label, labelBranch; prefix = "To")
             defaultVarianceMagnitude = default.varianceMagnitudeTo
             defaultVarianceAngle = default.varianceAngleTo
             defaultMagnitudeStatus = default.statusMagnitudeTo
@@ -266,8 +269,10 @@ function addPmu!(system::PowerSystem, device::Measurement, analysis::AC;
     pmu.angle.status = similar(pmu.magnitude.status)
 
     prefixInv = 1 / system.base.voltage.prefix
+    label = collect(keys(sort(system.bus.label; byvalue = true)))
     @inbounds for i = 1:system.bus.number
-        pmu.label[replace(default.label, r"\?" => string(i))] = i
+        labelBus = getLabel(system.bus, label[i], "bus")
+        setLabel(pmu, missing, default.label, labelBus)
 
         pmu.layout.index[i] = i
         pmu.layout.bus[i] = true
@@ -283,9 +288,11 @@ function addPmu!(system::PowerSystem, device::Measurement, analysis::AC;
 
     count = 1
     basePowerInv = 1 / (system.base.power.value * system.base.power.prefix)
+    label = collect(keys(sort(system.branch.label; byvalue = true)))
     @inbounds for i = (system.bus.number + 1):2:pmu.number
-        pmu.label[replace(default.label, r"\?" => string(i))] = i
-        pmu.label[replace(default.label, r"\?" => string(i + 1))] = i + 1
+        labelBranch = getLabel(system.branch, label[count], "branch")
+        setLabel(pmu, missing, default.label, labelBranch; prefix = "From")
+        setLabel(pmu, missing, default.label, labelBranch; prefix = "To")
 
         pmu.layout.index[i] = count
         pmu.layout.index[i + 1] = count
@@ -477,10 +484,10 @@ macro pmu(kwargs...)
                     setfield!(template.pmu, parameter, Bool(eval(kwarg.args[2])))
                 elseif parameter == :label
                     label = string(kwarg.args[2])
-                    if contains(label, "?")
+                    if contains(label, "?") || contains(label, "!")
                         setfield!(template.pmu, parameter, label)
                     else
-                        throw(ErrorException("The label template lacks the '?' symbol to indicate integer placement."))
+                        throw(ErrorException("The label template is missing the '?' or '!' symbols."))
                     end
                 end
             end